agent-bober 0.17.1 → 0.19.0

package/dist/seo/builder/hub-approved-source.js

@@ -0,0 +1,48 @@
+/**
+ * readApprovedSeoFindings — the hub->ApprovedFinding adapter
+ * (spec-20260717-seo-improver-builder, Sprint 11; ADR-4). The REVERSE of
+ * `../hub-emitter.ts`'s SeoFinding->hub mapping: decodes exactly what the
+ * emitter encoded (domain `"seo"` filter, `cite:` evidence extraction,
+ * `playbook:`/`workflow:` tag extraction — all inside `ApprovedFinding.from`).
+ *
+ * Reads RAW rows via the same primitive `../../hub/finding-store.ts:47`'s
+ * `readFindings` uses (`getActiveFacts(HUB_SCOPE, undefined, "finding")`) —
+ * deliberately NOT `readFindings()` itself, because that helper calls
+ * `FindingSchema.parse`, which THROWS on a status outside the canonical
+ * 5-value enum (`finding-store.ts:48`); an `"approved"` row would crash it.
+ * Instead each row is `safeParse`d against the widened
+ * `ApprovedHubFindingSchema` and skipped on failure — mirrors
+ * `FactStoreFindingSource.read` (`../../hub/finding-source.ts`,
+ * "never throws; skip malformed").
+ */
+import { HUB_SCOPE } from "../../hub/finding-source.js";
+import { ApprovedFinding, ApprovedHubFindingSchema } from "./approved-finding.js";
+/**
+ * Reads approved, cited, SEO-domain hub Findings from `store` and maps each
+ * to an `ApprovedFinding` via `ApprovedFinding.from`. Never throws: malformed
+ * JSON, schema-invalid rows, non-`"seo"`-domain rows, non-`"approved"`
+ * status, and uncited/malformed-citation rows are all silently skipped
+ * (sc-11-4).
+ */
+export function readApprovedSeoFindings(store) {
+    const out = [];
+    for (const row of store.getActiveFacts(HUB_SCOPE, undefined, "finding")) {
+        let json;
+        try {
+            json = JSON.parse(row.value);
+        }
+        catch {
+            continue; // malformed JSON — skip, never throw
+        }
+        const parsed = ApprovedHubFindingSchema.safeParse(json);
+        if (!parsed.success)
+            continue; // schema-invalid — skip
+        if (parsed.data.domain !== "seo")
+            continue; // SEO-domain only (../hub-emitter.ts:69)
+        const approved = ApprovedFinding.from(parsed.data); // null if !approved / cite-bad
+        if (approved !== null)
+            out.push(approved);
+    }
+    return out;
+}
+//# sourceMappingURL=hub-approved-source.js.map

package/dist/seo/builder/hub-approved-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub-approved-source.js","sourceRoot":"","sources":["../../../src/seo/builder/hub-approved-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAGxD,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAElF;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAgB;IACtD,MAAM,GAAG,GAAsB,EAAE,CAAC;IAElC,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,cAAc,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC;QACxE,IAAI,IAAa,CAAC;QAClB,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAY,CAAC;QAC1C,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,CAAC,qCAAqC;QACjD,CAAC;QAED,MAAM,MAAM,GAAG,wBAAwB,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACxD,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,SAAS,CAAC,wBAAwB;QAEvD,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,KAAK;YAAE,SAAS,CAAC,yCAAyC;QAErF,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,+BAA+B;QACnF,IAAI,QAAQ,KAAK,IAAI;YAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5C,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/seo/builder/seo-builder.d.ts

