@aragon-agent/cli 0.5.9 → 0.5.10

package/dist/update/classify-failure.js

@@ -0,0 +1,60 @@
+/**
+ * Turning a tail of npm output into a reason (cli-auto-update-hardening H2 /
+ * section 5.3).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * PURE, AND THE ONLY IMPORT IS A TYPE. The interesting half of H2 is not this
+ * table, it is the REPORTING rule that decides which of the resulting reasons
+ * may break the three-strike silence - and that lives in `types.ts` beside
+ * `shouldRenderUpdateLine`, as `IMMEDIATE_NOTICE_REASONS`.
+ *
+ * WHY THIS EXISTS AT ALL. The one line a user is ever allowed to see on the
+ * failure path reads `update failed <dot> npm i -g @aragon-agent/cli` for EVERY
+ * cause. For `EPERM` / `EBUSY` - the Windows self-replacement case, R-3 - that
+ * advice hits the same held handle and fails identically, so the single visible
+ * failure is also a wrong instruction.
+ */
+/**
+ * FIRST MATCH WINS, AND THE ORDER IS NOT ALPHABETICAL.
+ *
+ * `EPERM` is tested before `EACCES` because npm's Windows output frequently
+ * carries BOTH - the `EPERM` on the shim rename plus an `EACCES` from a retry -
+ * and the actionable one is the first. `network` is last because "proxy" and
+ * "network" appear inside unrelated npm advisory text often enough that an
+ * earlier position would swallow the three specific cases above it.
+ */
+const TABLE = [
+    [
+        /\bEPERM\b|\bEBUSY\b|\bETXTBSY\b|operation not permitted|resource busy or locked/i,
+        'blocked-by-os',
+    ],
+    [/\bEACCES\b|permission denied/i, 'not-writable'],
+    [/\bENOSPC\b|no space left/i, 'no-space'],
+    [
+        /\bENOTFOUND\b|\bEAI_AGAIN\b|\bECONNRESET\b|\bETIMEDOUT\b|network|proxy|tunneling socket/i,
+        'network',
+    ],
+];
+/**
+ * Classify an install failure from the bounded stderr tail `runNpmInstall`
+ * already returns.
+ *
+ * ONE PARAMETER, NOT TWO. An earlier draft took `exitCode` and never read it:
+ * npm exits `1` for every one of these, so the code carries no information the
+ * tail does not, and a parameter that no branch and no test consumes is a
+ * maintenance liability that reads like a promise (P2-2).
+ *
+ * An absent or unrecognised tail is `install-failed` - the pre-H2 behaviour, so
+ * a machine whose npm says something we have never seen degrades to exactly what
+ * it did before rather than to a confident wrong answer.
+ */
+export function classifyInstallFailure(tail) {
+    if (!tail)
+        return 'install-failed';
+    for (const [re, reason] of TABLE) {
+        if (re.test(tail))
+            return reason;
+    }
+    return 'install-failed';
+}

