@ozzylabs/feedradar 0.1.3 → 0.1.5

package/dist/core/progress.d.ts

@@ -0,0 +1,101 @@
+/**
+ * ProgressReporter — UX abstraction for long-running CLI operations.
+ *
+ * Implements [ADR-0015 Progress Reporting UX](../../docs/adr/0015-progress-reporting-ux.md):
+ *
+ * - 3-layer model (phase markers / heartbeat spinner / side metrics)
+ * - TTY auto-detection with env / flag overrides (`RADAR_NO_PROGRESS=1`,
+ *   `--quiet`, `--verbose`)
+ * - CI / non-TTY safe degradation: spinner becomes plain text and `\r`
+ *   same-line updates are disabled
+ * - Zero new runtime dependencies — the spinner frame set
+ *   (`⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏`) is rotated by an internal `setInterval` and rendered via
+ *   `process.stderr.write` + ANSI escape `\x1b[K\r`
+ *
+ * This is the **base** (#196) — only the interface, the factory, and the
+ * default reporter implementation. CLI integration (`research` / `review` /
+ * `update`) ships in #197, feed adapter integration in #198. Adapter call
+ * sites in `src/agents/*.ts` consume the optional `onProgress` callback
+ * defined alongside this module (see `src/agents/types.ts`).
+ */
+export type ProgressLevel = "quiet" | "normal" | "verbose";
+/**
+ * Public API surface used by CLI / adapter integrations. Six methods cover
+ * the three UX layers from ADR-0015:
+ *
+ * - `phase`: structured milestone, always rendered (TTY and non-TTY)
+ * - `start` / `succeed` / `fail`: spinner lifecycle for a single sub-task.
+ *   On TTY, `start` begins same-line spinner animation; `succeed` / `fail`
+ *   stop it and emit a single completion line.
+ * - `update`: side metrics (page x/N, stdout bytes, ...) — merged into the
+ *   spinner row on TTY, suppressed or printed as plain text on non-TTY
+ * - `raw`: agent stdout / stderr pass-through. Only printed in `verbose`
+ *   level. Default reporter pipes the chunk to `process.stderr` verbatim.
+ */
+export interface ProgressReporter {
+    /** Structured milestone. e.g. `"Spawning claude-code"` */
+    phase(name: string, info?: string): void;
+    /** Begin a spinner-tracked sub-task. e.g. `"Agent running…"` */
+    start(label: string): void;
+    /** Update side metrics for the active spinner row. */
+    update(metrics: Record<string, string>): void;
+    /** Stop the spinner and emit a success line. `duration` is milliseconds. */
+    succeed(label: string, duration?: number): void;
+    /** Stop the spinner and emit a failure line. */
+    fail(label: string, reason: string): void;
+    /** Pass-through agent stdout / stderr text (verbose only). */
+    raw(text: string): void;
+}
+export interface CreateProgressReporterOptions {
+    /**
+     * TTY override. If unspecified, falls back to `process.stderr.isTTY`.
+     * Always overridable so tests can pin the value.
+     */
+    tty?: boolean;
+    /** Verbosity. `quiet` = phase markers off; `verbose` = `raw()` enabled. */
+    level: ProgressLevel;
+    /**
+     * Output stream. Defaults to `process.stderr` so progress does not pollute
+     * piped stdout (`radar research > out.md`). Tests pass an in-memory stream.
+     */
+    stream?: NodeJS.WritableStream;
+    /**
+     * Heartbeat interval in milliseconds (default 1000ms / 1s). Tests can
+     * shorten this to verify spinner rotation without burning real time.
+     * Negative or zero disables the heartbeat (still renders a static first
+     * frame on `start`).
+     */
+    heartbeatMs?: number;
+    /** `Date.now()` override for deterministic elapsed-time rendering. */
+    now?: () => number;
+}
+/**
+ * No-op reporter. Used by:
+ *
+ * - tests that do not care about progress output
+ * - `--quiet` / `RADAR_NO_PROGRESS=1` paths (see `createProgressReporter`)
+ * - adapter call sites where the caller did not opt into progress
+ *
+ * All six methods return immediately so wiring a `noopProgressReporter()` to
+ * an existing adapter is byte-equivalent to passing `undefined`.
+ */
+export declare function noopProgressReporter(): ProgressReporter;
+/**
+ * Construct a `ProgressReporter` honouring the ADR-0015 D2 priority table:
+ *
+ *   env (`RADAR_NO_PROGRESS=1`) > flag (`level`) > TTY auto-detect
+ *
+ * - `level: "quiet"` → no-op (callers want zero output)
+ * - `RADAR_NO_PROGRESS=1` → no-op (CI escape hatch)
+ * - non-TTY + `level: "normal"` → plain text (phase markers + completion
+ *   lines, NO spinner animation, NO `\r` overwrite)
+ * - TTY + `level: "normal"` → phase markers + spinner + same-line update
+ * - `level: "verbose"` → phase markers + spinner (if TTY) + `raw()` pass-
+ *   through enabled (regardless of TTY)
+ *
+ * The reporter is self-contained: callers should not depend on internal
+ * state (e.g. the active spinner timer). The contract is the 6-method
+ * interface above.
+ */
+export declare function createProgressReporter(opts: CreateProgressReporterOptions): ProgressReporter;
+//# sourceMappingURL=progress.d.ts.map

