@oscharko-dev/keiko-server 0.2.0

package/dist/qualityIntelligence/exportRoutes.js

@@ -0,0 +1,320 @@
+// Quality Intelligence export BFF route (Epic #270, Issue #283 + #711).
+//
+//   * POST /api/quality-intelligence/runs/:id/export — serialise a run's candidates for export
+//
+// Local formats (csv / spreadsheet-safe-csv / json / markdown / plain-text) return the serialised
+// body for a same-origin download — no external credentials. Binary formats (pdf / zip-bundle) are
+// assembled server-side and returned as base64 in the JSON envelope. External TMS adapters
+// (jira / qtest / xray / polarion / alm / quality-center) are DISABLED for actual writes: they
+// only return a dry-run preview, require approved candidates, and never perform an outbound call.
+// The candidate bodies were already redacted at persist time; the bundle attests redaction so the
+// contract invariant holds. Path-/formula-safety lives in the pure adapters.
+import { QualityIntelligence } from "@oscharko-dev/keiko-contracts";
+import { sha256Hex } from "@oscharko-dev/keiko-security";
+import { QualityIntelligenceExport } from "@oscharko-dev/keiko-quality-intelligence";
+import { appendQualityIntelligenceExportRow, loadQualityIntelligenceRun, loadQualityIntelligenceCandidates, } from "@oscharko-dev/keiko-evidence";
+import { loadRunReviewState, candidateReviewStateOf, runReviewStateOf } from "./reviewStore.js";
+import { assemblePdf, assembleZipBundle } from "./exportAssembly.js";
+const ADAPTERS = new Set([
+    ...QualityIntelligence.QUALITY_INTELLIGENCE_EXPORT_ADAPTERS,
+    "pdf",
+    "zip-bundle",
+]);
+const MAX_BODY_BYTES = 16 * 1024;
+const LOCAL_META = {
+    csv: { contentType: "text/csv", ext: "csv" },
+    "spreadsheet-safe-csv": { contentType: "text/csv", ext: "csv" },
+    json: { contentType: "application/json", ext: "json" },
+    markdown: { contentType: "text/markdown", ext: "md" },
+    "plain-text": { contentType: "text/plain", ext: "txt" },
+    // NOTE: no "quality-center" entry — it is a TMS adapter, so a non-dry-run request is rejected with
+    // 403 before LOCAL_META is consulted, and the dry-run path returns a preview object that never
+    // reads LOCAL_META. The `?? { text/plain, txt }` fallback at the materialised-response site covers
+    // any future non-TMS text adapter.
+    pdf: { contentType: "application/pdf", ext: "pdf" },
+    "zip-bundle": { contentType: "application/zip", ext: "zip" },
+};
+const errorResult = (status, code, message) => ({
+    status,
+    body: { error: { code, message } },
+});
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const readBody = (req) => new Promise((resolve, reject) => {
+    const chunks = [];
+    let total = 0;
+    let capped = false;
+    req.on("data", (chunk) => {
+        total += chunk.length;
+        if (total > MAX_BODY_BYTES) {
+            if (!capped) {
+                capped = true;
+                chunks.length = 0;
+                reject(new Error("body too large"));
+                req.resume();
+            }
+            return;
+        }
+        chunks.push(chunk);
+    });
+    req.on("end", () => {
+        if (!capped)
+            resolve(Buffer.concat(chunks).toString("utf8"));
+    });
+    req.on("error", reject);
+});
+function rowToCandidate(row, runId) {
+    return {
+        id: QualityIntelligence.asQualityIntelligenceTestCaseId(row.id),
+        runId,
+        derivedFromAtomIds: row.derivedFromAtomIds.map((a) => QualityIntelligence.asQualityIntelligenceEvidenceAtomId(a)),
+        title: row.title,
+        preconditions: row.preconditions,
+        steps: row.steps,
+        expectedResults: row.expectedResults,
+        priority: row.priority,
+        riskClass: row.riskClass,
+        tags: row.tags,
+        status: row.status,
+    };
+}
+function buildBundle(runId, adapter, candidates, createdAt) {
+    const contents = candidates.map((c) => ({
+        candidateId: c.id,
+        coverageMapRefs: Object.freeze([]),
+        findingRefs: Object.freeze([]),
+    }));
+    const integrity = sha256Hex(JSON.stringify(candidates.map((c) => String(c.id))));
+    return {
+        id: QualityIntelligence.asQualityIntelligenceExportBundleId(`qi-export-${sha256Hex(`${runId}|${adapter}`).slice(0, 24)}`),
+        runId: QualityIntelligence.asQualityIntelligenceRunId(runId),
+        targetAdapter: adapter,
+        createdAt,
+        integrityHashSha256Hex: integrity,
+        redactionAttested: true,
+        contents,
+    };
+}
+/**
+ * Build the export-evidence row for an export action (Issue #283, AC4). Records the target type, a
+ * deterministic artifact id, an integrity hash over the exported candidate ids, the redaction
+ * attestation (candidates were redacted at persist time), and whether the action was a dry-run.
+ */
+function buildExportEvidenceRow(runId, target, rows, dryRun) {
+    return {
+        id: `qi-export-${sha256Hex(`${runId}|${target}`).slice(0, 24)}`,
+        targetAdapter: target,
+        integrityHash: sha256Hex(JSON.stringify(rows.map((r) => r.id))),
+        redactionAttested: true,
+        dryRun,
+    };
+}
+/**
+ * Best-effort append of an export-evidence row for a 200 export action (Issue #283, AC4). A failed
+ * audit write must NOT withhold an already-computed local export from the user: the artifact has no
+ * external side effect, the run already exists on disk, and the manifest write is atomic so this path
+ * is rare. Swallow on failure rather than turning a successful export into a 500. No-op for error
+ * responses and for the disabled external-TMS path (which produces no artifact).
+ */
+function recordExportEvidence(runId, outcome, evidenceDir) {
+    if (outcome.evidence === undefined || outcome.result.status !== 200) {
+        return;
+    }
+    try {
+        appendQualityIntelligenceExportRow({ runId, export: outcome.evidence }, { evidenceDir });
+    }
+    catch {
+        // intentionally swallowed — see doc comment
+    }
+}
+function parseExportBody(body) {
+    const adapter = body.adapter;
+    if (typeof adapter !== "string" || !ADAPTERS.has(adapter))
+        return undefined;
+    return {
+        adapter: adapter,
+        dryRun: body.dryRun === true,
+        approvedOnly: body.approvedOnly === true,
+    };
+}
+function selectRows(rows, approvedOnly, runId, evidenceDir) {
+    if (!approvedOnly)
+        return rows;
+    const review = loadRunReviewState(runId, evidenceDir);
+    // FIX E (Issue #282) — a reviewer can approve the whole RUN instead of each candidate. A
+    // run-level approval is an explicit approval of every candidate, so it satisfies approvedOnly
+    // (incl. the TMS adapters that force it). Otherwise fall back to the per-candidate filter.
+    if (runReviewStateOf(review) === "approved")
+        return rows;
+    return rows.filter((r) => candidateReviewStateOf(review, r.id) === "approved");
+}
+async function readExportRequest(req) {
+    let raw;
+    try {
+        raw = await readBody(req);
+    }
+    catch {
+        return {
+            ok: false,
+            result: errorResult(413, "QI_BODY_TOO_LARGE", "Export body is too large."),
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {
+            ok: false,
+            result: errorResult(400, "QI_BAD_REQUEST", "Export body is not valid JSON."),
+        };
+    }
+    if (!isObject(parsed)) {
+        return {
+            ok: false,
+            result: errorResult(400, "QI_BAD_REQUEST", "Export body must be an object."),
+        };
+    }
+    const request = parseExportBody(parsed);
+    if (request === undefined) {
+        return {
+            ok: false,
+            result: errorResult(400, "QI_BAD_ADAPTER", "A valid export adapter is required."),
+        };
+    }
+    return { ok: true, request };
+}
+export async function handleQiExport(ctx, deps) {
+    const { id } = ctx.params;
+    if (id === undefined || id.trim().length === 0) {
+        return errorResult(400, "QI_BAD_REQUEST", "Run id is required.");
+    }
+    const evidenceDir = deps.evidenceDir;
+    if (evidenceDir === undefined) {
+        return errorResult(500, "QI_NO_EVIDENCE_DIR", "The evidence directory is not configured.");
+    }
+    const parsed = await readExportRequest(ctx.req);
+    if (!parsed.ok)
+        return parsed.result;
+    try {
+        if (loadQualityIntelligenceRun(id, { evidenceDir }) === undefined) {
+            return errorResult(404, "QI_NOT_FOUND", "Quality Intelligence run not found.");
+        }
+        const artifact = loadQualityIntelligenceCandidates(id, { evidenceDir });
+        if (artifact === undefined || artifact.candidates.length === 0) {
+            return errorResult(409, "QI_NO_CANDIDATES", "This run has no candidates to export.");
+        }
+        const outcome = serialiseExport(id, parsed.request, artifact.candidates, evidenceDir);
+        // Emit audit evidence for every materialised export or dry-run preview (Issue #283, AC4). The
+        // append is best-effort and must not turn a successful export into a 500 — see recordExportEvidence.
+        recordExportEvidence(id, outcome, evidenceDir);
+        return outcome.result;
+    }
+    catch {
+        return errorResult(500, "QI_EXPORT_FAILED", "Failed to build the export.");
+    }
+}
+function binaryResponse(runId, mode, rows) {
+    const brandedRunId = QualityIntelligence.asQualityIntelligenceRunId(runId);
+    const candidates = rows.map((r) => rowToCandidate(r, brandedRunId));
+    const createdAt = new Date().toISOString();
+    const meta = LOCAL_META[mode] ?? { contentType: "application/octet-stream", ext: "bin" };
+    let bytes;
+    if (mode === "pdf") {
+        const bundle = buildBundle(runId, "plain-text", candidates, createdAt);
+        const serialized = QualityIntelligenceExport.serializeExportBundle(bundle, candidates);
+        bytes = assemblePdf(serialized.body, runId);
+    }
+    else {
+        const enc = new TextEncoder();
+        // Only timestamp-free serializers go into the bundle so the ZIP is byte-deterministic (its
+        // integrity feeds the Living-Tests drift epic #735). JSON is intentionally excluded: its body
+        // embeds the export `createdAt`, so a JSON-in-ZIP would differ on every export. JSON stays
+        // available as a standalone export.
+        const formats = ["csv", "markdown", "plain-text"];
+        const entries = formats.map((fmt) => {
+            const bundle = buildBundle(runId, fmt, candidates, createdAt);
+            const serialized = QualityIntelligenceExport.serializeExportBundle(bundle, candidates);
+            const ext = LOCAL_META[fmt]?.ext ?? "txt";
+            return { name: `${runId}.${ext}`, bytes: enc.encode(serialized.body) };
+        });
+        bytes = assembleZipBundle(entries);
+    }
+    return {
+        result: {
+            status: 200,
+            body: {
+                dryRun: false,
+                adapter: mode,
+                filename: `${runId}.${meta.ext}`,
+                contentType: meta.contentType,
+                byteLen: bytes.length,
+                encoding: "base64",
+                body: Buffer.from(bytes).toString("base64"),
+            },
+        },
+        evidence: buildExportEvidenceRow(runId, mode, rows, false),
+    };
+}
+function serialisedResponse(runId, request, rows) {
+    const adapter = request.adapter;
+    if (adapter === "pdf" || adapter === "zip-bundle") {
+        return binaryResponse(runId, adapter, rows);
+    }
+    const brandedRunId = QualityIntelligence.asQualityIntelligenceRunId(runId);
+    const candidates = rows.map((r) => rowToCandidate(r, brandedRunId));
+    const bundle = buildBundle(runId, adapter, candidates, new Date().toISOString());
+    const serialized = QualityIntelligenceExport.serializeExportBundle(bundle, candidates);
+    if (request.dryRun) {
+        return {
+            result: {
+                status: 200,
+                body: {
+                    dryRun: true,
+                    adapter,
+                    candidateCount: rows.length,
+                    byteLen: serialized.byteLen,
+                    preview: serialized.body.slice(0, 1200),
+                },
+            },
+            evidence: buildExportEvidenceRow(runId, adapter, rows, true),
+        };
+    }
+    const meta = LOCAL_META[adapter] ?? { contentType: "text/plain", ext: "txt" };
+    return {
+        result: {
+            status: 200,
+            body: {
+                dryRun: false,
+                adapter,
+                filename: `${runId}.${meta.ext}`,
+                contentType: meta.contentType,
+                byteLen: serialized.byteLen,
+                body: serialized.body,
+            },
+        },
+        evidence: buildExportEvidenceRow(runId, adapter, rows, false),
+    };
+}
+function serialiseExport(runId, request, allRows, evidenceDir) {
+    const adapter = request.adapter;
+    const isBinary = adapter === "pdf" || adapter === "zip-bundle";
+    const isTms = !isBinary && QualityIntelligence.QUALITY_INTELLIGENCE_TMS_ADAPTERS.has(adapter);
+    const approvedOnly = isTms ? true : request.approvedOnly;
+    const rows = selectRows(allRows, approvedOnly, runId, evidenceDir);
+    if (rows.length === 0) {
+        return {
+            result: errorResult(409, "QI_NOTHING_TO_EXPORT", approvedOnly ? "No approved candidates to export." : "No candidates to export."),
+        };
+    }
+    if (isTms && !request.dryRun) {
+        // External TMS write is disabled — no artifact is produced, so no export-evidence row is
+        // recorded for this rejected action.
+        return {
+            result: errorResult(403, "QI_EXTERNAL_EXPORT_DISABLED", "External TMS export is disabled. Configure the connector and use a dry-run preview."),
+        };
+    }
+    return serialisedResponse(runId, request, rows);
+}
+export const QI_EXPORT_ROUTE_GROUP = [
+    { method: "POST", pattern: "/api/quality-intelligence/runs/:id/export", handler: handleQiExport },
+];

package/dist/qualityIntelligence/figma/figmaConcurrency.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Map `items` through `worker` with at most `limit` invocations in flight at once, preserving
+ * input order in the result. `limit` is clamped to `[1, items.length]`. If any worker rejects the
+ * whole operation rejects (the snapshot builder turns a per-screen failure into a skip BEFORE it
+ * reaches here, so a rejection is a genuine fault, not a partial-render case).
+ */
+export declare const mapWithConcurrency: <T, R>(items: readonly T[], limit: number, worker: (item: T, index: number) => Promise<R>) => Promise<readonly R[]>;
+//# sourceMappingURL=figmaConcurrency.d.ts.map

package/dist/qualityIntelligence/figma/figmaConcurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figmaConcurrency.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaConcurrency.ts"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAU,CAAC,EAAE,CAAC,EAC3C,OAAO,SAAS,CAAC,EAAE,EACnB,OAAO,MAAM,EACb,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,KAC7C,OAAO,CAAC,SAAS,CAAC,EAAE,CAoBtB,CAAC"}

