@edspencer/paddock 0.79.0 → 0.80.0

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

@@ -23,8 +23,10 @@ import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { CliError, USAGE, SERVICE_USAGE, CONFIG_USAGE, parseCommand, nodeVersionProblem, explainListenError, } from "./args.js";
-import { runService, safeHomeDir } from "./service/index.js";
+import { CliError, UsageError, USAGE, USAGE_SYNOPSIS, SERVICE_USAGE, CONFIG_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";
 /**
  * This module's own file and directory: `<…>/packages/server/dist/cli/`.
  *
@@ -62,18 +64,27 @@ function findUp(rel) {
 }
 /** Nearest ancestor holding a `package.json` — `packages/server` in both layouts. */
 const packageRoot = findUp("package.json") ?? path.resolve(moduleDir, "../..");
-function fail(message) {
+/**
+ * Report a failure, and hand back the code to exit with (SPEC §2, §3).
+ *
+ * Two things here are the contract rather than style. Errors go to **stderr**
+ * as `paddock: <message>`, so a `--json` document on stdout stays the only
+ * thing on stdout. And the code is RETURNED rather than passed to
+ * `process.exit()`: exiting mid-write truncates piped output, which is how a
+ * `paddock service status | jq` loses the end of its document. `main` assigns
+ * `process.exitCode` and lets the process end on its own.
+ *
+ * A usage error also prints the synopsis after the message, because the spec
+ * 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) {
     console.error(`paddock: ${message}`);
-    process.exit(1);
-}
-function readVersion() {
-    try {
-        const raw = fs.readFileSync(path.join(packageRoot, "package.json"), "utf8");
-        return JSON.parse(raw).version ?? "unknown";
-    }
-    catch {
-        return "unknown";
+    if (code === EXIT.usage) {
+        console.error("");
+        console.error(USAGE_SYNOPSIS);
     }
+    return code;
 }
 /**
  * Put our bundled `claude` on PATH for child processes.
@@ -121,7 +132,10 @@ function addBundledBinsToPath() {
 function noteFirstRun(dataDir) {
     if (fs.existsSync(dataDir))
         return;
-    console.log([
+    // stderr, because stdout's first line belongs to the banner (SPEC §3). This
+    // block is prose for a person and it only appears on a first run — which is
+    // exactly the run a conformance check or a script reading the URL performs.
+    console.error([
         "",
         `  Welcome to Paddock. Creating a new instance in ${dataDir}`,
         "  Projects, chats and settings persist there between runs.",
@@ -161,12 +175,17 @@ async function service(command) {
     // which `main` has already handled. Typed rather than asserted.
     if (action === undefined) {
         console.log(SERVICE_USAGE);
-        return;
+        return EXIT.ok;
     }
     try {
-        await runService(action, opts, {
+        return await runService(action, opts, {
             platform: process.platform,
-            nodePath: process.execPath,
+            // Realpath'd (SPEC §7). `process.execPath` under a version manager is
+            // routinely a symlink into a per-shell directory — fnm's
+            // `fnm_multishells/<pid>_<ts>/bin/node` is deleted when that terminal
+            // exits — so a unit naming the symlink stops working when the tab closes,
+            // at some later login, with nothing in the logs because it never ran.
+            nodePath: realpathOr(process.execPath),
             scriptPath: entryScript,
             packageRoot,
             homeDir: safeHomeDir(),
@@ -180,10 +199,12 @@ async function service(command) {
         });
     }
     catch (err) {
+        // A CliError carries its own code: an unsupported platform or an npx
+        // refusal is a failure (1), a misspelled flag is usage (2).
         if (err instanceof CliError)
-            fail(err.message);
+            return fail(err.message, err.exitCode);
         if (err instanceof Error)
-            fail(err.message);
+            return fail(err.message);
         throw err;
     }
 }
@@ -214,12 +235,13 @@ async function config(command) {
     // which `main` has already handled. Typed rather than asserted.
     if (action === undefined) {
         console.log(CONFIG_USAGE);
-        return;
+        return EXIT.ok;
     }
     process.env.PADDOCK_DATA_DIR = resolveDataDir(opts);
     const { runConfig } = await import("./config.js");
     try {
         await runConfig(action, opts);
+        return EXIT.ok;
     }
     catch (err) {
         // A config that will not load reaches here as a CliError already carrying
@@ -227,9 +249,9 @@ async function config(command) {
         // because it is a bug in this command rather than in the configuration.
         // Same shape as `service` above.
         if (err instanceof CliError)
-            fail(err.message);
+            return fail(err.message, err.exitCode);
         if (err instanceof Error)
-            fail(err.message);
+            return fail(err.message);
         throw err;
     }
 }
@@ -239,30 +261,30 @@ async function main() {
         command = parseCommand(process.argv.slice(2));
     }
     catch (err) {
+        // Parse failures are usage failures: exit 2, not 1 (SPEC §2).
+        if (err instanceof UsageError)
+            return fail(err.message, err.exitCode);
         if (err instanceof CliError)
-            fail(err.message);
+            return fail(err.message, err.exitCode);
         throw err;
     }
     const opts = command.opts;
     if (opts.help) {
         console.log(command.verb === "service" ? SERVICE_USAGE : command.verb === "config" ? CONFIG_USAGE : USAGE);
-        return;
+        return EXIT.ok;
     }
     if (opts.version) {
-        console.log(readVersion());
-        return;
+        // Bare: the version and a newline, nothing else (SPEC §1). Scripts parse this.
+        console.log(PADDOCK_VERSION);
+        return EXIT.ok;
     }
     const problem = nodeVersionProblem(process.versions.node);
     if (problem !== undefined)
-        fail(problem);
-    if (command.verb === "service") {
-        await service(command);
-        return;
-    }
-    if (command.verb === "config") {
-        await config(command);
-        return;
-    }
+        return fail(problem);
+    if (command.verb === "service")
+        return service(command);
+    if (command.verb === "config")
+        return config(command);
     addBundledBinsToPath();
     // NOTHING here reads `process.cwd()`, and that is the point (#798). `--here`
     // used to make the current directory the workspace by setting
@@ -330,9 +352,14 @@ async function main() {
         await start();
     }
     catch (err) {
-        fail(explainListenError(err, host, port));
+        return fail(explainListenError(err, host, port));
     }
     const url = `http://${host}:${port}`;
+    // The contract's banner line, FIRST on stdout and in exactly this shape:
+    // `<Name> <version>: <url>` (SPEC §3). It is parsed — by the conformance
+    // 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}`);
     // 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
@@ -346,8 +373,28 @@ async function main() {
     ].join("\n"));
     if (opts.open)
         openBrowser(url);
+    // 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;
 }
-main().catch((err) => {
+/**
+ * A closed pipe exits quietly (SPEC §2).
+ *
+ * `paddock service logs | head -5` closes the pipe under us, and Node's default
+ * is an unhandled EPIPE with a stack trace — printed to the terminal, after the
+ * output the user asked for, about a thing that is not a problem.
+ */
+process.stdout.on("error", (err) => {
+    if (err.code === "EPIPE")
+        process.exit(0);
+});
+main().then((code) => {
+    // `process.exitCode`, never `process.exit()` (SPEC §2): exiting mid-write
+    // truncates piped output, which is how `paddock config show --json | jq`
+    // loses the end of a large document.
+    process.exitCode = code;
+}, (err) => {
     console.error("fatal:", err);
-    process.exit(1);
+    process.exitCode = EXIT.failure;
 });

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

@@ -12,6 +12,23 @@ export interface RunResult {
  */
 export type Runner = (cmd: string, args: string[]) => RunResult;
 export declare const spawnRunner: Runner;
+/**
+ * Whether the user lingers — Linux only (SPEC §7).
+ *
+ * `loginctl show-user <user> -p Linger` is the question, and all three answers
+ * are distinct and useful: on (nothing to say), off (the service dies at
+ * logout, and the fix needs `sudo`), and *unknown* — no `loginctl`, no logind,
+ * a container. Collapsing unknown into "off" would print a `sudo` instruction
+ * to someone whose machine has no `loginctl` to run it with.
+ */
+export interface LingerState {
+    /** False where the platform has no such concept (darwin). */
+    applies: boolean;
+    /** On, off, or undefined when the check could not answer. */
+    enabled?: boolean;
+    /** The user the check asked about, for the printed command. */
+    user?: string;
+}
 export interface ServiceState {
     /** Is a unit file installed for us? */
     registered: boolean;
@@ -20,6 +37,28 @@ export interface ServiceState {
     pid?: string;
     /** The Paddock arguments recorded in the installed unit, interpreter stripped. */
     argv: string[];
+    /**
+     * The interpreter and script the installed unit actually names.
+     *
+     * Reported separately from {@link argv} because `status` has to be able to
+     * say "the Node it runs is not there any more" (SPEC §7), which is only
+     * answerable from the paths in the FILE. Under nvm, fnm or volta, removing a
+     * Node version leaves a unit naming an interpreter that no longer exists —
+     * and the symptom is Paddock being absent with an empty log, because it never
+     * got as far as running. Undefined for a unit we could not parse.
+     */
+    nodePath?: string;
+    cliPath?: string;
+    /**
+     * The log file the installed unit names, if it names one.
+     *
+     * Read back rather than recomputed so `status` and `logs` report the file the
+     * service is really appending to. A unit written before the logs moved to
+     * `<dataDir>/logs/service.log` names the old pair under `<dataDir>/service/`,
+     * and telling its owner to read a file nothing writes to is worse than
+     * telling them nothing.
+     */
+    logPath?: string;
     /**
      * Does the unit ON DISK come back after a graceful stop (#872)?
      *
@@ -64,8 +103,13 @@ export interface ServiceBackend {
     start(): void;
     stop(): void;
     restart(): void;
-    /** How to read the logs, as printed lines. */
-    logsHint(spec: ServiceSpec): string;
-    /** The `enable-linger` warning, or undefined where it does not apply. */
-    lingerNote(): string | undefined;
+    /**
+     * Does this user linger? (SPEC §7.) Asked of the OS, not assumed.
+     *
+     * The note used to be printed unconditionally on Linux, which meant the
+     * people who had already run `enable-linger` were told to run it at every
+     * install and every status — so the one line that mattered to the people who
+     * had NOT was indistinguishable from boilerplate.
+     */
+    linger(): LingerState;
 }

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

@@ -1,7 +1,7 @@
 import { type CliOptions, type ServiceAction } from "../args.js";
 import { isNpxPath, serviceDir, type ServiceSpec } from "./spec.js";
 import { type Runner } from "./backend.js";
-import { type Readiness } from "./ready.js";
+import { type HealthAnswer, type Readiness } from "./ready.js";
 export interface ServiceContext {
     /** `process.platform`. */
     platform: NodeJS.Platform;
@@ -26,8 +26,62 @@ export interface ServiceContext {
      * message — twenty seconds per case, and green for the wrong reason.
      */
     checkReady?: (url: string) => Promise<Readiness>;
+    /**
+     * "What does `/api/health` say?", injected for the same reason `checkReady`
+     * is — `status` has to be assertable without a server to ask.
+     */
+    probeHealth?: (url: string) => Promise<HealthAnswer | undefined>;
+}
+/**
+ * The version of the Paddock the unit points at.
+ *
+ * Found by walking up from the `cli.js` in the unit to the nearest
+ * `package.json`, which is `packages/server/package.json` in both the repo and
+ * the published tarball — the same hop the CLI itself makes to answer
+ * `--version`. Undefined when the unit names a path that is no longer there,
+ * which is a state `status` reports rather than guesses around.
+ */
+export declare function installedVersionOf(cliPath: string | undefined): string | undefined;
+/**
+ * What `service status` knows, before it is either printed or serialised.
+ *
+ * One shape for both renderings, so `--json` cannot quietly disagree with the
+ * prose above it — which is the usual way a `--json` flag rots.
+ */
+export interface StatusReport {
+    installed: boolean;
+    running: boolean;
+    /** Did `/api/health` answer? Only then is the service actually usable. */
+    answering: boolean;
+    /** The version the unit points at, and the version that answered. */
+    installedVersion: string | null;
+    runningVersion: string | null;
+    port: number | null;
+    host: string | null;
+    url: string | null;
+    pid: number | null;
+    /** The Paddock arguments the unit records, interpreter and script stripped. */
+    args: string[];
+    /** The plist / unit file — present whether or not it exists. */
+    unit: string;
+    manager: "launchd" | "systemd";
+    /** The one file both streams append to. */
+    log: string | null;
+    dataDir: string | null;
+    node: string | null;
+    cli: string | null;
+    /** Linux only: null where the platform has no such concept. */
+    linger: boolean | null;
+    /** A stale unit, a missing Node — things that are wrong but not fatal. */
+    warnings: string[];
 }
-export declare function runService(action: ServiceAction, opts: CliOptions, ctx: ServiceContext): Promise<void>;
+/**
+ * Dispatch, returning the exit code rather than setting one (SPEC §2).
+ *
+ * The code is returned up to `paddock.ts`, which assigns `process.exitCode` —
+ * never `process.exit()`, which truncates piped output mid-write.
+ */
+export declare function runService(action: ServiceAction, opts: CliOptions, ctx: ServiceContext): Promise<number>;
 /** Exported for the entrypoint's context assembly, and for tests. */
 export { serviceDir, isNpxPath };
 export type { ServiceSpec };