package/dist/core/progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../src/core/progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE3D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,gEAAgE;IAChE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,sDAAsD;IACtD,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC9C,4EAA4E;IAC5E,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,gDAAgD;IAChD,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,8DAA8D;IAC9D,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,6BAA6B;IAC5C;;;OAGG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,2EAA2E;IAC3E,KAAK,EAAE,aAAa,CAAC;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC/B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAKD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,IAAI,gBAAgB,CASvD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,6BAA6B,GAAG,gBAAgB,CA8I5F"}

package/dist/core/progress.js

@@ -0,0 +1,212 @@
+/**
+ * ProgressReporter — UX abstraction for long-running CLI operations.
+ *
+ * Implements [ADR-0015 Progress Reporting UX](../../docs/adr/0015-progress-reporting-ux.md):
+ *
+ * - 3-layer model (phase markers / heartbeat spinner / side metrics)
+ * - TTY auto-detection with env / flag overrides (`RADAR_NO_PROGRESS=1`,
+ *   `--quiet`, `--verbose`)
+ * - CI / non-TTY safe degradation: spinner becomes plain text and `\r`
+ *   same-line updates are disabled
+ * - Zero new runtime dependencies — the spinner frame set
+ *   (`⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏`) is rotated by an internal `setInterval` and rendered via
+ *   `process.stderr.write` + ANSI escape `\x1b[K\r`
+ *
+ * This is the **base** (#196) — only the interface, the factory, and the
+ * default reporter implementation. CLI integration (`research` / `review` /
+ * `update`) ships in #197, feed adapter integration in #198. Adapter call
+ * sites in `src/agents/*.ts` consume the optional `onProgress` callback
+ * defined alongside this module (see `src/agents/types.ts`).
+ */
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const ANSI_CLEAR_LINE = "\x1b[K";
+/**
+ * No-op reporter. Used by:
+ *
+ * - tests that do not care about progress output
+ * - `--quiet` / `RADAR_NO_PROGRESS=1` paths (see `createProgressReporter`)
+ * - adapter call sites where the caller did not opt into progress
+ *
+ * All six methods return immediately so wiring a `noopProgressReporter()` to
+ * an existing adapter is byte-equivalent to passing `undefined`.
+ */
+export function noopProgressReporter() {
+    return {
+        phase() { },
+        start() { },
+        update() { },
+        succeed() { },
+        fail() { },
+        raw() { },
+    };
+}
+/**
+ * Construct a `ProgressReporter` honouring the ADR-0015 D2 priority table:
+ *
+ *   env (`RADAR_NO_PROGRESS=1`) > flag (`level`) > TTY auto-detect
+ *
+ * - `level: "quiet"` → no-op (callers want zero output)
+ * - `RADAR_NO_PROGRESS=1` → no-op (CI escape hatch)
+ * - non-TTY + `level: "normal"` → plain text (phase markers + completion
+ *   lines, NO spinner animation, NO `\r` overwrite)
+ * - TTY + `level: "normal"` → phase markers + spinner + same-line update
+ * - `level: "verbose"` → phase markers + spinner (if TTY) + `raw()` pass-
+ *   through enabled (regardless of TTY)
+ *
+ * The reporter is self-contained: callers should not depend on internal
+ * state (e.g. the active spinner timer). The contract is the 6-method
+ * interface above.
+ */
+export function createProgressReporter(opts) {
+    // Env escape hatch (D2 table row 1). Honoured even at `level: "verbose"`
+    // — CI environments must be able to opt out unconditionally.
+    if (process.env.RADAR_NO_PROGRESS === "1") {
+        return noopProgressReporter();
+    }
+    if (opts.level === "quiet") {
+        return noopProgressReporter();
+    }
+    const tty = opts.tty ?? Boolean(process.stderr.isTTY);
+    const stream = opts.stream ?? process.stderr;
+    const heartbeatMs = opts.heartbeatMs ?? 1000;
+    const now = opts.now ?? Date.now;
+    const verbose = opts.level === "verbose";
+    // Active spinner state. `null` means no spinner is running.
+    let active = null;
+    function renderSpinnerRow() {
+        if (!active)
+            return "";
+        const elapsedSec = Math.max(0, Math.floor((now() - active.startedAt) / 1000));
+        const mm = String(Math.floor(elapsedSec / 60)).padStart(2, "0");
+        const ss = String(elapsedSec % 60).padStart(2, "0");
+        const frame = SPINNER_FRAMES[active.frame % SPINNER_FRAMES.length];
+        const metricEntries = Object.entries(active.metrics);
+        const metricsSuffix = metricEntries.length > 0 ? `  ${metricEntries.map(([k, v]) => `${k}: ${v}`).join("  ")}` : "";
+        return `${frame} ${active.label} [${mm}:${ss}]${metricsSuffix}`;
+    }
+    function repaint() {
+        if (!active)
+            return;
+        if (tty) {
+            stream.write(`\r${ANSI_CLEAR_LINE}${renderSpinnerRow()}`);
+        }
+    }
+    function clearSpinnerLine() {
+        if (tty && active) {
+            stream.write(`\r${ANSI_CLEAR_LINE}`);
+        }
+    }
+    function stopSpinner() {
+        if (active?.timer) {
+            clearInterval(active.timer);
+        }
+        active = null;
+    }
+    return {
+        phase(name, info) {
+            // Phase markers always claim their own line; clear any active spinner
+            // overwrite first so we don't leave a half-painted row in scrollback.
+            clearSpinnerLine();
+            const suffix = info ? ` (${info})` : "";
+            stream.write(`${name}${suffix}\n`);
+            // Re-paint the spinner row on the new line so it continues to update.
+            repaint();
+        },
+        start(label) {
+            // If a previous spinner was still active, drop it silently — the new
+            // start supersedes it (caller bug, but we don't want to crash).
+            clearSpinnerLine();
+            stopSpinner();
+            active = {
+                label,
+                startedAt: now(),
+                frame: 0,
+                metrics: {},
+                timer: null,
+            };
+            if (tty) {
+                // Paint frame 0 immediately so the user sees something before the
+                // first heartbeat tick fires.
+                repaint();
+                if (heartbeatMs > 0) {
+                    const timer = setInterval(() => {
+                        if (!active)
+                            return;
+                        active.frame += 1;
+                        repaint();
+                    }, heartbeatMs);
+                    // Don't keep the event loop alive just for the spinner — if the
+                    // host process is otherwise idle (e.g. awaiting a child), we still
+                    // want it to exit when the work is done.
+                    if (typeof timer.unref === "function") {
+                        timer.unref();
+                    }
+                    active.timer = timer;
+                }
+            }
+            else {
+                // Non-TTY plain-text degrade: one line per state transition, no `\r`.
+                stream.write(`${label}\n`);
+            }
+        },
+        update(metrics) {
+            if (!active)
+                return;
+            // Merge so successive `update` calls only need to pass the changed
+            // metric (e.g. page index ticks per fetch).
+            active.metrics = { ...active.metrics, ...metrics };
+            if (tty) {
+                repaint();
+            }
+            // On non-TTY we intentionally drop tick updates to avoid spamming the
+            // log with one line per page. The next phase / succeed / fail line
+            // re-states the final metric set.
+        },
+        succeed(label, duration) {
+            const elapsedMs = duration ?? (active ? now() - active.startedAt : 0);
+            const formatted = formatDuration(elapsedMs);
+            clearSpinnerLine();
+            stopSpinner();
+            stream.write(`${label} (${formatted})\n`);
+        },
+        fail(label, reason) {
+            clearSpinnerLine();
+            stopSpinner();
+            stream.write(`${label} — ${reason}\n`);
+        },
+        raw(text) {
+            if (!verbose)
+                return;
+            // Clear the spinner row before flushing pass-through so the agent's
+            // stdout / stderr line doesn't end up appended to the spinner frame.
+            // On non-TTY, the spinner doesn't share a line so clearing is a no-op.
+            clearSpinnerLine();
+            stream.write(text);
+            // If the chunk does not end in a newline, the spinner repaint would
+            // overwrite the tail of the chunk. Insert a soft newline before
+            // re-rendering so the chunk is preserved verbatim in scrollback.
+            if (active && tty && !text.endsWith("\n")) {
+                stream.write("\n");
+            }
+            repaint();
+        },
+    };
+}
+/**
+ * Format an elapsed-time in milliseconds as either `Nms`, `N.Ns`, or
+ * `Nm Ns`. Used by `succeed()` so the completion line carries the actual
+ * sub-task duration without the caller having to compute it.
+ */
+function formatDuration(ms) {
+    if (ms < 1000) {
+        return `${ms}ms`;
+    }
+    if (ms < 60_000) {
+        const seconds = (ms / 1000).toFixed(1);
+        return `${seconds}s`;
+    }
+    const minutes = Math.floor(ms / 60_000);
+    const seconds = Math.floor((ms % 60_000) / 1000);
+    return `${minutes}m ${seconds}s`;
+}
+//# sourceMappingURL=progress.js.map

