@edspencer/paddock 0.79.1 → 0.80.0

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

@@ -0,0 +1,115 @@
+/**
+ * `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). */
+export const DEFAULT_LOG_LINES = 50;
+/** How much of the end of the file to read for a tail, in bytes. */
+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.
+ */
+export function tailFile(file, lines) {
+    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] === "")
+            all.pop();
+        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.
+ */
+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));
+        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`.
+            offset = 0;
+        }
+        if (size === offset)
+            continue;
+        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"));
+            offset = size;
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+}
+/** The file's size, or 0 if it is not there — where a follow should start. */
+export function sizeOf(file) {
+    try {
+        return fs.statSync(file).size;
+    }
+    catch {
+        return 0;
+    }
+}

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

@@ -0,0 +1,27 @@
+/** PATH entries that belong to one shell session or one npm invocation. */
+export declare const PER_SHELL_PATTERNS: readonly RegExp[];
+/** Where the usual tools live, after the inherited PATH. Only existing ones are kept. */
+export declare const SYSTEM_DIRS: readonly string[];
+export interface ServicePathOptions {
+    /** Injected for tests: "is this an existing directory?". */
+    exists?: (p: string) => boolean;
+    /** Injected for tests: the system directories to append. */
+    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.
+ */
+export declare function servicePath(nodeBin: string, inherited: string | undefined, opts?: ServicePathOptions): string;
+/** `which`: the first executable called `name` on `pathVar`, or undefined. */
+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.
+ */
+export declare function missingPaths(paths: readonly (string | undefined)[], exists?: (p: string) => boolean): string[];

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

@@ -0,0 +1,120 @@
+/**
+ * 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. */
+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",
+];
+function isDir(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function isExecutableFile(p) {
+    try {
+        if (!fs.statSync(p).isFile())
+            return false;
+        fs.accessSync(p, fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        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.
+ */
+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))
+            out.push(clean);
+    };
+    add(nodeBin);
+    for (const d of (inherited ?? "").split(path.delimiter))
+        add(d);
+    for (const d of system)
+        add(d);
+    return out.join(path.delimiter);
+}
+/** `which`: the first executable called `name` on `pathVar`, or undefined. */
+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;
+    }
+    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.
+ */
+export function missingPaths(paths, exists = (p) => fs.existsSync(p)) {
+    return paths.filter((p) => p !== undefined && p !== "" && !exists(p));
+}

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

@@ -23,6 +23,28 @@
  */
 /** Where the poll got to when it stopped. */
 export type Readiness = "ready" | "timeout";
+/** What `/api/health` said, when it said anything (SPEC §8). */
+export interface HealthAnswer {
+    ok: boolean;
+    /** The version the RUNNING server reports. Absent from a pre-contract Paddock. */
+    version?: string;
+}
+/**
+ * Ask `<url>/api/health` once, and say what it answered.
+ *
+ * Distinct from {@link waitForReady}, which only needs a boolean and polls for
+ * it. `status` needs the body: the version in it is the only way to tell a
+ * server that is running the installed Paddock from one that has been up since
+ * before an upgrade — the single most confusing state a service can be in, and
+ * invisible from the outside until something reports both numbers.
+ *
+ * `undefined` means nothing answered. That is a real answer (exit 3), not an
+ * error, so nothing is thrown.
+ */
+export declare function fetchHealth(url: string, opts?: {
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<HealthAnswer | undefined>;
 export interface ReadyOptions {
     /** Base URL of the server, e.g. `http://127.0.0.1:7233` — no trailing slash. */
     url: string;

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

@@ -21,6 +21,36 @@
  * same claim as "it failed". Callers print it as a caveat, not an error, and
  * point at the logs.
  */
