agent-bober 0.18.0 → 0.19.0

package/dist/seo/sources/damcrawler-crawl-engine.js

@@ -0,0 +1,154 @@
+import { ContentSanitizer } from "../content-sanitizer.js";
+const defaultLoader = async () => {
+    // Indirection through a variable: under `moduleResolution: NodeNext` a
+    // LITERAL `import("damcrawler")` is statically resolved by tsc and fails
+    // with TS2307 when the dep is absent. Routing the specifier through a
+    // `string` variable makes tsc treat the result as `any`, so `tsc --noEmit`
+    // stays clean whether or not damcrawler is installed (sprint briefing
+    // Pattern D / Pitfall #4).
+    const mod = "damcrawler";
+    return (await import(mod).catch(() => undefined));
+};
+/** `try { return new URL(u).origin } catch { return "" }` — URL parsing must never throw here. */
+function safeOrigin(u) {
+    try {
+        return new URL(u).origin;
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * `CrawlEngine` backed by damcrawler. Serves `crawl`/`urlVisibility`/
+ * `linkGraph` fully; every method is guard-first, lazy-load, SSRF-guarded,
+ * and never-throw.
+ */
+export class DamcrawlerCrawlEngine {
+    egress;
+    load;
+    now;
+    constructor(egress, load = defaultLoader, 
+    // Injected clock for provenance.retrievedAt — deterministic in tests.
+    now = () => new Date().toISOString()) {
+        this.egress = egress;
+        this.load = load;
+        this.now = now;
+    }
+    /** Site crawl -> sanitized `CrawlPageRow[]`. Guard, load, SSRF-guard, crawl+sanitize, degrade — never throws. */
+    async crawl(q) {
+        try {
+            this.egress.assertAllowed("site-crawl");
+        }
+        catch {
+            return { kind: "abstain", reason: "egress-site-crawl-disabled" };
+        }
+        const dam = await this.load();
+        if (!dam)
+            return { kind: "abstain", reason: "damcrawler-not-installed" };
+        try {
+            await dam.assertSafeUrl(q.rootUrl); // F2: engine-boundary SSRF guard, before any damcrawler network call
+        }
+        catch {
+            return { kind: "abstain", reason: "ssrf-blocked" };
+        }
+        try {
+            const result = await dam.crawl(q.rootUrl, { limit: q.limit, maxDepth: q.maxDepth });
+            const sanitizer = new ContentSanitizer(dam.sanitize); // ADR-11: sanitize at the network->in-process boundary
+            const rows = result.pages.map((p) => ({
+                // F1: title/url are attacker-controlled free text just like the body
+                // — every field CrawlPageRow exposes to SeoAnalyzer's prompt must be
+                // sanitized, not only `.markdown`.
+                url: sanitizer.clean(p.url, p.url).content,
+                title: sanitizer.clean(p.title, p.url).content,
+                content: sanitizer.clean(p.markdown, p.url).content, // page body field is `markdown`, not `content`
+            }));
+            return { kind: "data", rows, provenance: { source: "damcrawler", retrievedAt: this.now() } };
+        }
+        catch {
+            return { kind: "abstain", reason: "source-error" }; // BrowserError/TimeoutError/CrawlError all land here
+        }
+    }
+    /** URL indexability probe -> single-row `UrlInspectionRow[]`. Guard, load, SSRF-guard, probe, degrade — never throws. */
+    async urlVisibility(q) {
+        try {
+            this.egress.assertAllowed("site-crawl");
+        }
+        catch {
+            return { kind: "abstain", reason: "egress-site-crawl-disabled" };
+        }
+        const dam = await this.load();
+        if (!dam)
+            return { kind: "abstain", reason: "damcrawler-not-installed" };
+        try {
+            // F2: guard BOTH caller-supplied URLs before any damcrawler network call.
+            await dam.assertSafeUrl(q.inspectionUrl);
+            await dam.assertSafeUrl(q.siteUrl);
+        }
+        catch {
+            return { kind: "abstain", reason: "ssrf-blocked" };
+        }
+        try {
+            const visibility = await dam.probeVisibility(q.inspectionUrl, q.siteUrl);
+            const sanitizer = new ContentSanitizer(dam.sanitize); // Sprint 9 fix: sanitize at the boundary, mirrors crawl()
+            const row = {
+                url: sanitizer.clean(q.inspectionUrl, q.inspectionUrl).content,
+                indexingState: visibility === "visible" ? "indexed" : "not-indexed",
+            };
+            return { kind: "data", rows: [row], provenance: { source: "damcrawler", retrievedAt: this.now() } };
+        }
+        catch {
+            return { kind: "abstain", reason: "source-error" };
+        }
+    }
+    /**
+     * Internal link graph -> flat `LinkGraphRow[]` edges (ADR-6). Guard,
+     * load, SSRF-guard, scrape+extract, degrade — never throws. Uses
+     * `scrape(formats:["links"])` rather than `crawl()`, which yields
+     * Markdown with no link data (see class docstring).
+     */
+    async linkGraph(q) {
+        try {
+            this.egress.assertAllowed("site-crawl");
+        }
+        catch {
+            return { kind: "abstain", reason: "egress-site-crawl-disabled" };
+        }
+        const dam = await this.load();
+        if (!dam)
+            return { kind: "abstain", reason: "damcrawler-not-installed" };
+        try {
+            await dam.assertSafeUrl(q.rootUrl); // F2
+        }
+        catch {
+            return { kind: "abstain", reason: "ssrf-blocked" };
+        }
+        try {
+            const results = await dam.scrape([q.rootUrl], { formats: ["links"], limit: q.limit });
+            const sanitizer = new ContentSanitizer(dam.sanitize); // Sprint 9 fix (F1): sanitize at the boundary, mirrors crawl()
+            const rootOrigin = safeOrigin(q.rootUrl);
+            const rows = [];
+            for (const page of results) {
+                if (page.error)
+                    continue; // a failed fetch for this page yields no reliable link data
+                for (const link of page.links ?? []) {
+                    // F1: fromUrl/toUrl/anchor are attacker-controlled free text (the
+                    // page being linked FROM controls all three) — sanitize every
+                    // field BEFORE it can reach SeoAnalyzer's prompt serialization.
+                    const internal = safeOrigin(link.url) === rootOrigin; // same-origin computed on the RAW url, before sanitizing
+                    rows.push({
+                        fromUrl: sanitizer.clean(page.url, page.url).content,
+                        toUrl: sanitizer.clean(link.url, page.url).content,
+                        anchor: link.text ? sanitizer.clean(link.text, page.url).content : undefined,
+                        internal,
+                    });
+                }
+            }
+            // A partial/empty graph is a valid `data` outcome (ADR-6) — never fabricate, never throw.
+            return { kind: "data", rows, provenance: { source: "damcrawler", retrievedAt: this.now() } };
+        }
+        catch {
+            return { kind: "abstain", reason: "source-error" };
+        }
+    }
+}
+//# sourceMappingURL=damcrawler-crawl-engine.js.map

package/dist/seo/sources/damcrawler-crawl-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"damcrawler-crawl-engine.js","sourceRoot":"","sources":["../../../src/seo/sources/damcrawler-crawl-engine.ts"],"names":[],"mappings":"AAkEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AA4C3D,MAAM,aAAa,GAAqB,KAAK,IAAI,EAAE;IACjD,uEAAuE;IACvE,yEAAyE;IACzE,sEAAsE;IACtE,2EAA2E;IAC3E,sEAAsE;IACtE,2BAA2B;IAC3B,MAAM,GAAG,GAAG,YAAY,CAAC;IACzB,OAAO,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAiC,CAAC;AACpF,CAAC,CAAC;AAEF,kGAAkG;AAClG,SAAS,UAAU,CAAC,CAAS;IAC3B,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,qBAAqB;IAEb;IACA;IAEA;IAJnB,YACmB,MAAsB,EACtB,OAAyB,aAAa;IACvD,sEAAsE;IACrD,MAAoB,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAHlD,WAAM,GAAN,MAAM,CAAgB;QACtB,SAAI,GAAJ,IAAI,CAAkC;QAEtC,QAAG,GAAH,GAAG,CAA+C;IAClE,CAAC;IAEJ,iHAAiH;IACjH,KAAK,CAAC,KAAK,CAAC,CAAa;QACvB,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC;QAC1C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,4BAA4B,EAAE,CAAC;QACnE,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC9B,IAAI,CAAC,GAAG;YAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,0BAA0B,EAAE,CAAC;QAEzE,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,qEAAqE;QAC3G,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;QACrD,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;YACpF,MAAM,SAAS,GAAG,IAAI,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,uDAAuD;YAC7G,MAAM,IAAI,GAAmB,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACpD,qEAAqE;gBACrE,qEAAqE;gBACrE,mCAAmC;gBACnC,GAAG,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO;gBAC1C,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO;gBAC9C,OAAO,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,+CAA+C;aACrG,CAAC,CAAC,CAAC;YACJ,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,EAAE,CAAC;QAC/F,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC,qDAAqD;QAC3G,CAAC;IACH,CAAC;IAED,yHAAyH;IACzH,KAAK,CAAC,aAAa,CAAC,CAAqB;QACvC,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC;QAC1C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,4BAA4B,EAAE,CAAC;QACnE,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC9B,IAAI,CAAC,GAAG;YAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,0BAA0B,EAAE,CAAC;QAEzE,IAAI,CAAC;YACH,0EAA0E;YAC1E,MAAM,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC;YACzC,MAAM,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QACrC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;QACrD,CAAC;QAED,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,MAAM,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;YACzE,MAAM,SAAS,GAAG,IAAI,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,0DAA0D;YAChH,MAAM,GAAG,GAAqB;gBAC5B,GAAG,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,OAAO;gBAC9D,aAAa,EAAE,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa;aACpE,CAAC;YACF,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,EAAE,CAAC;QACtG,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;QACrD,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,SAAS,CAAC,CAAiB;QAC/B,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC;QAC1C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,4BAA4B,EAAE,CAAC;QACnE,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC9B,IAAI,CAAC,GAAG;YAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,0BAA0B,EAAE,CAAC;QAEzE,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK;QAC3C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;QACrD,CAAC;QAED,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;YACtF,MAAM,SAAS,GAAG,IAAI,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,+DAA+D;YACrH,MAAM,UAAU,GAAG,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YACzC,MAAM,IAAI,GAAmB,EAAE,CAAC;YAChC,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;gBAC3B,IAAI,IAAI,CAAC,KAAK;oBAAE,SAAS,CAAC,4DAA4D;gBACtF,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;oBACpC,kEAAkE;oBAClE,8DAA8D;oBAC9D,gEAAgE;oBAChE,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,UAAU,CAAC,CAAC,yDAAyD;oBAC/G,IAAI,CAAC,IAAI,CAAC;wBACR,OAAO,EAAE,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO;wBACpD,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO;wBAClD,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;wBAC5E,QAAQ;qBACT,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;YACD,0FAA0F;YAC1F,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,EAAE,CAAC;QAC/F,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;QACrD,CAAC;IACH,CAAC;CACF"}

package/dist/seo/sources/damcrawler-serp-provider.d.ts

@@ -0,0 +1,75 @@
+/**
+ * DamcrawlerSerpProvider — the `SerpProvider` (`../serp-provider.js`)
+ * implementation backed by damcrawler's `search()` command
+ * (spec-20260717-seo-improver-builder, Sprint 8; ADR-10).
+ *
+ * Mirrors `DamcrawlerCrawlEngine`'s guard-first/lazy-load/never-throw shape
+ * (`./damcrawler-crawl-engine.ts:133-165`) with three differences:
+ *   1. ADR-10: gated by the `"site-crawl"` axis (SAME Playwright-scrape/
+ *      anti-bot/ToS risk surface as the crawler), NOT `"serp-provider"`
+ *      (that axis means "licensed, USD-metered DataForSEO egress" — routing
+ *      un-licensed scraping through it would silently authorize ToS-gray
+ *      scraping the operator never consented to).
+ *   2. Zero USD — no `SeoQuotaGovernor` is injected or consulted at all.
+ *   3. No `assertSafeUrl` SSRF guard — the input is a search keyword, and
+ *      the result URLs are returned as DATA (never fetched by this class),
+ *      unlike `crawl()`'s `rootUrl`/`urlVisibility()`'s inspection URLs
+ *      which damcrawler itself fetches. Sanitization is the required
+ *      defense here (see below), not SSRF.
+ *
+ * SERP result `title` and `url` are attacker-influenced free-text (the
+ * page being ranked controls both) — per ADR-11 both are sanitized through
+ * `ContentSanitizer` (`../content-sanitizer.js`) at the network->in-process
+ * boundary, BEFORE the row ever reaches `SeoAnalyzer`'s prompt
+ * serialization. Any anti-bot/search/parse error degrades to
+ * `{ kind: "abstain", reason: "serp-scrape-error" }` — this class NEVER
+ * throws to its caller.
+ */
+import type { SeoEgressGuard } from "../egress.js";
+import type { DataOutcome } from "../types.js";
+import type { SerpRow } from "../data-source.js";
+import type { SerpProvider } from "../serp-provider.js";
+/**
+ * NARROW view of the ONLY damcrawler surface this provider calls (mirrors
+ * `DamcrawlerModule`, `./damcrawler-crawl-engine.ts:77-95`):
+ *   - `search(query, options)` — `damcrawler/src/commands/search.ts:481`;
+ *     returns `{ results: SearchResultItem[{title,url,description}] }`.
+ *   - `sanitize(raw, options?)` — the ONLY damcrawler sanitize export that
+ *     yields `hadThreats` (`damcrawler/src/lib/sanitize.ts:68-79,89`);
+ *     `sanitizeWithReport` returns a bare `string` and must NOT be used.
+ */
+export interface DamcrawlerSearchModule {
+    search(query: string, options: {
+        limit?: number;
+        country?: string;
+    }): Promise<{
+        results: Array<{
+            title: string;
+            url: string;
+            description: string;
+        }>;
+    }>;
+    sanitize(raw: string, options?: {
+        sourceUrl?: string;
+    }): {
+        content: string;
+        hadThreats: boolean;
+    };
+}
+/** Loader seam — the default performs the lazy dynamic import; tests inject a FAKE module (or `undefined` to simulate the dep being absent). */
+export type DamcrawlerSearchLoader = () => Promise<DamcrawlerSearchModule | undefined>;
+/**
+ * `SerpProvider` backed by damcrawler's search scrape. Guard-first,
+ * lazy-load, sanitize, never-throw; books zero USD (no governor at all).
+ */
+export declare class DamcrawlerSerpProvider implements SerpProvider {
+    private readonly egress;
+    private readonly load;
+    private readonly now;
+    private readonly limit;
+    readonly name: "damcrawler";
+    readonly estCostUsdPerResult = 0;
+    constructor(egress: SeoEgressGuard, load?: DamcrawlerSearchLoader, now?: () => string, limit?: number);
+    serp(keyword: string, location: string): Promise<DataOutcome<SerpRow[]>>;
+}
+//# sourceMappingURL=damcrawler-serp-provider.d.ts.map

package/dist/seo/sources/damcrawler-serp-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"damcrawler-serp-provider.d.ts","sourceRoot":"","sources":["../../../src/seo/sources/damcrawler-serp-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxD;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAsB;IACrC,MAAM,CACJ,KAAK,EAAE,MAAM,EACb,OAAO,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC5C,OAAO,CAAC;QAAE,OAAO,EAAE,KAAK,CAAC;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC,CAAC;IACpF,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,CAAA;KAAE,CAAC;CACnG;AAED,gJAAgJ;AAChJ,MAAM,MAAM,sBAAsB,GAAG,MAAM,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC,CAAC;AAavF;;;GAGG;AACH,qBAAa,sBAAuB,YAAW,YAAY;IAKvD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAErB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK;IARxB,QAAQ,CAAC,IAAI,EAAG,YAAY,CAAU;IACtC,QAAQ,CAAC,mBAAmB,KAAK;gBAGd,MAAM,EAAE,cAAc,EACtB,IAAI,GAAE,sBAAsC,EAE5C,GAAG,GAAE,MAAM,MAAuC,EAClD,KAAK,SAAK;IAGvB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC;CA0B/E"}

package/dist/seo/sources/damcrawler-serp-provider.js

@@ -0,0 +1,60 @@
+import { ContentSanitizer } from "../content-sanitizer.js";
+const defaultLoader = async () => {
+    // Indirection through a variable: a LITERAL `import("damcrawler")` is
+    // statically resolved by tsc under `moduleResolution: NodeNext` and fails
+    // with TS2307 when the dep is absent. Routing the specifier through a
+    // `string` variable makes tsc treat the result as `any`, so
+    // `tsc --noEmit` stays clean whether or not damcrawler is installed
+    // (mirrors `damcrawler-crawl-engine.ts:100-109`, Pattern B).
+    const mod = "damcrawler";
+    return (await import(mod).catch(() => undefined));
+};
+/**
+ * `SerpProvider` backed by damcrawler's search scrape. Guard-first,
+ * lazy-load, sanitize, never-throw; books zero USD (no governor at all).
+ */
+export class DamcrawlerSerpProvider {
+    egress;
+    load;
+    now;
+    limit;
+    name = "damcrawler";
+    estCostUsdPerResult = 0; // zero-USD scrape (ADR-10)
+    constructor(egress, load = defaultLoader, 
+    // Injected clock for provenance.retrievedAt — deterministic in tests.
+    now = () => new Date().toISOString(), limit = 10) {
+        this.egress = egress;
+        this.load = load;
+        this.now = now;
+        this.limit = limit;
+    }
+    async serp(keyword, location) {
+        // -- STATEMENT 1: egress gate (ADR-10) — FIRST, before any import --
+        try {
+            this.egress.assertAllowed("site-crawl");
+        }
+        catch {
+            return { kind: "abstain", reason: "egress-site-crawl-disabled" };
+        }
+        const dam = await this.load();
+        if (!dam)
+            return { kind: "abstain", reason: "damcrawler-not-installed" };
+        try {
+            const { results } = await dam.search(keyword, { limit: this.limit, country: location });
+            const sanitizer = new ContentSanitizer(dam.sanitize); // ADR-11: sanitize at the network->in-process boundary
+            const rows = results.map((r, i) => {
+                const url = sanitizer.clean(r.url, r.url).content;
+                const row = { keyword, position: i + 1, url, location };
+                const title = sanitizer.clean(r.title, r.url).content;
+                if (title)
+                    row.title = title; // SerpRow.title is optional — set only when non-empty (mirrors parseSerp)
+                return row;
+            });
+            return { kind: "data", rows, provenance: { source: "damcrawler", retrievedAt: this.now() } };
+        }
+        catch {
+            return { kind: "abstain", reason: "serp-scrape-error" }; // anti-bot/search/parse error -> abstain, NEVER throw
+        }
+    }
+}
+//# sourceMappingURL=damcrawler-serp-provider.js.map

package/dist/seo/sources/damcrawler-serp-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"damcrawler-serp-provider.js","sourceRoot":"","sources":["../../../src/seo/sources/damcrawler-serp-provider.ts"],"names":[],"mappings":"AA+BA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAsB3D,MAAM,aAAa,GAA2B,KAAK,IAAI,EAAE;IACvD,sEAAsE;IACtE,0EAA0E;IAC1E,sEAAsE;IACtE,4DAA4D;IAC5D,oEAAoE;IACpE,6DAA6D;IAC7D,MAAM,GAAG,GAAG,YAAY,CAAC;IACzB,OAAO,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAuC,CAAC;AAC1F,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,OAAO,sBAAsB;IAKd;IACA;IAEA;IACA;IARV,IAAI,GAAG,YAAqB,CAAC;IAC7B,mBAAmB,GAAG,CAAC,CAAC,CAAC,2BAA2B;IAE7D,YACmB,MAAsB,EACtB,OAA+B,aAAa;IAC7D,sEAAsE;IACrD,MAAoB,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAClD,QAAQ,EAAE;QAJV,WAAM,GAAN,MAAM,CAAgB;QACtB,SAAI,GAAJ,IAAI,CAAwC;QAE5C,QAAG,GAAH,GAAG,CAA+C;QAClD,UAAK,GAAL,KAAK,CAAK;IAC1B,CAAC;IAEJ,KAAK,CAAC,IAAI,CAAC,OAAe,EAAE,QAAgB;QAC1C,qEAAqE;QACrE,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC;QAC1C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,4BAA4B,EAAE,CAAC;QACnE,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC9B,IAAI,CAAC,GAAG;YAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,0BAA0B,EAAE,CAAC;QAEzE,IAAI,CAAC;YACH,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;YACxF,MAAM,SAAS,GAAG,IAAI,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,uDAAuD;YAC7G,MAAM,IAAI,GAAc,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;gBAC3C,MAAM,GAAG,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC;gBAClD,MAAM,GAAG,GAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;gBACjE,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC;gBACtD,IAAI,KAAK;oBAAE,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,0EAA0E;gBACxG,OAAO,GAAG,CAAC;YACb,CAAC,CAAC,CAAC;YACH,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,EAAE,CAAC;QAC/F,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC,CAAC,sDAAsD;QACjH,CAAC;IACH,CAAC;CACF"}

