@aragon-agent/cli 0.5.9 → 0.5.11

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 {};