@aragon-agent/cli 0.5.9 → 0.5.10

package/dist/update/semver.js

@@ -0,0 +1,295 @@
+/**
+ * Semver comparison and the update decision (cli-auto-update section 3.4).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * HAND-WRITTEN AND NOT `semver`. The package has no such dependency
+ * (`package.json`), and this feature needs three questions answered - "is B
+ * newer than A", "is B a prerelease", "does this Node satisfy that range" - on a
+ * document the registry writes and npm itself only warns about. Adding a
+ * transitive dependency to an auto-updater, of all things, is the one place the
+ * supply-chain argument in R-1 cuts hardest.
+ *
+ * PURE: no I/O, no clock, no process. Every function here is total and none of
+ * them throws.
+ */
+/**
+ * The form a version must have before it is interpolated into `npm install`'s
+ * argv (section 3.5 / AC-24).
+ *
+ * ANCHORED AND WITHOUT `v`: a registry that answered `"1.0.0; rm -rf /"` must
+ * never reach `execFile`. With `shell: false` this is not an injection surface
+ * to begin with, but the rejection is what makes that claim checkable rather
+ * than reasoned, and it also satisfies `fetch-source.ts` rule 3 (no leading `-`)
+ * by construction.
+ */
+export const STRICT_VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+/** Parse a semver string, or `null` when it is not one. Never throws. */
+export function parseSemver(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const match = SEMVER_RE.exec(raw.trim());
+    if (!match)
+        return null;
+    const [, major, minor, patch, pre] = match;
+    return {
+        major: Number.parseInt(major, 10),
+        minor: Number.parseInt(minor, 10),
+        patch: Number.parseInt(patch, 10),
+        prerelease: pre ? pre.split('.') : [],
+    };
+}
+export function isPrerelease(raw) {
+    return (parseSemver(raw)?.prerelease.length ?? 0) > 0;
+}
+/**
+ * Compare prerelease identifier lists per semver section 11.
+ *
+ * THE EMPTY LIST SORTS HIGHEST, which is the rule that keeps `1.0.0-rc.1` below
+ * `1.0.0`. Getting this backwards would let a `latest` tag pointing at a release
+ * candidate read as newer than the release it precedes.
+ */
+function comparePrerelease(a, b) {
+    if (a.length === 0 && b.length === 0)
+        return 0;
+    if (a.length === 0)
+        return 1;
+    if (b.length === 0)
+        return -1;
+    const len = Math.max(a.length, b.length);
+    for (let i = 0; i < len; i += 1) {
+        const x = a[i];
+        const y = b[i];
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        const xNum = /^\d+$/.test(x);
+        const yNum = /^\d+$/.test(y);
+        if (xNum && yNum) {
+            const diff = Number.parseInt(x, 10) - Number.parseInt(y, 10);
+            if (diff !== 0)
+                return diff < 0 ? -1 : 1;
+            continue;
+        }
+        // Numeric identifiers always sort below alphanumeric ones.
+        if (xNum !== yNum)
+            return xNum ? -1 : 1;
+        if (x !== y)
+            return x < y ? -1 : 1;
+    }
+    return 0;
+}
+/**
+ * `-1 | 0 | 1`. An UNPARSEABLE version sorts BELOW a parseable one and equal to
+ * another unparseable one, so a garbage registry answer can never read as newer
+ * than what is installed.
+ */
+export function compareSemver(a, b) {
+    const left = parseSemver(a);
+    const right = parseSemver(b);
+    if (!left && !right)
+        return 0;
+    if (!left)
+        return -1;
+    if (!right)
+        return 1;
+    if (left.major !== right.major)
+        return left.major < right.major ? -1 : 1;
+    if (left.minor !== right.minor)
+        return left.minor < right.minor ? -1 : 1;
+    if (left.patch !== right.patch)
+        return left.patch < right.patch ? -1 : 1;
+    return comparePrerelease(left.prerelease, right.prerelease);
+}
+function parseClause(raw) {
+    const text = raw.trim();
+    if (text.length === 0)
+        return null;
+    const ops = [
+        ['>=', '>='],
+        ['<=', '<='],
+        ['>', '>'],
+        ['<', '<'],
+        ['^', '^'],
+        ['~', '~'],
+        ['=', '='],
+    ];
+    for (const [prefix, op] of ops) {
+        if (text.startsWith(prefix)) {
+            const rest = text.slice(prefix.length).trim();
+            const parsed = parsePartial(rest);
+            return parsed ? { op, ...parsed } : null;
+        }
+    }
+    const parsed = parsePartial(text);
+    return parsed ? { op: '=', ...parsed } : null;
+}
+/**
+ * `18`, `18.x`, `18.19`, `18.19.0` - the partial forms `engines.node` uses in
+ * practice. Missing components read as `0`, which is what makes `>=18` mean
+ * `>=18.0.0`, and `specified` records how many were really named.
+ */
+function parsePartial(raw) {
+    const text = raw.trim().replace(/^v/, '');
+    if (text.length === 0)
+        return null;
+    const parts = text.split('.');
+    if (parts.length > 3)
+        return null;
+    const nums = [];
+    let specified = 0;
+    let sawWildcard = false;
+    for (const part of parts) {
+        if (part === 'x' || part === 'X' || part === '*') {
+            sawWildcard = true;
+            nums.push(0);
+            continue;
+        }
+        if (!/^\d+$/.test(part))
+            return null;
+        nums.push(Number.parseInt(part, 10));
+        // A concrete component AFTER a wildcard (`18.x.3`) names nothing further:
+        // the wildcard has already made everything below it free.
+        if (!sawWildcard)
+            specified += 1;
+    }
+    return {
+        version: {
+            major: nums[0] ?? 0,
+            minor: nums[1] ?? 0,
+            patch: nums[2] ?? 0,
+            prerelease: [],
+        },
+        specified,
+    };
+}
+function compareParsed(a, b) {
+    if (a.major !== b.major)
+        return a.major < b.major ? -1 : 1;
+    if (a.minor !== b.minor)
+        return a.minor < b.minor ? -1 : 1;
+    if (a.patch !== b.patch)
+        return a.patch < b.patch ? -1 : 1;
+    return comparePrerelease(a.prerelease, b.prerelease);
+}
+function satisfiesClause(actual, clause) {
+    const cmp = compareParsed(actual, clause.version);
+    switch (clause.op) {
+        case '>=':
+            return cmp >= 0;
+        case '>':
+            return cmp > 0;
+        case '<=':
+            return cmp <= 0;
+        case '<':
+            return cmp < 0;
+        case '=':
+            // A BARE PARTIAL IS A RANGE, NOT AN EQUALITY. `18` and `18.x` mean "any
+            // 18.y.z"; only a fully-specified `18.19.0` means that exact version.
+            if (clause.specified === 0)
+                return true;
+            if (actual.major !== clause.version.major)
+                return false;
+            if (clause.specified === 1)
+                return true;
+            if (actual.minor !== clause.version.minor)
+                return false;
+            if (clause.specified === 2)
+                return true;
+            return actual.patch === clause.version.patch;
+        case '^':
+            return cmp >= 0 && actual.major === clause.version.major;
+        case '~':
+            return (cmp >= 0 &&
+                actual.major === clause.version.major &&
+                actual.minor === clause.version.minor);
+        default:
+            return true;
+    }
+}
+/**
+ * Does `nodeVersion` satisfy `engines.node`?
+ *
+ * FAILS OPEN, and that is a decision rather than an oversight (D-15). Handled
+ * forms are `>=X`, `>=X.Y.Z`, `>X`, `<X`, `<=X`, `=X`, `^X`, `~X`, `X.x`, and
+ * `||`-joined unions of those, with space-separated clauses inside a union
+ * ANDed together. Anything this cannot parse returns `true`, matching npm's own
+ * default of warning rather than refusing.
+ *
+ * Failing CLOSED here would mean a syntax we did not anticipate silently freezes
+ * every user's updates forever, with no message and no way to find out - the
+ * worse of the two errors by a wide margin. A range we DID understand and that
+ * genuinely excludes this Node yields `false`, and the caller turns that into a
+ * `node-too-old` notice so the user is told to upgrade Node rather than left
+ * wondering.
+ */
+export function satisfiesNodeRange(range, nodeVersion) {
+    if (range === undefined)
+        return true;
+    const text = range.trim();
+    if (text.length === 0 || text === '*')
+        return true;
+    const actual = parseSemver(nodeVersion);
+    if (!actual)
+        return true;
+    for (const union of text.split('||')) {
+        const clauses = union.trim().split(/\s+/).filter((c) => c.length > 0);
+        if (clauses.length === 0)
+            continue;
+        let allParsed = true;
+        let allSatisfied = true;
+        for (const raw of clauses) {
+            const clause = parseClause(raw);
+            if (!clause) {
+                allParsed = false;
+                break;
+            }
+            if (!satisfiesClause(actual, clause))
+                allSatisfied = false;
+        }
+        // An unparseable clause makes the WHOLE range unknown, not just this union:
+        // a partially-understood range is exactly the input that would make a
+        // fail-open guard silently strict.
+        if (!allParsed)
+            return true;
+        if (allSatisfied)
+            return true;
+    }
+    return false;
+}
+/**
+ * Should we install, merely report, or say nothing? (section 3.4)
+ *
+ * ORDER IS SEMANTIC. `up-to-date` is answered first because it is the
+ * overwhelmingly common case and the cheapest; `skipped` comes before the
+ * quality gates so a user who typed `/update skip` is not told about a
+ * prerelease they already declined. Only a range we UNDERSTOOD and that excludes
+ * this Node produces `notify`; every other rejection is silent (`none`).
+ *
+ * The SOURCE and the MODE are deliberately NOT inputs here. This function
+ * answers "is that version worth having"; whether this machine may install it is
+ * the service's question, and folding the two would make a pure decision depend
+ * on the filesystem.
+ */
+export function decideUpdate(input) {
+    const { local, manifest, nodeVersion, skippedVersion } = input;
+    const remote = manifest.version;
+    if (compareSemver(remote, local) <= 0)
+        return { action: 'none', reason: 'up-to-date' };
+    if (skippedVersion.length > 0 && remote === skippedVersion) {
+        return { action: 'none', reason: 'skipped' };
+    }
+    // A stable install is never moved onto a prerelease, even if someone points
+    // `latest` at one. A local prerelease is already opted in, so it may move.
+    if (isPrerelease(remote) && !isPrerelease(local)) {
+        return { action: 'none', reason: 'prerelease' };
+    }
+    if (manifest.deprecated !== undefined)
+        return { action: 'none', reason: 'deprecated' };
+    if (!satisfiesNodeRange(manifest.engines?.node, nodeVersion)) {
+        return { action: 'notify', reason: 'node-too-old' };
+    }
+    return { action: 'install', reason: 'newer-available' };
+}

