Skip to content

feat(cli): managers update, doctor, service install --refresh, MANAGERS_IN_DOCKER (F3) - #22

Merged
edspencer merged 11 commits into
mainfrom
cli-contract-update
Nov 5, 2026
Merged

edspencer merged 11 commits into
mainfrom
cli-contract-update

Conversation

@edspencer

Copy link
Copy Markdown
Owner

Wave F3 of the CLI-contract rollout (SPEC 0.2), ported from Paddock 0.82 (paddock#986, #989, #991) and the contract's reference/.

What's in it

  • managers update [--check] [--to <version|tag>] [--yes] [--force] [--json], with upgrade as a hidden alias. This is SPEC §5's sequence in order: lock, install detection, registry, busy check, prompt, fetch, stop, install, hand-over via service install --refresh, health check on the target version, and rollback (exit 6 or 7). The generic code is the reference copied in (cli/update/*, with headers). Managers' own hooks are in cli/update-command.ts: the synthesized @edspencer/managers package layout, the busy guard with the keeper-chat trap, and the service.
  • MANAGERS_UPDATE_HINT is honoured: a managed install prints it and exits 5.
  • managers doctor [--json] [--offline] runs SPEC §1's eight checks, then config (the configuration loads) and security. security folds in /api/security's posture warnings: it asks the running instance, or computes the posture this shell would boot with, using the server's own rule.
  • service install --refresh. status --json carries update (absent, never null). start/restart run reset-failed first.
  • cli/service/{launchd,systemd,manager,path-env,logs}.ts are the reference copies, including cli-contract#7: a refused first install leaves no unit behind.
  • Image: MANAGERS_IN_DOCKER=1, and managers on PATH as a shim, so docker exec … managers busy works as a Watchtower pre-update hook.
  • UPDATING.md is new, with a pointer from the README. Managers has no docs site.
  • Conformance: all eleven update checks are on. update-service and update-rollback run in the real launchd/systemd jobs with CI_REAL_SERVICE=1. HOST/PORT are nulled in the config's env.
  • CI: a new Update (fake registry) job on ubuntu and macOS (scripts/update-registry.mjs, fake-registry.mjs and standin-systemctl.mjs, ported from Paddock). It is the non-root job, so the non-writable-prefix case runs there.

The changeset is a minor (new commands, and new exit codes 5/6/7 on update).

Testing

  • 3184 server tests and the typecheck pass locally, plus the ported chore: version packages #7 tests.
  • Locally, the conformance runner passed 17 checks with 3 skipped: update-not-writable because this box runs as root, and the two real-service checks, which run in CI.
  • Real-use QA is in the comments.

UI unaffected: CLI and image only.

🤖 Generated with Claude Code

HomeLab Agent and others added 11 commits November 5, 2026 03:19
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>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…a SIGTERM that finishes or records (F2)

Ported from Paddock's C1 (paddock#984) by three-way merge, plus Managers' own:

- /api/busy gains `run`: trigger runs in flight (ManagersState.liveRuns), from
  the running record being written until it is finished and committed.
- SIGTERM waits up to 8s for in-flight turns and runs to end by themselves,
  then finishes each run still in flight as failed, "interrupted by shutdown",
  through its own (now once-only) completion hook. Bounded at 15s overall.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
# Conflicts:
#	.github/workflows/ci.yml
#	README.md
#	cli-contract.json
#	packages/server/src/cli/args.ts
#	packages/server/src/cli/managers.ts
#	packages/server/src/cli/service/index.ts
#	packages/server/src/routes/meta.ts
#	packages/server/src/start.ts
#	packages/server/test/unit/cli-contract.test.ts
#	scripts/service-real.mjs
…#991)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A supervisor whose kill timeout is shorter than the 8 s wait (PM2's is 1.6 s)
otherwise left no record at all of what it cut short.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
# Conflicts:
#	README.md
#	packages/server/src/cli/args.ts
#	packages/server/src/cli/busy-command.ts
#	packages/server/src/cli/busy.ts
#	packages/server/src/cli/managers.ts
#	packages/server/src/cli/output.ts
#	packages/server/src/shutdown-drain.ts
#	packages/server/src/start.ts
#	packages/server/test/unit/cli-contract.test.ts
#	packages/server/test/unit/shutdown-drain.test.ts
The auto-merge of main (F2's squash, identical to this branch's F2 content)
added busyCheck() and the restart guard a second time.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…y a refused first install)

Also restores the reference's own wording in those two files (a blanket
rename had made Paddock's 0.80.0 launchd race read as Managers').

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nit description is Managers', not Paddock's

The stand-in systemctl hands the rig's env to the service, and Managers refuses
MANAGERS_DRIVE_MODE=batch at boot without the opt-in, so the service never
answered and the service-backed scenarios failed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@edspencer
edspencer merged commit 0b24695 into main Nov 5, 2026
9 checks passed
@edspencer
edspencer deleted the cli-contract-update branch November 5, 2026 09:31
@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