@@ -0,0 +1,72 @@
+/**
+ * SeoBuilder — the gated generative builder (spec-20260717-seo-improver-
+ * builder, Sprint 12; ADR-4, the highest-risk piece of this spec). Crosses
+ * the advisory→generative boundary that Sprints 2/11 fenced off:
+ * `build(input)` accepts `ApprovedFinding[]` ONLY (`./approved-finding.js`) —
+ * a raw `SeoFinding[]` does not type-check (see `seo-builder.test.ts`'s
+ * `@ts-expect-error` compile-proof, sc-12-1) — and is constructed with a
+ * MANDATORY `NeverEncodeFilter` (`../never-encode-filter.js`, Sprint 2) that
+ * is re-run over EVERY generated draft's artifact text before it is
+ * returned (drop-only, sc-12-3/sc-12-4). Every returned `SeoDraft` carries
+ * `humanApprovalRequired: true` (the type's literal, ADR-4) and a
+ * `sourceCitationUrl` copied verbatim from the approving finding — nothing
+ * is ever auto-applied to a live property.
+ *
+ * Mirrors `SeoAnalyzer`'s shape (`../analyzer.ts:304-336`): constructor-
+ * injected deps, `now` threaded in (never `new Date()`), and never-throws-
+ * on-recoverable-failure — here, a per-finding generation error increments
+ * `skipped` and moves on rather than bricking the whole batch (same
+ * drop-only spirit as `NeverEncodeFilter`, `../never-encode-filter.ts:16`).
+ */
+import type { BoberConfig } from "../../config/schema.js";
+import type { NeverEncodeFilter } from "../never-encode-filter.js";
+import type { ApprovedFinding } from "./approved-finding.js";
+import { type DraftGenerator } from "./draft-generators.js";
+import type { SeoDraft, SeoDraftKind } from "./draft-types.js";
+export type SeoBuildInput = {
+    /** ONLY `ApprovedFinding[]` — a raw `SeoFinding[]` must NOT type-check (sc-12-1). */
+    approvedFindings: ApprovedFinding[];
+    /** The URL/page/entity every produced draft targets. */
+    target: string;
+    /**
+     * Accepted for interface parity with `SeoAnalyzeInput` (`../analyzer.ts:76`)
+     * and the Sprint-13 runner/CLI contract. Not consumed by this sprint's
+     * `build` body — no builder behaviour this sprint reads `config`.
+     */
+    config: BoberConfig;
+    /** Injected wall-clock snapshot (ISO-8601) — `build` never reads the clock itself. */
+    now: string;
+};
+export type SeoBuildResult = {
+    drafts: SeoDraft[];
+    /** Count of approved findings that produced NO draft — either a generation error or a never-encode re-filter drop. */
+    skipped: number;
+};
+export declare class SeoBuilder {
+    /** MANDATORY (sc-12-1, ADR-4) — re-run over every generated draft's artifact text before it is returned. */
+    private readonly neverEncode;
+    private readonly generators;
+    constructor(
+    /** MANDATORY (sc-12-1, ADR-4) — re-run over every generated draft's artifact text before it is returned. */
+    neverEncode: NeverEncodeFilter, generators?: Record<SeoDraftKind, DraftGenerator>);
+    /**
+     * Generates one `SeoDraft` per approved finding via the deterministic
+     * templates in `./draft-generators.js`, re-runs the mandatory
+     * `NeverEncodeFilter` over each artifact, and returns only the drafts
+     * that pass. NEVER throws: a generation error for one finding increments
+     * `skipped` and the loop continues (sc-12-5).
+     */
+    build(input: SeoBuildInput): SeoBuildResult;
+    /**
+     * Re-runs the INJECTED `NeverEncodeFilter` over `artifactText` (§4 of the
+     * sprint briefing). `NeverEncodeFilter.apply` scans `SeoFinding.recommendation`
+     * + evidence fields (`../never-encode-filter.ts:50-57`); a `SeoDraft` has
+     * no `recommendation` field, so a throwaway probe `SeoFinding` is built
+     * whose `recommendation` IS the draft artifact text — the only field that
+     * matters for the scan. Using the injected filter instance (rather than
+     * `NEVER_ENCODE_PATTERNS` directly) keeps the "mandatory filter" guarantee
+     * load-bearing and testable (a test could inject a spy filter).
+     */
+    private isBanned;
+}
+//# sourceMappingURL=seo-builder.d.ts.map

package/dist/seo/builder/seo-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo-builder.d.ts","sourceRoot":"","sources":["../../../src/seo/builder/seo-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAGnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAoD,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC9G,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAI/D,MAAM,MAAM,aAAa,GAAG;IAC1B,qFAAqF;IACrF,gBAAgB,EAAE,eAAe,EAAE,CAAC;IACpC,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,EAAE,WAAW,CAAC;IACpB,sFAAsF;IACtF,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,sHAAsH;IACtH,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAIF,qBAAa,UAAU;IAEnB,4GAA4G;IAC5G,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,UAAU;;IAF3B,4GAA4G;IAC3F,WAAW,EAAE,iBAAiB,EAC9B,UAAU,GAAE,MAAM,CAAC,YAAY,EAAE,cAAc,CAA4B;IAG9F;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,cAAc;IAiC3C;;;;;;;;;OASG;IACH,OAAO,CAAC,QAAQ;CAajB"}

package/dist/seo/builder/seo-builder.js

