@edspencer/paddock 0.81.0 → 0.82.1

package/packages/server/dist/cli/exit-codes.d.ts

@@ -1,49 +1,25 @@
-/**
- * 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.
- */
 export declare const EXIT: {
-    /** Done. Running and answering. Up to date. Not busy. */
-    readonly ok: 0;
-    /** Failed — the catch-all. */
-    readonly failure: 1;
-    /** Usage: an unknown command or flag, or a bad value. Usage follows the message. */
-    readonly usage: 2;
-    /** Not running: installed, but not running or not answering. */
-    readonly notRunning: 3;
-    /** Not installed: there is no service unit. */
-    readonly notInstalled: 4;
-    /** This install cannot update itself; the right command was printed. */
-    readonly cannotSelfUpdate: 5;
+    /** Done; running and answering; up to date; not busy. */
+    readonly OK: 0;
+    /** Failed. */
+    readonly FAILED: 1;
+    /** Usage: an unknown command or flag, a bad value. The usage is printed after the message. */
+    readonly USAGE: 2;
+    /** Not running: installed but not running or not answering, or no instance answers. */
+    readonly NOT_RUNNING: 3;
+    /** Not installed: there's no service unit. */
+    readonly NOT_INSTALLED: 4;
+    /** This install can't update itself; the right command was printed. */
+    readonly CANNOT_UPDATE: 5;
     /** The update failed and was rolled back; the old version is running again. */
-    readonly rolledBack: 6;
-    /** The update failed and could not be rolled back; a person is needed. */
-    readonly needsHuman: 7;
-    /** Busy: refused, and why was printed. Try later, or use `--force`. */
-    readonly busy: 75;
+    readonly ROLLED_BACK: 6;
+    /** The update failed and couldn't be rolled back; a person is needed. */
+    readonly ROLLBACK_FAILED: 7;
+    /** Busy: refused, and why was printed. Try later, or use `--force`. `EX_TEMPFAIL` from sysexits.h. */
+    readonly BUSY: 75;
 };
 export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+/** A tool may use 8 to 63 for its own commands (SPEC §2). */
+export declare function isToolOwnCode(code: number): boolean;
+/** The SPEC's name for a shared code, for messages ("expected 4 (not installed), got 0 (ok)"). */
+export declare function describeExitCode(code: number | null): string;

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, parseCommand, nodeVersionProblem, explainListenError, } from "./args.js";
+import { CliError, UsageError, USAGE, USAGE_SYNOPSIS, SERVICE_USAGE, CONFIG_USAGE, BUSY_USAGE, UPDATE_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,28 +175,10 @@ 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, {
-            platform: process.platform,
-            // 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(),
-            ...(process.env.PADDOCK_DATA_DIR !== undefined
-                ? { envDataDir: process.env.PADDOCK_DATA_DIR }
-                : {}),
-            ...(process.env.XDG_CONFIG_HOME !== undefined
-                ? { xdgConfigHome: process.env.XDG_CONFIG_HOME }
-                : {}),
-            ...(process.env.PATH !== undefined ? { pathEnv: process.env.PATH } : {}),
-        });
+        return await runService(action, opts, serviceContext());
     }
     catch (err) {
         // A CliError carries its own code: an unsupported platform or an npx
@@ -208,6 +190,35 @@ async function service(command) {
         throw err;
     }
 }
