@edspencer/paddock 0.81.0 → 0.82.1

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

@@ -1,102 +1,60 @@
-/**
- * `paddock service logs [-f] [-n <lines>]` (SPEC §1, §7).
- *
- * One implementation for every platform, which is the whole reason the units
- * write to a file rather than to the journal: `journalctl --user -u paddock` on
- * Linux and a pair of files on macOS meant "where are the logs" had two
- * answers, neither of which Windows could ever have.
- *
- * Reading the tail of a file is deliberately done by hand rather than by
- * spawning `tail`: `tail -f` is not on every box this runs on (and is `Get-
- * Content -Wait` on the platform the contract requires us not to rule out),
- * and shelling out would make the output depend on which `tail` won a PATH
- * lookup.
- */
-import fs from "node:fs";
-/** How many lines `logs` prints when nobody says otherwise (SPEC §1). */
+// From edspencer/cli-contract reference/service/logs.ts @ 0.2; 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.
+import fs from 'node:fs';
+/** How many lines `logs` prints when nobody says (SPEC §1). */
 export const DEFAULT_LOG_LINES = 50;
-/** How much of the end of the file to read for a tail, in bytes. */
+/** Only the end of the file is read for a tail: a log can reach tens of megabytes between rotations. */
 const TAIL_WINDOW = 256 * 1024;
-/** The gap between size checks when following. */
-const FOLLOW_INTERVAL_MS = 400;
-/**
- * The last `lines` lines of `file`.
- *
- * Only the last {@link TAIL_WINDOW} bytes are read. A service log is append-only
- * and can reach tens of megabytes between rotations, and reading all of it to
- * print fifty lines would make `logs` slower than the thing it is reporting on.
- * A window that happens to start mid-line drops that partial first line rather
- * than printing half of one.
- */
+/** The last `lines` lines of `file`. A window that starts mid-line drops that fragment. */
 export function tailFile(file, lines) {
-    const fd = fs.openSync(file, "r");
+    const fd = fs.openSync(file, 'r');
     try {
         const size = fs.fstatSync(fd).size;
         const start = Math.max(0, size - TAIL_WINDOW);
-        const length = size - start;
-        if (length === 0)
-            return "";
-        const buf = Buffer.alloc(length);
-        fs.readSync(fd, buf, 0, length, start);
-        let text = buf.toString("utf8");
-        // A window that starts mid-line: drop the fragment.
-        if (start > 0) {
-            const nl = text.indexOf("\n");
-            text = nl === -1 ? "" : text.slice(nl + 1);
-        }
-        const all = text.split("\n");
-        // A trailing newline produces a final empty element that is not a line.
-        if (all[all.length - 1] === "")
+        if (size === start)
+            return '';
+        const buf = Buffer.alloc(size - start);
+        fs.readSync(fd, buf, 0, buf.length, start);
+        let text = buf.toString('utf8');
+        if (start > 0)
+            text = text.includes('\n') ? text.slice(text.indexOf('\n') + 1) : '';
+        const all = text.split('\n');
+        if (all.at(-1) === '')
             all.pop();
-        return all.slice(-lines).join("\n");
+        return all.slice(-lines).join('\n');
     }
     finally {
         fs.closeSync(fd);
     }
 }
 /**
- * Print what gets appended to `file`, from `from` onwards, until the process is
- * interrupted.
- *
- * Polling rather than `fs.watch`: the writer here is the supervisor's own file
- * descriptor, and `fs.watch` on an appended-to file is unreliable across
- * platforms (no events at all on some network filesystems, and a stream of
- * them on others). A 400 ms poll of the size is both portable and cheap.
- *
- * Rotation is handled by the one case that can actually happen: the server
- * rotates by COPY-AND-TRUNCATE (see `service-log.ts`), so the inode is stable
- * and the size goes DOWN. Seeing that, this resets to the new start rather than
- * reading past the end forever, which is what a naive follower does — it goes
- * quiet after the first rotation and never recovers.
+ * Prints what's appended to `file` until stopped. Polls the size (`fs.watch` on an appended file is unreliable across
+ * platforms). The tool rotates by copy-and-truncate, so the size goes down; seeing that, it starts again from 0
+ * rather than reading past the end for ever. A file that vanishes is waited for.
  */