@@ -0,0 +1,72 @@
+import { DEFAULT_DRAFT_GENERATORS, kindForApprovedFinding } from "./draft-generators.js";
+// -- SeoBuilder ---------------------------------------------------------------
+export class SeoBuilder {
+    neverEncode;
+    generators;
+    constructor(
+    /** MANDATORY (sc-12-1, ADR-4) — re-run over every generated draft's artifact text before it is returned. */
+    neverEncode, generators = DEFAULT_DRAFT_GENERATORS) {
+        this.neverEncode = neverEncode;
+        this.generators = generators;
+    }
+    /**
+     * Generates one `SeoDraft` per approved finding via the deterministic
+     * templates in `./draft-generators.js`, re-runs the mandatory
+     * `NeverEncodeFilter` over each artifact, and returns only the drafts
+     * that pass. NEVER throws: a generation error for one finding increments
+     * `skipped` and the loop continues (sc-12-5).
+     */
+    build(input) {
+        const drafts = [];
+        let skipped = 0;
+        for (const finding of input.approvedFindings) {
+            try {
+                const kind = kindForApprovedFinding(finding);
+                const artifact = this.generators[kind](finding, input.target);
+                if (this.isBanned(artifact)) {
+                    // Re-filter DROP (sc-12-3/sc-12-4) — never emitted, counted as skipped.
+                    skipped += 1;
+                    continue;
+                }
+                drafts.push({
+                    kind,
+                    humanApprovalRequired: true, // LITERAL true (draft-types.ts) — never a plain boolean.
+                    sourceCitationUrl: finding.sourceCitationUrl, // COPIED verbatim — never invented.
+                    sourceFindingId: finding.sourceFindingId,
+                    target: input.target,
+                    artifact,
+                    playbookRef: finding.playbookRef,
+                });
+            }
+            catch {
+                // A generation error skips this finding only — never bricks the batch (sc-12-5).
+                skipped += 1;
+            }
+        }
+        return { drafts, skipped };
+    }
+    /**
+     * Re-runs the INJECTED `NeverEncodeFilter` over `artifactText` (§4 of the
+     * sprint briefing). `NeverEncodeFilter.apply` scans `SeoFinding.recommendation`
+     * + evidence fields (`../never-encode-filter.ts:50-57`); a `SeoDraft` has
+     * no `recommendation` field, so a throwaway probe `SeoFinding` is built
+     * whose `recommendation` IS the draft artifact text — the only field that
+     * matters for the scan. Using the injected filter instance (rather than
+     * `NEVER_ENCODE_PATTERNS` directly) keeps the "mandatory filter" guarantee
+     * load-bearing and testable (a test could inject a spy filter).
+     */
+    isBanned(artifactText) {
+        const probe = {
+            recommendation: artifactText,
+            workflow: "technical-audit",
+            playbookRef: "",
+            citationUrl: "",
+            evidence: [],
+            severity: 3,
+            humanApprovalRequired: false,
+            confidence: "firm",
+        };
+        return this.neverEncode.apply([probe]).dropped.length > 0;
+    }
+}
+//# sourceMappingURL=seo-builder.js.map

package/dist/seo/builder/seo-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo-builder.js","sourceRoot":"","sources":["../../../src/seo/builder/seo-builder.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAE,wBAAwB,EAAE,sBAAsB,EAAuB,MAAM,uBAAuB,CAAC;AA0B9G,gFAAgF;AAEhF,MAAM,OAAO,UAAU;IAGF;IACA;IAHnB;IACE,4GAA4G;IAC3F,WAA8B,EAC9B,aAAmD,wBAAwB;QAD3E,gBAAW,GAAX,WAAW,CAAmB;QAC9B,eAAU,GAAV,UAAU,CAAiE;IAC3F,CAAC;IAEJ;;;;;;OAMG;IACH,KAAK,CAAC,KAAoB;QACxB,MAAM,MAAM,GAAe,EAAE,CAAC;QAC9B,IAAI,OAAO,GAAG,CAAC,CAAC;QAEhB,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC;YAC7C,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC;gBAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;gBAE9D,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAC5B,wEAAwE;oBACxE,OAAO,IAAI,CAAC,CAAC;oBACb,SAAS;gBACX,CAAC;gBAED,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI;oBACJ,qBAAqB,EAAE,IAAI,EAAE,yDAAyD;oBACtF,iBAAiB,EAAE,OAAO,CAAC,iBAAiB,EAAE,oCAAoC;oBAClF,eAAe,EAAE,OAAO,CAAC,eAAe;oBACxC,MAAM,EAAE,KAAK,CAAC,MAAM;oBACpB,QAAQ;oBACR,WAAW,EAAE,OAAO,CAAC,WAAW;iBACjC,CAAC,CAAC;YACL,CAAC;YAAC,MAAM,CAAC;gBACP,iFAAiF;gBACjF,OAAO,IAAI,CAAC,CAAC;YACf,CAAC;QACH,CAAC;QAED,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAC7B,CAAC;IAED;;;;;;;;;OASG;IACK,QAAQ,CAAC,YAAoB;QACnC,MAAM,KAAK,GAAe;YACxB,cAAc,EAAE,YAAY;YAC5B,QAAQ,EAAE,iBAAiB;YAC3B,WAAW,EAAE,EAAE;YACf,WAAW,EAAE,EAAE;YACf,QAAQ,EAAE,EAAE;YACZ,QAAQ,EAAE,CAAC;YACX,qBAAqB,EAAE,KAAK;YAC5B,UAAU,EAAE,MAAM;SACnB,CAAC;QACF,OAAO,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;IAC5D,CAAC;CACF"}