+/**
+ * The facts about THIS install that every unit-reading command needs.
+ *
+ * One function, used by `paddock service` and by `paddock update`, because the
+ * two have to agree: an `update` that refreshed a unit built from a different
+ * Node path or a different script than `service status` reports would be the
+ * worst kind of nearly-working.
+ */
+function serviceContext() {
+    return {
+        platform: process.platform,
+        // 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(),
+        ...(process.env.PADDOCK_DATA_DIR !== undefined
+            ? { envDataDir: process.env.PADDOCK_DATA_DIR }
+            : {}),
+        ...(process.env.XDG_CONFIG_HOME !== undefined
+            ? { xdgConfigHome: process.env.XDG_CONFIG_HOME }
+            : {}),
+        ...(process.env.PATH !== undefined ? { pathEnv: process.env.PATH } : {}),
+    };
+}
 /**
  * Which instance this invocation is about: an explicit flag, else the
  * environment, else `~/.paddock`.
@@ -235,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
@@ -276,13 +287,15 @@ async function main() {
                 ? CONFIG_USAGE
                 : command.verb === "busy"
                     ? BUSY_USAGE
-                    : USAGE);
-        return EXIT.ok;
+                    : command.verb === "update"
+                        ? UPDATE_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)
@@ -299,6 +312,23 @@ async function main() {
         const { runBusy } = await import("./busy-command.js");
         return runBusy(resolveDataDir(opts), opts.json === true);
     }
+    // `update` (SPEC §1, §5). Imported dynamically for the same reason `busy` is:
+    // nothing in it needs the server, and a command whose whole job is to replace
+    // the files it would have loaded has particularly good reason not to load
+    // them.
+    if (command.verb === "update") {
+        const { runUpdateCommand } = await import("./update-command.js");
+        try {
+            return await runUpdateCommand(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
@@ -390,7 +420,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).
@@ -410,5 +440,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,7 @@
 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 ServiceSpec } from "./manager.js";
+import { type UpdateSummary } from "../update/update-check.js";
 import { type HealthAnswer, type Readiness } from "./ready.js";
 export interface ServiceContext {
     /** `process.platform`. */
@@ -84,6 +85,22 @@ export interface StatusReport {
     cli: string | null;
     /** Linux only: null where the platform has no such concept. */
     linger: boolean | null;
+    /**
+     * What the last `update --check` found, from `<data-dir>/update-check.json`
+     * (SPEC §3).
+     *
+     * `status` never asks the registry itself — the contract is explicit that
+     * nothing contacts it by itself, and a status command run by a monitoring
+     * loop would be exactly the background check §3 forbids. So this repeats a
+     * file somebody's `update --check` or `doctor` wrote.
+     *
+     * **Absent, not null, when there is nothing to repeat.** The contract's
+     * `schemas/service-status.schema.json` types this key as an OBJECT, so a
+     * `null` fails the schema and the conformance runner says so — which is how
+     * this was found. The other optional fields here are `| null` because the
+     * schema types THOSE as nullable; this one it does not.
+     */
+    update?: UpdateSummary;
     /** A stale unit, a missing Node — things that are wrong but not fatal. */
     warnings: string[];
 }
@@ -94,6 +111,41 @@ export interface StatusReport {
  * never `process.exit()`, which truncates piped output mid-write.
  */
 export declare function runService(action: ServiceAction, opts: CliOptions, ctx: ServiceContext): Promise<number>;
+/**
+ * What `paddock update` needs to know and do about the service (SPEC §5).
+ *
+ * Built here rather than in the update module so that everything which reads a
+ * unit file stays in one place: `update` gets the same answer `status` and
+ * `logs` get, from the same backend, including the #824 rule that the instance
+ * in question is the one the UNIT describes and not whatever `--data-dir` the
+ * invocation carries.
+ *
+ * Returns `home` too, which is the data dir `update.lock` and
+ * `update-check.json` go in. It has to be the unit's: the cache's reader is
+ * `service status`, which looks in the unit's data dir, so writing it anywhere
+ * else would be writing a file nothing reads.
+ */
+export declare function updateServiceHooks(ctx: ServiceContext): {
+    hooks: ServiceHooksForUpdate;
+    home: string;
+    installed: boolean;
+};
+/** The shape {@link updateServiceHooks} returns — structurally `UpdateServiceHooks`. */
+export interface ServiceHooksForUpdate {
+    inspect(): {
+        installed: boolean;
+        running: boolean;
+        url?: string;
+        log?: string;
+    };
+    stop(): void;
+    refresh(cliPath: string): {
+        status: number | null;
+        stdout: string;
+        stderr: string;
+    };
+    tail(lines: number): string;
+}
 /** Exported for the entrypoint's context assembly, and for tests. */
 export { serviceDir, isNpxPath };
 export type { ServiceSpec };