@edspencer/paddock 0.81.0 → 0.82.1

package/packages/server/dist/cli/update/health.js

@@ -0,0 +1,64 @@
+// From edspencer/cli-contract reference/health.ts @ 0.2; local changes: `.ts` import specifiers → `.js`.
+// Asking `/api/health` (SPEC §8): once, until it answers, or until it answers with one version. The service commands
+// wait on it before they claim success, and `update` waits for the target version (SPEC §5 step 12). It's an HTTP
+// request to the URL a person would open, not a pid lookup: launchd and systemd both report a crash-looping job as
+// running for most of each restart interval. Node built-ins only.
+const healthUrl = (base) => new URL('/api/health', base).toString();
+/** Asks once. Undefined means nothing answered (with a 2xx), which is an answer, not an error. */
+export async function fetchHealth(o) {
+    try {
+        const res = await (o.fetch ?? globalThis.fetch)(healthUrl(o.url), { signal: AbortSignal.timeout(o.timeoutMs ?? 2000) });
+        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 it didn't answer. Generous, because it's only spent when something is wrong, and
+ * too short a wait says "didn't start" about a service that's only slow to boot.
+ */
+export const READY_TIMEOUT_MS = 20_000;
+const defaults = (o) => ({
+    timeoutMs: o.timeoutMs ?? READY_TIMEOUT_MS,
+    intervalMs: o.intervalMs ?? 250,
+    now: o.now ?? (() => Date.now()),
+    sleep: o.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms))),
+});
+/** Polls until `/api/health` answers 2xx, or the time runs out. Each request has its own abort. */
+export async function waitForReady(o) {
+    const { timeoutMs, intervalMs, now, sleep } = defaults(o);
+    const deadline = now() + timeoutMs;
+    for (;;) {
+        const answer = await fetchHealth({ ...o, timeoutMs: Math.max(250, Math.min(2000, deadline - now())) });
+        if (answer !== undefined)
+            return 'ready';
+        if (deadline - now() <= 0)
+            return 'timeout';
+        await sleep(intervalMs);
+    }
+}
+/**
+ * Polls until `/api/health` reports exactly `version`. "It answers" isn't enough: the old server still shutting
+ * down, another instance on the port, and a supervisor that brought the old unit back all answer, and those are the
+ * failures a rollback is for. A wrong version and no answer are kept apart because they read differently in a report.
+ */
+export async function waitForVersion(o) {
+    const { timeoutMs, intervalMs, now, sleep } = defaults(o);
+    const deadline = now() + timeoutMs;
+    let last;
+    for (;;) {
+        const answer = await fetchHealth({ ...o, timeoutMs: Math.max(250, Math.min(2000, deadline - now())) });
+        if (answer?.version !== undefined) {
+            if (answer.version === o.version)
+                return { state: 'ok', version: o.version };
+            last = answer.version;
+        }
+        if (deadline - now() <= 0)
+            return last !== undefined ? { state: 'wrong-version', version: last } : { state: 'no-answer' };
+        await sleep(intervalMs);
+    }
+}

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