package/dist/seo/citation-gate.d.ts

@@ -0,0 +1,36 @@
+/**
+ * SeoCitationGate — the deterministic, offline, pre-hub citation gate
+ * (spec-20260715-ultimate-seo-suite, Sprint 10; ADR-3,
+ * arch-20260715-ultimate-seo-agents-skills-architecture.md:279-295).
+ *
+ * Pure and total: no LLM, no egress, no filesystem, no clock. Imports
+ * nothing beyond `./types.js`. Partitions findings by whether their
+ * `citationUrl` is a well-formed primary-source URL — uncited findings are
+ * dropped and NEVER reach the hub (Sprint 11) or a human.
+ *
+ * Naming note (see the sprint briefing §0): the contract (sc-10-3) spells
+ * the method `filter`; the architecture and generatorNotes call it `apply`.
+ * Both are provided — `filter` is an alias of the same implementation.
+ */
+import type { SeoFinding } from "./types.js";
+/** Mirrors `SeoConfigSchema.blockThreshold` (config/schema.ts:697). */
+export type SeoBlockThreshold = "never" | "any-uncited" | "critical-uncited";
+export type CitationGateResult = {
+    /** Findings with a well-formed primary-source citationUrl — the ONLY findings emitted downstream. */
+    cited: SeoFinding[];
+    /** Findings with an empty/malformed citationUrl — never reach the hub. */
+    dropped: SeoFinding[];
+    /** Fail-closed exit-2 signal, derived from `dropped` per `threshold`. */
+    blocked: boolean;
+};
+export declare class SeoCitationGate {
+    /**
+     * Partitions `findings` into `cited`/`dropped` by citationUrl
+     * well-formedness, then derives `blocked` from `threshold`. Pure and
+     * total: identical input always yields identical output.
+     */
+    apply(findings: SeoFinding[], threshold: SeoBlockThreshold): CitationGateResult;
+    /** Alias of `apply` — satisfies the contract's literal `.filter(...)` wording (sc-10-3). */
+    filter: (findings: SeoFinding[], threshold: SeoBlockThreshold) => CitationGateResult;
+}
+//# sourceMappingURL=citation-gate.d.ts.map

package/dist/seo/citation-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citation-gate.d.ts","sourceRoot":"","sources":["../../src/seo/citation-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,uEAAuE;AACvE,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,aAAa,GAAG,kBAAkB,CAAC;AAE7E,MAAM,MAAM,kBAAkB,GAAG;IAC/B,qGAAqG;IACrG,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,0EAA0E;IAC1E,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,yEAAyE;IACzE,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAuCF,qBAAa,eAAe;IAC1B;;;;OAIG;IACH,KAAK,CAAC,QAAQ,EAAE,UAAU,EAAE,EAAE,SAAS,EAAE,iBAAiB,GAAG,kBAAkB;IAe/E,4FAA4F;IAC5F,MAAM,GAAI,UAAU,UAAU,EAAE,EAAE,WAAW,iBAAiB,KAAG,kBAAkB,CACjD;CACnC"}

package/dist/seo/citation-gate.js

