@birdie_moblie/open_spec 2.1.7

package/dist/figma/index.js

@@ -0,0 +1,178 @@
+import { SaxesParser } from 'saxes';
+import { sha256 } from '../shared/hash.js';
+import { AppError } from '../shared/errors.js';
+export const FIGMA_ADAPTER_VERSION = 2;
+const CONTAINERS = new Set(['document', 'canvas', 'page', 'section']);
+const CANDIDATES = new Set(['frame', 'component', 'instance', 'component-set', 'group']);
+// Known drawing primitives cannot contain page candidates. Retain their identity
+// in the full index and raw response, without asking collect to expand them.
+const LEAVES = new Set(['text', 'rectangle', 'rounded-rectangle', 'ellipse', 'line', 'vector', 'star', 'regular-polygon', 'polygon', 'slice']);
+export function normalizeNodeId(value) {
+    const id = value.replace(/-/g, ':');
+    if (!/^I?\d+:\d+(?:;\d+:\d+)*$/.test(id))
+        throw new AppError('figma_node_invalid', 'Figma nodeId 格式无效');
+    return id;
+}
+export function figmaSource(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new AppError('figma_url_invalid', '需要完整 Figma URL');
+    }
+    const match = url.pathname.match(/^\/(?:design|file|proto)\/([a-zA-Z0-9]+)(?:\/|$)/);
+    if (url.protocol !== 'https:' || !['figma.com', 'www.figma.com'].includes(url.hostname) || url.port || url.username || url.password || !match) {
+        throw new AppError('figma_url_invalid', '需要官方 Figma design/file URL');
+    }
+    const nodeId = url.searchParams.has('node-id') ? normalizeNodeId(url.searchParams.get('node-id')) : undefined;
+    return { url: `https://www.figma.com/design/${match[1]}${nodeId ? `?node-id=${nodeId.replace(':', '-')}` : ''}`, fileKey: match[1], ...(nodeId ? { nodeId } : {}) };
+}
+/** Parse only complete XML documents. Never infer an empty design from sparse metadata. */
+export function projectMetadata(response, source) {
+    const encoded = JSON.stringify(response);
+    if (Buffer.byteLength(encoded) > 16 * 1024 * 1024)
+        throw new AppError('figma_response_too_large', '响应超过 16 MiB；需缩小来源容器');
+    const blocks = textBlocks(response);
+    const docs = blocks.filter(text => text.trimStart().startsWith('<'));
+    if (!docs.length && !source.nodeId) {
+        const catalog = blocks.find(text => text.startsWith('No nodeId was provided. Listing the top-level pages of the document.') && text.includes('\nTop-level pages of the document:\n'));
+        if (catalog) {
+            const lines = catalog.split('\nTop-level pages of the document:\n')[1].trim().split('\n');
+            const pages = lines.map(line => {
+                const match = /^- (\d+:\d+): (.+)$/.exec(line);
+                if (!match)
+                    throw new AppError('figma_catalog_invalid', '官方画布目录格式不完整');
+                return { id: match[1], name: match[2], type: 'page', childrenObserved: false };
+            });
+            if (new Set(pages.map(page => page.id)).size !== pages.length)
+                throw new AppError('figma_catalog_invalid', '画布目录含重复节点');
+            return { adapter: 'smart-figma', version: FIGMA_ADAPTER_VERSION, source, responseSha256: sha256(encoded),
+                roots: pages, candidates: [], containers: pages, leaves: [], unresolved: pages, status: 'needs-container-expansion' };
+        }
+    }
+    if (!docs.length)
+        throw new AppError('figma_metadata_missing', 'MCP 未返回完整 XML metadata；不能宣称采集成功');
+    const trees = [];
+    let count = 0;
+    for (const xml of docs) {
+        const stack = [];
+        const parser = new SaxesParser({ xmlns: false });
+        parser.on('doctype', () => { throw new Error('DOCTYPE is forbidden'); });
+        parser.on('opentag', tag => {
+            if (stack.length > 512)
+                throw new Error('XML too deep');
+            if (++count > 100000)
+                throw new Error('XML node budget exceeded');
+            const a = tag.attributes;
+            if (typeof a.id !== 'string')
+                throw new Error('Node id missing');
+            const id = normalizeNodeId(a.id);
+            const dimensions = ['x', 'y', 'width', 'height'].map(key => Number(a[key]));
+            const node = { id, name: String(a.name ?? ''), type: tag.name.toLowerCase(), childrenObserved: false };
+            if (stack.length)
+                node.parent = stack.at(-1).node.id;
+            if (dimensions.every(Number.isFinite))
+                node.bounds = dimensions;
+            const tree = { node, children: [] };
+            if (stack.length) {
+                stack.at(-1).children.push(tree);
+                stack.at(-1).node.childrenObserved = true;
+            }
+            else
+                trees.push(tree);
+            stack.push(tree);
+        });
+        parser.on('closetag', () => { stack.pop(); });
+        parser.on('error', error => { throw error; });
+        try {
+            parser.write(xml).close();
+        }
+        catch (error) {
+            throw new AppError('figma_metadata_invalid', `XML 不完整或无效: ${error.message}`);
+        }
+    }
+    const nodes = new Map();
+    const pending = [...trees];
+    while (pending.length) {
+        const tree = pending.pop();
+        if (nodes.has(tree.node.id))
+            throw new AppError('figma_duplicate_node', `响应含重复节点: ${tree.node.id}`);
+        nodes.set(tree.node.id, tree);
+        pending.push(...tree.children);
+    }
+    const roots = source.nodeId ? [nodes.get(source.nodeId)] : trees;
+    if (roots.some(root => !root))
+        throw new AppError('figma_root_missing', '返回内容不含请求节点；不能使用服务端回退的其他页面');
+    const candidates = [];
+    const containers = [];
+    const leaves = [];
+    const unresolved = [];
+    const queue = [...roots];
+    while (queue.length) {
+        const tree = queue.shift();
+        if (CONTAINERS.has(tree.node.type)) {
+            containers.push(tree.node);
+            if (tree.children.length)
+                queue.push(...tree.children);
+            else
+                unresolved.push(tree.node);
+        }
+        else if (CANDIDATES.has(tree.node.type))
+            candidates.push(tree.node);
+        else if (LEAVES.has(tree.node.type) && !tree.children.length)
+            leaves.push(tree.node);
+        else
+            unresolved.push(tree.node); // Unknown containers are not silently discarded or expanded as pages.
+    }
+    const sort = (values) => values.sort((a, b) => a.id.localeCompare(b.id, 'en', { numeric: true }));
+    return { adapter: 'smart-figma', version: FIGMA_ADAPTER_VERSION, source, responseSha256: sha256(encoded),
+        roots: roots.map(root => root.node), candidates: sort(candidates), containers: sort(containers), leaves: sort(leaves), unresolved: sort(unresolved),
+        status: unresolved.length ? 'needs-container-expansion' : 'candidates' };
+}
+function textBlocks(value) {
+    if (typeof value === 'string') {
+        if (value.trimStart().startsWith('<'))
+            return [value];
+        try {
+            return textBlocks(JSON.parse(value));
+        }
+        catch {
+            return [value];
+        }
+    }
+    if (Array.isArray(value))
+        return value.flatMap(textBlocks);
+    if (value && typeof value === 'object') {
+        const obj = value;
+        if (obj.isError === true)
+            throw new AppError('figma_tool_failed', '官方 MCP 返回错误，未形成页面索引');
+        if (obj.type === 'text' && typeof obj.text === 'string')
+            return [obj.text];
+        if (Array.isArray(obj.content))
+            return textBlocks(obj.content);
+    }
+    return [];
+}
+/** Bounded model view; full candidates remain in the machine artifact, with explicit pagination. */
+export function indexPage(index, offset = 0, budget = 8000) {
+    const entries = [...index.candidates.map(node => ({ ...node, role: 'candidate' })), ...index.unresolved.map(node => ({ ...node, role: 'unresolved' }))];
+    if (!Number.isSafeInteger(offset) || offset < 0 || offset > entries.length || budget < 1024)
+        throw new AppError('figma_page_invalid', '索引分页参数无效');
+    const result = { adapter: index.adapter, version: index.version, source: index.source,
+        status: index.status, total: entries.length, candidateCount: index.candidates.length, offset, entries: [],
+        unresolvedCount: index.unresolved.length, leafCount: index.leaves?.length ?? null, note: '页面候选，不推断业务角色；无子层不表示设计为空。parse 可确认形态，tech/plan 可定向核对复用与范围；完整实现证据在 coding 读取。' };
+    const candidates = result.entries;
+    for (const node of entries.slice(offset)) {
+        candidates.push(node);
+        if (Buffer.byteLength(JSON.stringify(result)) > budget - 100) {
+            candidates.pop();
+            break;
+        }
+    }
+    if (!candidates.length && offset < entries.length)
+        throw new AppError('figma_entry_too_large', '单个候选超过输出预算，完整索引仍保留');
+    result.nextOffset = offset + candidates.length < entries.length ? offset + candidates.length : null;
+    return result;
+}
+//# sourceMappingURL=index.js.map

package/dist/figma/media.d.ts

@@ -0,0 +1,5 @@
+/** Provider-specific opt-in. Production assets are never resized or rewritten. */
+export declare function imagePixelLimit(value: string | number): number;
+export declare function guardImageRead(root: string, input: Record<string, unknown>, limit: number): Record<string, unknown>;
+export declare function compatibleImages(root: string, change: string, response: unknown, limit: number): Record<string, unknown>;
+//# sourceMappingURL=media.d.ts.map

package/dist/figma/media.js

@@ -0,0 +1,77 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { artifactPath, artifactRel } from '../core/change.js';
+import { resolveInside } from '../shared/paths.js';
+import { sha256 } from '../shared/hash.js';
+import { writeOnce } from './cache.js';
+/** Provider-specific opt-in. Production assets are never resized or rewritten. */
+export function imagePixelLimit(value) {
+    const limit = Number(value);
+    if (!Number.isSafeInteger(limit) || limit < 1)
+        throw new Error('min-image-pixels 必须为正整数');
+    return limit;
+}
+function pngSize(bytes) {
+    if (bytes.length < 24 || bytes.subarray(0, 8).toString('hex') !== '89504e470d0a1a0a'
+        || bytes.toString('ascii', 12, 16) !== 'IHDR')
+        return;
+    const width = bytes.readUInt32BE(16), height = bytes.readUInt32BE(20);
+    return width && height ? { width, height } : undefined;
+}
+export function guardImageRead(root, input, limit) {
+    if (typeof input.file_path !== 'string')
+        return {};
+    const relative = path.isAbsolute(input.file_path) ? path.relative(root, input.file_path) : input.file_path;
+    let file;
+    try {
+        file = resolveInside(root, relative);
+    }
+    catch {
+        return {};
+    } // Never inspect another project.
+    if (!existsSync(file) || !statSync(file).isFile() || statSync(file).size > 20 * 1024 * 1024)
+        return {};
+    const size = pngSize(readFileSync(file));
+    if (!size || size.width * size.height >= limit)
+        return {};
+    return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny',
+            permissionDecisionReason: `当前会话的模型图片限制为 ${limit} 总像素；此 PNG 为 ${size.width}×${size.height}。原文件可用于应用，请读取父级按钮/组件/页面截图观察，不通过 Read 重送这张小图。` } };
+}
+export function compatibleImages(root, change, response, limit) {
+    // Claude currently delivers either content blocks directly or an MCP result envelope.
+    const envelope = response && typeof response === 'object' && !Array.isArray(response) ? response : undefined;
+    const blocks = Array.isArray(response) ? response : envelope?.content;
+    if (!Array.isArray(blocks))
+        return {};
+    let changed = false;
+    const raw = JSON.stringify(response);
+    const rawRel = `.opsx/figma-media/${sha256(raw)}.response.json`;
+    const content = blocks.map(block => {
+        if (!block || typeof block !== 'object' || block.type !== 'image')
+            return block;
+        const data = block.data ?? (block.source?.type === 'base64' ? block.source.data : undefined);
+        if (typeof data !== 'string')
+            return block;
+        const bytes = Buffer.from(data, 'base64'), size = pngSize(bytes);
+        if (!size || size.width * size.height >= limit)
+            return block;
+        const relative = `.opsx/figma-media/${sha256(bytes)}.png`;
+        const file = artifactPath(root, change, relative);
+        mkdirSync(path.dirname(file), { recursive: true });
+        if (existsSync(file)) {
+            if (!readFileSync(file).equals(bytes))
+                throw new Error('Figma 原图归档摘要不符');
+        }
+        else
+            writeFileSync(file, bytes, { flag: 'wx' });
+        changed = true;
+        return { type: 'text', text: JSON.stringify({ kind: 'figma-image-input-limit', ...size,
+                minImagePixels: limit, imagePath: artifactRel(change, relative), rawEvidencePath: artifactRel(change, rawRel),
+                instruction: '原图已完整保存，下载未失败；用于应用时保持原件。当前模型不接收此尺寸，请读取父级按钮/组件/页面截图观察，不通过 Read 重送小图。' }) };
+    });
+    if (!changed)
+        return {};
+    writeOnce(artifactPath(root, change, rawRel), raw);
+    return { hookSpecificOutput: { hookEventName: 'PostToolUse', updatedMCPToolOutput: envelope ? { ...envelope, content } : content } };
+}
+//# sourceMappingURL=media.js.map