package/dist/qualityIntelligence/figma/figmaConcurrency.js

@@ -0,0 +1,34 @@
+// Bounded-concurrency worker pool for the Figma snapshot-build (Epic #750, Issue #759).
+//
+// A huge enterprise board has many screens to render and download. Firing every byte-download at
+// once would burst the API (inviting 429s) and the host. This runs the per-screen work through a
+// fixed, small concurrency cap — order-preserving so the assembled Snapshot is deterministic — and
+// is generic over the work it drives (no Figma specifics, no timers, no scheduler).
+/**
+ * Map `items` through `worker` with at most `limit` invocations in flight at once, preserving
+ * input order in the result. `limit` is clamped to `[1, items.length]`. If any worker rejects the
+ * whole operation rejects (the snapshot builder turns a per-screen failure into a skip BEFORE it
+ * reaches here, so a rejection is a genuine fault, not a partial-render case).
+ */
+export const mapWithConcurrency = async (items, limit, worker) => {
+    if (items.length === 0)
+        return [];
+    const safeLimit = Number.isInteger(limit) && limit >= 1 ? limit : 1;
+    const cap = Math.max(1, Math.min(safeLimit, items.length));
+    const results = new Array(items.length);
+    let next = 0;
+    const runLane = async () => {
+        for (;;) {
+            const index = next;
+            next += 1;
+            if (index >= items.length)
+                return;
+            const item = items[index];
+            if (item === undefined)
+                continue;
+            results[index] = await worker(item, index);
+        }
+    };
+    await Promise.all(Array.from({ length: cap }, () => runLane()));
+    return results;
+};

