Skip to content

feat(cli): align the CLI with the cli-contract spec (F1) - #20

Merged
edspencer merged 1 commit into
mainfrom
cli-contract
Nov 5, 2026
Merged

edspencer merged 1 commit into
mainfrom
cli-contract

Conversation

@edspencer

Copy link
Copy Markdown
Owner

Wave F1 of the CLI-contract rollout (edspencer/cli-contract SPEC 0.2): Paddock's alignment, ported. Managers' CLI is Paddock's nearly line for line, so this is Paddock's own change applied by a three-way merge (Paddock before → Paddock after, with the Paddock→Managers renames applied to both sides, onto Managers) rather than rewritten:

Conflicts were all Managers-only lines sitting next to Paddock's (the M14.5 /api/security route beside the new health route, start.ts's env scrub / MCP sequestering / loopbackNoAuth, Managers' own README), resolved by keeping both.

What a user or script sees (minor changeset, which names each exit-code change):

  • /api/health → { ok, version }, one version shared with the OpenAPI document and the management MCP handshake.
  • managers serve, with start a permanent alias. Server logs go to stderr, so serve's first stdout line is Managers <version>: <url>.
  • Usage errors exit 2 with the usage after the message. service status exits 0 / 3 / 4; logs, start, stop, restart exit 4 with no unit; an install that never answers exits 1.
  • service status --json (matches the contract's service-status.schema.json), service logs [-f] [-n].
  • Linux service logs go to <data-dir>/logs/service.log (rotated by copy-and-truncate at 8 MB, three generations), not the journal.
  • Units: realpath'd Node, rebuilt PATH, quoted ExecStart, a linger check, warnings for a vanished Node / version gap.
  • launchd: wait for a bootout to finish, retry a bootstrap returning 5 or 37. systemd: install restarts a unit that was already active.

CI: two new jobs from Paddock — CLI conformance (@edspencer/cli-conformance ^0.2.0 against the packed dist-npm) and Service (real launchd / real systemd) (scripts/service-real.mjs). cli-contract.json pins a throwaway data dir, batch drive mode (with MANAGERS_ALLOW_BATCH_DRIVE=1), and nulls HOST, PORT, NODE_ENV and the Claude credentials.

Testing

  • Server tests: 3052 passed, 0 failed. Typecheck clean. check:nul clean.
  • Conformance runner, locally against the packed tarball on a fresh home: 7 passed, 2 skipped (busy/busy-json, which F2 turns on).
  • Installed the packed tarball into a throwaway prefix and HOME: --version bare; service status and service logs with no unit → 4; service bogus, serve --nope, logs → 2 with the usage. Scoped flags (e.g. -f on status) arrive with F2/F3's flag table.
  • Real launchd and systemd can't run on the dev box (a container with no systemd), so the new Service jobs here are the proof.

No UI change.

🤖 Generated with Claude Code

Ported from Paddock, whose CLI this is, by three-way merging Paddock's own
changes onto Managers: B1 (paddock#981, #983), the launchd bootout/bootstrap
race fix (paddock#984) and the systemd restart-an-active-unit fix (paddock#986).

- /api/health answers { ok, version } (version.ts, shared with the OpenAPI
  document and the management MCP handshake).
- `serve`, with `start` a permanent alias; the server logs to stderr so the
  first stdout line is `Managers <version>: <url>`.
- Exit codes: usage errors 2 with the usage after; `service status` 0/3/4;
  logs/start/stop/restart 4 with no unit; an install that never answers 1.
- `service status --json`, `service logs [-f] [-n]`; Linux logs go to
  <data>/logs/service.log, rotated by copy-and-truncate.
- Units: realpath'd Node, a rebuilt PATH, quoted ExecStart, a linger check.
- launchd: poll until a bootout has finished, retry bootstrap on 5/37.
- systemd: install restarts a unit that was already active.
- Real-service CI (scripts/service-real.mjs) and the conformance runner
  (@edspencer/cli-conformance ^0.2.0): 7 passed, 2 skipped (busy, F2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@edspencer
edspencer merged commit a19f89b into main Nov 5, 2026
7 checks passed
@edspencer
edspencer deleted the cli-contract branch November 5, 2026 08:27
@github-actions github-actions Bot mentioned this pull request Nov 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant