@ozzylabs/feedradar 0.1.1 → 0.1.2

package/dist/cli/watch.d.ts

@@ -1,3 +1,4 @@
+import type { installChromium, ProbeOptions } from "../core/playwright-check.js";
 import type { Command } from "./index.js";
 export interface WatchIO {
     log?: (message: string) => void;
@@ -9,6 +10,21 @@ export interface WatchCommandOptions {
     io?: WatchIO;
     /** Test seam: override the adapter HTTP fetcher. */
     fetch?: typeof globalThis.fetch;
+    /**
+     * Test seam: override the Playwright probe used by the lazy `html-js`
+     * pre-check. Threaded straight through to `watchRun` — see watcher.ts.
+     */
+    playwrightProbeOptions?: ProbeOptions;
+    /**
+     * Test seam: override `process.env` lookup so the test can toggle
+     * `RADAR_AUTO_INSTALL_CHROMIUM=1` deterministically.
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Test seam: override the Chromium auto-install function. Tests inject a
+     * stub that records invocation without spawning the real `npx`.
+     */
+    installChromiumImpl?: typeof installChromium;
 }
 /**
  * Implementation of `watch run`.

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

@@ -1 +1 @@
-{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../../src/cli/watch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,WAAW,OAAO;IACtB,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,oDAAoD;IACpD,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AA2CD;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4CjG;AAED,eAAO,MAAM,YAAY,EAAE,OAgB1B,CAAC"}
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../../src/cli/watch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEjF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,WAAW,OAAO;IACtB,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,oDAAoD;IACpD,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC;;;OAGG;IACH,sBAAsB,CAAC,EAAE,YAAY,CAAC;IACtC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,eAAe,CAAC;CAC9C;AA2CD;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CA+CjG;AAED,eAAO,MAAM,YAAY,EAAE,OAgB1B,CAAC"}

package/dist/cli/watch.js

@@ -66,6 +66,9 @@ export async function runWatch(args, options = {}) {
             log,
             warn,
             error,
+            env: options.env,
+            playwrightProbeOptions: options.playwrightProbeOptions,
+            installChromiumImpl: options.installChromiumImpl,
         });
     }
     catch (e) {

package/dist/cli/watch.js.map

@@ -1 +1 @@
-{"version":3,"file":"watch.js","sourceRoot":"","sources":["../../src/cli/watch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAsBnE,SAAS,YAAY,CAAC,IAAc;IAClC,MAAM,GAAG,GAAiB,EAAE,CAAC;IAC7B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,QAAQ,EAAE,CAAC;YACjC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;YAChB,SAAS;QACX,CAAC;QACD,IAAI,CAAC,KAAK,UAAU,EAAE,CAAC;YACrB,GAAG,CAAC,QAAQ,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;YACzB,SAAS;QACX,CAAC;QACD,IAAI,CAAC,KAAK,aAAa,EAAE,CAAC;YACxB,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC;YACrB,SAAS;QACX,CAAC;QACD,IAAI,CAAC,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,EAAE,CAAC,CAAC;QAC1C,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,cAAc,CAAC,GAAwB;IAC9C,GAAG,CAAC,oCAAoC,CAAC,CAAC;IAC1C,GAAG,CAAC,EAAE,CAAC,CAAC;IACR,GAAG,CAAC,cAAc,CAAC,CAAC;IACpB,GAAG,CAAC,uEAAuE,CAAC,CAAC;IAC7E,GAAG,CAAC,EAAE,CAAC,CAAC;IACR,GAAG,CAAC,kBAAkB,CAAC,CAAC;IACxB,GAAG,CAAC,uDAAuD,CAAC,CAAC;IAC7D,GAAG,CAAC,oFAAoF,CAAC,CAAC;AAC5F,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAc,EAAE,UAA+B,EAAE;IAC9E,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACzC,MAAM,GAAG,GAAG,OAAO,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,MAAM,IAAI,GAAG,OAAO,CAAC,EAAE,EAAE,IAAI,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAClE,MAAM,KAAK,GAAG,OAAO,CAAC,EAAE,EAAE,KAAK,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAErE,IAAI,MAAoB,CAAC;IACzB,IAAI,CAAC;QACH,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,KAAK,CAAC,cAAc,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAClE,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAChB,cAAc,CAAC,GAAG,CAAC,CAAC;QACpB,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,MAAsB,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,QAAQ,CAAC;YACtB,GAAG;YACH,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,KAAK,EAAE,OAAO,CAAC,KAAc;YAC7B,GAAG;YACH,IAAI;YACJ,KAAK;SACN,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,KAAK,CAAC,cAAc,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAClE,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACjG,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;QACrB,GAAG,CAAC,kCAAkC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,WAAW,CAAC,CAAC;IACtF,CAAC;SAAM,CAAC;QACN,GAAG,CACD,cAAc,aAAa,uBAAuB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,YAAY,CAChG,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GAAY;IACnC,IAAI,EAAE,OAAO;IACb,OAAO,EAAE,gDAAgD;IACzD,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QAClB,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;QAC5B,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,MAAM,EAAE,CAAC;YAC/D,cAAc,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YACtC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACrB,CAAC;QACD,IAAI,GAAG,KAAK,KAAK,EAAE,CAAC;YAClB,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC;QACxB,CAAC;QACD,OAAO,CAAC,KAAK,CAAC,8BAA8B,GAAG,GAAG,CAAC,CAAC;QACpD,cAAc,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACxC,OAAO,CAAC,CAAC;IACX,CAAC;CACF,CAAC"}
+{"version":3,"file":"watch.js","sourceRoot":"","sources":["../../src/cli/watch.ts"],"names":[],"mappings":"AACA,OAAO,EAAuB,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAqCnE,SAAS,YAAY,CAAC,IAAc;IAClC,MAAM,GAAG,GAAiB,EAAE,CAAC;IAC7B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,QAAQ,EAAE,CAAC;YACjC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;YAChB,SAAS;QACX,CAAC;QACD,IAAI,CAAC,KAAK,UAAU,EAAE,CAAC;YACrB,GAAG,CAAC,QAAQ,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;YACzB,SAAS;QACX,CAAC;QACD,IAAI,CAAC,KAAK,aAAa,EAAE,CAAC;YACxB,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC;YACrB,SAAS;QACX,CAAC;QACD,IAAI,CAAC,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,EAAE,CAAC,CAAC;QAC1C,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,cAAc,CAAC,GAAwB;IAC9C,GAAG,CAAC,oCAAoC,CAAC,CAAC;IAC1C,GAAG,CAAC,EAAE,CAAC,CAAC;IACR,GAAG,CAAC,cAAc,CAAC,CAAC;IACpB,GAAG,CAAC,uEAAuE,CAAC,CAAC;IAC7E,GAAG,CAAC,EAAE,CAAC,CAAC;IACR,GAAG,CAAC,kBAAkB,CAAC,CAAC;IACxB,GAAG,CAAC,uDAAuD,CAAC,CAAC;IAC7D,GAAG,CAAC,oFAAoF,CAAC,CAAC;AAC5F,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAc,EAAE,UAA+B,EAAE;IAC9E,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACzC,MAAM,GAAG,GAAG,OAAO,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,MAAM,IAAI,GAAG,OAAO,CAAC,EAAE,EAAE,IAAI,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAClE,MAAM,KAAK,GAAG,OAAO,CAAC,EAAE,EAAE,KAAK,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAErE,IAAI,MAAoB,CAAC;IACzB,IAAI,CAAC;QACH,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,KAAK,CAAC,cAAc,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAClE,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAChB,cAAc,CAAC,GAAG,CAAC,CAAC;QACpB,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,MAAsB,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,QAAQ,CAAC;YACtB,GAAG;YACH,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,KAAK,EAAE,OAAO,CAAC,KAAc;YAC7B,GAAG;YACH,IAAI;YACJ,KAAK;YACL,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,sBAAsB,EAAE,OAAO,CAAC,sBAAsB;YACtD,mBAAmB,EAAE,OAAO,CAAC,mBAAmB;SACjD,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,KAAK,CAAC,cAAc,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAClE,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACjG,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;QACrB,GAAG,CAAC,kCAAkC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,WAAW,CAAC,CAAC;IACtF,CAAC;SAAM,CAAC;QACN,GAAG,CACD,cAAc,aAAa,uBAAuB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,YAAY,CAChG,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GAAY;IACnC,IAAI,EAAE,OAAO;IACb,OAAO,EAAE,gDAAgD;IACzD,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QAClB,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;QAC5B,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,MAAM,EAAE,CAAC;YAC/D,cAAc,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YACtC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACrB,CAAC;QACD,IAAI,GAAG,KAAK,KAAK,EAAE,CAAC;YAClB,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC;QACxB,CAAC;QACD,OAAO,CAAC,KAAK,CAAC,8BAA8B,GAAG,GAAG,CAAC,CAAC;QACpD,cAAc,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACxC,OAAO,CAAC,CAAC;IACX,CAAC;CACF,CAAC"}

package/dist/core/feeds/_html-common.d.ts

@@ -0,0 +1,30 @@
+import type { Item, Source } from "../../schemas/index.js";
+/**
+ * Shared parsing primitives for the `kind: html` (static) and `kind: html-js`
+ * (Playwright-rendered) adapters (ADR-0010 §D1).
+ *
+ * Both adapters apply the same `SourceSelectors` contract to a serialized HTML
+ * string — the only difference is how that string was acquired (raw HTTP body
+ * vs `page.content()` after JS execution). Extracting `parseHtmlDocument` and
+ * `contentHash` here keeps the selector semantics and dedup marker format in
+ * lockstep so a switch from `html` to `html-js` is transparent to downstream
+ * consumers (dedup, state file, watcher).
+ */
+/**
+ * Prefix that flags an `lastEtag` slot as carrying a content hash rather than
+ * an actual HTTP ETag. Both adapters reuse the `lastEtag` field so neither
+ * has to migrate `SourceState` (see `docs/design/source-html.md`).
+ */
+export declare const CONTENT_HASH_PREFIX = "sha256:";
+/**
+ * Parse an HTML document into validated `Item[]` using the source's
+ * `selectors`. Both `kind: html` and `kind: html-js` go through here so the
+ * selector contract stays in one place.
+ */
+export declare function parseHtmlDocument(html: string, source: Source, fetchedAt: string): Item[];
+/**
+ * Compute the sha256 of the raw response body, prefixed so callers can tell
+ * it apart from a real ETag inside `SourceState.lastEtag`.
+ */
+export declare function contentHash(body: string): string;
+//# sourceMappingURL=_html-common.d.ts.map

package/dist/core/feeds/_html-common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_html-common.d.ts","sourceRoot":"","sources":["../../../src/core/feeds/_html-common.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAmB,MAAM,wBAAwB,CAAC;AAI5E;;;;;;;;;;GAUG;AAEH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAoJ7C;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,CAiBzF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD"}

package/dist/core/feeds/_html-common.js

@@ -0,0 +1,192 @@
+import { createHash } from "node:crypto";
+import { parse as parseHtml } from "node-html-parser";
+import { ItemSchema } from "../../schemas/index.js";
+import { deriveItemId, deriveStableKey } from "./derive-id.js";
+/**
+ * Shared parsing primitives for the `kind: html` (static) and `kind: html-js`
+ * (Playwright-rendered) adapters (ADR-0010 §D1).
+ *
+ * Both adapters apply the same `SourceSelectors` contract to a serialized HTML
+ * string — the only difference is how that string was acquired (raw HTTP body
+ * vs `page.content()` after JS execution). Extracting `parseHtmlDocument` and
+ * `contentHash` here keeps the selector semantics and dedup marker format in
+ * lockstep so a switch from `html` to `html-js` is transparent to downstream
+ * consumers (dedup, state file, watcher).
+ */
+/**
+ * Prefix that flags an `lastEtag` slot as carrying a content hash rather than
+ * an actual HTTP ETag. Both adapters reuse the `lastEtag` field so neither
+ * has to migrate `SourceState` (see `docs/design/source-html.md`).
+ */
+export const CONTENT_HASH_PREFIX = "sha256:";
+/** Attributes the parser checks before falling back to text content. */
+const DATETIME_ATTRS = ["datetime", "content", "value"];
+/**
+ * Convert an `HTMLElement | null` to its trimmed text, or `undefined` when
+ * the selector did not match. We always trim because raw scrapes routinely
+ * carry surrounding whitespace from formatted markup.
+ */
+function textOf(el) {
+    if (!el)
+        return undefined;
+    const text = el.text?.trim();
+    return text ? text : undefined;
+}
+/**
+ * Apply a CSS selector relative to `root` and return the first match.
+ * `node-html-parser` returns `null` instead of throwing for invalid input,
+ * which matches what callers want here (a missing field, not a hard error).
+ */
+function queryFirst(root, selector) {
+    return root.querySelector(selector);
+}
+/**
+ * Resolve the `link` selector to an `href` (or text fallback).
+ *
+ * Anchor tags expose the URL via `href` so we prefer the attribute. When the
+ * selector points at a non-anchor (e.g. a `<div data-link>` wrapper used by
+ * some changelog layouts), we fall back to text content so the adapter can
+ * still operate, deferring URL validation to `ItemSchema`.
+ */
+function pickLink(el) {
+    if (!el)
+        return undefined;
+    const href = el.getAttribute("href");
+    if (href && href.trim())
+        return href.trim();
+    return textOf(el);
+}
+/**
+ * Resolve `publishedAt` to a candidate string for `new Date()`.
+ *
+ * `<time datetime="2026-05-12">` and `<meta content="..."/>` markup hide the
+ * canonical timestamp in attributes; the visible text is often a
+ * localized "May 12, 2026" that is harder to parse reliably. We probe the
+ * known attributes first, then fall back to element text.
+ */
+function pickDatetime(el) {
+    if (!el)
+        return undefined;
+    for (const attr of DATETIME_ATTRS) {
+        const value = el.getAttribute(attr);
+        if (value && value.trim())
+            return value.trim();
+    }
+    return textOf(el);
+}
+/**
+ * Try to parse a candidate timestamp into ISO 8601. Returns `undefined` for
+ * unparseable inputs so the item can still be emitted (RSS adapter parity).
+ */
+function toIsoDate(value) {
+    if (!value)
+        return undefined;
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return undefined;
+    return date.toISOString();
+}
+/** Collect the trimmed text of every match for `selector`. */
+function collectTags(root, selector) {
+    if (!selector)
+        return undefined;
+    const tags = root
+        .querySelectorAll(selector)
+        .map((el) => el.text?.trim())
+        .filter((t) => !!t && t.length > 0);
+    return tags.length > 0 ? tags : undefined;
+}
+/**
+ * Resolve a relative `link` against the source URL.
+ *
+ * Many sites publish `<a href="/changelog/foo">` rather than absolute URLs;
+ * without resolution `ItemSchema`'s `z.string().url()` would drop them. We
+ * intentionally swallow `URL` constructor errors so a malformed `link`
+ * surfaces as a normal validation drop later instead of breaking the whole
+ * fetch.
+ */
+function resolveUrl(raw, base) {
+    try {
+        return new URL(raw, base).toString();
+    }
+    catch {
+        return raw;
+    }
+}
+/** Normalize one matched element into an Item, or `null` to drop it. */
+function parseItem(itemEl, selectors, source, fetchedAt) {
+    const title = textOf(queryFirst(itemEl, selectors.title));
+    const linkRaw = pickLink(queryFirst(itemEl, selectors.link));
+    if (!title || !linkRaw)
+        return null;
+    const url = resolveUrl(linkRaw, source.url);
+    const summary = selectors.summary ? textOf(queryFirst(itemEl, selectors.summary)) : undefined;
+    const body = selectors.body ? textOf(queryFirst(itemEl, selectors.body)) : undefined;
+    const publishedAt = selectors.publishedAt
+        ? toIsoDate(pickDatetime(queryFirst(itemEl, selectors.publishedAt)))
+        : undefined;
+    const tags = collectTags(itemEl, selectors.tags);
+    const stableKey = deriveStableKey({
+        url,
+        fallbackHashInputs: [title, publishedAt],
+    });
+    const id = deriveItemId(title, stableKey);
+    // Preserve a structured snapshot of the raw scrape rather than the
+    // `HTMLElement` instance itself — the watcher serializes `raw` to YAML and
+    // we want the on-disk payload to be diff-friendly.
+    const raw = { title, link: linkRaw };
+    if (summary !== undefined)
+        raw.summary = summary;
+    if (body !== undefined)
+        raw.body = body;
+    if (publishedAt !== undefined)
+        raw.publishedAt = publishedAt;
+    if (tags !== undefined)
+        raw.tags = tags;
+    return validateItem({
+        id,
+        sourceId: source.id,
+        title,
+        url,
+        summary,
+        publishedAt,
+        fetchedAt,
+        raw,
+    });
+}
+function validateItem(candidate) {
+    const result = ItemSchema.safeParse(candidate);
+    // Items that fail validation (e.g. unresolvable URL) are dropped silently —
+    // see rss.ts for the same fail-soft rationale.
+    return result.success ? result.data : null;
+}
+/**
+ * Parse an HTML document into validated `Item[]` using the source's
+ * `selectors`. Both `kind: html` and `kind: html-js` go through here so the
+ * selector contract stays in one place.
+ */
+export function parseHtmlDocument(html, source, fetchedAt) {
+    if (!source.selectors) {
+        throw new Error(`html adapter: source '${source.id}' has no selectors`);
+    }
+    const selectors = source.selectors;
+    let root;
+    try {
+        root = parseHtml(html);
+    }
+    catch (e) {
+        throw new Error(`html adapter: failed to parse HTML: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const itemEls = root.querySelectorAll(selectors.item);
+    return itemEls
+        .map((el) => parseItem(el, selectors, source, fetchedAt))
+        .filter((i) => i !== null);
+}
+/**
+ * Compute the sha256 of the raw response body, prefixed so callers can tell
+ * it apart from a real ETag inside `SourceState.lastEtag`.
+ */
+export function contentHash(body) {
+    return `${CONTENT_HASH_PREFIX}${createHash("sha256").update(body).digest("hex")}`;
+}
+//# sourceMappingURL=_html-common.js.map

package/dist/core/feeds/_html-common.js.map

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

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

@@ -0,0 +1,50 @@
+import type { SourceJsOptions } from "../../schemas/index.js";
+import type { FeedAdapter, FeedAdapterOptions } from "./types.js";
+/**
+ * Minimal subset of the Playwright surface this adapter uses. Defined
+ * structurally so the `chromium` argument passed by tests does not need to
+ * pull in the full Playwright type tree (which is itself an optional peer
+ * dep and therefore not guaranteed to be installed in dev).
+ */
+export interface PlaywrightLike {
+    chromium: {
+        launch(options?: {
+            headless?: boolean;
+        }): Promise<PlaywrightBrowserLike>;
+    };
+}
+export interface PlaywrightBrowserLike {
+    newContext(options?: {
+        acceptDownloads?: boolean;
+        userAgent?: string;
+    }): Promise<PlaywrightContextLike>;
+    close(): Promise<void>;
+}
+export interface PlaywrightContextLike {
+    newPage(): Promise<PlaywrightPageLike>;
+    close(): Promise<void>;
+}
+export interface PlaywrightPageLike {
+    goto(url: string, options?: {
+        waitUntil?: SourceJsOptions["waitUntil"];
+        timeout?: number;
+    }): Promise<unknown>;
+    waitForSelector(selector: string, options?: {
+        timeout?: number;
+    }): Promise<unknown>;
+    content(): Promise<string>;
+    close(): Promise<void>;
+}
+/**
+ * Test-only extension to `FeedAdapterOptions` for the `html-js` adapter.
+ *
+ * Production callers leave `playwright` unset and the adapter dynamically
+ * imports it. Tests inject a fake module so they can exercise the adapter
+ * without spinning up real Chromium. The shape mirrors the subset above.
+ */
+export interface HtmlJsAdapterOptions extends FeedAdapterOptions {
+    /** Injected Playwright module (tests only). Production uses dynamic import. */
+    playwright?: PlaywrightLike;
+}
+export declare const htmlJsAdapter: FeedAdapter;
+//# sourceMappingURL=html-js.d.ts.map

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

@@ -0,0 +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;AAEtE,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AA+ClE;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE;QACR,MAAM,CAAC,OAAO,CAAC,EAAE;YAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;SAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;KAC1E,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;CAC7B;AAqBD,eAAO,MAAM,aAAa,EAAE,WAyE3B,CAAC"}

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

@@ -0,0 +1,135 @@
+import { contentHash, parseHtmlDocument } from "./_html-common.js";
+/**
+ * `kind: html-js` adapter — Playwright-rendered HTML scraping (ADR-0010).
+ *
+ * Same selector contract as `kind: html` (delegates to `parseHtmlDocument`),
+ * but acquires the document by driving headless Chromium so SPA / CSR pages
+ * (Next.js, Notion embeds, Algolia DocSearch, etc.) that ship empty initial
+ * HTML can still be scraped.
+ *
+ * ## Hardening (ADR-0010 §D5 — hardcoded, NOT user-configurable)
+ *
+ * | Policy              | Value                | Rationale                                                |
+ * |---------------------|----------------------|----------------------------------------------------------|
+ * | `headless`          | `true`               | UI mode is CI-incompatible and an operator-UI risk.      |
+ * | `acceptDownloads`   | `false`              | Block drive-by downloads (page JS-triggered file saves). |
+ * | context reuse       | none — fresh each fetch | Prevent SW / IndexedDB / localStorage injection persistence and cross-source state mixing. |
+ * | default `timeout`   | 30000ms              | Cap OOM / infinite loops on pathological pages.          |
+ * | `page.close()`      | in `finally`         | Prevent page leak / memory accumulation.                 |
+ * | viewport            | Playwright default   | Avoid bloating DOM with oversized viewports.             |
+ *
+ * The above are intentionally NOT exposed through `SourceJsOptions`. Users
+ * may tune `waitFor` / `waitUntil` / `timeout` / `userAgent`, but the threat
+ * model assumes the policy floor above always holds.
+ *
+ * ## Optional peer dep
+ *
+ * Playwright is declared as an *optional* peer dependency (ADR-0010 §D3) so
+ * users who only run `kind: rss` / `kind: html` are not forced to install
+ * Chromium. The import is therefore `await import("playwright")` and resolves
+ * lazily on the first `html-js` fetch; missing-module errors are translated
+ * into a user-friendly install hint.
+ */
+/**
+ * Default per-step timeout in ms when `Source.js?.timeout` is omitted.
+ * Mirrors `SourceJsOptionsSchema`'s default so adapter-direct callers (not
+ * going through schema parse) still get the documented behavior.
+ */
+const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * Default Playwright `page.goto()` waitUntil mode. `networkidle` is the
+ * safest default for SPA / CSR pages where item data arrives via XHR after
+ * the document has loaded.
+ */
+const DEFAULT_WAIT_UNTIL = "networkidle";
+/**
+ * Dynamically import Playwright. Translates the very common
+ * "package not installed" failure into the install hint from ADR-0010 §D3.
+ */
+async function loadPlaywright() {
+    try {
+        // Bare specifier: resolves via the consumer project's node_modules. The
+        // type assertion narrows the dynamic import to the subset we use.
+        const mod = (await import("playwright"));
+        return mod;
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        throw new Error(`html-js adapter: failed to load Playwright (${message}). ` +
+            "Install it with: `npm i playwright && npx playwright install chromium`");
+    }
+}
+export const htmlJsAdapter = {
+    kind: "html-js",
+    fetch: async (source, options = {}) => {
+        if (!source.selectors) {
+            throw new Error(`html-js adapter: source '${source.id}' has no selectors`);
+        }
+        const selectors = source.selectors;
+        const js = source.js;
+        const timeout = js?.timeout ?? DEFAULT_TIMEOUT_MS;
+        const waitUntil = js?.waitUntil ?? DEFAULT_WAIT_UNTIL;
+        // When `waitFor` is omitted we wait for the item selector itself — the
+        // common "wait until the item list rendered" intent without extra config.
+        const waitFor = js?.waitFor ?? selectors.item;
+        const playwright = options.playwright ?? (await loadPlaywright());
+        const previous = options.state;
+        const fetchedAt = new Date().toISOString();
+        // Hardening: headless is forced true. Even if a future Playwright default
+        // changes, the adapter pins it explicitly here.
+        const browser = await playwright.chromium.launch({ headless: true });
+        let html;
+        try {
+            // Hardening: fresh context per fetch (no SW / IndexedDB / localStorage
+            // persistence across fetches or sources). `acceptDownloads: false`
+            // blocks drive-by download routes (page JS triggering file saves).
+            const context = await browser.newContext({
+                acceptDownloads: false,
+                ...(js?.userAgent ? { userAgent: js.userAgent } : {}),
+            });
+            try {
+                const page = await context.newPage();
+                try {
+                    await page.goto(source.url, { waitUntil, timeout });
+                    await page.waitForSelector(waitFor, { timeout });
+                    html = await page.content();
+                }
+                finally {
+                    // `finally` guarantees page close even on goto / waitFor timeout —
+                    // prevents page leak / memory accumulation per ADR-0010 §D5.
+                    await page.close();
+                }
+            }
+            finally {
+                await context.close();
+            }
+        }
+        finally {
+            await browser.close();
+        }
+        // Dedup via content hash stored in the `lastEtag` slot (same convention
+        // as `kind: html` — see `_html-common.ts`). Server-side ETags are not
+        // observable from `page.content()`, so the content hash is the only
+        // dedup signal available here.
+        const bodyHash = contentHash(html);
+        if (previous?.lastEtag === bodyHash) {
+            return {
+                items: [],
+                notModified: true,
+                state: {
+                    lastFetchedAt: fetchedAt,
+                    lastEtag: bodyHash,
+                },
+            };
+        }
+        const items = parseHtmlDocument(html, source, fetchedAt);
+        return {
+            items,
+            state: {
+                lastFetchedAt: fetchedAt,
+                lastEtag: bodyHash,
+            },
+        };
+    },
+};
+//# sourceMappingURL=html-js.js.map

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

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

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

@@ -1,10 +1,4 @@
-import type { Item, Source } from "../../schemas/index.js";
 import type { FeedAdapter } from "./types.js";
-/**
- * Parse an HTML document into validated `Item[]` using the source's
- * `selectors`. Exported so tests can drive the parser directly without
- * needing a fake HTTP layer.
- */
-export declare function parseHtmlDocument(html: string, source: Source, fetchedAt: string): Item[];
+export { parseHtmlDocument } from "./_html-common.js";
 export declare const htmlAdapter: FeedAdapter;
 //# sourceMappingURL=html.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../../src/core/feeds/html.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAmB,MAAM,wBAAwB,CAAC;AAG5E,OAAO,KAAK,EAAE,WAAW,EAAiC,MAAM,YAAY,CAAC;AA6J7E;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,CAiBzF;AA+CD,eAAO,MAAM,WAAW,EAAE,WAuDzB,CAAC"}
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../../src/core/feeds/html.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAiC,MAAM,YAAY,CAAC;AAK7E,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAyCtD,eAAO,MAAM,WAAW,EAAE,WAuDzB,CAAC"}