package/dist/update/install-lock.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The cross-process install lock (cli-auto-update section 3.7).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * INHERITS `skills/lock.ts`'s PAYLOAD DISCIPLINE, NOT ITS ACQUISITION LOOP
+ * (C-9). The payload shape, the TTL, the liveness probe, the
+ * `LOCK_UNREADABLE_CONFIRMATIONS` rule and the uuid-guarded release are all the
+ * same and are imported rather than restated. The retry loop is NOT:
+ *
+ * INVARIANT U-5b - ACQUISITION IS A SINGLE NON-BLOCKING ATTEMPT.
+ * `acquireRootLock` busy-waits SYNCHRONOUSLY through `Atomics.wait` for up to
+ * `LOCK_MAX_WAIT_MS = 5_000` and then THROWS. That is right for `aragon skills
+ * install`, where a human typed the command and there is nothing else to do.
+ * Here it would freeze the Ink render loop for five seconds, from a background
+ * timer, in the feature whose entire requirement is that it is invisible. So:
+ * one `wx` attempt, no sleep, no retry, no throw - `tryAcquireInstallLock()`
+ * returns `null` on `EEXIST` after the staleness check, and the caller treats
+ * that as INFORMATION (someone else is already installing) rather than failure.
+ */
+export interface InstallLockHandle {
+    /**
+     * Phase two of U-4: rewrite the payload in place with the CHILD's pid.
+     *
+     * `uuid` and `startedAt` are preserved - the uuid is what `release()` matches
+     * on, and `startedAt` is what the TTL measures, so replacing either here would
+     * silently break one of the two recovery paths.
+     */
+    adoptChild(pid: number): void;
+    release(): void;
+}
+export interface InstallLockOptions {
+    now?: () => number;
+    /** Injected for tests; defaults to `process.kill(pid, 0)` liveness probing. */
+    isProcessAlive?: (pid: number) => boolean;
+    /** Injected for tests; defaults to `<home>/update-install.lock`. */
+    path?: string;
+}
+/**
+ * Take the install lock, or report that someone else has it. NEVER SLEEPS,
+ * NEVER THROWS (U-5b / AC-27).
+ *
+ * The payload written here carries the PARENT's pid, and that is not a mistake:
+ * INVARIANT U-4 says the lock must name the CHILD, but the lock has to be held
+ * BEFORE the spawn (or the race it exists to close is wide open) and `child.pid`
+ * does not exist UNTIL AFTER it. `skills/lock.ts::tryCreate` writes its payload
+ * at create time, so a literal mirror can only ever write the parent's. Hence
+ * two phases: this call, then `adoptChild(child.pid)` the moment `execFile`
+ * returns.
+ *
+ * The window between them is SAFE rather than merely narrow: a crash inside it
+ * leaves a lock naming a DEAD PARENT, which is exactly the case the liveness
+ * probe below already reclaims.
+ */
+export declare function tryAcquireInstallLock(opts?: InstallLockOptions): InstallLockHandle | null;

package/dist/update/install-lock.js

