@oscharko-dev/keiko-server 0.2.0

package/dist/qualityIntelligence/figmaSnapshotAdapter.js

@@ -0,0 +1,219 @@
+// figmaSnapshotAdapter.ts — Figma-snapshot source seam for QI ingestion (Epic #750, Issue #754).
+//
+// Two server-tier seams the pure-domain ingestion cannot own:
+//
+//   1. The snapshot LOADER — reads the immutable Figma Snapshot evidence record for a runId through
+//      the existing keiko-evidence store (`createNodeFigmaSnapshotStore(evidenceDir).load`). It
+//      reads ONLY the stored snapshot and never contacts Figma. Returns `undefined` when no
+//      evidence dir is configured, so the ingestion layer rejects the source with a coded error.
+//
+//   2. The capability-routed VISION hint provider — consults `resolveQiMultimodalSelection` (#810)
+//      to decide whether a multimodal model is available; when one is, it MAY call an injected
+//      server-owned vision call to recover image-derived semantics from the STORED render side-file,
+//      returning them as additive hints. There is
+//      NO hard-coded model id. On "unavailable", a thrown call, or a non-array/garbage result the
+//      provider returns `[]`, so the source degrades silently to the deterministic IR-only baseline.
+//      The call goes through deps.modelPortFactory / Model Gateway only — no provider SDK and no
+//      Figma egress after snapshot build.
+import { Buffer } from "node:buffer";
+import { createNodeFigmaSnapshotStore, } from "@oscharko-dev/keiko-evidence";
+import { resolveQiMultimodalSelection } from "./modelSelection.js";
+/**
+ * Build the snapshot loader. Returns `undefined` when `deps.evidenceDir` is not configured so the
+ * ingestion layer maps an attempted figma-snapshot source to QI_FIGMA_SNAPSHOT_UNAVAILABLE.
+ */
+export function makeFigmaSnapshotLoader(deps, options) {
+    const evidenceDir = deps.evidenceDir;
+    if (evidenceDir === undefined || evidenceDir.length === 0)
+        return undefined;
+    const store = createNodeFigmaSnapshotStore(evidenceDir);
+    const resolveLatest = options?.resolveLatestByScope === true;
+    return (snapshotRunId) => {
+        try {
+            const pinned = store.load(snapshotRunId);
+            if (pinned === undefined || !resolveLatest)
+                return pinned;
+            const entries = store.listByScope(pinned.provenance.fileKey, pinned.provenance.nodeId);
+            const newest = entries[0];
+            if (newest === undefined ||
+                newest.runId === pinned.runId ||
+                newest.integrityHash === pinned.integrityHash) {
+                return pinned;
+            }
+            // Fall back to the pinned record when the newest record fails to load — drift detection
+            // must degrade to "fresh", never crash the re-check.
+            return store.load(newest.runId) ?? pinned;
+        }
+        catch {
+            // A malformed / unreadable record is treated as "not found"; the caller emits a coded error.
+            return undefined;
+        }
+    };
+}
+const MAX_VISION_IMAGE_BYTES = 4 * 1024 * 1024;
+const MAX_VISION_BASELINE_BYTES = 12_000;
+const MAX_VISION_HINTS = 24;
+const FIGMA_VISION_TIMEOUT_MS = 30_000;
+const encoder = new TextEncoder();
+function utf8ByteLength(value) {
+    return encoder.encode(value).length;
+}
+function truncateUtf8(value, maxBytes) {
+    if (utf8ByteLength(value) <= maxBytes)
+        return value;
+    let out = "";
+    let bytes = 0;
+    for (const cp of value) {
+        const cpBytes = utf8ByteLength(cp);
+        if (bytes + cpBytes > maxBytes)
+            break;
+        out += cp;
+        bytes += cpBytes;
+    }
+    return out;
+}
+function redactedString(deps, value) {
+    const redacted = deps.redactor(value);
+    return typeof redacted === "string" ? redacted : "";
+}
+function sanitiseCallResult(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((entry) => typeof entry === "string");
+}
+function stripJsonCodeFence(raw) {
+    const match = /^```(?:json)?\s*([\s\S]*?)\s*```$/iu.exec(raw);
+    return match?.[1]?.trim() ?? raw;
+}
+function parseHintResponse(raw) {
+    const trimmed = stripJsonCodeFence(raw.trim());
+    if (trimmed.length === 0)
+        return [];
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed))
+            return sanitiseCallResult(parsed).slice(0, MAX_VISION_HINTS);
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            Array.isArray(parsed.hints)) {
+            return sanitiseCallResult(parsed.hints).slice(0, MAX_VISION_HINTS);
+        }
+    }
+    catch {
+        return [];
+    }
+    return [];
+}
+function visionUserText(request, baselineText) {
+    return (`Screen id: ${request.screenId}\n` +
+        "Structural baseline, already authoritative:\n" +
+        `${baselineText}\n\n` +
+        "Return only visual/semantic hints that are absent from the baseline.");
+}
+function buildVisionRequest(request, modelId, dataUrl, baselineText, structuredOutput) {
+    const userText = visionUserText(request, baselineText);
+    return {
+        modelId,
+        messages: [
+            {
+                role: "system",
+                content: "You are an additive UI test-generation vision pass. Use the image only to recover " +
+                    "semantics missing from the structural baseline. Do not contradict, replace, or restate " +
+                    "the baseline. Return concise JSON: an array of strings.",
+            },
+            {
+                role: "user",
+                content: userText,
+                contentParts: [
+                    { type: "text", text: userText },
+                    { type: "image_url", image_url: { url: dataUrl } },
+                ],
+            },
+        ],
+        ...(structuredOutput
+            ? {
+                responseFormat: {
+                    type: "json_schema",
+                    schema: {
+                        type: "array",
+                        items: { type: "string" },
+                        maxItems: MAX_VISION_HINTS,
+                    },
+                },
+            }
+            : {}),
+    };
+}
+function createVisionAbortSignal() {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+        controller.abort();
+    }, FIGMA_VISION_TIMEOUT_MS);
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            clearTimeout(timeout);
+        },
+    };
+}
+function makeGatewayFigmaVisionCall(deps, options) {
+    const evidenceDir = deps.evidenceDir;
+    if (evidenceDir === undefined || evidenceDir.length === 0)
+        return undefined;
+    const store = createNodeFigmaSnapshotStore(evidenceDir);
+    // Capture the structured-output flag once at closure-creation, not per screen. The multimodal
+    // selection is stable for the lifetime of the provider (deps is immutable after server init),
+    // so re-calling resolveQiMultimodalSelection on every vision call is redundant work.
+    const closureSelection = resolveQiMultimodalSelection(deps);
+    const closureModelSelection = closureSelection.kind === "model" ? closureSelection : undefined;
+    return async (request, modelId) => {
+        if (request.image.byteLength > MAX_VISION_IMAGE_BYTES)
+            return [];
+        const model = deps.modelPortFactory(modelId);
+        if (model === undefined)
+            return [];
+        const image = store.loadImage(request.snapshotRunId, request.image);
+        if (image.byteLength > MAX_VISION_IMAGE_BYTES)
+            return [];
+        const dataUrl = `data:${image.mimeType};base64,${Buffer.from(image.bytes).toString("base64")}`;
+        const baselineText = truncateUtf8(redactedString(deps, request.baselineText), MAX_VISION_BASELINE_BYTES);
+        const structuredOutput = closureModelSelection?.modelId === modelId &&
+            closureModelSelection.capability.supportsResponseFormat === true;
+        const gatewayRequest = buildVisionRequest(request, modelId, dataUrl, baselineText, structuredOutput);
+        const abort = createVisionAbortSignal();
+        try {
+            options.onGatewayCallAttempt?.();
+            const response = await model.call(gatewayRequest, abort.signal);
+            return parseHintResponse(redactedString(deps, response.content));
+        }
+        finally {
+            abort.cleanup();
+        }
+    };
+}
+/**
+ * Build a capability-routed vision hint provider. When no multimodal capability is configured (or no
+ * `visionCall` is injected), every request returns `[]` — the deterministic IR-only baseline path.
+ * When a multimodal model IS available, the provider routes the call through it; any thrown error or
+ * garbage result is swallowed to `[]` so a misbehaving model can never break the run or override the
+ * structural baseline. No model id is hard-coded — selection is via `resolveQiMultimodalSelection`.
+ */
+export function makeFigmaVisionHintProvider(deps, visionCall, options = {}) {
+    const resolvedVisionCall = visionCall ?? makeGatewayFigmaVisionCall(deps, options);
+    const selection = resolveQiMultimodalSelection(deps);
+    if (selection.kind === "unavailable" || resolvedVisionCall === undefined) {
+        return () => [];
+    }
+    const { modelId } = selection;
+    return (request) => {
+        try {
+            const result = resolvedVisionCall(request, modelId);
+            return typeof result.then === "function"
+                ? Promise.resolve(result).then(sanitiseCallResult, () => [])
+                : sanitiseCallResult(result);
+        }
+        catch {
+            return [];
+        }
+    };
+}

package/dist/qualityIntelligence/figmaSnapshotOrchestration.d.ts

@@ -0,0 +1,64 @@
+import { createFigmaTokenStore, type FigmaConnectorMetrics, type FigmaHttpPort, type FigmaKeychainAccess, type FigmaProvenance, type FigmaRenderPort, type FigmaScopeCoverage, type FigmaScopeRef, type FigmaSnapshot, type ScopedPaginationLimits } from "./figma/index.js";
+import { QualityIntelligenceFigma } from "@oscharko-dev/keiko-quality-intelligence";
+import type { EnvSource } from "@oscharko-dev/keiko-security";
+import type { OutboundHttpEgressConfig } from "@oscharko-dev/keiko-model-gateway/internal/http";
+type ScreenIrResult = QualityIntelligenceFigma.ScreenIrResult;
+export interface GovernedSnapshotDeps {
+    readonly evidenceDir: string;
+    readonly env: EnvSource;
+    /** Wall-clock for consent + audit timestamps; injected so tests stay deterministic. */
+    readonly now: string;
+    /** When true, record the read-only-scope acknowledgement before the fetch (operator consent). */
+    readonly acknowledgeReadOnly?: boolean;
+    /**
+     * Route orchestration sets this true so `snapshot`/`resnapshot` success is audited only after the
+     * evidence record has been durably persisted and reloaded.
+     */
+    readonly deferSuccessAudit?: boolean;
+    /** Deep scoped-pagination overrides (#837). */
+    readonly pagination?: Partial<ScopedPaginationLimits>;
+    /** Optional pinned Figma file version. When present it is sent to the scoped REST fetch. */
+    readonly version?: string | undefined;
+    /** Optional Keiko config PAT alternate (#751). Vault remains higher precedence. */
+    readonly configToken?: string | undefined;
+    /** Shared enterprise egress settings for Figma API + render downloads (#802). */
+    readonly egress?: OutboundHttpEgressConfig | undefined;
+    /**
+     * Creation-time overrides forwarded to the default HTTP and render ports when no explicit
+     * httpPort/renderPort is injected. Currently only `timeoutMs` (maps to
+     * KEIKO_FIGMA_REQUEST_TIMEOUT_MS). Ignored when httpPort/renderPort are injected directly
+     * (route tests supply fakes that honour their own timeouts).
+     */
+    readonly portOptions?: {
+        readonly timeoutMs?: number;
+    };
+    readonly httpPort?: FigmaHttpPort;
+    readonly renderPort?: FigmaRenderPort;
+    readonly keychainAccess?: FigmaKeychainAccess;
+}
+export interface GovernedSnapshotResult {
+    readonly provenance: FigmaProvenance;
+    readonly coverage: FigmaScopeCoverage | undefined;
+    readonly snapshot: FigmaSnapshot;
+    readonly ir: ScreenIrResult;
+    readonly metrics: FigmaConnectorMetrics;
+    readonly scopeRef: FigmaScopeRef;
+}
+/**
+ * Read the encrypted-at-rest vault PAT (#758), or `undefined` when no vault token is stored or the
+ * vault key cannot be resolved. Highest precedence in {@link resolveFigmaToken}. Never throws — a
+ * missing/unreadable vault degrades to the config/env token rather than failing the build.
+ */
+export declare const readFigmaVaultToken: (deps: GovernedSnapshotDeps) => string | undefined;
+/** Build the encrypted token store for operator rotation/revocation (#758). */
+export declare const figmaTokenStoreFor: (deps: Pick<GovernedSnapshotDeps, "env" | "evidenceDir" | "keychainAccess">) => ReturnType<typeof createFigmaTokenStore>;
+/**
+ * Run the governed snapshot-build for `boardLink`: resolve the vault>config>env PAT, gate on recorded
+ * read-only consent BEFORE any Figma egress, perform the deep scoped-pagination fetch + render, and
+ * audit + compute metrics. Throws a coded {@link FigmaConnectorError} on any failure (the route maps
+ * it to a status) — a fetch failure is audited before it propagates, a render failure inside the
+ * observed wrapper likewise. `isResnapshot` only changes the audited action label.
+ */
+export declare const governedSnapshotBuild: (boardLink: string, deps: GovernedSnapshotDeps, isResnapshot?: boolean) => Promise<GovernedSnapshotResult>;
+export {};
+//# sourceMappingURL=figmaSnapshotOrchestration.d.ts.map

package/dist/qualityIntelligence/figmaSnapshotOrchestration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figmaSnapshotOrchestration.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/figmaSnapshotOrchestration.ts"],"names":[],"mappings":"AAeA,OAAO,EAOL,qBAAqB,EAUrB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAElB,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AACpF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iDAAiD,CAAC;AAKhG,KAAK,cAAc,GAAG,wBAAwB,CAAC,cAAc,CAAC;AAE9D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,uFAAuF;IACvF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iGAAiG;IACjG,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC,+CAA+C;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACtD,4FAA4F;IAC5F,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,mFAAmF;IACnF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,wBAAwB,GAAG,SAAS,CAAC;IACvD;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAEvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;IACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,mBAAmB,CAAC;CAC/C;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;CAClC;AAMD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,oBAAoB,KAAG,MAAM,GAAG,SAWzE,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,kBAAkB,GAC7B,MAAM,IAAI,CAAC,oBAAoB,EAAE,KAAK,GAAG,aAAa,GAAG,gBAAgB,CAAC,KACzE,UAAU,CAAC,OAAO,qBAAqB,CAOzC,CAAC;AAsJF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GAChC,WAAW,MAAM,EACjB,MAAM,oBAAoB,EAC1B,sBAAoB,KACnB,OAAO,CAAC,sBAAsB,CA+ChC,CAAC"}

package/dist/qualityIntelligence/figmaSnapshotOrchestration.js

@@ -0,0 +1,203 @@
+// Governed Figma snapshot-build orchestration (Epic #750, Issues #758, #760, #759).
+//
+// The snapshot route was a thin happy-path that bypassed the governance machinery the epic's children
+// built and unit-tested: the encrypted PAT vault (#758), the read-only-scope consent gate + audit
+// ledger + operational metrics (#760). This module wires them into ONE governed build so every
+// production snapshot is consent-gated, audited (success AND coded failure), metric-bearing, and
+// resolves the PAT with the correct vault > config > env precedence — without changing any connector,
+// builder, or store behaviour. Figma is contacted ONLY inside the bounded build (the boundary holds).
+//
+// Token handling stays server-side: the vault token (when present) flows into the connector's
+// X-Figma-Token header only; it never reaches a return value, log, audit entry, metric, or snapshot.
+// The vault degrades gracefully — an unconfigured vault yields `undefined` and the build falls back to
+// the config/env token, so the existing env-auth path keeps working unchanged.
+import { join } from "node:path";
+import { appendFigmaConnectorAudit, assertReadOnlyConsent, buildFigmaSnapshot, createDefaultFigmaHttpPort, createDefaultFigmaRenderPort, createFigmaConnector, createFigmaTokenStore, deriveFigmaScopeRef, FigmaConnectorError, loadFigmaConnectorAudit, observeFigmaSnapshot, parseFigmaTarget, recordReadOnlyConsent, resolveFigmaToken, resolveScopedPaginationLimits, resolveFigmaVaultKey, } from "./figma/index.js";
+import { QualityIntelligenceFigma } from "@oscharko-dev/keiko-quality-intelligence";
+const FIGMA_VAULT_SUBDIR = "figma";
+const FIGMA_TOKEN_VAULT_FILE = "figma-token.vault";
+const tokenVaultDir = (evidenceDir) => join(evidenceDir, FIGMA_VAULT_SUBDIR);
+const tokenVaultPath = (evidenceDir) => join(tokenVaultDir(evidenceDir), FIGMA_TOKEN_VAULT_FILE);
+/**
+ * Read the encrypted-at-rest vault PAT (#758), or `undefined` when no vault token is stored or the
+ * vault key cannot be resolved. Highest precedence in {@link resolveFigmaToken}. Never throws — a
+ * missing/unreadable vault degrades to the config/env token rather than failing the build.
+ */
+export const readFigmaVaultToken = (deps) => {
+    try {
+        const { key } = resolveFigmaVaultKey(deps.env, tokenVaultDir(deps.evidenceDir), deps.keychainAccess);
+        return createFigmaTokenStore({ key, storePath: tokenVaultPath(deps.evidenceDir) }).read();
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Build the encrypted token store for operator rotation/revocation (#758). */
+export const figmaTokenStoreFor = (deps) => {
+    const { key } = resolveFigmaVaultKey(deps.env, tokenVaultDir(deps.evidenceDir), deps.keychainAccess);
+    return createFigmaTokenStore({ key, storePath: tokenVaultPath(deps.evidenceDir) });
+};
+// Count deterministic a11y findings (#812) on the cleaned IR — the metric the #760 audit surfaces.
+// Passing checks, generic expectations, and coverage notices are excluded: they record test cases or
+// unverified coverage, not confirmed a11y findings.
+const a11yFindingsCount = (ir) => {
+    let count = 0;
+    for (const items of QualityIntelligenceFigma.deriveA11yTestItemsByScreen(ir.screens).values()) {
+        for (const item of items)
+            if (item.category === "a11y" && item.outcome === "fail")
+                count += 1;
+    }
+    return count;
+};
+const hasSuccessfulConnectAudit = (scopeRef, evidenceDir) => loadFigmaConnectorAudit(scopeRef, evidenceDir)?.auditLog.some((entry) => entry.action === "connect" && entry.outcome === "ok") === true;
+// Record (when acknowledged) and assert read-only-scope consent BEFORE any token materialisation or
+// egress — an unconsented scope never reaches Figma (#760). Throws FIGMA_CONSENT_REQUIRED if missing.
+const gateConsent = (deps, scopeRef) => {
+    if (deps.acknowledgeReadOnly === true) {
+        // The first acknowledgement IS the operator's "connect" gesture. Guard on the audit ledger, not
+        // only on consent existence: if consent was written but the audit append failed, an acknowledged
+        // retry must repair the missing connect marker rather than suppressing it forever.
+        const needsConnectAudit = !hasSuccessfulConnectAudit(scopeRef, deps.evidenceDir);
+        recordReadOnlyConsent({
+            scopeRef,
+            evidenceDir: deps.evidenceDir,
+            acknowledgedBy: "operator",
+            now: deps.now,
+        });
+        if (needsConnectAudit) {
+            appendFigmaConnectorAudit({
+                scopeRef,
+                evidenceDir: deps.evidenceDir,
+                action: "connect",
+                outcome: "ok",
+                now: deps.now,
+            });
+        }
+    }
+    assertReadOnlyConsent(scopeRef, deps.evidenceDir);
+};
+function snapshotPorts(deps) {
+    return {
+        httpPort: deps.httpPort ?? createDefaultFigmaHttpPort(deps.egress, undefined, deps.portOptions),
+        renderPort: deps.renderPort ?? createDefaultFigmaRenderPort(deps.egress, undefined, deps.portOptions),
+    };
+}
+function resolveBuildToken(deps, vaultToken) {
+    return resolveFigmaToken({
+        vaultToken,
+        configToken: deps.configToken,
+        envToken: deps.env.FIGMA_ACCESS_TOKEN,
+    });
+}
+function createGovernedConnector(deps, httpPort, vaultToken) {
+    return createFigmaConnector({
+        http: httpPort,
+        env: deps.env,
+        ...(vaultToken !== undefined ? { vaultToken } : {}),
+        config: {
+            ...(deps.configToken !== undefined ? { accessToken: deps.configToken } : {}),
+            pagination: deps.pagination ?? {},
+        },
+    });
+}
+function auditedResolveBuildToken(deps, vaultToken, scopeRef, action) {
+    try {
+        return resolveBuildToken(deps, vaultToken);
+    }
+    catch (error) {
+        appendFigmaConnectorAudit({
+            scopeRef,
+            evidenceDir: deps.evidenceDir,
+            action,
+            outcome: "error",
+            errorCode: error instanceof FigmaConnectorError ? error.code : "FIGMA_INTERNAL",
+            now: deps.now,
+        });
+        throw error;
+    }
+}
+// Deep scoped fetch with audit-on-failure: a fetch failure is recorded as a coded audit entry before
+// it propagates, so the audit ledger captures the action even when the egress never produced a build.
+const auditedDeepFetch = async (connector, boardLink, deps, scopeRef, action) => {
+    try {
+        return await connector.fetchScopedNodesDeep(boardLink, {
+            fetchedAt: deps.now,
+            ...(deps.version !== undefined ? { version: deps.version } : {}),
+        });
+    }
+    catch (error) {
+        appendFigmaConnectorAudit({
+            scopeRef,
+            evidenceDir: deps.evidenceDir,
+            action,
+            outcome: "error",
+            errorCode: error instanceof FigmaConnectorError ? error.code : "FIGMA_INTERNAL",
+            now: deps.now,
+        });
+        throw error;
+    }
+};
+const assertReadyForSnapshot = (scoped, deps, scopeRef, action) => {
+    if (scoped.readiness.ready)
+        return;
+    appendFigmaConnectorAudit({
+        scopeRef,
+        evidenceDir: deps.evidenceDir,
+        action,
+        outcome: "error",
+        errorCode: "FIGMA_NOT_READY",
+        now: deps.now,
+    });
+    throw new FigmaConnectorError("FIGMA_NOT_READY");
+};
+/**
+ * Run the governed snapshot-build for `boardLink`: resolve the vault>config>env PAT, gate on recorded
+ * read-only consent BEFORE any Figma egress, perform the deep scoped-pagination fetch + render, and
+ * audit + compute metrics. Throws a coded {@link FigmaConnectorError} on any failure (the route maps
+ * it to a status) — a fetch failure is audited before it propagates, a render failure inside the
+ * observed wrapper likewise. `isResnapshot` only changes the audited action label.
+ */
+export const governedSnapshotBuild = async (boardLink, deps, isResnapshot = false) => {
+    const target = parseFigmaTarget(boardLink);
+    if (target === null)
+        throw new FigmaConnectorError("FIGMA_MALFORMED_URL");
+    const scopeRef = deriveFigmaScopeRef(target.fileKey, target.nodeId);
+    const { httpPort, renderPort } = snapshotPorts(deps);
+    const action = isResnapshot ? "resnapshot" : "snapshot";
+    gateConsent(deps, scopeRef);
+    const vaultToken = readFigmaVaultToken(deps);
+    // Render-token (vault > config > env). Throws FIGMA_TOKEN_MISSING when nothing is configured.
+    const token = auditedResolveBuildToken(deps, vaultToken, scopeRef, action);
+    const connector = createGovernedConnector(deps, httpPort, vaultToken);
+    const scoped = await auditedDeepFetch(connector, boardLink, deps, scopeRef, action);
+    assertReadyForSnapshot(scoped, deps, scopeRef, action);
+    const ir = QualityIntelligenceFigma.cleanScopedNodesToScreenIr(scoped.nodes);
+    const renderLimits = resolveScopedPaginationLimits(deps.pagination);
+    const observed = await observeFigmaSnapshot({
+        ctx: { evidenceDir: deps.evidenceDir, now: deps.now },
+        provenance: scoped.provenance,
+        ir,
+        // The snapshot-build itself is fully deterministic (no model) — the model-augmentation share is
+        // the QI test-gen concern (#754). Here it is 0/0 → a 0 model-augmented share (100% deterministic).
+        augmentation: { deterministic: 0, modelAugmented: 0 },
+        extras: { a11yFindings: a11yFindingsCount(ir) },
+        isResnapshot,
+        auditSuccess: deps.deferSuccessAudit !== true,
+        run: () => buildFigmaSnapshot({
+            ir,
+            provenance: scoped.provenance,
+            token,
+            imagesPort: httpPort,
+            renderPort,
+            maxScreensRendered: renderLimits.maxScreensDeep,
+        }),
+    });
+    return {
+        provenance: scoped.provenance,
+        coverage: scoped.coverage,
+        snapshot: observed.snapshot,
+        ir,
+        metrics: observed.metrics,
+        scopeRef,
+    };
+};

package/dist/qualityIntelligence/figmaSnapshotRoutes.d.ts

@@ -0,0 +1,112 @@
+import { type HandlerOutcome, type RouteContext, type RouteResult } from "../routes.js";
+import { type UiHandlerDeps } from "../deps.js";
+import type { EnvSource } from "@oscharko-dev/keiko-security";
+import { type FigmaConnectorMetrics, type FigmaScopeCoverage, type ScopedPaginationLimits } from "./figma/index.js";
+export interface FigmaSnapshotSummary {
+    readonly runId: string;
+    /** Mutable display name stored outside the immutable evidence record. */
+    readonly displayName?: string;
+    /** Mutable management metadata stored outside the immutable evidence record. */
+    readonly management: FigmaSnapshotManagementSummary;
+    readonly fileKey: string;
+    readonly nodeId: string;
+    readonly version: string | undefined;
+    readonly fetchedAt: string;
+    /** Total screens included in the snapshot. */
+    readonly screenCount: number;
+    /** Screens that could not be rendered (partial build). */
+    readonly skippedCount: number;
+    /**
+     * Human-readable reduction hint, e.g. "1 screen from 1 Figma node" or
+     * "3 screens from 1 section (2 skipped)".
+     */
+    readonly reductionHint: string;
+    /** Skipped/non-rendered screens that still carry persisted structural Screen-IR JSON. */
+    readonly structuralOnlyCount: number;
+    /** Integrity hash over the snapshot content — deterministic for drift detection (#735). */
+    readonly integrityHash: string;
+    /**
+     * Deep-fetch coverage telemetry (#837) — present on a freshly-built snapshot (POST response).
+     * Lets the UI honestly report how much of a huge instance-heavy board was deep-fetched vs
+     * truncated by the bounded per-screen budgets. Build-time only; never persisted in the snapshot.
+     */
+    readonly coverage?: FigmaScopeCoverage;
+    /**
+     * Operational metrics (#760) — present on POST and reloaded GET summaries: reduction
+     * ratio, screen/render counts, design-token count, navigation-graph size (screens + transitions),
+     * a11y-finding count, and the deterministic-vs-model augmentation share. All NUMBERS — never any
+     * board content, screen name, token, or board id.
+     */
+    readonly metrics?: FigmaConnectorMetrics;
+    /**
+     * Per-screen summary for the UI gallery. IR display names + image metadata only. The client loads
+     * the token-free PNG side-file through /api/figma/snapshots/:runId/screens/:screenIndex/image.
+     */
+    readonly screens: readonly FigmaScreenSummary[];
+    /**
+     * Screen-IR summaries for detected screens that have JSON evidence but no rendered PNG side-file.
+     * These are selectable as QI sources, but the browser cannot request an image for them.
+     */
+    readonly structuralScreens: readonly FigmaStructuralScreenSummary[];
+}
+export interface FigmaSnapshotManagementSummary {
+    readonly displayName?: string;
+    readonly updatedAt?: string;
+}
+export interface FigmaScreenSummary {
+    readonly screenId: string;
+    /** Display name derived from the IR (ir.name). */
+    readonly name: string;
+    /** A brief structural description (field count, control count) for the gallery card. */
+    readonly irSummary: string;
+    /** Relative path of the side-file (informational). */
+    readonly imageRelativePath: string;
+    /** sha256 of the rendered PNG. */
+    readonly imageSha256: string;
+    /** Byte size of the rendered PNG. */
+    readonly imageByteLength: number;
+}
+export interface FigmaStructuralScreenSummary {
+    readonly screenId: string;
+    /** Display name derived from the IR (ir.name). */
+    readonly name: string;
+    /** A brief structural description (field count, control count) for the gallery card. */
+    readonly irSummary: string;
+    /** Why no rendered PNG side-file exists for this screen. */
+    readonly reason: string;
+}
+export interface FigmaSnapshotListEntry {
+    readonly runId: string;
+    readonly displayName?: string;
+    readonly management: FigmaSnapshotManagementSummary;
+    readonly fileKey: string;
+    readonly nodeId: string;
+    readonly version: string | undefined;
+    readonly fetchedAt: string;
+    readonly screenCount: number;
+    readonly skippedCount: number;
+    readonly structuralOnlyCount: number;
+    readonly reductionHint: string;
+    readonly integrityHash: string;
+}
+export interface FigmaSnapshotListResponse {
+    readonly snapshots: readonly FigmaSnapshotListEntry[];
+}
+export declare function figmaPaginationFromEnv(env: EnvSource): ScopedPaginationLimits;
+interface CoalescedBuildEntry {
+    readonly promise: Promise<RouteResult>;
+}
+/** Injectable for tests — returns the module-level map by default. */
+export declare function makeInFlightMap(): Map<string, CoalescedBuildEntry>;
+/** Reset the module-level coalescing map. Used by tests to ensure isolation. */
+export declare function resetInFlightMap(): void;
+export declare function handleFigmaTriggerSnapshot(ctx: RouteContext, deps: UiHandlerDeps, inFlight?: Map<string, CoalescedBuildEntry>): Promise<RouteResult>;
+export declare function handleFigmaRevokeToken(ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
+export declare function handleFigmaListSnapshots(ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
+export declare function handleFigmaLoadSnapshot(ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
+export declare function handleFigmaUpdateSnapshotMetadata(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleFigmaDeleteSnapshot(ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
+export declare function handleFigmaInspectSnapshotScreenJson(ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
+export declare function handleFigmaLoadSnapshotImage(ctx: RouteContext, deps: UiHandlerDeps): HandlerOutcome;
+export {};
+//# sourceMappingURL=figmaSnapshotRoutes.d.ts.map

package/dist/qualityIntelligence/figmaSnapshotRoutes.d.ts.map

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