@aragon-agent/cli 0.6.47 → 0.6.48

package/dist/update/semver.js

@@ -1,295 +0,0 @@
-/**
- * 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/types.d.ts

@@ -1,169 +0,0 @@
-/**
- * The updater's runtime shapes, plus the ONE pure predicate the renderer needs
- * (cli-auto-update sections 5.3 / 5.3a).
- *
- * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
- *
- * THE ONLY VALUE EXPORTED HERE IS `shouldRenderUpdateLine`. Everything else is a
- * type, so `ui/UpdateLine.tsx` and `commands/registry.ts` can import from this
- * module with `import type` and tsc erases the specifier entirely - no runtime
- * edge from the renderer or the command registry into `update/` (section 3.1
- * rule 1 / P1-7). This module and `limits.ts` import nothing but each other, are
- * side-effect-free, and open no socket, spawn no process and create no timer.
- */
-export type UpdatePhase = 'idle' | 'checking' | 'available' | 'installing' | 'ready' | 'failed';
-/**
- * How the running copy of `aragon` got onto this machine (section 3.2).
- *
- * `npm-global` is the ONLY value that may be auto-installed, because it is the
- * only one whose install target is unambiguous and verifiable from this machine
- * (D-5). Everything else is advice, not execution.
- */
-export type InstallSource = 'dev-monorepo' | 'npx' | 'pnpm' | 'yarn' | 'bun' | 'volta' | 'npm-local' | 'npm-global' | 'unknown';
-/** Why we are not installing, when we are not. Drives the advice line. */
-export type UpdateReason = 'up-to-date' | 'prerelease' | 'deprecated' | 'node-too-old' | 'skipped' | 'not-writable' | 'source-ineligible' | 'network' | 'install-failed' | 'locked'
-/** npm exited 0 but THIS root did not move - see U-6. */
- | 'install-ineffective'
-/** EPERM / EBUSY / ETXTBSY - something holds the file we must replace. */
- | 'blocked-by-os'
-/** ENOSPC. */
- | 'no-space';
-/** The slice of the registry's dist-tag document this feature reads. */
-export interface LatestManifest {
-    name: string;
-    version: string;
-    engines?: {
-        node?: string;
-    };
-    /** Present ONLY when the version is deprecated; the string is the reason. */
-    deprecated?: string;
-}
-export interface UpdateSnapshot {
-    phase: UpdatePhase;
-    currentVersion: string;
-    latestVersion: string | null;
-    source: InstallSource;
-    reason?: UpdateReason;
-    /** Copy-pasteable command for an ineligible source. */
-    advice?: string;
-    /**
-     * The `engines.node` range the offered version demands, and the Node actually
-     * running - set ONLY on the `node-too-old` path.
-     *
-     * They exist because section 6.2 specifies that row as
-     * `<warn> 0.6.0 needs Node >=20 (running 18.19.0)`, and neither number is
-     * derivable from anything else on this object. "Needs a newer Node" without
-     * saying WHICH is the kind of notice a user cannot act on, which is exactly
-     * what D-7 spends the rest of this feature avoiding (IF-2).
-     */
-    requiredNode?: string;
-    runningNode?: string;
-    /**
-     * Set for the WHOLE session after a rollback, and deliberately NOT a `reason`
-     * (cli-auto-update-hardening section 5.2a / D-39).
-     *
-     * `reason` is rewritten by `setPhase` on EVERY transition, so the first
-     * scheduled check three seconds into the session would erase it before anyone
-     * read it. A fact that is true for a whole session needs a carrier the state
-     * machine does not own.
-     *
-     * BOTH, OR NEITHER, on the `requiredNode` / `runningNode` precedent above -
-     * half the pair is a notice nobody can read. Here it holds BY CONSTRUCTION
-     * rather than by discipline: `rolledBackTo` is the running version, assigned
-     * in the same two lines that read `rolledBackFrom` out of the state file.
-     */
-    rolledBackFrom?: string;
-    rolledBackTo?: string;
-    /**
-     * What `aragon update --rollback` would reinstall, read from the state file.
-     *
-     * On the snapshot rather than derived because `/update status` is the only
-     * place a user can find out what that command would DO before running it
-     * (section 6.3). See IF-1 in the hardening spec.
-     */
-    lastGoodVersion?: string;
-    /** Which probe answered the last successful check (H3). */
-    probe?: 'http' | 'npm';
-    nextCheckAt: number | null;
-    consecutiveFailures: number;
-}
-export type UpdateEvent = {
-    type: 'phase';
-    snapshot: UpdateSnapshot;
-} | {
-    type: 'log';
-    level: 'info' | 'warn';
-    msg: string;
-};
-/**
- * The narrow surface `/update` sees (section 4.4 / C-14 / P0-2).
- *
- * `CommandContext` carries this rather than the service itself, and carries it
- * as an OPTIONAL member: the service is legitimately absent under
- * `update.mode: 'off'`, on a non-TTY and in CI, and a required field would break
- * every existing `CommandContext` fixture at compile time.
- *
- * `UpdateService` satisfies it STRUCTURALLY, so nothing implements it explicitly
- * and there is no adapter to keep in sync.
- */
-export interface UpdateCommandPort {
-    snapshot(): UpdateSnapshot;
-    checkNow(opts?: {
-        force?: boolean;
-    }): Promise<UpdateSnapshot>;
-    skip(version: string): void;
-    nextCheckAt(): number | null;
-}
-/** What the renderer needs on top of the command port: a subscription. */
-export interface UpdateServiceHandle extends UpdateCommandPort {
-    subscribe(fn: (snapshot: UpdateSnapshot) => void): () => void;
-}
-/**
- * The late-arrival channel between `cli.tsx` and `App` (IF-4).
- *
- * The service is constructed through a DYNAMIC `import()` fired AFTER
- * `render()` (section 3.8 / D-25), so it does not exist when `App` mounts and
- * cannot be an ordinary prop. This is the same shape `ConfirmBridge` and
- * `HumanInputBridge` already use for exactly the same reason: a mutable object
- * created before `render()`, populated by whichever side arrives second.
- *
- * A PLAIN INTERFACE AND NOT A CLASS, so `cli.tsx` builds one with an object
- * literal and needs no runtime import from `update/` (AC-1).
- */
-export interface UpdateBridge {
-    /** Set once the dynamically-imported service exists; `null` until then. */
-    service: UpdateServiceHandle | null;
-    /** Set by `App` on mount, so a service that arrives later can wake it. */
-    onAttach: ((service: UpdateServiceHandle) => void) | null;
-}
-/**
- * The reasons allowed to break the three-strike silence rule (D-7 / D-33),
- * because each is both ACTIONABLE BY THE USER and NOT SELF-HEALING.
- *
- * THE MEMBERSHIP RULE IS THE WHOLE MECHANISM, not the list. `network` fails both
- * halves - the user cannot fix the registry and the next check may well succeed -
- * so it stays silent and backs off, which is the entire reason a background
- * updater is tolerable at all. The three below will otherwise repeat identically
- * until the user does something, which is the definition of a notice worth
- * showing once. Anything added here without passing both halves is the first
- * step of the notification fatigue the rest of this feature is built to avoid
- * (R-20).
- */
-export declare const IMMEDIATE_NOTICE_REASONS: ReadonlySet<UpdateReason>;
-/**
- * Whether the bottom row has anything to say. PURE, and deliberately NOT
- * expressed as `UpdateLine` returning `null` (C-15 / P0-1 / D-19).
- *
- * A component that returns `null` still satisfies `if (update)` at the call site
- * - the prop is a React ELEMENT, and an element is truthy however it renders.
- * The row would become `<Box flexShrink={0}>{nothing}</Box>`, which in
- * full-screen is ZERO rows, and the transcript silently gains a row for as long
- * as the updater is idle and loses it again the moment it has news. That is
- * precisely the layout shift `BottomStatusRow` exists to prevent, and
- * `bottom-status-row.test.tsx`'s "holds one row in all four states" is the
- * assertion it would defeat.
- *
- * `ActivityLine` already settles the pattern: it ALWAYS returns an element, and
- * `App.tsx` decides presence at the call site with `running && !overlayNode`.
- */
-export declare function shouldRenderUpdateLine(snapshot: UpdateSnapshot): boolean;