@@ -0,0 +1,184 @@
+/**
+ * The cross-process install lock (cli-auto-update section 3.7).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * INHERITS `skills/lock.ts`'s PAYLOAD DISCIPLINE, NOT ITS ACQUISITION LOOP
+ * (C-9). The payload shape, the TTL, the liveness probe, the
+ * `LOCK_UNREADABLE_CONFIRMATIONS` rule and the uuid-guarded release are all the
+ * same and are imported rather than restated. The retry loop is NOT:
+ *
+ * INVARIANT U-5b - ACQUISITION IS A SINGLE NON-BLOCKING ATTEMPT.
+ * `acquireRootLock` busy-waits SYNCHRONOUSLY through `Atomics.wait` for up to
+ * `LOCK_MAX_WAIT_MS = 5_000` and then THROWS. That is right for `aragon skills
+ * install`, where a human typed the command and there is nothing else to do.
+ * Here it would freeze the Ink render loop for five seconds, from a background
+ * timer, in the feature whose entire requirement is that it is invisible. So:
+ * one `wx` attempt, no sleep, no retry, no throw - `tryAcquireInstallLock()`
+ * returns `null` on `EEXIST` after the staleness check, and the caller treats
+ * that as INFORMATION (someone else is already installing) rather than failure.
+ */
+import { closeSync, openSync, readFileSync, unlinkSync, writeFileSync, writeSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+import process from 'node:process';
+import { getUpdateLockPath } from '../config/app-paths.js';
+import { LOCK_UNREADABLE_CONFIRMATIONS } from '../skills/lock.js';
+import { UPDATE_LIMITS } from './limits.js';
+/**
+ * `ESRCH` means gone. `EPERM` means the process EXISTS but belongs to another
+ * user - treating that as dead would let one user steal another's lock, so it
+ * reports alive. Verbatim from `skills/lock.ts`.
+ */
+function defaultIsProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code !== 'ESRCH';
+    }
+}
+function readLock(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        if (typeof parsed.pid !== 'number' || typeof parsed.startedAt !== 'number')
+            return null;
+        if (typeof parsed.uuid !== 'string' || typeof parsed.host !== 'string')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** `wx` - atomic exclusive create. THIS SINGLE CALL IS THE MUTUAL EXCLUSION;
+ *  everything else in this file is recovery policy. */
+function tryCreate(path, payload) {
+    let fd;
+    try {
+        fd = openSync(path, 'wx');
+    }
+    catch (err) {
+        if (err.code === 'EEXIST')
+            return false;
+        // An unwritable home is not a lock conflict, but it is equally a reason not
+        // to install; the caller cannot act on the difference.
+        return false;
+    }
+    try {
+        writeSync(fd, JSON.stringify(payload));
+    }
+    finally {
+        // Closed IMMEDIATELY: on Windows an open handle blocks `unlink`, so holding
+        // it would make our own release fail and turn every lock into a
+        // ten-minute stall for the next process.
+        closeSync(fd);
+    }
+    return true;
+}
+/**
+ * Take the install lock, or report that someone else has it. NEVER SLEEPS,
+ * NEVER THROWS (U-5b / AC-27).
+ *
+ * The payload written here carries the PARENT's pid, and that is not a mistake:
+ * INVARIANT U-4 says the lock must name the CHILD, but the lock has to be held
+ * BEFORE the spawn (or the race it exists to close is wide open) and `child.pid`
+ * does not exist UNTIL AFTER it. `skills/lock.ts::tryCreate` writes its payload
+ * at create time, so a literal mirror can only ever write the parent's. Hence
+ * two phases: this call, then `adoptChild(child.pid)` the moment `execFile`
+ * returns.
+ *
+ * The window between them is SAFE rather than merely narrow: a crash inside it
+ * leaves a lock naming a DEAD PARENT, which is exactly the case the liveness
+ * probe below already reclaims.
+ */
+export function tryAcquireInstallLock(opts = {}) {
+    const now = opts.now ?? Date.now;
+    const isAlive = opts.isProcessAlive ?? defaultIsProcessAlive;
+    const path = opts.path ?? getUpdateLockPath();
+    const payload = {
+        pid: process.pid,
+        host: hostname(),
+        startedAt: now(),
+        uuid: randomUUID(),
+    };
+    if (tryCreate(path, payload))
+        return makeHandle(path, payload);
+    // Held. The ONLY thing we may do about it is decide whether the holder is
+    // plausibly dead - and even then we get exactly one more `wx` attempt, because
+    // two processes can judge the same lock stale at the same moment and `wx` is
+    // the only thing entitled to decide between them.
+    const holder = readLock(path);
+    let stale;
+    if (holder === null) {
+        // One unreadable read is indistinguishable from a lock that is mid-creation
+        // (create and write are two syscalls), so it is NOT evidence of abandonment.
+        // With a single attempt there is no second probe to accumulate, so an
+        // unreadable lock is left alone unless the discipline says one look is
+        // enough - which, at `LOCK_UNREADABLE_CONFIRMATIONS = 2`, it is not.
+        stale = LOCK_UNREADABLE_CONFIRMATIONS <= 1;
+    }
+    else {
+        stale =
+            now() - holder.startedAt > UPDATE_LIMITS.lockTtlMs ||
+                (holder.host === payload.host && !isAlive(holder.pid));
+    }
+    if (!stale)
+        return null;
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // Another process won the race to clean it up, or the file is pinned by a
+        // scanner holding a handle open on Windows. Either way: not ours this tick.
+        return null;
+    }
+    return tryCreate(path, payload) ? makeHandle(path, payload) : null;
+}
+function makeHandle(path, payload) {
+    let released = false;
+    let current = payload;
+    return {
+        adoptChild(pid) {
+            if (released)
+                return;
+            const next = { ...current, pid };
+            try {
+                // A plain overwrite and NOT `wx`: we already own this file, and a
+                // rename-based atomic swap would break the `wx` invariant for whoever is
+                // probing it at this instant.
+                writeFileSync(path, JSON.stringify(next), 'utf-8');
+                current = next;
+            }
+            catch {
+                // The lock keeps naming the parent. That degrades to the pre-U-4
+                // behaviour for this one install - a lock that may be judged stale early
+                // - and is strictly better than aborting an install that is already
+                // running.
+            }
+        },
+        release() {
+            if (released)
+                return;
+            released = true;
+            try {
+                const holder = readLock(path);
+                // THE UUID CHECK IS NOT DEFENSIVE PADDING (D-A10's argument, verbatim).
+                // If this process was judged stale and preempted, an unconditional
+                // `unlink` here would delete the NEW holder's lock and open a second
+                // concurrency window - the classic file-lock bug, and one that only
+                // shows up under exactly the contention the lock exists to handle.
+                if (holder?.uuid !== current.uuid)
+                    return;
+                unlinkSync(path);
+            }
+            catch {
+                // A failed release costs at most one TTL of waiting for the next
+                // process. Letting it throw would end a SUCCESSFUL install in an error.
+            }
+        },
+    };
+}