package/dist/figma/response.d.ts

@@ -0,0 +1,9 @@
+/** Claude moves large MCP results to its session directory BEFORE PostToolUse.
+ * Accept only that precise envelope and the current host session's tool-results file.
+ * Instructions inside the envelope or fetched source are data, never commands.
+ */
+export declare function unwrapClaudeResponse(response: unknown, context: {
+    root: string;
+    sessionId?: string;
+}, projectsRoot?: string): unknown;
+//# sourceMappingURL=response.d.ts.map

package/dist/figma/response.js

@@ -0,0 +1,27 @@
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { readFileSync, statSync } from 'node:fs';
+import { resolveInside } from '../shared/paths.js';
+import { AppError } from '../shared/errors.js';
+/** Claude moves large MCP results to its session directory BEFORE PostToolUse.
+ * Accept only that precise envelope and the current host session's tool-results file.
+ * Instructions inside the envelope or fetched source are data, never commands.
+ */
+export function unwrapClaudeResponse(response, context, projectsRoot = path.join(homedir(), '.claude/projects')) {
+    if (typeof response !== 'string')
+        return response;
+    const match = response.match(/^Error: result \([\d,]+ characters\) exceeds maximum allowed tokens\. Output has been saved to ([^\n]+)\.\r?\nFormat: JSON array with schema:/);
+    if (!match)
+        return response;
+    if (!context.sessionId || !/^[a-f0-9-]{36}$/.test(context.sessionId))
+        throw new AppError('figma_session_invalid', '大响应缺少当前 Claude session id');
+    const base = path.join(projectsRoot, context.root.replace(/[^a-zA-Z0-9]/g, '-'), context.sessionId, 'tool-results');
+    const relative = path.relative(base, match[1]);
+    if (!/^mcp-(?:plugin_figma_figma|figma)-get_metadata-[\d]+\.txt$/.test(relative))
+        throw new AppError('figma_result_outside_session', '大响应文件不属于当前 Figma 调用的会话目录');
+    const file = resolveInside(base, relative, 'figma_result_outside_session');
+    if (!statSync(file).isFile() || statSync(file).size > 16 * 1024 * 1024)
+        throw new AppError('figma_response_too_large', '大响应文件无效或超过 16 MiB');
+    return JSON.parse(readFileSync(file, 'utf8'));
+}
+//# sourceMappingURL=response.js.map

