agent-bober 0.17.1 → 0.19.0

package/dist/seo/quota-ledger.js

@@ -0,0 +1,95 @@
+/**
+ * Persisted quota ledger — pure persistence + keying helpers, no quota
+ * decision logic (that lives in `quota-governor.ts`).
+ *
+ * Layout: `.bober/seo/quota-ledger.json`.
+ *
+ * Every write is atomic via temp-file + rename (mirrors
+ * `src/incident/timeline.ts:86-92` atomicWriteJson / `src/state/run-state.ts:41-52`).
+ *
+ * Concurrent read-modify-write calls to the SAME resolved path are serialized
+ * via a module-scoped per-path promise-chain mutex (mirrors
+ * `src/telemetry/emit.ts:57,85-86`) so two `SeoQuotaGovernor` instances
+ * sharing a ledger path never lose an update.
+ *
+ * Fail-closed discrimination: a MISSING ledger (ENOENT) is a fresh, empty
+ * ledger (offline / first-run => allow). An EXISTING-but-unparseable or
+ * unreadable ledger is the `"corrupt"` sentinel (fail-closed => at-ceiling).
+ * This is deliberately NOT the blanket catch used by `readRunState`
+ * (`src/state/run-state.ts:61-68`), which collapses both cases to `null`.
+ *
+ * Sprint 7 — spec-20260715-ultimate-seo-suite.
+ */
+import { readFile, writeFile, rename } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { dirname, resolve } from "node:path";
+import { ensureDir } from "../utils/fs.js";
+// ── Keying helpers ───────────────────────────────────────────────────
+/** `YYYY-MM-DD` date key; daily counters reset on this boundary. */
+export function dateKey(now) {
+    return now.toISOString().slice(0, 10);
+}
+/** Composite per-site/per-user scope key (`${siteUrl}|${userId}`). */
+export function scopeKey(scope) {
+    return `${scope.siteUrl ?? ""}|${scope.userId ?? ""}`;
+}
+// ── Read ─────────────────────────────────────────────────────────────
+/**
+ * Read the ledger from disk.
+ *
+ * - Missing file (ENOENT) => fresh empty ledger `{}` (offline/first-run, NOT corrupt).
+ * - Existing-but-unreadable (permissions, etc.) or unparseable JSON => `"corrupt"`
+ *   sentinel so the caller can fail closed (treat spend as at-ceiling).
+ */
+export async function readLedger(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return {};
+        return "corrupt";
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return "corrupt";
+    }
+}
+// ── Write ────────────────────────────────────────────────────────────
+/**
+ * Atomically overwrite the ledger: write a unique temp file, then rename
+ * (POSIX-atomic) so a crash mid-write can never leave a torn/corrupt file.
+ */
+export async function writeLedgerAtomic(path, ledger) {
+    await ensureDir(dirname(path));
+    const tmp = `${path}.${process.pid}.${Date.now()}.${randomBytes(4).toString("hex")}.tmp`;
+    await writeFile(tmp, JSON.stringify(ledger, null, 2) + "\n", {
+        encoding: "utf-8",
+        mode: 0o600,
+    });
+    await rename(tmp, path);
+}
+// ── Per-path mutex ───────────────────────────────────────────────────
+/**
+ * Module-scoped chain of promises, one per resolved ledger path. ALL
+ * `SeoQuotaGovernor` instances that share a ledger path serialize their
+ * read-modify-write through this SAME chain, which is what guarantees
+ * `record()` never loses a concurrent update (sc-7-3).
+ */
+const ledgerChains = new Map();
+/**
+ * Run `fn` exclusively with respect to any other `withLedgerLock` call on
+ * the same resolved path. Chains onto the previous run regardless of
+ * whether it resolved or rejected, so one failure never wedges the chain.
+ */
+export async function withLedgerLock(path, fn) {
+    const key = resolve(path);
+    const prev = ledgerChains.get(key) ?? Promise.resolve();
+    const run = prev.then(fn, fn);
+    ledgerChains.set(key, run.then(() => { }, () => { }));
+    return run;
+}
+//# sourceMappingURL=quota-ledger.js.map

