Skip to content

feat(cli): service install --dry-run/--from-checkout, port refusal, --json on service actions, serve --quiet (CLI contract SPEC §1, §3) - #24

Merged
edspencer merged 2 commits into
mainfrom
cli-contract-shoulds
Nov 5, 2026
Merged

edspencer merged 2 commits into
mainfrom
cli-contract-shoulds

Conversation

@edspencer

Copy link
Copy Markdown
Owner

CLI contract SPEC 1.0, §1 and §3: the service install musts Managers was missing, and the shoulds that came with them. Ported from Paddock #996 (0e2b624) by applying Paddock's own diff to Managers' near-identical packages/server/src/cli/, then renaming.

What's in it

  • service install refuses a checkout (or an npm link), exit 1, unless you give --from-checkout. A checkout is a package root not under any node_modules (underNodeModules, which update already uses). The npx refusal and --help used to suggest npm link -w packages/server && managers service install, which this refusal now catches, so they say npm i -g @edspencer/managers instead.
  • service install refuses a port something else holds, exit 1, instead of writing a unit that crash-loops. A Managers on the port is fine (a reinstall), and so is the unit's own running service.
    • identifyManagers (in service/ready.ts) tells Managers apart by /api/busy's counts.run, which only Managers has. That means a Paddock on the port counts as something else.
  • A plain reinstall keeps the unit's port, host, data dir and verbosity unless a flag says otherwise. It used to fall back to 7234 unless you gave --refresh.
  • service install --dry-run prints the unit on stdout, says where it would go on stderr, and writes nothing, not even folders. It also works with --refresh and --json.
  • --json on install, uninstall, start, stop, restart: one document, { ok, action, error?, …status }, and all prose on stderr. Exit codes don't change.
  • serve --quiet / -q prints only Managers <version>: <url>.
  • These flags exit 2 where they don't apply: --dry-run, --from-checkout, --quiet, and --json on serve, service logs and config eject.
  • scripts/service-real.mjs gains Paddock's steps: dry-run, install --json, doctor --offline --json, and a flagless reinstall that keeps the port and replaces the process.
  • test/unit/cli-service-shoulds.test.ts is ported, plus two identifyManagers tests (Managers vs. Paddock).
  • Docs: --help (both usages), README.md, NPM-README.md and UPDATING.md.
  • The changeset is a minor, because scripts may depend on the new refusals (exit 1) and on a reinstall keeping its settings.

Left out on purpose:

Testing

  • npm run typecheck passes. vitest passes: unit 2681/2681, integration 556/556.
  • Real-use QA used the packed tarball, installed into a throwaway prefix with a throwaway HOME. The rig had batch drive mode with the opt-in, no Claude/API tokens, and no HOST/PORT/NODE_ENV (checked in /proc/<pid>/environ). Service runs went through the repo's stand-in systemctl (scripts/standin-systemctl.mjs), because this box has no systemd. Results are in the comment below.

UI unaffected: CLI only.

🤖 Generated with Claude Code

…-json on service actions, serve --quiet (CLI contract SPEC §1, §3)

Ported from paddock#996 (0e2b624). A reinstall keeps the unit's port, host
and data dir; identifyManagers tells Managers from Paddock by /api/busy's
counts.run; the npx refusal suggests npm i -g rather than npm link.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@edspencer

Copy link
Copy Markdown
Owner Author

Real-use QA (packed tarball, throwaway prefix and HOME, the stand-in systemctl)

All of this ran on npm run pack:npm → npm pack → npm i -g --prefix <tmp>. The tarball was grepped to confirm it carries from-checkout. The rig had a throwaway HOME/XDG_CONFIG_HOME, MANAGERS_DRIVE_MODE=batch with MANAGERS_ALLOW_BATCH_DRIVE=1, no Claude/API tokens, and no HOST/PORT/NODE_ENV, all checked in the service's /proc/<pid>/environ.

What Result
service install --dry-run --port P exit 0; the unit on stdout, Nothing was written on stderr; no ~/.config, no ~/.managers afterwards
… --dry-run --json one document { ok, action, dryRun, unit, contents }; still nothing written
install from the worktree's own dist/cli/managers.js (a checkout) exit 1, the refusal names the checkout, npm i -g @edspencer/managers and --from-checkout; --dry-run refused too
--from-checkout --dry-run from the checkout exit 0; ExecStart runs the checkout
a fake Paddock on the port (/api/health ok, /api/busy without counts.run) exit 1, port P is held by something that isn't Managers; with --json, ok:false and that error; nothing written
a raw TCP listener on the port exit 1, same refusal
service install --port P --json exit 0; ok, installed, running, answering: true, port: P, runningVersion: 0.4.0; prose on stderr
service install --json with no flags exit 0; Keeping: managers serve --port P; the unit still says --port P; a new pid
service stop/start/restart --json each exit 0, one document; running is false after stop and true after start and restart
service uninstall --json, then stop --json 0 with installed:false; then exit 4 with error: "not installed"
serve -q under pm stdout is exactly Managers 0.4.0: http://127.0.0.1:5202; /api/health answers
service start --dry-run, update --dry-run, service status --from-checkout, serve --from-checkout, busy --quiet, service install -q, service logs --json, serve --json, config eject --json each exits 2 with <flag> applies to … only

Conformance (local): npx cli-conformance --dir dist-npm --config cli-contract.json: 17 passed, 0 failed, 3 skipped. The skips are update-not-writable (this box runs as root) and the real-service pair, which CI runs.

@edspencer
edspencer merged commit db06a62 into main Nov 5, 2026
9 checks passed
@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