@edspencer/paddock 0.82.0 → 0.83.0

package/packages/server/dist/cli/exit-codes.js

@@ -1,48 +1,45 @@
-/**
- * The CLI contract's exit codes (SPEC §2), as constants.
- *
- * From edspencer/cli-contract SPEC.md §2 @ 0.1. Written here rather than copied
- * from `reference/exit-codes.ts` because the reference module did not exist yet
- * when Paddock aligned; wave C4 re-syncs this file to it and adds the usual
- * provenance header. The numbers, and what each means, are the contract.
- *
- * | 0 | done; running and answering; up to date; not busy
- * | 1 | failed
- * | 2 | usage: an unknown command or flag, a bad value
- * | 3 | not running: installed but not running or not answering
- * | 4 | not installed: there is no service unit
- * | 5 | this install cannot update itself          (`update`, not yet built)
- * | 6 | the update failed and was rolled back      (`update`, not yet built)
- * | 7 | the update failed and could not be rolled back
- * | 75 | busy: refused, and why was printed        (`busy`, not yet built)
- *
- * Codes 3 and 4 are what `systemctl status` and LSB init scripts use for "not
- * running" and "no such service", so a script that already branches on them
- * keeps working. 75 is `EX_TEMPFAIL` from `sysexits.h`, which is also the code
- * that makes Watchtower's pre-update hook skip an update.
- *
- * The three `update` codes are declared now and unused until wave C2. They are
- * here because the contract's whole point is that the numbers mean the same
- * thing in every tool: adding them later, from a different file, is how two
- * tools end up disagreeing about what 5 means.
- */
+// From edspencer/cli-contract reference/exit-codes.ts @ 0.2; local changes: none.
+// The exit codes every tool shares (SPEC §2). Copy this file; don't renumber it.
+//
+// Set `process.exitCode`, never call `process.exit()`, so piped output isn't cut short.
 export const EXIT = {
-    /** Done. Running and answering. Up to date. Not busy. */
-    ok: 0,
-    /** Failed — the catch-all. */
-    failure: 1,
-    /** Usage: an unknown command or flag, or a bad value. Usage follows the message. */
-    usage: 2,
-    /** Not running: installed, but not running or not answering. */
-    notRunning: 3,
-    /** Not installed: there is no service unit. */
-    notInstalled: 4,
-    /** This install cannot update itself; the right command was printed. */
-    cannotSelfUpdate: 5,
+    /** Done; running and answering; up to date; not busy. */
+    OK: 0,
+    /** Failed. */
+    FAILED: 1,
+    /** Usage: an unknown command or flag, a bad value. The usage is printed after the message. */
+    USAGE: 2,
+    /** Not running: installed but not running or not answering, or no instance answers. */
+    NOT_RUNNING: 3,
+    /** Not installed: there's no service unit. */
+    NOT_INSTALLED: 4,
+    /** This install can't update itself; the right command was printed. */
+    CANNOT_UPDATE: 5,
     /** The update failed and was rolled back; the old version is running again. */
-    rolledBack: 6,
-    /** The update failed and could not be rolled back; a person is needed. */
-    needsHuman: 7,
-    /** Busy: refused, and why was printed. Try later, or use `--force`. */
-    busy: 75,
+    ROLLED_BACK: 6,
+    /** The update failed and couldn't be rolled back; a person is needed. */
+    ROLLBACK_FAILED: 7,
+    /** Busy: refused, and why was printed. Try later, or use `--force`. `EX_TEMPFAIL` from sysexits.h. */
+    BUSY: 75,
 };