@@ -0,0 +1,84 @@
+/** SPEC §6's rows, 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: `@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]`. It's realpath'd here, because npm installs a bin as a symlink. */
+    entry: string;
+    env: NodeJS.ProcessEnv;
+    /** `npm root -g`, asked of the npm beside `process.execPath` (`package-manager.ts`). Undefined if npm can't say. */
+    npmGlobalRoot?: () => string | undefined;
+    fs?: FsLike;
+}
+export interface InstallInfo {
+    method: InstallMethod;
+    /**
+     * The folder whose `package.json` has our name or, when none does, the nearest folder with a `package.json` at all.
+     * The fallback is what makes a checkout of a tool whose published package is put together at build time (Paddock's)
+     * come out as a checkout rather than as nothing.
+     */
+    packageRoot: string | undefined;
+    /** Whether the name was found, rather than fallen back from. */
+    named: boolean;
+    /** Whether `update` can install a new version itself, or must print a command and exit 5. */
+    canUpdate: boolean;
+    /** The package manager to install with, when it can. */
+    manager?: PackageManager;
+    /** `<TOOL>_UPDATE_HINT`, when it's set. */
+    hint?: string;
+}
+/** `PADDOCK` → `PADDOCK_IN_DOCKER`. */
+export declare const inDockerVar: (prefix: string) => string;
+/** `PADDOCK` → `PADDOCK_UPDATE_HINT`. */
+export declare const updateHintVar: (prefix: string) => string;
+/** Walks up from `entry` to the folder whose `package.json` has our name (see `InstallInfo.packageRoot`). */
+export declare function findPackageRoot(entry: string, packageName: string, fs: FsLike): {
+    root: string | undefined;
+    named: boolean;
+};
+/** Whether a path is inside a `node_modules` folder: by segment, so `my-node_modules` isn't one. */
+export declare function underNodeModules(p: string): boolean;
+/**
+ * The npx, pnpm dlx, bunx and yarn dlx caches (SPEC §6). `_npx` and `bunx-…` are matched as whole segments; pnpm's
+ * `…/dlx/<hash>` and yarn's `xfs-<hash>/dlx-<n>` need a segment that is `dlx` or starts `dlx-`.
+ */
+export declare function isEphemeralCachePath(p: string): boolean;
+/**
+ * Which of SPEC §6's rows this install is, checked in the table's order.
+ *
+ * - **Docker beats managed.** A container an Ansible role also labelled is an image, but `hint` still carries the
+ *   operator's sentence, and `updateCommand` prints it rather than guessing a `docker compose` line.
+ * - **No package root at all** reads as a checkout: it refuses to install, and "you're running from source" is the
+ *   least wrong thing to say.
+ */
+export declare function detectInstall(input: DetectInput): InstallInfo;
+export interface CommandInput {
+    packageName: string;
+    /** The version to install, once it's known. */
+    target?: string;
+    /** The image, for the Docker row: `ghcr.io/edspencer/paddock`. */
+    image?: string;
+    /** `sudo` in front: SPEC §5 step 5's not-writable case. */
+    sudo?: boolean;
+    /** What brings a checkout up to date, if not `git pull && npm install && npm run build`. */
+    checkoutCommand?: string;
+}
+/**
+ * The command SPEC §3's notice prints for this install, and the note in brackets after it. The rows that can update
+ * themselves get the package manager's own command here; the notice prints `<tool> update` for those instead.
+ */
+export declare function updateCommand(info: InstallInfo, input: CommandInput): {
+    command: string;
+    note?: string;
+};
+/** A line a person can read, for each row. */
+export declare function describeInstall(info: InstallInfo, packageName: string): string;

package/packages/server/dist/cli/update/install-method.js

