@ozzylabs/feedradar 0.1.3 → 0.1.5

package/dist/agents/types.d.ts

@@ -1,4 +1,21 @@
 import type { AgentId, Item, ResearchFrontmatter } from "../schemas/index.js";
+/**
+ * Low-level stream pass-through callback (ADR-0015 D3).
+ *
+ * Adapters wire this to each `child.stdout` / `child.stderr` `"data"` chunk
+ * so the caller (`research` / `review` / `update` CLI in #197) can keep a
+ * `ProgressReporter` ticking — e.g. update `stdout: 4.2 KB` on the spinner
+ * row, or stream the chunk verbatim under `--verbose`.
+ *
+ * Stays at the lowest level (raw chunk text) so the adapter contract does
+ * not have to know about the `ProgressReporter` shape; callers translate
+ * chunks into reporter calls. `kind` distinguishes streams because some
+ * callers render stderr differently (warning colour, separate buffer).
+ *
+ * Optional everywhere: leaving `onProgress` unset is byte-equivalent to the
+ * pre-#196 adapter behaviour.
+ */
+export type AgentProgressCallback = (kind: "stdout" | "stderr", text: string) => void;
 export interface ResearchRequest {
     agent: AgentId;
     templateId: string;
@@ -13,6 +30,12 @@ export interface ResearchRequest {
      * `research/`, and resolve relative paths the same way the CLI does.
      */
     cwd: string;
+    /**
+     * Optional progress callback. Invoked once per `stdout` / `stderr` chunk
+     * from the spawned agent CLI. Unset means "no progress reporting"
+     * (#196 forward-compat: existing call sites work unchanged).
+     */
+    onProgress?: AgentProgressCallback;
 }
 /**
  * Inputs for the `review` adapter method.
@@ -48,6 +71,11 @@ export interface ReviewRequest {
      * `items/`, `sources/`, etc. with relative paths.
      */
     cwd: string;
+    /**
+     * Optional progress callback. See {@link AgentProgressCallback} /
+     * {@link ResearchRequest.onProgress}.
+     */
+    onProgress?: AgentProgressCallback;
 }
 /**
  * Inputs for the `update` adapter method.
@@ -93,6 +121,11 @@ export interface UpdateRequest {
      * `items/`, `sources/`, etc. with relative paths.
      */
     cwd: string;