package/dist/hooks/command-context.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import type { WorkerPacket } from '../core/types.js';
+export declare const CommandContextEvidenceSchema: z.ZodObject<{
+    path: z.ZodString;
+    digest: z.ZodString;
+}, z.core.$strict>;
+export type CommandContextEvidence = z.infer<typeof CommandContextEvidenceSchema>;
+/** Generic invocation facts; host policies remain outside the scheduler. */
+export declare function prepareCommandContext(root: string, change: string, relative: string, runId: string, hookId: string, packet?: WorkerPacket): {
+    evidence: {
+        path: string;
+        digest: string;
+    };
+    env: {
+        OPENSPEC_COMMAND_CONTEXT: string;
+    };
+};
+export declare function commandContextCurrent(root: string, evidence: CommandContextEvidence): boolean;
+//# sourceMappingURL=command-context.d.ts.map

package/dist/hooks/command-context.js

@@ -0,0 +1,33 @@
+import path from 'node:path';
+import { z } from 'zod';
+import { exists, writeJson } from '../shared/fs.js';
+import { sha256File } from '../shared/hash.js';
+import { resolveInside } from '../shared/paths.js';
+import { codeChangeScope } from '../core/code-changes.js';
+import { artifactRel, requireChange } from '../core/change.js';
+export const CommandContextEvidenceSchema = z.object({ path: z.string(), digest: z.string() }).strict();
+/** Generic invocation facts; host policies remain outside the scheduler. */
+export function prepareCommandContext(root, change, relative, runId, hookId, packet) {
+    const state = requireChange(root, change);
+    const changesCode = packet && (packet.stepId.startsWith('code-') || packet.stepId === 'repair-verify');
+    const scope = changesCode ? codeChangeScope(root, state, packet) : {
+        workerChangedFiles: [], changedFiles: packet ? [] : state.engineChangedFiles, changeChangedFiles: state.engineChangedFiles,
+    };
+    const file = resolveInside(root, relative, 'command_context_outside_project');
+    writeJson(file, {
+        version: 1, projectRoot: root, change: { name: change, root: path.join(root, artifactRel(change, '.')) },
+        runId, hookId, worker: { id: packet?.workerId ?? runId, stepId: packet?.stepId ?? 'verify' },
+        task: packet?.task ?? null, ...scope,
+    });
+    return { evidence: { path: relative, digest: sha256File(file) }, env: { OPENSPEC_COMMAND_CONTEXT: file } };
+}
+export function commandContextCurrent(root, evidence) {
+    try {
+        const file = resolveInside(root, evidence.path, 'command_context_outside_project');
+        return exists(file) && sha256File(file) === evidence.digest;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=command-context.js.map

package/dist/hooks/engine.d.ts

@@ -0,0 +1,61 @@
+import type { ProjectConfig, ProjectHook } from '../config/schema.js';
+import type { ExecuteHookDescriptor, SourceCapability, SourceItem, TaskInitContext } from '../core/types.js';
+export declare function hooksFor(config: ProjectConfig, stage: ProjectHook['stage']): ProjectHook[];
+export interface HookEntryCheck {
+    hook: string;
+    use: string;
+    ok: boolean;
+    code?: string;
+    error?: string;
+}
+/**
+ * 按运行时相同的规则预先解析配置中的全部插件入口（collect 解析 adapter 并核对 capability，其余走 pluginHook），
+ * 让入口缺失、类型/阶段不符在安装与 doctor 时暴露，而不是等到某个阶段运行才失败。
+ * 只证明接得上，不证明插件行为与之前一致。
+ */
+export declare function inspectHookEntries(projectRoot: string, config: ProjectConfig): HookEntryCheck[];
+export declare function buildTaskInitContext(projectRoot: string, config: ProjectConfig, category: string): TaskInitContext;
+/**
+ * repair-verify Worker 的初始化上下文：修复可能触及任何已完成 task 的代码，
+ * 因此下发这些 task 所属分类的 notes 以及匹配其中任一分类的 execute Hook（按 id 去重，保持配置顺序）。
+ */
+export declare function buildRepairInitContext(projectRoot: string, config: ProjectConfig, categories: string[]): TaskInitContext;
+/** parse/tech/plan Worker 的初始化上下文：该 stage 全部 hook 都以 descriptor 下发并要求回执。 */
+export declare function buildStageInitContext(projectRoot: string, config: ProjectConfig, stage: 'parse' | 'tech' | 'plan', capabilities?: SourceCapability[]): TaskInitContext;
+/** verify Worker 需要登记证据的 hook 清单（command 由引擎执行，也一并列出便于核对）。 */
+export declare function buildVerifyHookDescriptors(projectRoot: string, config: ProjectConfig): ExecuteHookDescriptor[];
+/**
+ * 在项目锁定的 marketplace 插件中查找 `skills/<name>/SKILL.md`。
+ * 宿主（如 Cursor）没有把 marketplace 插件注册成 skill 时，Worker 仍可按该路径读取。
+ * 任何 marketplace 未锁定 / cache 缺失都静默返回 undefined：path 只是提示，不是硬依赖。
+ */
+export declare function resolveSkillPath(projectRoot: string, config: ProjectConfig, skillName: string): string | undefined;
+export declare function hookDescriptor(projectRoot: string, hook: ProjectHook, config: ProjectConfig): ExecuteHookDescriptor;
+export interface CollectOutcome {
+    artifacts: string[];
+    sourceArtifacts: Array<{
+        sourceId: string;
+        path: string;
+    }>;
+    deferred: string[];
+    /** 没有 adapter 的 url source，被同 capability 的手工 file/text source 覆盖：`<hookId|unhandled>:<urlSourceId>:<manualSourceId>` */
+    covered: string[];
+    warnings: string[];
+}
+/**
+ * 按 capability 执行 collect 阶段 hook；无 adapter 时允许 notes/手工源。
+ *
+ * skill 型 hook（或没有 `use` 的 hook）无法自动采集 url source。skills 的 collect 节点要求 agent 用宿主工具人工采集后
+ * 以 `--source-file <capability>=<path>` 登记再重新 collect，因此同 capability 只要存在手工 file/text source，
+ * 对应 url source 就视为已被覆盖：它的 artifact 指向该手工产物，不再阻塞进入 parse。
+ */
+export declare function collectSources(projectRoot: string, changeName: string, config: ProjectConfig, items: SourceItem[], options?: {
+    refresh?: boolean;
+    checkpoint?: (sourceId: string, artifact: string, collection: NonNullable<SourceItem['collection']>) => void;
+}): CollectOutcome;
+export declare function fileHookDigest(projectRoot: string, hook: ProjectHook): string | null;
+/** preset scaffold 出来的模板带此标记；团队填写完删掉它，file hook 才算就位。 */
+export declare const TEMPLATE_MARKER = "<!-- openspec:fill-me -->";
+export type FileHookState = 'missing' | 'unfilled' | 'ready';
+export declare function fileHookState(projectRoot: string, relativePath: string): FileHookState;
+//# sourceMappingURL=engine.d.ts.map