agent-bober 0.17.1 → 0.19.0

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

@@ -0,0 +1,64 @@
+/**
+ * GscAdapter — the FIRST live network `SeoDataSource` (spec-20260715-ultimate-seo-suite,
+ * Sprint 8). Serves `searchAnalytics` + `urlInspection` from the real Google
+ * Search Console API, behind the `"search-console"` egress axis.
+ *
+ * ADR-5 (the load-bearing invariant of this file): EVERY capability method
+ * that would open a socket begins with these two gates, IN ORDER, before any
+ * network work:
+ *   1. `this.egress.assertAllowed("search-console")` — throws when the axis
+ *      is off; caught immediately and converted to `abstain` WITHOUT opening
+ *      a socket (never hoisted into a caller/runner — see `src/seo/egress.ts`).
+ *   2. `this.governor.admit(req)` — synchronous, never throws, no side
+ *      effect; refused admission also aborts before any socket opens.
+ * Only after BOTH gates pass does the injected `HttpClient` make a request.
+ * Any HTTP/network/parse error (including 429/5xx) degrades to
+ * `{ kind: "abstain", reason }` — this method NEVER throws to the caller
+ * (mirrors `MedlineSource.fetchPassages`,
+ * `src/medical/retrieval/medline-source.ts:142-164`).
+ *
+ * The real global `fetch` is referenced NOWHERE in this file — the injected
+ * `HttpClient` (`../adapters/http.js`) is the sole transport, defaulting to
+ * `defaultHttpClient` (production) or a fixture/spy client (tests), so CI
+ * never opens a real socket.
+ */
+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 Google Search Console `SeoDataSource`. Serves `search-analytics` +
+ * `url-inspection`; `serp`/`keywords`/`backlinks` are NOT GSC capabilities
+ * (`{ kind: "disabled" }` unconditionally — DataForSEO serves those in
+ * Sprint 9).
+ *
+ * bober: no OAuth refresh-grant flow here (unlike `WhoopClient`) — the
+ *        access token is injected fully-formed via `getAccessToken`; add a
+ *        refresh flow only if/when a token store is wired in a later sprint.
+ */
+export declare class GscAdapter implements SeoDataSource {
+    private readonly egress;
+    private readonly governor;
+    private readonly http;
+    private readonly getAccessToken;
+    constructor(egress: SeoEgressGuard, governor: SeoQuotaGovernor, http?: HttpClient, getAccessToken?: () => Promise<string>);
+    capabilities(): SeoCapability[];
+    /**
+     * Search Analytics query. ADR-5 preamble (egress gate, then quota gate)
+     * runs before any network work; `rowLimit` is hard-capped at 25,000
+     * regardless of what the caller requests (sc-8-3).
+     */
+    searchAnalytics(q: SearchAnalyticsQuery): Promise<DataOutcome<SearchAnalyticsRow[]>>;
+    /**
+     * URL Inspection query. Same ADR-5 preamble as `searchAnalytics`; GSC
+     * inspects exactly one URL per call, so `estRows` is always 1.
+     */
+    urlInspection(q: UrlInspectionQuery): Promise<DataOutcome<UrlInspectionRow[]>>;
+    serp(_q: SerpQuery): Promise<DataOutcome<SerpRow[]>>;
+    keywords(_q: KeywordQuery): Promise<DataOutcome<KeywordRow[]>>;
+    backlinks(_q: BacklinkQuery): Promise<DataOutcome<BacklinkRow[]>>;
+    aiVisibility(_q: AiVisibilityQuery): Promise<DataOutcome<AiVisibilityRow[]>>;
+    linkGraph(_q: LinkGraphQuery): Promise<DataOutcome<LinkGraphRow[]>>;
+}
+//# sourceMappingURL=gsc-adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gsc-adapter.d.ts","sourceRoot":"","sources":["../../../src/seo/sources/gsc-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,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;AA4E/D;;;;;;;;;GASG;AACH,qBAAa,UAAW,YAAW,aAAa;IAE5C,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAGzB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAGrB,OAAO,CAAC,QAAQ,CAAC,cAAc;gBAPd,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,gBAAgB,EAG1B,IAAI,GAAE,UAA8B,EAGpC,cAAc,GAAE,MAAM,OAAO,CAAC,MAAM,CACE;IAGzD,YAAY,IAAI,aAAa,EAAE;IAI/B;;;;OAIG;IACG,eAAe,CACnB,CAAC,EAAE,oBAAoB,GACtB,OAAO,CAAC,WAAW,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAmD7C;;;OAGG;IACG,aAAa,CAAC,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAgD9E,IAAI,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC;IAIpD,QAAQ,CAAC,EAAE,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC,CAAC;IAI9D,SAAS,CAAC,EAAE,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC;IAMjE,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"}

package/dist/seo/sources/gsc-adapter.js

@@ -0,0 +1,221 @@
+import { defaultHttpClient } from "../adapters/http.js";
+// -- GSC endpoint constants (research S4) ----------------------------------
+const GSC_SEARCH_ANALYTICS_BASE = "https://www.googleapis.com/webmasters/v3/sites";
+const GSC_URL_INSPECTION_URL = "https://searchconsole.googleapis.com/v1/urlInspection/index:inspect";
+/** GSC Search Analytics hard per-request cap — never send a larger rowLimit. */
+const GSC_ROW_LIMIT_CAP = 25_000;
+// -- Response parsers (pure, total — [] / {} on any shape mismatch) --------
+/**
+ * Parse a GSC `searchAnalytics/query` response body into typed rows.
+ * `dimensions` gives the order of the `keys[]` array in each response row
+ * (GSC echoes dimensions positionally, no field names). Any structural
+ * mismatch degrades to `[]` (fail-closed read, never throws).
+ */
+function parseSearchAnalytics(raw, dimensions) {
+    if (!raw || typeof raw !== "object")
+        return [];
+    const body = raw;
+    const rawRows = body["rows"];
+    if (!Array.isArray(rawRows))
+        return [];
+    const rows = [];
+    for (const item of rawRows) {
+        if (!item || typeof item !== "object")
+            continue;
+        const r = item;
+        const keys = Array.isArray(r["keys"]) ? r["keys"] : [];
+        const row = {
+            clicks: typeof r["clicks"] === "number" ? r["clicks"] : 0,
+            impressions: typeof r["impressions"] === "number" ? r["impressions"] : 0,
+            ctr: typeof r["ctr"] === "number" ? r["ctr"] : 0,
+            position: typeof r["position"] === "number" ? r["position"] : 0,
+        };
+        dimensions.forEach((dim, idx) => {
+            const value = keys[idx];
+            if (typeof value !== "string")
+                return;
+            row[dim] = value;
+        });
+        rows.push(row);
+    }
+    return rows;
+}
+/**
+ * Parse a GSC `urlInspection/index:inspect` response body into a single
+ * `UrlInspectionRow` (GSC inspects one URL per call). `[]` when the
+ * response shape is unrecognized (fail-closed read, never throws).
+ */
+function parseUrlInspection(raw, url) {
+    if (!raw || typeof raw !== "object")
+        return [];
+    const body = raw;
+    const inspectionResult = body["inspectionResult"];
+    if (!inspectionResult || typeof inspectionResult !== "object")
+        return [];
+    const indexStatusResult = inspectionResult["indexStatusResult"];
+    if (!indexStatusResult || typeof indexStatusResult !== "object")
+        return [];
+    const s = indexStatusResult;
+    const row = { url };
+    if (typeof s["coverageState"] === "string")
+        row.coverageState = s["coverageState"];
+    if (typeof s["indexingState"] === "string")
+        row.indexingState = s["indexingState"];
+    if (typeof s["lastCrawlTime"] === "string")
+        row.lastCrawlTime = s["lastCrawlTime"];
+    if (typeof s["robotsTxtState"] === "string")
+        row.robotsTxtState = s["robotsTxtState"];
+    if (typeof s["pageFetchState"] === "string")
+        row.pageFetchState = s["pageFetchState"];
+    return [row];
+}
+// -- GscAdapter --------------------------------------------------------------
+/**
+ * Live Google Search Console `SeoDataSource`. Serves `search-analytics` +
+ * `url-inspection`; `serp`/`keywords`/`backlinks` are NOT GSC capabilities
+ * (`{ kind: "disabled" }` unconditionally — DataForSEO serves those in
+ * Sprint 9).
+ *
+ * bober: no OAuth refresh-grant flow here (unlike `WhoopClient`) — the
+ *        access token is injected fully-formed via `getAccessToken`; add a
+ *        refresh flow only if/when a token store is wired in a later sprint.
+ */
+export class GscAdapter {
+    egress;
+    governor;
+    http;
+    getAccessToken;
+    constructor(egress, governor, 
+    // Injectable transport — default = the ONE global-fetch wrapper
+    // (`../adapters/http.js`). Tests inject a fake `HttpClient`.
+    http = defaultHttpClient, 
+    // OAuth bearer token provider — injected, NEVER hardcoded. Tests stub
+    // it (`async () => "test-token"`); production defaults to the env var.
+    getAccessToken = () => Promise.resolve(process.env["GSC_OAUTH_TOKEN"] ?? "")) {
+        this.egress = egress;
+        this.governor = governor;
+        this.http = http;
+        this.getAccessToken = getAccessToken;
+    }
+    capabilities() {
+        return ["search-analytics", "url-inspection"];
+    }
+    /**
+     * Search Analytics query. ADR-5 preamble (egress gate, then quota gate)
+     * runs before any network work; `rowLimit` is hard-capped at 25,000
+     * regardless of what the caller requests (sc-8-3).
+     */
+    async searchAnalytics(q) {
+        // -- STATEMENT 1: egress gate (ADR-5) --
+        try {
+            this.egress.assertAllowed("search-console");
+        }
+        catch {
+            return { kind: "abstain", reason: "egress-search-console-disabled" };
+        }
+        // -- STATEMENT 2: quota gate (ADR-5); synchronous, never throws --
+        const rowLimit = Math.min(q.rowLimit ?? GSC_ROW_LIMIT_CAP, GSC_ROW_LIMIT_CAP);
+        const admitReq = {
+            source: "gsc",
+            capability: "search-analytics",
+            scope: { siteUrl: q.siteUrl }, // per-site (+ per-user, when available) scope threaded into the governor
+            estRows: rowLimit, // worst-case pre-emption
+            estCostUsd: 0, // GSC Search Analytics is free
+        };
+        const decision = this.governor.admit(admitReq);
+        if (!decision.admit) {
+            return { kind: "abstain", reason: decision.reason };
+        }
+        // -- Only now may a socket open. --
+        try {
+            const token = await this.getAccessToken();
+            const url = `${GSC_SEARCH_ANALYTICS_BASE}/${encodeURIComponent(q.siteUrl)}/searchAnalytics/query`;
+            const res = await this.http.request(url, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    startDate: q.startDate,
+                    endDate: q.endDate,
+                    dimensions: q.dimensions,
+                    rowLimit,
+                }),
+            });
+            if (!res.ok) {
+                return { kind: "abstain", reason: `gsc-http-${res.status}` }; // 429/5xx -> abstain, NEVER throw
+            }
+            const rows = parseSearchAnalytics(await res.json(), q.dimensions);
+            // Book ACTUAL rows served (not the worst-case estimate used for admit()).
+            await this.governor.record({ ...admitReq, estRows: rows.length }, 0);
+            const provenance = { source: "gsc", retrievedAt: new Date().toISOString() };
+            return { kind: "data", rows, provenance };
+        }
+        catch {
+            return { kind: "abstain", reason: "source-error" }; // network/parse error -> abstain, NEVER throw
+        }
+    }
+    /**
+     * URL Inspection query. Same ADR-5 preamble as `searchAnalytics`; GSC
+     * inspects exactly one URL per call, so `estRows` is always 1.
+     */
+    async urlInspection(q) {
+        // -- STATEMENT 1: egress gate (ADR-5) --
+        try {
+            this.egress.assertAllowed("search-console");
+        }
+        catch {
+            return { kind: "abstain", reason: "egress-search-console-disabled" };
+        }
+        // -- STATEMENT 2: quota gate (ADR-5); synchronous, never throws --
+        const admitReq = {
+            source: "gsc",
+            capability: "url-inspection",
+            scope: { siteUrl: q.siteUrl },
+            estRows: 1,
+            estCostUsd: 0,
+        };
+        const decision = this.governor.admit(admitReq);
+        if (!decision.admit) {
+            return { kind: "abstain", reason: decision.reason };
+        }
+        // -- Only now may a socket open. --
+        try {
+            const token = await this.getAccessToken();
+            const res = await this.http.request(GSC_URL_INSPECTION_URL, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+                body: JSON.stringify({ inspectionUrl: q.inspectionUrl, siteUrl: q.siteUrl }),
+            });
+            if (!res.ok) {
+                return { kind: "abstain", reason: `gsc-http-${res.status}` }; // 429/5xx -> abstain, NEVER throw
+            }
+            const rows = parseUrlInspection(await res.json(), q.inspectionUrl);
+            if (rows.length === 0) {
+                return { kind: "abstain", reason: "unrecognized-response-shape" };
+            }
+            await this.governor.record(admitReq, 0);
+            const provenance = { source: "gsc", retrievedAt: new Date().toISOString() };
+            return { kind: "data", rows, provenance };
+        }
+        catch {
+            return { kind: "abstain", reason: "source-error" }; // network/parse error -> abstain, NEVER throw
+        }
+    }
+    // -- Capabilities GSC does not serve; DataForSEO covers these (Sprint 9) --
+    async serp(_q) {
+        return { kind: "disabled" };
+    }
+    async keywords(_q) {
+        return { kind: "disabled" };
+    }
+    async backlinks(_q) {
+        return { kind: "disabled" };
+    }
+    // -- GSC does not serve ai-visibility/link-graph either (spec-20260717-seo-improver-builder, Sprint 1) --
+    async aiVisibility(_q) {
+        return { kind: "disabled" };
+    }
+    async linkGraph(_q) {
+        return { kind: "disabled" };
+    }
+}
+//# sourceMappingURL=gsc-adapter.js.map

package/dist/seo/sources/gsc-adapter.js.map

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

package/dist/seo/sources/local-export.d.ts

@@ -0,0 +1,53 @@
+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";
+/**
+ * Pure, total CSV reader. First non-empty line is the header; every
+ * subsequent non-empty line becomes one record keyed by that header.
+ * Handles quoted fields (including embedded commas and escaped `""`),
+ * `\r\n`/`\n` line endings, and a trailing blank line. Header-only input
+ * (or empty input) returns `[]`. NEVER throws (same spirit as
+ * `SeoPlaybookParser.parse`, `../parser.js:151-169`).
+ */
+export declare function parseCsv(text: string): Array<Record<string, string>>;
+/**
+ * Offline `SeoDataSource` backed by `.bober/seo/imports/` (or any directory
+ * passed to the constructor — tests inject an absolute fixture path).
+ *
+ * `capabilities()` is synchronous but presence detection requires an async
+ * `readdir`, so the present-file map is memoised in `load()` (mirrors
+ * `SeoPlaybookIndex.load()`, `../playbook-index.js:43-67`). Every
+ * capability method also calls `load()` itself if it hasn't run yet, so a
+ * method invoked before an explicit `load()` still resolves correctly.
+ */
+export declare class LocalExportSource implements SeoDataSource {
+    private readonly exportDir;
+    private files;
+    constructor(exportDir?: string);
+    /**
+     * Scan `exportDir` once for `<capability>.csv`/`.json` files and cache
+     * which capabilities have a present file. Never throws: a missing
+     * directory degrades to an empty capability set rather than rejecting.
+     */
+    load(): Promise<SeoCapability[]>;
+    /** The capabilities this source can currently serve, or `[]` before `load()` has run. */
+    capabilities(): SeoCapability[];
+    searchAnalytics(_q: SearchAnalyticsQuery): Promise<DataOutcome<SearchAnalyticsRow[]>>;
+    urlInspection(_q: UrlInspectionQuery): Promise<DataOutcome<UrlInspectionRow[]>>;
+    serp(_q: SerpQuery): Promise<DataOutcome<SerpRow[]>>;
+    keywords(_q: KeywordQuery): Promise<DataOutcome<KeywordRow[]>>;
+    backlinks(_q: BacklinkQuery): Promise<DataOutcome<BacklinkRow[]>>;
+    aiVisibility(_q: AiVisibilityQuery): Promise<DataOutcome<AiVisibilityRow[]>>;
+    linkGraph(_q: LinkGraphQuery): Promise<DataOutcome<LinkGraphRow[]>>;
+    /**
+     * Shared read path for every capability method.
+     *
+     * Order: ensure `load()` has run -> absent file => `disabled` -> read +
+     * parse (CSV or JSON) -> zero rows => `abstain{empty-export}` -> `stat`
+     * for `mtimeMs` -> `data` + `provenance{source:"local-export",
+     * retrievedAt, path, mtimeMs}` (sc-6-4). NEVER throws out of this
+     * method — any fs/parse error maps to `abstain{source-error}`, mirroring
+     * `MedlineSource.fetchPassages` (`../../medical/retrieval/medline-source.js:142-164`).
+     */
+    private readCapability;
+}
+//# sourceMappingURL=local-export.d.ts.map