package/dist/update/types.js

@@ -1,68 +0,0 @@
-/**
- * The updater's runtime shapes, plus the ONE pure predicate the renderer needs
- * (cli-auto-update sections 5.3 / 5.3a).
- *
- * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
- *
- * THE ONLY VALUE EXPORTED HERE IS `shouldRenderUpdateLine`. Everything else is a
- * type, so `ui/UpdateLine.tsx` and `commands/registry.ts` can import from this
- * module with `import type` and tsc erases the specifier entirely - no runtime
- * edge from the renderer or the command registry into `update/` (section 3.1
- * rule 1 / P1-7). This module and `limits.ts` import nothing but each other, are
- * side-effect-free, and open no socket, spawn no process and create no timer.
- */
-import { UPDATE_LIMITS } from './limits.js';
-/**
- * The reasons allowed to break the three-strike silence rule (D-7 / D-33),
- * because each is both ACTIONABLE BY THE USER and NOT SELF-HEALING.
- *
- * THE MEMBERSHIP RULE IS THE WHOLE MECHANISM, not the list. `network` fails both
- * halves - the user cannot fix the registry and the next check may well succeed -
- * so it stays silent and backs off, which is the entire reason a background
- * updater is tolerable at all. The three below will otherwise repeat identically
- * until the user does something, which is the definition of a notice worth
- * showing once. Anything added here without passing both halves is the first
- * step of the notification fatigue the rest of this feature is built to avoid
- * (R-20).
- */
-export const IMMEDIATE_NOTICE_REASONS = new Set([
-    'blocked-by-os',
-    'no-space',
-    'not-writable',
-]);
-/**
- * Whether the bottom row has anything to say. PURE, and deliberately NOT
- * expressed as `UpdateLine` returning `null` (C-15 / P0-1 / D-19).
- *
- * A component that returns `null` still satisfies `if (update)` at the call site
- * - the prop is a React ELEMENT, and an element is truthy however it renders.
- * The row would become `<Box flexShrink={0}>{nothing}</Box>`, which in
- * full-screen is ZERO rows, and the transcript silently gains a row for as long
- * as the updater is idle and loses it again the moment it has news. That is
- * precisely the layout shift `BottomStatusRow` exists to prevent, and
- * `bottom-status-row.test.tsx`'s "holds one row in all four states" is the
- * assertion it would defeat.
- *
- * `ActivityLine` already settles the pattern: it ALWAYS returns an element, and
- * `App.tsx` decides presence at the call site with `running && !overlayNode`.
- */
-export function shouldRenderUpdateLine(snapshot) {
-    if (snapshot.phase === 'available' ||
-        snapshot.phase === 'installing' ||
-        snapshot.phase === 'ready') {
-        return true;
-    }
-    if (snapshot.phase === 'failed') {
-        if (snapshot.reason && IMMEDIATE_NOTICE_REASONS.has(snapshot.reason))
-            return true;
-        return snapshot.consecutiveFailures >= UPDATE_LIMITS.failuresBeforeNotice;
-    }
-    // `idle` / `checking` - the two phases the user must never be told about,
-    // EXCEPT for a rollback this session has not yet reported. Placed LAST on
-    // purpose: any real news above owns the row first, and the budget is one row
-    // (C-15). It is therefore possible for the notice never to appear on a machine
-    // that has an update waiting on the very next launch, which is the correct
-    // trade - the newer fact is the more actionable one, and the rollback is still
-    // in `/update status` and in the log.
-    return Boolean(snapshot.rolledBackFrom);
-}