package/dist/seo/quota-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota-ledger.js","sourceRoot":"","sources":["../../src/seo/quota-ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG3C,wEAAwE;AAExE,oEAAoE;AACpE,MAAM,UAAU,OAAO,CAAC,GAAS;IAC/B,OAAO,GAAG,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACxC,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,QAAQ,CAAC,KAA4C;IACnE,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,EAAE,IAAI,KAAK,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;AACxD,CAAC;AAED,wEAAwE;AAExE;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY;IAC3C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAAyB,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QAC5D,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAmB,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,wEAAwE;AAExE;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAAY,EAAE,MAAsB;IAC1E,MAAM,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/B,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC;IACzF,MAAM,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE;QAC3D,QAAQ,EAAE,OAAO;QACjB,IAAI,EAAE,KAAK;KACZ,CAAC,CAAC;IACH,MAAM,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,wEAAwE;AAExE;;;;;GAKG;AACH,MAAM,YAAY,GAAG,IAAI,GAAG,EAAyB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAI,IAAY,EAAE,EAAoB;IACxE,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IACxD,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IAC9B,YAAY,CAAC,GAAG,CACd,GAAG,EACH,GAAG,CAAC,IAAI,CACN,GAAG,EAAE,GAAE,CAAC,EACR,GAAG,EAAE,GAAE,CAAC,CACT,CACF,CAAC;IACF,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/seo/report-store.d.ts

@@ -0,0 +1,30 @@
+import type { SeoReport, SeoWorkflow } from "./types.js";
+/**
+ * Derive a write-once, collision-free `reportId` from `now` + `workflow` +
+ * a short hash of `target`. PURE — never reads the clock itself (`now` is
+ * caller-injected). `now` is sanitized into a filename-safe slug (mirrors
+ * `buildAuditDescriptor`'s slug, `security-audit.ts:78`); `target` is
+ * hashed (not embedded raw) so an arbitrary target string can never break
+ * the id shape or collide across two different targets.
+ */
+export declare function deriveReportId(now: string, workflow: SeoWorkflow, target: string): string;
+export declare class SeoReportStore {
+    /**
+     * Write `report` atomically (temp file + POSIX-atomic rename) under
+     * `.bober/seo/reports/`. Overwrites any existing report with the same
+     * `reportId`. Throws on an unrecoverable fs failure — callers (the
+     * runner) are expected to catch and fail closed.
+     */
+    save(projectRoot: string, report: SeoReport): Promise<void>;
+    /**
+     * Read a persisted `SeoReport` by id. Returns `null` on a missing file —
+     * NEVER throws (mirrors `readSecurityAudit`, `security-audit-state.ts:51-55`).
+     */
+    read(projectRoot: string, reportId: string): Promise<SeoReport | null>;
+    /**
+     * List all persisted report ids, sorted by filename. Returns `[]` if the
+     * reports directory does not exist — never throws.
+     */
+    list(projectRoot: string): Promise<string[]>;
+}
+//# sourceMappingURL=report-store.d.ts.map

package/dist/seo/report-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-store.d.ts","sourceRoot":"","sources":["../../src/seo/report-store.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAmBzD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAIzF;AAID,qBAAa,cAAc;IACzB;;;;;OAKG;IACG,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IASjE;;;OAGG;IACG,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAU5E;;;OAGG;IACG,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAanD"}

package/dist/seo/report-store.js