package/dist/seo/sources/local-export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-export.d.ts","sourceRoot":"","sources":["../../../src/seo/sources/local-export.ts"],"names":[],"mappings":"AAiBA,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;AAgF/D;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAgBpE;AAuGD;;;;;;;;;GASG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IAGzC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAFtC,OAAO,CAAC,KAAK,CAA8C;gBAE9B,SAAS,GAAE,MAA2B;IAEnE;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAyBtC,yFAAyF;IACzF,YAAY,IAAI,aAAa,EAAE;IAIzB,eAAe,CACnB,EAAE,EAAE,oBAAoB,GACvB,OAAO,CAAC,WAAW,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAIvC,aAAa,CAAC,EAAE,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAI/E,IAAI,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC;IAIpD,QAAQ,CAAC,EAAE,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC,CAAC;IAI9D,SAAS,CAAC,EAAE,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC;IAIjE,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;IAIzE;;;;;;;;;OASG;YACW,cAAc;CAwC7B"}

package/dist/seo/sources/local-export.js

@@ -0,0 +1,307 @@
+/**
+ * LocalExportSource — offline `SeoDataSource` (spec-20260715-ultimate-seo-suite,
+ * Sprint 6). Parses crawl output + GSC/SERP exports dropped under
+ * `.bober/seo/imports/` (one file per capability, `<capability>.csv` or
+ * `<capability>.json` — see the briefing's file-convention table).
+ *
+ * Blends the never-throws-per-method discipline of
+ * `src/medical/retrieval/medline-source.ts` with the async-fs + memoised
+ * `load()` pattern of `../playbook-index.js`. Unlike `MedlineSource`, this
+ * source takes NO `EgressGuard` and NO transport — it is offline by
+ * construction; "disabled" here means *no local file for this capability*,
+ * not *axis off*. Zero network imports: reads local files only.
+ */
+import { readFile, readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { readJson } from "../../utils/fs.js";
+/** Relative to cwd; tests pass an absolute fixture directory instead. */
+const DEFAULT_EXPORT_DIR = ".bober/seo/imports";
+const CAPABILITIES = [
+    "search-analytics",
+    "url-inspection",
+    "serp",
+    "keywords",
+    "backlinks",
+    "ai-visibility",
+    "link-graph",
+];
+/** `<capability>` file basename — see the briefing's import-convention table. */
+const FILE_BASENAME = {
+    "search-analytics": "search-analytics",
+    "url-inspection": "url-inspection",
+    serp: "serp",
+    keywords: "keywords",
+    backlinks: "backlinks",
+    "ai-visibility": "ai-visibility",
+    "link-graph": "link-graph",
+};
+// -- Hand-rolled CSV parser (no dependency — no CSV/tabular parser exists
+//    anywhere in the repo; see the briefing §5 recommendation) -----------
+/** Split one CSV record line into fields, honoring quotes/escaped `""`. */
+function parseCsvLine(line) {
+    const fields = [];
+    let cur = "";
+    let inQuotes = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (inQuotes) {
+            if (ch === '"') {
+                if (line[i + 1] === '"') {
+                    cur += '"';
+                    i++;
+                }
+                else {
+                    inQuotes = false;
+                }
+            }
+            else {
+                cur += ch;
+            }
+        }
+        else if (ch === '"') {
+            inQuotes = true;
+        }
+        else if (ch === ",") {
+            fields.push(cur);
+            cur = "";
+        }
+        else {
+            cur += ch;
+        }
+    }
+    fields.push(cur);
+    return fields;
+}
+/**
+ * Pure, total CSV reader. First non-empty line is the header; every
+ * subsequent non-empty line becomes one record keyed by that header.
+ * Handles quoted fields (including embedded commas and escaped `""`),
+ * `\r\n`/`\n` line endings, and a trailing blank line. Header-only input
+ * (or empty input) returns `[]`. NEVER throws (same spirit as
+ * `SeoPlaybookParser.parse`, `../parser.js:151-169`).
+ */
+export function parseCsv(text) {
+    if (typeof text !== "string")
+        return [];
+    const lines = text.split(/\r\n|\n/).filter((line) => line.length > 0);
+    if (lines.length === 0)
+        return [];
+    const header = parseCsvLine(lines[0]);
+    const rows = [];
+    for (const line of lines.slice(1)) {
+        const values = parseCsvLine(line);
+        const row = {};
+        header.forEach((key, idx) => {
+            row[key] = values[idx] ?? "";
+        });
+        rows.push(row);
+    }
+    return rows;
+}
+// -- Numeric coercion helpers (CSV/JSON values arrive as strings; guard NaN) --
+function toNumber(value) {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : 0;
+}
+function toOptionalNumber(value) {
+    if (value === undefined || value === "")
+        return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+}
+function toOptionalString(value) {
+    return value === undefined || value === "" ? undefined : value;
+}
+function toOptionalBoolean(value) {
+    if (value === undefined || value === "")
+        return undefined;
+    return value === "true" || value === "1";
+}
+// -- Per-capability row mappers (record<string,string> -> typed Row; keys
+//    MUST match the CSV header / JSON keys 1:1, see data-source.ts) ------
+function mapSearchAnalyticsRow(r) {
+    return {
+        query: toOptionalString(r.query),
+        page: toOptionalString(r.page),
+        country: toOptionalString(r.country),
+        device: toOptionalString(r.device),
+        clicks: toNumber(r.clicks),
+        impressions: toNumber(r.impressions),
+        ctr: toNumber(r.ctr),
+        position: toNumber(r.position),
+    };
+}
+function mapUrlInspectionRow(r) {
+    return {
+        url: r.url ?? "",
+        coverageState: toOptionalString(r.coverageState),
+        indexingState: toOptionalString(r.indexingState),
+        lastCrawlTime: toOptionalString(r.lastCrawlTime),
+        robotsTxtState: toOptionalString(r.robotsTxtState),
+        pageFetchState: toOptionalString(r.pageFetchState),
+    };
+}
+function mapSerpRow(r) {
+    return {
+        keyword: r.keyword ?? "",
+        position: toNumber(r.position),
+        url: r.url ?? "",
+        title: toOptionalString(r.title),
+        location: toOptionalString(r.location),
+    };
+}
+function mapKeywordRow(r) {
+    return {
+        keyword: r.keyword ?? "",
+        searchVolume: toOptionalNumber(r.searchVolume),
+        cpc: toOptionalNumber(r.cpc),
+        competition: toOptionalNumber(r.competition),
+        location: toOptionalString(r.location),
+    };
+}
+function mapBacklinkRow(r) {
+    return {
+        sourceUrl: r.sourceUrl ?? "",
+        targetUrl: r.targetUrl ?? "",
+        anchor: toOptionalString(r.anchor),
+        dofollow: toOptionalBoolean(r.dofollow),
+    };
+}
+function mapAiVisibilityRow(r) {
+    return {
+        prompt: r.prompt ?? "",
+        provider: r.provider ?? "",
+        mentioned: toOptionalBoolean(r.mentioned) ?? false,
+        rank: toOptionalNumber(r.rank),
+        citationPresent: toOptionalBoolean(r.citationPresent) ?? false,
+        // sourceUrls is a single CSV cell, space-delimited (URLs never contain spaces).
+        sourceUrls: (r.sourceUrls ?? "").split(/\s+/).filter(Boolean),
+    };
+}
+function mapLinkGraphRow(r) {
+    return {
+        fromUrl: r.fromUrl ?? "",
+        toUrl: r.toUrl ?? "",
+        anchor: toOptionalString(r.anchor),
+        internal: toOptionalBoolean(r.internal) ?? false,
+    };
+}
+// -- LocalExportSource ------------------------------------------------------
+/**
+ * Offline `SeoDataSource` backed by `.bober/seo/imports/` (or any directory
+ * passed to the constructor — tests inject an absolute fixture path).
+ *
+ * `capabilities()` is synchronous but presence detection requires an async
+ * `readdir`, so the present-file map is memoised in `load()` (mirrors
+ * `SeoPlaybookIndex.load()`, `../playbook-index.js:43-67`). Every
+ * capability method also calls `load()` itself if it hasn't run yet, so a
+ * method invoked before an explicit `load()` still resolves correctly.
+ */
+export class LocalExportSource {
+    exportDir;
+    files = null;
+    constructor(exportDir = DEFAULT_EXPORT_DIR) {
+        this.exportDir = exportDir;
+    }
+    /**
+     * Scan `exportDir` once for `<capability>.csv`/`.json` files and cache
+     * which capabilities have a present file. Never throws: a missing
+     * directory degrades to an empty capability set rather than rejecting.
+     */
+    async load() {
+        if (this.files)
+            return [...this.files.keys()];
+        const found = new Map();
+        let entries;
+        try {
+            entries = await readdir(this.exportDir);
+        }
+        catch {
+            this.files = found;
+            return [];
+        }
+        for (const cap of CAPABILITIES) {
+            const base = FILE_BASENAME[cap];
+            if (entries.includes(`${base}.csv`)) {
+                found.set(cap, { path: join(this.exportDir, `${base}.csv`), ext: "csv" });
+            }
+            else if (entries.includes(`${base}.json`)) {
+                found.set(cap, { path: join(this.exportDir, `${base}.json`), ext: "json" });
+            }
+        }
+        this.files = found;
+        return [...found.keys()];
+    }
+    /** The capabilities this source can currently serve, or `[]` before `load()` has run. */
+    capabilities() {
+        return [...(this.files?.keys() ?? [])];
+    }
+    async searchAnalytics(_q) {
+        return this.readCapability("search-analytics", mapSearchAnalyticsRow);
+    }
+    async urlInspection(_q) {
+        return this.readCapability("url-inspection", mapUrlInspectionRow);
+    }
+    async serp(_q) {
+        return this.readCapability("serp", mapSerpRow);
+    }
+    async keywords(_q) {
+        return this.readCapability("keywords", mapKeywordRow);
+    }
+    async backlinks(_q) {
+        return this.readCapability("backlinks", mapBacklinkRow);
+    }
+    async aiVisibility(_q) {
+        return this.readCapability("ai-visibility", mapAiVisibilityRow);
+    }
+    async linkGraph(_q) {
+        return this.readCapability("link-graph", mapLinkGraphRow);
+    }
+    /**
+     * Shared read path for every capability method.
+     *
+     * Order: ensure `load()` has run -> absent file => `disabled` -> read +
+     * parse (CSV or JSON) -> zero rows => `abstain{empty-export}` -> `stat`
+     * for `mtimeMs` -> `data` + `provenance{source:"local-export",
+     * retrievedAt, path, mtimeMs}` (sc-6-4). NEVER throws out of this
+     * method — any fs/parse error maps to `abstain{source-error}`, mirroring
+     * `MedlineSource.fetchPassages` (`../../medical/retrieval/medline-source.js:142-164`).
+     */
+    async readCapability(cap, map) {
+        try {
+            if (!this.files) {
+                await this.load();
+            }
+            const entry = this.files?.get(cap);
+            if (!entry) {
+                return { kind: "disabled" };
+            }
+            let records;
+            if (entry.ext === "csv") {
+                const text = await readFile(entry.path, "utf-8");
+                records = parseCsv(text);
+            }
+            else {
+                const parsed = await readJson(entry.path);
+                records = Array.isArray(parsed) ? parsed : [];
+            }
+            if (records.length === 0) {
+                return { kind: "abstain", reason: "empty-export" };
+            }
+            const rows = records.map(map);
+            const fileStat = await stat(entry.path);
+            const provenance = {
+                source: "local-export",
+                retrievedAt: new Date().toISOString(),
+                path: entry.path,
+                mtimeMs: fileStat.mtimeMs,
+            };
+            return { kind: "data", rows, provenance };
+        }
+        catch {
+            // Includes: unreadable file, invalid JSON, stat failure. NEVER fail-open.
+            return { kind: "abstain", reason: "source-error" };
+        }
+    }
+}
+//# sourceMappingURL=local-export.js.map