@edspencer/paddock 0.82.0 → 0.83.0

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

@@ -1,39 +1,20 @@
-/** How many lines `logs` prints when nobody says otherwise (SPEC §1). */
+/** How many lines `logs` prints when nobody says (SPEC §1). */
 export declare const DEFAULT_LOG_LINES = 50;
-/**
- * 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 declare function tailFile(file: string, lines: number): string;
 export interface FollowOptions {
-    /** Where to start reading from — normally the file's size after the tail. */
+    /** Where to start: the file's size after the tail. */
     from: number;
-    /** Injected for tests. */
     intervalMs?: number;
-    /** Injected for tests: return false to stop the loop. */
+    /** Return false to stop. */
     keepGoing?: () => boolean;
     write?: (s: string) => void;
 }
 /**
- * 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 declare function followFile(file: string, opts: FollowOptions): Promise<void>;
-/** The file's size, or 0 if it is not there — where a follow should start. */
+export declare function followFile(file: string, o: FollowOptions): Promise<void>;
+/** The file's size, or 0 if it isn't there: where a follow starts. */
 export declare function sizeOf(file: string): number;

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

@@ -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/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;