package/dist/qualityIntelligence/figma/figmaConnector.d.ts

@@ -0,0 +1,65 @@
+import type { FigmaHttpPort } from "./figmaHttpPort.js";
+import { type FigmaRetryPolicy, type FigmaRetrySleep } from "./figmaRetry.js";
+import { type FigmaNode, type ReadinessSignal } from "./figmaReadiness.js";
+import { type FigmaScopeCoverage, type ScopedPaginationLimits } from "./figmaScopedPagination.js";
+export interface FigmaConnectorConfig {
+    /**
+     * Optional config-key PAT alternate (#751 AC2). Sits between the vault and env sources in the
+     * vault > config > env precedence. It is only honoured when the connector is constructed directly
+     * with a config token; the governed production build ({@link governedSnapshotBuild}) resolves
+     * vault > env (no config token), so this field stays inert there by design.
+     */
+    readonly accessToken?: string;
+    readonly depth?: number;
+    readonly releaseMarker?: string;
+    readonly maxNodeCount?: number;
+    /**
+     * Per-deployment overrides for the deep scoped-pagination budgets (#837). Any omitted field falls
+     * back to {@link DEFAULT_SCOPED_PAGINATION_LIMITS}. Generic budgets — never tuned to a sample board.
+     */
+    readonly pagination?: Partial<ScopedPaginationLimits>;
+}
+export interface FigmaEnv {
+    readonly FIGMA_ACCESS_TOKEN?: string;
+}
+export interface FigmaConnectorDeps {
+    readonly http: FigmaHttpPort;
+    readonly env: FigmaEnv;
+    readonly config?: FigmaConnectorConfig;
+    readonly vaultToken?: string;
+    readonly retryPolicy?: FigmaRetryPolicy;
+    readonly sleep?: FigmaRetrySleep;
+}
+export interface FigmaFetchOptions {
+    readonly version?: string;
+    readonly fetchedAt?: string;
+}
+export interface FigmaProvenance {
+    readonly fileKey: string;
+    readonly nodeId: string;
+    readonly version: string | undefined;
+    readonly fetchedAt: string;
+}
+export interface FigmaScopedResult {
+    readonly nodes: FigmaNode;
+    readonly provenance: FigmaProvenance;
+    readonly readiness: ReadinessSignal;
+    /**
+     * Coverage telemetry, present only on the deep (`fetchScopedNodesDeep`) path (#837). Reports how
+     * many screens were deep-fetched / truncated and the assembled node + fetch counts, so the build
+     * can surface honest coverage instead of silently under-feeding the IR.
+     */
+    readonly coverage?: FigmaScopeCoverage;
+}
+export interface FigmaConnector {
+    /** Single shallow scoped fetch (depth cap + oversize guard). Backwards-compatible entry point. */
+    fetchScopedNodes(url: string, options?: FigmaFetchOptions): Promise<FigmaScopedResult>;
+    /**
+     * Bounded per-screen scoped-pagination fetch (#837): one shallow discovery fetch to enumerate
+     * screens, then a bounded breadth-first deepening of each screen subtree so in-screen text survives
+     * into the IR. Stays within the snapshot-build boundary; reports {@link FigmaScopeCoverage}.
+     */
+    fetchScopedNodesDeep(url: string, options?: FigmaFetchOptions): Promise<FigmaScopedResult>;
+}
+export declare const createFigmaConnector: (deps: FigmaConnectorDeps) => FigmaConnector;
+//# sourceMappingURL=figmaConnector.d.ts.map

