@birdie_moblie/open_spec 2.1.7

package/dist/delivery/skills.js

@@ -0,0 +1,178 @@
+import path from 'node:path';
+import { z } from 'zod';
+import { exists, readJson, readText, writeJson, writeText } from '../shared/fs.js';
+import { digestDirectory, sha256 } from '../shared/hash.js';
+import { AppError } from '../shared/errors.js';
+import { packageRoot } from '../shared/pkg.js';
+import { execFile } from '../shared/exec.js';
+import { WORKFLOWS } from '../core/types.js';
+import { resolveInside } from '../shared/paths.js';
+import { preparePluginDistribution } from './distribution.js';
+import { installClaudePlugin } from './claude-install.js';
+const DeliveryResultSchema = z.object({
+    host: z.enum(['claude', 'codex', 'cursor']),
+    status: z.enum(['installed', 'pending_user_action', 'skipped_by_user', 'failed']),
+    digest: z.string(),
+    skills: z.array(z.string()),
+    target: z.string(),
+    error: z.string().optional(),
+}).strict();
+const DeliveryReceiptSchema = z.object({
+    deliveredAt: z.string(),
+    results: z.array(DeliveryResultSchema),
+}).strict();
+export function deliverSkills(projectRoot, hosts, mode) {
+    const source = path.join(packageRoot(), 'skills');
+    if (!exists(source))
+        throw new AppError('skills_missing', '本包缺少 skills/ 目录');
+    const skills = WORKFLOWS.filter((name) => exists(path.join(source, name)));
+    const results = hosts.map((host) => DeliveryResultSchema.parse(deliverHost(projectRoot, host, mode, digestDelivery(packageRoot(), host), skills)));
+    writeJson(resolveInside(projectRoot, 'openspec/.runtime/delivery.json', 'delivery_path_outside_project'), {
+        deliveredAt: new Date().toISOString(),
+        results,
+    });
+    return results;
+}
+function deliverHost(projectRoot, host, mode, digest, skills) {
+    const selector = 'openspec@openspec-bridge';
+    if (mode === 'skip')
+        return { host, status: 'skipped_by_user', digest, skills, target: selector };
+    if (host === 'cursor' || mode === 'pending') {
+        const target = host === 'cursor' ? 'Cursor Customize → Plugins → openspec' : selector;
+        return { host, status: 'pending_user_action', digest, skills, target };
+    }
+    const root = preparePluginDistribution(packageRoot());
+    // Claude 用 local scope（.claude/settings.local.json，不入库）：marketplace 路径是本机绝对路径，不能随 project scope 提交给他人
+    const add = host === 'claude'
+        ? execFile('claude', ['plugin', 'marketplace', 'add', root, '--scope', 'local'], { cwd: projectRoot })
+        : execFile('codex', ['plugin', 'marketplace', 'add', root, '--json'], { cwd: projectRoot });
+    if (!add.ok)
+        return { host, status: 'failed', digest, skills, target: selector, error: add.stderr || add.stdout };
+    const install = host === 'claude'
+        ? installClaudePlugin(projectRoot, selector, root)
+        : execFile('codex', ['plugin', 'add', selector, '--json'], { cwd: projectRoot });
+    return install.ok
+        ? { host, status: 'installed', digest, skills, target: selector }
+        : { host, status: 'failed', digest, skills, target: selector, error: install.stderr || install.stdout };
+}
+export function verifyDelivery(projectRoot, host) {
+    const expected = digestDelivery(packageRoot(), host);
+    const file = resolveInside(projectRoot, 'openspec/.runtime/delivery.json', 'delivery_path_outside_project');
+    if (!exists(file))
+        return { ok: false, status: 'missing', expected, actual: '' };
+    const parsed = DeliveryReceiptSchema.safeParse(readJson(file));
+    if (!parsed.success)
+        throw new AppError('invalid_delivery_receipt', '宿主交付记录不合法', parsed.error.issues);
+    const record = parsed.data.results.find((item) => item.host === host);
+    if (!record)
+        return { ok: false, status: 'missing', expected, actual: '' };
+    return {
+        ok: record.status === 'installed' && record.digest === expected,
+        status: record.status,
+        expected,
+        actual: record.digest,
+    };
+}
+export function digestDelivery(root, host) {
+    const parts = [];
+    for (const name of WORKFLOWS) {
+        const skillDir = path.join(root, 'skills', name);
+        if (exists(skillDir))
+            parts.push(`${name}:${digestDirectory(skillDir)}`);
+    }
+    // Offline benchmarks also digest historical packages that contained host helpers.
+    const extras = path.join(root, 'host-skills', host);
+    if (exists(extras))
+        parts.push(`host:${digestDirectory(extras)}`);
+    for (const relative of ['plugin.json', '.agents', ...(host === 'claude' ? ['.claude-plugin'] : host === 'codex' ? ['.codex-plugin'] : [])]) {
+        const file = path.join(root, relative);
+        if (exists(file))
+            parts.push(`${relative}:${relative.endsWith('.json') ? sha256(readText(file)) : digestDirectory(file)}`);
+    }
+    return sha256(parts.join('|'));
+}
+/** Entire executable artifact, excluding installation dependencies and local state. */
+export function digestPackage(root) {
+    return sha256(['dist', 'bin', 'skills', 'host-skills', 'presets', 'docs', '.agents', '.codex-plugin', '.claude-plugin',
+        'package.json', 'plugin.json', 'README.md'].map((relative) => {
+        const file = path.join(root, relative);
+        if (!exists(file))
+            return `${relative}:missing`;
+        return `${relative}:${relative.includes('.') && !relative.startsWith('.') ? sha256(readText(file)) : digestDirectory(file)}`;
+    }).join('|'));
+}
+export function generateInstallCli(version, packageName) {
+    return `#!/usr/bin/env node
+// @openspec-installer ${JSON.stringify({ packageName, packageVersion: version })}
+import { spawnSync } from 'node:child_process';
+
+const meta = { packageName: ${JSON.stringify(packageName)}, packageVersion: ${JSON.stringify(version)} };
+const check = process.argv.includes('--check');
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+const nodeMajor = Number(process.versions.node.split('.')[0]);
+if (nodeMajor !== 22 && nodeMajor !== 24) {
+  fail('OpenSpec 需要 Node.js 22 或 24，当前为 ' + process.versions.node);
+}
+
+const npmCheck = spawnSync('npm', ['--version'], { encoding: 'utf8' });
+if (npmCheck.status !== 0) fail('未找到可用的 npm，无法校验或安装 OpenSpec CLI');
+
+function installedVersion() {
+  const result = spawnSync('openspec', ['--version'], { encoding: 'utf8' });
+  if (result.status !== 0) return null;
+  return (result.stdout || '').trim();
+}
+
+const current = installedVersion();
+if (check) {
+  const ok = current === meta.packageVersion;
+  console.log(JSON.stringify({ ok, current, expected: meta.packageVersion, node: process.versions.node, npm: (npmCheck.stdout || '').trim() }));
+  process.exit(ok ? 0 : 1);
+}
+
+if (current === meta.packageVersion) {
+  console.log(\`OpenSpec \${meta.packageVersion} 已安装\`);
+  process.exit(0);
+}
+
+const install = spawnSync(
+  'npm',
+  ['install', '--global', \`\${meta.packageName}@\${meta.packageVersion}\`, '--no-audit', '--no-fund'],
+  { stdio: 'inherit' },
+);
+if (install.status !== 0) process.exit(install.status ?? 1);
+const installed = installedVersion();
+if (installed !== meta.packageVersion) {
+  fail('安装后版本校验失败：期望 ' + meta.packageVersion + '，实际 ' + (installed ?? 'missing'));
+}
+console.log('OpenSpec ' + meta.packageVersion + ' 安装并校验完成');
+`;
+}
+export function writeInstallCli(projectRoot, version, packageName) {
+    writeText(resolveInside(projectRoot, 'openspec/install-cli.mjs', 'installer_path_outside_project'), generateInstallCli(version, packageName));
+}
+export function verifyInstallCli(projectRoot, version, packageName) {
+    const expected = { packageName, packageVersion: version };
+    const file = resolveInside(projectRoot, 'openspec/install-cli.mjs', 'installer_path_outside_project');
+    if (!exists(file))
+        return { ok: false, expected, actual: null };
+    const firstLine = readText(file).split('\n').find((line) => line.startsWith('// @openspec-installer '));
+    if (!firstLine)
+        return { ok: false, expected, actual: null };
+    try {
+        const actual = JSON.parse(firstLine.slice('// @openspec-installer '.length));
+        return { ok: actual.packageName === packageName && actual.packageVersion === version, expected, actual };
+    }
+    catch {
+        return { ok: false, expected, actual: null };
+    }
+}
+export function isWorkflow(value) {
+    return WORKFLOWS.includes(value);
+}
+//# sourceMappingURL=skills.js.map