@@ -0,0 +1,94 @@
+/**
+ * SeoReportStore — persists `SeoReport` JSON under `.bober/seo/reports/`
+ * (spec-20260715-ultimate-seo-suite, Sprint 11).
+ *
+ * Mirrors `saveSecurityAudit`/`readSecurityAudit`
+ * (`src/state/security-audit-state.ts:29-56`) for the path/dir/null-on-missing
+ * shape, but writes via the ATOMIC temp-file + rename pattern of
+ * `writeLedgerAtomic` (`src/seo/quota-ledger.ts:73-81`) — the architecture
+ * (lines 337/406/483) explicitly requires atomic writes for the report
+ * artifact, which `saveSecurityAudit`'s plain `writeFile` does not provide.
+ *
+ * `reportId` is a PURE function of (now, workflow, target) — see
+ * `deriveReportId` — so callers never need to invent an id themselves, and
+ * two runs of the same workflow/target in the same second (extremely
+ * unlikely given ISO-millisecond `now`) still diverge via the target hash.
+ */
+import { readFile, writeFile, readdir, rename } from "node:fs/promises";
+import { randomBytes, createHash } from "node:crypto";
+import { join } from "node:path";
+import { ensureDir } from "../utils/fs.js";
+// ── Paths ────────────────────────────────────────────────────────────
+const SEO_REPORTS_DIR = ".bober/seo/reports";
+const REPORT_SUFFIX = "-seo-report.json";
+function reportsDir(projectRoot) {
+    return join(projectRoot, SEO_REPORTS_DIR);
+}
+/** fs-safe filename — mirrors `security-audit-state.ts:17`'s sanitization. */
+function reportPath(projectRoot, reportId) {
+    const safeId = reportId.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return join(reportsDir(projectRoot), `${safeId}${REPORT_SUFFIX}`);
+}
+// ── Id derivation ────────────────────────────────────────────────────
+/**
+ * Derive a write-once, collision-free `reportId` from `now` + `workflow` +
+ * a short hash of `target`. PURE — never reads the clock itself (`now` is
+ * caller-injected). `now` is sanitized into a filename-safe slug (mirrors
+ * `buildAuditDescriptor`'s slug, `security-audit.ts:78`); `target` is
+ * hashed (not embedded raw) so an arbitrary target string can never break
+ * the id shape or collide across two different targets.
+ */
+export function deriveReportId(now, workflow, target) {
+    const slug = now.replace(/[^A-Za-z0-9]/g, "-");
+    const targetHash = createHash("sha256").update(target).digest("hex").slice(0, 8);
+    return `seo-${workflow}-${slug}-${targetHash}`;
+}
+// ── Store ────────────────────────────────────────────────────────────
+export class SeoReportStore {
+    /**
+     * Write `report` atomically (temp file + POSIX-atomic rename) under
+     * `.bober/seo/reports/`. Overwrites any existing report with the same
+     * `reportId`. Throws on an unrecoverable fs failure — callers (the
+     * runner) are expected to catch and fail closed.
+     */
+    async save(projectRoot, report) {
+        await ensureDir(reportsDir(projectRoot));
+        const path = reportPath(projectRoot, report.reportId);
+        // Uniqueness token for the temp filename only — NOT a report timestamp.
+        const tmp = `${path}.${process.pid}.${Date.now()}.${randomBytes(4).toString("hex")}.tmp`;
+        await writeFile(tmp, JSON.stringify(report, null, 2) + "\n", { encoding: "utf-8" });
+        await rename(tmp, path);
+    }
+    /**
+     * Read a persisted `SeoReport` by id. Returns `null` on a missing file —
+     * NEVER throws (mirrors `readSecurityAudit`, `security-audit-state.ts:51-55`).
+     */
+    async read(projectRoot, reportId) {
+        const path = reportPath(projectRoot, reportId);
+        try {
+            const raw = await readFile(path, "utf-8");
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * List all persisted report ids, sorted by filename. Returns `[]` if the
+     * reports directory does not exist — never throws.
+     */
+    async list(projectRoot) {
+        let entries;
+        try {
+            entries = await readdir(reportsDir(projectRoot));
+        }
+        catch {
+            return [];
+        }
+        return entries
+            .filter((f) => f.endsWith(REPORT_SUFFIX))
+            .sort()
+            .map((f) => f.slice(0, -REPORT_SUFFIX.length));
+    }
+}
+//# sourceMappingURL=report-store.js.map

package/dist/seo/report-store.js.map

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

package/dist/seo/retriever.d.ts

@@ -0,0 +1,34 @@
+/**
+ * SeoPlaybookRetriever — ranks + never-empty renders SeoSignature[] for a
+ * given workflow (spec-20260715-ultimate-seo-suite, Sprint 2; folds the
+ * security template's selector.ts (rank + generic-floor dedup) and
+ * resolver.ts (never-empty promptFragment) into one file, since the
+ * contract lists only this as a single code file).
+ *
+ * Method name is `retrieve` (sc-2-4) — NOT `resolve` (the architecture API
+ * table's name); the binding success criterion and evaluator assert
+ * `retrieve({workflow,target,vertical})`.
+ */
+import type { SeoSignature, SeoWorkflow } from "./types.js";
+import type { SeoPlaybookIndex } from "./playbook-index.js";
+export interface SeoRetrieveInput {
+    workflow: SeoWorkflow;
+    target?: string;
+    vertical?: string;
+    topK?: number;
+}
+export interface SeoRetrieveResult {
+    promptFragment: string;
+    signatures: SeoSignature[];
+}
+export declare class SeoPlaybookRetriever {
+    private readonly index;
+    constructor(index: SeoPlaybookIndex);
+    /**
+     * Never throws: loads (idempotent) the index, ranks the workflow's
+     * matching signatures, and always includes the generic floor deduped by
+     * `playbookId`. `promptFragment` is never empty.
+     */
+    retrieve(input: SeoRetrieveInput): Promise<SeoRetrieveResult>;
+}
+//# sourceMappingURL=retriever.d.ts.map

package/dist/seo/retriever.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retriever.d.ts","sourceRoot":"","sources":["../../src/seo/retriever.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,WAAW,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,YAAY,EAAE,CAAC;CAC5B;AAgGD,qBAAa,oBAAoB;IACnB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,gBAAgB;IAEpD;;;;OAIG;IACG,QAAQ,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAiBpE"}

package/dist/seo/retriever.js

@@ -0,0 +1,95 @@
+/**
+ * There is NO "seo" lens in `eval-lenses.ts` LENS_CATALOG — `resolveLensFocus("seo")`
+ * would only return a bland generic fallback string. This is a dedicated,
+ * purpose-written floor so an empty index still yields useful guidance, and
+ * `promptFragment` is guaranteed non-empty (sc-2-4).
+ */
+const SEO_GENERIC_FLOOR = "Apply the generic SEO/GEO playbook: prioritise cited, first-party, evidence-backed signals " +
+    "(branded mentions, YouTube presence, comprehensive fan-out coverage) over volume tactics (bulk " +
+    "backlinks, mass-produced pages); never recommend a never-encode tactic (parasite SEO, expired-domain " +
+    "plays, paid links, AI-recommendation poisoning).";
+/** score = workflow membership + target/vertical keyword overlap. */
+function scoreSignature(signature, input) {
+    let score = 0;
+    if (signature.workflows.includes(input.workflow))
+        score += 3;
+    const needles = [input.target, input.vertical]
+        .filter((v) => typeof v === "string" && v.length > 0)
+        .map((v) => v.toLowerCase());
+    for (const needle of needles) {
+        for (const keyword of signature.keywords) {
+            const keywordLower = keyword.toLowerCase();
+            if (needle.includes(keywordLower) || keywordLower.includes(needle))
+                score += 1;
+        }
+    }
+    return score;
+}
+/**
+ * Pure and total: ranks `workflowSigs` by score, caps at `topK`, then ALWAYS
+ * concatenates `floor` (the generic-skill signatures), deduped by
+ * `playbookId` — the floor is present even when it did not rank into the
+ * top-K on its own merit (sc-2-4).
+ */
+function selectSeoSignatures(input) {
+    const workflowSigs = Array.isArray(input.workflowSigs) ? input.workflowSigs : [];
+    const floor = Array.isArray(input.floor) ? input.floor : [];
+    const topK = Number.isFinite(input.topK) ? Math.max(0, Math.trunc(input.topK)) : 0;
+    const ranked = workflowSigs
+        .map((signature) => ({ signature, score: scoreSignature(signature, input) }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, topK)
+        .map((r) => r.signature);
+    const selected = [...ranked];
+    const seen = new Set(selected.map((s) => s.playbookId));
+    for (const floorSig of floor) {
+        if (!seen.has(floorSig.playbookId)) {
+            seen.add(floorSig.playbookId);
+            selected.push(floorSig);
+        }
+    }
+    return selected;
+}
+function renderSignature(signature) {
+    return [
+        `### ${signature.playbookId} — ${signature.title}`,
+        `Invariant: ${signature.invariant}`,
+        `Tactic: ${signature.tactic}`,
+        `Source: ${signature.primarySourceUrl}`,
+        `LiveWeight: ${signature.liveWeightStatus}`,
+    ].join("\n");
+}
+/**
+ * Renders the selected signatures into a compact prompt fragment. NEVER
+ * empty: falls back to `SEO_GENERIC_FLOOR` when the selected set is empty
+ * (e.g. a wholly missing/empty skills directory — closes the analogue of G3).
+ */
+function renderPromptFragment(signatures) {
+    return signatures.length > 0 ? signatures.map(renderSignature).join("\n\n") : SEO_GENERIC_FLOOR;
+}
+export class SeoPlaybookRetriever {
+    index;
+    constructor(index) {
+        this.index = index;
+    }
+    /**
+     * Never throws: loads (idempotent) the index, ranks the workflow's
+     * matching signatures, and always includes the generic floor deduped by
+     * `playbookId`. `promptFragment` is never empty.
+     */
+    async retrieve(input) {
+        await this.index.load();
+        const floor = this.index.generic();
+        const workflowSigs = this.index.all().filter((s) => s.workflows.includes(input.workflow));
+        const signatures = selectSeoSignatures({
+            workflow: input.workflow,
+            target: input.target,
+            vertical: input.vertical,
+            topK: input.topK ?? 8,
+            workflowSigs,
+            floor,
+        });
+        return { promptFragment: renderPromptFragment(signatures), signatures };
+    }
+}
+//# sourceMappingURL=retriever.js.map

package/dist/seo/retriever.js.map

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

package/dist/seo/runner.d.ts

@@ -0,0 +1,108 @@
+/**
+ * SeoWorkflowRunner — the end-to-end SEO workflow pipeline
+ * (spec-20260715-ultimate-seo-suite, Sprint 11). Mirrors
+ * `runStandaloneSecurityAudit` (`src/cli/commands/security-audit.ts:141-180`):
+ * resolve playbook context -> select a data source -> gather data -> analyze
+ * -> never-encode filter -> citation gate -> persist -> best-effort hub emit
+ * -> exit code.
+ *
+ * Clock discipline: `now` is injected by the caller (`SeoCommand`) and NEVER
+ * re-stamped here — this file never constructs a `Date` for wall-clock
+ * purposes (the `.tmp` uniqueness suffix inside `SeoReportStore.save` is a
+ * uniqueness token, not a report timestamp, and lives in a different file).
+ *
+ * Fail-closed: EVERY step that can throw (context resolution, source
+ * selection, data gathering, analysis, persistence) is wrapped in a single
+ * top-level try/catch -> `exitCode: 2` (arch line 395). A transport error
+ * from `analyzer.analyze` (which does NOT catch `llm.chat` errors itself,
+ * `analyzer.ts:16-18`) is caught here. A `parsed: false` analysis result is
+ * ALSO fail-closed -> `exitCode: 2` with ZERO hub emits (sc-11-5) — checked
+ * BEFORE the never-encode filter and citation gate run.
+ *
+ * Never-encode belt (spec-20260717-seo-improver-builder, Sprint 2; ADR-3):
+ * `NeverEncodeFilter` runs between the `parsed` check and the citation gate,
+ * dropping any LLM-synthesized banned tactic — even one carrying a
+ * well-formed `citationUrl` that would otherwise pass the gate. Only its
+ * `kept` findings ever reach `SeoCitationGate.apply`.
+ *
+ * Hub emission is best-effort and happens strictly AFTER the report has
+ * been persisted; a hub failure never changes the exit code (mirrors
+ * `emitFindingsToHub`, `security-audit.ts:196-239`). Only `gate.cited`
+ * findings are ever passed to the emitter — an uncited finding is dropped
+ * TWICE (the gate, then `SeoHubEmitter.mapToFindings`'s own belt-and-
+ * suspenders check).
+ */
+import type { BoberConfig } from "../config/schema.js";
+import type { SeoWorkflow, SeoReport } from "./types.js";
+import type { AiVisibilityDeps } from "./ai-visibility-provider.js";
+import type { SeoDataSource } from "./data-source.js";
+import { SeoAnalyzer } from "./analyzer.js";
+import type { SeoFindingSink } from "./hub-emitter.js";
+import type { SeoVerifier } from "./verifier.js";
+export type SeoRunInput = {
+    projectRoot: string;
+    /** May omit `seo` entirely — the explicit CLI call IS the opt-in. */
+    config: BoberConfig;
+    workflow: SeoWorkflow;
+    /** Defaults to `config.seo?.defaultTarget`, then `DEFAULT_TARGET_FALLBACK`. */
+    target?: string;
+    /** ISO timestamp, stamped ONCE by `SeoCommand`. */
+    now: string;
+    /** TEST injection — default = `selectSource(config, projectRoot)`. */
+    dataSource?: SeoDataSource;
+    /** TEST injection — default binds `ingestFinding` to a real `FactStore`. */
+    findingSink?: SeoFindingSink;
+    /**
+     * TEST injection so `runner.test.ts` never builds a real LLM client
+     * (the built `SeoAnalyzer` is LLM-only — `analyzer.ts:280-288` always
+     * calls `llm.chat`). Default = a real `SeoAnalyzer` via `createClient`.
+     */
+    analyzer?: SeoAnalyzer;
+    /**
+     * TEST injection for the opt-in adversarial verifier stage (Sprint 12).
+     * Default = a real `SeoRecommendationVerifier`, constructed and invoked
+     * ONLY when `config.seo?.verifier?.enabled === true` (byte-identical to
+     * the no-verifier run otherwise — sc-12-2).
+     */
+    verifier?: SeoVerifier;
+};
+export type SeoRunOutcome = {
+    report?: SeoReport;
+    exitCode: 0 | 2;
+};
+/**
+ * Build the `SeoDataSource` for a run from the FOUR independent egress axes
+ * (widened from two, spec-20260717-seo-improver-builder Sprint 9). ALL FOUR
+ * axes off (default) -> `LocalExportSource` (zero egress, no credentials
+ * touched, no governor/ledger constructed, `import('damcrawler')` never
+ * evaluated — sc-9-2). This `return` is the FIRST statement after the
+ * predicate, strictly BEFORE `SeoQuotaGovernor.load` (sprint briefing
+ * Pattern B / Pitfall 2) — that ordering is what makes the all-off path
+ * provably zero-construction.
+ *
+ * Otherwise, assemble a `CapabilitySeoRouter` per the deterministic
+ * ADR-8/ADR-10 route table (sc-9-3):
+ *   - `url-inspection`: `GscAdapter` when `search-console` is on (GSC always
+ *     wins, ADR-8); else `CrawlSource` when `site-crawl` is on.
+ *   - `link-graph`: `CrawlSource` when `site-crawl` is on.
+ *   - `serp`: the config-selected `SerpProvider` (`resolveSerpProvider`,
+ *     ADR-10), wrapped in `SerpProviderSource`, whenever `serp-provider` OR
+ *     `site-crawl` is on (whichever axis the selected provider itself
+ *     requires; each provider re-asserts its own axis on call).
+ *   - `keywords`/`backlinks`: `DataForSeoAdapter` when `serp-provider` is on.
+ *   - `ai-visibility`: `AiVisibilityAdapter` wrapping the composed
+ *     `resolveAiVisibilityProvider(...)` result when `ai-visibility` is on
+ *     AND at least one configured engine is keyed (Sprint 3); the offline
+ *     `LocalExportSource` arm otherwise (no-key-safe fallback).
+ */
+export declare function selectSource(config: BoberConfig, projectRoot: string, deps?: AiVisibilityDeps): Promise<SeoDataSource>;
+export declare class SeoWorkflowRunner {
+    /**
+     * Run one SEO workflow end-to-end. NEVER throws — every failure mode
+     * (context/source/gather/analyze/persist errors, a `parsed: false`
+     * analysis, or a blocked citation gate) resolves to `exitCode: 2`;
+     * only a fully successful, non-blocked run resolves to `exitCode: 0`.
+     */
+    run(input: SeoRunInput): Promise<SeoRunOutcome>;
+}
+//# sourceMappingURL=runner.d.ts.map

package/dist/seo/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/seo/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AASvD,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAe,MAAM,YAAY,CAAC;AAetE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAIpE,OAAO,KAAK,EACV,aAAa,EAgBd,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAM5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAIjD,MAAM,MAAM,WAAW,GAAG;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,EAAE,WAAW,CAAC;IACtB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,4EAA4E;IAC5E,WAAW,CAAC,EAAE,cAAc,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAAE,MAAM,CAAC,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAA;CAAE,CAAC;AA8OpE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,WAAW,EACnB,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,gBAAgB,GACtB,OAAO,CAAC,aAAa,CAAC,CA8ExB;AA6GD,qBAAa,iBAAiB;IAC5B;;;;;OAKG;IACG,GAAG,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;CAoFtD"}