package/dist/qualityIntelligence/figma/figmaConnector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figmaConnector.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaConnector.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACrB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAoB,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE7F,OAAO,EAIL,KAAK,kBAAkB,EAGvB,KAAK,sBAAsB,EAC5B,MAAM,4BAA4B,CAAC;AAYpC,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAIvC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAExC,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;CAClC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CACxC;AAED,MAAM,WAAW,cAAc;IAC7B,kGAAkG;IAClG,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACvF;;;;OAIG;IACH,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC5F;AAgOD,eAAO,MAAM,oBAAoB,GAAI,MAAM,kBAAkB,KAAG,cAiB/D,CAAC"}

package/dist/qualityIntelligence/figma/figmaConnector.js

@@ -0,0 +1,184 @@
+// Figma connector — scoped fetch + ready-signal resolution (Epic #750, Issue #751).
+//
+// Server-side only, read-only PAT, REST API only (no SDK, no MCP, no OAuth, no webhooks).
+// From a pasted board/section link it fetches ONLY the scoped node subtree via
+// `GET /v1/files/:key/nodes?ids=&depth=[&version=]` — never the whole-file endpoint — and
+// resolves an advisory readiness signal. Output is the raw scoped node tree (handed to the
+// IR cleaner in #752) plus token-free provenance.
+//
+// Token handling: the PAT is resolved from an injected config override or the
+// `FIGMA_ACCESS_TOKEN` env var. It is materialised into the `X-Figma-Token` header at the
+// transport boundary only; it is never logged, never returned, and never placed in any
+// error or provenance. The HTTP transport is the injectable FigmaHttpPort so a future
+// proxy/custom-CA client (#802) slots in without touching this logic.
+import { FigmaConnectorError } from "./figmaConnectorErrors.js";
+import { DEFAULT_FIGMA_RETRY_POLICY, fetchWithBackoff, realFigmaRetrySleep, } from "./figmaRetry.js";
+import { parseFigmaTarget } from "./figmaUrl.js";
+import { resolveReadiness } from "./figmaReadiness.js";
+import { classifyTokenFailure, resolveFigmaToken } from "./figmaTokenSource.js";
+import { DEFAULT_SCOPED_PAGINATION_LIMITS, paginateScopedDocument, resolveScopedPaginationLimits, } from "./figmaScopedPagination.js";
+const FIGMA_API_ORIGIN = "https://api.figma.com";
+const DEFAULT_DEPTH = 2;
+const DEFAULT_MAX_NODE_COUNT = 5000;
+const EPOCH = "1970-01-01T00:00:00.000Z";
+const DEEP_FETCH_FAIL_SOFT_RETRY_POLICY = {
+    maxRetries: 0,
+    baseDelayMs: 500,
+    maxDelayMs: 500,
+};
+const resolveToken = (deps) => resolveFigmaToken({
+    vaultToken: deps.vaultToken,
+    configToken: deps.config?.accessToken,
+    envToken: deps.env.FIGMA_ACCESS_TOKEN,
+});
+const buildScopedUrl = (fileKey, nodeId, depth, version) => {
+    const url = new URL(`${FIGMA_API_ORIGIN}/v1/files/${encodeURIComponent(fileKey)}/nodes`);
+    url.searchParams.set("ids", nodeId);
+    url.searchParams.set("depth", String(depth));
+    if (version !== undefined && version.length > 0)
+        url.searchParams.set("version", version);
+    return url.toString();
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+// Figma error bodies carry a short reason in `err` (occasionally `message`). We pass only that
+// generic string to the structural classifier so a 403 resolves to the most specific coded error
+// (expired / revoked / insufficient-scope) without ever surfacing the raw payload. The token is
+// never part of a response body, so this cannot leak it.
+const extractFigmaReason = (body) => {
+    if (!isRecord(body))
+        return undefined;
+    const reason = body.err ?? body.message;
+    return typeof reason === "string" ? reason : undefined;
+};
+const statusToError = (status, body) => classifyTokenFailure(status, extractFigmaReason(body));
+const extractDocument = (body, nodeId) => {
+    if (!isRecord(body) || !isRecord(body.nodes))
+        throw new FigmaConnectorError("FIGMA_INTERNAL");
+    const entry = body.nodes[nodeId];
+    if (entry === undefined)
+        throw new FigmaConnectorError("FIGMA_NOT_FOUND");
+    if (!isRecord(entry) || !isRecord(entry.document)) {
+        throw new FigmaConnectorError("FIGMA_INTERNAL");
+    }
+    return entry.document;
+};
+const countNodes = (node) => {
+    let total = 1;
+    for (const child of Array.isArray(node.children) ? node.children : [])
+        total += countNodes(child);
+    return total;
+};
+const guardScopeSize = (node, maxNodeCount) => {
+    if (countNodes(node) > maxNodeCount)
+        throw new FigmaConnectorError("FIGMA_OVERSIZED_SCOPE");
+};
+// A per-node deep fetch that hits one of these codes means the WHOLE build is compromised (auth lost,
+// rate-limit exhausted, egress/TLS broken) — it must abort, not silently degrade a branch to shallow.
+// Any other per-node failure (a transient 5xx or a vanished sub-node) is soft: that branch keeps its
+// shallow content and the build proceeds with a truncation-aware coverage report.
+// The proxy family is covered in full — symmetric with RENDER_EGRESS_ABORT_CODES in
+// figmaSnapshotBuilder.ts — so a forward-proxy that requires auth (FIGMA_PROXY_AUTH_REQUIRED) or
+// denies the request by policy (FIGMA_PROXY_BLOCKED_BY_POLICY) on a per-screen fetch aborts the build
+// instead of silently degrading that screen to shallow content.
+// Rate-limit exhaustion is deliberately NOT in this hard-abort set. The discovery fetch still aborts
+// on FIGMA_RATE_LIMITED before this fetcher is constructed, but a single per-screen deepening fetch
+// that exhausts retries can safely degrade to the already-fetched shallow screen while coverage marks
+// it truncated. That keeps large boards reviewable instead of failing the whole snapshot after one
+// expensive branch hits Figma's cost-based limit.
+const DEEP_FETCH_ABORT_CODES = new Set([
+    "FIGMA_TOKEN_MISSING",
+    "FIGMA_TOKEN_INVALID",
+    "FIGMA_TOKEN_EXPIRED",
+    "FIGMA_TOKEN_REVOKED",
+    "FIGMA_INSUFFICIENT_SCOPE",
+    "FIGMA_CONSENT_REQUIRED",
+    "FIGMA_PROXY_EGRESS_FAILED",
+    "FIGMA_PROXY_UNREACHABLE",
+    "FIGMA_PROXY_AUTH_REQUIRED",
+    "FIGMA_PROXY_BLOCKED_BY_POLICY",
+    "FIGMA_TLS_CA_FAILURE",
+]);
+// One scoped `nodes?ids=&depth=` fetch (with 429 backoff), returning the raw document. No oversize
+// guard here — the shallow path applies it; the deep path is bounded by the pagination budgets. The
+// token flows into the header only.
+const fetchDocumentAt = async (rt, token, fileKey, nodeId, fetchDepth, version, retryPolicy = rt.retryPolicy) => {
+    const requestUrl = buildScopedUrl(fileKey, nodeId, fetchDepth, version);
+    const response = await fetchWithBackoff(() => rt.deps.http({ url: requestUrl, headers: { "X-Figma-Token": token } }), retryPolicy, rt.sleep);
+    if (response.status < 200 || response.status >= 300) {
+        throw statusToError(response.status, response.json);
+    }
+    return extractDocument(response.json, nodeId);
+};
+const provenanceFor = (target, options) => ({
+    fileKey: target.fileKey,
+    nodeId: target.nodeId,
+    version: options.version,
+    fetchedAt: options.fetchedAt ?? EPOCH,
+});
+// RawFigmaNode → FigmaNode is a safe widening for the readiness reader (which tolerates absent fields).
+const readinessFor = (rt, document, version) => resolveReadiness(document, { version, releaseMarker: rt.releaseMarker });
+const resolveTarget = (url) => {
+    const target = parseFigmaTarget(url);
+    if (target === null)
+        throw new FigmaConnectorError("FIGMA_MALFORMED_URL");
+    return target;
+};
+const doFetchScopedNodes = async (rt, url, options) => {
+    const token = resolveToken(rt.deps);
+    const target = resolveTarget(url);
+    const document = await fetchDocumentAt(rt, token, target.fileKey, target.nodeId, rt.depth, options.version);
+    guardScopeSize(document, rt.maxNodeCount);
+    return {
+        nodes: document,
+        provenance: provenanceFor(target, options),
+        readiness: readinessFor(rt, document, options.version),
+    };
+};
+// The per-screen deepening fetcher: a hard (auth/rate/egress) code aborts the build; any other
+// per-node failure degrades that branch to its shallow content (recorded as truncation in coverage).
+const makeDeepFetcher = (rt, token, target, version) => {
+    return async (nodeId) => {
+        try {
+            return await fetchDocumentAt(rt, token, target.fileKey, nodeId, rt.paginationLimits.pageDepth, version, DEEP_FETCH_FAIL_SOFT_RETRY_POLICY);
+        }
+        catch (err) {
+            if (err instanceof FigmaConnectorError && DEEP_FETCH_ABORT_CODES.has(err.code))
+                throw err;
+            return undefined;
+        }
+    };
+};
+const doFetchScopedNodesDeep = async (rt, url, options) => {
+    const token = resolveToken(rt.deps);
+    const target = resolveTarget(url);
+    // One shallow discovery fetch enumerates the screens (and resolves advisory readiness). No oversize
+    // guard: a wide canvas is exactly what the deep path paginates. This is the FIRST, auth-establishing
+    // egress; a hard failure here aborts before any per-screen fetch.
+    const discovery = await fetchDocumentAt(rt, token, target.fileKey, target.nodeId, rt.depth, options.version);
+    const fetchNode = makeDeepFetcher(rt, token, target, options.version);
+    const { document, coverage } = await paginateScopedDocument(discovery, fetchNode, rt.paginationLimits);
+    return {
+        nodes: document,
+        provenance: provenanceFor(target, options),
+        readiness: readinessFor(rt, document, options.version),
+        coverage,
+    };
+};
+export const createFigmaConnector = (deps) => {
+    const rt = {
+        deps,
+        depth: deps.config?.depth ?? DEFAULT_DEPTH,
+        releaseMarker: deps.config?.releaseMarker,
+        maxNodeCount: deps.config?.maxNodeCount ?? DEFAULT_MAX_NODE_COUNT,
+        retryPolicy: deps.retryPolicy ?? DEFAULT_FIGMA_RETRY_POLICY,
+        sleep: deps.sleep ?? realFigmaRetrySleep,
+        paginationLimits: resolveScopedPaginationLimits({
+            ...DEFAULT_SCOPED_PAGINATION_LIMITS,
+            ...deps.config?.pagination,
+        }),
+    };
+    return {
+        fetchScopedNodes: (url, options = {}) => doFetchScopedNodes(rt, url, options),
+        fetchScopedNodesDeep: (url, options = {}) => doFetchScopedNodesDeep(rt, url, options),
+    };
+};