@@ -0,0 +1,183 @@
+// From edspencer/cli-contract reference/install-method.ts @ 0.2; local changes: `.ts` import specifiers → `.js`.
+// How was this copy installed? (SPEC §6.) `update` can't run `npm install -g` on a checkout, in a container or out of
+// npx's cache, so before it touches anything it works out which of the table's ten rows it's in, and either picks the
+// package manager or prints the command that would work and exits 5.
+//
+// Nothing here knows about a particular tool: the package name, the environment prefix and the entry script come in
+// as data, and everything that touches the world (`npm root -g`, reading a manifest, resolving a symlink) is injected,
+// so all ten rows can be tested against made-up layouts on one machine. Node built-ins only.
+import fsDefault from 'node:fs';
+import path from 'node:path';
+/** `PADDOCK` → `PADDOCK_IN_DOCKER`. */
+export const inDockerVar = (prefix) => `${prefix}_IN_DOCKER`;
+/** `PADDOCK` → `PADDOCK_UPDATE_HINT`. */
+export const updateHintVar = (prefix) => `${prefix}_UPDATE_HINT`;
+/** Walks up from `entry` to the folder whose `package.json` has our name (see `InstallInfo.packageRoot`). */
+export function findPackageRoot(entry, packageName, fs) {
+    let dir = path.dirname(realpathOr(entry, fs));
+    let nearest;
+    for (;;) {
+        const manifest = path.join(dir, 'package.json');
+        if (fs.existsSync(manifest)) {
+            nearest ??= dir;
+            try {
+                if (JSON.parse(fs.readFileSync(manifest, 'utf8')).name === packageName)
+                    return { root: dir, named: true };
+            }
+            catch {
+                // A broken package.json on the way up isn't ours; keep walking.
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return { root: nearest, named: false };
+        dir = parent;
+    }
+}
+function realpathOr(p, fs) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+const segments = (p) => p.split(/[/\\]/);
+/** Whether a path is inside a `node_modules` folder: by segment, so `my-node_modules` isn't one. */
+export function underNodeModules(p) {
+    return segments(p).includes('node_modules');
+}
+/**
+ * The npx, pnpm dlx, bunx and yarn dlx caches (SPEC §6). `_npx` and `bunx-…` are matched as whole segments; pnpm's
+ * `…/dlx/<hash>` and yarn's `xfs-<hash>/dlx-<n>` need a segment that is `dlx` or starts `dlx-`.
+ */
+export function isEphemeralCachePath(p) {
+    return segments(p).some((seg) => seg === '_npx' || seg === 'dlx' || seg.startsWith('dlx-') || seg.startsWith('bunx-'));
+}
+function hasSegments(p, run) {
+    const parts = segments(p);
+    for (let i = 0; i + run.length <= parts.length; i++) {
+        if (run.every((s, j) => parts[i + j] === s))
+            return true;
+    }
+    return false;
+}
+/**
+ * Which of SPEC §6's rows this install is, checked in the table's order.
+ *
+ * - **Docker beats managed.** A container an Ansible role also labelled is an image, but `hint` still carries the
+ *   operator's sentence, and `updateCommand` prints it rather than guessing a `docker compose` line.
+ * - **No package root at all** reads as a checkout: it refuses to install, and "you're running from source" is the
+ *   least wrong thing to say.
+ */
+export function detectInstall(input) {
+    const fs = input.fs ?? fsDefault;
+    const env = input.env;
+    const { root, named } = findPackageRoot(input.entry, input.packageName, fs);
+    const hint = env[updateHintVar(input.envPrefix)];
+    const base = { packageRoot: root, named, ...(hint !== undefined && hint !== '' ? { hint } : {}) };
+    // 1. The tool's own Dockerfile sets this. Never `/.dockerenv`: dev containers have it, and a global install in one
+    //    is a legitimate thing to update.
+    if (env[inDockerVar(input.envPrefix)] === '1')
+        return { ...base, method: 'docker', canUpdate: false };
+    // 2. Something outside owns this install, and said so.
+    if (base.hint !== undefined)
+        return { ...base, method: 'managed', canUpdate: false };
+    if (root === undefined)
+        return { ...base, method: 'checkout', canUpdate: false };
+    // 3. A hash-keyed cache that gets pruned.
+    if (isEphemeralCachePath(root))
+        return { ...base, method: 'npx', canUpdate: false };
+    // 4. A checkout or an `npm link`: not under a node_modules at all.
+    if (!underNodeModules(root))
+        return { ...base, method: 'checkout', canUpdate: false };
+    // 5. The package root is `<npm root -g>/<name>`.
+    const globalRoot = input.npmGlobalRoot?.();
+    if (globalRoot !== undefined && samePath(root, path.join(globalRoot, input.packageName), fs)) {
+        return { ...base, method: 'npm-global', canUpdate: true, manager: 'npm' };
+    }
+    // 6–9. The other global layouts, each known by a run of segments in its path.
+    if (hasSegments(root, ['pnpm', 'global']))
+        return { ...base, method: 'pnpm-global', canUpdate: true, manager: 'pnpm' };
+    if (hasSegments(root, ['.bun', 'install', 'global']))
+        return { ...base, method: 'bun-global', canUpdate: true, manager: 'bun' };
+    if (hasSegments(root, ['.volta', 'tools', 'image', 'packages']))
+        return { ...base, method: 'volta', canUpdate: true, manager: 'volta' };
+    // Yarn classic is unmaintained and berry has no global add, so SPEC §6 prints the command rather than running it.
+    if (hasSegments(root, ['yarn', 'global', 'node_modules']))
+        return { ...base, method: 'yarn-global', canUpdate: false };
+    // 10. Under some other node_modules: a dependency of a project.
+    return { ...base, method: 'dependency', canUpdate: false };
+}
+/** A global root is often reached through a symlink (Homebrew's, nvm's), so realpaths count too. */
+function samePath(a, b, fs) {
+    return path.resolve(a) === path.resolve(b) || realpathOr(a, fs) === realpathOr(b, fs);
+}
+/**
+ * The command SPEC §3's notice prints for this install, and the note in brackets after it. The rows that can update
+ * themselves get the package manager's own command here; the notice prints `<tool> update` for those instead.
+ */
+export function updateCommand(info, input) {
+    const spec = input.target !== undefined ? `${input.packageName}@${input.target}` : input.packageName;
+    switch (info.method) {
+        case 'docker': {
+            if (info.hint !== undefined)
+                return { command: info.hint };
+            const tag = input.target !== undefined ? `:${input.target}` : '';
+            return { command: 'docker compose pull && docker compose up -d', ...(input.image !== undefined ? { note: `image ${input.image}${tag}` } : {}) };
+        }
+        case 'managed':
+            return { command: info.hint ?? 'ask whoever manages this install' };
+        case 'npx':
+            return { command: `npx ${input.packageName}@latest`, note: 'npx already runs the latest version each time' };
+        case 'checkout':
+            return { command: input.checkoutCommand ?? 'git pull && npm install && npm run build', note: 'this is a checkout' };
+        case 'npm-global':
+            return input.sudo === true
+                ? { command: `sudo npm install -g ${spec}`, note: "the global folder isn't writable" }
+                : { command: `npm install -g ${spec}` };
+        case 'pnpm-global':
+            return { command: `pnpm add -g ${spec}` };
+        case 'bun-global':
+            return { command: `bun add -g ${spec}` };
+        case 'volta':
+            return { command: `volta install ${spec}` };
+        case 'yarn-global':
+            return { command: `yarn global add ${spec}` };
+        case 'dependency': {
+            const project = info.packageRoot !== undefined ? ` (${projectOf(info.packageRoot)})` : '';
+            return { command: `npm install ${spec}`, note: `run it in the project that depends on ${input.packageName}${project}` };
+        }
+    }
+}
+/** The folder above a dependency's `node_modules`. */
+function projectOf(packageRoot) {
+    const parts = segments(packageRoot);
+    const i = parts.lastIndexOf('node_modules');
+    return i <= 0 ? packageRoot : packageRoot.slice(0, parts.slice(0, i).join('/').length);
+}
+/** A line a person can read, for each row. */
+export function describeInstall(info, packageName) {
+    switch (info.method) {
+        case 'docker':
+            return 'running from a container image';
+        case 'managed':
+            return "managed by something outside this machine's package manager";
+        case 'npx':
+            return 'running from an npx or dlx cache';
+        case 'checkout':
+            return info.packageRoot !== undefined ? `running from a checkout at ${info.packageRoot}` : 'running from a checkout';
+        case 'npm-global':
+            return 'installed globally with npm';
+        case 'pnpm-global':
+            return 'installed globally with pnpm';
+        case 'bun-global':
+            return 'installed globally with bun';
+        case 'volta':
+            return 'installed with volta';
+        case 'yarn-global':
+            return 'installed globally with yarn (classic)';
+        case 'dependency':
+            return `installed as a dependency of another project (${packageName})`;
+    }
+}

package/packages/server/dist/cli/update/lock.d.ts

@@ -0,0 +1,35 @@
+export declare const LOCK_FILE = "update.lock";
+export declare function lockPath(home: string): string;
+export interface LockBody {
+    pid: number;
+    startedAt: string;
+    /** What holds it, for the message: `paddock update --to 0.81.0`. */
+    command?: string;
+}
+export interface Lock {
+    path: string;
+    /** Removes the file if it's still ours. Safe to call twice. */
+    release(): void;
+}
+/** Another live process holds the lock. */
+export declare class LockHeldError extends Error {
+    name: string;
+    readonly holder: LockBody;
+    readonly path: string;
+    constructor(file: string, holder: LockBody);
+}
+export interface AcquireOptions {
+    home: string;
+    pid?: number;
+    command?: string;
+    isAlive?: (pid: number) => boolean;
+    now?: () => Date;
+}
+/**
+ * Takes the lock, or throws `LockHeldError`. After removing a stale lock it tries once more, and only once: a second
+ * `EEXIST` means another process won the same race just now, which is a real holder.
+ */
+export declare function acquireLock(o: AcquireOptions): Lock;
+export declare function readLock(file: string): LockBody | null;
+/** Removes the lock only if it names `pid`, or names nothing: never somebody else's. */
+export declare function releaseLock(file: string, pid: number): void;

package/packages/server/dist/cli/update/lock.js

@@ -0,0 +1,74 @@
+// From edspencer/cli-contract reference/lock.ts @ 0.2; local changes: `.ts` import specifiers → `.js`, and `exit-codes`, `output` and `runtime-file` imported from where Paddock keeps them (`../`, `../../`).
+// `<home>/update.lock`: one update at a time (SPEC §5 step 1). Two at once is easy to cause (an Ansible run and a
+// person at a terminal) and bad: the second stops the service the first just started, or installs an older target
+// over a newer one, and the loser's rollback "restores" a version nobody asked for.
+//
+// So the lock is an `O_EXCL` create holding the pid. A live holder refuses with exit 1; a dead one (a crashed or
+// killed update) is stale and is removed, or the install could never update itself again. Node built-ins only.
+import fs from 'node:fs';
+import path from 'node:path';
+import { isPidAlive } from '../../runtime-file.js';
+export const LOCK_FILE = 'update.lock';
+export function lockPath(home) {
+    return path.join(home, LOCK_FILE);
+}
+/** Another live process holds the lock. */
+export class LockHeldError extends Error {
+    name = 'LockHeldError';
+    holder;
+    path;
+    constructor(file, holder) {
+        super(`another update is already running (pid ${holder.pid}, started ${holder.startedAt}). If that's wrong, remove ${file} and try again.`);
+        this.holder = holder;
+        this.path = file;
+    }
+}
+/**
+ * Takes the lock, or throws `LockHeldError`. After removing a stale lock it tries once more, and only once: a second
+ * `EEXIST` means another process won the same race just now, which is a real holder.
+ */
+export function acquireLock(o) {
+    const file = lockPath(o.home);
+    const pid = o.pid ?? process.pid;
+    const isAlive = o.isAlive ?? isPidAlive;
+    const body = {
+        pid,
+        startedAt: (o.now ?? (() => new Date()))().toISOString(),
+        ...(o.command !== undefined ? { command: o.command } : {}),
+    };
+    fs.mkdirSync(o.home, { recursive: true });
+    for (let attempt = 0;; attempt++) {
+        try {
+            // 'wx' is O_CREAT | O_EXCL: the create is the lock, in one call.
+            fs.writeFileSync(file, `${JSON.stringify(body, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+            return { path: file, release: () => releaseLock(file, pid) };
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            const holder = readLock(file);
+            // A lock with no readable pid counts as stale: nobody can show a process holds it.
+            if ((holder !== null && holder.pid !== pid && isAlive(holder.pid)) || attempt > 0) {
+                throw new LockHeldError(file, holder ?? { pid: 0, startedAt: 'unknown' });
+            }
+            fs.rmSync(file, { force: true });
+        }
+    }
+}
+export function readLock(file) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (Number.isInteger(raw.pid) && typeof raw.startedAt === 'string')
+            return raw;
+    }
+    catch {
+        // missing, half-written, or not a lock
+    }
+    return null;
+}
+/** Removes the lock only if it names `pid`, or names nothing: never somebody else's. */
+export function releaseLock(file, pid) {
+    const holder = readLock(file);
+    if (holder === null || holder.pid === pid)
+        fs.rmSync(file, { force: true });
+}

package/packages/server/dist/cli/update/package-manager.d.ts

@@ -0,0 +1,74 @@
+import type { PackageManager } from './install-method.js';
+export interface RunResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+}
+/** Runs a command to completion; never throws for a non-zero exit. Injected everywhere, for tests. */
+export type Spawn = (cmd: string, args: string[], opts?: {
+    env?: NodeJS.ProcessEnv;
+    shell?: boolean;
+    timeoutMs?: number;
+}) => RunResult;
+export declare const spawnSyncRunner: Spawn;
+/** How long an install may take. */
+export declare const INSTALL_TIMEOUT_MS: number;
+export interface NpmContext {
+    spawn?: Spawn;
+    env?: NodeJS.ProcessEnv;
+    execPath?: string;
+    platform?: NodeJS.Platform;
+    /** Injected for tests: does this file exist? */
+    exists?: (p: string) => boolean;
+    realpath?: (p: string) => string;
+}
+/**
+ * How to run the npm that belongs to this Node: `[execPath, npm-cli.js]`, found beside it (`<dir>/npm` is a symlink
+ * to it on POSIX; on Windows it's `<dir>/node_modules/npm/bin/npm-cli.js`). Falls back to `npm` on the PATH, for a
+ * distribution that packages npm separately.
+ */
+export declare function npmCommand(ctx?: NpmContext): {
+    cmd: string;
+    pre: string[];
+    shell: boolean;
+};
+/** Runs this Node's npm. */
+export declare function runNpm(args: string[], ctx?: NpmContext, timeoutMs?: number): RunResult;
+/** `npm root -g`, or undefined when npm can't answer. */
+export declare function npmGlobalRoot(ctx?: NpmContext): string | undefined;
+/** `npm config get <key>`, or undefined. */
+export declare function npmConfigGet(key: string, ctx?: NpmContext): string | undefined;
+/**
+ * Whether `dir` is really writable (SPEC §5 step 5): a folder is created in it and removed again, the same call npm
+ * is about to make. `access(W_OK)` alone says yes to root on a read-only mount, and nothing about ACLs or immutable
+ * flags. A folder that doesn't exist yet asks its nearest existing parent, since npm would create it.
+ */
+export declare function isWritable(dir: string): boolean;
+/**
+ * Where a manager would install, for `isWritable` to ask about. Only npm can be asked (`npm root -g`). For the others
+ * there's no answer, and an install that can't write fails with that manager's own message, and rolls back.
+ */
+export declare function globalRootFor(manager: PackageManager, ctx?: NpmContext): string | undefined;
+/** The global install command, per SPEC §6's last column. */
+export declare function installArgs(manager: PackageManager, spec: string): {
+    cmd: string;
+    args: string[];
+};
+/** Installs `<name>@<version>` with the manager this install came from. pnpm, bun and volta come from the PATH. */
+export declare function installPackage(o: NpmContext & {
+    manager: PackageManager;
+    packageName: string;
+    version: string;
+}): RunResult;
+/**
+ * `npm cache add <name>@<version>` (SPEC §5 step 8), for the target and for the current version, while the old one
+ * still serves. Caching the current one is what lets a rollback reinstall it when the network is what failed. npm
+ * is used whatever the manager: it ships with Node, and the point is only to have the tarball on the machine.
+ */
+export declare function cacheAdd(packageName: string, version: string, ctx?: NpmContext): RunResult;
+/**
+ * A CLI's version, by running it: `node <cli> --version`. This is how `update` shows the install replaced the files
+ * before it hands over. A `package.json` beside it answers a different question: a stale symlink, or a pnpm layout
+ * whose versioned path moved, shows up here and not there.
+ */
+export declare function cliVersion(cliPath: string, ctx?: NpmContext): string | undefined;