package/dist/update/install-source.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The eligibility ladder (cli-auto-update section 3.2).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * THE DANGEROUS VERSION OF THIS FEATURE RUNS `npm i -g` ON A MACHINE WHERE
+ * `aragon` CAME FROM SOMEWHERE ELSE. From `npx`, from a pnpm store, from a
+ * project's `node_modules`, from volta, or from a clone of this monorepo - in
+ * every one of those the global install either does not exist, is not what is
+ * running, or is actively wrong to touch. This module classifies the running
+ * installation from its own real path and reports which of those it is; the
+ * service auto-installs for exactly one classification and degrades everything
+ * else to a one-line notice carrying the correct command for THAT manager.
+ */
+import type { InstallSource } from './types.js';
+/** The package this CLI publishes as. Read from the manifest, never hardcoded
+ *  into the registry URL, so a fork keeps working (U-1). */
+export interface SelfManifest {
+    name: string;
+    version: string;
+}
+/**
+ * The package root, resolved from THIS MODULE's own URL.
+ *
+ * INVARIANT U-1 - THE LEVEL COUNT IS LOAD-BEARING AND THE FAILURE IS SILENT.
+ *
+ * The count is only correct because this package is compiled by plain `tsc` with
+ * `rootDir: ./src` and NO BUNDLER (C-16), so `src/update/install-source.ts`
+ * really does land at `dist/update/install-source.js`. If a bundler is ever
+ * introduced, `import.meta.url` collapses to `dist/cli.js` and this ascent
+ * becomes off-by-one - so that build property is a dependency of this module,
+ * not a background detail. `cli.tsx::readVersion()` goes up ONE level because it
+ * lives at `dist/cli.js`; this module lives two deep and goes up TWO.
+ *
+ * An off-by-one yields a directory whose `package.json` may still parse (the
+ * monorepo root's does), so the updater would silently check a package that is
+ * not us. `readSelfManifest()` therefore refuses a manifest without both a
+ * `name` and a `version`, and AC-3 asserts the name it reads.
+ *
+ * `realpathSync` is MANDATORY: nvm, volta and `npm link` all put symlinks on
+ * this path, and every rung of the ladder below is path-shaped.
+ */
+export declare function selfPackageRoot(): string | null;
+/**
+ * `<root>/package.json`, or `null` when it is absent, unparseable, or missing
+ * either of the two fields that make it OURS rather than some ancestor's.
+ */
+export declare function readSelfManifest(root?: string | null): SelfManifest | null;
+/**
+ * Classify the running installation. FIRST MATCH WINS, and the order is the
+ * table in section 3.2 read top to bottom.
+ *
+ * D-4 - THE GLOBAL/LOCAL CRITERION IS "DOES A MANIFEST PIN US", NOT "IS THIS THE
+ * NPM PREFIX". The obvious implementation derives the global prefix from
+ * `process.execPath`. That is wrong on Windows, where the bundled npm's default
+ * prefix is `%APPDATA%\npm` and has nothing to do with `C:\Program Files\nodejs`.
+ * It is also semantically weaker than what we actually need to know: auto-update
+ * is legitimate exactly when NO PROJECT MANIFEST PINS OUR VERSION. A
+ * `node_modules` with a sibling `package.json` is a project; one without is a
+ * global root (`%APPDATA%\npm\node_modules`, `/usr/local/lib/node_modules`,
+ * `~/.nvm/versions/node/vX/lib/node_modules` - none of them has a sibling
+ * manifest). The rule needs no subprocess, no prefix arithmetic and no platform
+ * branch.
+ */
+export declare function classifyInstallSource(root: string, env?: NodeJS.ProcessEnv): InstallSource;
+/**
+ * Can we actually write the directory the install would replace?
+ *
+ * A path can look global and still be unwritable - the ordinary Linux case,
+ * where the global root belongs to root and the user has no sudo (R-2). Probing
+ * BEFORE spawning npm turns a confusing EACCES deep in npm's output into an
+ * actionable one-line notice.
+ */
+export declare function probeWritable(root: string): boolean;
+/** Whether this classification may be auto-installed at all (D-5). */
+export declare function isAutoInstallable(source: InstallSource): boolean;
+/**
+ * Whether a classification is worth telling the user about when it is NOT
+ * auto-installable.
+ *
+ * THREE ARE SILENT, and the third is the one a reader is most likely to drop.
+ * `dev-monorepo` and `npx` are the obvious pair (AC-6 / AC-7): a developer's
+ * clone is not out of date, it is checked out; and an `npx` invocation already
+ * resolved `latest` seconds ago. `npm-local` belongs with them for the reason
+ * D-4 exists at all - a project manifest PINS our version, so upgrading is not
+ * the user's decision to make from inside this session, and `adviceFor` returns
+ * `undefined` for it because there is no command we could honestly suggest.
+ *
+ * WITHOUT `npm-local` HERE THE ROW RENDERS `0.6.0 available` WITH NO COMMAND
+ * AFTER IT, once per session, forever, on every project that depends on this
+ * package - a persistent notice carrying no action, which is precisely the
+ * notification fatigue D-7 and R-8 spend the rest of this feature avoiding.
+ * The section 3.2 table and `manual-test.md` row 10 both say "silent".
+ */
+export declare function isReportableSource(source: InstallSource): boolean;
+/** The copy-pasteable command for a source we will not install ourselves. */
+export declare function adviceFor(source: InstallSource, packageName: string): string | undefined;