package/dist/core/progress.js.map

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

package/dist/core/proxy.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Proxy environment detection & NODE_OPTIONS merging helpers.
+ *
+ * `radar` runs `fetch()` on Node's built-in `undici`. Honoring `HTTPS_PROXY` /
+ * `HTTP_PROXY` requires `NODE_OPTIONS=--use-env-proxy` (Node 22.21+ / 24.5+).
+ * Rather than asking users to set it manually, the `bin` self-respawns with
+ * the flag injected when a proxy env var is present.
+ *
+ * This module is intentionally pure (no I/O, no `process` access) so the
+ * detection / merge logic can be unit tested with arbitrary env objects.
+ */
+/**
+ * Result of probing the environment for a proxy URL. `source` records which
+ * variable supplied the URL so the CLI can warn when only `ALL_PROXY` is set
+ * (`ALL_PROXY` does not engage `--use-env-proxy`; users must also set
+ * `HTTPS_PROXY` or `HTTP_PROXY`).
+ */
+export interface ProxyDetection {
+    /** The proxy URL string as found in env (no normalization). */
+    url: string;
+    /** Variable name the URL was sourced from. */
+    source: "HTTPS_PROXY" | "HTTP_PROXY" | "ALL_PROXY";
+    /**
+     * True when the URL came **only** from `ALL_PROXY` and no `HTTPS_PROXY` /
+     * `HTTP_PROXY` is set. `--use-env-proxy` ignores `ALL_PROXY`, so the CLI
+     * should warn the user before respawning would otherwise be a no-op.
+     */
+    allProxyOnly: boolean;
+}
+/**
+ * Lookup order: HTTPS_PROXY → HTTP_PROXY → ALL_PROXY, each tried in upper-case
+ * then lower-case form (POSIX convention, matches what `undici` itself checks).
+ * Empty-string values are treated as unset, matching `curl` / `wget` behavior
+ * where `HTTPS_PROXY=""` disables the proxy rather than configures it.
+ */
+export declare function detectProxyUrl(env: NodeJS.ProcessEnv): ProxyDetection | undefined;
+/**
+ * Append `flag` to an existing `NODE_OPTIONS` string, preserving user-supplied
+ * options. Skips the append when the exact flag is already present (whitespace
+ * separated) so re-spawn chains don't keep growing the env var.
+ *
+ * `existing` may be `undefined` (env var unset) or empty string — both yield
+ * just `flag` with no leading whitespace.
+ */
+export declare function mergeNodeOptions(existing: string | undefined, flag: string): string;
+/**
+ * Convert a `NO_PROXY` env value (Node / curl / wget convention) to Playwright's
+ * `proxy.bypass` form.
+ *
+ * Differences between the two formats:
+ *
+ * | Concern        | Node `NO_PROXY`              | Playwright `bypass`             |
+ * |----------------|------------------------------|---------------------------------|
+ * | Separator      | `,`                          | `;`                             |
+ * | Domain suffix  | `.example.com` (leading dot) | `*.example.com` (glob wildcard) |
+ * | Bare host      | `example.com`                | `example.com`                   |
+ *
+ * Empty / whitespace-only entries are dropped so trailing commas or accidental
+ * double commas don't produce empty rules (which Playwright would treat as
+ * "bypass nothing"). Returns `undefined` when the input is unset / empty so
+ * callers can pass through "no bypass list" to Playwright without an empty
+ * string (Playwright treats `""` as a valid empty bypass list — slightly
+ * different intent than "not specified").
+ */
+export declare function noProxyToPlaywrightBypass(noProxy: string | undefined): string | undefined;
+/**
+ * Redact basic-auth credentials from a proxy URL before printing.
+ *
+ * Proxy URLs like `http://user:pass@proxy:8080` are routinely set in env vars
+ * (`HTTPS_PROXY`, `HTTP_PROXY`) at corporate networks. `radar doctor` prints
+ * the detected URL so users can confirm radar is honoring the right env var,
+ * but the credentials must never reach stdout — terminal scrollback, CI
+ * artifact logs, and shared screenshots are all common leak vectors.
+ *
+ * Strategy:
+ * - Userinfo is replaced with `***:***` when **both** username and password
+ *   are present. When only a username is set, it is still replaced (treating
+ *   it as a credential because some proxies encode tokens in the userinfo
+ *   slot without a separate password).
+ * - All other URL components (scheme / host / port / path / query) are
+ *   preserved verbatim so the user can still verify the proxy address.
+ * - Invalid URLs that can't be parsed are returned as `***` rather than the
+ *   original string — better to over-redact than risk leaking malformed
+ *   credentials we couldn't classify.
+ */
+export declare function maskProxyUrl(url: string): string;
+//# sourceMappingURL=proxy.d.ts.map