+    /**
+     * Optional progress callback. See {@link AgentProgressCallback} /
+     * {@link ResearchRequest.onProgress}.
+     */
+    onProgress?: AgentProgressCallback;
 }
 export interface AgentAdapter {
     id: AgentId;

package/dist/agents/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE9E,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,mBAAmB,EAAE,mBAAmB,CAAC;IACzC,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,YAAY,EAAE;QACZ,WAAW,EAAE,mBAAmB,CAAC;QACjC,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,4EAA4E;IAC5E,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,MAAM,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE9E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAEtF,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,UAAU,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,mBAAmB,EAAE,mBAAmB,CAAC;IACzC,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,UAAU,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,YAAY,EAAE;QACZ,WAAW,EAAE,mBAAmB,CAAC;QACjC,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,4EAA4E;IAC5E,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,UAAU,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,MAAM,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C"}

package/dist/cli/_progress.d.ts

@@ -0,0 +1,138 @@
+import type { AgentProgressCallback } from "../agents/types.js";
+import { noopProgressReporter, type ProgressLevel, type ProgressReporter } from "../core/progress.js";
+/**
+ * Shared progress helpers for `radar research` / `review` / `update`.
+ *
+ * #197 wires `ProgressReporter` (ADR-0015) into the three agent-driven CLIs.
+ * The CLIs each follow the same phase-marker sequence (Loaded item / Loaded
+ * template / Spawning / Agent running / Agent completed / Frontmatter
+ * validated / Status transition), so the boilerplate lives here:
+ *
+ * - {@link parseProgressFlags} normalises `--verbose` / `--quiet` parsing
+ *   (extracting them from `argv` so the per-command `parseArgs` sees a clean
+ *   array)
+ * - {@link buildReporter} centralises the priority chain `RADAR_NO_PROGRESS=1`
+ *   > `--quiet` > `--verbose` > default. The reporter writes to `stderr` so it
+ *   never collides with the existing `io.log()` / `io.warn()` / `io.error()`
+ *   sinks that tests inject (those still drive stdout-like channels).
+ * - {@link buildAgentProgressCallback} adapts the adapter's
+ *   {@link AgentProgressCallback} (which receives raw stdout/stderr chunks)
+ *   into reporter calls. It tracks cumulative stdout bytes so the spinner row
+ *   shows `stdout: 4.2 KB`, and forwards chunks verbatim via `reporter.raw()`
+ *   when the reporter is in verbose mode.
+ * - {@link pollOutputFileSize} starts a 500ms `fs.stat` poll so the spinner
+ *   row can show how big the agent's output file is growing. The agent CLIs
+ *   write the report to disk as they go (or atomically at the end); polling
+ *   the file size is the only stream-agnostic way to surface "something is
+ *   actually happening" because most agent runners only emit chatty stdout
+ *   for tool calls, not for the report body itself.
+ *
+ * Naming convention follows ADR-0015 D4: every phase marker uses the verb-
+ * forms documented there (`Loaded …`, `Spawning …`, `Agent running…`,
+ * `Agent completed (…)`, `Status: … → …`).
+ */
+export interface ProgressFlagState {
+    /** Argv with `--verbose` / `--quiet` stripped. */
+    rest: string[];
+    /** Resolved verbosity level. */
+    level: ProgressLevel;
+    /** Saw `--verbose` flag explicitly. */
+    verbose: boolean;
+    /** Saw `--quiet` flag explicitly. */
+    quiet: boolean;
+}
+export declare class ProgressFlagError extends Error {
+    constructor(message: string);
+}
+/**
+ * Strip `--verbose` / `--quiet` from `argv` and return the resolved
+ * {@link ProgressLevel} plus the remaining argv for the command's own parser.
+ *
+ * Mutually exclusive: passing both raises {@link ProgressFlagError} so the
+ * caller can convert it into an exit-code-2 usage error consistent with the
+ * existing `parseArgs` style. `RADAR_NO_PROGRESS=1` is honoured at reporter
+ * construction time (see {@link buildReporter}); we do not mix env handling
+ * into argv parsing because env is global and argv is per-invocation.
+ */
+export declare function parseProgressFlags(argv: string[]): ProgressFlagState;
+export interface BuildReporterOptions {
+    level: ProgressLevel;
+    /** Test-only TTY override. Falls back to `process.stderr.isTTY` at runtime. */
+    tty?: boolean;
+    /** Test-only output stream override. Defaults to `process.stderr`. */
+    stream?: NodeJS.WritableStream;
+}
+/**
+ * Construct a {@link ProgressReporter} for a CLI invocation. Thin wrapper
+ * around {@link createProgressReporter} that records the helper's existence
+ * for grep-discoverability — production callers route through here so the
+ * defaulting logic stays in one place.
+ *
+ * `level: "quiet"` and `RADAR_NO_PROGRESS=1` both produce a no-op reporter
+ * (the env check happens inside `createProgressReporter`); the CLI keeps its
+ * pre-existing 1-line `io.log("research: wrote …")` summary as the only
+ * surviving signal, satisfying the issue's acceptance criterion 8.
+ */
+export declare function buildReporter(opts: BuildReporterOptions): ProgressReporter;
+/**
+ * Render a byte count for the spinner row. Uses binary prefixes (KiB / MiB)
+ * but renders them as `KB` / `MB` for readability — the spinner is a UX
+ * affordance, not a precise meter, and the ADR-0015 D4 examples show `4.2 KB`
+ * without binary-suffix pedantry.
+ */
+export declare function formatBytes(n: number): string;
+/**
+ * Bridge {@link AgentProgressCallback} (raw stdout / stderr chunks) to a
+ * {@link ProgressReporter}.
+ *
+ * On every chunk:
+ * - cumulative stdout byte count is folded into the spinner row via
+ *   `reporter.update({ stdout: "<formatted>" })`
+ * - `reporter.raw(text)` forwards the chunk verbatim. The reporter swallows
+ *   the call unless verbosity is `verbose`, so non-verbose callers pay only
+ *   the cost of the bridge function itself (no extra stderr writes).
+ *
+ * stderr chunks are also passed to `reporter.raw()` so `--verbose` users see
+ * agent CLI warnings inline. They don't update the `stdout:` metric (that
+ * key is intentionally tied to actual stdout volume so the spinner row stays
+ * comparable across runs).
+ */
+export declare function buildAgentProgressCallback(reporter: ProgressReporter): AgentProgressCallback;
+export interface OutputSizePollHandle {
+    /** Stop the poll loop. Safe to call multiple times. */
+    stop: () => void;
+}
+export interface OutputSizePollOptions {
+    /** Path to `fs.stat`. The agent should be writing here. */
+    path: string;
+    reporter: ProgressReporter;
+    /** Poll interval in milliseconds (default 500ms per ADR-0015 D5 / #197). */
+    intervalMs?: number;
+    /**
+     * Metric key on the spinner row. Defaults to `output` so the row reads
+     * `output: 4.2 KB`. Tests override for deterministic assertions.
+     */
+    metricKey?: string;
+}
+/**
+ * Poll the agent's output file with `fs.stat` every 500ms (configurable) and
+ * push the latest size onto the spinner row.
+ *
+ * Why polling instead of `fs.watch`: `fs.watch` is platform-flaky (Linux
+ * needs inotify, macOS uses FSEvents, WSL has its own quirks) and the agent
+ * may write atomically at the end with no intermediate `change` events. A
+ * 500ms `fs.stat` poll is reliable everywhere and the cost (one syscall per
+ * tick) is negligible next to the agent CLI spawn.
+ *
+ * The poll silently ignores `ENOENT` because the agent writes the file part-
+ * way through the run; we only start showing sizes once the file exists. Any
+ * other stat error is also swallowed (best-effort UX, the reporter must
+ * never abort the actual research operation).
+ */
+export declare function pollOutputFileSize(opts: OutputSizePollOptions): OutputSizePollHandle;
+/**
+ * Convenience: return a no-op reporter typed as a {@link ProgressReporter}.
+ * Re-exported here so CLI modules don't have to import from two places.
+ */
+export { noopProgressReporter };
+//# sourceMappingURL=_progress.d.ts.map

package/dist/cli/_progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_progress.d.ts","sourceRoot":"","sources":["../../src/cli/_progress.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAEL,oBAAoB,EACpB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,gCAAgC;IAChC,KAAK,EAAE,aAAa,CAAC;IACrB,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,qCAAqC;IACrC,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,iBAAiB,CAuBpE;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,aAAa,CAAC;IACrB,+EAA+E;IAC/E,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;CAChC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,gBAAgB,CAM1E;AAKD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAI7C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,gBAAgB,GAAG,qBAAqB,CAS5F;AAED,MAAM,WAAW,oBAAoB;IACnC,uDAAuD;IACvD,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,qBAAqB,GAAG,oBAAoB,CAgDpF;AAED;;;GAGG;AACH,OAAO,EAAE,oBAAoB,EAAE,CAAC"}

package/dist/cli/_progress.js

@@ -0,0 +1,176 @@
+import { stat } from "node:fs/promises";
+import { createProgressReporter, noopProgressReporter, } from "../core/progress.js";
+export class ProgressFlagError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ProgressFlagError";
+    }
+}
+/**
+ * Strip `--verbose` / `--quiet` from `argv` and return the resolved
+ * {@link ProgressLevel} plus the remaining argv for the command's own parser.
+ *
+ * Mutually exclusive: passing both raises {@link ProgressFlagError} so the
+ * caller can convert it into an exit-code-2 usage error consistent with the
+ * existing `parseArgs` style. `RADAR_NO_PROGRESS=1` is honoured at reporter
+ * construction time (see {@link buildReporter}); we do not mix env handling
+ * into argv parsing because env is global and argv is per-invocation.
+ */
+export function parseProgressFlags(argv) {
+    const rest = [];
+    let verbose = false;
+    let quiet = false;
+    for (const arg of argv) {
+        if (arg === "--verbose") {
+            verbose = true;
+            continue;
+        }
+        if (arg === "--quiet") {
+            quiet = true;
+            continue;
+        }
+        rest.push(arg);
+    }
+    if (verbose && quiet) {
+        throw new ProgressFlagError("--verbose and --quiet are mutually exclusive");
+    }
+    let level;
+    if (quiet)
+        level = "quiet";
+    else if (verbose)
+        level = "verbose";
+    else
+        level = "normal";
+    return { rest, level, verbose, quiet };
+}
+/**
+ * Construct a {@link ProgressReporter} for a CLI invocation. Thin wrapper
+ * around {@link createProgressReporter} that records the helper's existence
+ * for grep-discoverability — production callers route through here so the
+ * defaulting logic stays in one place.
+ *
+ * `level: "quiet"` and `RADAR_NO_PROGRESS=1` both produce a no-op reporter
+ * (the env check happens inside `createProgressReporter`); the CLI keeps its
+ * pre-existing 1-line `io.log("research: wrote …")` summary as the only
+ * surviving signal, satisfying the issue's acceptance criterion 8.
+ */
+export function buildReporter(opts) {
+    return createProgressReporter({
+        level: opts.level,
+        tty: opts.tty,
+        stream: opts.stream,
+    });
+}
+const KIB = 1024;
+const MIB = KIB * 1024;
+/**
+ * Render a byte count for the spinner row. Uses binary prefixes (KiB / MiB)
+ * but renders them as `KB` / `MB` for readability — the spinner is a UX
+ * affordance, not a precise meter, and the ADR-0015 D4 examples show `4.2 KB`
+ * without binary-suffix pedantry.
+ */
+export function formatBytes(n) {
+    if (n < KIB)
+        return `${n} B`;
+    if (n < MIB)
+        return `${(n / KIB).toFixed(1)} KB`;
+    return `${(n / MIB).toFixed(1)} MB`;
+}
+/**
+ * Bridge {@link AgentProgressCallback} (raw stdout / stderr chunks) to a
+ * {@link ProgressReporter}.
+ *
+ * On every chunk:
+ * - cumulative stdout byte count is folded into the spinner row via
+ *   `reporter.update({ stdout: "<formatted>" })`
+ * - `reporter.raw(text)` forwards the chunk verbatim. The reporter swallows
+ *   the call unless verbosity is `verbose`, so non-verbose callers pay only
+ *   the cost of the bridge function itself (no extra stderr writes).
+ *
+ * stderr chunks are also passed to `reporter.raw()` so `--verbose` users see
+ * agent CLI warnings inline. They don't update the `stdout:` metric (that
+ * key is intentionally tied to actual stdout volume so the spinner row stays
+ * comparable across runs).
+ */
+export function buildAgentProgressCallback(reporter) {
+    let stdoutBytes = 0;
+    return (kind, text) => {
+        if (kind === "stdout") {
+            stdoutBytes += Buffer.byteLength(text, "utf8");
+            reporter.update({ stdout: formatBytes(stdoutBytes) });
+        }
+        reporter.raw(text);
+    };
+}
+/**
+ * Poll the agent's output file with `fs.stat` every 500ms (configurable) and
+ * push the latest size onto the spinner row.
+ *
+ * Why polling instead of `fs.watch`: `fs.watch` is platform-flaky (Linux
+ * needs inotify, macOS uses FSEvents, WSL has its own quirks) and the agent
+ * may write atomically at the end with no intermediate `change` events. A
+ * 500ms `fs.stat` poll is reliable everywhere and the cost (one syscall per
+ * tick) is negligible next to the agent CLI spawn.
+ *
+ * The poll silently ignores `ENOENT` because the agent writes the file part-
+ * way through the run; we only start showing sizes once the file exists. Any
+ * other stat error is also swallowed (best-effort UX, the reporter must
+ * never abort the actual research operation).
+ */
+export function pollOutputFileSize(opts) {
+    const intervalMs = opts.intervalMs ?? 500;
+    const metricKey = opts.metricKey ?? "output";
+    let stopped = false;
+    let timer = null;
+    let lastReportedSize = -1;
+    const tick = async () => {
+        if (stopped)
+            return;
+        try {
+            const s = await stat(opts.path);
+            if (s.size !== lastReportedSize) {
+                lastReportedSize = s.size;
+                opts.reporter.update({ [metricKey]: formatBytes(s.size) });
+            }
+        }
+        catch {
+            // ENOENT during the early phase of the agent run, or transient stat
+            // failure — silently ignore so the spinner UX never crashes the real
+            // operation.
+        }
+    };
+    // First tick on next macrotask so callers can return the handle before the
+    // poll begins. setInterval also schedules; we add the immediate call so the
+    // spinner picks up an existing file without waiting a full interval.
+    const startup = setTimeout(() => {
+        if (!stopped) {
+            void tick();
+            timer = setInterval(() => {
+                void tick();
+            }, intervalMs);
+            // Don't keep the event loop alive just for the poll.
+            if (typeof timer.unref === "function") {
+                timer.unref();
+            }
+        }
+    }, 0);
+    if (typeof startup.unref === "function") {
+        startup.unref();
+    }
+    return {
+        stop() {
+            stopped = true;
+            clearTimeout(startup);
+            if (timer) {
+                clearInterval(timer);
+                timer = null;
+            }
+        },
+    };
+}
+/**
+ * Convenience: return a no-op reporter typed as a {@link ProgressReporter}.
+ * Re-exported here so CLI modules don't have to import from two places.
+ */
+export { noopProgressReporter };
+//# sourceMappingURL=_progress.js.map