package/dist/seo/sources/dataforseo-adapter.d.ts

@@ -0,0 +1,46 @@
+import type { SeoEgressGuard } from "../egress.js";
+import type { SeoQuotaGovernor } from "../quota-governor.js";
+import type { HttpClient } from "../adapters/http.js";
+import type { SeoDataSource, SeoCapability, SearchAnalyticsQuery, SearchAnalyticsRow, UrlInspectionQuery, UrlInspectionRow, SerpQuery, SerpRow, KeywordQuery, KeywordRow, BacklinkQuery, BacklinkRow, AiVisibilityQuery, AiVisibilityRow, LinkGraphQuery, LinkGraphRow } from "../data-source.js";
+import type { DataOutcome } from "../types.js";
+/**
+ * Live DataForSEO `SeoDataSource`. Serves `serp` + `keywords` + `backlinks`;
+ * `search-analytics`/`url-inspection` are NOT DataForSEO capabilities
+ * (`{ kind: "disabled" }` unconditionally — GscAdapter serves those).
+ *
+ * bober: no OAuth/refresh flow here — the HTTP Basic credential is injected
+ *        fully-formed via `getBasicAuth`; add credential rotation only if a
+ *        credential store is wired in a later sprint.
+ */
+export declare class DataForSeoAdapter implements SeoDataSource {
+    private readonly egress;
+    private readonly governor;
+    private readonly http;
+    private readonly getBasicAuth;
+    constructor(egress: SeoEgressGuard, governor: SeoQuotaGovernor, http?: HttpClient, getBasicAuth?: () => Promise<string>);
+    capabilities(): SeoCapability[];
+    /**
+     * SERP query. ADR-5 preamble (egress gate, then quota gate) runs before
+     * any network work; USD cost is the fixed per-task price for `q.priority`
+     * (default `"standard"`) — booked in `admit()` (estimate) and `record()`
+     * (actual, identical since SERP is a fixed-price task, sc-9-3).
+     */
+    serp(q: SerpQuery): Promise<DataOutcome<SerpRow[]>>;
+    /**
+     * Keyword ideas query. Same ADR-5 preamble as `serp`; USD cost uses the
+     * documented `KEYWORDS_TASK_USD` placeholder (research §4 does not pin a
+     * keywords price — see the constant's `bober:` comment).
+     */
+    keywords(q: KeywordQuery): Promise<DataOutcome<KeywordRow[]>>;
+    /**
+     * Backlinks query. Same ADR-5 preamble; USD cost is `$0.02/req` plus
+     * `$0.00003/row` — `admit()` uses the worst-case `q.limit` estimate,
+     * `record()`/`provenance.costUsd` use the ACTUAL returned row count.
+     */
+    backlinks(q: BacklinkQuery): Promise<DataOutcome<BacklinkRow[]>>;
+    searchAnalytics(_q: SearchAnalyticsQuery): Promise<DataOutcome<SearchAnalyticsRow[]>>;
+    urlInspection(_q: UrlInspectionQuery): Promise<DataOutcome<UrlInspectionRow[]>>;
+    aiVisibility(_q: AiVisibilityQuery): Promise<DataOutcome<AiVisibilityRow[]>>;
+    linkGraph(_q: LinkGraphQuery): Promise<DataOutcome<LinkGraphRow[]>>;
+}
+//# sourceMappingURL=dataforseo-adapter.d.ts.map

