@edspencer/paddock 0.81.0 → 0.82.0

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

@@ -1,6 +1,7 @@
 import { type CliOptions, type ServiceAction } from "../args.js";
 import { isNpxPath, serviceDir, type ServiceSpec } from "./spec.js";
 import { type Runner } from "./backend.js";
+import { type UpdateSummary } from "../update/update-check.js";
 import { type HealthAnswer, type Readiness } from "./ready.js";
 export interface ServiceContext {
     /** `process.platform`. */
@@ -84,6 +85,22 @@ export interface StatusReport {
     cli: string | null;
     /** Linux only: null where the platform has no such concept. */
     linger: boolean | null;
+    /**
+     * What the last `update --check` found, from `<data-dir>/update-check.json`
+     * (SPEC §3).
+     *
+     * `status` never asks the registry itself — the contract is explicit that
+     * nothing contacts it by itself, and a status command run by a monitoring
+     * loop would be exactly the background check §3 forbids. So this repeats a
+     * file somebody's `update --check` or `doctor` wrote.
+     *
+     * **Absent, not null, when there is nothing to repeat.** The contract's
+     * `schemas/service-status.schema.json` types this key as an OBJECT, so a
+     * `null` fails the schema and the conformance runner says so — which is how
+     * this was found. The other optional fields here are `| null` because the
+     * schema types THOSE as nullable; this one it does not.
+     */
+    update?: UpdateSummary;
     /** A stale unit, a missing Node — things that are wrong but not fatal. */
     warnings: string[];
 }
@@ -94,6 +111,41 @@ export interface StatusReport {
  * never `process.exit()`, which truncates piped output mid-write.
  */
 export declare function runService(action: ServiceAction, opts: CliOptions, ctx: ServiceContext): Promise<number>;
+/**
+ * What `paddock update` needs to know and do about the service (SPEC §5).
+ *
+ * Built here rather than in the update module so that everything which reads a
+ * unit file stays in one place: `update` gets the same answer `status` and
+ * `logs` get, from the same backend, including the #824 rule that the instance
+ * in question is the one the UNIT describes and not whatever `--data-dir` the
+ * invocation carries.
+ *
+ * Returns `home` too, which is the data dir `update.lock` and
+ * `update-check.json` go in. It has to be the unit's: the cache's reader is
+ * `service status`, which looks in the unit's data dir, so writing it anywhere
+ * else would be writing a file nothing reads.
+ */
+export declare function updateServiceHooks(ctx: ServiceContext): {
+    hooks: ServiceHooksForUpdate;
+    home: string;
+    installed: boolean;
+};
+/** The shape {@link updateServiceHooks} returns — structurally `UpdateServiceHooks`. */
+export interface ServiceHooksForUpdate {
+    inspect(): {
+        installed: boolean;
+        running: boolean;
+        url?: string;
+        log?: string;
+    };
+    stop(): void;
+    refresh(cliPath: string): {
+        status: number | null;
+        stdout: string;
+        stderr: string;
+    };
+    tail(lines: number): string;
+}
 /** Exported for the entrypoint's context assembly, and for tests. */
 export { serviceDir, isNpxPath };
 export type { ServiceSpec };

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

@@ -33,6 +33,8 @@ import { createLaunchdBackend } from "./launchd.js";
 import { createSystemdBackend } from "./systemd.js";
 import { missingPaths } from "./path-env.js";
 import { DEFAULT_LOG_LINES, followFile, sizeOf, tailFile } from "./logs.js";
+import { readLiveRuntimeFile } from "../../runtime-file.js";
+import { updateSummary } from "../update/update-check.js";
 import { waitForReady, fetchHealth, READY_TIMEOUT_LABEL, } from "./ready.js";
 /**
  * Pick a backend, or explain why there isn't one.
@@ -63,8 +65,52 @@ function resolveDataDir(opts, ctx) {
     }
     return { dataDir: defaultDataDir(ctx.homeDir), explicit: undefined };
 }
-function specFor(opts, ctx) {
-    const { dataDir, explicit } = resolveDataDir(opts, ctx);
+/** The value of a flag in a recorded argument vector, or undefined. */
+function argValue(argv, names) {
+    for (let i = 0; i < argv.length; i++) {
+        if (names.includes(argv[i]) && argv[i + 1] !== undefined)
+            return argv[i + 1];
+    }
+    return undefined;
+}
+/**
+ * The settings an EXISTING unit carries, as if they had been typed
+ * (`service install --refresh`, SPEC §1 and §5 step 11).
+ *
+ * This is what makes a reinstall idempotent rather than a reset. A unit
+ * installed with `--port 9000 --data-dir /srv/paddock` must come back on 9000
+ * pointing at /srv/paddock — and `update` is precisely the caller that has no
+ * way to know those values, because it runs the NEW version's CLI in a shell
+ * that never typed them.
+ *
+ * Flags still win, so `service install --refresh --port 7300` moves the port.
+ * The ENVIRONMENT deliberately does not: `resolveDataDir` normally lets
+ * `PADDOCK_DATA_DIR` stand in for `--data-dir`, which would be wrong here —
+ * the refresh is a faithful re-render of a unit, and inheriting the updating
+ * shell's data dir would silently repoint somebody's service at a different
+ * instance. A unit with no recorded `--data-dir` keeps having none, which is
+ * how it stays the same `~/.paddock` a bare `paddock` reaches.
+ */
+function inherit(opts, state) {
+    const port = argValue(state.argv, ["--port", "-p"]);
+    const host = argValue(state.argv, ["--host"]);
+    const dataDir = argValue(state.argv, ["--data-dir", "-d"]);
+    return {
+        ...opts,
+        ...(opts.port === undefined && port !== undefined ? { port } : {}),
+        ...(opts.host === undefined && host !== undefined ? { host } : {}),
+        ...(opts.dataDir === undefined && dataDir !== undefined ? { dataDir } : {}),
+        verbose: opts.verbose || state.argv.includes("--verbose"),
+    };
+}
+function specFor(opts, ctx, 
+/** Set on a `--refresh`: the data dir comes from the unit, not the environment. */
+fromUnit = false) {
+    const { dataDir, explicit } = fromUnit
+        ? opts.dataDir !== undefined
+            ? { dataDir: path.resolve(opts.dataDir), explicit: path.resolve(opts.dataDir) }
+            : { dataDir: defaultDataDir(ctx.homeDir), explicit: undefined }
+        : resolveDataDir(opts, ctx);
     const spec = buildSpec({
         nodePath: ctx.nodePath,
         scriptPath: ctx.scriptPath,
@@ -136,8 +182,27 @@ function lingerNote(linger) {
 async function install(opts, ctx, backend) {
     if (isNpxPath(ctx.packageRoot))
         throw new CliError(NPX_REFUSAL);
-    const { spec, dataDir } = specFor(opts, ctx);
+    // `--refresh` (SPEC §5 step 11): re-render an EXISTING unit, keeping what it
+    // records. With nothing installed there is nothing to refresh — exit 4, the
+    // same code every other command that needs a unit returns, rather than
+    // quietly performing a first install from defaults. That distinction is the
+    // whole reason the flag exists: `update` runs this through the new version's
+    // CLI, and a silent fallback would move a `--port 9000` service to 7233 on
+    // the one run nobody is watching.
+    const refreshing = opts.refresh === true;
+    let existing;
+    if (refreshing) {
+        existing = backend.status();
+        if (!existing.registered) {
+            console.log(notInstalled(backend));
+            return EXIT.notInstalled;
+        }
+    }
+    const { spec, dataDir } = specFor(existing !== undefined ? inherit(opts, existing) : opts, ctx, refreshing);
     const url = `http://${hostFromArgv(spec.args)}:${portFromArgv(spec.args)}`;
+    if (refreshing) {
+        console.log(`\n  Re-writing ${backend.unitPath}\n  Keeping: paddock ${spec.args.join(" ")}`);
+    }
     console.log(installProgress(backend));
     backend.install(spec);
     // The unit is written and the supervisor has accepted it. That is NOT the
@@ -251,6 +316,11 @@ export function installedVersionOf(cliPath) {
         dir = parent;
     }
 }
+/** `{ update }` when there is a recent check to repeat, and `{}` otherwise. */
+function withUpdate(home) {
+    const summary = updateSummary(home);
+    return summary !== undefined ? { update: summary } : {};
+}
 async function buildStatus(ctx, backend) {
     const state = backend.status();
     const base = {
@@ -277,6 +347,7 @@ async function buildStatus(ctx, backend) {
             node: null,
             cli: null,
             linger: lingerValue,
+            ...withUpdate(path.resolve(ctx.envDataDir ?? defaultDataDir(ctx.homeDir))),
             warnings: [],
         };
     }
@@ -318,6 +389,7 @@ async function buildStatus(ctx, backend) {
         node: state.nodePath ?? null,
         cli: state.cliPath ?? null,
         linger: lingerValue,
+        ...withUpdate(dataDir),
         warnings,
     };
 }
@@ -354,6 +426,12 @@ async function status(opts, ctx, backend) {
             "  paddock service install     register it and start it now",
             "",
         ].join("\n"));
+        // The notice belongs here too. Found in QA: it was printed only on the
+        // installed path, so a machine with no service got `update` in `--json`
+        // and silence in the prose — the exact `--json`-disagrees-with-the-text rot
+        // that one StatusReport is supposed to prevent. A newer version is worth
+        // knowing about whether or not a unit exists.
+        noteUpdate(report);
         return EXIT.notInstalled;
     }
     const versions = report.runningVersion !== null && report.runningVersion !== report.installedVersion
@@ -387,8 +465,33 @@ async function status(opts, ctx, backend) {
         ...report.warnings.flatMap((w) => ["", `  ⚠ ${w}`]),
         "",
     ].join("\n"));
+    // The update notice goes to STDERR, and only ever repeats the cache (SPEC
+    // §3). stderr because it is prose about something other than what was asked
+    // for, and because that keeps every byte of stdout under the `--json`
+    // discipline's one rule rather than two.
+    noteUpdate(report);
     return statusExit(report);
 }
+/**
+ * Repeat the cached update answer on stderr, when there is one worth repeating
+ * (SPEC §3).
+ *
+ * Nothing is fetched here. The `Run:` line is the plain `paddock update`
+ * rather than §6's per-install variant, because working that out needs the
+ * install method and the target's tag — and `status` has deliberately not
+ * asked the registry, so it has neither. Anyone whose install cannot update
+ * itself gets the right command from `update --check`, which has.
+ */
+function noteUpdate(report) {
+    const update = report.update;
+    if (update === undefined || !update.updateAvailable)
+        return;
+    console.error("");
+    const have = report.runningVersion ?? report.installedVersion;
+    console.error(`  ${update.latest} is available${have !== null && have !== undefined ? ` (you have ${have})` : ""}.`);
+    console.error("    Run: paddock update");
+    console.error(`    Checked: ${update.checkedAt}`);
+}
 /** The exit code a report means (SPEC §2). */
 function statusExit(report) {
     if (!report.installed)
@@ -589,6 +692,70 @@ export async function runService(action, opts, ctx) {
         return logs(opts, ctx, backend);
     return status(opts, ctx, backend);
 }
+/**
+ * What `paddock update` needs to know and do about the service (SPEC §5).
+ *
+ * Built here rather than in the update module so that everything which reads a
+ * unit file stays in one place: `update` gets the same answer `status` and
+ * `logs` get, from the same backend, including the #824 rule that the instance
+ * in question is the one the UNIT describes and not whatever `--data-dir` the
+ * invocation carries.
+ *
+ * Returns `home` too, which is the data dir `update.lock` and
+ * `update-check.json` go in. It has to be the unit's: the cache's reader is
+ * `service status`, which looks in the unit's data dir, so writing it anywhere
+ * else would be writing a file nothing reads.
+ */
+export function updateServiceHooks(ctx) {
+    const backend = backendFor(ctx);
+    const first = backend.status();
+    const home = first.registered
+        ? dataDirOf(first, ctx)
+        : path.resolve(ctx.envDataDir ?? defaultDataDir(ctx.homeDir));
+    const inspect = () => {
+        const state = backend.status();
+        if (!state.registered) {
+            // No unit. A foreground `paddock serve` is still worth finding, because
+            // SPEC §5's "without a service" path has to be able to say "restart
+            // Paddock to use the new version" — and `runtime.json` is the only honest
+            // way to find it (no guessing at a default port, the busy client's rule).
+            const live = readLiveRuntimeFile(home);
+            return {
+                installed: false,
+                running: live !== null,
+                ...(live !== null ? { url: live.url } : {}),
+            };
+        }
+        return {
+            installed: true,
+            running: state.running,
+            url: urlOf(state),
+            log: logPathOf(state, dataDirOf(state, ctx)),
+        };
+    };
+    return {
+        installed: first.registered,
+        home,
+        hooks: {
+            inspect,
+            stop: () => backend.stop(),
+            // The NEW version's CLI writes the unit (SPEC §5 step 11). Run with the
+            // interpreter we are running, not the bin shim: the shim's shebang has to
+            // find `node` on PATH, and under a version manager there may not be one.
+            refresh: (cliPath) => {
+                const run = ctx.run ?? spawnRunner;
+                return run(process.execPath, [cliPath, "service", "install", "--refresh"]);
+            },
+            tail: (lines) => {
+                const state = backend.status();
+                if (!state.registered)
+                    return "";
+                const file = logPathOf(state, dataDirOf(state, ctx));
+                return fs.existsSync(file) ? tailFile(file, lines) : "";
+            },
+        },
+    };
+}
 /** Exported for the entrypoint's context assembly, and for tests. */
 export { serviceDir, isNpxPath };
 /** Best-effort home dir; `os.homedir()` throws on a machine with no passwd entry. */

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/systemd.js

@@ -224,6 +224,9 @@ export function createSystemdBackend(run, homeDir, xdgConfigHome) {
         unitPath: file,
         label: SYSTEMD_UNIT,
         install(spec) {
+            // Asked BEFORE the unit is overwritten, because the answer decides whether a restart is
+            // needed below and the file is about to stop describing what is running.
+            const wasActive = fs.existsSync(file) && run("systemctl", ["--user", "is-active", SYSTEMD_UNIT]).stdout.trim() === "active";
             fs.mkdirSync(path.dirname(file), { recursive: true });
             fs.mkdirSync(spec.workingDirectory, { recursive: true });
             // systemd creates the log FILE for `append:` but not its directory, and a
@@ -239,6 +242,30 @@ export function createSystemdBackend(run, homeDir, xdgConfigHome) {
             const enabled = run("systemctl", args);
             if (enabled.status !== 0)
                 throw new Error(systemctlFailure(args, enabled));
+            // And then RESTART, but only if it was ALREADY active, because `enable --now` does nothing
+            // to a unit that is already running — systemd starts it only if it is stopped. So a
+            // reinstall over a running service wrote a new unit, left the old process serving, and
+            // reported success.
+            //
+            // That is not a theoretical gap: it is the one `paddock update`'s ROLLBACK walks into. The
+            // forward path stops the service first (SPEC §5 step 9), so `enable --now` starts the new
+            // version cleanly; the rollback runs `service install --refresh` while the FAILED version
+            // is still up, and without this the "restored" service was the broken one — which turns a
+            // clean exit 6 into an exit 7 and a machine nobody has fixed.
+            //
+            // Conditional rather than unconditional, even though `restart` would converge both states
+            // in one call: on a stopped unit that would be TWO starts milliseconds apart, and systemd's
+            // default start limit is five in ten seconds. Halving the headroom of a unit whose whole
+            // job is to come back is not worth saving a question.
+            //
+            // launchd needs no equivalent — its install is a bootout followed by a bootstrap, which
+            // already replaces a running job.
+            if (wasActive) {
+                const restartArgs = ["--user", "restart", SYSTEMD_UNIT];
+                const restarted = run("systemctl", restartArgs);
+                if (restarted.status !== 0)
+                    throw new Error(systemctlFailure(restartArgs, restarted));
+            }
         },
         uninstall() {
             const existed = fs.existsSync(file);

package/packages/server/dist/cli/update/install-method.d.ts

@@ -0,0 +1,131 @@
+/** The ten rows of SPEC §6's table, in its order. Matches `schemas/update-check.schema.json`. */
+export type InstallMethod = "docker" | "managed" | "npx" | "checkout" | "npm-global" | "pnpm-global" | "bun-global" | "volta" | "yarn-global" | "dependency";
+/** The package managers that can replace an install in place. */
+export type PackageManager = "npm" | "pnpm" | "bun" | "volta";
+export interface FsLike {
+    existsSync(p: string): boolean;
+    readFileSync(p: string, encoding: "utf8"): string;
+    realpathSync(p: string): string;
+}
+export interface DetectInput {
+    /** The published package's name, e.g. `@edspencer/paddock`. */
+    packageName: string;
+    /** The environment prefix: `PADDOCK` gives `PADDOCK_IN_DOCKER` and `PADDOCK_UPDATE_HINT`. */
+    envPrefix: string;
+    /**
+     * The script to walk up from — `process.argv[1]`, or this module's own file.
+     *
+     * SPEC §6 says `realpath(process.argv[1])`. Realpathing is done HERE rather
+     * than asked of the caller, because npm installs a `bin` as a symlink and the
+     * whole table is about where the package really sits (args.ts has the long
+     * version of why that distinction has bitten this CLI before).
+     */
+    entry: string;
+    env: NodeJS.ProcessEnv;
+    /**
+     * `npm root -g`, asked of the `npm` next to `process.execPath` (SPEC §6).
+     *
+     * Injected because it spawns a process: a unit test of the table must not
+     * depend on what the machine running it happens to have installed globally.
+     * Returning undefined (no npm, or it failed) is a normal answer — the row
+     * simply does not match.
+     */
+    npmGlobalRoot?: () => string | undefined;
+    fs?: FsLike;
+}
+export interface InstallInfo {
+    method: InstallMethod;
+    /**
+     * The folder whose `package.json` names {@link DetectInput.packageName}, or —
+     * when no ancestor does — the nearest folder with a `package.json` at all.
+     *
+     * The fallback is what makes a checkout detectable. Paddock's repo publishes
+     * a SYNTHESIZED package (`scripts/make-npm-package.mjs`), so in the checkout
+     * no manifest is called `@edspencer/paddock`: the root one is `paddock` and
+     * the workspace one is `@paddock/server`. A strict search would find nothing
+     * and have nothing to say; the nearest root finds `packages/server` and the
+     * "not under node_modules" test then correctly reports a checkout.
+     */
+    packageRoot: string | undefined;
+    /** True when the name was actually found, rather than fallen back to. */
+    named: boolean;
+    /** Can `update` install a new version itself, or must it print a command and exit 5? */
+    canUpdate: boolean;
+    /** The package manager to install with, when it can. */
+    manager?: PackageManager;
+    /** `<TOOL>_UPDATE_HINT`, when the environment set one. */
+    hint?: string;
+}
+/** `PADDOCK` → `PADDOCK_IN_DOCKER`. */
+export declare const inDockerVar: (prefix: string) => string;
+/** `PADDOCK` → `PADDOCK_UPDATE_HINT`. */
+export declare const updateHintVar: (prefix: string) => string;
+/**
+ * Walk up from `entry` looking for the package root.
+ *
+ * Returns the first ancestor whose `package.json` has our name, and the nearest
+ * ancestor with any `package.json` as a fallback — see
+ * {@link InstallInfo.packageRoot}.
+ */
+export declare function findPackageRoot(entry: string, packageName: string, fs: FsLike): {
+    root: string | undefined;
+    named: boolean;
+};
+/**
+ * Is `p` inside a `node_modules` directory?
+ *
+ * Split on the separator rather than matched as a substring, so a project
+ * genuinely called `my-node_modules` is not mistaken for one (and so Windows
+ * paths work, since `path.sep` is what split them). SPEC §6's "checkout or npm
+ * link" row is exactly the negation of this.
+ */
+export declare function underNodeModules(p: string): boolean;
+/**
+ * The npx / pnpm dlx / bunx / yarn dlx caches (SPEC §6).
+ *
+ * `_npx` and `bunx-` are matched between separators for the reason above.
+ * `dlx` has to be looser — pnpm's is `~/.local/share/pnpm/store/.../dlx/<hash>`
+ * and yarn's is `$TMPDIR/xfs-<hash>/dlx-<n>` — so a path SEGMENT that is `dlx`
+ * or starts `dlx-` counts.
+ */
+export declare function isEphemeralCachePath(p: string): boolean;
+/**
+ * Which of SPEC §6's rows this install is, checked in the table's own order.
+ *
+ * The order is the contract, and two pairs of rows genuinely overlap:
+ *
+ * - **Docker beats managed.** A container that an Ansible role also labelled
+ *   has both variables set, and the honest answer is "this is an image" — but
+ *   the hint is still carried on {@link InstallInfo.hint} and
+ *   {@link updateCommand} prefers it, because a hint is a sentence an operator
+ *   deliberately wrote and our guess at a `docker compose` line is not.
+ * - **Checkout beats every global.** They cannot both be true (every global
+ *   layout is under a `node_modules`), so the order between them never decides
+ *   anything; it is kept as the table has it so the two can be read side by
+ *   side.
+ */
+export declare function detectInstall(input: DetectInput): InstallInfo;
+export interface CommandInput {
+    packageName: string;
+    /** The version to install, when one has been resolved. */
+    target?: string;
+    /** The container image to pull, for the Docker row: `ghcr.io/edspencer/paddock`. */
+    image?: string;
+    /** Prefix the npm command with `sudo` — SPEC §5 step 5's not-writable case. */
+    sudo?: boolean;
+    /** The command that brings a checkout up to date. */
+    checkoutCommand?: string;
+}
+/**
+ * The one command to print (SPEC §3, §6): what the reader should run instead.
+ *
+ * Returns the command and, where it helps, the parenthetical the spec's example
+ * carries (`(the global folder isn't writable)`). An install that CAN update
+ * itself gets `<tool> update`, which is the line the update notice prints.
+ */
+export declare function updateCommand(info: InstallInfo, input: CommandInput): {
+    command: string;
+    note?: string;
+};
+/** One line a person can act on, for every row of the table. */
+export declare function describeInstall(info: InstallInfo, packageName: string): string;