package/dist/cli/_progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_progress.js","sourceRoot":"","sources":["../../src/cli/_progress.ts"],"names":[],"mappings":"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"}

package/dist/cli/doctor.d.ts

@@ -30,6 +30,26 @@ export interface DoctorCommandOptions {
      * what is actually installed on the host machine).
      */
     whichImpl?: (binary: string, env: NodeJS.ProcessEnv) => Promise<string | undefined>;
+    /**
+     * Skip the live proxy healthcheck (default: run the check when a proxy is
+     * detected). Off-line developer machines and CI jobs that intentionally
+     * isolate the network want a deterministic doctor run without paying for
+     * a network round-trip that is guaranteed to fail.
+     */
+    noProxyCheck?: boolean;
+    /**
+     * Test seam: override `fetch` used by the proxy healthcheck so the test can
+     * drive the 200 / 407 / TLS / ECONNREFUSED branches deterministically
+     * without hitting api.github.com.
+     */
+    fetchImpl?: typeof fetch;
+    /**
+     * Test seam: override the wall-clock used to measure the healthcheck
+     * latency. Returns an elapsed-milliseconds reading; we don't accept a raw
+     * clock function because vitest's `vi.useFakeTimers()` interferes with
+     * `performance.now()` in surprising ways.
+     */
+    nowImpl?: () => number;
 }
 /**
  * Possible statuses for a single doctor check.

package/dist/cli/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,YAAY,EAElB,MAAM,6BAA6B,CAAC;AAErC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,QAAQ,CAAC;IACd;;;OAGG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CACrF;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,MAAM,GAAG,OAAO,CAAC;AAEnD,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,EAAE,EAAE,MAAM,CAAC;IACX,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,oCAAoC;IACpC,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACtD;AA4DD;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,YAAY,CAAC,CA4H/F;AAqCD;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,MAAM,CAAC,CA2BjB;AAED,eAAO,MAAM,aAAa,EAAE,OAI3B,CAAC"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,YAAY,EAElB,MAAM,6BAA6B,CAAC;AAGrC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,QAAQ,CAAC;IACd;;;OAGG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACpF;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,MAAM,GAAG,OAAO,CAAC;AAEnD,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,EAAE,EAAE,MAAM,CAAC;IACX,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,oCAAoC;IACpC,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACtD;AA+FD;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,YAAY,CAAC,CAkO/F;AAkMD;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,MAAM,CAAC,CAiCjB;AAED,eAAO,MAAM,aAAa,EAAE,OAI3B,CAAC"}