@@ -0,0 +1,59 @@
+/**
+ * A citationUrl is well-formed when it is a non-empty, non-whitespace
+ * string that parses as an absolute http(s) URL. No URL-validation utility
+ * exists elsewhere in `src` — this is a local, single-purpose check.
+ */
+function isWellFormedCitationUrl(url) {
+    if (typeof url !== "string" || url.trim().length === 0)
+        return false;
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === "http:" || parsed.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * bober: the "critical" cutoff for `critical-uncited` is not pinned by the
+ * contract; severity 4-5 (of the 1..5 scale) is the recommended reading
+ * per the sprint briefing — bump this constant if that reading changes.
+ */
+const CRITICAL_SEVERITY_FLOOR = 4;
+function isBlocked(dropped, threshold) {
+    switch (threshold) {
+        case "never":
+            return false;
+        case "any-uncited":
+            return dropped.length > 0;
+        case "critical-uncited":
+            return dropped.some((finding) => finding.severity >= CRITICAL_SEVERITY_FLOOR);
+        default: {
+            const _exhaustive = threshold; // compile error if a SeoBlockThreshold value is unhandled
+            return _exhaustive;
+        }
+    }
+}
+export class SeoCitationGate {
+    /**
+     * Partitions `findings` into `cited`/`dropped` by citationUrl
+     * well-formedness, then derives `blocked` from `threshold`. Pure and
+     * total: identical input always yields identical output.
+     */
+    apply(findings, threshold) {
+        const cited = [];
+        const dropped = [];
+        for (const finding of findings) {
+            if (isWellFormedCitationUrl(finding.citationUrl)) {
+                cited.push(finding);
+            }
+            else {
+                dropped.push(finding);
+            }
+        }
+        return { cited, dropped, blocked: isBlocked(dropped, threshold) };
+    }
+    /** Alias of `apply` — satisfies the contract's literal `.filter(...)` wording (sc-10-3). */
+    filter = (findings, threshold) => this.apply(findings, threshold);
+}
+//# sourceMappingURL=citation-gate.js.map

package/dist/seo/citation-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"citation-gate.js","sourceRoot":"","sources":["../../src/seo/citation-gate.ts"],"names":[],"mappings":"AA4BA;;;;GAIG;AACH,SAAS,uBAAuB,CAAC,GAAW;IAC1C,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACrE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,OAAO,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAElC,SAAS,SAAS,CAAC,OAAqB,EAAE,SAA4B;IACpE,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,OAAO;YACV,OAAO,KAAK,CAAC;QACf,KAAK,aAAa;YAChB,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;QAC5B,KAAK,kBAAkB;YACrB,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,IAAI,uBAAuB,CAAC,CAAC;QAChF,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,WAAW,GAAU,SAAS,CAAC,CAAC,0DAA0D;YAChG,OAAO,WAAW,CAAC;QACrB,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,OAAO,eAAe;IAC1B;;;;OAIG;IACH,KAAK,CAAC,QAAsB,EAAE,SAA4B;QACxD,MAAM,KAAK,GAAiB,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAiB,EAAE,CAAC;QAEjC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,IAAI,uBAAuB,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;gBACjD,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACtB,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;QAED,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;IACpE,CAAC;IAED,4FAA4F;IAC5F,MAAM,GAAG,CAAC,QAAsB,EAAE,SAA4B,EAAsB,EAAE,CACpF,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;CACnC"}

package/dist/seo/command.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from "commander";
+import type { SeoRunInput, SeoRunOutcome } from "./runner.js";
+import type { SeoBuildRunInput, SeoBuildRunOutcome } from "./builder/build-runner.js";
+export interface SeoCommandOverrides {
+    /** Injected in tests to bypass the real runner (no real LLM/network/fs). */
+    runWorkflow?: (input: SeoRunInput) => Promise<SeoRunOutcome>;
+    /** Injected in tests to bypass the real build runner (no real fs/hub). */
+    runBuild?: (input: SeoBuildRunInput) => Promise<SeoBuildRunOutcome>;
+}
+export declare function registerSeoCommand(program: Command, overrides?: SeoCommandOverrides): void;
+//# sourceMappingURL=command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/seo/command.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOzC,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAkBtF,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IAC7D,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACrE;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAqE1F"}

package/dist/seo/command.js

