@edspencer/paddock 0.80.0 → 0.82.0

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

@@ -0,0 +1,150 @@
+// From edspencer/cli-contract reference/busy-client.ts @ SPEC 0.1; local changes: `.ts` import specifiers → `.js`
+// and `../runtime-file.js` (the writer lives server-side, next to the boot path that writes the file); `EXIT.OK` /
+// `EXIT.BUSY` / `EXIT.NOT_RUNNING` / `EXIT.FAILED` → Paddock's lowercase `EXIT.ok` / `busy` / `notRunning` /
+// `failure` (see `exit-codes.ts`, which wave C4 re-syncs); and `hint` widened from a string to
+// `string | ((result) => string | undefined)`, with {@link runBusyCommand} printing it too — that is what carries
+// Paddock's keeper-chat trap (ROADMAP "Busy, per tool"), where the line to print depends on WHICH counts are
+// non-zero, so a fixed string could not say it.
+//
+// The CLI's side of the busy check (SPEC §4): find the running instance through `<home>/runtime.json`, ask its
+// `/api/busy`, and map the answer to exit 0 (idle), 75 (busy) or 3 (nothing answers), with §4's messages.
+// Used by `<tool> busy`, and before `service stop`, `service restart` and `update`. Node built-ins only.
+import { EXIT } from "./exit-codes.js";
+import { readLiveRuntimeFile } from "../runtime-file.js";
+/**
+ * Asks the running instance whether it's busy. There's no fallback to a default port: an instance that's running
+ * wrote `runtime.json`, and guessing a port would ask whatever else is listening there.
+ */
+export async function checkBusy(o) {
+    const base = o.url ?? readLiveRuntimeFile(o.home)?.url;
+    if (!base)
+        return { state: "not-running" };
+    const url = new URL("/api/busy", base).toString();
+    const doFetch = o.fetch ?? globalThis.fetch;
+    let res;
+    try {
+        res = await doFetch(url, {
+            signal: AbortSignal.timeout(o.timeoutMs ?? 3000),
+            headers: { accept: "application/json" },
+        });
+    }
+    catch {
+        // Refused, reset or timed out: nothing is answering, which §4 calls not running.
+        return { state: "not-running" };
+    }
+    if (!res.ok)
+        return { state: "unknown", url, detail: `HTTP ${res.status}` };
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch {
+        return { state: "unknown", url, detail: "the answer isn't JSON" };
+    }
+    if (!isBusyAnswer(body))
+        return { state: "unknown", url, detail: "the answer has no boolean `busy`" };
+    return { state: body.busy ? "busy" : "idle", url, answer: body };
+}
+function isBusyAnswer(v) {
+    if (typeof v !== "object" || v === null || typeof v.busy !== "boolean")
+        return false;
+    const counts = v.counts;
+    if (counts === undefined)
+        return true;
+    return (typeof counts === "object" &&
+        counts !== null &&
+        Object.values(counts).every((n) => Number.isInteger(n) && n >= 0));
+}
+/** `2 chats and 1 job are running`, from the non-zero counts; '' if there are none. */
+export function describeCounts(counts = {}, nouns = {}) {
+    const parts = Object.entries(counts)
+        .filter(([, n]) => n > 0)
+        .map(([kind, n]) => {
+        const [one, many] = nouns[kind] ?? [kind, `${kind}s`];
+        return `${n} ${n === 1 ? one : many}`;
+    });
+    if (parts.length === 0)
+        return "";
+    const list = parts.length === 1 ? parts[0] : `${parts.slice(0, -1).join(", ")} and ${parts.at(-1)}`;
+    const total = Object.values(counts).reduce((a, n) => a + (n > 0 ? n : 0), 0);
+    return `${list} ${total === 1 ? "is" : "are"} running`;
+}
+/** The sentence for a person (SPEC §4): `Paddock is busy: 2 chats are running.` */
+export function busyMessage(name, result, nouns = {}) {
+    switch (result.state) {
+        case "not-running":
+            return `${name} isn't running.`;
+        case "idle":
+            return `${name} isn't busy.`;
+        case "busy": {
+            const what = describeCounts(result.answer.counts, nouns);
+            return what ? `${name} is busy: ${what}.` : `${name} is busy.`;
+        }
+        case "unknown":
+            return `Something answered at ${result.url}, but not as ${name}'s busy check (${result.detail}).`;
+    }
+}
+/** 0 idle, 75 busy, 3 nothing answers, 1 an answer that isn't a busy answer. */
+export function busyExitCode(result) {
+    switch (result.state) {
+        case "idle":
+            return EXIT.ok;
+        case "busy":
+            return EXIT.busy;
+        case "not-running":
+            return EXIT.notRunning;
+        case "unknown":
+            return EXIT.failure;
+    }
+}
+/** What `<tool> busy --json` prints: valid against `schemas/busy.schema.json`. */
+export function busyJson(result) {
+    if (result.state === "not-running")
+        return { running: false, busy: false };
+    if (result.state === "unknown")
+        return { running: true, busy: false, url: base(result.url), error: result.detail };
+    return {
+        running: true,
+        busy: result.answer.busy,
+        url: base(result.url),
+        ...(result.answer.version !== undefined ? { version: result.answer.version } : {}),
+        counts: result.answer.counts ?? {},
+    };
+}
+const base = (busyUrl) => busyUrl.replace(/\/api\/busy$/, "");
+function resolveHint(hint, result) {
+    return typeof hint === "function" ? hint(result) : hint;
+}
+/** `<tool> busy [--json]`. Returns the exit code; the caller sets `process.exitCode`. */
+export async function runBusyCommand(o) {
+    const result = await checkBusy(o);
+    const message = busyMessage(o.name, result, o.nouns);
+    o.out.result(busyJson(result));
+    if (result.state === "unknown")
+        o.out.error(message);
+    else
+        o.out.say(message);
+    // LOCAL CHANGE: the hint rides along with a busy answer here too, not only on the guard's refusal — someone who
+    // ran `paddock busy` from inside a chat needs the same sentence as someone whose `service stop` was refused.
+    const hint = result.state === "busy" ? resolveHint(o.hint, result) : undefined;
+    if (hint !== undefined)
+        o.out.say(hint);
+    return busyExitCode(result);
+}
+/**
+ * The check before `service stop`, `service restart` and `update` (SPEC §4). Returns null to go ahead, or 75 after
+ * printing the refusal. With `--force` it prints the same message, prefixed `Overriding:`, and goes ahead.
+ * Nothing answering goes ahead: there's nothing to cut short.
+ */
+export async function guardBusy(o) {
+    const result = await checkBusy(o);
+    if (result.state !== "busy")
+        return null;
+    const message = busyMessage(o.name, result, o.nouns);
+    if (o.force) {
+        o.out.warn(`Overriding: ${message}`);
+        return null;
+    }
+    const hint = resolveHint(o.hint, result) ?? "Try again once it has finished, or use --force.";
+    return o.out.error(`${message} ${hint}`, EXIT.busy);
+}