package/dist/update/install-source.js

@@ -0,0 +1,218 @@
+/**
+ * The eligibility ladder (cli-auto-update section 3.2).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * THE DANGEROUS VERSION OF THIS FEATURE RUNS `npm i -g` ON A MACHINE WHERE
+ * `aragon` CAME FROM SOMEWHERE ELSE. From `npx`, from a pnpm store, from a
+ * project's `node_modules`, from volta, or from a clone of this monorepo - in
+ * every one of those the global install either does not exist, is not what is
+ * running, or is actively wrong to touch. This module classifies the running
+ * installation from its own real path and reports which of those it is; the
+ * service auto-installs for exactly one classification and degrades everything
+ * else to a one-line notice carrying the correct command for THAT manager.
+ */
+import { accessSync, constants, existsSync, readFileSync, realpathSync } from 'node:fs';
+import { basename, dirname, resolve, sep } from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+/**
+ * The package root, resolved from THIS MODULE's own URL.
+ *
+ * INVARIANT U-1 - THE LEVEL COUNT IS LOAD-BEARING AND THE FAILURE IS SILENT.
+ *
+ * The count is only correct because this package is compiled by plain `tsc` with
+ * `rootDir: ./src` and NO BUNDLER (C-16), so `src/update/install-source.ts`
+ * really does land at `dist/update/install-source.js`. If a bundler is ever
+ * introduced, `import.meta.url` collapses to `dist/cli.js` and this ascent
+ * becomes off-by-one - so that build property is a dependency of this module,
+ * not a background detail. `cli.tsx::readVersion()` goes up ONE level because it
+ * lives at `dist/cli.js`; this module lives two deep and goes up TWO.
+ *
+ * An off-by-one yields a directory whose `package.json` may still parse (the
+ * monorepo root's does), so the updater would silently check a package that is
+ * not us. `readSelfManifest()` therefore refuses a manifest without both a
+ * `name` and a `version`, and AC-3 asserts the name it reads.
+ *
+ * `realpathSync` is MANDATORY: nvm, volta and `npm link` all put symlinks on
+ * this path, and every rung of the ladder below is path-shaped.
+ */
+export function selfPackageRoot() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        return realpathSync(resolve(here, '..', '..'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `<root>/package.json`, or `null` when it is absent, unparseable, or missing
+ * either of the two fields that make it OURS rather than some ancestor's.
+ */
+export function readSelfManifest(root = selfPackageRoot()) {
+    if (!root)
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf-8'));
+        if (typeof parsed?.name !== 'string' || parsed.name.length === 0)
+            return null;
+        if (typeof parsed?.version !== 'string' || parsed.version.length === 0)
+            return null;
+        return { name: parsed.name, version: parsed.version };
+    }
+    catch {
+        return null;
+    }
+}
+function segments(path) {
+    return path.split(/[\\/]/).filter((s) => s.length > 0);
+}
+/** The nearest ancestor directory named `node_modules`, or `null`. */
+function nearestNodeModules(root) {
+    let current = root;
+    for (;;) {
+        if (basename(current) === 'node_modules')
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+function isMonorepoCheckout(root) {
+    if (basename(root) !== 'cli')
+        return false;
+    if (basename(dirname(root)) !== 'packages')
+        return false;
+    try {
+        const parsed = JSON.parse(readFileSync(resolve(root, '..', '..', 'package.json'), 'utf-8'));
+        return Array.isArray(parsed?.workspaces);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Classify the running installation. FIRST MATCH WINS, and the order is the
+ * table in section 3.2 read top to bottom.
+ *
+ * D-4 - THE GLOBAL/LOCAL CRITERION IS "DOES A MANIFEST PIN US", NOT "IS THIS THE
+ * NPM PREFIX". The obvious implementation derives the global prefix from
+ * `process.execPath`. That is wrong on Windows, where the bundled npm's default
+ * prefix is `%APPDATA%\npm` and has nothing to do with `C:\Program Files\nodejs`.
+ * It is also semantically weaker than what we actually need to know: auto-update
+ * is legitimate exactly when NO PROJECT MANIFEST PINS OUR VERSION. A
+ * `node_modules` with a sibling `package.json` is a project; one without is a
+ * global root (`%APPDATA%\npm\node_modules`, `/usr/local/lib/node_modules`,
+ * `~/.nvm/versions/node/vX/lib/node_modules` - none of them has a sibling
+ * manifest). The rule needs no subprocess, no prefix arithmetic and no platform
+ * branch.
+ */
+export function classifyInstallSource(root, env = process.env) {
+    const parts = segments(root);
+    if (isMonorepoCheckout(root))
+        return 'dev-monorepo';
+    // `npx` already resolves `latest` on every run, so there is nothing here that
+    // could be out of date tomorrow.
+    if (parts.includes('_npx'))
+        return 'npx';
+    if (parts.includes('.pnpm') || existsSync(resolve(root, '..', '..', '.pnpm')))
+        return 'pnpm';
+    // `.yarn` (berry) or the classic `yarn/global` PAIR - adjacency matters, or a
+    // `/opt/yarn/lib/node_modules` install plus an unrelated `global` segment
+    // somewhere else on the path would misclassify.
+    if (parts.includes('.yarn'))
+        return 'yarn';
+    if (parts.some((part, i) => part === 'yarn' && parts[i + 1] === 'global'))
+        return 'yarn';
+    if (parts.includes('.bun'))
+        return 'bun';
+    if (parts.includes('.volta'))
+        return 'volta';
+    const voltaHome = env.VOLTA_HOME?.trim();
+    if (voltaHome && voltaHome.length > 0) {
+        const prefix = realpathQuiet(voltaHome);
+        if (prefix && (root === prefix || root.startsWith(prefix + sep)))
+            return 'volta';
+    }
+    const nm = nearestNodeModules(root);
+    if (!nm)
+        return 'unknown';
+    // THE WHOLE OF D-4, in one line: a sibling manifest means a project pins our
+    // version and an auto-upgrade would fight it.
+    return existsSync(resolve(dirname(nm), 'package.json')) ? 'npm-local' : 'npm-global';
+}
+function realpathQuiet(path) {
+    try {
+        return realpathSync(resolve(path));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Can we actually write the directory the install would replace?
+ *
+ * A path can look global and still be unwritable - the ordinary Linux case,
+ * where the global root belongs to root and the user has no sudo (R-2). Probing
+ * BEFORE spawning npm turns a confusing EACCES deep in npm's output into an
+ * actionable one-line notice.
+ */
+export function probeWritable(root) {
+    try {
+        accessSync(dirname(root), constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether this classification may be auto-installed at all (D-5). */
+export function isAutoInstallable(source) {
+    return source === 'npm-global';
+}
+/**
+ * Whether a classification is worth telling the user about when it is NOT
+ * auto-installable.
+ *
+ * THREE ARE SILENT, and the third is the one a reader is most likely to drop.
+ * `dev-monorepo` and `npx` are the obvious pair (AC-6 / AC-7): a developer's
+ * clone is not out of date, it is checked out; and an `npx` invocation already
+ * resolved `latest` seconds ago. `npm-local` belongs with them for the reason
+ * D-4 exists at all - a project manifest PINS our version, so upgrading is not
+ * the user's decision to make from inside this session, and `adviceFor` returns
+ * `undefined` for it because there is no command we could honestly suggest.
+ *
+ * WITHOUT `npm-local` HERE THE ROW RENDERS `0.6.0 available` WITH NO COMMAND
+ * AFTER IT, once per session, forever, on every project that depends on this
+ * package - a persistent notice carrying no action, which is precisely the
+ * notification fatigue D-7 and R-8 spend the rest of this feature avoiding.
+ * The section 3.2 table and `manual-test.md` row 10 both say "silent".
+ */
+export function isReportableSource(source) {
+    return source !== 'dev-monorepo' && source !== 'npx' && source !== 'npm-local';
+}
+/** The copy-pasteable command for a source we will not install ourselves. */
+export function adviceFor(source, packageName) {
+    switch (source) {
+        case 'pnpm':
+            return `pnpm add -g ${packageName}`;
+        case 'yarn':
+            return `yarn global add ${packageName}`;
+        case 'bun':
+            return `bun add -g ${packageName}`;
+        case 'volta':
+            return `volta install ${packageName}`;
+        case 'npm-global':
+        case 'unknown':
+            return `npm i -g ${packageName}`;
+        // A project manifest pins us; upgrading behind its back is the one thing a
+        // package manager exists to prevent (D-4).
+        case 'npm-local':
+        case 'dev-monorepo':
+        case 'npx':
+        default:
+            return undefined;
+    }
+}