@edspencer/paddock 0.82.1 → 0.83.1

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

@@ -1,6 +1,6 @@
 import { type CliOptions, type ServiceAction } from "../args.js";
 import { isNpxPath, serviceDir } from "./spec.js";
-import { type Runner, type ServiceSpec } from "./manager.js";
+import { type LingerState, 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,38 @@ 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 `enable-linger` line, printed only to the people it applies to (SPEC §7): when linger is off. Nothing when it's
+ * on, and nothing when loginctl couldn't answer (`doctor` reports that check as skipped).
+ */
+export declare function lingerNote(linger: LingerState): string | undefined;
 /**
  * The version of the Paddock the unit points at.
  *
@@ -104,6 +135,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

@@ -29,14 +29,39 @@ import { CliError } from "../args.js";
 import { EXIT } from "../exit-codes.js";
 import { buildSpec, defaultDataDir, hostFromArgv, isNpxPath, NPX_REFUSAL, portFromArgv, serviceDir, serviceLogPath, PADDOCK_SERVICE, } from "./spec.js";
 import { spawnRunner, } from "./manager.js";
-import { createLaunchd } from "./launchd.js";
-import { createSystemd } from "./systemd.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.
  *
@@ -44,6 +69,9 @@ 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")
@@ -174,20 +202,26 @@ function installProgress(backend) {
             "  macOS may take a few seconds to approve the background item."
         : `\n  Installing ${kind} and starting Paddock…`;
 }
-/** The `enable-linger` line, printed only to the people it applies to (SPEC §7). */
-function lingerNote(linger) {
-    if (!linger.applies || linger.enabled === true)
+/**
+ * The `enable-linger` line, printed only to the people it applies to (SPEC §7): when linger is off. Nothing when it's
+ * on, and nothing when loginctl couldn't answer (`doctor` reports that check as skipped).
+ */
+export function lingerNote(linger) {
+    if (!linger.applies || linger.enabled !== false)
         return undefined;
-    const head = linger.enabled === false
-        ? "  Lingering is off, so this service stops when you log out — including"
-        : "  If you log out (this check could not reach loginctl), a user service";
-    return (`${head}\n` +
+    return ("  Lingering is off, so this service stops when you log out — including\n" +
         "  out of an SSH session. To keep Paddock up, once:\n" +
         `    sudo loginctl enable-linger ${linger.user ?? "$USER"}`);
 }
 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
@@ -196,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));
+        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));
@@ -327,7 +401,8 @@ function withUpdate(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,
@@ -686,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")

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

@@ -1,4 +1,4 @@
-// From edspencer/cli-contract reference/service/launchd.ts @ 0.2; local changes: `.ts` import specifiers → `.js`.
+// From edspencer/cli-contract reference/service/launchd.ts @ 1.0; local changes: `.ts` import specifiers → `.js`.
 // macOS: a launchd LaunchAgent in the `gui/<uid>` domain (SPEC §7). It starts at login, not at boot, and runs as the
 // user, inside their login session (so the login keychain is unlocked). Node built-ins only.
 //
@@ -135,6 +135,7 @@ export function createLaunchd(id, o) {
         label: id.label,
         kind: 'a launchd LaunchAgent',
         install(spec) {
+            const existed = fs.existsSync(file);
             fs.mkdirSync(path.dirname(file), { recursive: true });
             fs.mkdirSync(spec.workingDirectory, { recursive: true });
             // launchd doesn't create the log's folder; without it the job fails to spawn, and says nothing.
@@ -142,7 +143,16 @@ export function createLaunchd(id, o) {
             fs.writeFileSync(file, renderPlist(id, spec), 'utf8');
             // A bootout first, because bootstrap refuses a label that's loaded. It fails on a first install, as expected.
             bootoutAndWait();
-            bootstrap();
+            try {
+                bootstrap();
+            }
+            catch (err) {
+                // A first install launchd refused mustn't leave a plist behind: `status` would then say it's installed, and
+                // the next login would try it again. A reinstall keeps its plist.
+                if (!existed)
+                    fs.rmSync(file, { force: true });
+                throw err;
+            }
             run('launchctl', ['kickstart', '-k', target]);
         },
         uninstall() {

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

@@ -1,4 +1,4 @@
-// From edspencer/cli-contract reference/service/logs.ts @ 0.2; local changes: `.ts` import specifiers → `.js`.
+// From edspencer/cli-contract reference/service/logs.ts @ 1.0; local changes: `.ts` import specifiers → `.js`.
 // `<tool> service logs [-f] [-n <lines>]` (SPEC §1, §7): one Node implementation on every OS, because every unit
 // writes to `<home>/logs/service.log`. No `tail`: `tail -f` isn't on Windows, and which `tail` won a PATH lookup would
 // change the output. Node built-ins only.

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

@@ -1,4 +1,4 @@
-// From edspencer/cli-contract reference/service/manager.ts @ 0.2; local changes: `.ts` import specifiers → `.js`.
+// From edspencer/cli-contract reference/service/manager.ts @ 1.0; local changes: `.ts` import specifiers → `.js`.
 // The seam between what a tool's service is and how a service manager spells it (SPEC §7). launchd.ts and
 // systemd.ts implement `ServiceManager`; Task Scheduler (Windows, P3) is the third, later, behind the same interface.
 // Every command goes through a `Runner`, so the lifecycle is tested with a fake one, on any OS. Node built-ins only.

package/packages/server/dist/cli/service/path-env.js

@@ -1,4 +1,4 @@
-// From edspencer/cli-contract reference/service/path-env.ts @ 0.2; local changes: `.ts` import specifiers → `.js`.
+// From edspencer/cli-contract reference/service/path-env.ts @ 1.0; local changes: `.ts` import specifiers → `.js`.
 // The PATH a unit gives the service (SPEC §7): Node's own bin folder first, then the installing shell's PATH without
 // its per-shell entries, then the system folders. Only folders that exist are kept. Node built-ins only.
 //

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

@@ -1,26 +1,3 @@
-/**
- * "Is it actually up?" — the bounded readiness poll the service CLI uses before
- * it claims success (#873, #861).
- *
- * Every service command that starts something has the same failure mode without
- * this: the supervisor accepts the request and returns, so the CLI prints a URL
- * and a cheerful past tense while the server is still binding — or is already
- * crash-looping on a port clash, which `launchctl` and `systemctl` will both
- * happily report as "running" for the ten seconds between restarts. A message
- * that can sit over a crash-loop and still say "running at <url>" is not a
- * status line, it is a guess.
- *
- * So the check is deliberately end-to-end: an HTTP request to the URL a human
- * would open, not a pid lookup. `/api/health` is the probe because it is in
- * `ALWAYS_PUBLIC_PATHS` (`auth.ts`) — it answers whatever `PADDOCK_AUTH_MODE`
- * the installed unit runs with, so this does not quietly stop working for the
- * people who configured a credential.
- *
- * The result is a tri-state on purpose. "I could not confirm it" is a real and
- * common answer — an unusual bind host, a slow first boot — and it is not the
- * same claim as "it failed". Callers print it as a caveat, not an error, and
- * point at the logs.
- */
 /** Where the poll got to when it stopped. */
 export type Readiness = "ready" | "timeout";
 /** What `/api/health` said, when it said anything (SPEC §8). */
@@ -111,3 +88,19 @@ export type VersionVerdict = {
 export declare function waitForVersion(opts: ReadyOptions & {
     version: string;
 }): Promise<VersionVerdict>;
+/** Is anything accepting connections at host:port? A second at most. */
+export declare function isListening(host: string, port: number): Promise<boolean>;
+/**
+ * Is what answers at `url` a Paddock, and which version? Undefined when nothing
+ * answers `/api/health` there.
+ *
+ * `/api/health`'s `{ ok, version }` is the CLI contract's, so every one of the
+ * six tools answers it alike; `/api/busy`'s `counts.chat` and
+ * `counts.background` are Paddock's own. A Paddock older than 0.81 has no
+ * `/api/busy`, and reads as not-Paddock here — callers that can tell it apart
+ * some other way (an installed unit on that port) should.
+ */
+export declare function identifyPaddock(url: string, fetchImpl?: typeof fetch): Promise<{
+    paddock: boolean;
+    version?: string;
+} | undefined>;

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

@@ -21,6 +21,7 @@
  * same claim as "it failed". Callers print it as a caveat, not an error, and
  * point at the logs.
  */
+import net from "node:net";
 /**
  * Ask `<url>/api/health` once, and say what it answered.
  *
@@ -134,3 +135,44 @@ export async function waitForVersion(opts) {
         await sleep(intervalMs);
     }
 }
+/** Is anything accepting connections at host:port? A second at most. */
+export function isListening(host, port) {
+    return new Promise((resolve) => {
+        const s = net.connect({ host, port });
+        s.setTimeout(1000);
+        s.once("connect", () => {
+            s.destroy();
+            resolve(true);
+        });
+        s.once("timeout", () => {
+            s.destroy();
+            resolve(false);
+        });
+        s.once("error", () => resolve(false));
+    });
+}
+/**
+ * Is what answers at `url` a Paddock, and which version? Undefined when nothing
+ * answers `/api/health` there.
+ *
+ * `/api/health`'s `{ ok, version }` is the CLI contract's, so every one of the
+ * six tools answers it alike; `/api/busy`'s `counts.chat` and
+ * `counts.background` are Paddock's own. A Paddock older than 0.81 has no
+ * `/api/busy`, and reads as not-Paddock here — callers that can tell it apart
+ * some other way (an installed unit on that port) should.
+ */
+export async function identifyPaddock(url, fetchImpl = fetch) {
+    const health = await fetchHealth(url, { fetchImpl });
+    if (health === undefined)
+        return undefined;
+    const version = health.version !== undefined ? { version: health.version } : {};
+    try {
+        const res = await fetchImpl(`${url}/api/busy`, { signal: AbortSignal.timeout(2_000) });
+        const body = (await res.json());
+        const counts = body.counts ?? {};
+        return { paddock: health.ok && typeof counts.chat === "number" && "background" in counts, ...version };
+    }
+    catch {
+        return { paddock: false, ...version };
+    }
+}

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

@@ -1,4 +1,4 @@
-// From edspencer/cli-contract reference/service/systemd.ts @ 0.2; local changes: `.ts` import specifiers → `.js`.
+// From edspencer/cli-contract reference/service/systemd.ts @ 1.0; local changes: `.ts` import specifiers → `.js`.
 // Linux: a systemd user unit (`systemctl --user`, SPEC §7), running as the user. Without linger the user's manager,
 // and the service with it, stops at their last logout, SSH sessions included; `linger()` asks, and the tool prints
 // the `sudo loginctl enable-linger` line rather than running it. Node built-ins only.
@@ -103,14 +103,27 @@ export function createSystemd(id, o) {
         kind: 'a systemd --user service',
         install(spec) {
             // Asked before the unit is overwritten, while it still describes what's running.
-            const wasActive = fs.existsSync(file) && isActive();
+            const existed = fs.existsSync(file);
+            const wasActive = existed && isActive();
             fs.mkdirSync(path.dirname(file), { recursive: true });
             fs.mkdirSync(spec.workingDirectory, { recursive: true });
             fs.mkdirSync(path.dirname(spec.logPath), { recursive: true });
             fs.writeFileSync(file, renderUnit(id, spec), 'utf8');
             // Without a reload the manager keeps serving its cached copy of the old unit.
             run('systemctl', ['--user', 'daemon-reload']);
-            systemctl('enable', '--now', id.unit);
+            try {
+                systemctl('enable', '--now', id.unit);
+            }
+            catch (err) {
+                // A first install systemd refused (no systemd here, no user bus) mustn't leave a unit behind: `status` would
+                // then say it's installed. A reinstall keeps its unit, which is what's installed either way.
+                if (!existed) {
+                    run('systemctl', ['--user', 'disable', id.unit]);
+                    fs.rmSync(file, { force: true });
+                    run('systemctl', ['--user', 'daemon-reload']);
+                }
+                throw err;
+            }
             // `enable --now` doesn't touch a unit that's already active: a reinstall over a running service would leave the
             // old process serving and report success. That's the state `update`'s rollback refreshes in, while the failed
             // version is still up. So restart, but only then: on a stopped unit it would be two starts milliseconds apart,

package/packages/server/dist/cli/update/health.js

@@ -1,4 +1,4 @@
-// From edspencer/cli-contract reference/health.ts @ 0.2; local changes: `.ts` import specifiers → `.js`.
+// From edspencer/cli-contract reference/health.ts @ 1.0; local changes: `.ts` import specifiers → `.js`.
 // Asking `/api/health` (SPEC §8): once, until it answers, or until it answers with one version. The service commands
 // wait on it before they claim success, and `update` waits for the target version (SPEC §5 step 12). It's an HTTP
 // request to the URL a person would open, not a pid lookup: launchd and systemd both report a crash-looping job as

package/packages/server/dist/cli/update/install-method.js

@@ -1,4 +1,4 @@
-// From edspencer/cli-contract reference/install-method.ts @ 0.2; local changes: `.ts` import specifiers → `.js`.
+// From edspencer/cli-contract reference/install-method.ts @ 1.0; local changes: `.ts` import specifiers → `.js`.
 // How was this copy installed? (SPEC §6.) `update` can't run `npm install -g` on a checkout, in a container or out of
 // npx's cache, so before it touches anything it works out which of the table's ten rows it's in, and either picks the
 // package manager or prints the command that would work and exits 5.

package/packages/server/dist/cli/update/lock.js

@@ -1,4 +1,4 @@
-// From edspencer/cli-contract reference/lock.ts @ 0.2; local changes: `.ts` import specifiers → `.js`, and `exit-codes`, `output` and `runtime-file` imported from where Paddock keeps them (`../`, `../../`).
+// From edspencer/cli-contract reference/lock.ts @ 1.0; local changes: `.ts` import specifiers → `.js`, and `exit-codes`, `output` and `runtime-file` imported from where Paddock keeps them (`../`, `../../`).
 // `<home>/update.lock`: one update at a time (SPEC §5 step 1). Two at once is easy to cause (an Ansible run and a
 // person at a terminal) and bad: the second stops the service the first just started, or installs an older target
 // over a newer one, and the loser's rollback "restores" a version nobody asked for.

package/packages/server/dist/cli/update/package-manager.js

@@ -1,4 +1,4 @@
-// From edspencer/cli-contract reference/package-manager.ts @ 0.2; local changes: `.ts` import specifiers → `.js`, and `exit-codes`, `output` and `runtime-file` imported from where Paddock keeps them (`../`, `../../`).
+// From edspencer/cli-contract reference/package-manager.ts @ 1.0; local changes: `.ts` import specifiers → `.js`, and `exit-codes`, `output` and `runtime-file` imported from where Paddock keeps them (`../`, `../../`).
 // Running the package manager (SPEC §5 steps 5, 8 and 10, §6, §7). Node built-ins only.
 //
 // - **npm is the one beside `process.execPath`**, run as `node <npm-cli.js>`, never whichever `npm` is first on PATH.

package/packages/server/dist/cli/update/registry.js

@@ -1,4 +1,4 @@
-// From edspencer/cli-contract reference/registry.ts @ 0.2; local changes: `.ts` import specifiers → `.js`.
+// From edspencer/cli-contract reference/registry.ts @ 1.0; local changes: `.ts` import specifiers → `.js`.
 // The npm registry, as `update` asks it (SPEC §5 step 3): two requests with `fetch` and a 10-second abort.
 //
 //   GET <registry>/-/package/<name>/dist-tags   which version `latest` (or `--to <tag>`) is

package/packages/server/dist/cli/update/semver.js

@@ -1,4 +1,4 @@
-// From edspencer/cli-contract reference/semver.ts @ 0.2; local changes: `.ts` import specifiers → `.js`.
+// From edspencer/cli-contract reference/semver.ts @ 1.0; local changes: `.ts` import specifiers → `.js`.
 // The small semver `update` needs (SPEC §5 step 4): is the target newer, is it a prerelease, and does its
 // `engines.node` accept this Node. Node built-ins only.
 //

package/packages/server/dist/cli/update/update-check.js

@@ -1,4 +1,4 @@
-// From edspencer/cli-contract reference/update-check.ts @ 0.2; local changes: `.ts` import specifiers → `.js`, and `exit-codes`, `output` and `runtime-file` imported from where Paddock keeps them (`../`, `../../`).
+// From edspencer/cli-contract reference/update-check.ts @ 1.0; local changes: `.ts` import specifiers → `.js`, and `exit-codes`, `output` and `runtime-file` imported from where Paddock keeps them (`../`, `../../`).
 // `<home>/update-check.json`: what the last registry question found (SPEC §3). Only `update`, `update --check` and
 // `doctor` ask the registry; they write the answer here, and `service status` repeats it without opening a socket.
 // It's the document `update --check --json` prints (`schemas/update-check.schema.json`), and `service status --json`'s

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

@@ -1,4 +1,4 @@
-// From edspencer/cli-contract reference/update.ts @ 0.2; local changes: `.ts` import specifiers → `.js`, and `exit-codes`, `output` and `runtime-file` imported from where Paddock keeps them (`../`, `../../`).
+// From edspencer/cli-contract reference/update.ts @ 1.0; local changes: `.ts` import specifiers → `.js`, and `exit-codes`, `output` and `runtime-file` imported from where Paddock keeps them (`../`, `../../`).
 // `<tool> update`: SPEC §5, step by step, for every tool. Node built-ins only; nothing here imports a server.
 //
 // It's a sequence over injected hooks. A tool supplies what's its own (`UpdateProduct`): its names, its busy check,

package/packages/server/dist/runtime-file.d.ts

@@ -10,7 +10,7 @@ export interface RuntimeInfo {
 export declare const RUNTIME_FILE = "runtime.json";
 export declare function runtimeFilePath(home: string): string;
 /** Writes the file atomically (a temporary file, then a rename), readable only by this user. */
-export declare function writeRuntimeFile(home: string, info: Omit<RuntimeInfo, "startedAt"> & {
+export declare function writeRuntimeFile(home: string, info: Omit<RuntimeInfo, 'startedAt'> & {
     startedAt?: string;
 }): RuntimeInfo;
 /** The file's contents, or null if it's missing or isn't a runtime file (a half-written or foreign file). */

package/packages/server/dist/runtime-file.js

@@ -1,17 +1,13 @@
-// From edspencer/cli-contract reference/runtime-file.ts @ SPEC 0.1; local changes: `node:fs` / `node:path` imports
-// unchanged, nothing else — the module is Node built-ins only and Paddock's `<home>` is its data dir, so it needed
-// no adaptation. Kept verbatim on purpose: wave C4 re-syncs it, and a divergence here would be a divergence in the
-// one file every tool's `busy`, `service status` and `update` agree on.
-//
+// From edspencer/cli-contract reference/runtime-file.ts @ 1.0; local changes: none.
 // `<home>/runtime.json`: what a running instance tells its own CLI (SPEC §4, ROADMAP). `serve` writes it once it's
 // listening and removes it on a clean exit; `busy`, `service status` and `update` read it to find the instance.
 //
 // It holds `{ pid, port, url, version, startedAt }`. A token for /api/busy will join it once SPEC §10's first question
 // is settled; the file is written 0600 already, so adding one later changes nothing about who can read it.
 // Node built-ins only.
-import fs from "node:fs";
-import path from "node:path";
-export const RUNTIME_FILE = "runtime.json";
+import fs from 'node:fs';
+import path from 'node:path';
+export const RUNTIME_FILE = 'runtime.json';
 export function runtimeFilePath(home) {
     return path.join(home, RUNTIME_FILE);
 }
@@ -41,7 +37,7 @@ export function writeRuntimeFile(home, info) {
 export function readRuntimeFile(home) {
     let raw;
     try {
-        raw = fs.readFileSync(runtimeFilePath(home), "utf8");
+        raw = fs.readFileSync(runtimeFilePath(home), 'utf8');
     }
     catch {
         return null;
@@ -50,9 +46,9 @@ export function readRuntimeFile(home) {
         const v = JSON.parse(raw);
         if (Number.isInteger(v.pid) &&
             Number.isInteger(v.port) &&
-            typeof v.url === "string" &&
-            typeof v.version === "string" &&
-            typeof v.startedAt === "string") {
+            typeof v.url === 'string' &&
+            typeof v.version === 'string' &&
+            typeof v.startedAt === 'string') {
             return v;
         }
     }
@@ -81,7 +77,7 @@ export function isPidAlive(pid) {
         return true;
     }
     catch (err) {
-        return err.code === "EPERM";
+        return err.code === 'EPERM';
     }
 }
 /** The runtime file, if the process it names is still alive. A crashed instance leaves a stale file behind. */

package/packages/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paddock/server",
-  "version": "0.82.1",
+  "version": "0.83.1",
   "private": true,
   "type": "module"
 }

package/packages/web/dist/assets/{DeleteProjectDialog-CgHpQctt.js → DeleteProjectDialog-BPwSkY3s.js}

@@ -1,2 +1,2 @@
-import{r as l,e as k,j as s,A as y,d as p,a as w}from"./index-1E9yHciS.js";import{c as N}from"./lastTab-CU1zsF0j.js";function v({open:e,title:t,message:c,confirmLabel:n="Delete",cancelLabel:o="Cancel",danger:a=!0,wide:h=!1,dismissOnBackdrop:b=!0,onConfirm:g,onClose:d}){const[r,m]=l.useState(!1),[f,u]=l.useState(null);if(l.useEffect(()=>{e?u(null):m(!1)},[e]),k(e&&!r,d),!e)return null;const j=async()=>{m(!0),u(null);try{await g()}catch(i){u(i instanceof Error?i.message:"Action failed"),m(!1)}};return s.jsx("div",{className:"fixed inset-0 z-[60] flex items-center justify-center bg-overlay p-4 backdrop-blur-sm",onClick:()=>b&&!r&&d(),children:s.jsxs("div",{className:`w-full ${h?"max-w-md":"max-w-sm"} animate-scale-in rounded-2xl border border-edge bg-surface-raised p-6 shadow-2xl`,onClick:i=>i.stopPropagation(),role:"alertdialog","aria-modal":"true",children:[s.jsxs("div",{className:"flex items-start gap-3",children:[a&&s.jsx("span",{className:"mt-0.5 flex h-9 w-9 shrink-0 items-center justify-center rounded-xl bg-danger-soft text-danger",children:s.jsx(y,{width:18,height:18})}),s.jsxs("div",{className:"min-w-0",children:[s.jsx("h2",{className:"text-base font-semibold",children:t}),s.jsx("div",{className:"mt-1.5 text-sm text-fg-muted",children:c})]})]}),f&&s.jsx("p",{className:"mt-4 rounded-lg bg-danger-soft px-3 py-2 text-sm text-danger",children:f}),s.jsxs("div",{className:"mt-5 flex justify-end gap-2",children:[s.jsx("button",{type:"button",className:"btn-ghost",onClick:d,disabled:r,children:o}),s.jsx("button",{type:"button",className:a?"btn btn-danger":"btn-primary",onClick:j,disabled:r,children:r?"Working…":n})]})]})})}function P(e,t){return e===t?!0:e.startsWith(t.endsWith("/")?t:`${t}/`)}function x(e){return!P(e.workingDir,e.dir)}function C({project:e}){const t=s.jsx("span",{className:"font-medium text-fg",children:e.name});return x(e)?s.jsxs(s.Fragment,{children:[t," will be unlinked. Paddock’s notes, settings and chats for it are permanently removed, and this cannot be undone — but the directory it works in is left alone:",s.jsx("span",{className:"mt-1.5 block break-all font-mono text-xs text-fg",children:e.workingDir}),s.jsx("span",{className:"mt-1.5 block",children:"Nothing in there is deleted."})]}):s.jsxs(s.Fragment,{children:[t," and all its chats and files will be permanently removed. This cannot be undone."]})}function D(){const{remove:e}=p();return l.useCallback(async t=>{await w.deleteProject(t),e(t),N(t)},[e])}function W({project:e,open:t,onClose:c,onDeleted:n}){const o=D(),a=x(e);return s.jsx(v,{open:t,title:"Delete project?",message:s.jsx(C,{project:e}),confirmLabel:"Delete project",wide:a,dismissOnBackdrop:!a,onConfirm:async()=>{await o(e.slug),n==null||n()},onClose:c})}export{v as C,W as D,x as d};
+import{r as l,e as k,j as s,A as y,d as p,a as w}from"./index-2MWb3aF0.js";import{c as N}from"./lastTab-CU1zsF0j.js";function v({open:e,title:t,message:c,confirmLabel:n="Delete",cancelLabel:o="Cancel",danger:a=!0,wide:h=!1,dismissOnBackdrop:b=!0,onConfirm:g,onClose:d}){const[r,m]=l.useState(!1),[f,u]=l.useState(null);if(l.useEffect(()=>{e?u(null):m(!1)},[e]),k(e&&!r,d),!e)return null;const j=async()=>{m(!0),u(null);try{await g()}catch(i){u(i instanceof Error?i.message:"Action failed"),m(!1)}};return s.jsx("div",{className:"fixed inset-0 z-[60] flex items-center justify-center bg-overlay p-4 backdrop-blur-sm",onClick:()=>b&&!r&&d(),children:s.jsxs("div",{className:`w-full ${h?"max-w-md":"max-w-sm"} animate-scale-in rounded-2xl border border-edge bg-surface-raised p-6 shadow-2xl`,onClick:i=>i.stopPropagation(),role:"alertdialog","aria-modal":"true",children:[s.jsxs("div",{className:"flex items-start gap-3",children:[a&&s.jsx("span",{className:"mt-0.5 flex h-9 w-9 shrink-0 items-center justify-center rounded-xl bg-danger-soft text-danger",children:s.jsx(y,{width:18,height:18})}),s.jsxs("div",{className:"min-w-0",children:[s.jsx("h2",{className:"text-base font-semibold",children:t}),s.jsx("div",{className:"mt-1.5 text-sm text-fg-muted",children:c})]})]}),f&&s.jsx("p",{className:"mt-4 rounded-lg bg-danger-soft px-3 py-2 text-sm text-danger",children:f}),s.jsxs("div",{className:"mt-5 flex justify-end gap-2",children:[s.jsx("button",{type:"button",className:"btn-ghost",onClick:d,disabled:r,children:o}),s.jsx("button",{type:"button",className:a?"btn btn-danger":"btn-primary",onClick:j,disabled:r,children:r?"Working…":n})]})]})})}function P(e,t){return e===t?!0:e.startsWith(t.endsWith("/")?t:`${t}/`)}function x(e){return!P(e.workingDir,e.dir)}function C({project:e}){const t=s.jsx("span",{className:"font-medium text-fg",children:e.name});return x(e)?s.jsxs(s.Fragment,{children:[t," will be unlinked. Paddock’s notes, settings and chats for it are permanently removed, and this cannot be undone — but the directory it works in is left alone:",s.jsx("span",{className:"mt-1.5 block break-all font-mono text-xs text-fg",children:e.workingDir}),s.jsx("span",{className:"mt-1.5 block",children:"Nothing in there is deleted."})]}):s.jsxs(s.Fragment,{children:[t," and all its chats and files will be permanently removed. This cannot be undone."]})}function D(){const{remove:e}=p();return l.useCallback(async t=>{await w.deleteProject(t),e(t),N(t)},[e])}function W({project:e,open:t,onClose:c,onDeleted:n}){const o=D(),a=x(e);return s.jsx(v,{open:t,title:"Delete project?",message:s.jsx(C,{project:e}),confirmLabel:"Delete project",wide:a,dismissOnBackdrop:!a,onConfirm:async()=>{await o(e.slug),n==null||n()},onClose:c})}export{v as C,W as D,x as d};
 

package/packages/web/dist/assets/DiscoverPage-DVoF9Vil.js

@@ -0,0 +1,2 @@
+import{j as o}from"./index-2MWb3aF0.js";import{D as r}from"./DiscoverView-Bz4Rxg-V.js";import{u as e}from"./documentTitle-BgvYvKAe.js";import"./Surfaces-By65IjL4.js";function p(){return e(["Discover"]),o.jsx(r,{})}export{p as DiscoverPage};
+