package/packages/server/dist/cli/output.d.ts

@@ -0,0 +1,52 @@
+export interface OutputStream {
+    write(chunk: string): unknown;
+    isTTY?: boolean;
+}
+export interface OutputOptions {
+    /** The bin, for `<tool>: <message>`. */
+    tool: string;
+    /** `--json` was given: stdout carries exactly one JSON document, and prose goes to stderr. */
+    json?: boolean;
+    stdout?: OutputStream;
+    stderr?: OutputStream;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Whether to colour what goes to this stream (SPEC §3).
+ *
+ * - `NO_COLOR` set to anything but the empty string: never (https://no-color.org).
+ * - `FORCE_COLOR` set: `0` or `false` means never, anything else always.
+ * - Otherwise only on a TTY, and not when `TERM=dumb`.
+ */
+export declare function useColor(stream: OutputStream, env?: NodeJS.ProcessEnv): boolean;
+export interface Paint {
+    bold(s: string): string;
+    dim(s: string): string;
+    red(s: string): string;
+    green(s: string): string;
+    yellow(s: string): string;
+}
+/** Colour functions that do nothing when `on` is false. */
+export declare function paint(on: boolean): Paint;
+export interface Output {
+    readonly json: boolean;
+    /** Colour for prose on stdout (never with `--json`, which has no prose on stdout). */
+    readonly color: Paint;
+    /** Colour for stderr. */
+    readonly errColor: Paint;
+    /** Prose for a person: stdout, or stderr under `--json`. */
+    say(line: string): void;
+    /** A warning on stderr, always. */
+    warn(line: string): void;
+    /** `<tool>: <message>` on stderr. Returns `code` (default 1), for `return out.error(…)`. Sets nothing itself. */
+    error(message: string, code?: number): number;
+    /** The one JSON document `--json` promises. Prints nothing without `--json`. */
+    result(doc: unknown): void;
+}
+/** One place for a command's output. Make it once per command, after the flags are parsed. */
+export declare function createOutput(o: OutputOptions): Output;
+/**
+ * A closed pipe (`<tool> … | head -1`) exits quietly (SPEC §2): without this, Node throws EPIPE from a later write
+ * and prints a stack trace. Call once, at startup.
+ */
+export declare function exitQuietlyOnEpipe(stream?: NodeJS.WriteStream, exit?: (code: number) => void): void;

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

@@ -0,0 +1,84 @@
+// 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.
+//
+// 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.
+// Node built-ins only.
+import { EXIT } from "./exit-codes.js";
+/**
+ * Whether to colour what goes to this stream (SPEC §3).
+ *
+ * - `NO_COLOR` set to anything but the empty string: never (https://no-color.org).
+ * - `FORCE_COLOR` set: `0` or `false` means never, anything else always.
+ * - Otherwise only on a TTY, and not when `TERM=dumb`.
+ */
+export function useColor(stream, env = process.env) {
+    if (env.NO_COLOR !== undefined && env.NO_COLOR !== "")
+        return false;
+    if (env.FORCE_COLOR !== undefined)
+        return env.FORCE_COLOR !== "0" && env.FORCE_COLOR !== "false";
+    if (env.TERM === "dumb")
+        return false;
+    return stream.isTTY === true;
+}
+const sgr = (open, close) => (s) => `\u001b[${open}m${s}\u001b[${close}m`;
+const plain = (s) => s;
+/** Colour functions that do nothing when `on` is false. */
+export function paint(on) {
+    return on
+        ? {
+            bold: sgr(1, 22),
+            dim: sgr(2, 22),
+            red: sgr(31, 39),
+            green: sgr(32, 39),
+            yellow: sgr(33, 39),
+        }
+        : { bold: plain, dim: plain, red: plain, green: plain, yellow: plain };
+}
+/** One place for a command's output. Make it once per command, after the flags are parsed. */
+export function createOutput(o) {
+    const stdout = o.stdout ?? process.stdout;
+    const stderr = o.stderr ?? process.stderr;
+    const env = o.env ?? process.env;
+    const json = o.json === true;
+    let printed = false;
+    const line = (s) => (s.endsWith("\n") ? s : `${s}\n`);
+    return {
+        json,
+        color: paint(!json && useColor(stdout, env)),
+        errColor: paint(useColor(stderr, env)),
+        say(s) {
+            (json ? stderr : stdout).write(line(s));
+        },
+        warn(s) {
+            stderr.write(line(s));
+        },
+        error(message, code = EXIT.failure) {
+            stderr.write(line(`${o.tool}: ${message}`));
+            return code;
+        },
+        result(doc) {
+            if (!json)
+                return;
+            if (printed)
+                throw new Error("--json prints one document; result() was called twice");
+            printed = true;
+            stdout.write(`${JSON.stringify(doc, null, 2)}\n`);
+        },
+    };
+}
+/**
+ * A closed pipe (`<tool> … | head -1`) exits quietly (SPEC §2): without this, Node throws EPIPE from a later write
+ * and prints a stack trace. Call once, at startup.
+ */
+export function exitQuietlyOnEpipe(stream = process.stdout, exit = (c) => process.exit(c)) {
+    stream.on("error", (err) => {
+        if (err.code === "EPIPE")
+            exit(typeof process.exitCode === "number" ? process.exitCode : 0);
+        else
+            throw err;
+    });
+}

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, 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";
@@ -178,25 +178,7 @@ async function service(command) {
         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`.
@@ -270,7 +281,15 @@ async function main() {
     }
     const opts = command.opts;
     if (opts.help) {
-        console.log(command.verb === "service" ? SERVICE_USAGE : command.verb === "config" ? CONFIG_USAGE : USAGE);
+        console.log(command.verb === "service"
+            ? SERVICE_USAGE
+            : command.verb === "config"
+                ? CONFIG_USAGE
+                : command.verb === "busy"
+                    ? BUSY_USAGE
+                    : command.verb === "update"
+                        ? UPDATE_USAGE
+                        : USAGE);
         return EXIT.ok;
     }
     if (opts.version) {
@@ -285,6 +304,31 @@ async function main() {
         return service(command);
     if (command.verb === "config")
         return config(command);
+    // `busy` (SPEC §1, §4). Nothing is imported from the server for this: the
+    // answer comes off the wire, and `cli/busy.ts` is Node built-ins only — which
+    // is what keeps a question meant for a Watchtower hook from loading Fastify,
+    // herdctl and the project layer to ask it.
+    if (command.verb === "busy") {
+        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

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 { type UpdateSummary } from "../update/update-check.js";
 import { type HealthAnswer, type Readiness } from "./ready.js";
 export interface ServiceContext {
     /** `process.platform`. */
@@ -31,6 +32,18 @@ export interface ServiceContext {
      * is — `status` has to be assertable without a server to ask.
      */
     probeHealth?: (url: string) => Promise<HealthAnswer | undefined>;
+    /**
+     * The busy check `stop` and `restart` run first (SPEC §1, §4): null to go
+     * ahead, or 75 having printed the refusal.
+     *
+     * Injected for the third time for the third version of the same reason: the
+     * real one reads `<home>/runtime.json` and fetches a URL, so a test of "does
+     * stop refuse" would otherwise need a server to be busy at it.
+     */
+    guardBusy?: (action: "stop" | "restart", home: string, opts: {
+        force?: boolean;
+        json?: boolean;
+    }) => Promise<number | null>;
 }
 /**
  * The version of the Paddock the unit points at.
@@ -72,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[];
 }
@@ -82,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 };