-export async function followFile(file, opts) {
-    const interval = opts.intervalMs ?? FOLLOW_INTERVAL_MS;
-    const write = opts.write ?? ((s) => process.stdout.write(s));
-    const keepGoing = opts.keepGoing ?? (() => true);
-    let offset = opts.from;
-    while (keepGoing()) {
-        await new Promise((r) => setTimeout(r, interval));
+export async function followFile(file, o) {
+    const write = o.write ?? ((s) => process.stdout.write(s));
+    let offset = o.from;
+    while (o.keepGoing?.() ?? true) {
+        await new Promise((r) => setTimeout(r, o.intervalMs ?? 400));
         let size;
         try {
             size = fs.statSync(file).size;
         }
         catch {
-            // The file can vanish: an uninstall, or a rotation that renames. Wait for
-            // it to come back rather than giving up — `logs -f` is left running.
             continue;
         }
-        if (size < offset) {
-            // Truncated: the rotation above, or a hand-run `: > service.log`.
+        if (size < offset)
             offset = 0;
-        }
         if (size === offset)
             continue;
-        const fd = fs.openSync(file, "r");
+        const fd = fs.openSync(file, 'r');
         try {
-            const length = size - offset;
-            const buf = Buffer.alloc(length);
-            fs.readSync(fd, buf, 0, length, offset);
-            write(buf.toString("utf8"));
+            const buf = Buffer.alloc(size - offset);
+            fs.readSync(fd, buf, 0, buf.length, offset);
+            write(buf.toString('utf8'));
             offset = size;
         }
         finally {
@@ -104,7 +62,7 @@ export async function followFile(file, opts) {
         }
     }
 }
-/** The file's size, or 0 if it is not there — where a follow should start. */
+/** The file's size, or 0 if it isn't there: where a follow starts. */
 export function sizeOf(file) {
     try {
         return fs.statSync(file).size;

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

@@ -0,0 +1,93 @@
+/** Who the service belongs to. */
+export interface ServiceIdentity {
+    /** `Paddock`: for messages and the unit's header. */
+    name: string;
+    /** `paddock`: the bin, for the commands messages print. */
+    tool: string;
+    /** The launchd label: `net.edspencer.paddock`. A person may type it (`launchctl print gui/501/<label>`). */
+    label: string;
+    /** The systemd user unit: `paddock.service`. */
+    unit: string;
+    /** systemd's `Description=`. */
+    description: string;
+    /** systemd's `Documentation=`, if there's a page. */
+    documentation?: string;
+}
+/** What the unit runs, already resolved: every path absolute and real. */
+export interface ServiceSpec {
+    /** `realpath(process.execPath)`. */
+    nodePath: string;
+    /** `realpath(<package>/…/cli.js)`, never the bin shim: its `#!/usr/bin/env node` needs a `node` on a PATH a
+     *  service manager doesn't have under a version manager. */
+    scriptPath: string;
+    /** After the script: `serve` and the options. */
+    args: string[];
+    /** A folder the service owns: `<home>/service`. */
+    workingDirectory: string;
+    /** `<home>/logs/service.log`: both streams, appended, on every OS. */
+    logPath: string;
+    /** The service's PATH (path-env.ts). */
+    pathEnv: string;
+    /** More environment, if the tool needs any. Never a credential: a unit file is readable. */
+    env?: Record<string, string>;
+}
+/** Linux only: whether the user lingers (SPEC §7). Undefined `enabled` means the check couldn't answer. */
+export interface LingerState {
+    /** False where there's no such thing (macOS, Windows). */
+    applies: boolean;
+    enabled?: boolean;
+    user?: string;
+}
+/** What the service manager and the unit file say. */
+export interface ServiceState {
+    /** A unit file is installed. */
+    registered: boolean;
+    /** The service manager says the process is up. */
+    running: boolean;
+    pid?: string;
+    /** The tool's arguments the unit records, with Node and the script taken off. */
+    argv: string[];
+    /** The Node and script the unit names, so `status` can say when one has gone (nvm, fnm and volta remove them). */
+    nodePath?: string;
+    cliPath?: string;
+    /** The log the unit names. Read back, so `logs` reads the file the service writes even if an older unit named another. */
+    logPath?: string;
+    /** The unit restarts the service after a clean exit (launchd `KeepAlive`, systemd `Restart=always`). True when nothing's registered. */
+    keepsAlive: boolean;
+}
+export interface ServiceManager {
+    platform: 'darwin' | 'linux' | 'win32';
+    /** Where the unit file goes. */
+    unitPath: string;
+    /** The launchd label or systemd unit: the string a person would type. */
+    label: string;
+    /** For people: `a launchd LaunchAgent`, `a systemd --user service`. */
+    kind: string;
+    /** Writes the unit, enables it and starts it, replacing a running one. */
+    install(spec: ServiceSpec): void;
+    /** Stops it, disables it and removes the unit; true if there was one. Keeps the data and the logs. */
+    uninstall(): boolean;
+    /**
+     * `start`, `stop` and `restart` throw with the manager's own words. `stop` doesn't disable: the service comes back
+     * at the next login or boot (SPEC §1). `restart` re-reads the unit.
+     */
+    start(): void;
+    stop(): void;
+    restart(): void;
+    status(): ServiceState;
+    linger(): LingerState;
+}
+export interface RunResult {
+    /** null when it couldn't be run or was killed. */
+    status: number | null;
+    stdout: string;
+    stderr: string;
+}
+export type Runner = (cmd: string, args: string[]) => RunResult;
+export declare const spawnRunner: Runner;
+/** Blocks for `ms`: the Runner is synchronous, so the waits between its calls are too. */
+export declare function sleepSync(ms: number): void;
+/** No service manager here yet: Windows (P3), or anything else. */
+export declare class UnsupportedPlatformError extends Error {
+    name: string;
+}

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

@@ -0,0 +1,21 @@
+// From edspencer/cli-contract reference/service/manager.ts @ 0.2; 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.
+//
+// The Runner is synchronous on purpose: `update`'s service hooks are, and a sleep between launchd's bootout and
+// bootstrap (`sleepSync`) is all the waiting there is.
+import { spawnSync } from 'node:child_process';
+export const spawnRunner = (cmd, args) => {
+    const r = spawnSync(cmd, args, { encoding: 'utf8', timeout: 60_000, windowsHide: true });
+    return { status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+};
+/** Blocks for `ms`: the Runner is synchronous, so the waits between its calls are too. */
+export function sleepSync(ms) {
+    if (ms > 0)
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** No service manager here yet: Windows (P3), or anything else. */
+export class UnsupportedPlatformError extends Error {
+    name = 'UnsupportedPlatformError';
+}

package/packages/server/dist/cli/service/path-env.d.ts

@@ -1,27 +1,16 @@
-/** PATH entries that belong to one shell session or one npm invocation. */
+/** Entries that belong to one shell or one npm run. */
 export declare const PER_SHELL_PATTERNS: readonly RegExp[];
-/** Where the usual tools live, after the inherited PATH. Only existing ones are kept. */
+/** Where the usual tools live, after the inherited PATH. Only the ones that exist are kept. */
 export declare const SYSTEM_DIRS: readonly string[];
 export interface ServicePathOptions {
-    /** Injected for tests: "is this an existing directory?". */
+    /** Injected for tests: is this an existing folder? */
     exists?: (p: string) => boolean;
-    /** Injected for tests: the system directories to append. */
+    /** Injected for tests: the system folders to add. */
     systemDirs?: readonly string[];
 }
-/**
- * The job's PATH: Node's bin directory, then the usable part of `inherited`,
- * then the system directories. De-duplicated, order preserved.
- */
+/** Node's bin folder, then what's worth keeping of `inherited`, then the system folders; no duplicates. */
 export declare function servicePath(nodeBin: string, inherited: string | undefined, opts?: ServicePathOptions): string;
-/** `which`: the first executable called `name` on `pathVar`, or undefined. */
+/** The first executable called `name` on `pathVar`. */
 export declare function which(name: string, pathVar: string, isExec?: (p: string) => boolean): string | undefined;
-/**
- * Of `paths`, those that are no longer on disk.
- *
- * This is the check behind `status`'s and (from wave G) `doctor`'s "the Node it
- * runs has gone" warning. It happens under nvm, fnm and volta the moment a Node
- * version is uninstalled: the unit still names an absolute interpreter path,
- * the supervisor still dutifully tries to exec it, and the failure arrives as
- * Paddock being absent with nothing in its own logs — because it never ran.
- */
+/** Those of `paths` that aren't on disk any more: `status` and `doctor` warn about a unit's Node that has gone. */
 export declare function missingPaths(paths: readonly (string | undefined)[], exists?: (p: string) => boolean): string[];

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

@@ -1,52 +1,21 @@
-/**
- * The PATH a generated unit gives the service (SPEC §7).
- *
- * From edspencer/cli-contract — Local Review's `server/service/spec.ts`
- * (`PER_SHELL_PATTERNS`, `SYSTEM_DIRS`, `servicePath`, `which`) @ spec 0.1;
- * local changes: Paddock's own doc comments, `node:path`'s platform-aware
- * `delimiter`/`join` instead of hard-coded `:` and `path.posix`, and a
- * `missingFromPath` helper the CLI uses for its unit warnings. Wave C4 moves
- * this to `reference/service/` and re-syncs.
- *
- * ## Why a unit cannot just inherit the installing shell's PATH
- *
- * Paddock used to record `process.env.PATH` verbatim. That is the PATH of one
- * terminal at one moment, and several of its entries are *per-session*:
- *
- * - **fnm** puts a symlink per terminal under `fnm_multishells/<pid>_<ts>/bin`.
- *   The directory is deleted when that shell exits — and fnm never cleans up
- *   the stale ones, so a unit installed from an fnm shell names a `node`
- *   directory that stops existing the moment the tab closes.
- * - **npx** adds its own per-invocation cache; `npm run` adds `node-gyp-bin`
- *   and the package's `node_modules/.bin`. A long-lived background job has no
- *   business looking in any of them for `git`.
- *
- * So the job's PATH is rebuilt: Node's own bin directory first (so the `node`
- * the unit runs can resolve its neighbours), then whatever of the installing
- * shell's PATH is worth keeping, then the system directories. Entries that are
- * relative, per-shell, or simply not there are dropped — a PATH naming
- * directories that do not exist is how `git` goes missing at some later login,
- * silently, with the symptom appearing in an agent's turn rather than at
- * install time.
- */
-import fs from "node:fs";
-import path from "node:path";
-/** PATH entries that belong to one shell session or one npm invocation. */
+// From edspencer/cli-contract reference/service/path-env.ts @ 0.2; 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.
+//
+// A unit can't just record the shell's PATH: fnm puts a folder per terminal (`fnm_multishells/<pid>_<ts>/bin`) on it
+// that goes when the terminal closes, and npx and `npm run` add their own. A unit naming those loses `node` or `git`
+// at some later login, with the symptom showing up far from the cause.
+import fs from 'node:fs';
+import path from 'node:path';
+/** Entries that belong to one shell or one npm run. */
 export const PER_SHELL_PATTERNS = [
-    /[/\\]fnm_multishells[/\\]/, // fnm: a symlink per terminal, never cleaned up
-    /[/\\]_npx[/\\]/, // npx's per-invocation package cache
-    /[/\\]node-gyp-bin$/, // added by `npm run` for the script it is running
-    /[/\\]node_modules[/\\]\.bin$/, // likewise (and by npx): a package's tools, not the user's
-];
-/** Where the usual tools live, after the inherited PATH. Only existing ones are kept. */
-export const SYSTEM_DIRS = [
-    "/opt/homebrew/bin",
-    "/usr/local/bin",
-    "/usr/bin",
-    "/bin",
-    "/usr/sbin",
-    "/sbin",
+    /[/\\]fnm_multishells[/\\]/, // fnm: a folder per terminal, never cleaned up
+    /[/\\]_npx[/\\]/, // npx's cache
+    /[/\\]node-gyp-bin$/, // added by `npm run`
+    /[/\\]node_modules[/\\]\.bin$/, // a package's own tools, added by `npm run` and npx
 ];
+/** Where the usual tools live, after the inherited PATH. Only the ones that exist are kept. */
+export const SYSTEM_DIRS = ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin'];
 function isDir(p) {
     try {
         return fs.statSync(p).isDirectory();
@@ -66,55 +35,35 @@ function isExecutableFile(p) {
         return false;
     }
 }
-/** Kept on the job's PATH: non-empty, absolute, not per-shell, and an existing directory. */
-function keep(dir, exists) {
-    if (dir === "" || !path.isAbsolute(dir))
-        return false;
-    if (PER_SHELL_PATTERNS.some((re) => re.test(dir) || re.test(`${dir}${path.sep}`)))
-        return false;
-    return exists(dir);
-}
-/**
- * The job's PATH: Node's bin directory, then the usable part of `inherited`,
- * then the system directories. De-duplicated, order preserved.
- */
+/** Node's bin folder, then what's worth keeping of `inherited`, then the system folders; no duplicates. */
 export function servicePath(nodeBin, inherited, opts = {}) {
     const exists = opts.exists ?? isDir;
-    const system = opts.systemDirs ?? SYSTEM_DIRS;
     const out = [];
     const add = (d) => {
-        // Trailing separators would make `/usr/bin/` and `/usr/bin` two entries.
-        const clean = d.length > 1 ? d.replace(/[/\\]+$/, "") : d;
-        if (!out.includes(clean) && keep(clean, exists))
+        const clean = d.length > 1 ? d.replace(/[/\\]+$/, '') : d;
+        if (clean === '' || !path.isAbsolute(clean) || out.includes(clean))
+            return;
+        if (PER_SHELL_PATTERNS.some((re) => re.test(clean) || re.test(`${clean}${path.sep}`)))
+            return;
+        if (exists(clean))
             out.push(clean);
     };
     add(nodeBin);
-    for (const d of (inherited ?? "").split(path.delimiter))
+    for (const d of (inherited ?? '').split(path.delimiter))
         add(d);
-    for (const d of system)
+    for (const d of opts.systemDirs ?? SYSTEM_DIRS)
         add(d);
     return out.join(path.delimiter);
 }
-/** `which`: the first executable called `name` on `pathVar`, or undefined. */
+/** The first executable called `name` on `pathVar`. */
 export function which(name, pathVar, isExec = isExecutableFile) {
     for (const dir of pathVar.split(path.delimiter)) {
-        if (dir === "")
-            continue;
-        const p = path.join(dir, name);
-        if (isExec(p))
-            return p;
+        if (dir !== '' && isExec(path.join(dir, name)))
+            return path.join(dir, name);
     }
     return undefined;
 }
-/**
- * Of `paths`, those that are no longer on disk.
- *
- * This is the check behind `status`'s and (from wave G) `doctor`'s "the Node it
- * runs has gone" warning. It happens under nvm, fnm and volta the moment a Node
- * version is uninstalled: the unit still names an absolute interpreter path,
- * the supervisor still dutifully tries to exec it, and the failure arrives as
- * Paddock being absent with nothing in its own logs — because it never ran.
- */
+/** Those of `paths` that aren't on disk any more: `status` and `doctor` warn about a unit's Node that has gone. */
 export function missingPaths(paths, exists = (p) => fs.existsSync(p)) {
-    return paths.filter((p) => p !== undefined && p !== "" && !exists(p));
+    return paths.filter((p) => p !== undefined && p !== '' && !exists(p));
 }

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

@@ -81,3 +81,33 @@ export declare const READY_TIMEOUT_LABEL = "20 seconds";
  * would park here well past `timeoutMs`.
  */
 export declare function waitForReady(opts: ReadyOptions): Promise<Readiness>;
+/** What {@link waitForVersion} concluded (CLI contract SPEC §5 step 12). */
+export type VersionVerdict = {
+    state: "ok";
+    version: string;
+}
+/** Something answers, and it is not the version we were waiting for. */
+ | {
+    state: "wrong-version";
+    version: string;
+} | {
+    state: "no-answer";
+};
+/**
+ * Poll until `/api/health` reports exactly `version` (SPEC §5 step 12).
+ *
+ * The version is the point, and it is what makes `update`'s health check mean
+ * something. "The URL answers" is satisfied by the OLD server that has not
+ * finished shutting down, by a sibling instance on the same port, and by a
+ * supervisor that restarted the old unit because the new one crashed — all
+ * three of which are exactly the failures step 13's rollback exists for. An
+ * update that polled for a 200 would call every one of them a success.
+ *
+ * The distinction between "no answer" and "the wrong version answers" is kept
+ * because the two read completely differently in a failure report: one is a
+ * server that did not come up, the other is a server that came up as something
+ * else.
+ */
+export declare function waitForVersion(opts: ReadyOptions & {
+    version: string;
+}): Promise<VersionVerdict>;

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

@@ -99,3 +99,38 @@ export async function waitForReady(opts) {
         await sleep(intervalMs);
     }
 }
+/**
+ * Poll until `/api/health` reports exactly `version` (SPEC §5 step 12).
+ *
+ * The version is the point, and it is what makes `update`'s health check mean
+ * something. "The URL answers" is satisfied by the OLD server that has not
+ * finished shutting down, by a sibling instance on the same port, and by a
+ * supervisor that restarted the old unit because the new one crashed — all
+ * three of which are exactly the failures step 13's rollback exists for. An
+ * update that polled for a 200 would call every one of them a success.
+ *
+ * The distinction between "no answer" and "the wrong version answers" is kept
+ * because the two read completely differently in a failure report: one is a
+ * server that did not come up, the other is a server that came up as something
+ * else.
+ */
+export async function waitForVersion(opts) {
+    const { url, version, timeoutMs = READY_TIMEOUT_MS, intervalMs = DEFAULT_INTERVAL_MS, fetchImpl = fetch, now = () => Date.now(), sleep = (ms) => new Promise((r) => setTimeout(r, ms)), } = opts;
+    const deadline = now() + timeoutMs;
+    let last;
+    for (;;) {
+        const health = await fetchHealth(url, {
+            fetchImpl,
+            timeoutMs: Math.max(250, Math.min(2_000, deadline - now())),
+        });
+        if (health?.version !== undefined) {
+            if (health.version === version)
+                return { state: "ok", version };
+            last = health.version;
+        }
+        if (deadline - now() <= 0) {
+            return last !== undefined ? { state: "wrong-version", version: last } : { state: "no-answer" };
+        }
+        await sleep(intervalMs);
+    }
+}

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

@@ -1,3 +1,4 @@
+import type { ServiceIdentity, ServiceSpec } from "./manager.js";
 /**
  * Reverse-DNS on macOS, plain on Linux. Both are stable identifiers a user may
  * end up typing (`launchctl print gui/501/net.edspencer.paddock`,
@@ -6,41 +7,13 @@
  */
 export declare const LAUNCHD_LABEL = "net.edspencer.paddock";
 export declare const SYSTEMD_UNIT = "paddock.service";
+/** Who the reference's launchd and systemd writers are writing for. */
+export declare const PADDOCK_SERVICE: ServiceIdentity;
 /** Default port, matching the server's own (#741). Kept here so the generated
  * unit can name a port even when the user passed no flag — a unit that relies
  * on a default is a unit whose port changes under it on upgrade. */
 export declare const DEFAULT_PORT = "7233";
-export interface ServiceSpec {
-    /** Absolute path to the `node` that will run us — `process.execPath`. */
-    nodePath: string;
-    /**
-     * Absolute path to `dist/cli/paddock.js`.
-     *
-     * NOT the `bin` shim. npm installs a bin as a symlink whose `#!/usr/bin/env
-     * node` shebang has to find `node` on PATH, and launchd's PATH is a stub —
-     * under a version manager there is no `node` on it at all. Invoking the
-     * interpreter explicitly removes the lookup entirely.
-     */
-    scriptPath: string;
-    /** Arguments after the script: always starts with the `serve` verb. */
-    args: string[];
-    /** A directory the service can sit in that it certainly owns. */
-    workingDirectory: string;
-    /**
-     * The one file both streams append to, on every OS (SPEC §7).
-     *
-     * launchd names it twice (`StandardOutPath` and `StandardErrorPath`); systemd
-     * names it twice as well (`StandardOutput=append:` / `StandardError=append:`)
-     * rather than using the journal. That is what makes `paddock service logs`
-     * one Node implementation instead of two, and it is also what makes the
-     * Linux logs survive a journal that is volatile or rate-limited — the default
-     * on plenty of distributions, where `journalctl --user` after a reboot showed
-     * nothing at all.
-     */
-    logPath: string;
-    /** PATH for the service: Node's bin, the usable inherited entries, the system dirs. */
-    pathEnv: string;
-}
+export type { ServiceSpec } from "./manager.js";
 export interface SpecInput {
     nodePath: string;
     scriptPath: string;

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

@@ -19,6 +19,15 @@ import { servicePath } from "./path-env.js";
  */
 export const LAUNCHD_LABEL = "net.edspencer.paddock";
 export const SYSTEMD_UNIT = "paddock.service";
+/** Who the reference's launchd and systemd writers are writing for. */
+export const PADDOCK_SERVICE = {
+    name: "Paddock",
+    tool: "paddock",
+    label: LAUNCHD_LABEL,
+    unit: SYSTEMD_UNIT,
+    description: "Paddock — persistent, resumable Claude Code sessions, by project",
+    documentation: "https://paddock.edspencer.net",
+};
 /** Default port, matching the server's own (#741). Kept here so the generated
  * unit can name a port even when the user passed no flag — a unit that relies
  * on a default is a unit whose port changes under it on upgrade. */