@ozzylabs/feedradar 0.1.4 → 0.1.5

package/dist/core/feeds/_fetch.js

@@ -40,6 +40,184 @@ function parsePositiveInt(value, fallback) {
         return fallback;
     return n;
 }
+/**
+ * SSRF host-blocklist for the shared fetch wrapper (ADR-0009 §D5b /
+ * ADR-0012 §D5b). Every adapter that funnels through `fetchWithRetry`
+ * inherits this check, including pagination follow-up URLs and recipe-
+ * supplied URLs in `kind: json-api` where a malicious recipe / compromised
+ * upstream could otherwise point us at:
+ *
+ * - cloud instance metadata endpoints (`169.254.169.254`, etc.) — IAM
+ *   credential theft
+ * - LAN / VPC internal services (`10.0.0.0/8`, `192.168.0.0/16`,
+ *   `172.16.0.0/12`) — internal admin panels, unauthenticated dev servers
+ * - loopback (`127.0.0.0/8` / `::1`) — user's localhost dev / debug services
+ * - link-local (`169.254.0.0/16` / `fe80::/10`)
+ * - IPv6 ULA (`fc00::/7`)
+ * - non-HTTP schemes (`file://`, `data:`, `gopher://`, `ftp://`, …) —
+ *   filesystem reads / SMTP smuggling / arbitrary protocol abuse
+ *
+ * Scope: this is the minimum useful defense — we inspect the URL hostname
+ * literal only. We do not resolve DNS; an attacker can still get past this
+ * by pointing a public DNS record at `127.0.0.1` (DNS rebinding). That
+ * deeper defense is tracked separately (see ADR-0009 §D5b note on DNS
+ * rebinding); the literal check still cuts off the common SSRF recipes
+ * (metadata IPs, `file://`, `localhost`) for negligible cost.
+ *
+ * Override via `RADAR_FETCH_HOST_ALLOWLIST` (comma-separated host literals).
+ * Intended for testing (e2e smoke tests that spin up a local HTTP fixture
+ * on `127.0.0.1`) and explicit opt-in to private-network targets. The
+ * allowlist is matched against the URL hostname after lowercasing and
+ * trimming IPv6 brackets; entries are exact-match (no glob / CIDR).
+ */
+/** IPv4 octet sequence — used as a heuristic to detect numeric-only hosts. */
+const IPV4_PATTERN = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+/** Hostnames that always resolve to a loopback / unspecified address. */
+const BLOCKED_HOSTNAMES = new Set(["localhost", "ip6-localhost", "ip6-loopback"]);
+/**
+ * Parse the `RADAR_FETCH_HOST_ALLOWLIST` env into a normalized Set. We
+ * lowercase and strip IPv6 brackets so users can write either `[::1]` or
+ * `::1` and have the override apply.
+ */
+function parseHostAllowlist(value) {
+    if (!value)
+        return new Set();
+    const entries = value
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0)
+        .map((s) => normalizeHost(s));
+    return new Set(entries);
+}
+/** Lowercase a host and strip wrapping `[` / `]` from IPv6 literals. */
+function normalizeHost(host) {
+    const lower = host.toLowerCase();
+    if (lower.startsWith("[") && lower.endsWith("]")) {
+        return lower.slice(1, -1);
+    }
+    return lower;
+}
+/** Whether a host string is an IPv4 address in one of the private ranges. */
+function isPrivateIPv4(host) {
+    const match = host.match(IPV4_PATTERN);
+    if (!match)
+        return false;
+    const [, a, b, c, d] = match;
+    const o1 = Number.parseInt(a ?? "", 10);
+    const o2 = Number.parseInt(b ?? "", 10);
+    const o3 = Number.parseInt(c ?? "", 10);
+    const o4 = Number.parseInt(d ?? "", 10);
+    // Reject malformed octets (>255). The URL parser already rejects most of
+    // these but we keep the bound check for defense in depth.
+    if (![o1, o2, o3, o4].every((n) => Number.isFinite(n) && n >= 0 && n <= 255)) {
+        return true; // malformed = unsafe; treat as blocked.
+    }
+    // 10.0.0.0/8
+    if (o1 === 10)
+        return true;
+    // 172.16.0.0/12 (172.16.x.x – 172.31.x.x)
+    if (o1 === 172 && o2 >= 16 && o2 <= 31)
+        return true;
+    // 192.168.0.0/16
+    if (o1 === 192 && o2 === 168)
+        return true;
+    // 127.0.0.0/8 (loopback)
+    if (o1 === 127)
+        return true;
+    // 169.254.0.0/16 (link-local / AWS metadata)
+    if (o1 === 169 && o2 === 254)
+        return true;
+    // 0.0.0.0/8 (unspecified — listens-everywhere on Linux)
+    if (o1 === 0)
+        return true;
+    return false;
+}
+/**
+ * Whether an IPv6 literal (already lowercase, brackets stripped) is in a
+ * blocked range. We do not implement full address arithmetic — instead we
+ * pattern-match the textual prefix, which is enough for the well-known
+ * ranges we want to block (loopback, link-local, ULA, unspecified).
+ *
+ * Edge: `::ffff:a.b.c.d` IPv4-mapped form is normalized by Node's URL
+ * parser to bracketed IPv6, so we also rerun the IPv4 check on the trailing
+ * dotted-quad to catch the mapped-loopback case (`::ffff:127.0.0.1`).
+ */
+function isPrivateIPv6(host) {
+    if (host === "::" || host === "::1")
+        return true;
+    // Link-local: fe80::/10 — first 10 bits are 1111 1110 10, which in hex
+    // means `fe80::` through `febf::`. Match the first two chars after fe.
+    if (/^fe[89ab][0-9a-f]?:/.test(host))
+        return true;
+    // ULA: fc00::/7 — first 7 bits are 1111 110, i.e. fc00–fdff.
+    if (/^f[cd][0-9a-f]{2}:/.test(host))
+        return true;
+    // IPv4-mapped IPv6, dotted-quad form: ::ffff:127.0.0.1, ::ffff:10.0.0.1
+    const v4MappedDotted = host.match(/^::ffff:([\d.]+)$/);
+    if (v4MappedDotted?.[1] && isPrivateIPv4(v4MappedDotted[1]))
+        return true;
+    // IPv4-mapped IPv6, hex form: Node's URL parser normalizes
+    // `::ffff:127.0.0.1` → `[::ffff:7f00:1]`, so we also accept the two
+    // 16-bit hex groups after `::ffff:` and reconstruct the dotted quad.
+    const v4MappedHex = host.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+    if (v4MappedHex?.[1] && v4MappedHex[2]) {
+        const high = Number.parseInt(v4MappedHex[1], 16);
+        const low = Number.parseInt(v4MappedHex[2], 16);
+        if (Number.isFinite(high) && Number.isFinite(low)) {
+            const dotted = `${(high >> 8) & 0xff}.${high & 0xff}.${(low >> 8) & 0xff}.${low & 0xff}`;
+            if (isPrivateIPv4(dotted))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Validate a fetch URL against the SSRF host blocklist (ADR-0009 §D5b).
+ *
+ * Throws a `TypeError` with a user-friendly message when the URL is
+ * rejected. Returns nothing on success.
+ *
+ * Exported so adapters / tests can trigger the check independently of
+ * `fetchWithRetry` (e.g. validate a recipe URL at config-load time).
+ */
+export function validateFetchUrl(url, env = process.env) {
+    let parsed;
+    try {
+        parsed = url instanceof URL ? url : new URL(url);
+    }
+    catch {
+        throw new TypeError(`refused to fetch invalid URL: ${String(url)}`);
+    }
+    const allowlist = parseHostAllowlist(env.RADAR_FETCH_HOST_ALLOWLIST);
+    const host = normalizeHost(parsed.hostname);
+    // Allowlist short-circuits both scheme and host checks so users testing
+    // a local fixture over `http://127.0.0.1:PORT/` do not need to fight
+    // the blocklist for every adapter test.
+    if (allowlist.has(host))
+        return;
+    // Reject non-HTTP(S) schemes outright. `data:` / `file:` / `gopher:` /
+    // `ftp:` / `javascript:` all have no business being fetched through an
+    // adapter; even when they would not technically SSRF, they break the
+    // wrapper's invariant ("HTTP request, retry on transient errors").
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new TypeError(`refused to fetch URL with non-HTTP scheme "${parsed.protocol}" (${String(url)}). ` +
+            `Only http:// and https:// are allowed.`);
+    }
+    // Blocked literal hostnames (`localhost` etc.).
+    if (BLOCKED_HOSTNAMES.has(host)) {
+        throw new TypeError(`refused to fetch loopback hostname "${host}" (${String(url)}). ` +
+            `Set RADAR_FETCH_HOST_ALLOWLIST=${host} to override (testing only).`);
+    }
+    // Numeric IPv4 / IPv6 ranges.
+    if (isPrivateIPv4(host)) {
+        throw new TypeError(`refused to fetch private / loopback IPv4 address "${host}" (${String(url)}). ` +
+            `Set RADAR_FETCH_HOST_ALLOWLIST=${host} to override (testing only).`);
+    }
+    if (host.includes(":") && isPrivateIPv6(host)) {
+        throw new TypeError(`refused to fetch private / loopback IPv6 address "${host}" (${String(url)}). ` +
+            `Set RADAR_FETCH_HOST_ALLOWLIST=${host} to override (testing only).`);
+    }
+}
 /**
  * Build a `FetchConfig` from env vars + explicit overrides.
  *
@@ -134,6 +312,10 @@ export async function fetchWithRetry(fetchImpl, url, init = {}, options = {}) {
     const config = resolveFetchConfig(options);
     const sleep = options.sleep ?? defaultSleep;
     const callerSignal = options.signal ?? init.signal;
+    // SSRF host blocklist (ADR-0009 / ADR-0012 §D5b). Runs *before* the retry
+    // loop so a blocked URL fails fast with a single clear error rather than
+    // looking like a transient network failure across multiple attempts.
+    validateFetchUrl(url, options.env ?? process.env);
     let lastError;
     let lastResponse;
     // attempts = retries + 1; e.g. retries=2 → 3 total attempts.

package/dist/core/feeds/_fetch.js.map

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

package/dist/core/feeds/_jsonpath.d.ts

@@ -0,0 +1,57 @@
+/**
+ * JSONPath-lite — minimal expression evaluator for the `kind: json-api` adapter
+ * (ADR-0012 §D2).
+ *
+ * Supports the smallest subset of JSONPath that covers the page-based JSON
+ * APIs FeedRadar targets (AWS What's New, dev.to, Anthropic news, …) without
+ * bringing in a 30 KB dep:
+ *
+ *   $                        — root
+ *   .field                   — property access (dotted form)
+ *   ['field']                — property access (bracket form, single key)
+ *   [N]                      — array index (non-negative integer)
+ *   [*]                      — array wildcard (returns all elements)
+ *   .*                       — object wildcard (returns all values)
+ *   $.a.b.c                  — chained property access
+ *   $.array[*].field         — chain after wildcard
+ *
+ * Out of scope (throws `JsonPathError` at compile time):
+ *
+ *   ..field                  — recursive descent
+ *   [?(...)]                 — filter expressions
+ *   [N:M]                    — slicing
+ *   ['a','b']                — multi-key
+ *   length() / min() / ...   — functions
+ *
+ * Two evaluation modes:
+ *
+ * - `selectOne(path, root)`: returns a single value (the first match), or
+ *   `undefined` when nothing matches. Used for scalar selectors like
+ *   `selectors.title` / `selectors.url`.
+ *
+ * - `selectAll(path, root)`: returns an array of all matches. Used for
+ *   `selectors.items` which is expected to yield the per-item list.
+ *
+ * Errors:
+ *
+ * - `JsonPathError` (compile time): syntactically invalid or unsupported.
+ * - At runtime, missing properties / out-of-range indices simply return
+ *   `undefined` / `[]` so recipe authors can selectors-and-shrug their way
+ *   through optional fields like `summary` / `publishedAt`.
+ */
+/** Error thrown when a path expression is syntactically invalid or uses an unsupported feature. */
+export declare class JsonPathError extends Error {
+    constructor(message: string);
+}
+/**
+ * Return the first match for `path` against `root`, or `undefined` when the
+ * path does not match anything. Used by scalar selectors.
+ */
+export declare function selectOne(path: string, root: unknown): unknown;
+/**
+ * Return all matches for `path` against `root`. Used by `selectors.items` to
+ * pick the per-item list. Always returns an array (never `undefined`) so the
+ * adapter can iterate without a null check.
+ */
+export declare function selectAll(path: string, root: unknown): unknown[];
+//# sourceMappingURL=_jsonpath.d.ts.map

package/dist/core/feeds/_jsonpath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_jsonpath.d.ts","sourceRoot":"","sources":["../../../src/core/feeds/_jsonpath.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,mGAAmG;AACnG,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AA6JD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAG9D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,EAAE,CAEhE"}

package/dist/core/feeds/_jsonpath.js

@@ -0,0 +1,207 @@
+/**
+ * JSONPath-lite — minimal expression evaluator for the `kind: json-api` adapter
+ * (ADR-0012 §D2).
+ *
+ * Supports the smallest subset of JSONPath that covers the page-based JSON
+ * APIs FeedRadar targets (AWS What's New, dev.to, Anthropic news, …) without
+ * bringing in a 30 KB dep:
+ *
+ *   $                        — root
+ *   .field                   — property access (dotted form)
+ *   ['field']                — property access (bracket form, single key)
+ *   [N]                      — array index (non-negative integer)
+ *   [*]                      — array wildcard (returns all elements)
+ *   .*                       — object wildcard (returns all values)
+ *   $.a.b.c                  — chained property access
+ *   $.array[*].field         — chain after wildcard
+ *
+ * Out of scope (throws `JsonPathError` at compile time):
+ *
+ *   ..field                  — recursive descent
+ *   [?(...)]                 — filter expressions
+ *   [N:M]                    — slicing
+ *   ['a','b']                — multi-key
+ *   length() / min() / ...   — functions
+ *
+ * Two evaluation modes:
+ *
+ * - `selectOne(path, root)`: returns a single value (the first match), or
+ *   `undefined` when nothing matches. Used for scalar selectors like
+ *   `selectors.title` / `selectors.url`.
+ *
+ * - `selectAll(path, root)`: returns an array of all matches. Used for
+ *   `selectors.items` which is expected to yield the per-item list.
+ *
+ * Errors:
+ *
+ * - `JsonPathError` (compile time): syntactically invalid or unsupported.
+ * - At runtime, missing properties / out-of-range indices simply return
+ *   `undefined` / `[]` so recipe authors can selectors-and-shrug their way
+ *   through optional fields like `summary` / `publishedAt`.
+ */
+/** Error thrown when a path expression is syntactically invalid or uses an unsupported feature. */
+export class JsonPathError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "JsonPathError";
+    }
+}
+/** Tokens that mark an unsupported (out-of-scope) construct. Detected pre-parse. */
+const UNSUPPORTED_PATTERNS = [
+    { pattern: /\.\./, message: "recursive descent ('..') is not supported" },
+    { pattern: /\[\?/, message: "filter expression ('[?(...)]') is not supported" },
+    { pattern: /\[\s*\d+\s*:/, message: "slice ('[N:M]') is not supported" },
+    { pattern: /\[\s*['"][^'"]+['"]\s*,/, message: "multi-key ('[a,b]') is not supported" },
+];
+/**
+ * Compile a path expression into an array of steps.
+ *
+ * The expression must start with `$`. Trailing whitespace is tolerated; any
+ * other deviation throws so misconfigured recipes surface at parse time
+ * (rather than silently returning empty selectors on every fetch).
+ */
+function compile(path) {
+    const trimmed = path.trim();
+    if (trimmed.length === 0) {
+        throw new JsonPathError("path is empty");
+    }
+    for (const { pattern, message } of UNSUPPORTED_PATTERNS) {
+        if (pattern.test(trimmed)) {
+            throw new JsonPathError(`jsonpath-lite: ${message} (path: '${path}')`);
+        }
+    }
+    if (trimmed[0] !== "$") {
+        throw new JsonPathError(`jsonpath-lite: path must start with '$' (path: '${path}')`);
+    }
+    const steps = [];
+    let i = 1; // past the '$'
+    while (i < trimmed.length) {
+        const ch = trimmed[i];
+        if (ch === ".") {
+            i++;
+            // Object wildcard: `.*`
+            if (trimmed[i] === "*") {
+                steps.push({ kind: "wildcard-object" });
+                i++;
+                continue;
+            }
+            // Property: `.field` — consume identifier-ish chars.
+            const start = i;
+            while (i < trimmed.length && /[A-Za-z0-9_-]/.test(trimmed[i] ?? "")) {
+                i++;
+            }
+            if (start === i) {
+                throw new JsonPathError(`jsonpath-lite: expected property name after '.' at position ${i} (path: '${path}')`);
+            }
+            steps.push({ kind: "prop", name: trimmed.slice(start, i) });
+            continue;
+        }
+        if (ch === "[") {
+            // Find the matching close bracket.
+            const close = trimmed.indexOf("]", i);
+            if (close === -1) {
+                throw new JsonPathError(`jsonpath-lite: unclosed '[' at position ${i} (path: '${path}')`);
+            }
+            const inner = trimmed.slice(i + 1, close).trim();
+            if (inner === "*") {
+                steps.push({ kind: "wildcard-array" });
+            }
+            else if (/^-?\d+$/.test(inner)) {
+                const idx = Number.parseInt(inner, 10);
+                if (idx < 0) {
+                    throw new JsonPathError(`jsonpath-lite: negative index not supported (path: '${path}')`);
+                }
+                steps.push({ kind: "index", index: idx });
+            }
+            else if ((inner.startsWith("'") && inner.endsWith("'")) ||
+                (inner.startsWith('"') && inner.endsWith('"'))) {
+                // Single-key bracket form: ['field'] / ["field"]
+                const name = inner.slice(1, -1);
+                if (name.length === 0) {
+                    throw new JsonPathError(`jsonpath-lite: empty bracket key not supported (path: '${path}')`);
+                }
+                steps.push({ kind: "prop", name });
+            }
+            else {
+                throw new JsonPathError(`jsonpath-lite: unsupported bracket expression '[${inner}]' (path: '${path}')`);
+            }
+            i = close + 1;
+            continue;
+        }
+        throw new JsonPathError(`jsonpath-lite: unexpected character '${ch}' at position ${i} (path: '${path}')`);
+    }
+    return steps;
+}
+/** Apply one step to a single value, producing zero or more values. */
+function applyStep(step, value) {
+    if (value == null)
+        return [];
+    switch (step.kind) {
+        case "prop": {
+            if (typeof value !== "object")
+                return [];
+            // Arrays do not expose arbitrary string properties for JSON purposes;
+            // we restrict to plain objects so `$.items.title` does not accidentally
+            // match `Array.prototype.title`.
+            if (Array.isArray(value))
+                return [];
+            const obj = value;
+            // `hasOwnProperty` avoids picking up prototype-chain pollution.
+            if (!Object.hasOwn(obj, step.name))
+                return [];
+            return [obj[step.name]];
+        }
+        case "index": {
+            if (!Array.isArray(value))
+                return [];
+            if (step.index >= value.length)
+                return [];
+            return [value[step.index]];
+        }
+        case "wildcard-array": {
+            if (!Array.isArray(value))
+                return [];
+            return value.slice();
+        }
+        case "wildcard-object": {
+            if (typeof value !== "object" || Array.isArray(value))
+                return [];
+            return Object.values(value);
+        }
+    }
+}
+/**
+ * Walk every compiled step, fanning out at wildcards. Returns the full set
+ * of matches in document order.
+ */
+function evaluate(path, root) {
+    const steps = compile(path);
+    let frontier = [root];
+    for (const step of steps) {
+        const next = [];
+        for (const v of frontier) {
+            next.push(...applyStep(step, v));
+        }
+        frontier = next;
+        if (frontier.length === 0)
+            return [];
+    }
+    return frontier;
+}
+/**
+ * Return the first match for `path` against `root`, or `undefined` when the
+ * path does not match anything. Used by scalar selectors.
+ */
+export function selectOne(path, root) {
+    const matches = evaluate(path, root);
+    return matches.length > 0 ? matches[0] : undefined;
+}
+/**
+ * Return all matches for `path` against `root`. Used by `selectors.items` to
+ * pick the per-item list. Always returns an array (never `undefined`) so the
+ * adapter can iterate without a null check.
+ */
+export function selectAll(path, root) {
+    return evaluate(path, root);
+}
+//# sourceMappingURL=_jsonpath.js.map

package/dist/core/feeds/_jsonpath.js.map

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

package/dist/core/feeds/html-js.d.ts

@@ -66,6 +66,14 @@ export interface HtmlJsAdapterOptions extends FeedAdapterOptions {
      * deterministically testable without polluting the real process env.
      */
     env?: NodeJS.ProcessEnv;
+    /**
+     * Test seam (#198): override the `Still waiting…` reminder threshold in
+     * milliseconds. Production hardcodes 10s (a third of the default 30s
+     * timeout) so the prediction triggers well before the actual selector
+     * timeout. Tests shrink it so the reminder fires deterministically without
+     * blocking the suite on real time.
+     */
+    stillWaitingMs?: number;
 }
 export declare const htmlJsAdapter: FeedAdapter;
 //# sourceMappingURL=html-js.d.ts.map

package/dist/core/feeds/html-js.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"html-js.d.ts","sourceRoot":"","sources":["../../../src/core/feeds/html-js.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAGtE,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AA2DlE;;;;;GAKG;AACH;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB;IACrC,iGAAiG;IACjG,MAAM,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE;QACR,MAAM,CAAC,OAAO,CAAC,EAAE;YACf,QAAQ,CAAC,EAAE,OAAO,CAAC;YACnB,KAAK,CAAC,EAAE,sBAAsB,CAAC;SAChC,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;KACpC,CAAC;CACH;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,OAAO,CAAC,EAAE;QACnB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACnC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACvC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,CACF,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,eAAe,CAAC,WAAW,CAAC,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GACvE,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpF,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAqB,SAAQ,kBAAkB;IAC9D,+EAA+E;IAC/E,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAqBD,eAAO,MAAM,aAAa,EAAE,WAmG3B,CAAC"}
+{"version":3,"file":"html-js.d.ts","sourceRoot":"","sources":["../../../src/core/feeds/html-js.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAGtE,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAoElE;;;;;GAKG;AACH;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB;IACrC,iGAAiG;IACjG,MAAM,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE;QACR,MAAM,CAAC,OAAO,CAAC,EAAE;YACf,QAAQ,CAAC,EAAE,OAAO,CAAC;YACnB,KAAK,CAAC,EAAE,sBAAsB,CAAC;SAChC,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;KACpC,CAAC;CACH;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,OAAO,CAAC,EAAE;QACnB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACnC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACvC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,CACF,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,eAAe,CAAC,WAAW,CAAC,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GACvE,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpF,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAqB,SAAQ,kBAAkB;IAC9D,+EAA+E;IAC/E,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAqBD,eAAO,MAAM,aAAa,EAAE,WAsI3B,CAAC"}

package/dist/core/feeds/html-js.js

@@ -49,6 +49,15 @@ import { contentHash, parseHtmlDocument } from "./_html-common.js";
  * going through schema parse) still get the documented behavior.
  */
 const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * Default delay before the adapter emits a `Still waiting for "<sel>"…`
+ * reminder during `waitForSelector` (#198). Chosen at ~33% of the default
+ * 30s timeout so the user gets a heads-up well before the actual timeout
+ * fires; the reminder is purely informational and never causes the wait
+ * itself to abort. Override via `HtmlJsAdapterOptions.stillWaitingMs` in
+ * tests.
+ */
+const DEFAULT_STILL_WAITING_MS = 10_000;
 /**
  * Default Playwright `page.goto()` waitUntil mode. `networkidle` is the
  * safest default for SPA / CSR pages where item data arrives via XHR after
@@ -88,6 +97,12 @@ export const htmlJsAdapter = {
         const playwright = options.playwright ?? (await loadPlaywright());
         const previous = options.state;
         const fetchedAt = new Date().toISOString();
+        // Progress reporter is optional — callers that did not opt in see the
+        // pre-#198 no-op behavior. Marker names follow ADR-0015 D4
+        // ("Chromium launching" / "Page navigated to <url>" etc.) verbatim so
+        // the user-guide stays accurate without per-call docstrings.
+        const progress = options.onProgress;
+        const stillWaitingMs = options.stillWaitingMs ?? DEFAULT_STILL_WAITING_MS;
         // Probe proxy env BEFORE launch. Playwright's `BrowserType.launch()` does
         // not honor `HTTPS_PROXY` / `HTTP_PROXY` automatically (unlike Node's
         // `--use-env-proxy` flag for built-in `fetch()`) — we must pass the URL
@@ -112,6 +127,7 @@ export const htmlJsAdapter = {
             : undefined;
         // Hardening: headless is forced true. Even if a future Playwright default
         // changes, the adapter pins it explicitly here.
+        progress?.phase("Launching Chromium…");
         const browser = await playwright.chromium.launch({
             headless: true,
             ...(proxyOption ? { proxy: proxyOption } : {}),
@@ -128,8 +144,37 @@ export const htmlJsAdapter = {
             try {
                 const page = await context.newPage();
                 try {
+                    progress?.phase(`Navigating to ${source.url}…`);
                     await page.goto(source.url, { waitUntil, timeout });
-                    await page.waitForSelector(waitFor, { timeout });
+                    progress?.phase(`Waiting for selector "${waitFor}" (timeout: ${timeout}ms)…`);
+                    // Long-running selector waits warrant a `Still waiting…` reminder
+                    // so the user knows the adapter is alive (not hung). The timer is
+                    // set up only when a progress reporter is wired so we do not keep
+                    // an idle interval running in the no-progress fast path. `unref()`
+                    // (when supported) lets the event loop exit if the underlying
+                    // wait resolves quickly — we still clear the timer below in
+                    // `finally`.
+                    let stillWaitingTimer;
+                    if (progress && stillWaitingMs > 0) {
+                        const startedAt = Date.now();
+                        stillWaitingTimer = setTimeout(() => {
+                            const elapsed = Date.now() - startedAt;
+                            const mm = String(Math.floor(elapsed / 60_000)).padStart(2, "0");
+                            const ss = String(Math.floor((elapsed % 60_000) / 1000)).padStart(2, "0");
+                            progress.phase(`Still waiting for "${waitFor}"… [${mm}:${ss}]`);
+                        }, stillWaitingMs);
+                        if (typeof stillWaitingTimer.unref === "function") {
+                            stillWaitingTimer.unref();
+                        }
+                    }
+                    try {
+                        await page.waitForSelector(waitFor, { timeout });
+                    }
+                    finally {
+                        if (stillWaitingTimer)
+                            clearTimeout(stillWaitingTimer);
+                    }
+                    progress?.phase("Capturing page content…");
                     html = await page.content();
                 }
                 finally {
@@ -143,6 +188,7 @@ export const htmlJsAdapter = {
             }
         }
         finally {
+            progress?.phase("Closing browser…");
             await browser.close();
         }
         // Dedup via content hash stored in the `lastEtag` slot (same convention

package/dist/core/feeds/html-js.js.map

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

package/dist/core/feeds/index.d.ts

@@ -1,5 +1,5 @@
 import type { Source } from "../../schemas/index.js";
 import type { FeedAdapter } from "./types.js";
 export declare function getFeedAdapter(kind: Source["kind"]): FeedAdapter;
-export type { FeedAdapter, FeedAdapterOptions, FeedFetchResult, FetchLike } from "./types.js";
+export type { FeedAdapter, FeedAdapterOptions, FeedFetchDiag, FeedFetchResult, FetchLike, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/core/feeds/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/feeds/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAMrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAU9C,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,WAAW,CAMhE;AAED,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/feeds/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAQrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAY9C,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,WAAW,CAMhE;AAED,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,SAAS,GACV,MAAM,YAAY,CAAC"}