@@ -0,0 +1,90 @@
+/**
+ * `bober seo <workflow> [target]` — run an SEO workflow end-to-end.
+ * (spec-20260715-ultimate-seo-suite, Sprint 11.)
+ *
+ * Mirrors `registerSecurityAuditCommand`
+ * (`src/cli/commands/security-audit.ts:289-322`): `now` is stamped ONCE at
+ * the `.action()` boundary and threaded downstream — never re-read inside
+ * `SeoWorkflowRunner`. The handler NEVER throws; it always sets
+ * `process.exitCode` (`0` pass / `2` blocked-or-fail-closed — `1` is
+ * Commander-reserved).
+ *
+ * Lives at `src/seo/command.ts` (not `src/cli/commands/seo.ts`) per the
+ * contract's `estimatedFiles` — mirrors `registerFleetCommand`
+ * (`src/fleet/index.ts`, imported into the CLI at `cli/index.ts:39`).
+ *
+ * `bober seo build <reportId>` (spec-20260717-seo-improver-builder,
+ * Sprint 13) is an ADDITIVE child subcommand hung off the returned `seo`
+ * command — it does NOT alter the `seo <workflow> [target]` `.action()`
+ * chain above (sc-13-3). Same stamp-once + never-throw discipline via
+ * `SeoBuildRunner`.
+ */
+import chalk from "chalk";
+import { findProjectRoot } from "../utils/fs.js";
+import { loadConfig } from "../config/loader.js";
+import { SeoWorkflowRunner } from "./runner.js";
+import { SeoBuildRunner } from "./builder/build-runner.js";
+/** The 8 SEO workflows the CLI dispatches on (mirrors `types.ts:17-25`). */
+const SEO_WORKFLOWS = [
+    "technical-audit",
+    "rank-track",
+    "content-decay",
+    "topical-map",
+    "ai-visibility",
+    "parasite-watch",
+    "internal-linking",
+    "schema-audit",
+];
+function isSeoWorkflow(value) {
+    return SEO_WORKFLOWS.includes(value);
+}
+export function registerSeoCommand(program, overrides) {
+    const seo = program
+        .command("seo <workflow> [target]")
+        .description("Run an SEO workflow end-to-end (offline by default; opt-in live data via config.seo.egress).")
+        .action(async (workflow, target) => {
+        try {
+            if (!isSeoWorkflow(workflow)) {
+                process.stderr.write(chalk.red(`seo: unknown workflow "${workflow}". Expected one of: ${SEO_WORKFLOWS.join(", ")}\n`));
+                process.exitCode = 2;
+                return;
+            }
+            const projectRoot = (await findProjectRoot()) ?? process.cwd();
+            // Stamp wall-clock time ONLY here — never inside the runner.
+            const now = new Date().toISOString();
+            const config = await loadConfig(projectRoot);
+            const run = overrides?.runWorkflow ?? ((i) => new SeoWorkflowRunner().run(i));
+            const { report, exitCode } = await run({ projectRoot, config, workflow, target, now });
+            if (report) {
+                process.stdout.write(`SEO report ${report.reportId}: verdict=${report.verdict}, ` +
+                    `findings=${report.findings.length}, droppedUncited=${report.droppedUncited}\n`);
+            }
+            process.exitCode = exitCode;
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(`seo failed: ${err instanceof Error ? err.message : String(err)}\n`));
+            process.exitCode = 2; // fail-closed; 1 is Commander-reserved
+        }
+    });
+    // Additive child subcommand (spec-20260717-seo-improver-builder, Sprint 13)
+    // — does NOT alter the analyze `.action()` chain above (sc-13-3).
+    seo
+        .command("build <reportId>")
+        .description("Draft human-approval-required SEO artifacts from a report's approved hub findings.")
+        .action(async (reportId) => {
+        try {
+            const projectRoot = (await findProjectRoot()) ?? process.cwd();
+            // Stamp wall-clock time ONLY here — never inside the build runner.
+            const now = new Date().toISOString();
+            const config = await loadConfig(projectRoot);
+            const run = overrides?.runBuild ?? ((i) => new SeoBuildRunner().run(i));
+            const { exitCode } = await run({ projectRoot, config, reportId, now });
+            process.exitCode = exitCode;
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(`seo build failed: ${err instanceof Error ? err.message : String(err)}\n`));
+            process.exitCode = 2; // fail-closed; 1 is Commander-reserved
+        }
+    });
+}
+//# sourceMappingURL=command.js.map

package/dist/seo/command.js.map

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

package/dist/seo/content-sanitizer.d.ts

