Skip to content

--json on service install, uninstall, start, stop and restart - #87

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

edspencer merged 2 commits into
mainfrom
g-json

Conversation

@edspencer

Copy link
Copy Markdown
Owner

Summary

cli-contract SPEC §1 says --json should be on the other service commands too. Until now only service status took it, and install, uninstall, start, stop and restart refused it with exit 2. Now they take it (minor).

  • The shape is Hallway's (hallway service … --json, server/commands/services.ts), so the tools agree: { ok, action, error?, …what the command found, …every field of service status --json as it is afterwards }.
    • error is busy on 75, not installed on 4, and otherwise the reason (exit 1).
    • What each command adds:
      • install: dryRun (and with it definition, the file it would write), refreshed and changed;
      • start and stop: wasRunning;
      • restart: rewritten;
      • uninstall: wasInstalled.
  • One document on stdout, prose on stderr, and the exit code is unchanged. withJson in server/service/index.ts gives the command a context whose out is stderr, and then prints the document. A refusal that's thrown (npx's cache, a checkout, the port in use) still gets its document, with the reason, and is then rethrown, so it's still printed and still exits 1.
  • service logs --json stays a usage error (exit 2), and so does logs --force. The two scoped-flag tests that asserted stop --json and install --json were refused now assert those instead.
  • Docs:
    • the --help synopsis and per-command options;
    • the CLI reference's --help block, regenerated;
    • its service synopsis;
    • a new "which command takes which option" table;
    • a --json section with the fields.

Testing

  • npm test: 509 passed, 0 failed, 3 skipped (main merged in). npm run typecheck is clean. npm run smoke:pack is ok. The docs site builds, and check-links reports 3267 internal links OK.

  • New unit tests (test/service.test.ts), each asserting exactly one document on stdout:

    • install, with the prose on stderr;
    • --dry-run carries the definition and writes nothing;
    • stop, start, restart and uninstall each carry their own field;
    • not installed gives 4 and not installed (start, stop, restart);
    • busy gives 75, busy and the counts;
    • a restart that doesn't answer gives 1 and the reason;
    • a thrown npx refusal still gets its document, then rejects.
  • Real use: the packed tarball, in a throwaway prefix and HOME. A stand-in systemctl really runs the unit's ExecStart, because there's no systemd here. Every case below printed exactly one JSON document on stdout:

    Command Exit JSON
    start --json, nothing installed 4 not installed
    install --dry-run --json 0 dryRun: true, the unit on stderr
    install --port 5998 --json 0 changed: true, answering: true, runningVersion 0.16.0
    the same again 0 changed: false
    stop --json 0 wasRunning: true
    stop --json again 0 wasRunning: false
    start --json 0 —
    restart --json 0 rewritten: false
    stop --json during a real in-flight POST /api/examples 75 error: "busy", busy.counts.save: 1
    start --json with a foreground serve holding the port 1 the port-in-use reason
    uninstall --json 0 wasInstalled: true
    uninstall --json again 0 wasInstalled: false
    logs --json 2 — (usage error)

    The control, uninstall without --json, still prints its prose on stdout.

Checklist

  • User-facing change? It has a changeset (minor; it says scripts used to get exit 2 here).
  • UI change? No.
  • Doesn't weaken the read-only, never-delete or localhost-only guarantees.

🤖 Generated with Claude Code

HomeLab Agent and others added 2 commits November 5, 2026 03:16
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
# Conflicts:
#	test/service.test.ts
@cloudflare-workers-and-pages

Copy link
Copy Markdown

Deploying local-review with  Cloudflare Pages  Cloudflare Pages

Latest commit: 7998e9e
Status: ✅  Deploy successful!
Preview URL: https://756c503c.local-review-dpz.pages.dev
Branch Preview URL: https://g-json.local-review-dpz.pages.dev

View logs

@edspencer
edspencer merged commit 50372f8 into main Nov 5, 2026
10 checks passed
@edspencer
edspencer deleted the g-json branch November 5, 2026 08:36
@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