@edspencer/paddock 0.82.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/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. */

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

@@ -1,110 +1,36 @@
-import { type ServiceSpec } from "./spec.js";
-import type { RunResult, Runner, ServiceBackend } from "./backend.js";
+import type { Runner, RunResult, ServiceIdentity, ServiceManager, ServiceSpec } from './manager.js';
 /**
- * `~/.config/systemd/user/paddock.service`, honouring `XDG_CONFIG_HOME`.
- *
- * ## An injected home outranks the ambient variable
- *
- * The precedence is: an explicit `xdgConfigHome` argument, then an explicitly
- * **injected** `homeDir`, then — only when the caller named neither — the real
- * environment. That middle rung is the whole point, and getting it wrong was a
- * live bug rather than a style question.
- *
- * The first version read `process.env.XDG_CONFIG_HOME` before falling back to
- * `homeDir`. On any machine with that variable set — CI, and plenty of Linux
- * desktops — the `homeDir` parameter was therefore **a lie**: a caller passing a
- * throwaway directory still resolved to the real config home. Two things
- * followed. Test isolation quietly stopped working, so which assertion passed
- * depended on test ORDER rather than test content. And the suite wrote a real
- * `paddock.service` into the runner's actual config directory, outside every
- * temp dir it thought it was confined to — which on a contributor's machine
- * would have installed a unit they never asked for.
- *
- * So: passing a home is a statement about where home is, and it wins. The
- * ambient read survives only on the branch where nobody said otherwise, which
- * is the real-use branch and the one where honouring `XDG_CONFIG_HOME` is
- * correct. (`paddock.ts` threads the variable in explicitly as well, so the
- * production path does not depend on this fallback — it is here so that a
- * caller with no opinion still gets the right answer.)
+ * `${XDG_CONFIG_HOME:-~/.config}/systemd/user/<unit>`. A home passed in beats the ambient `XDG_CONFIG_HOME`: a test
+ * that names a throwaway home must not write a unit into the real config folder because the variable was set.
  */
-export declare function unitPath(homeDir?: string, xdgConfigHome?: string): string;
-/** One `ExecStart` word: specifiers and variables escaped, quoted when it has to be. */
+export declare function unitPath(id: Pick<ServiceIdentity, 'unit'>, homeDir?: string, xdgConfigHome?: string): string;
+/** One `ExecStart` word: specifiers and variables escaped, and quoted when it has to be. */
 export declare function execWord(a: string): string;
-/**
- * The other way: the words of an `ExecStart` line.
- *
- * Reads both shapes on purpose. A unit written before #796's quoting is a bare
- * whitespace-separated line, and its owner is exactly the person whose `status`
- * has to keep working — so unquoted words pass through unchanged, and quoted
- * ones are unescaped.
- */
+/** The words of an `ExecStart` line. Reads unquoted words too, so an older unit's `status` still works. */
 export declare function execWords(line: string): string[];
 /**
- * Render the unit.
- *
- * `Restart=always`, matching launchd's `KeepAlive=<true/>` (#872). It was
- * `on-failure`, which for a service is the wrong default for the same reason it
- * was wrong there: `start.ts` exits `0` on SIGTERM, so a logout — or anything
- * else that signals the user manager — was read as an intended stop and Paddock
- * stayed down.
- *
- * `always` does not make the unit unstoppable. systemd never restarts a unit it
- * was itself asked to stop, so `systemctl --user stop` (and therefore
- * `uninstall`) remains the clean, explicit way to put it down. That is the
- * difference between an exit code, which has to guess at intent, and a command,
- * which carries it.
- *
- * `WantedBy=default.target` is what makes `systemctl --user enable` mean
- * "start at login" for a user unit; `multi-user.target` is the system-unit
- * spelling and does nothing here.
- *
- * ## Logs go to a file, not the journal (SPEC §7)
+ * The unit.
  *
- * `StandardOutput=append:` / `StandardError=append:` name one file, the same
- * one launchd's two keys name. The journal was the obvious choice and the wrong
- * one for three reasons: `journalctl --user` shows nothing at all on a distro
- * whose journal is volatile (the output is gone after a reboot, which is
- * exactly when someone looks); it makes "where are the logs" have a different
- * answer on each platform, so `paddock service logs` would be two
- * implementations; and it rules out Windows, which the contract requires
- * nothing rule out.
- *
- * The directory has to exist first — systemd creates the file, not its parent —
- * which `install` below does.
- *
- * ## Every ExecStart word is quoted
- *
- * `%` starts a specifier anywhere in a unit file and `$` starts a variable in
- * `ExecStart`, so both are escaped; a word containing whitespace, a quote or a
- * backslash is quoted. Paths with a space in them are the common case
- * (`/Users/Ed Spencer/.paddock`), and the old unqualified `join(" ")` wrote a
- * unit systemd then split into the wrong arguments — a service that fails at
- * login having printed nothing.
+ * - `Restart=always`, matching launchd's `KeepAlive`: a server exits 0 on SIGTERM, so `on-failure` would leave it
+ *   down after a logout signals the user's manager. systemd never restarts a unit it was asked to stop.
+ * - Both streams `append:` to one file rather than the journal, which is volatile on many distributions and would
+ *   make `logs` a different program on each OS. systemd creates the file, not its folder, so `install` makes that.
+ * - Every `ExecStart` word is escaped and quoted where needed: paths with spaces are common (`/Users/Ed Spencer/…`).
  */
-export declare function renderUnit(spec: ServiceSpec): string;
-/** The log file an installed unit appends to, or undefined if it names none. */
+export declare function renderUnit(id: ServiceIdentity, spec: ServiceSpec): string;
+/** `ExecStart=`, read back as an argv. */
+export declare function parseUnitArgv(text: string): string[];
+/** The log the unit appends to, if it names one. */
 export declare function parseUnitLogPath(text: string): string | undefined;
-/**
- * Does an installed unit carry `Restart=always` (#872)?
- *
- * The counterpart to `plistKeepsAlive`, and narrow for the same reason: the
- * value it has to reject is the `on-failure` this file used to write, which
- * leaves Paddock down after the graceful exit `start.ts` performs on SIGTERM.
- * Anything unrecognised reads as "not the fixed shape", which at worst tells a
- * hand-edited unit's owner to re-run install.
- */
+/** Whether the unit has `Restart=always` (the older `on-failure` doesn't count). */
 export declare function unitKeepsAlive(text: string): boolean;
-/** Read `ExecStart=` back out of an installed unit, split into an argv. */
-export declare function parseUnitArgv(text: string): string[];
-/**
- * What a `systemctl` failure means, in the manager's own words where it has any.
- *
- * The `status === null` branch is the one QA found: `spawnSync` reports a
- * missing binary that way, with no output at all, so the message was
- * `systemctl --user enable --now failed (exit null).` and then a blank line —
- * which tells someone on a container with no systemd nothing whatsoever. That
- * is also the single likeliest way this command fails on a machine it was never
- * going to work on.
- */
-export declare function systemctlFailure(args: string[], r: RunResult): string;
-export declare function createSystemdBackend(run: Runner, homeDir?: string, xdgConfigHome?: string): ServiceBackend;
+/** What a `systemctl` failure means, in the manager's words where it has any. */
+export declare function systemctlFailure(id: Pick<ServiceIdentity, 'name' | 'tool'>, args: string[], r: RunResult): string;
+export interface SystemdOptions {
+    run: Runner;
+    homeDir?: string;
+    xdgConfigHome?: string;
+    /** Injected for tests: whose linger to ask about. */
+    user?: string;
+}
+export declare function createSystemd(id: ServiceIdentity, o: SystemdOptions): ServiceManager;