@@ -0,0 +1,56 @@
+/**
+ * ContentSanitizer — fail-closed wrapper around damcrawler's `sanitize`
+ * (spec-20260717-seo-improver-builder, Sprint 6; ADR-11).
+ *
+ * ADR-11's decision is to sanitize untrusted crawled/scraped free-text
+ * INSIDE the damcrawler adapter, at the network→in-process boundary,
+ * BEFORE it ever reaches `SeoAnalyzer` (which `JSON.stringify`s rows
+ * verbatim into its LLM system prompt — the prompt-injection surface this
+ * sprint closes). This class does no importing/loading of damcrawler
+ * itself — the caller (`DamcrawlerCrawlEngine`, already holding the loaded
+ * module behind the `site-crawl` axis) injects the narrow `SanitizeFn`.
+ *
+ * IMPORTANT SDK correction (see sprint briefing §0/§9.1): damcrawler's
+ * `sanitizeWithReport(raw, sourceUrl?)` returns a bare `string` — it does
+ * NOT yield `hadThreats`. The only damcrawler export exposing `hadThreats`
+ * is `sanitize(raw, options?): { content; threats; hadThreats }`
+ * (`damcrawler/src/lib/sanitize.ts:68-79,89`). This wrapper's `SanitizeFn`
+ * type matches THAT signature — callers must inject `dam.sanitize`, not
+ * `dam.sanitizeWithReport`.
+ */
+import { type Logger } from "../utils/logger.js";
+/**
+ * The narrow sanitize surface this module depends on — a SUBSET of
+ * damcrawler's `SanitizeResult` (`sanitize.ts:68-79`, `threats` omitted,
+ * this module never needs the detailed threat breakdown). Injected so
+ * tests never require the real `damcrawler` dependency.
+ */
+export type SanitizeFn = (raw: string, options?: {
+    sourceUrl?: string;
+}) => {
+    content: string;
+    hadThreats: boolean;
+};
+/**
+ * Fail-closed content sanitizer. `clean()` never throws: a successful
+ * sanitize call logs+strips on `hadThreats`; a sanitize-function error
+ * drops the text entirely (`content: ""`, `hadThreats: true`) rather than
+ * letting raw, unsanitized attacker-controlled text pass through.
+ */
+export declare class ContentSanitizer {
+    private readonly sanitizeFn;
+    private readonly log;
+    constructor(sanitizeFn: SanitizeFn, log?: Pick<Logger, "warn">);
+    /**
+     * Sanitizes `text` sourced from `url`. `hadThreats` is logged (warn, for
+     * audit) and the STRIPPED `content` is returned either way — callers
+     * must never fall back to the raw input. A thrown sanitize error is
+     * treated as fail-closed: the page's free-text is dropped rather than
+     * passed through unsanitized.
+     */
+    clean(text: string, url: string): {
+        content: string;
+        hadThreats: boolean;
+    };
+}
+//# sourceMappingURL=content-sanitizer.d.ts.map

package/dist/seo/content-sanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-sanitizer.d.ts","sourceRoot":"","sources":["../../src/seo/content-sanitizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAU,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,KAAK;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC;AAErH;;;;;GAKG;AACH,qBAAa,gBAAgB;IAEzB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,GAAG;gBADH,UAAU,EAAE,UAAU,EACtB,GAAG,GAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAU;IAGrD;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,CAAA;KAAE;CAW3E"}

package/dist/seo/content-sanitizer.js

@@ -0,0 +1,55 @@
+/**
+ * ContentSanitizer — fail-closed wrapper around damcrawler's `sanitize`
+ * (spec-20260717-seo-improver-builder, Sprint 6; ADR-11).
+ *
+ * ADR-11's decision is to sanitize untrusted crawled/scraped free-text
+ * INSIDE the damcrawler adapter, at the network→in-process boundary,
+ * BEFORE it ever reaches `SeoAnalyzer` (which `JSON.stringify`s rows
+ * verbatim into its LLM system prompt — the prompt-injection surface this
+ * sprint closes). This class does no importing/loading of damcrawler
+ * itself — the caller (`DamcrawlerCrawlEngine`, already holding the loaded
+ * module behind the `site-crawl` axis) injects the narrow `SanitizeFn`.
+ *
+ * IMPORTANT SDK correction (see sprint briefing §0/§9.1): damcrawler's
+ * `sanitizeWithReport(raw, sourceUrl?)` returns a bare `string` — it does
+ * NOT yield `hadThreats`. The only damcrawler export exposing `hadThreats`
+ * is `sanitize(raw, options?): { content; threats; hadThreats }`
+ * (`damcrawler/src/lib/sanitize.ts:68-79,89`). This wrapper's `SanitizeFn`
+ * type matches THAT signature — callers must inject `dam.sanitize`, not
+ * `dam.sanitizeWithReport`.
+ */
+import { logger } from "../utils/logger.js";
+/**
+ * Fail-closed content sanitizer. `clean()` never throws: a successful
+ * sanitize call logs+strips on `hadThreats`; a sanitize-function error
+ * drops the text entirely (`content: ""`, `hadThreats: true`) rather than
+ * letting raw, unsanitized attacker-controlled text pass through.
+ */
+export class ContentSanitizer {
+    sanitizeFn;
+    log;
+    constructor(sanitizeFn, log = logger) {
+        this.sanitizeFn = sanitizeFn;
+        this.log = log;
+    }
+    /**
+     * Sanitizes `text` sourced from `url`. `hadThreats` is logged (warn, for
+     * audit) and the STRIPPED `content` is returned either way — callers
+     * must never fall back to the raw input. A thrown sanitize error is
+     * treated as fail-closed: the page's free-text is dropped rather than
+     * passed through unsanitized.
+     */
+    clean(text, url) {
+        try {
+            const r = this.sanitizeFn(text, { sourceUrl: url });
+            if (r.hadThreats) {
+                this.log.warn(`[seo][content-sanitizer] injection vectors neutralized in ${url}`);
+            }
+            return { content: r.content, hadThreats: r.hadThreats };
+        }
+        catch {
+            return { content: "", hadThreats: true }; // fail-closed DROP: never pass raw text through
+        }
+    }
+}
+//# sourceMappingURL=content-sanitizer.js.map