+/** A tool may use 8 to 63 for its own commands (SPEC §2). */
+export function isToolOwnCode(code) {
+    return Number.isInteger(code) && code >= 8 && code <= 63;
+}
+/** The SPEC's name for a shared code, for messages ("expected 4 (not installed), got 0 (ok)"). */
+export function describeExitCode(code) {
+    if (code === null)
+        return 'no exit code (killed by a signal)';
+    const names = {
+        0: 'ok',
+        1: 'failed',
+        2: 'usage',
+        3: 'not running',
+        4: 'not installed',
+        5: "can't update itself",
+        6: 'rolled back',
+        7: "couldn't roll back",
+        75: 'busy',
+    };
+    return names[code] ? `${code} (${names[code]})` : String(code);
+}

package/packages/server/dist/cli/output.js

@@ -1,8 +1,7 @@
-// From edspencer/cli-contract reference/output.ts @ SPEC 0.1; local changes: `./exit-codes.ts` → `./exit-codes.js`
-// (Paddock compiles to ESM-with-extensions, not a TS runtime); `EXIT.FAILED`/`EXIT.USAGE` → Paddock's lowercase
-// `EXIT.failure`/`EXIT.usage`, because Paddock's own `exit-codes.ts` predates the reference module and wave C4
-// re-syncs that file; and the reference's `UsageError` / `reportUsageError` are NOT copied, because `cli/args.ts`
-// already has a `UsageError` (a `CliError` subclass carrying its own code) that the entrypoint already reports.
+// From edspencer/cli-contract reference/output.ts @ 0.2; local changes: `./exit-codes.ts` → `./exit-codes.js`
+// (Paddock compiles to ESM-with-extensions, not a TS runtime); and the reference's `UsageError` / `reportUsageError`
+// are NOT copied, because `cli/args.ts` already has a `UsageError` (a `CliError` subclass carrying its own code) that
+// the entrypoint already reports.
 //
 // A CLI's output, the way SPEC §2 and §3 say: errors as `<tool>: <message>` on stderr, colour only on a TTY (honouring
 // NO_COLOR and FORCE_COLOR), and with `--json`, one JSON document on stdout and every word of prose on stderr.
