feat(resources): tracebloc resources — show this machine's allowance (SHOW; set deferred) (#143)

[LukasWodka]

What

Refs #143. Ships the tracebloc resources command — "one knob for how much of this machine tracebloc may use" (design approved 2026-07-06) — SHOW only. SET and the macOS VM-raise are deferred on a real groundwork gap (below).

Built — tracebloc resources (SHOW / P1)

Bare tracebloc resources shows the machine's capacity + the per-training-run allowance in the user's language (cores + GiB, no Kubernetes vocabulary). New pure internal/resources package: MachineCapacity (sums Ready-node allocatable + GPU), ParseTraining (reads RESOURCE_LIMITS→RESOURCE_REQUESTS→chart default cpu=2/mem=8Gi, per client#308), user-language formatters, and a release-scoped jobs-manager env reader (mirrors doctor's attribution rule so another release's jobs-manager can't satisfy the read). --verbose adds namespace/client/raw-env/GPU; --plain honored; wired top-level + into the home screen. Cluster-free tests via the fake clientset; internal/resources at 96.7%.

Deferred — resources set + macOS VM raise (P2/P3)

resources set --cpu … --memory … and resources set max parse cleanly and return an honest "not supported in this build yet" (exit 1) — not a flag error. SET is deferred on a real groundwork gap: persisting a change needs helm upgrade with the chart reference, which the CLI can't safely reconstruct (the installer's repo-alias/chart-ref isn't recoverable from helm list), and blindly mutating a live training cluster with reconstructed args is unsafe. The unblock is installer-side — the installer must record the chart ref where the CLI can read it. Worth its own follow-up ticket.

Tests / gates

make ci green (vet + -race tests + errcheck/ineffassign/misspell + gofmt -s + schema-check); coverage-floor.sh ok (cli 74.6% ≥ 68%, submit 76.1% ≥ 72%).

Open questions (for when P2 lands)

• SHOW displays the real stored per-run ceiling today; when SET lands, decide whether the headline becomes the allowance (training + platform overhead) for round-trip consistency with set, and whether overhead is a fixed constant or computed from chart requests.
• Multi-node: SHOW sums allocatable across Ready nodes (the installer path is single-node).

Refs #143 (not Closes — P2/P3 outstanding).

🤖 Generated with Claude Code

---

Note

Low Risk
Read-only cluster inspection and user-facing formatting; set is explicitly non-mutating. Risk is mainly misreporting capacity/ceiling if attribution or parsing diverges from doctor—mitigated by mirrored rules and tests.

Overview
Adds a top-leveltracebloc resources command (cli#143) that read-only shows machine schedulable capacity vs the per-training-run ceiling, in plain CPU/GiB language without Kubernetes jargon.

SHOW (P1): Resolves the cluster like other data commands, sums Ready node allocatable (GPUs included), and reads the training ceiling from the release-scoped jobs-manager env (RESOURCE_LIMITS → requests → chart default), aligned with cluster doctor. --verbose exposes namespace/client/raw env; node list failures still show the ceiling with a clear capacity-unavailable line.

New internal/resources: Pure helpers (MachineCapacity, ParseTraining, formatters) plus JobsManagerEnv with the same deployment attribution rules as doctor (no cross-release reads; ambiguous multi-release → empty).

resources set (deferred P2): Subcommand and flags (--cpu, --memory, max) parse the approved shapes but exit 1 with an honest “not supported yet” message—no cluster mutation.

Root command tree and bare tracebloc home screen list the new command; CLI and package tests cover rendering, routing, exit codes, and deferral parsing.

^{Reviewed by Cursor Bugbot for commit 899b0d7. Bugbot is set up for automated code reviews on this repo. Configure here.}

[aptracebloc]

Approving. Clean, read-only, well-tested (96.7% on the pure internal/resources), and the resources set deferral is done right — it parses the approved shape (--cpu/--memory/set max, ValidArgs rejecting set bogus) and returns an honest exit-1 "not built yet" instead of a cobra flag error or a silent no-op, and it refuses to blindly helm upgrade a live training cluster with a chart ref it can't safely reconstruct. Good judgment. One non-blocking iteration note.

Non-blocking — shared logic worth extracting (suggest a follow-up)

internal/resources hand-copies a fair bit of internal/doctor: the chart-env parsers (parseResourceSpec, parseCPUMem, parseGPU, nodeReady) and the jobsManagerDeployment release-attribution rule. I see the in-code justification — keeping resources a pure leaf that doesn't import the cli command package — and that's a fair reason not to reach into doctor.

But this PR's own grounding ("a reader must mirror the writer", di#358) now applies twice over: there are two independent readers (doctor + resources) that must also stay mirrored to each other by hand, so a future change to the chart env format or the attribution rule has to land in both copies or they silently drift. The clean fix is to lift those helpers into internal/cluster — which both packages already import — rather than maintain two hand-synced copies. Could you open a follow-up issue for that extraction?

Two small things that'd fold into the same extraction:

• parseGPU ranges a map and returns the first match — nondeterministic if GPU_LIMITS ever carries more than one entry (same note as on #91). Fine for single-entry today.
• FormatGPU(name, q) never references name — the vendor prefix is "dropped" by simply not using it; either use it or drop the param.

None of this blocks — approving as-is; the extraction is a worthwhile iteration, not a fix.

— drafted with Claude (Opus 4.8), sent by @aptracebloc