package/dist/core/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/core/proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ,8CAA8C;IAC9C,MAAM,EAAE,aAAa,GAAG,YAAY,GAAG,WAAW,CAAC;IACnD;;;;OAIG;IACH,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,cAAc,GAAG,SAAS,CAmBjF;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAOnF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAiBzF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA2BhD"}

package/dist/core/proxy.js

@@ -0,0 +1,146 @@
+/**
+ * Proxy environment detection & NODE_OPTIONS merging helpers.
+ *
+ * `radar` runs `fetch()` on Node's built-in `undici`. Honoring `HTTPS_PROXY` /
+ * `HTTP_PROXY` requires `NODE_OPTIONS=--use-env-proxy` (Node 22.21+ / 24.5+).
+ * Rather than asking users to set it manually, the `bin` self-respawns with
+ * the flag injected when a proxy env var is present.
+ *
+ * This module is intentionally pure (no I/O, no `process` access) so the
+ * detection / merge logic can be unit tested with arbitrary env objects.
+ */
+/**
+ * Lookup order: HTTPS_PROXY → HTTP_PROXY → ALL_PROXY, each tried in upper-case
+ * then lower-case form (POSIX convention, matches what `undici` itself checks).
+ * Empty-string values are treated as unset, matching `curl` / `wget` behavior
+ * where `HTTPS_PROXY=""` disables the proxy rather than configures it.
+ */
+export function detectProxyUrl(env) {
+    const pick = (name) => {
+        const upper = env[name];
+        if (upper && upper.length > 0)
+            return upper;
+        const lower = env[name.toLowerCase()];
+        if (lower && lower.length > 0)
+            return lower;
+        return undefined;
+    };
+    const https = pick("HTTPS_PROXY");
+    if (https)
+        return { url: https, source: "HTTPS_PROXY", allProxyOnly: false };
+    const http = pick("HTTP_PROXY");
+    if (http)
+        return { url: http, source: "HTTP_PROXY", allProxyOnly: false };
+    const all = pick("ALL_PROXY");
+    if (all)
+        return { url: all, source: "ALL_PROXY", allProxyOnly: true };
+    return undefined;
+}
+/**
+ * Append `flag` to an existing `NODE_OPTIONS` string, preserving user-supplied
+ * options. Skips the append when the exact flag is already present (whitespace
+ * separated) so re-spawn chains don't keep growing the env var.
+ *
+ * `existing` may be `undefined` (env var unset) or empty string — both yield
+ * just `flag` with no leading whitespace.
+ */
+export function mergeNodeOptions(existing, flag) {
+    if (!existing || existing.length === 0)
+        return flag;
+    // Whitespace-split avoids false positives like matching `--use-env-proxy`
+    // against an unrelated flag that contains the same substring.
+    const tokens = existing.split(/\s+/).filter((t) => t.length > 0);
+    if (tokens.includes(flag))
+        return existing;
+    return `${existing} ${flag}`;
+}
+/**
+ * Convert a `NO_PROXY` env value (Node / curl / wget convention) to Playwright's
+ * `proxy.bypass` form.
+ *
+ * Differences between the two formats:
+ *
+ * | Concern        | Node `NO_PROXY`              | Playwright `bypass`             |
+ * |----------------|------------------------------|---------------------------------|
+ * | Separator      | `,`                          | `;`                             |
+ * | Domain suffix  | `.example.com` (leading dot) | `*.example.com` (glob wildcard) |
+ * | Bare host      | `example.com`                | `example.com`                   |
+ *
+ * Empty / whitespace-only entries are dropped so trailing commas or accidental
+ * double commas don't produce empty rules (which Playwright would treat as
+ * "bypass nothing"). Returns `undefined` when the input is unset / empty so
+ * callers can pass through "no bypass list" to Playwright without an empty
+ * string (Playwright treats `""` as a valid empty bypass list — slightly
+ * different intent than "not specified").
+ */
+export function noProxyToPlaywrightBypass(noProxy) {
+    if (!noProxy)
+        return undefined;
+    const entries = noProxy
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0)
+        .map((entry) => {
+        // Node convention: a leading dot means "match this domain and all
+        // subdomains" (`.example.com` matches `api.example.com`). Playwright
+        // expresses the same intent with a glob wildcard: `*.example.com`.
+        // Bare hosts (no leading dot) are passed through untouched — both
+        // formats agree on the exact-match semantics there.
+        if (entry.startsWith("."))
+            return `*${entry}`;
+        return entry;
+    });
+    if (entries.length === 0)
+        return undefined;
+    return entries.join(";");
+}
+/**
+ * Redact basic-auth credentials from a proxy URL before printing.
+ *
+ * Proxy URLs like `http://user:pass@proxy:8080` are routinely set in env vars
+ * (`HTTPS_PROXY`, `HTTP_PROXY`) at corporate networks. `radar doctor` prints
+ * the detected URL so users can confirm radar is honoring the right env var,
+ * but the credentials must never reach stdout — terminal scrollback, CI
+ * artifact logs, and shared screenshots are all common leak vectors.
+ *
+ * Strategy:
+ * - Userinfo is replaced with `***:***` when **both** username and password
+ *   are present. When only a username is set, it is still replaced (treating
+ *   it as a credential because some proxies encode tokens in the userinfo
+ *   slot without a separate password).
+ * - All other URL components (scheme / host / port / path / query) are
+ *   preserved verbatim so the user can still verify the proxy address.
+ * - Invalid URLs that can't be parsed are returned as `***` rather than the
+ *   original string — better to over-redact than risk leaking malformed
+ *   credentials we couldn't classify.
+ */
+export function maskProxyUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        // We can't tell where the credentials are if parsing failed; treat the
+        // whole string as sensitive. The doctor still tells the user *which*
+        // env var the URL came from, so total redaction is acceptable here.
+        return "***";
+    }
+    if (parsed.password) {
+        // Both halves present (or password-only — unusual but spec-valid). Mask
+        // both with `***` so neither leaks into terminal output. We intentionally
+        // don't keep the username "for debugging" because admins often use the
+        // username slot for tokens or service-account names that are themselves
+        // sensitive.
+        parsed.username = "***";
+        parsed.password = "***";
+    }
+    else if (parsed.username) {
+        // Userinfo with no password: some proxies encode service-account tokens
+        // or PATs in the username slot. Replace just the username; keep the URL
+        // shape (no spurious `:` separator) so the output matches the user's env
+        // var format.
+        parsed.username = "***";
+    }
+    return parsed.toString();
+}
+//# sourceMappingURL=proxy.js.map

package/dist/core/proxy.js.map

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