@@ -56,7 +55,7 @@ export function createOutput(o) {
         warn(s) {
             stderr.write(line(s));
         },
-        error(message, code = EXIT.failure) {
+        error(message, code = EXIT.FAILED) {
             stderr.write(line(`${o.tool}: ${message}`));
             return code;
         },

package/packages/server/dist/cli/paddock.js

@@ -23,7 +23,7 @@ import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { CliError, UsageError, USAGE, USAGE_SYNOPSIS, SERVICE_USAGE, CONFIG_USAGE, BUSY_USAGE, UPDATE_USAGE, parseCommand, nodeVersionProblem, explainListenError, } from "./args.js";
+import { CliError, UsageError, USAGE, USAGE_SYNOPSIS, SERVICE_USAGE, CONFIG_USAGE, BUSY_USAGE, UPDATE_USAGE, DOCTOR_USAGE, parseCommand, nodeVersionProblem, explainListenError, } from "./args.js";
 import { EXIT } from "./exit-codes.js";
 import { runService, safeHomeDir, realpathOr } from "./service/index.js";
 import { PADDOCK_NAME, PADDOCK_VERSION } from "../version.js";
@@ -78,9 +78,9 @@ const packageRoot = findUp("package.json") ?? path.resolve(moduleDir, "../..");
  * says the usage follows the message — the short one, not {@link USAGE}'s
  * thousand words, which would bury the line that says what was wrong.
  */
-function fail(message, code = EXIT.failure) {
+function fail(message, code = EXIT.FAILED) {
     console.error(`paddock: ${message}`);
-    if (code === EXIT.usage) {
+    if (code === EXIT.USAGE) {
         console.error("");
         console.error(USAGE_SYNOPSIS);
     }
@@ -175,7 +175,7 @@ async function service(command) {
     // which `main` has already handled. Typed rather than asserted.
     if (action === undefined) {
         console.log(SERVICE_USAGE);
-        return EXIT.ok;
+        return EXIT.OK;
     }
     try {
         return await runService(action, opts, serviceContext());
@@ -246,13 +246,13 @@ async function config(command) {
     // which `main` has already handled. Typed rather than asserted.
     if (action === undefined) {
         console.log(CONFIG_USAGE);
-        return EXIT.ok;
+        return EXIT.OK;
     }
     process.env.PADDOCK_DATA_DIR = resolveDataDir(opts);
     const { runConfig } = await import("./config.js");
     try {
         await runConfig(action, opts);
-        return EXIT.ok;
+        return EXIT.OK;
     }
     catch (err) {
         // A config that will not load reaches here as a CliError already carrying
@@ -289,13 +289,15 @@ async function main() {
                     ? BUSY_USAGE
                     : command.verb === "update"
                         ? UPDATE_USAGE
-                        : USAGE);
-        return EXIT.ok;
+                        : command.verb === "doctor"
+                            ? DOCTOR_USAGE
+                            : USAGE);
+        return EXIT.OK;
     }
     if (opts.version) {
         // Bare: the version and a newline, nothing else (SPEC §1). Scripts parse this.
         console.log(PADDOCK_VERSION);
-        return EXIT.ok;
+        return EXIT.OK;
     }
     const problem = nodeVersionProblem(process.versions.node);
     if (problem !== undefined)
@@ -329,6 +331,21 @@ async function main() {
             throw err;
         }
     }
+    // `doctor` (SPEC §1). Dynamic for the same reason `busy` and `update` are; it
+    // loads the config only to check it, and starts nothing.
+    if (command.verb === "doctor") {
+        const { runDoctor } = await import("./doctor.js");
+        try {
+            return await runDoctor(opts, serviceContext());
+        }
+        catch (err) {
+            if (err instanceof CliError)
+                return fail(err.message, err.exitCode);
+            if (err instanceof Error)
+                return fail(err.message);
+            throw err;
+        }
+    }
     addBundledBinsToPath();
     // NOTHING here reads `process.cwd()`, and that is the point (#798). `--here`
     // used to make the current directory the workspace by setting
@@ -352,7 +369,10 @@ async function main() {
     // dynamic import below is picked up with no special-casing in config.ts.
     // Precedence is explicit flag > existing env > our default.
     const dataDir = resolveDataDir(opts);
-    noteFirstRun(dataDir);
+    // `--quiet` (SPEC §3): the banner line and nothing else, so not the
+    // first-run note either (it is prose on stderr, but prose all the same).
+    if (opts.quiet !== true)
+        noteFirstRun(dataDir);
     process.env.PADDOCK_DATA_DIR = dataDir;
     if (opts.port)
         process.env.PORT = opts.port;
@@ -404,6 +424,11 @@ async function main() {
     // runner, and by anything that wants the URL without guessing the port — so
     // the friendly block below it stays, but below it.
     console.log(`${PADDOCK_NAME} ${PADDOCK_VERSION}: ${url}`);
+    if (opts.quiet === true) {
+        if (opts.open)
+            openBrowser(url);
+        return EXIT.OK;
+    }
     // Still name the data dir, even though it no longer varies with cwd: "which
     // instance am I looking at" is a real question the moment anyone passes
     // `--data-dir`, and the answer should be readable off the two lines the tool
@@ -420,7 +445,7 @@ async function main() {
     // 0, but NOT yet: a foreground serve keeps running because the server holds
     // the event loop open. `process.exitCode` is set and never acted on until the
     // listener closes, which is what SIGTERM does (start.ts).
-    return EXIT.ok;
+    return EXIT.OK;
 }
 /**
  * A closed pipe exits quietly (SPEC §2).
@@ -440,5 +465,5 @@ main().then((code) => {
     process.exitCode = code;
 }, (err) => {
     console.error("fatal:", err);
-    process.exitCode = EXIT.failure;
+    process.exitCode = EXIT.FAILED;
 });

package/packages/server/dist/cli/service/index.d.ts

@@ -1,6 +1,6 @@
 import { type CliOptions, type ServiceAction } from "../args.js";
-import { isNpxPath, serviceDir, type ServiceSpec } from "./spec.js";
-import { type Runner } from "./backend.js";
+import { isNpxPath, serviceDir } from "./spec.js";
+import { type Runner, type ServiceManager as ServiceBackend, type ServiceSpec } from "./manager.js";
 import { type UpdateSummary } from "../update/update-check.js";
 import { type HealthAnswer, type Readiness } from "./ready.js";
 export interface ServiceContext {
@@ -44,7 +44,33 @@ export interface ServiceContext {
         force?: boolean;
         json?: boolean;
     }) => Promise<number | null>;
+    /**
+     * Who holds `host:port` — nothing, a Paddock, or something else — asked by
+     * `install` before it writes a unit (SPEC §1). Injected so a test's answer
+     * does not depend on what happens to be listening on the box running it.
+     */
+    portOwner?: (host: string, port: number) => Promise<PortOwner>;
 }
+export type PortOwner = "free" | "paddock" | "other";
+/** The real {@link ServiceContext.portOwner}: a TCP connect, then `/api/health` and `/api/busy`. */
+export declare function portOwner(host: string, port: number): Promise<PortOwner>;
+/**
+ * Why `install` won't write a unit that runs a checkout (SPEC §1, §6).
+ *
+ * A checkout (or an `npm link`) is a working tree: it gets rebuilt, switched to
+ * another branch, cleaned and moved, and a unit that runs it follows every one
+ * of those — half-built `dist/` included — at the next login, unattended. The
+ * flag is there for working on Paddock itself, where that is the point.
+ */
+export declare function checkoutRefusal(packageRoot: string): string;
+/**
+ * Pick a backend, or explain why there isn't one.
+ *
+ * Windows is the honest gap. It has no per-user service concept that maps onto
+ * either of these without a scheduled task or a service wrapper, and shipping
+ * an untested third writer would be worse than saying so.
+ */
+export declare function serviceBackend(ctx: ServiceContext): ServiceBackend;
 /**
  * The version of the Paddock the unit points at.
  *
@@ -104,6 +130,8 @@ export interface StatusReport {
     /** A stale unit, a missing Node — things that are wrong but not fatal. */
     warnings: string[];
 }
+/** What `status` reports, and what `doctor`'s service checks read: one report, so the two agree. */
+export declare function buildStatus(ctx: ServiceContext, backend: ServiceBackend): Promise<StatusReport>;
 /**
  * Dispatch, returning the exit code rather than setting one (SPEC §2).
  *

package/packages/server/dist/cli/service/index.js

@@ -27,15 +27,41 @@ import os from "node:os";
 import path from "node:path";
 import { CliError } from "../args.js";
 import { EXIT } from "../exit-codes.js";
-import { buildSpec, defaultDataDir, hostFromArgv, isNpxPath, NPX_REFUSAL, portFromArgv, serviceDir, serviceLogPath, } from "./spec.js";
-import { spawnRunner, } from "./backend.js";
-import { createLaunchdBackend } from "./launchd.js";
-import { createSystemdBackend } from "./systemd.js";
+import { buildSpec, defaultDataDir, hostFromArgv, isNpxPath, NPX_REFUSAL, portFromArgv, serviceDir, serviceLogPath, PADDOCK_SERVICE, } from "./spec.js";
+import { spawnRunner, } from "./manager.js";
+import { createLaunchd, renderPlist } from "./launchd.js";
+import { createSystemd, renderUnit } from "./systemd.js";
+import { underNodeModules } from "../update/install-method.js";
 import { missingPaths } from "./path-env.js";
 import { DEFAULT_LOG_LINES, followFile, sizeOf, tailFile } from "./logs.js";
 import { readLiveRuntimeFile } from "../../runtime-file.js";
+import { PADDOCK_VERSION } from "../../version.js";
 import { updateSummary } from "../update/update-check.js";
-import { waitForReady, fetchHealth, READY_TIMEOUT_LABEL, } from "./ready.js";
+import { waitForReady, fetchHealth, identifyPaddock, isListening, READY_TIMEOUT_LABEL, } from "./ready.js";
+/** The real {@link ServiceContext.portOwner}: a TCP connect, then `/api/health` and `/api/busy`. */
+export async function portOwner(host, port) {
+    const probe = host === "0.0.0.0" || host === "" ? "127.0.0.1" : host === "::" ? "::1" : host;
+    if (!(await isListening(probe, port)))
+        return "free";
+    const who = await identifyPaddock(`http://${probe.includes(":") ? `[${probe}]` : probe}:${port}`);
+    return who?.paddock === true ? "paddock" : "other";
+}
+/**
+ * Why `install` won't write a unit that runs a checkout (SPEC §1, §6).
+ *
+ * A checkout (or an `npm link`) is a working tree: it gets rebuilt, switched to
+ * another branch, cleaned and moved, and a unit that runs it follows every one
+ * of those — half-built `dist/` included — at the next login, unattended. The
+ * flag is there for working on Paddock itself, where that is the point.
+ */
+export function checkoutRefusal(packageRoot) {
+    return (`this copy of Paddock is a checkout (${packageRoot}), so \`service install\` won't use it.\n` +
+        "         A unit that runs a checkout follows every rebuild, branch switch and move of\n" +
+        "         it, at your next login, unattended. Install it properly first:\n\n" +
+        "  npm i -g @edspencer/paddock && paddock service install\n\n" +
+        "  Or run this checkout as the service anyway (when working on Paddock):\n" +
+        "  paddock service install --from-checkout\n");
+}
 /**
  * Pick a backend, or explain why there isn't one.
  *
@@ -43,12 +69,20 @@ import { waitForReady, fetchHealth, READY_TIMEOUT_LABEL, } from "./ready.js";
  * either of these without a scheduled task or a service wrapper, and shipping
  * an untested third writer would be worse than saying so.
  */
+export function serviceBackend(ctx) {
+    return backendFor(ctx);
+}
 function backendFor(ctx) {
     const run = ctx.run ?? spawnRunner;
     if (ctx.platform === "darwin")
-        return createLaunchdBackend(run, ctx.homeDir);
-    if (ctx.platform === "linux")
-        return createSystemdBackend(run, ctx.homeDir, ctx.xdgConfigHome);
+        return createLaunchd(PADDOCK_SERVICE, { run, homeDir: ctx.homeDir });
+    if (ctx.platform === "linux") {
+        return createSystemd(PADDOCK_SERVICE, {
+            run,
+            homeDir: ctx.homeDir,
+            ...(ctx.xdgConfigHome !== undefined ? { xdgConfigHome: ctx.xdgConfigHome } : {}),
+        });
+    }
     throw new CliError(`\`paddock service\` supports macOS (launchd) and Linux (systemd --user), not ${ctx.platform}.\n` +
         "Run `paddock` in a terminal, or keep it up with whatever your platform uses.");
 }
@@ -182,6 +216,12 @@ function lingerNote(linger) {
 async function install(opts, ctx, backend) {
     if (isNpxPath(ctx.packageRoot))
         throw new CliError(NPX_REFUSAL);
+    // A checkout is a package root that isn't under any `node_modules` (SPEC §6):
+    // `packages/server` in the repo, `<prefix>/lib/node_modules/@edspencer/paddock/
+    // packages/server` from npm. `npm link` reads the same, on purpose.
+    if (!underNodeModules(ctx.packageRoot) && opts.fromCheckout !== true) {
+        throw new CliError(checkoutRefusal(ctx.packageRoot));
+    }
     // `--refresh` (SPEC §5 step 11): re-render an EXISTING unit, keeping what it
     // records. With nothing installed there is nothing to refresh — exit 4, the
     // same code every other command that needs a unit returns, rather than
@@ -190,17 +230,57 @@ async function install(opts, ctx, backend) {
     // CLI, and a silent fallback would move a `--port 9000` service to 7233 on
     // the one run nobody is watching.
     const refreshing = opts.refresh === true;
-    let existing;
+    // A reinstall keeps what the installed unit records — its port, host, data
+    // dir and verbosity — unless a flag says otherwise (SPEC §1). It used to do
+    // that only with `--refresh`, so `service install` over a `--port 9000`
+    // service quietly moved it to 7233. `--refresh` still differs in two ways:
+    // it ignores `PADDOCK_DATA_DIR` in this shell, and with no unit it exits 4.
+    const current = backend.status();
+    const existing = current.registered ? current : undefined;
     if (refreshing) {
-        existing = backend.status();
-        if (!existing.registered) {
-            console.log(notInstalled(backend));
-            return EXIT.notInstalled;
+        if (existing === undefined) {
+            if (opts.dryRun === true && opts.json === true) {
+                // `--dry-run --json` prints its own document (runService leaves it be).
+                console.error(notInstalled(backend));
+                console.log(JSON.stringify({ ok: false, action: "install", dryRun: true, error: "not installed", unit: backend.unitPath }, null, 2));
+            }
+            else {
+                console.log(notInstalled(backend));
+            }
+            return EXIT.NOT_INSTALLED;
         }
     }
     const { spec, dataDir } = specFor(existing !== undefined ? inherit(opts, existing) : opts, ctx, refreshing);
     const url = `http://${hostFromArgv(spec.args)}:${portFromArgv(spec.args)}`;
-    if (refreshing) {
+    // `--dry-run` (SPEC §1): the unit, on stdout, and nothing written — not the
+    // unit, not the service or log folders `backend.install` would make. The
+    // where-it-would-go line is on stderr, so `> paddock.service` captures the
+    // unit alone.
+    if (opts.dryRun === true) {
+        const contents = backend.platform === "darwin" ? renderPlist(PADDOCK_SERVICE, spec) : renderUnit(PADDOCK_SERVICE, spec);
+        if (opts.json === true) {
+            console.log(JSON.stringify({ ok: true, action: "install", dryRun: true, unit: backend.unitPath, contents }, null, 2));
+        }
+        else {
+            console.error(`paddock: dry run: this is the unit \`service install\` would write to ${backend.unitPath}. Nothing was written.`);
+            console.log(contents.trimEnd());
+        }
+        return EXIT.OK;
+    }
+    // Refuse a port something else holds (SPEC §1): the service would start,
+    // fail to bind, and restart every ten seconds, for good. A Paddock holding it
+    // is fine — that's the reinstall this replaces — and so is the unit's own
+    // running service when it's too old to say it's Paddock (before 0.81).
+    const port = Number(portFromArgv(spec.args));
+    const owner = await (ctx.portOwner ?? portOwner)(hostFromArgv(spec.args), port);
+    if (owner === "other") {
+        const itsOwn = current.registered && current.running && portFromArgv(current.argv) === String(port);
+        if (!itsOwn) {
+            throw new CliError(`port ${port} is held by something that isn't Paddock, so the service could not start.\n` +
+                `  Stop it, or pick another port:  paddock service install --port ${port + 1}`);
+        }
+    }
+    if (existing !== undefined) {
         console.log(`\n  Re-writing ${backend.unitPath}\n  Keeping: paddock ${spec.args.join(" ")}`);
     }
     console.log(installProgress(backend));
@@ -241,7 +321,7 @@ async function install(opts, ctx, backend) {
     ].join("\n"));
     // "It is installed but did not answer" is a failure, and used to exit 0 — so
     // an Ansible task or a CI step could not tell it from a working install.
-    return readiness === "ready" ? EXIT.ok : EXIT.failure;
+    return readiness === "ready" ? EXIT.OK : EXIT.FAILED;
 }
 function uninstall(ctx, backend) {
     const existed = backend.uninstall();
@@ -255,7 +335,7 @@ function uninstall(ctx, backend) {
     // 0 either way: "there was nothing to remove" is the state the caller asked
     // for. `uninstall` is idempotent on purpose, so a teardown script can run it
     // without first asking whether it has anything to do.
-    return EXIT.ok;
+    return EXIT.OK;
 }
 /**
  * The data dir the INSTALLED unit uses, read out of its own argument vector.
@@ -318,10 +398,11 @@ export function installedVersionOf(cliPath) {
 }
 /** `{ update }` when there is a recent check to repeat, and `{}` otherwise. */
 function withUpdate(home) {
-    const summary = updateSummary(home);
+    const summary = updateSummary(home, { currentVersion: PADDOCK_VERSION });
     return summary !== undefined ? { update: summary } : {};
 }
-async function buildStatus(ctx, backend) {
+/** What `status` reports, and what `doctor`'s service checks read: one report, so the two agree. */
+export async function buildStatus(ctx, backend) {
     const state = backend.status();
     const base = {
         installed: state.registered,
@@ -432,7 +513,7 @@ async function status(opts, ctx, backend) {
         // that one StatusReport is supposed to prevent. A newer version is worth
         // knowing about whether or not a unit exists.
         noteUpdate(report);
-        return EXIT.notInstalled;
+        return EXIT.NOT_INSTALLED;
     }
     const versions = report.runningVersion !== null && report.runningVersion !== report.installedVersion
         ? `  Version: ${report.runningVersion} running, ${report.installedVersion ?? "unknown"} installed`
@@ -495,10 +576,10 @@ function noteUpdate(report) {
 /** The exit code a report means (SPEC §2). */
 function statusExit(report) {
     if (!report.installed)
-        return EXIT.notInstalled;
+        return EXIT.NOT_INSTALLED;
     if (!report.running || !report.answering)
-        return EXIT.notRunning;
-    return EXIT.ok;
+        return EXIT.NOT_RUNNING;
+    return EXIT.OK;
 }
 /**
  * The URL an installed unit is actually serving, or undefined if none is.
@@ -539,12 +620,12 @@ async function startOrRestart(action, opts, ctx, backend) {
     const before = backend.status();
     if (!before.registered) {
         console.log(notInstalled(backend));
-        return EXIT.notInstalled;
+        return EXIT.NOT_INSTALLED;
     }
     const url = installedUrl(before);
     if (action === "start" && before.running) {
         console.log(`\n  Paddock is already running${pid(before)}.\n\n  URL:  ${url}\n`);
-        return EXIT.ok;
+        return EXIT.OK;
     }
     // A restart stops the instance first, so it asks the same question `stop`
     // asks (SPEC §1): refuse with 75 unless `--force`. `start` does not — there
@@ -578,7 +659,7 @@ async function startOrRestart(action, opts, ctx, backend) {
     ].join("\n"));
     // A start that never answered is a failure, not a success with a caveat: the
     // caller — often an Ansible task — has no other way to find out.
-    return readiness === "ready" ? EXIT.ok : EXIT.failure;
+    return readiness === "ready" ? EXIT.OK : EXIT.FAILED;
 }
 /**
  * The busy check, asked of the instance the UNIT describes (SPEC §1, §4).
@@ -603,11 +684,11 @@ async function stop(opts, ctx, backend) {
     const state = backend.status();
     if (!state.registered) {
         console.log(notInstalled(backend));
-        return EXIT.notInstalled;
+        return EXIT.NOT_INSTALLED;
     }
     if (!state.running) {
         console.log(`\n  Paddock is already stopped.\n  Unit: ${backend.unitPath}\n`);
-        return EXIT.ok;
+        return EXIT.OK;
     }
     // Refuse with 75 if it is in the middle of something, unless --force (SPEC
     // §4). Deliberately AFTER the two cases above: an unit that is not there, or
@@ -626,7 +707,7 @@ async function stop(opts, ctx, backend) {
         "    paddock service start",
         "",
     ].join("\n"));
-    return EXIT.ok;
+    return EXIT.OK;
 }
 function pid(state) {
     return state.pid !== undefined ? ` (pid ${state.pid})` : "";
@@ -648,7 +729,7 @@ async function logs(opts, ctx, backend) {
     const state = backend.status();
     if (!state.registered) {
         console.log(notInstalled(backend));
-        return EXIT.notInstalled;
+        return EXIT.NOT_INSTALLED;
     }
     const file = logPathOf(state, dataDirOf(state, ctx));
     const lines = opts.lines ?? DEFAULT_LOG_LINES;
@@ -657,7 +738,7 @@ async function logs(opts, ctx, backend) {
         // would be mixed into the log output itself.
         console.error(`paddock: nothing has been written to ${file} yet.`);
         if (opts.follow !== true)
-            return EXIT.ok;
+            return EXIT.OK;
     }
     else {
         const tail = tailFile(file, lines);
@@ -668,7 +749,7 @@ async function logs(opts, ctx, backend) {
         console.error(`paddock: following ${file} — Ctrl-C to stop.`);
         await followFile(file, { from: sizeOf(file) });
     }
-    return EXIT.ok;
+    return EXIT.OK;
 }
 /**
  * Dispatch, returning the exit code rather than setting one (SPEC §2).
@@ -680,6 +761,57 @@ export async function runService(action, opts, ctx) {
     // `--force` is rejected on every action but `stop` and `restart` — in
     // `parseCommand`, once, for every verb. See the note there.
     const backend = backendFor(ctx);
+    // `--json` on the actions that change something (SPEC §1): their prose goes
+    // to stderr, and stdout gets one document — what was done, and the status
+    // afterwards. `status` has its own; `--dry-run` prints its own.
+    if (opts.json === true && action !== "status" && action !== "logs" && opts.dryRun !== true) {
+        return withJson(action, () => act(action, opts, ctx, backend), ctx, backend);
+    }
+    return act(action, opts, ctx, backend);
+}
+/**
+ * Run `act` with its prose on stderr, then print `{ ok, action, error?,
+ * ...status }` on stdout (SPEC §1, §3) — the shape Hallway's `service … --json`
+ * prints, and `status --json`'s fields after `ok` and `action`, so a script
+ * reads one shape whatever it asked.
+ *
+ * Every line in this file goes through `console.log`, so the prose is moved by
+ * pointing that at stderr for the duration, rather than by threading a writer
+ * through every function. A failure still prints its document, and is then
+ * re-thrown, so `paddock: <message>` and the exit code are what they are
+ * without `--json`.
+ */
+async function withJson(action, run, ctx, backend) {
+    const log = console.log;
+    console.log = (...a) => console.error(...a);
+    let code;
+    let failure;
+    try {
+        code = await run();
+    }
+    catch (err) {
+        failure = err;
+        code = err instanceof CliError ? err.exitCode : EXIT.FAILED;
+    }
+    finally {
+        console.log = log;
+    }
+    const error = failure !== undefined
+        ? (failure instanceof Error ? failure.message : String(failure)).split("\n")[0]
+        : code === EXIT.BUSY
+            ? "busy"
+            : code === EXIT.NOT_INSTALLED
+                ? "not installed"
+                : code !== EXIT.OK
+                    ? "failed"
+                    : undefined;
+    const report = await buildStatus(ctx, backend);
+    console.log(JSON.stringify({ ok: code === EXIT.OK, action, ...(error !== undefined ? { error } : {}), ...report }, null, 2));
+    if (failure !== undefined)
+        throw failure;
+    return code;
+}
+async function act(action, opts, ctx, backend) {
     if (action === "install")
         return install(opts, ctx, backend);
     if (action === "uninstall")