package/dist/update/service.d.ts

@@ -0,0 +1,193 @@
+/**
+ * `UpdateService` - the state machine, the scheduler and the event stream
+ * (cli-auto-update section 3.6).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ *         idle --check()--> checking --none--> idle
+ *                              |
+ *                              |-notify--> available     (terminal for the session)
+ *                              `-install-> installing --ok--> ready   (terminal)
+ *                                               `-err--> failed --backoff--> idle
+ *
+ * EVERY FAILURE IS SILENT (D-7). A background updater that cannot reach the
+ * registry behind a corporate proxy, or cannot write to `/usr/lib/node_modules`
+ * without sudo, must not turn into a recurring interruption: it logs, backs off
+ * exponentially, and stays quiet. The single exception is a failure the user can
+ * actually fix, after `UPDATE_LIMITS.failuresBeforeNotice` consecutive
+ * occurrences.
+ *
+ * THIS MODULE IS REACHED ONLY THROUGH A DYNAMIC `import()` (section 3.8 / D-25).
+ * `runOneShot` and `runInteractive` live in the same `cli.tsx` module and there
+ * is no bundler (C-16), so a static import here would put the whole subsystem in
+ * `dist/cli.js`'s graph and `aragon -p` would evaluate every module under
+ * `update/`.
+ */
+import type { ScopedLogger } from '../logging/logger.js';
+import type { UpdateConfig } from '../config/schema.js';
+import { type NpmViewDeps } from './npm-view.js';
+import { type InstallDeps, type SpawnImpl } from './installer.js';
+import type { InstallSource, UpdateCommandPort, UpdateSnapshot } from './types.js';
+/** A timer handle we only ever cancel and `unref`. */
+interface TimerHandle {
+    unref?: () => void;
+}
+export interface UpdateServiceDeps {
+    config: UpdateConfig;
+    /** The running version - `cli.tsx`'s `VERSION`. */
+    currentVersion: string;
+    now?: () => number;
+    fetchImpl?: typeof fetch;
+    spawnImpl?: SpawnImpl;
+    logger?: ScopedLogger;
+    env?: NodeJS.ProcessEnv;
+    /** `process.versions.node`, injected so every engine test is offline. */
+    nodeVersion?: string;
+    /** Overrides `selfPackageRoot()`; tests point it at a synthetic tree. */
+    packageRoot?: string | null;
+    /** Overrides the name read from `<root>/package.json`. */
+    packageName?: string;
+    /** Pre-resolved classification, so a test need not build a real tree. */
+    source?: InstallSource;
+    setTimeoutImpl?: (fn: () => void, ms: number) => TimerHandle;
+    clearTimeoutImpl?: (handle: TimerHandle) => void;
+    /** Deterministic jitter for tests. */
+    random?: () => number;
+    /** Forwarded to `runNpmInstall` and `tryAcquireInstallLock`. */
+    install?: InstallDeps;
+    /** Forwarded to `fetchLatestViaNpm`, so no test spawns npm (H3). */
+    npmView?: NpmViewDeps;
+    lockPath?: string;
+    isProcessAlive?: (pid: number) => boolean;
+}
+type Listener = (snapshot: UpdateSnapshot) => void;
+export declare class UpdateService implements UpdateCommandPort {
+    private readonly deps;
+    private readonly now;
+    private readonly log;
+    private readonly listeners;
+    private phase;
+    private latestVersion;
+    private reason;
+    private advice;
+    /** Set only on the `node-too-old` path; both, or neither (section 6.2). */
+    private requiredNode;
+    private runningNode;
+    private nextAt;
+    private failures;
+    /**
+     * The rollback notice, held for THIS SESSION and cleared from the file the
+     * first time it is read (section 5.2a / D-38). Both, or neither.
+     */
+    private rolledBackFrom;
+    private rolledBackTo;
+    /** What `aragon update --rollback` would reinstall, for `/update status`. */
+    private lastGoodVersion;
+    /** Which probe answered the last successful check (H3). */
+    private probe;
+    private timer;
+    private started;
+    private disposed;
+    private inFlight;
+    private resolved;
+    constructor(deps: UpdateServiceDeps);
+    /**
+     * Schedule the first check. Idempotent.
+     *
+     * The first check fires `UPDATE_LIMITS.startupDelayMs` after this call so it
+     * can never contend with first paint, and every timer is `unref()`ed so a
+     * pending check never keeps `aragon` from exiting.
+     */
+    start(): void;
+    snapshot(): UpdateSnapshot;
+    subscribe(fn: Listener): () => void;
+    nextCheckAt(): number | null;
+    /**
+     * Run a check now, subject to the machine-wide throttle unless forced.
+     *
+     * SINGLE-FLIGHT. Two `/update now` in a row, or a slash command landing on top
+     * of the scheduled tick, must produce one registry request and one install -
+     * the in-process half of what `lastCheckAt` does across processes.
+     */
+    checkNow(opts?: {
+        force?: boolean;
+    }): Promise<UpdateSnapshot>;
+    /**
+     * Install a specific version now, bypassing the decision gates.
+     *
+     * The explicit escape hatch behind `aragon update --to <version>` (non-goal 4:
+     * there is no AUTOMATIC downgrade, but a deliberate one is exactly what a user
+     * needs when a release misbehaves).
+     */
+    installNow(version?: string): Promise<UpdateSnapshot>;
+    /** Persist `skippedVersion`; the line disappears until a newer one appears. */
+    skip(version: string): void;
+    /**
+     * Clear timers and drop listeners. NEVER KILLS THE INSTALLER CHILD (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 `dispose()` is called
+     * by the most ordinary event there is - the user pressing Ctrl+C. The child is
+     * detached and `unref()`ed precisely so it can finish without us.
+     *
+     * Idempotent, and called on BOTH of `runInteractive`'s teardown branches.
+     */
+    dispose(): void;
+    private cancelTimer;
+    /**
+     * Arm the next check.
+     *
+     * The jitter is not decoration (D-12 / R-6): machine fleets started by the
+     * same automation otherwise arrive at the registry together, and the throttle
+     * in `update-state.json` only de-duplicates within ONE machine.
+     */
+    private schedule;
+    /** `backoffBaseMs * 2^(n-1)`, capped. `n` is the consecutive-failure count. */
+    private backoffMs;
+    private scheduleNext;
+    private setPhase;
+    /**
+     * Step 11 of the happy path: the new version is now the running one, so the
+     * pending marker has served its purpose.
+     *
+     * Silent by design - the user restarted, which is the acknowledgement. The log
+     * record is what makes "when did this machine actually pick up 0.6.0"
+     * answerable after the fact.
+     */
+    private reconcilePendingRestart;
+    /**
+     * Read the rollback notice, hold it for this session, and clear the file
+     * (cli-auto-update-hardening section 5.2a / D-38 / D-40).
+     *
+     * CONSUMING ON READ IS WHAT MAKES "ONE SESSION" TRUE WITHOUT A SECOND
+     * TIMESTAMP. It also means a launch that never constructs a service -
+     * `update.mode: 'off'`, a non-TTY, CI - does NOT burn the notice, so it
+     * survives to the first session that could actually have shown it.
+     *
+     * `rolledBackTo` is the running version and is therefore DERIVED, not stored:
+     * we are, by definition, the target of the rollback that wrote this field. The
+     * "both or neither" rule the pair inherits from `requiredNode` / `runningNode`
+     * is satisfied by construction rather than by discipline.
+     *
+     * `lastGoodVersion` is picked up in the same read - it is what
+     * `aragon update --rollback` would reinstall, and `/update status` is the only
+     * place a user can find that out before running the command.
+     */
+    private consumeRollbackNotice;
+    /** Classify this installation once. Cheap, but it stats the filesystem. */
+    private resolve;
+    private runCheck;
+    /**
+     * Report an available version without installing it.
+     *
+     * `dev-monorepo` and `npx` are SILENT even here (AC-6 / AC-7): a developer's
+     * clone is not out of date, it is checked out, and `npx` resolved `latest`
+     * seconds ago. Both fall back to `idle`, which `shouldRenderUpdateLine`
+     * answers `false` for.
+     */
+    private offer;
+    private performInstall;
+    private recordFailure;
+    private clearFailures;
+}
+export {};