package/dist/seo/content-sanitizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-sanitizer.js","sourceRoot":"","sources":["../../src/seo/content-sanitizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,MAAM,EAAe,MAAM,oBAAoB,CAAC;AAUzD;;;;;GAKG;AACH,MAAM,OAAO,gBAAgB;IAER;IACA;IAFnB,YACmB,UAAsB,EACtB,MAA4B,MAAM;QADlC,eAAU,GAAV,UAAU,CAAY;QACtB,QAAG,GAAH,GAAG,CAA+B;IAClD,CAAC;IAEJ;;;;;;OAMG;IACH,KAAK,CAAC,IAAY,EAAE,GAAW;QAC7B,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;YACpD,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC;gBACjB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,6DAA6D,GAAG,EAAE,CAAC,CAAC;YACpF,CAAC;YACD,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC;QAC1D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,gDAAgD;QAC5F,CAAC;IACH,CAAC;CACF"}

package/dist/seo/crawl-engine.d.ts

@@ -0,0 +1,35 @@
+/**
+ * CrawlEngine port (spec-20260717-seo-improver-builder, Sprint 6; ADR-9).
+ *
+ * Pure `interface` + query `type` only — no runtime code, mirroring
+ * `data-source.ts`'s structure. `DamcrawlerCrawlEngine` (Sprint 6) is the
+ * first implementer; `CrawlSource`/`SeoDataSource` wiring is deferred to
+ * Sprint 7 (nonGoal here).
+ *
+ * `UrlInspectionQuery`/`UrlInspectionRow`, `LinkGraphQuery`/`LinkGraphRow`,
+ * and `CrawlPageRow` already exist on `data-source.ts` (Sprint 1) — imported
+ * here, never redefined.
+ */
+import type { DataOutcome } from "./types.js";
+import type { UrlInspectionQuery, UrlInspectionRow, LinkGraphQuery, LinkGraphRow, CrawlPageRow } from "./data-source.js";
+/**
+ * Site-crawl query (rootUrl + optional bounds). No `Query` pair exists yet
+ * in `data-source.ts` for crawl pages — `CrawlPageRow` has none (see its
+ * docstring, `data-source.ts:136-143`) since the crawl query lives here.
+ */
+export type CrawlQuery = {
+    rootUrl: string;
+    limit?: number;
+    maxDepth?: number;
+};
+/**
+ * ADR-9 port. Every method: guard `site-crawl` FIRST (before any import),
+ * lazy-load damcrawler, and degrade to `{ kind: "abstain", reason }` —
+ * never throw to the caller.
+ */
+export interface CrawlEngine {
+    crawl(q: CrawlQuery): Promise<DataOutcome<CrawlPageRow[]>>;
+    urlVisibility(q: UrlInspectionQuery): Promise<DataOutcome<UrlInspectionRow[]>>;
+    linkGraph(q: LinkGraphQuery): Promise<DataOutcome<LinkGraphRow[]>>;
+}
+//# sourceMappingURL=crawl-engine.d.ts.map

package/dist/seo/crawl-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crawl-engine.d.ts","sourceRoot":"","sources":["../../src/seo/crawl-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,cAAc,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEzH;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhF;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC;IAC3D,aAAa,CAAC,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC;IAC/E,SAAS,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC;CACpE"}

package/dist/seo/crawl-engine.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=crawl-engine.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"crawl-engine.js","sourceRoot":"","sources":["../../src/seo/crawl-engine.ts"],"names":[],"mappings":""}