Skip to content

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

Merged
edspencer merged 6 commits into
mainfrom
g-shoulds-2
Nov 5, 2026
Merged

edspencer merged 6 commits into
mainfrom
g-shoulds-2

Conversation

@edspencer

Copy link
Copy Markdown
Owner

The CLI contract's remaining service/serve shoulds (SPEC §1, §3), plus two musts found on the way

What landed

  • service install --dry-run: the systemd unit / launchd plist on stdout, where it would go on stderr, nothing written (no unit, no folder, no systemctl/launchctl call). Works with --refresh and --json ({ ok, action, dryRun, unit, contents }).
  • Checkout refusal (exit 1) unless --from-checkout: a package root not under any node_modules (SPEC §6's checkout / npm link row).
  • Port refusal (exit 1) when something that isn't Paddock holds the port (SPEC §1 must, wasn't implemented). Paddock is told apart by /api/busy's counts; the unit's own running service on that port is also accepted, so a pre-0.81 service can still be reinstalled over. isListening/identifyPaddock moved to service/ready.ts; doctor's port check uses the same code.
  • A plain reinstall keeps the unit's port/host/data dir/verbosity unless a flag says otherwise (SPEC §1 must). Before, only --refresh did, so service install over a --port 9000 service moved it to 7233.
  • --json on install/uninstall/start/stop/restart: one document on stdout, { ok, action, error?, ...status afterwards } (Hallway's shape; the fields after action are status --json's), all prose on stderr, exit codes unchanged (error: "busy" on 75, "not installed" on 4; a thrown failure prints its document and then paddock: … as before).
  • serve --quiet / -q: only Paddock <version>: <url> (and no first-run note).
  • Scoped flags: --dry-run, --from-checkout (service install), --quiet (serve), and --json now exit 2 on serve, service logs, config eject (they were accepted and ignored). logs --json has no sensible document, so it's rejected.
  • Reference re-sync: cli/service/systemd.ts and launchd.ts to cli-contract d5ddc0e (a refused first install removes its unit; headers stay @ 0.2). src/runtime-file.ts is now the reference @ 0.2 verbatim with the standard header (local changes: none) — it only differed in quote style.
  • --help updated. Changeset: minor (names every exit-code change).
  • scripts/service-real.mjs gains: install --dry-run (unit on stdout, nothing written), install --json (the document), doctor --offline --json against the real service, and a flagless reinstall that keeps the port and replaces the pid.
  • Conformance config: no change needed (no new runner checks; serviceInstall runs from a global install).

Testing

  • test/unit/cli-service-shoulds.test.ts (49): every scoped flag accepted/refused, dry-run on both platforms incl. --refresh (mtime unchanged) and --json, checkout refusal (+ --dry-run, --from-checkout, control), port refusal and its two exceptions, reinstall keeps settings (+ control), --json on each action incl. 4/75/thrown failures, first-install cleanup on systemd and launchd (+ reinstall control).
  • Server suite: 2720 passed with the box's env scrub; typecheck clean.

Real-use QA (packed tarball, throwaway HOME/prefix/cache, batch, no credentials, the repo's stand-in systemctl)

  • install --dry-run → unit on stdout, note on stderr, home tree byte-identical before/after; --dry-run --json parses.
  • the checkout's own CLI → refused (1), --json still one document, --from-checkout --dry-run prints a unit naming the checkout; nothing written.
  • python3 -m http.server on the port → install refused (1), nothing written; reinstall over a running Paddock on the same port → 0.
  • install/stop/start/restart/uninstall --json → one document each with the right running/installed, prose on stderr; start --json with nothing installed → 4, error: "not installed".
  • logs --json, serve --json, config eject --json, status --dry-run, busy -q, start --from-checkout, update --quiet → 2.
  • serve -q on a genuinely first run → exactly one stdout line; control without -q → 6 lines and the welcome on stderr.
  • Not exercised for real: a 75 under --json (unit-tested; the busy guard itself is unchanged).

For the record (asked by the rollout)

  • systemd service install over an already-active unit does restart it (wasActive → systemctl --user restart).
  • service start (and restart) do run reset-failed first.

🤖 Generated with Claude Code

HomeLab Agent and others added 6 commits November 5, 2026 03:24
The contract's eight checks with the shared ids, then Paddock's own (config,
projects, claude-login, claude-cli). ✓/!/✗/- lines with a fix: under every
warning and failure, exit 1 on a failure, --json matching
schemas/doctor.schema.json, the update notice on stderr. --offline is scoped
to doctor. The update check writes update-check.json only into a data dir
that already exists, so doctor never creates an instance.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… --json on the service actions, serve --quiet; re-sync service/ and runtime-file with the reference (WIP)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d doctor steps

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…herwise (SPEC §1)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@cloudflare-workers-and-pages

Copy link
Copy Markdown

Deploying paddock with  Cloudflare Pages  Cloudflare Pages

Latest commit: b203003
Status: ✅  Deploy successful!
Preview URL: https://ac16d9f4.paddock-7u2.pages.dev
Branch Preview URL: https://g-shoulds-2.paddock-7u2.pages.dev

View logs

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