@cruxy/cli 0.25.0 → 0.27.0

package/dist/render/state.js

@@ -1,4 +1,5 @@
 import { UNICODE_GLYPHS } from "../theme/index.js";
+import { fit, visibleWidth } from "./layout.js";
 /**
  * The U.4 state→text mapping: pure data → string, like plan/render.ts and
  * diff.ts, so both renderers (and tests) share one composition with no
@@ -90,3 +91,40 @@ export function composeStatusLine(progress, phase, elapsedMs, glyph = UNICODE_GL
     }
     return line;
 }
+/**
+ * The width-aware live line (U.12): {@link composeStatusLine} with honest
+ * degradation tiers so the status line never soft-wraps and never loses its
+ * essential meaning — *what is happening*. Priority is phase (the action) >
+ * the `[i/n] title` progress prefix (context) > the elapsed clock (decor), so
+ * as width shrinks we shed decor first and identity last:
+ *
+ * - wide: `[2/5] title · read_file src/x.ts… (12s)`
+ * - medium: drop the elapsed clock
+ * - narrow: drop the `[i/n] title` prefix, keep the phase
+ * - very-narrow: {@link fit} the phase text with an honest ellipsis
+ */
+export function fitStatusLine(progress, phase, elapsedMs, glyph, width) {
+    const sep = ` ${glyph.sep} `;
+    const phaseText = phase ? describePhase(phase, glyph) : "";
+    const prefix = progress
+        ? `[${progress.step}/${progress.of}] ${progress.title}`
+        : "";
+    const elapsed = elapsedMs !== undefined && elapsedMs >= ELAPSED_AFTER_MS
+        ? ` (${formatElapsed(elapsedMs)})`
+        : "";
+    const join = (parts) => parts.filter((p) => p !== "").join(sep);
+    // The identity that must survive to the last: the phase, or the progress
+    // prefix when there is no phase (between-turns step context).
+    const essential = phaseText !== "" ? phaseText : prefix;
+    const candidates = [
+        join([prefix, phaseText]) + elapsed, // full
+        join([prefix, phaseText]), // drop elapsed
+        phaseText + elapsed, // drop progress prefix
+        essential, // essential only
+    ];
+    for (const c of candidates) {
+        if (c !== "" && visibleWidth(c) <= width)
+            return c;
+    }
+    return fit(essential, width, glyph.ellipsis);
+}

package/dist/render/tty-renderer.d.ts