+/**
+ * Ask `<url>/api/health` once, and say what it answered.
+ *
+ * Distinct from {@link waitForReady}, which only needs a boolean and polls for
+ * it. `status` needs the body: the version in it is the only way to tell a
+ * server that is running the installed Paddock from one that has been up since
+ * before an upgrade — the single most confusing state a service can be in, and
+ * invisible from the outside until something reports both numbers.
+ *
+ * `undefined` means nothing answered. That is a real answer (exit 3), not an
+ * error, so nothing is thrown.
+ */
+export async function fetchHealth(url, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    try {
+        const res = await fetchImpl(`${url}/api/health`, {
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 2_000),
+        });
+        if (!res.ok)
+            return undefined;
+        const body = (await res.json());
+        return {
+            ok: body.ok === true,
+            ...(typeof body.version === "string" ? { version: body.version } : {}),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * How long to wait before saying "could not confirm".
  *

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

@@ -22,14 +22,23 @@ export interface ServiceSpec {
      * interpreter explicitly removes the lookup entirely.
      */
     scriptPath: string;
-    /** Arguments after the script: always starts with the `start` verb. */
+    /** 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;
-    /** Where stdout/stderr go on launchd. systemd uses journald and ignores these. */
-    stdoutPath: string;
-    stderrPath: string;
-    /** PATH for the service, captured at install time. */
+    /**
+     * 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 interface SpecInput {
@@ -44,6 +53,19 @@ export interface SpecInput {
     dataDirArg?: string;
     verbose?: boolean;
     pathEnv?: string;
+    /**
+     * Injected by tests: "is this an existing directory?", and which system
+     * directories to append.
+     *
+     * Not a knob — a necessity. `servicePath` keeps only directories that EXIST,
+     * which is what stops a unit naming a `node` that went away with a terminal
+     * (path-env.ts). That makes the rendered unit depend on the filesystem it was
+     * rendered on, so a golden plist asserted on this box would differ from the
+     * same golden on a macOS runner, for reasons that have nothing to do with the
+     * code under test. Pinning both makes the goldens about the renderer again.
+     */
+    pathExists?: (p: string) => boolean;
+    systemDirs?: readonly string[];
 }
 /**
  * The service's own directory inside the data dir.
@@ -58,14 +80,31 @@ export interface SpecInput {
  * subdirectory is neither.
  */
 export declare function serviceDir(dataDir: string): string;
+/**
+ * Where the service's log lives: `<dataDir>/logs/service.log` (SPEC §7).
+ *
+ * One file, both streams, every platform — so `paddock service logs` is one
+ * implementation and the answer to "where are the logs" is one path. It is NOT
+ * under {@link serviceDir}: the logs outlive any one install (`uninstall` keeps
+ * them deliberately), and the server rotates this file itself
+ * (`service-log.ts`), which means something other than the service CLI has to
+ * be able to name it from the data dir alone.
+ */
+export declare function logsDir(dataDir: string): string;
+/** The single log file both streams append to. */
+export declare function serviceLogPath(dataDir: string): string;
 /** The data dir the service will use, resolved the same way `paddock.ts` does. */
 export declare function defaultDataDir(homeDir?: string): string;
 /**
  * Assemble the spec.
  *
- * The argument vector leads with the `start` verb even though bare `paddock`
+ * The argument vector leads with the `serve` verb even though bare `paddock`
  * would do the same thing. It costs nothing and it is the difference between
  * `launchctl print` showing an argv you can read and one you have to recognise.
+ * It was `start` until the CLI contract made `serve` the name for running in
+ * the foreground (SPEC §1); `start` is a permanent alias, so a unit written by
+ * an older Paddock keeps working untouched and only gets `serve` when something
+ * rewrites it.
  *
  * `--data-dir` is forwarded ONLY when the user passed it. The default of
  * setting nothing is load-bearing: with no data dir named anywhere, the service

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

@@ -10,6 +10,7 @@
  */
 import os from "node:os";
 import path from "node:path";
+import { servicePath } from "./path-env.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`,
@@ -37,6 +38,23 @@ export const DEFAULT_PORT = "7233";
 export function serviceDir(dataDir) {
     return path.join(dataDir, "service");
 }
+/**
+ * Where the service's log lives: `<dataDir>/logs/service.log` (SPEC §7).
+ *
+ * One file, both streams, every platform — so `paddock service logs` is one
+ * implementation and the answer to "where are the logs" is one path. It is NOT
+ * under {@link serviceDir}: the logs outlive any one install (`uninstall` keeps
+ * them deliberately), and the server rotates this file itself
+ * (`service-log.ts`), which means something other than the service CLI has to
+ * be able to name it from the data dir alone.
+ */
+export function logsDir(dataDir) {
+    return path.join(dataDir, "logs");
+}
+/** The single log file both streams append to. */
+export function serviceLogPath(dataDir) {
+    return path.join(logsDir(dataDir), "service.log");
+}
 /** The data dir the service will use, resolved the same way `paddock.ts` does. */
 export function defaultDataDir(homeDir = os.homedir()) {
     return path.join(homeDir, ".paddock");
@@ -44,9 +62,13 @@ export function defaultDataDir(homeDir = os.homedir()) {
 /**
  * Assemble the spec.
  *
- * The argument vector leads with the `start` verb even though bare `paddock`
+ * The argument vector leads with the `serve` verb even though bare `paddock`
  * would do the same thing. It costs nothing and it is the difference between
  * `launchctl print` showing an argv you can read and one you have to recognise.
+ * It was `start` until the CLI contract made `serve` the name for running in
+ * the foreground (SPEC §1); `start` is a permanent alias, so a unit written by
+ * an older Paddock keeps working untouched and only gets `serve` when something
+ * rewrites it.
  *
  * `--data-dir` is forwarded ONLY when the user passed it. The default of
  * setting nothing is load-bearing: with no data dir named anywhere, the service
@@ -58,7 +80,7 @@ export function defaultDataDir(homeDir = os.homedir()) {
  * service opening a browser tab at login is not a feature.
  */
 export function buildSpec(input) {
-    const args = ["start"];
+    const args = ["serve"];
     if (input.port !== undefined)
         args.push("--port", input.port);
     if (input.host !== undefined)
@@ -67,15 +89,20 @@ export function buildSpec(input) {
         args.push("--data-dir", input.dataDirArg);
     if (input.verbose === true)
         args.push("--verbose");
-    const dir = serviceDir(input.dataDir);
     return {
         nodePath: input.nodePath,
         scriptPath: input.scriptPath,
         args,
-        workingDirectory: dir,
-        stdoutPath: path.join(dir, "paddock.log"),
-        stderrPath: path.join(dir, "paddock.error.log"),
-        pathEnv: input.pathEnv ?? "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
+        workingDirectory: serviceDir(input.dataDir),
+        logPath: serviceLogPath(input.dataDir),
+        // Node's own bin directory leads, so the interpreter the unit names can
+        // find its neighbours; `servicePath` drops the installing shell's
+        // per-session entries. See path-env.ts for why inheriting PATH verbatim
+        // writes a unit that rots when a terminal closes.
+        pathEnv: servicePath(path.dirname(input.nodePath), input.pathEnv, {
+            ...(input.pathExists !== undefined ? { exists: input.pathExists } : {}),
+            ...(input.systemDirs !== undefined ? { systemDirs: input.systemDirs } : {}),
+        }),
     };
 }
 /**

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

@@ -1,5 +1,5 @@
 import { type ServiceSpec } from "./spec.js";
-import type { Runner, ServiceBackend } from "./backend.js";
+import type { RunResult, Runner, ServiceBackend } from "./backend.js";
 /**
  * `~/.config/systemd/user/paddock.service`, honouring `XDG_CONFIG_HOME`.
  *
@@ -28,6 +28,17 @@ import type { Runner, ServiceBackend } from "./backend.js";
  * caller with no opinion still gets the right answer.)
  */
 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 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.
+ */
+export declare function execWords(line: string): string[];
 /**
  * Render the unit.
  *
@@ -47,11 +58,32 @@ export declare function unitPath(homeDir?: string, xdgConfigHome?: string): stri
  * "start at login" for a user unit; `multi-user.target` is the system-unit
  * spelling and does nothing here.
  *
- * No `StandardOutput=` — a user unit's output goes to the journal, which is
- * where a Linux user will look, and duplicating it into a file would give two
- * answers to "where are the logs".
+ * ## Logs go to a file, not the journal (SPEC §7)
+ *
+ * `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.
  */
 export declare function renderUnit(spec: ServiceSpec): string;
+/** The log file an installed unit appends to, or undefined if it names none. */
+export declare function parseUnitLogPath(text: string): string | undefined;
 /**
  * Does an installed unit carry `Restart=always` (#872)?
  *
@@ -64,4 +96,15 @@ export declare function renderUnit(spec: ServiceSpec): string;
 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;