package/dist/seo/sources/dataforseo-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataforseo-adapter.d.ts","sourceRoot":"","sources":["../../../src/seo/sources/dataforseo-adapter.ts"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAgB,MAAM,sBAAsB,CAAC;AAC3E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,SAAS,EACT,OAAO,EACP,YAAY,EACZ,UAAU,EACV,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,YAAY,EACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,aAAa,CAAC;AAgG/D;;;;;;;;GAQG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IAEnD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAGzB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAIrB,OAAO,CAAC,QAAQ,CAAC,YAAY;gBARZ,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,gBAAgB,EAG1B,IAAI,GAAE,UAA8B,EAIpC,YAAY,GAAE,MAAM,OAAO,CAAC,MAAM,CAKhD;IAGL,YAAY,IAAI,aAAa,EAAE;IAI/B;;;;;OAKG;IACG,IAAI,CAAC,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC;IAkDzD;;;;OAIG;IACG,QAAQ,CAAC,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC,CAAC;IAgDnE;;;;OAIG;IACG,SAAS,CAAC,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC;IAmDhE,eAAe,CAAC,EAAE,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAIrF,aAAa,CAAC,EAAE,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAM/E,YAAY,CAAC,EAAE,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,eAAe,EAAE,CAAC,CAAC;IAI5E,SAAS,CAAC,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,YAAY,EAAE,CAAC,CAAC;CAG1E"}