@aragon-agent/cli 0.5.8 → 0.5.10

package/dist/update/installer.js

@@ -0,0 +1,242 @@
+/**
+ * The install (cli-auto-update section 3.5).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * INVARIANT U-2 - INVOKE NPM'S JS ENTRY THROUGH `process.execPath`, NEVER THE
+ * `npm` SHIM. On Windows `npm` is `npm.cmd`, and since the CVE-2024-27980 fix
+ * Node refuses to spawn a `.cmd` without `shell: true` - which C-7 forbids
+ * outright. Running node's own binary also guarantees the update is installed by
+ * the same runtime that will execute it.
+ *
+ * INVARIANT U-5 - THE CHILD'S OUTPUT GOES TO A FILE, AND ITS LIFETIME IS NEVER
+ * BOUNDED BY US. `'ignore'` leaves nothing to put in `update_install_failed`'s
+ * `stderrTail`, which is the one diagnostic a feature whose contract is silence
+ * actually needs; a PIPE would break D-10, because a detached child whose parent
+ * has exited takes `EPIPE` on its next write. A real file descriptor is
+ * inherited across the detach and keeps working after the parent is gone.
+ *
+ * `spawn`, NOT `execFile`, AND THAT IS A CORRECTION TO THE DESIGN (IF-3).
+ * Section 3.5 spelled this call as `execFile(..., { detached: true, stdio:
+ * [...], timeout: 0 })`, but `execFile` forwards NEITHER `detached` NOR `stdio`
+ * to `spawn` - it always builds its own pipes so it can buffer the output it
+ * hands to its callback. Measured on this package's own Node: with
+ * `stdio: ['ignore', fd, fd]` the log file stays EMPTY and the bytes arrive in
+ * the callback's `stdout` instead. Written as designed, U-5 loses its
+ * `stderrTail` AND D-10 loses the detach, silently and on every platform.
+ * `spawn` with an argv array and an explicit `shell: false` satisfies C-7's
+ * actual requirement ("argv array, never a shell, never a concatenated command
+ * line"), and it has no `timeout` option at all - so P1-5's "the limit must
+ * never become the child's bound" holds STRUCTURALLY here rather than by
+ * remembering to leave a field at `0`.
+ */
+import { spawn } from 'node:child_process';
+import { closeSync, existsSync, openSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import process from 'node:process';
+import { getUpdateInstallLogPath } from '../config/app-paths.js';
+import { UPDATE_LIMITS } from './limits.js';
+import { readSelfManifest } from './install-source.js';
+import { STRICT_VERSION_RE } from './semver.js';
+/**
+ * Where npm's JS entry point lives, or `null`.
+ *
+ * Probes the Windows / nvm4w layout first and the POSIX one second. There is
+ * deliberately NO bare-`npm`-on-PATH fallback: on Windows that resolves to
+ * `npm.cmd`, which is exactly what U-2 forbids, and a fallback that is correct
+ * on one platform and forbidden on another is the kind of branch that gets
+ * copied without its condition. A machine with no reachable `npm-cli.js`
+ * degrades to notify-only, which is the honest outcome.
+ */
+export function resolveNpmCli(execPath = process.execPath) {
+    const nodeDir = dirname(execPath);
+    const candidates = [
+        resolve(nodeDir, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+        resolve(nodeDir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    ];
+    for (const candidate of candidates) {
+        try {
+            if (existsSync(candidate) && statSync(candidate).isFile())
+                return candidate;
+        }
+        catch {
+            // Unreadable candidate; try the next.
+        }
+    }
+    return null;
+}
+/**
+ * `env` minus `NODE_OPTIONS`, plus the three switches that keep npm's
+ * postinstall banners from spawning anything interactive.
+ *
+ * `NODE_OPTIONS` is dropped because a `--require` hook inherited into npm is an
+ * unnecessary surface on a process we start unattended and never watch.
+ */
+export function cleanInstallEnv(env) {
+    const next = { ...env };
+    delete next.NODE_OPTIONS;
+    next.npm_config_yes = 'true';
+    next.ADBLOCK = '1';
+    next.DISABLE_OPENCOLLECTIVE = '1';
+    return next;
+}
+/** The argv this feature is allowed to build. Exported for AC-24's assertion. */
+export function buildInstallArgs(npmCliJs, packageName, version) {
+    return [
+        npmCliJs,
+        'install',
+        '--global',
+        `${packageName}@${version}`,
+        '--no-fund',
+        '--no-audit',
+        '--loglevel=error',
+    ];
+}
+function tailOf(path, maxChars) {
+    try {
+        const text = readFileSync(path, 'utf-8');
+        return text.length <= maxChars ? text : text.slice(-maxChars);
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Install `packageName@version` globally, detached, and verify it landed HERE.
+ *
+ * Resolves when the child exits (or fails to start). The child is `unref()`ed
+ * either way, so if the user quits mid-install the install COMPLETES rather than
+ * leaving a global package half-written; the next launch's check then finds
+ * local === remote and does nothing. Convergence, not bookkeeping (D-10).
+ *
+ * NEVER REJECTS. Every failure is an `InstallResult` with `ok: false`, because
+ * the only caller is a background timer whose contract is silence.
+ */
+export function runNpmInstall(input) {
+    const { packageName, version, root, onSpawn } = input;
+    const deps = input.deps ?? {};
+    const now = deps.now ?? Date.now;
+    const doSpawn = (deps.spawnImpl ?? spawn);
+    const logPath = deps.logPath ?? getUpdateInstallLogPath();
+    const readVersionAt = deps.readVersionAt ?? ((where) => readSelfManifest(where)?.version ?? null);
+    return new Promise((settle) => {
+        // The version came back from the registry and has already been through
+        // `parseSemver`; this is the gate that makes "not an injection surface" a
+        // checkable claim rather than a reasoned one (AC-24). It also satisfies
+        // `fetch-source.ts` rule 3 (no leading `-`) by construction.
+        if (!STRICT_VERSION_RE.test(version)) {
+            settle({ ok: false, failure: 'spawn' });
+            return;
+        }
+        const npmCliJs = deps.npmCliPath !== undefined ? deps.npmCliPath : resolveNpmCli();
+        if (!npmCliJs) {
+            settle({ ok: false, failure: 'spawn' });
+            return;
+        }
+        // A stale log from a parent that died before its child is unlinked here, so
+        // the tail read later can only be THIS install's (U-5).
+        try {
+            rmSync(logPath, { force: true });
+        }
+        catch {
+            // Best-effort; an unremovable stale log costs one misleading tail.
+        }
+        let logFd = null;
+        try {
+            logFd = openSync(logPath, 'w');
+        }
+        catch {
+            // No log file means no `stderrTail`, which is a diagnostic loss and not a
+            // reason to skip the install.
+            logFd = null;
+        }
+        const startedAt = now();
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (logFd !== null) {
+                try {
+                    closeSync(logFd);
+                }
+                catch {
+                    // Already closed; the child holds its own duplicated descriptor.
+                }
+            }
+            settle({ ...result, elapsedMs: now() - startedAt });
+        };
+        const options = {
+            detached: true,
+            stdio: ['ignore', logFd ?? 'ignore', logFd ?? 'ignore'],
+            env: cleanInstallEnv(deps.env ?? process.env),
+            // C-7, spelled out rather than inherited from the default: this argv is
+            // built from a manifest on disk and a registry response, and a `true` here
+            // would turn both into shell input.
+            shell: false,
+            windowsHide: true,
+        };
+        let child;
+        try {
+            child = doSpawn(process.execPath, buildInstallArgs(npmCliJs, packageName, version), options);
+        }
+        catch {
+            finish({ ok: false, failure: 'spawn' });
+            return;
+        }
+        child.on('error', () => finish({ ok: false, failure: 'spawn' }));
+        child.on('exit', (code) => {
+            const tail = tailOf(logPath, UPDATE_LIMITS.stderrTailChars);
+            try {
+                rmSync(logPath, { force: true });
+            }
+            catch {
+                // The next install unlinks it before opening.
+            }
+            if (code !== 0) {
+                finish({
+                    ok: false,
+                    failure: 'exit',
+                    ...(tail ? { stderrTail: tail } : {}),
+                    ...(typeof code === 'number' ? { exitCode: code } : {}),
+                });
+                return;
+            }
+            // ---------------------------------------------------------------------
+            // U-6 - `npm` EXITING 0 DOES NOT MEAN THIS INSTALLATION MOVED.
+            //
+            // Section 3.2 classifies the running copy by PATH; `npm install --global`
+            // writes to the prefix NPM'S OWN CONFIG resolves. Those are the same
+            // directory on an ordinary machine and different directories on one with
+            // `prefix=` in `.npmrc`, with two Node installations, or with a global
+            // root inherited from a version manager the user has since switched away
+            // from. Left unchecked the state machine reaches `ready` on a lie,
+            // `pendingRestartVersion` never matches, and the next check re-decides
+            // `install` - an UNBOUNDED SILENT REINSTALL, once per interval, forever
+            // (R-12). The check costs one `readFileSync` of a file we already know how
+            // to parse, and it is the only thing standing between this design and the
+            // worst failure shape available to a feature that promised to be invisible.
+            // ---------------------------------------------------------------------
+            const observed = readVersionAt(root);
+            if (observed !== version) {
+                finish({
+                    ok: false,
+                    failure: 'ineffective',
+                    ...(observed ? { observedVersion: observed } : {}),
+                    ...(tail ? { stderrTail: tail } : {}),
+                });
+                return;
+            }
+            finish({ ok: true, observedVersion: observed, exitCode: 0 });
+        });
+        // Phase two of U-4, and it must happen HERE: the lock had to be taken before
+        // the spawn, but `child.pid` does not exist until after it.
+        if (typeof child.pid === 'number' && onSpawn)
+            onSpawn(child.pid);
+        // Survives our own exit (D-10). `dispose()` deliberately never kills it
+        // (U-3): killing a running `npm install -g` is the one action in this
+        // feature that can leave the user's global installation broken, and it would
+        // be triggered by the most ordinary event there is - Ctrl+C.
+        child.unref?.();
+    });
+}

package/dist/update/limits.d.ts

@@ -0,0 +1,111 @@
+/**
+ * UPDATE_LIMITS - the single authority on every structural bound the updater
+ * enforces (cli-auto-update section 5.4).
+ *
+ * ASCII ONLY: `src/update/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts`), so no literal in this tree may hold a non-ASCII byte. The
+ * regex there is a hardcoded directory list, which is why adding this tree and
+ * adding `update` to that list are the SAME change (C-2 / AC-18) - a scanner
+ * that silently stops scanning is worse than no scanner.
+ *
+ * TWO KINDS OF NUMBER, AND THEY ARE NOT INTERCHANGEABLE - the distinction
+ * `TEAM_LIMITS`, `TODO_LIMITS` and `FAST_LIMITS` all state:
+ *
+ *  - The entries below are STRUCTURAL. They describe what a background check, a
+ *    detached install and a one-row readout can physically carry. A user has no
+ *    business tuning them.
+ *  - The four `update.*` keys in `config/schema.ts` are POLICY: whether to
+ *    install at all, how often to ask, which registry, which dist-tag. Those are
+ *    clamped, persisted and user-facing.
+ *
+ * NOTHING HERE IS IMPORTED AT RUNTIME BY `cli.tsx` (AC-1). This module and
+ * `types.ts` are pure, dependency-free and side-effect-free; every other module
+ * in this tree is reached only through the dynamic `import()` in section 3.8.
+ */
+export declare const UPDATE_LIMITS: {
+    /** Never contend with first paint. */
+    readonly startupDelayMs: 3000;
+    /**
+     * A background check has nobody waiting on it.
+     *
+     * Below `fetch-source.ts`'s `HTTP_TIMEOUT_MS` (15 s) ON PURPOSE: that one
+     * bounds a download a human typed a command for, this one bounds a request the
+     * user never asked for and must never notice.
+     */
+    readonly checkTimeoutMs: 8000;
+    /**
+     * Wall-clock budget for the `installing` PHASE and the lock's staleness
+     * refresh - NEVER FOR THE CHILD (U-5 / P1-5).
+     *
+     * It decides when the UI stops saying "updating" and when a lock is treated as
+     * abandoned. It is deliberately NOT `execFile`'s `timeout`, which stays `0`:
+     * wiring it there makes Node `SIGTERM` npm mid-write - the broken global
+     * installation U-3 and D-10 exist to prevent - and it would fire on exactly
+     * the slow links where a five-minute install is the correct outcome.
+     */
+    readonly installTimeoutMs: 300000;
+    /** The `/latest` document is ~2 KB; this is the C-8 ceiling, not a target. */
+    readonly manifestMaxBytes: number;
+    /** Matches `fetch-source.ts`'s `MAX_REDIRECTS`. */
+    readonly maxRedirects: 3;
+    /**
+     * Longer than `skills`' 60 s, and the difference is the point: the holder here
+     * is an npm install on a cold cache, not a file rename.
+     */
+    readonly lockTtlMs: 600000;
+    /** First retry after a failed check or install. */
+    readonly backoffBaseMs: 1800000;
+    /** Ceiling of the exponential. */
+    readonly backoffMaxMs: 86400000;
+    /**
+     * Consecutive failures before the row says anything at all (D-7).
+     *
+     * Below this the failure is silent, because silence is the requirement and an
+     * unactionable recurring warning is the standard way updaters become hated.
+     */
+    readonly failuresBeforeNotice: 3;
+    /** Thundering-herd spread on the check interval (D-12). */
+    readonly jitterRatio: 0.15;
+    /**
+     * Bounded, redacted npm error tail, read from the install LOG FILE (U-5).
+     *
+     * There is a tail to read at all only because the child writes to a real file
+     * descriptor rather than to `'ignore'`; a pipe would have died with the parent
+     * and broken D-10.
+     */
+    readonly stderrTailChars: 500;
+    /**
+     * Below this many columns the update line renders its short form (section 6.2).
+     *
+     * DELIBERATELY NOT `FAST_LIMITS.statusCompactCols`' 100 (`fast/limits.ts`).
+     * That number governs a multi-part status chip competing with the context
+     * gauge for the same row; this one governs a single short clause that owns its
+     * row outright. Two numbers about two different things - do not unify them.
+     */
+    readonly statusCompactCols: 60;
+    /**
+     * Non-zero exits of a version WE installed before it is rolled back
+     * (cli-auto-update-hardening section 7.2 / D-30).
+     *
+     * Tested against the count of PREVIOUS launches, so `2` means "the third
+     * launch rolls back". One crash can be transient - a machine that ran out of
+     * memory once, or whose session file was corrupt, gets a second chance at the
+     * release it just installed. Two is a pattern.
+     *
+     * NOTHING ELSE IN THIS TABLE BOUNDS THE ROLLBACK. There is deliberately no
+     * `bootGuardMaxAgeMs`: the guard is armed only while `autoInstalledVersion`
+     * equals the RUNNING version, so "a machine offline for a year" is a machine
+     * still running the version we installed, and rolling it back to
+     * `lastGoodVersion` is exactly as correct on day 400 as on day 1 (P1-3).
+     */
+    readonly crashesBeforeRollback: 2;
+    /**
+     * Bound on the `npm view` fallback probe (H3).
+     *
+     * SAFE HERE AND FORBIDDEN FOR THE INSTALLER (C-20). A killed `npm view` has
+     * written nothing; a killed `npm install -g` leaves a broken global
+     * installation, which is why `installTimeoutMs` above bounds the PHASE and
+     * never the child.
+     */
+    readonly npmViewTimeoutMs: 10000;
+};

package/dist/update/limits.js

@@ -0,0 +1,111 @@
+/**
+ * UPDATE_LIMITS - the single authority on every structural bound the updater
+ * enforces (cli-auto-update section 5.4).
+ *
+ * ASCII ONLY: `src/update/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts`), so no literal in this tree may hold a non-ASCII byte. The
+ * regex there is a hardcoded directory list, which is why adding this tree and
+ * adding `update` to that list are the SAME change (C-2 / AC-18) - a scanner
+ * that silently stops scanning is worse than no scanner.
+ *
+ * TWO KINDS OF NUMBER, AND THEY ARE NOT INTERCHANGEABLE - the distinction
+ * `TEAM_LIMITS`, `TODO_LIMITS` and `FAST_LIMITS` all state:
+ *
+ *  - The entries below are STRUCTURAL. They describe what a background check, a
+ *    detached install and a one-row readout can physically carry. A user has no
+ *    business tuning them.
+ *  - The four `update.*` keys in `config/schema.ts` are POLICY: whether to
+ *    install at all, how often to ask, which registry, which dist-tag. Those are
+ *    clamped, persisted and user-facing.
+ *
+ * NOTHING HERE IS IMPORTED AT RUNTIME BY `cli.tsx` (AC-1). This module and
+ * `types.ts` are pure, dependency-free and side-effect-free; every other module
+ * in this tree is reached only through the dynamic `import()` in section 3.8.
+ */
+export const UPDATE_LIMITS = {
+    /** Never contend with first paint. */
+    startupDelayMs: 3_000,
+    /**
+     * A background check has nobody waiting on it.
+     *
+     * Below `fetch-source.ts`'s `HTTP_TIMEOUT_MS` (15 s) ON PURPOSE: that one
+     * bounds a download a human typed a command for, this one bounds a request the
+     * user never asked for and must never notice.
+     */
+    checkTimeoutMs: 8_000,
+    /**
+     * Wall-clock budget for the `installing` PHASE and the lock's staleness
+     * refresh - NEVER FOR THE CHILD (U-5 / P1-5).
+     *
+     * It decides when the UI stops saying "updating" and when a lock is treated as
+     * abandoned. It is deliberately NOT `execFile`'s `timeout`, which stays `0`:
+     * wiring it there makes Node `SIGTERM` npm mid-write - the broken global
+     * installation U-3 and D-10 exist to prevent - and it would fire on exactly
+     * the slow links where a five-minute install is the correct outcome.
+     */
+    installTimeoutMs: 300_000,
+    /** The `/latest` document is ~2 KB; this is the C-8 ceiling, not a target. */
+    manifestMaxBytes: 256 * 1024,
+    /** Matches `fetch-source.ts`'s `MAX_REDIRECTS`. */
+    maxRedirects: 3,
+    /**
+     * Longer than `skills`' 60 s, and the difference is the point: the holder here
+     * is an npm install on a cold cache, not a file rename.
+     */
+    lockTtlMs: 600_000,
+    /** First retry after a failed check or install. */
+    backoffBaseMs: 1_800_000,
+    /** Ceiling of the exponential. */
+    backoffMaxMs: 86_400_000,
+    /**
+     * Consecutive failures before the row says anything at all (D-7).
+     *
+     * Below this the failure is silent, because silence is the requirement and an
+     * unactionable recurring warning is the standard way updaters become hated.
+     */
+    failuresBeforeNotice: 3,
+    /** Thundering-herd spread on the check interval (D-12). */
+    jitterRatio: 0.15,
+    /**
+     * Bounded, redacted npm error tail, read from the install LOG FILE (U-5).
+     *
+     * There is a tail to read at all only because the child writes to a real file
+     * descriptor rather than to `'ignore'`; a pipe would have died with the parent
+     * and broken D-10.
+     */
+    stderrTailChars: 500,
+    /**
+     * Below this many columns the update line renders its short form (section 6.2).
+     *
+     * DELIBERATELY NOT `FAST_LIMITS.statusCompactCols`' 100 (`fast/limits.ts`).
+     * That number governs a multi-part status chip competing with the context
+     * gauge for the same row; this one governs a single short clause that owns its
+     * row outright. Two numbers about two different things - do not unify them.
+     */
+    statusCompactCols: 60,
+    /**
+     * Non-zero exits of a version WE installed before it is rolled back
+     * (cli-auto-update-hardening section 7.2 / D-30).
+     *
+     * Tested against the count of PREVIOUS launches, so `2` means "the third
+     * launch rolls back". One crash can be transient - a machine that ran out of
+     * memory once, or whose session file was corrupt, gets a second chance at the
+     * release it just installed. Two is a pattern.
+     *
+     * NOTHING ELSE IN THIS TABLE BOUNDS THE ROLLBACK. There is deliberately no
+     * `bootGuardMaxAgeMs`: the guard is armed only while `autoInstalledVersion`
+     * equals the RUNNING version, so "a machine offline for a year" is a machine
+     * still running the version we installed, and rolling it back to
+     * `lastGoodVersion` is exactly as correct on day 400 as on day 1 (P1-3).
+     */
+    crashesBeforeRollback: 2,
+    /**
+     * Bound on the `npm view` fallback probe (H3).
+     *
+     * SAFE HERE AND FORBIDDEN FOR THE INSTALLER (C-20). A killed `npm view` has
+     * written nothing; a killed `npm install -g` leaves a broken global
+     * installation, which is why `installTimeoutMs` above bounds the PHASE and
+     * never the child.
+     */
+    npmViewTimeoutMs: 10_000,
+};

package/dist/update/npm-view.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The proxy-aware fallback probe (cli-auto-update-hardening H3 / section 5.4).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * NODE'S `fetch` (undici) IGNORES `HTTP_PROXY`. v1 recorded that as R-5 and
+ * accepted it: "the check fails, silently, forever". When the direct request
+ * returns `null`, the check now retries ONCE through the npm this machine
+ * already has, which honours `proxy`, `https-proxy`, `.npmrc` and any auth the
+ * user configured.
+ *
+ * WE DELEGATE RATHER THAN IMPLEMENT A PROXY (D-34). We do not read `.npmrc`, we
+ * do not parse `HTTP_PROXY`, and we attach credentials to nothing - D-13's "NO
+ * CREDENTIALS, EVER" is untouched because we never see them. We run the command
+ * the user could have typed and read one version string out of its JSON.
+ *
+ * `execFile` HERE, `spawn` IN `installer.ts`, AND THAT IS NOT AN INCONSISTENCY
+ * (D-36 / C-20). v1's IF-3 rejected `execFile` for the installer because it
+ * forwards neither `stdio` nor `detached`. This probe wants neither: it wants
+ * the buffered stdout `execFile` exists to provide, and it must NOT be detached.
+ * `timeout` is likewise safe here and forbidden there - a killed `npm view` has
+ * written nothing, a killed `npm install -g` has left a broken global install.
+ */
+import { type ExecFileOptions } from 'node:child_process';
+import type { LatestManifest } from './types.js';
+/** The `execFile` shape this module needs. Injectable so no test spawns npm. */
+export type ExecFileImpl = (file: string, args: string[], options: ExecFileOptions, callback: (error: Error | null, stdout: string, stderr: string) => void) => unknown;
+export interface NpmViewDeps {
+    execFileImpl?: ExecFileImpl;
+    /** `null` forces the "no npm entry point" branch; `undefined` probes. */
+    npmCliPath?: string | null;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+}
+/**
+ * The argv this probe is allowed to build. Exported for AC-47's assertion, on
+ * the `buildInstallArgs` precedent.
+ *
+ * `--registry` IS NOT OPTIONAL, and leaving it out was a real divergence (P1-4 /
+ * D-41). The HTTP path resolves `update.registry` through `resolveRegistryUrl`;
+ * `npm view` without the flag obeys whatever `.npmrc` says. The two would then
+ * answer about DIFFERENT REGISTRIES - and the population where they differ is a
+ * mirror-configured corporate machine, which is the same population this
+ * fallback exists for. The `registry` passed in is the already-resolved string
+ * `runCheck` computed, so the two probes describe one registry by construction.
+ *
+ * Auth is unaffected: `--registry` selects a URL, and npm still applies whatever
+ * `.npmrc` credentials are scoped to it. We neither read nor forward any (D-13).
+ */
+export declare function buildNpmViewArgs(npmCliJs: string, packageName: string, distTag: string, registry: string): string[];
+/**
+ * Ask the machine's own npm what the dist-tag points at, or `null`.
+ *
+ * NEVER THROWS - the same contract as `fetchLatestManifest`, for the same
+ * reason: the only caller is a background timer whose entire contract is that
+ * the user does not find out. Any non-zero exit, any timeout, any unparseable
+ * stdout and a `resolveNpmCli()` of `null` all resolve to `null`.
+ *
+ * NO BARE-`npm`-ON-PATH FALLBACK, for the reason `installer.ts` already gives:
+ * on Windows that resolves to `npm.cmd`, which U-2 forbids.
+ */
+export declare function fetchLatestViaNpm(registry: string, packageName: string, distTag: string, deps?: NpmViewDeps): Promise<LatestManifest | null>;

package/dist/update/npm-view.js

@@ -0,0 +1,133 @@
+/**
+ * The proxy-aware fallback probe (cli-auto-update-hardening H3 / section 5.4).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * NODE'S `fetch` (undici) IGNORES `HTTP_PROXY`. v1 recorded that as R-5 and
+ * accepted it: "the check fails, silently, forever". When the direct request
+ * returns `null`, the check now retries ONCE through the npm this machine
+ * already has, which honours `proxy`, `https-proxy`, `.npmrc` and any auth the
+ * user configured.
+ *
+ * WE DELEGATE RATHER THAN IMPLEMENT A PROXY (D-34). We do not read `.npmrc`, we
+ * do not parse `HTTP_PROXY`, and we attach credentials to nothing - D-13's "NO
+ * CREDENTIALS, EVER" is untouched because we never see them. We run the command
+ * the user could have typed and read one version string out of its JSON.
+ *
+ * `execFile` HERE, `spawn` IN `installer.ts`, AND THAT IS NOT AN INCONSISTENCY
+ * (D-36 / C-20). v1's IF-3 rejected `execFile` for the installer because it
+ * forwards neither `stdio` nor `detached`. This probe wants neither: it wants
+ * the buffered stdout `execFile` exists to provide, and it must NOT be detached.
+ * `timeout` is likewise safe here and forbidden there - a killed `npm view` has
+ * written nothing, a killed `npm install -g` has left a broken global install.
+ */
+import { execFile } from 'node:child_process';
+import process from 'node:process';
+import { cleanInstallEnv, resolveNpmCli } from './installer.js';
+import { UPDATE_LIMITS } from './limits.js';
+/**
+ * The argv this probe is allowed to build. Exported for AC-47's assertion, on
+ * the `buildInstallArgs` precedent.
+ *
+ * `--registry` IS NOT OPTIONAL, and leaving it out was a real divergence (P1-4 /
+ * D-41). The HTTP path resolves `update.registry` through `resolveRegistryUrl`;
+ * `npm view` without the flag obeys whatever `.npmrc` says. The two would then
+ * answer about DIFFERENT REGISTRIES - and the population where they differ is a
+ * mirror-configured corporate machine, which is the same population this
+ * fallback exists for. The `registry` passed in is the already-resolved string
+ * `runCheck` computed, so the two probes describe one registry by construction.
+ *
+ * Auth is unaffected: `--registry` selects a URL, and npm still applies whatever
+ * `.npmrc` credentials are scoped to it. We neither read nor forward any (D-13).
+ */
+export function buildNpmViewArgs(npmCliJs, packageName, distTag, registry) {
+    return [
+        npmCliJs,
+        'view',
+        `${packageName}@${distTag}`,
+        '--json',
+        '--loglevel=error',
+        `--registry=${registry}`,
+    ];
+}
+/**
+ * Normalise `npm view`'s object into the SAME shape `fetchLatestManifest`
+ * returns, so `decideUpdate` cannot tell the two sources apart.
+ *
+ * `npm view pkg@tag --json` on a dist-tag yields one object. An ARRAY comes back
+ * for a range, which we never send - but npm is not ours, so take the last
+ * element rather than failing the whole probe on a shape we did not ask for.
+ */
+function normalise(parsed) {
+    const one = Array.isArray(parsed) ? parsed[parsed.length - 1] : parsed;
+    if (!one || typeof one !== 'object')
+        return null;
+    const doc = one;
+    if (typeof doc.name !== 'string' || typeof doc.version !== 'string')
+        return null;
+    return {
+        name: doc.name,
+        version: doc.version,
+        ...(doc.engines && typeof doc.engines === 'object'
+            ? { engines: { ...(typeof doc.engines.node === 'string' ? { node: doc.engines.node } : {}) } }
+            : {}),
+        // Present ONLY when the version is deprecated. npm writes a string, but
+        // `true` appears in the wild; both mean "do not auto-install this".
+        ...(doc.deprecated !== undefined ? { deprecated: String(doc.deprecated) } : {}),
+    };
+}
+/**
+ * Ask the machine's own npm what the dist-tag points at, or `null`.
+ *
+ * NEVER THROWS - the same contract as `fetchLatestManifest`, for the same
+ * reason: the only caller is a background timer whose entire contract is that
+ * the user does not find out. Any non-zero exit, any timeout, any unparseable
+ * stdout and a `resolveNpmCli()` of `null` all resolve to `null`.
+ *
+ * NO BARE-`npm`-ON-PATH FALLBACK, for the reason `installer.ts` already gives:
+ * on Windows that resolves to `npm.cmd`, which U-2 forbids.
+ */
+export function fetchLatestViaNpm(registry, packageName, distTag, deps = {}) {
+    return new Promise((settle) => {
+        const npmCliJs = deps.npmCliPath !== undefined ? deps.npmCliPath : resolveNpmCli();
+        if (!npmCliJs) {
+            settle(null);
+            return;
+        }
+        const run = deps.execFileImpl ?? execFile;
+        const options = {
+            // C-7, spelled out rather than inherited: this argv carries a package name
+            // read from a manifest on disk and a registry URL from config.
+            shell: false,
+            windowsHide: true,
+            timeout: deps.timeoutMs ?? UPDATE_LIMITS.npmViewTimeoutMs,
+            maxBuffer: UPDATE_LIMITS.manifestMaxBytes,
+            env: cleanInstallEnv(deps.env ?? process.env),
+        };
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            settle(value);
+        };
+        try {
+            run(process.execPath, buildNpmViewArgs(npmCliJs, packageName, distTag, registry), options, (error, stdout) => {
+                if (error) {
+                    finish(null);
+                    return;
+                }
+                try {
+                    finish(normalise(JSON.parse(String(stdout))));
+                }
+                catch {
+                    finish(null);
+                }
+            });
+        }
+        catch {
+            // `execFile` can throw synchronously on a bad argv or a missing binary.
+            finish(null);
+        }
+    });
+}