package/dist/figma/cache.d.ts

@@ -0,0 +1,19 @@
+import { type PageIndex } from './index.js';
+import type { SourceItem } from '../core/types.js';
+interface CacheRecord {
+    epoch: string;
+    key: string;
+    indexRel: string;
+}
+export declare function figmaEpoch(root: string, change: string): string;
+export declare function cachedIndexes(root: string, change: string): Array<CacheRecord & {
+    index: PageIndex;
+}>;
+/** After collect, the ledger owns the snapshot; the collection cache epoch has ended. */
+export declare function collectedIndexes(root: string, change: string, sources: SourceItem[]): PageIndex[];
+export declare function persistIndex(root: string, change: string, key: string, index: PageIndex): string;
+export declare function refreshFigma(root: string, change: string): void;
+export declare function hasFigmaSession(root: string, change: string): boolean;
+export declare function writeOnce(file: string, text: string): void;
+export {};
+//# sourceMappingURL=cache.d.ts.map

package/dist/figma/cache.js

@@ -0,0 +1,115 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, linkSync, unlinkSync, renameSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { artifactPath, requireChange } from '../core/change.js';
+import { sha256 } from '../shared/hash.js';
+import { figmaSource, projectMetadata } from './index.js';
+const MANIFEST = 'sources/figma/cache.jsonl';
+export function figmaEpoch(root, change) {
+    const state = requireChange(root, change);
+    return `${state.collectedRevision}:${state.sourceUpdate?.startedAt ?? ''}`;
+}
+export function cachedIndexes(root, change) {
+    const manifest = artifactPath(root, change, MANIFEST);
+    if (!existsSync(manifest))
+        return [];
+    let records = [];
+    const epoch = figmaEpoch(root, change);
+    for (const line of readFileSync(manifest, 'utf8').split('\n').filter(Boolean)) {
+        const row = JSON.parse(line);
+        if (row.refresh)
+            records = [];
+        else if (row.epoch === epoch)
+            records.push(row);
+    }
+    const latest = new Map(records.map(row => [row.key, row]));
+    return [...latest.values()].flatMap(record => {
+        if (!/^sources\/figma\/[a-f0-9]{64}\.index\.json$/.test(record.indexRel))
+            return [];
+        const index = readIndex(root, change, record.indexRel);
+        return index ? [{ ...record, index }] : [];
+    });
+}
+/** After collect, the ledger owns the snapshot; the collection cache epoch has ended. */
+export function collectedIndexes(root, change, sources) {
+    return sources.flatMap(source => {
+        if (!source.artifact || !source.artifactSha256)
+            return [];
+        try {
+            const text = readFileSync(artifactPath(root, change, source.artifact), 'utf8');
+            if (sha256(text) !== source.artifactSha256)
+                return [];
+            const pages = JSON.parse(text);
+            if (pages.adapter !== 'smart-figma' || pages.source?.url !== figmaSource(source.locator).url
+                || !Array.isArray(pages.indexes) || !pages.indexes.length)
+                return [];
+            const indexes = pages.indexes.map((relative) => typeof relative === 'string'
+                && /^sources\/figma\/[a-f0-9]{64}\.index\.json$/.test(relative) ? readIndex(root, change, relative) : undefined);
+            return indexes.every((index) => index !== undefined) ? indexes : [];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+export function persistIndex(root, change, key, index) {
+    const text = JSON.stringify(index, null, 2) + '\n';
+    const indexRel = `sources/figma/${sha256(text)}.index.json`;
+    const file = artifactPath(root, change, indexRel);
+    writeOnce(file, text);
+    const manifest = artifactPath(root, change, MANIFEST);
+    appendFileSync(manifest, JSON.stringify({ epoch: figmaEpoch(root, change), key, indexRel }) + '\n');
+    return indexRel;
+}
+export function refreshFigma(root, change) {
+    const manifest = artifactPath(root, change, MANIFEST);
+    if (existsSync(manifest))
+        appendFileSync(manifest, JSON.stringify({ refresh: true, at: new Date().toISOString() }) + '\n');
+}
+export function hasFigmaSession(root, change) {
+    return existsSync(artifactPath(root, change, '.opsx/figma-claude-settings.json')) || existsSync(artifactPath(root, change, MANIFEST));
+}
+export function writeOnce(file, text) {
+    mkdirSync(path.dirname(file), { recursive: true });
+    const temp = `${file}.${randomUUID()}.tmp`;
+    writeFileSync(temp, text, { flag: 'wx', mode: 0o600 });
+    try {
+        linkSync(temp, file);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        const old = readFileSync(file, 'utf8');
+        if (old !== text) {
+            renameSync(file, `${file}.invalid-${sha256(old)}`); // Keep corruption evidence; a fresh response can repair the cache.
+            linkSync(temp, file);
+        }
+    }
+    finally {
+        unlinkSync(temp);
+    }
+}
+function readIndex(root, change, relative) {
+    const file = artifactPath(root, change, relative);
+    if (!existsSync(file))
+        return undefined;
+    try {
+        const text = readFileSync(file, 'utf8');
+        if (path.basename(file) !== `${sha256(text)}.index.json`)
+            return undefined;
+        const value = JSON.parse(text);
+        if (!/^[a-f0-9]{64}$/.test(value.responseSha256))
+            return undefined;
+        const raw = artifactPath(root, change, `sources/figma/raw/${value.responseSha256}.json`);
+        if (!existsSync(raw) || sha256(readFileSync(raw)) !== value.responseSha256)
+            return undefined;
+        const expected = projectMetadata(JSON.parse(readFileSync(raw, 'utf8')), value.source);
+        if (JSON.stringify(expected) !== JSON.stringify(value))
+            return undefined;
+        return value;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/figma/claude.d.ts

@@ -0,0 +1,14 @@
+interface HookInput {
+    hook_event_name: string;
+    cwd: string;
+    tool_name: string;
+    tool_input?: Record<string, unknown>;
+    tool_response?: unknown;
+    tool_use_id?: string;
+    session_id?: string;
+}
+/** Session-scoped transport, never a worker dispatcher or an authentication client. */
+export declare function figmaHook(root: string, change: string, event: HookInput, minImagePixels?: number): Record<string, unknown>;
+export declare function claudeFigmaSettings(cli: string, root: string, change: string, minImagePixels?: number): Record<string, unknown>;
+export {};
+//# sourceMappingURL=claude.d.ts.map

package/dist/figma/claude.js

@@ -0,0 +1,121 @@
+import { readFileSync, realpathSync } from 'node:fs';
+import { artifactPath, artifactRel, requireChange } from '../core/change.js';
+import { loadLedger } from '../core/sources.js';
+import { sha256 } from '../shared/hash.js';
+import { figmaSource, indexPage, normalizeNodeId, projectMetadata } from './index.js';
+import { unwrapClaudeResponse } from './response.js';
+import { cachedIndexes, collectedIndexes, figmaEpoch, persistIndex, writeOnce } from './cache.js';
+import { compatibleImages, guardImageRead, imagePixelLimit } from './media.js';
+const FRONT = new Set(['collect', 'parse', 'tech', 'plan', 'gate_a']);
+const MCP = /^mcp__(?:plugin_figma_figma|figma)__(.+)$/;
+/** Session-scoped transport, never a worker dispatcher or an authentication client. */
+export function figmaHook(root, change, event, minImagePixels) {
+    if (realpathSync(event.cwd) !== realpathSync(root))
+        return {};
+    const state = requireChange(root, change);
+    if (minImagePixels !== undefined)
+        imagePixelLimit(minImagePixels);
+    const pre = event.hook_event_name === 'PreToolUse';
+    if (!pre && event.hook_event_name !== 'PostToolUse')
+        return {};
+    if (pre && event.tool_name === 'Read' && minImagePixels)
+        return guardImageRead(root, event.tool_input ?? {}, minImagePixels);
+    const tool = MCP.exec(event.tool_name)?.[1];
+    if (!tool)
+        return {};
+    const media = () => !pre && minImagePixels ? compatibleImages(root, change, event.tool_response, minImagePixels) : {};
+    if (!FRONT.has(state.node))
+        return media(); // Coding retains full details and usable screenshots.
+    const deny = (reason) => ({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: reason } });
+    const replace = (value) => ({ hookSpecificOutput: { hookEventName: 'PostToolUse', updatedMCPToolOutput: [{ type: 'text', text: JSON.stringify(value) }] } });
+    const designSources = loadLedger(root, change, state.sourceRevision).items.filter(item => item.capability === 'design' && item.kind === 'url');
+    const sources = designSources
+        .flatMap(item => { try {
+        return [figmaSource(item.locator)];
+    }
+    catch {
+        return [];
+    } });
+    if (!sources.length)
+        return media(); // Only an explicitly configured image limit applies.
+    const input = event.tool_input ?? {};
+    const fileKeys = [...new Set(sources.map(source => source.fileKey))];
+    const fileKey = typeof input.fileKey === 'string' ? input.fileKey : fileKeys.length === 1 ? fileKeys[0] : undefined;
+    let nodeId;
+    try {
+        nodeId = typeof input.nodeId === 'string' && input.nodeId ? normalizeNodeId(input.nodeId) : undefined;
+    }
+    catch {
+        return pre ? deny('Smart Figma: nodeId 无效。') : replace({ ok: false, code: 'figma_node_invalid' });
+    }
+    if (state.node !== 'collect') {
+        const allowed = state.node === 'parse' ? ['get_metadata', 'get_screenshot']
+            : ['tech', 'plan'].includes(state.node) ? ['get_metadata', 'get_screenshot', 'get_design_context', 'get_variable_defs'] : [];
+        const known = fileKey && nodeId && collectedIndexes(root, change, designSources)
+            .some(index => index.source.fileKey === fileKey && index.candidates.some(node => node.id === nodeId));
+        if (!allowed.includes(tool) || !known)
+            return pre
+                ? deny('Smart Figma: parse 仅确认形态；tech/plan 仅核对复用与修改范围。请定向读取当前已采集索引中的候选 frame；来源范围、摘要或节点未确认，不能展开其他容器。')
+                : replace({ ok: false, code: 'figma_outside_scope' });
+        return media(); // Targeted evidence stays complete; only incompatible image blocks change.
+    }
+    if (tool !== 'get_metadata')
+        return pre ? deny('Smart Figma: collect 只做页面定位；形态在 parse 确认，复用适配在 tech 核对，完整实现证据在 coding 读取。') : {};
+    const epoch = figmaEpoch(root, change);
+    const cacheKey = sha256(JSON.stringify({ adapterVersion: 1, fileKey, nodeId, epoch }));
+    const cache = cachedIndexes(root, change);
+    const cached = cache.find(record => record.key === cacheKey);
+    let source = sources.find(item => item.fileKey === fileKey && item.nodeId === nodeId);
+    if (!source && fileKey && nodeId) {
+        // Descend only into explicitly returned unresolved containers, never page internals.
+        for (const record of cache) {
+            const parent = record.index;
+            if (parent?.source.fileKey === fileKey && parent.unresolved.some(node => node.id === nodeId && ['page', 'canvas', 'section', 'document'].includes(node.type))) {
+                source = figmaSource(`https://www.figma.com/design/${fileKey}?node-id=${nodeId}`);
+                break;
+            }
+        }
+    }
+    if (!source)
+        return pre ? deny('Smart Figma: 请求不在登记的设计范围或待展开容器内；请使用页面索引，不能展开页面子树。') : replace({ ok: false, code: 'figma_outside_scope' });
+    if (pre) {
+        if (cached)
+            return deny(`Smart Figma: 本次 collect 已取得该索引，不再抓取。${JSON.stringify({ indexPath: artifactRel(change, cached.indexRel), ...indexPage(cached.index, 0, 7500) })}`);
+        const parent = cache.find(row => row.index.source.fileKey === fileKey
+            && (row.index.candidates.some(node => node.id === nodeId)
+                || row.index.containers.some(node => node.id === nodeId && node.childrenObserved)));
+        if (parent && source.nodeId) {
+            const rawFile = artifactPath(root, change, `sources/figma/raw/${parent.index.responseSha256}.json`);
+            const projected = projectMetadata(JSON.parse(readFileSync(rawFile, 'utf8')), source);
+            const indexRel = persistIndex(root, change, cacheKey, projected);
+            return deny(`Smart Figma: 已有响应包含此范围，无需再次抓取。${JSON.stringify({ indexPath: artifactRel(change, indexRel), ...indexPage(projected, 0, 7500) })}`);
+        }
+        return {};
+    }
+    const response = unwrapClaudeResponse(event.tool_response, { root, sessionId: event.session_id });
+    const raw = JSON.stringify(response);
+    const rawRel = `sources/figma/raw/${sha256(raw)}.json`;
+    const rawFile = artifactPath(root, change, rawRel);
+    writeOnce(rawFile, raw);
+    try {
+        const index = projectMetadata(response, source);
+        const indexRel = persistIndex(root, change, cacheKey, index);
+        return replace({ ok: true, indexPath: artifactRel(change, indexRel), ...indexPage(index, 0, 7500) });
+    }
+    catch (error) {
+        return replace({ ok: false, code: 'figma_index_failed', error: error.message,
+            evidence: artifactRel(change, rawRel), instruction: '采集未完成；保留错误，不把缺失索引当作空设计。' });
+    }
+}
+export function claudeFigmaSettings(cli, root, change, minImagePixels) {
+    requireChange(root, change);
+    const quote = (value) => `'${value.replace(/'/g, `'"'"'`)}'`;
+    const command = [process.execPath, cli, 'sources', 'figma', 'hook', '--project-root', root, '--change', change,
+        ...(minImagePixels === undefined ? [] : ['--min-image-pixels', String(imagePixelLimit(minImagePixels))])].map(quote).join(' ');
+    const matcher = '^mcp__(plugin_figma_figma|figma)__.*$';
+    return { hooks: {
+            PreToolUse: [{ matcher: minImagePixels === undefined ? matcher : '^(Read|mcp__(plugin_figma_figma|figma)__.*)$', hooks: [{ type: 'command', command, timeout: 20 }] }],
+            PostToolUse: [{ matcher, hooks: [{ type: 'command', command, timeout: 20 }] }],
+        } };
+}
+//# sourceMappingURL=claude.js.map

package/dist/figma/collect.d.ts

@@ -0,0 +1,3 @@
+/** undefined = not opted in; null = scoped source incomplete, never covered by an unrelated design file. */
+export declare function collectSmartFigma(root: string, change: string, locator: string): string | null | undefined;
+//# sourceMappingURL=collect.d.ts.map

package/dist/figma/collect.js

@@ -0,0 +1,57 @@
+import { artifactPath } from '../core/change.js';
+import { sha256 } from '../shared/hash.js';
+import { AppError } from '../shared/errors.js';
+import { cachedIndexes, hasFigmaSession, writeOnce } from './cache.js';
+import { FIGMA_ADAPTER_VERSION, figmaSource } from './index.js';
+/** undefined = not opted in; null = scoped source incomplete, never covered by an unrelated design file. */
+export function collectSmartFigma(root, change, locator) {
+    if (!hasFigmaSession(root, change))
+        return undefined;
+    let source;
+    try {
+        source = figmaSource(locator);
+    }
+    catch {
+        return undefined;
+    }
+    const cache = cachedIndexes(root, change).filter(row => row.index.source.fileKey === source.fileKey);
+    const first = cache.find(row => row.index.source.url === source.url);
+    if (!first)
+        return null;
+    const queue = [first];
+    const visited = new Set();
+    const parts = [];
+    while (queue.length) {
+        const row = queue.shift();
+        if (visited.has(row.indexRel))
+            continue;
+        visited.add(row.indexRel);
+        parts.push(row.index);
+        for (const node of row.index.unresolved) {
+            const expanded = cache.find(child => child.index.source.nodeId === node.id && child.index.source.url !== row.index.source.url);
+            if (!expanded)
+                return null;
+            if (visited.has(expanded.indexRel))
+                return null; // A cyclic/inconsistent response cannot prove complete coverage.
+            queue.push(expanded);
+        }
+    }
+    const nodes = new Map();
+    for (const part of parts)
+        for (const node of part.candidates) {
+            const old = nodes.get(node.id);
+            if (old && (old.name !== node.name || old.type !== node.type || JSON.stringify(old.bounds) !== JSON.stringify(node.bounds))) {
+                throw new AppError('figma_snapshot_conflict', `页面 ${node.id} 在采集响应中不一致，需刷新来源`);
+            }
+            nodes.set(node.id, node);
+        }
+    const artifact = { adapter: 'smart-figma', version: FIGMA_ADAPTER_VERSION, source, status: 'candidates',
+        candidates: [...nodes.values()].sort((a, b) => a.id.localeCompare(b.id, 'en', { numeric: true })),
+        indexes: [...visited].sort(), evidence: parts.map(part => part.responseSha256),
+        note: '结构候选，不推断业务映射；parse 可确认形态，tech/plan 可定向核对复用与范围；完整实现证据在 coding 读取。' };
+    const text = JSON.stringify(artifact, null, 2) + '\n';
+    const relative = `sources/figma/pages-${sha256(text)}.json`;
+    writeOnce(artifactPath(root, change, relative), text);
+    return relative;
+}
+//# sourceMappingURL=collect.js.map

package/dist/figma/index.d.ts

@@ -0,0 +1,35 @@
+export declare const FIGMA_ADAPTER_VERSION = 2;
+export interface FigmaSource {
+    url: string;
+    fileKey: string;
+    nodeId?: string;
+}
+export interface DesignNode {
+    id: string;
+    name: string;
+    type: string;
+    parent?: string;
+    bounds?: number[];
+    childrenObserved: boolean;
+}
+export interface PageIndex {
+    adapter: 'smart-figma';
+    version: number;
+    source: FigmaSource;
+    responseSha256: string;
+    roots: DesignNode[];
+    candidates: DesignNode[];
+    containers: DesignNode[];
+    leaves: DesignNode[];
+    unresolved: DesignNode[];
+    status: 'candidates' | 'needs-container-expansion';
+}
+export declare function normalizeNodeId(value: string): string;
+export declare function figmaSource(value: string): FigmaSource;
+/** Parse only complete XML documents. Never infer an empty design from sparse metadata. */
+export declare function projectMetadata(response: unknown, source: FigmaSource): PageIndex;
+/** Bounded model view; full candidates remain in the machine artifact, with explicit pagination. */
+export declare function indexPage(index: Omit<PageIndex, 'leaves'> & {
+    leaves?: DesignNode[];
+}, offset?: number, budget?: number): Record<string, unknown>;
+//# sourceMappingURL=index.d.ts.map