@@ -25,6 +25,15 @@ import type { ProgressState, RenderCapabilities, RenderPhase, RenderStream, Stre
  * A committed write still only *hides* the drawn line (registers survive);
  * the next state transition redraws. Nothing redraws per streamed delta, so
  * the U.2 first-chunk-immediate guarantee is untouched.
+ *
+ * U.10 puts every live animation on ONE frame clock (see motion.ts) instead of
+ * a private interval: the spinner glyph and the phase-transition emphasis draw
+ * off `clock.frame`, subscribed only while the line is visible and torn down on
+ * hide/close (no leaked timer). Reduced motion disables the clock — the line is
+ * drawn once in its static end-state. The result reveal is a one-time entrance
+ * emphasis on a committed tool note (never a redraw of committed bytes), so it
+ * needs no clock. Motion is a cosmetic overlay on the live region only; it never
+ * gates a committed write, so the latency guarantee holds with motion active.
  */
 export declare class TtyRenderer implements StreamRenderer {
     readonly caps: RenderCapabilities;
@@ -45,10 +54,22 @@ export declare class TtyRenderer implements StreamRenderer {
     private displaced;
     /** Whether the live line is currently drawn on screen. */
     private lineVisible;
-    private timer;
-    private frame;
+    /** The one frame clock driving live animation (U.10); disabled under reduced motion. */
+    private readonly clock;
+    /** Detach from the clock; null when the live line is hidden (no ticks wanted). */
+    private unsubscribeFrame;
+    /** Clock frame the current phase *identity* began on — drives the transition emphasis (U.10). */
+    private phaseStartFrame;
     private closed;
+    /** Unsubscribe from the resize signal (U.12); null when the stream can't resize. */
+    private unsubscribeResize;
     constructor(caps: RenderCapabilities, out: RenderStream);
+    /**
+     * Redraw the live line at the current `caps.width` after a resize. A no-op
+     * when nothing is drawn (so a resize between turns writes zero bytes) — the
+     * next state transition will draw at the new width anyway.
+     */
+    private reflowLive;
     private newPrinter;
     /** Append committed content, erasing the status line first if one is live. */
     private commit;
@@ -59,7 +80,8 @@ export declare class TtyRenderer implements StreamRenderer {
      * zero-cost: no redraw-under per delta.)
      */
     private hideLine;
-    private stopTimer;
+    /** Detach from the frame clock — the timer stops once this is the last subscriber. */
+    private stopFrames;
     /**
      * The current live-line text, composed from the registers. `null` means the
      * line must be hidden: nothing to say, or an interactive prompt owns the

package/dist/render/tty-renderer.js

@@ -2,10 +2,11 @@ import { resolveTheme } from "../theme/index.js";
 import { createStreamPrinter } from "../cli/stream-print.js";
 import { renderActionPreview } from "./diff.js";
 import { createStreamHighlighter, } from "./highlight.js";
-import { composeStatusLine, ELAPSED_AFTER_MS, formatElapsed, phaseIdentity, } from "./state.js";
+import { fit } from "./layout.js";
+import { createFrameClock, inTransition, spinnerGlyph, } from "./motion.js";
+import { ELAPSED_AFTER_MS, fitStatusLine, formatElapsed, phaseIdentity, } from "./state.js";
 /** Erase the current line and return the cursor to column 0. */
 const CLEAR_LINE = "\r\x1b[2K";
-const SPINNER_INTERVAL_MS = 100;
 /**
  * The interactive renderer: committed content is append-only; the one transient
  * thing on screen is a single managed status line, redrawn in place.
@@ -30,6 +31,15 @@ const SPINNER_INTERVAL_MS = 100;
  * A committed write still only *hides* the drawn line (registers survive);
  * the next state transition redraws. Nothing redraws per streamed delta, so
  * the U.2 first-chunk-immediate guarantee is untouched.
+ *
+ * U.10 puts every live animation on ONE frame clock (see motion.ts) instead of
+ * a private interval: the spinner glyph and the phase-transition emphasis draw
+ * off `clock.frame`, subscribed only while the line is visible and torn down on
+ * hide/close (no leaked timer). Reduced motion disables the clock — the line is
+ * drawn once in its static end-state. The result reveal is a one-time entrance
+ * emphasis on a committed tool note (never a redraw of committed bytes), so it
+ * needs no clock. Motion is a cosmetic overlay on the live region only; it never
+ * gates a committed write, so the latency guarantee holds with motion active.
  */
 export class TtyRenderer {
     caps;
@@ -50,15 +60,43 @@ export class TtyRenderer {
     displaced = null;
     /** Whether the live line is currently drawn on screen. */
     lineVisible = false;
-    timer = null;
-    frame = 0;
+    /** The one frame clock driving live animation (U.10); disabled under reduced motion. */
+    clock;
+    /** Detach from the clock; null when the live line is hidden (no ticks wanted). */
+    unsubscribeFrame = null;
+    /** Clock frame the current phase *identity* began on — drives the transition emphasis (U.10). */
+    phaseStartFrame = 0;
     closed = false;
+    /** Unsubscribe from the resize signal (U.12); null when the stream can't resize. */
+    unsubscribeResize = null;
     constructor(caps, out) {
         this.caps = caps;
         this.out = out;
         this.theme = resolveTheme(caps);
         this.highlighter = createStreamHighlighter(this.theme);
         this.print = this.newPrinter();
+        // One clock for all live motion (U.10). Gated on `caps.spinner`
+        // (cursor && !reducedMotion), so reduced motion yields an inert clock that
+        // never schedules or ticks — the line is drawn once, statically.
+        this.clock = createFrameClock(caps.spinner);
+        // Resize reactivity (U.12): only the live line reflows at the new width —
+        // committed rows above are immutable and never rewritten.
+        this.unsubscribeResize = caps.onResize?.(() => this.reflowLive()) ?? null;
+    }
+    /**
+     * Redraw the live line at the current `caps.width` after a resize. A no-op
+     * when nothing is drawn (so a resize between turns writes zero bytes) — the
+     * next state transition will draw at the new width anyway.
+     */
+    reflowLive() {
+        if (this.closed || !this.lineVisible)
+            return;
+        const line = this.currentLine();
+        if (line === null) {
+            this.hideLine();
+            return;
+        }
+        this.drawLine(line);
     }
     newPrinter() {
         return createStreamPrinter((text) => {
@@ -86,13 +124,14 @@ export class TtyRenderer {
         if (!this.lineVisible)
             return;
         this.lineVisible = false;
-        this.stopTimer();
+        this.stopFrames();
         this.out.write(CLEAR_LINE);
     }
-    stopTimer() {
-        if (this.timer !== null) {
-            clearInterval(this.timer);
-            this.timer = null;
+    /** Detach from the frame clock — the timer stops once this is the last subscriber. */
+    stopFrames() {
+        if (this.unsubscribeFrame !== null) {
+            this.unsubscribeFrame();
+            this.unsubscribeFrame = null;
         }
     }
     /**
@@ -112,7 +151,10 @@ export class TtyRenderer {
         const elapsed = this.phase !== null && this.caps.spinner
             ? Date.now() - this.phaseStartedAt
             : undefined;
-        return composeStatusLine(this.progressState, this.phase, elapsed, this.theme.glyph);
+        // Reserve the glyph + space (2 cols): the composed line is degraded and
+        // fitted to the remainder so it can never soft-wrap (U.12).
+        const room = Math.max(1, this.caps.width - 2);
+        return fitStatusLine(this.progressState, this.phase, elapsed, this.theme.glyph, room);
     }
     /** Redraw the live line from current state, or hide it when there is none. */
     refresh() {
@@ -122,29 +164,36 @@ export class TtyRenderer {
             return;
         }
         this.drawLine(line);
-        if (this.caps.spinner && this.timer === null) {
-            this.timer = setInterval(() => {
-                this.frame++;
+        // Subscribe to the one clock while the line is live; the clock owns the
+        // single (unref'd) timer and only runs while something is subscribed. An
+        // inert clock (reduced motion) subscribes to nothing — the static draw
+        // above is the whole story, no frames follow.
+        if (this.clock.enabled && this.unsubscribeFrame === null) {
+            this.unsubscribeFrame = this.clock.subscribe(() => {
                 const current = this.currentLine();
                 if (current !== null)
                     this.drawLine(current);
-            }, SPINNER_INTERVAL_MS);
-            // Never hold the process open for a spinner.
-            this.timer.unref?.();
+            });
         }
     }
     drawLine(text) {
         this.lineVisible = true;
-        const frames = this.theme.glyph.spinnerFrames;
-        const glyph = this.caps.spinner
-            ? frames[this.frame % frames.length]
-            : this.theme.glyph.spinnerStatic;
-        // Reserve glyph + space; truncate so the live line can never soft-wrap.
+        const animated = this.caps.spinner;
+        const glyph = spinnerGlyph(this.clock.frame, this.theme.glyph, animated);
+        // Reserve glyph + space; ANSI-aware fit so the live line can never
+        // soft-wrap (currentLine already fits — this is defense in depth) (U.12).
         const room = Math.max(1, this.caps.width - 2);
-        const line = text.length > room
-            ? text.slice(0, Math.max(0, room - 1)) + this.theme.glyph.ellipsis
-            : text;
-        this.out.write(`${CLEAR_LINE}${this.theme.accent(glyph)} ${this.theme.muted(line)}`);
+        const line = fit(text, room, this.theme.glyph.ellipsis);
+        // Phase-transition emphasis (U.10): a newly-begun activity brightens for a
+        // few frames, then settles to muted. Purely a color role, so NO_COLOR and
+        // the static (reduced-motion) draw both collapse to the settled end-state —
+        // and it only ever plays on a live phase whose identity just changed.
+        const emphasized = animated &&
+            this.rawStatus === null &&
+            this.phase !== null &&
+            inTransition(this.clock.frame, this.phaseStartFrame);
+        const body = emphasized ? this.theme.accent(line) : this.theme.muted(line);
+        this.out.write(`${CLEAR_LINE}${this.theme.accent(glyph)} ${body}`);
     }
     beginTurn() {
         this.highlighter = createStreamHighlighter(this.theme);
@@ -168,16 +217,16 @@ export class TtyRenderer {
     note(text) {
         if (this.closed)
             return;
-        const room = Math.max(1, this.caps.width);
-        const line = text.length > room
-            ? text.slice(0, room - 1) + this.theme.glyph.ellipsis
-            : text;
+        // ANSI-aware fit (U.12): a note may carry color (subagent trail marks), so
+        // width must be measured on visible chars, not bytes, or it truncates early
+        // and can sever an escape sequence.
+        const line = fit(text, Math.max(1, this.caps.width), this.theme.glyph.ellipsis);
         this.commit(this.theme.muted(line) + "\n");
     }
     preview(preview) {
         if (this.closed)
             return;
-        const block = renderActionPreview(preview, this.theme);
+        const block = renderActionPreview(preview, this.theme, this.caps.width);
         if (block)
             this.commit(block + "\n");
     }
@@ -207,8 +256,13 @@ export class TtyRenderer {
         }
         const before = phaseIdentity(this.phase);
         this.phase = phase;
-        if (phaseIdentity(phase) !== before)
+        if (phaseIdentity(phase) !== before) {
             this.phaseStartedAt = Date.now();
+            // A new activity: restart the transition emphasis from the current frame
+            // (U.10). Only a genuine identity change resets it — a thinking phase that
+            // merely gains token counts keeps drawing settled, no re-flourish.
+            this.phaseStartFrame = this.clock.frame;
+        }
         if (phase === null) {
             // A cleared phase means "nothing is happening" — hide rather than
             // redraw a bare progress prefix between turns.
@@ -240,7 +294,13 @@ export class TtyRenderer {
         const elapsed = started === null ? 0 : Date.now() - started.at;
         const suffix = elapsed >= ELAPSED_AFTER_MS ? ` (${formatElapsed(elapsed)})` : "";
         const mark = event.ok ? this.theme.glyph.success : this.theme.glyph.failure;
-        this.note(`${mark} ${event.label}${suffix}`);
+        // Result reveal (U.10): a freshly-landed result gets a one-time entrance
+        // emphasis on its mark when motion is active — written once into committed
+        // history and never redrawn (immutable). It gates on the same motion axis,
+        // so reduced motion shows the plain mark; under NO_COLOR `strong` is the
+        // identity, so the committed bytes are byte-for-byte unchanged either way.
+        const shownMark = this.caps.spinner ? this.theme.strong(mark) : mark;
+        this.note(`${shownMark} ${event.label}${suffix}`);
     }
     promptResolved() {
         if (this.closed)
@@ -274,6 +334,8 @@ export class TtyRenderer {
         if (this.closed)
             return;
         this.endTurn();
+        this.unsubscribeResize?.();
+        this.unsubscribeResize = null;
         this.closed = true;
     }
 }

package/dist/render/types.d.ts

@@ -39,8 +39,22 @@ export interface RenderCapabilities {
     /** Unicode glyphs are safe (U.1) — false under `TERM=dumb` / `CRUXY_ASCII`;
      * independent of `color`. Drives the theme's glyph table, not its stylers. */
     unicode: boolean;
-    /** Terminal columns; 80 when unknown (non-TTY). */
+    /**
+     * Terminal columns (U.12) — the ONE width source every surface reads; 80 when
+     * unknown (non-TTY / no `columns`). Honors `COLUMNS` when set. Mutated in
+     * place on resize (see {@link onResize}), so a surface reading it after a
+     * SIGWINCH sees the new width without re-probing anything.
+     */
     width: number;
+    /**
+     * Subscribe to width changes (U.12): the SIGWINCH push signal for the live
+     * region / transient frames to reflow at the new width. The listener fires
+     * with the new width AFTER {@link width} has been updated; the returned
+     * function unsubscribes. Absent when the stream cannot resize (non-TTY / no
+     * `columns`) — those surfaces just read the static {@link width}. Committed
+     * output is never re-rendered from here; only live surfaces subscribe.
+     */
+    onResize?(listener: (width: number) => void): () => void;
 }
 /** Accumulated token usage the loop already tracks (U.4) — never fabricated. */
 export interface TokenUsage {

package/dist/web/ssrf.d.ts

@@ -17,34 +17,20 @@ import type { HostResolver } from "./types.js";
  *
  * The check runs BEFORE any request is dispatched, and again on every redirect hop
  * (see fetch.ts). A block is a security refusal, distinct from a network failure.
+ *
+ * The IP range math, the pin shim, and the error types now live in the shared
+ * {@link ../net/ip-guard ip-guard} module (JC-A) — the ONE owner of "is this IP
+ * allowed"; this file keeps only the web-specific policy (scheme + the
+ * `allowPrivateHosts` escape hatch) and the web one-shot dispatcher.
  */
-/** Default resolver: node's `dns.lookup` returning ALL addresses. */
-export declare const defaultResolveHost: HostResolver;
-/** Thrown when a URL is refused pre-dispatch; carries a human reason. */
-export declare class BlockedHostError extends Error {
-}
-/** Thrown when the host could not be resolved (a network failure, not a block). */
-export declare class HostUnresolvedError extends Error {
-}
-/** True if an address (v4 or v6) is in a range `web_fetch` must never reach. */
-export declare function isBlockedAddress(addr: string): boolean;
-/**
- * A `dns.lookup`-compatible function that ignores the hostname and always hands
- * back one of the pre-validated `addresses`. This is what pins a connection to the
- * address the SSRF check already approved, defeating DNS rebinding: the socket can
- * only reach a validated IP, never a value re-resolved at connect time.
- */
-export declare function pinnedLookup(addresses: string[]): (_hostname: string, options: unknown, callback: (err: NodeJS.ErrnoException | null, address: string | {
-    address: string;
-    family: number;
-}[], family?: number) => void) => void;
+export { BlockedHostError, HostUnresolvedError, isBlockedAddress, defaultResolveHost, pinnedLookup, } from "../net/ip-guard.js";
 /** An undici dispatcher whose connections are pinned to `addresses`. */
 export declare function createPinnedDispatcher(addresses: string[]): Dispatcher;
 /**
  * Assert that `url` may be fetched and return the validated addresses to pin the
  * connection to. Throws {@link BlockedHostError} for a bad scheme or a host
- * resolving into a blocked range, or {@link HostUnresolvedError} if the host cannot
- * be resolved.
+ * resolving into a blocked range, or `HostUnresolvedError` if the host cannot be
+ * resolved.
  *
  * The returned list is the exact set of addresses the caller must restrict the
  * connection to (via {@link createPinnedDispatcher}). An empty list means "do not

package/dist/web/ssrf.js

@@ -1,5 +1,5 @@
-import { lookup } from "node:dns";
 import { Agent } from "undici";
+import { assertAllPublic, BlockedHostError, pinnedLookup, } from "../net/ip-guard.js";
 /**
  * SSRF guard (C.20). A URL the MODEL chose must not be able to reach the user's
  * internal network, cloud metadata service, or loopback interface. Three layers:
@@ -17,170 +17,14 @@ import { Agent } from "undici";
  *
  * The check runs BEFORE any request is dispatched, and again on every redirect hop
  * (see fetch.ts). A block is a security refusal, distinct from a network failure.
+ *
+ * The IP range math, the pin shim, and the error types now live in the shared
+ * {@link ../net/ip-guard ip-guard} module (JC-A) — the ONE owner of "is this IP
+ * allowed"; this file keeps only the web-specific policy (scheme + the
+ * `allowPrivateHosts` escape hatch) and the web one-shot dispatcher.
  */
-/** Default resolver: node's `dns.lookup` returning ALL addresses. */
-export const defaultResolveHost = (host) => new Promise((resolve, reject) => {
-    lookup(host, { all: true }, (err, addresses) => {
-        if (err)
-            reject(err);
-        else
-            resolve(addresses.map((a) => a.address));
-    });
-});
-/** Thrown when a URL is refused pre-dispatch; carries a human reason. */
-export class BlockedHostError extends Error {
-}
-/** Thrown when the host could not be resolved (a network failure, not a block). */
-export class HostUnresolvedError extends Error {
-}
-/** Parse a dotted-quad IPv4 string into its four octets, or null. */
-function parseIpv4(ip) {
-    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(ip);
-    if (!m)
-        return null;
-    const octets = m.slice(1, 5).map((s) => Number(s));
-    if (octets.some((o) => o > 255))
-        return null;
-    return octets;
-}
-/** True if an IPv4 address falls in a private/loopback/link-local/reserved range. */
-function isBlockedIpv4(ip) {
-    const octets = parseIpv4(ip);
-    if (!octets)
-        return false;
-    const [a, b] = octets;
-    if (a === 0)
-        return true; // 0.0.0.0/8 "this network" / unspecified
-    if (a === 10)
-        return true; // 10.0.0.0/8 private
-    if (a === 127)
-        return true; // 127.0.0.0/8 loopback
-    if (a === 169 && b === 254)
-        return true; // 169.254.0.0/16 link-local (incl. 169.254.169.254 metadata)
-    if (a === 172 && b >= 16 && b <= 31)
-        return true; // 172.16.0.0/12 private
-    if (a === 192 && b === 168)
-        return true; // 192.168.0.0/16 private
-    if (a === 100 && b >= 64 && b <= 127)
-        return true; // 100.64.0.0/10 CGNAT
-    if (a === 198 && (b === 18 || b === 19))
-        return true; // 198.18.0.0/15 benchmarking
-    if (a === 255 && b === 255)
-        return true; // broadcast-ish
-    return false;
-}
-/**
- * Expand an IPv6 literal into its 8 sixteen-bit groups, or null if unparseable.
- * Handles `::` compression and an embedded IPv4 tail (`::ffff:127.0.0.1`).
- */
-function parseIpv6(input) {
-    let s = input;
-    const tail = [];
-    // Peel off a trailing dotted-quad (IPv4-mapped/-compatible forms).
-    const v4 = /(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(s);
-    if (v4) {
-        const o = parseIpv4(v4[1]);
-        if (!o)
-            return null;
-        tail.push((o[0] << 8) | o[1], (o[2] << 8) | o[3]);
-        s = s.slice(0, v4.index); // leaves a trailing ':' before the compression split
-    }
-    const halves = s.split("::");
-    if (halves.length > 2)
-        return null; // more than one "::" is illegal
-    const head = halves[0] ? halves[0].split(":").filter(Boolean) : [];
-    const rest = halves[1] ? halves[1].split(":").filter(Boolean) : [];
-    const toNums = (groups) => {
-        const out = [];
-        for (const g of groups) {
-            if (!/^[0-9a-f]{1,4}$/.test(g))
-                return null;
-            out.push(parseInt(g, 16));
-        }
-        return out;
-    };
-    const headNums = toNums(head);
-    const restNums = toNums(rest);
-    if (!headNums || !restNums)
-        return null;
-    let groups;
-    if (halves.length === 2) {
-        const fill = 8 - (headNums.length + restNums.length + tail.length);
-        if (fill < 0)
-            return null;
-        groups = [
-            ...headNums,
-            ...Array(fill).fill(0),
-            ...restNums,
-            ...tail,
-        ];
-    }
-    else {
-        groups = [...headNums, ...tail];
-    }
-    return groups.length === 8 ? groups : null;
-}
-/** True if an expanded IPv6 address is in a range `web_fetch` must never reach. */
-function isBlockedIpv6(g) {
-    // IPv4-mapped (::ffff:a.b.c.d) and IPv4-compatible (::a.b.c.d): check the v4 part.
-    const firstFiveZero = g.slice(0, 5).every((x) => x === 0);
-    const firstSixZero = firstFiveZero && g[5] === 0;
-    const embedded = `${g[6] >> 8}.${g[6] & 0xff}.${g[7] >> 8}.${g[7] & 0xff}`;
-    if (firstFiveZero && g[5] === 0xffff)
-        return isBlockedIpv4(embedded); // ::ffff:x
-    if (firstSixZero &&
-        !(g[6] === 0 && g[7] === 0) &&
-        !(g[6] === 0 && g[7] === 1))
-        return isBlockedIpv4(embedded); // ::x.y.z.w (IPv4-compatible, deprecated)
-    if (g.every((x) => x === 0))
-        return true; // :: unspecified
-    if (firstSixZero && g[6] === 0 && g[7] === 1)
-        return true; // ::1 loopback
-    if ((g[0] & 0xffc0) === 0xfe80)
-        return true; // fe80::/10 link-local (fe80–febf)
-    if ((g[0] & 0xfe00) === 0xfc00)
-        return true; // fc00::/7 unique-local (fc00–fdff)
-    if ((g[0] & 0xff00) === 0xff00)
-        return true; // ff00::/8 multicast
-    return false;
-}
-/** True if an address (v4 or v6) is in a range `web_fetch` must never reach. */
-export function isBlockedAddress(addr) {
-    // Strip IPv6 brackets and a scope/zone id (e.g. fe80::1%eth0).
-    const ip = addr
-        .trim()
-        .toLowerCase()
-        .replace(/^\[|\]$/g, "")
-        .split("%")[0];
-    if (ip.includes(":")) {
-        const groups = parseIpv6(ip);
-        if (!groups)
-            return true; // fail closed: an unparseable colon-address is refused
-        return isBlockedIpv6(groups);
-    }
-    return isBlockedIpv4(ip);
-}
-/**
- * A `dns.lookup`-compatible function that ignores the hostname and always hands
- * back one of the pre-validated `addresses`. This is what pins a connection to the
- * address the SSRF check already approved, defeating DNS rebinding: the socket can
- * only reach a validated IP, never a value re-resolved at connect time.
- */
-export function pinnedLookup(addresses) {
-    const resolved = addresses.map((address) => ({
-        address,
-        family: address.includes(":") ? 6 : 4,
-    }));
-    return (_hostname, options, callback) => {
-        const all = typeof options === "object" && options !== null && "all" in options
-            ? options.all
-            : false;
-        if (all)
-            callback(null, resolved);
-        else
-            callback(null, resolved[0].address, resolved[0].family);
-    };
-}
+// Re-export the shared surface so existing web importers/tests are unchanged.
+export { BlockedHostError, HostUnresolvedError, isBlockedAddress, defaultResolveHost, pinnedLookup, } from "../net/ip-guard.js";
 /** An undici dispatcher whose connections are pinned to `addresses`. */
 export function createPinnedDispatcher(addresses) {
     return new Agent({ connect: { lookup: pinnedLookup(addresses) } });
@@ -188,8 +32,8 @@ export function createPinnedDispatcher(addresses) {
 /**
  * Assert that `url` may be fetched and return the validated addresses to pin the
  * connection to. Throws {@link BlockedHostError} for a bad scheme or a host
- * resolving into a blocked range, or {@link HostUnresolvedError} if the host cannot
- * be resolved.
+ * resolving into a blocked range, or `HostUnresolvedError` if the host cannot be
+ * resolved.
  *
  * The returned list is the exact set of addresses the caller must restrict the
  * connection to (via {@link createPinnedDispatcher}). An empty list means "do not
@@ -203,21 +47,5 @@ export async function assertFetchable(url, resolveHost, allowPrivate) {
     }
     if (allowPrivate)
         return [];
-    const host = url.hostname.replace(/^\[|\]$/g, ""); // strip IPv6 brackets
-    let addresses;
-    try {
-        addresses = await resolveHost(host);
-    }
-    catch (err) {
-        throw new HostUnresolvedError(`could not resolve host "${host}": ${err.message}`);
-    }
-    if (addresses.length === 0) {
-        throw new HostUnresolvedError(`host "${host}" resolved to no addresses`);
-    }
-    for (const addr of addresses) {
-        if (isBlockedAddress(addr)) {
-            throw new BlockedHostError(`host "${host}" resolves to ${addr}, a private/loopback/link-local address`);
-        }
-    }
-    return addresses;
+    return assertAllPublic(url.hostname, resolveHost);
 }

package/dist/web/types.d.ts

@@ -1,3 +1,4 @@
+import type { HostResolver } from "../net/ip-guard.js";
 import type { WebConfig } from "../config/index.js";
 /**
  * Web subtool seams + shapes (C.20). Everything the `web_search`/`web_fetch`
@@ -44,9 +45,10 @@ export interface SearchProvider {
 /**
  * Resolve a hostname to its IP addresses. Injected so the SSRF guard can be tested
  * deterministically (a hostname that "resolves" to an internal IP) without real
- * DNS. Defaults to node's `dns.lookup` with `all: true`.
+ * DNS. Owned by the shared {@link ../net/ip-guard ip-guard} module (JC-A) and
+ * re-exported here for web importers.
  */
-export type HostResolver = (host: string) => Promise<string[]>;
+export type { HostResolver } from "../net/ip-guard.js";
 /**
  * Injectable dependencies for the web tools. Defaults wire the real `fetch` and
  * DNS; tests pass spies/fakes. No global is ever patched.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {