@oscharko-dev/keiko-server 0.2.0

package/dist/qualityIntelligence/figma/figmaTokenStore.js

@@ -0,0 +1,156 @@
+// Figma PAT vault — encrypted-at-rest storage for the read-only Personal Access Token
+// (Epic #750, Issue #758).
+//
+// The PAT is a single, server-side, READ-ONLY token. This module seals it at rest with the
+// shared AES-256-GCM secretbox primitive (@oscharko-dev/keiko-security) — the same cipher that
+// protects the MemoriaViva memory vault — and never writes plaintext to disk. The plaintext token
+// NEVER appears in an error message, log line, return value other than read(), or persisted
+// artifact: only the `kv1.` sealed envelope touches the filesystem.
+//
+// Lifecycle for a non-refreshable PAT (a PAT cannot be refreshed):
+//   - store(token)  rotation-by-replacement — overwrites the single sealed entry in place.
+//   - read()        decrypts the stored entry, or undefined when none exists.
+//   - revoke()      operator removal — deletes the stored entry.
+//
+// Key precedence mirrors the memory-vault seam (resolveVaultKey), namespaced so it never collides
+// with the memory key:
+//   1. KEIKO_FIGMA_KEY  — base64 of exactly 32 bytes. Explicit operator override.
+//   2. macOS Keychain   — generic password "keiko-figma-vault". The OS protects the key.
+//   3. Keyfile          — <vaultDir>/figma-vault.key, mode 0600. Weakest tier (key next to store).
+import { execFileSync } from "node:child_process";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { userInfo } from "node:os";
+import { dirname, resolve } from "node:path";
+import { isSealed, openString, sealString } from "@oscharko-dev/keiko-security";
+import { FigmaConnectorError } from "./figmaConnectorErrors.js";
+const KEY_BYTES = 32;
+const KEYFILE_NAME = "figma-vault.key";
+const KEYCHAIN_SERVICE = "keiko-figma-vault";
+function decodeKeyOrThrow(raw) {
+    const decoded = Buffer.from(raw, "base64");
+    if (decoded.length !== KEY_BYTES) {
+        // Coded, secret-free: a misconfigured key surfaces as FIGMA_INTERNAL and never echoes the
+        // (possibly partial) key material in the message.
+        throw new FigmaConnectorError("FIGMA_INTERNAL");
+    }
+    return decoded;
+}
+function keyFromEnv(env) {
+    const raw = env.KEIKO_FIGMA_KEY;
+    if (raw === undefined || raw.length === 0)
+        return undefined;
+    return decodeKeyOrThrow(raw);
+}
+function ensureDirHardened(dir) {
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (process.platform === "win32")
+        return;
+    try {
+        chmodSync(dir, 0o700);
+    }
+    catch {
+        // Best-effort: a parent-owned directory we cannot chmod beats a hard failure.
+    }
+}
+function assertNoSymlinkedPathSegments(resolvedPath) {
+    let current = resolvedPath;
+    while (current !== dirname(current)) {
+        if (isSymlink(current)) {
+            throw new FigmaConnectorError("FIGMA_INTERNAL");
+        }
+        current = dirname(current);
+    }
+}
+function isSymlink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+function keyFromKeychain() {
+    if (process.platform !== "darwin")
+        return undefined;
+    const account = userInfo().username;
+    try {
+        const found = execFileSync("security", ["find-generic-password", "-s", KEYCHAIN_SERVICE, "-a", account, "-w"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        return decodeKeyOrThrow(found);
+    }
+    catch {
+        return generateKeychainKey(account);
+    }
+}
+function generateKeychainKey(account) {
+    const key = randomBytes(KEY_BYTES);
+    try {
+        execFileSync("security", ["add-generic-password", "-s", KEYCHAIN_SERVICE, "-a", account, "-w", key.toString("base64")], { stdio: ["ignore", "ignore", "ignore"] });
+        return key;
+    }
+    catch {
+        return undefined;
+    }
+}
+function keyFromKeyfile(vaultDir) {
+    const keyfile = resolve(vaultDir, KEYFILE_NAME);
+    assertNoSymlinkedPathSegments(keyfile);
+    ensureDirHardened(dirname(keyfile));
+    assertNoSymlinkedPathSegments(keyfile);
+    if (existsSync(keyfile)) {
+        return decodeKeyOrThrow(readFileSync(keyfile, "utf8").trim());
+    }
+    const key = randomBytes(KEY_BYTES);
+    writeFileSync(keyfile, key.toString("base64"), { mode: 0o600 });
+    chmodIfPresent(keyfile, 0o600);
+    return key;
+}
+function chmodIfPresent(path, mode) {
+    if (process.platform === "win32")
+        return;
+    try {
+        chmodSync(path, mode);
+    }
+    catch {
+        // Best-effort hardening.
+    }
+}
+export const NO_FIGMA_KEYCHAIN = () => undefined;
+export function resolveFigmaVaultKey(env, vaultDir, keychainAccess = keyFromKeychain) {
+    const fromEnv = keyFromEnv(env);
+    if (fromEnv !== undefined)
+        return { key: fromEnv, source: "env" };
+    const fromKeychain = keychainAccess();
+    if (fromKeychain !== undefined)
+        return { key: fromKeychain, source: "keychain" };
+    return { key: keyFromKeyfile(vaultDir), source: "keyfile" };
+}
+export function createFigmaTokenStore(deps) {
+    const { key } = deps;
+    const storePath = resolve(deps.storePath);
+    const store = (token) => {
+        assertNoSymlinkedPathSegments(storePath);
+        ensureDirHardened(dirname(storePath));
+        assertNoSymlinkedPathSegments(storePath);
+        writeFileSync(storePath, sealString(key, token), { mode: 0o600 });
+        chmodIfPresent(storePath, 0o600);
+    };
+    const read = () => {
+        assertNoSymlinkedPathSegments(storePath);
+        if (!existsSync(storePath))
+            return undefined;
+        const envelope = readFileSync(storePath, "utf8").trim();
+        if (envelope.length === 0 || !isSealed(envelope))
+            return undefined;
+        return openString(key, envelope);
+    };
+    const revoke = () => {
+        assertNoSymlinkedPathSegments(storePath);
+        rmSync(storePath, { force: true });
+    };
+    return { store, read, revoke };
+}

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

@@ -0,0 +1,6 @@
+export interface FigmaTarget {
+    readonly fileKey: string;
+    readonly nodeId: string;
+}
+export declare const parseFigmaTarget: (value: string) => FigmaTarget | null;
+//# sourceMappingURL=figmaUrl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"figmaUrl.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaUrl.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAeD,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,KAAG,WAAW,GAAG,IAe9D,CAAC"}

package/dist/qualityIntelligence/figma/figmaUrl.js

@@ -0,0 +1,36 @@
+// Figma URL → scoped target parsing (Epic #750, Issue #751).
+//
+// Pure, deterministic. Extracts a file-key + node-id from a pasted Figma board/section
+// link. A link WITHOUT a node-id is rejected (null) so the connector can never default to
+// a whole-file pull. Figma URLs encode node-ids with `-` (e.g. `0-1`); the REST API uses
+// `:` (e.g. `0:1`), so the parsed node-id is normalised to the API form.
+const ACCEPTED_HOSTS = ["figma.com", "www.figma.com"];
+const SCOPED_PATH_KINDS = ["design", "file"];
+const normaliseNodeId = (raw) => raw.replace(/-/g, ":");
+const parseUrl = (value) => {
+    try {
+        return new URL(value);
+    }
+    catch {
+        return null;
+    }
+};
+export const parseFigmaTarget = (value) => {
+    const url = parseUrl(value.trim());
+    if (url === null)
+        return null;
+    if (url.protocol !== "https:")
+        return null;
+    if (!ACCEPTED_HOSTS.includes(url.hostname))
+        return null;
+    const segments = url.pathname.split("/").filter((part) => part.length > 0);
+    const [kind, fileKey] = segments;
+    if (kind === undefined || !SCOPED_PATH_KINDS.includes(kind))
+        return null;
+    if (fileKey === undefined || fileKey.length === 0)
+        return null;
+    const rawNodeId = url.searchParams.get("node-id");
+    if (rawNodeId === null || rawNodeId.length === 0)
+        return null;
+    return { fileKey, nodeId: normaliseNodeId(rawNodeId) };
+};

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

@@ -0,0 +1,20 @@
+export { createFigmaConnector, type FigmaConnector, type FigmaConnectorConfig, type FigmaConnectorDeps, type FigmaEnv, type FigmaFetchOptions, type FigmaProvenance, type FigmaScopedResult, } from "./figmaConnector.js";
+export { createDefaultFigmaHttpPort, type FigmaHttpPort, type FigmaHttpRequest, type FigmaHttpResponse, } from "./figmaHttpPort.js";
+export { createDefaultFigmaRenderPort, type FigmaRenderPort, type FigmaRenderRequest, type FigmaRenderResponse, } from "./figmaRenderPort.js";
+export { buildFigmaSnapshot, type BuildFigmaSnapshotInput } from "./figmaSnapshotBuilder.js";
+export { resnapshotFigma, type FigmaCleanToIr, type ResnapshotFigmaDeps, } from "./figmaResnapshot.js";
+export { fetchWithBackoff, realFigmaRetrySleep, DEFAULT_FIGMA_RETRY_POLICY, type FigmaBackoffResponse, type FigmaRetryPolicy, type FigmaRetrySleep, } from "./figmaRetry.js";
+export { mapWithConcurrency } from "./figmaConcurrency.js";
+export { paginateScopedDocument, discoverScreenNodes, DEFAULT_SCOPED_PAGINATION_LIMITS, SCOPED_PAGINATION_LIMIT_CEILINGS, resolveScopedPaginationLimits, type FigmaScopeCoverage, type RawFigmaNode, type ScopedNodeFetcher, type ScopedPaginationLimits, } from "./figmaScopedPagination.js";
+export type { FigmaRenderedImage, FigmaSkippedScreen, FigmaSkippedScreenReason, FigmaSnapshot, FigmaSnapshotScreen, } from "./figmaSnapshotTypes.js";
+export { FigmaConnectorError, figmaConnectorErrorBody, type FigmaConnectorErrorBody, type FigmaConnectorErrorCode, } from "./figmaConnectorErrors.js";
+export { parseFigmaTarget, type FigmaTarget } from "./figmaUrl.js";
+export { resolveReadiness, type FigmaNode, type FigmaDevStatus, type ReadinessOptions, type ReadinessSignal, } from "./figmaReadiness.js";
+export { createFigmaTokenStore, resolveFigmaVaultKey, NO_FIGMA_KEYCHAIN, type FigmaTokenStore, type FigmaTokenStoreDeps, type FigmaKeychainAccess, type FigmaVaultKeySource, type ResolvedFigmaVaultKey, } from "./figmaTokenStore.js";
+export { resolveFigmaToken, classifyTokenFailure, type FigmaTokenSources, } from "./figmaTokenSource.js";
+export { deriveFigmaScopeRef, type FigmaScopeRef } from "./figmaScopeRef.js";
+export { appendFigmaConnectorAudit, loadFigmaConnectorAudit, FIGMA_AUDIT_SCHEMA_VERSION, type AppendFigmaConnectorAuditInput, type FigmaConnectorAction, type FigmaConnectorAuditArtifact, type FigmaConnectorAuditCounts, type FigmaConnectorAuditEntry, type FigmaConnectorOutcome, } from "./figmaConnectorAudit.js";
+export { recordReadOnlyConsent, loadReadOnlyConsent, hasReadOnlyConsent, assertReadOnlyConsent, EXPECTED_FIGMA_SCOPES, FIGMA_CONSENT_SCHEMA_VERSION, type FigmaScopeConsent, type RecordReadOnlyConsentInput, } from "./figmaConsent.js";
+export { computeFigmaConnectorMetrics, type FigmaA11yMetrics, type FigmaAugmentationShare, type FigmaAugmentationTally, type FigmaConnectorMetrics, type FigmaConnectorMetricsExtras, type FigmaNavGraphMetrics, } from "./figmaConnectorMetrics.js";
+export { observeFigmaSnapshot, observeFigmaRevoke, type ObservedActionContext, type ObservedRevokeInput, type ObservedSnapshotInput, type ObservedSnapshotResult, } from "./figmaObservedActions.js";
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/qualityIntelligence/figma/index.js

@@ -0,0 +1,26 @@
+// Local barrel for the server-side Figma connector (Epic #750, Issue #751).
+//
+// Intentionally NOT re-exported from the keiko-server Quality Intelligence package
+// public barrel (../index.ts): these are internal server modules consumed by the route
+// tier, kept out of the package public surface so `check:package-surface` stays stable.
+//
+// The connector is disabled-until-configured (no token ⇒ FIGMA_TOKEN_MISSING), reads the
+// read-only PAT server-side only, and never logs/returns/embeds the token.
+export { createFigmaConnector, } from "./figmaConnector.js";
+export { createDefaultFigmaHttpPort, } from "./figmaHttpPort.js";
+export { createDefaultFigmaRenderPort, } from "./figmaRenderPort.js";
+export { buildFigmaSnapshot } from "./figmaSnapshotBuilder.js";
+export { resnapshotFigma, } from "./figmaResnapshot.js";
+export { fetchWithBackoff, realFigmaRetrySleep, DEFAULT_FIGMA_RETRY_POLICY, } from "./figmaRetry.js";
+export { mapWithConcurrency } from "./figmaConcurrency.js";
+export { paginateScopedDocument, discoverScreenNodes, DEFAULT_SCOPED_PAGINATION_LIMITS, SCOPED_PAGINATION_LIMIT_CEILINGS, resolveScopedPaginationLimits, } from "./figmaScopedPagination.js";
+export { FigmaConnectorError, figmaConnectorErrorBody, } from "./figmaConnectorErrors.js";
+export { parseFigmaTarget } from "./figmaUrl.js";
+export { resolveReadiness, } from "./figmaReadiness.js";
+export { createFigmaTokenStore, resolveFigmaVaultKey, NO_FIGMA_KEYCHAIN, } from "./figmaTokenStore.js";
+export { resolveFigmaToken, classifyTokenFailure, } from "./figmaTokenSource.js";
+export { deriveFigmaScopeRef } from "./figmaScopeRef.js";
+export { appendFigmaConnectorAudit, loadFigmaConnectorAudit, FIGMA_AUDIT_SCHEMA_VERSION, } from "./figmaConnectorAudit.js";
+export { recordReadOnlyConsent, loadReadOnlyConsent, hasReadOnlyConsent, assertReadOnlyConsent, EXPECTED_FIGMA_SCOPES, FIGMA_CONSENT_SCHEMA_VERSION, } from "./figmaConsent.js";
+export { computeFigmaConnectorMetrics, } from "./figmaConnectorMetrics.js";
+export { observeFigmaSnapshot, observeFigmaRevoke, } from "./figmaObservedActions.js";

package/dist/qualityIntelligence/figmaCodegenRoutes.d.ts

@@ -0,0 +1,28 @@
+import type { RouteContext, RouteResult } from "../routes.js";
+import type { UiHandlerDeps } from "../deps.js";
+declare const FIGMA_CODEGEN_SCHEMA_VERSION: 1;
+/** The persisted, reviewable code artifact (evidence-backed; deterministic, carries no timestamp). */
+export interface PersistedFigmaCodeArtifact {
+    readonly figmaCodegenSchemaVersion: typeof FIGMA_CODEGEN_SCHEMA_VERSION;
+    readonly runId: string;
+    readonly adapterName: string;
+    readonly files: readonly {
+        readonly path: string;
+        readonly contents: string;
+    }[];
+}
+/** Browser-safe response: the reviewable file set plus a small summary. No token, no board id. */
+export interface FigmaCodegenResponse {
+    readonly runId: string;
+    readonly adapterName: string;
+    readonly fileCount: number;
+    readonly totalBytes: number;
+    readonly screenCount: number;
+    readonly files: readonly {
+        readonly path: string;
+        readonly contents: string;
+    }[];
+}
+export declare function handleFigmaGenerateCode(ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
+export {};
+//# sourceMappingURL=figmaCodegenRoutes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"figmaCodegenRoutes.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/figmaCodegenRoutes.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAShD,QAAA,MAAM,4BAA4B,EAAG,CAAU,CAAC;AAMhD,sGAAsG;AACtG,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,yBAAyB,EAAE,OAAO,4BAA4B,CAAC;IACxE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACjF;AAED,kGAAkG;AAClG,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACjF;AA+GD,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,GAAG,WAAW,CAkD3F"}

package/dist/qualityIntelligence/figmaCodegenRoutes.js

@@ -0,0 +1,165 @@
+// Design-to-code generation from a stored Figma Snapshot (Epic #750, Issue #755).
+//
+//   POST /api/figma/snapshots/:runId/code — emit reviewable frontend code for a built snapshot.
+//
+// This is the missing runnable seam for #755: the pure emission domain (emitCode + htmlCssAdapter +
+// the CodeTargetAdapter seam) shipped, but no route/run consumed it, so the capability was unreachable
+// from a user. The run reads ONLY the stored snapshot (the communication boundary holds — no Figma,
+// no model, no network, no filesystem beyond the local evidence write), builds the deterministic
+// target-neutral emission plan from the Screen-IR + the persisted design tokens (#752) + the routing
+// hints derived from the persisted inter-screen links (#811), renders semantic HTML/CSS through the
+// first-slice html-css adapter, and returns a reviewable artifact (a proposal — never auto-applied).
+//
+// Determinism + model-independence (#755 DoD): emission is pure and model-free, so the same stored
+// snapshot yields a byte-identical artifact; semantic naming (the only model-augmentation point) is
+// additive and absent here, so the structural defaults are used. Evidence-backed: the artifact must be
+// persisted to the local evidence dir through the reused contained-store seam before the route returns
+// success. Gated: CSRF + host-check + a valid stored runId (the dispatch layer enforces the
+// state-changing-request guard for this POST). No hidden external effects: nothing leaves the box, the
+// snapshot is never mutated.
+//
+// Cancellable (#755 AC2): for the first slice this is moot by construction — the handler is a
+// synchronous, pure, microsecond computation with no run-registry entry, no model call, no streaming,
+// and no long-running external work to abort; a client disconnect simply drops the response. When a
+// future slice wires the SemanticNamingProvider to a gateway model call, that injected port is where
+// an AbortSignal threads through — no structural change to this route is required.
+import { createNodeContainedJsonArtifactStore, createNodeFigmaSnapshotStore, } from "@oscharko-dev/keiko-evidence";
+import { QualityIntelligenceFigma } from "@oscharko-dev/keiko-quality-intelligence";
+const FIGMA_CODEGEN_SUFFIX = ".figma-codegen.json";
+const FIGMA_CODEGEN_SCHEMA_VERSION = 1;
+const MAX_CODEGEN_SCREENS = 80;
+const MAX_CODEGEN_FILES = MAX_CODEGEN_SCREENS + 2;
+const MAX_CODEGEN_FILE_BYTES = 1024 * 1024;
+const MAX_CODEGEN_TOTAL_BYTES = 5 * 1024 * 1024;
+const errorBody = (code, message) => ({
+    error: { code, message },
+});
+function codegenTooLarge(message) {
+    return { status: 413, body: errorBody("FIGMA_CODEGEN_TOO_LARGE", message) };
+}
+// Re-hydrate the deterministic emission input from the stored snapshot. Unparseable screens are
+// dropped (never crash). Links → nav graph → routing hints feed the adapter's screen-to-screen wiring.
+function emissionInputFromRecord(record) {
+    const screens = record.screens
+        .map((s) => QualityIntelligenceFigma.parseScreenIr(s.irJson))
+        .filter((s) => s !== undefined);
+    const tokens = QualityIntelligenceFigma.parseDesignTokens(record.tokens);
+    const links = (record.links ?? []).map((l) => ({
+        sourceNodeId: l.sourceNodeId,
+        trigger: l.trigger,
+        targetNodeId: l.targetNodeId,
+    }));
+    const graph = QualityIntelligenceFigma.deriveNavGraph({
+        screens,
+        links,
+        tokens,
+        reduction: { inputNodeCount: 0, keptNodeCount: 0, removedNodeCount: 0, removedRatio: 0 },
+    });
+    return { screens, tokens, hints: QualityIntelligenceFigma.deriveRoutingHints(graph) };
+}
+function persistArtifact(evidenceDir, artifact) {
+    // Evidence-backed (#755): the reviewable artifact is written through the reused contained-store seam.
+    // Fail closed when the companion cannot be written; otherwise the route could return generated code
+    // with no durable evidence record.
+    createNodeContainedJsonArtifactStore(evidenceDir, FIGMA_CODEGEN_SUFFIX, {
+        parse: (value) => typeof value === "object" &&
+            value !== null &&
+            value.figmaCodegenSchemaVersion ===
+                FIGMA_CODEGEN_SCHEMA_VERSION
+            ? value
+            : undefined,
+    }).record(artifact.runId, artifact);
+}
+function summarizeArtifact(artifact) {
+    if (artifact.files.length > MAX_CODEGEN_FILES) {
+        return codegenTooLarge("The generated code artifact contains too many files to review safely.");
+    }
+    let totalBytes = 0;
+    for (const file of artifact.files) {
+        const fileBytes = Buffer.byteLength(file.contents, "utf8");
+        if (fileBytes > MAX_CODEGEN_FILE_BYTES) {
+            return codegenTooLarge("A generated code file is too large to review safely.");
+        }
+        totalBytes += fileBytes;
+        if (totalBytes > MAX_CODEGEN_TOTAL_BYTES) {
+            return codegenTooLarge("The generated code artifact is too large to review safely.");
+        }
+    }
+    return { totalBytes };
+}
+// ─── POST /api/figma/snapshots/:runId/code ─────────────────────────────────────
+// Resolve evidenceDir + runId, load + 404 the stored snapshot, or return a coded RouteResult.
+function loadSnapshotForCodegen(ctx, deps) {
+    const evidenceDir = deps.evidenceDir;
+    if (evidenceDir === undefined || evidenceDir.length === 0) {
+        return {
+            status: 503,
+            body: errorBody("FIGMA_NO_EVIDENCE_DIR", "The evidence directory is not configured."),
+        };
+    }
+    const runId = ctx.params.runId ?? "";
+    if (runId.length === 0) {
+        return { status: 400, body: errorBody("FIGMA_SNAPSHOT_NOT_FOUND", "Missing snapshot run id.") };
+    }
+    let record;
+    try {
+        record = createNodeFigmaSnapshotStore(evidenceDir).load(runId);
+    }
+    catch {
+        return {
+            status: 500,
+            body: errorBody("FIGMA_INTERNAL", "The snapshot could not be read for code generation."),
+        };
+    }
+    if (record === undefined) {
+        return {
+            status: 404,
+            body: errorBody("FIGMA_SNAPSHOT_NOT_FOUND", "No snapshot was found for this run id."),
+        };
+    }
+    return { record, evidenceDir, runId };
+}
+export function handleFigmaGenerateCode(ctx, deps) {
+    const loaded = loadSnapshotForCodegen(ctx, deps);
+    if ("status" in loaded)
+        return loaded;
+    const { record, evidenceDir, runId } = loaded;
+    const input = emissionInputFromRecord(record);
+    if (input.screens.length === 0) {
+        return {
+            status: 422,
+            body: errorBody("FIGMA_CODEGEN_NO_SCREENS", "The snapshot has no usable screen to generate code from."),
+        };
+    }
+    if (input.screens.length > MAX_CODEGEN_SCREENS) {
+        return codegenTooLarge("The snapshot contains too many screens to generate code safely.");
+    }
+    const artifact = QualityIntelligenceFigma.emitCode(input, QualityIntelligenceFigma.htmlCssAdapter);
+    const artifactSummary = summarizeArtifact(artifact);
+    if ("status" in artifactSummary)
+        return artifactSummary;
+    const persisted = {
+        figmaCodegenSchemaVersion: FIGMA_CODEGEN_SCHEMA_VERSION,
+        runId,
+        adapterName: artifact.adapterName,
+        files: artifact.files,
+    };
+    try {
+        persistArtifact(evidenceDir, persisted);
+    }
+    catch {
+        return {
+            status: 500,
+            body: errorBody("FIGMA_INTERNAL", "The code artifact could not be persisted as evidence."),
+        };
+    }
+    const response = {
+        runId,
+        adapterName: artifact.adapterName,
+        fileCount: artifact.files.length,
+        totalBytes: artifactSummary.totalBytes,
+        screenCount: input.screens.length,
+        files: artifact.files,
+    };
+    return { status: 200, body: response };
+}

package/dist/qualityIntelligence/figmaSnapshotAdapter.d.ts

@@ -0,0 +1,55 @@
+import { type FigmaSnapshotImageRef, type FigmaSnapshotRecord } from "@oscharko-dev/keiko-evidence";
+import type { UiHandlerDeps } from "../deps.js";
+/** Loads an immutable Figma Snapshot evidence record by runId. Returns `undefined` when not found. */
+export type FigmaSnapshotLoader = (snapshotRunId: string) => FigmaSnapshotRecord | undefined;
+export interface FigmaSnapshotLoaderOptions {
+    /**
+     * Drift seam (#735): a figma-snapshot source pins a write-once, content-addressed runId, so its
+     * content can never change under its identity — re-checking the pinned record would always
+     * report "fresh" even after the board changed and was re-snapshotted. When this flag is set the
+     * loader resolves the LATEST snapshot recorded for the same board scope (fileKey + nodeId) and
+     * returns it instead of the pinned record whenever its integrity hash differs. Screen atom ids
+     * are board-stable (screenId-derived), so compareStaleness sees changed atoms, not orphans.
+     * Used by re-check and regenerate-stale ONLY — the generate path keeps exact pinning.
+     */
+    readonly resolveLatestByScope?: boolean;
+}
+/**
+ * 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 declare function makeFigmaSnapshotLoader(deps: UiHandlerDeps, options?: FigmaSnapshotLoaderOptions): FigmaSnapshotLoader | undefined;
+/** The image-derived semantics a multimodal model recovered for one screen, as additive hints. */
+export interface FigmaVisionScreenRequest {
+    readonly snapshotRunId: string;
+    readonly screenId: string;
+    /** The image side-file reference recorded in the snapshot (relative path + sha256). */
+    readonly image: FigmaSnapshotImageRef;
+    readonly imageRelativePath: string;
+    /** The deterministic baseline text, supplied so the model cross-checks rather than re-derives. */
+    readonly baselineText: string;
+}
+/**
+ * Produces additive vision hints for a screen, OR an empty list when vision is unavailable / failed.
+ * The contract is total: it NEVER throws and NEVER returns a value that could override the IR — the
+ * caller appends the hints below the baseline.
+ */
+export type FigmaVisionHintProvider = (request: FigmaVisionScreenRequest) => readonly string[] | Promise<readonly string[]>;
+/**
+ * A raw vision call: given a screen request and the selected model id, return image-derived hint
+ * strings. Injectable so tests can keep the provider deterministic; production defaults to the
+ * server-owned evidence-store + Model Gateway port below. Absence is exactly the IR-only path.
+ */
+export type FigmaVisionCall = (request: FigmaVisionScreenRequest, modelId: string) => readonly string[] | Promise<readonly string[]>;
+export interface FigmaVisionHintProviderOptions {
+    readonly onGatewayCallAttempt?: (() => void) | undefined;
+}
+/**
+ * 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 declare function makeFigmaVisionHintProvider(deps: UiHandlerDeps, visionCall?: FigmaVisionCall, options?: FigmaVisionHintProviderOptions): FigmaVisionHintProvider;
+//# sourceMappingURL=figmaSnapshotAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"figmaSnapshotAdapter.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/figmaSnapshotAdapter.ts"],"names":[],"mappings":"AAmBA,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACzB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGhD,sGAAsG;AACtG,MAAM,MAAM,mBAAmB,GAAG,CAAC,aAAa,EAAE,MAAM,KAAK,mBAAmB,GAAG,SAAS,CAAC;AAE7F,MAAM,WAAW,0BAA0B;IACzC;;;;;;;;OAQG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;CACzC;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,aAAa,EACnB,OAAO,CAAC,EAAE,0BAA0B,GACnC,mBAAmB,GAAG,SAAS,CA0BjC;AAED,kGAAkG;AAClG,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uFAAuF;IACvF,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,kGAAkG;IAClG,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,CACpC,OAAO,EAAE,wBAAwB,KAC9B,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;AAEpD;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,OAAO,EAAE,wBAAwB,EACjC,OAAO,EAAE,MAAM,KACZ,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;AAEpD,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;CAC1D;AA2KD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,aAAa,EACnB,UAAU,CAAC,EAAE,eAAe,EAC5B,OAAO,GAAE,8BAAmC,GAC3C,uBAAuB,CAiBzB"}