@birdie_moblie/open_spec 2.1.7

package/dist/hooks/engine.js

@@ -0,0 +1,314 @@
+import { exists, readText } from '../shared/fs.js';
+import { sha256 } from '../shared/hash.js';
+import { effectiveTaskCategories } from '../config/schema.js';
+import { discoverPluginDirs, marketplaceRootForProject, resolveAdapterEntry, readMarketplaceLock, parseSelector } from '../marketplace/adapters.js';
+import { execFile } from '../shared/exec.js';
+import { AppError } from '../shared/errors.js';
+import { writeText } from '../shared/fs.js';
+import path from 'node:path';
+import { artifactPath } from '../core/change.js';
+import { resolveInside } from '../shared/paths.js';
+import { collectSmartFigma } from '../figma/collect.js';
+import { pluginHook } from './plugin-runtime.js';
+import { refreshFigma } from '../figma/cache.js';
+export function hooksFor(config, stage) {
+    return (config.hooks ?? []).filter((hook) => hook.stage === stage);
+}
+/**
+ * 按运行时相同的规则预先解析配置中的全部插件入口（collect 解析 adapter 并核对 capability，其余走 pluginHook），
+ * 让入口缺失、类型/阶段不符在安装与 doctor 时暴露，而不是等到某个阶段运行才失败。
+ * 只证明接得上，不证明插件行为与之前一致。
+ */
+export function inspectHookEntries(projectRoot, config) {
+    const checks = [];
+    for (const hook of config.hooks ?? []) {
+        const use = hook.use;
+        if (!use || (hook.stage === 'collect' && hook.type === 'skill'))
+            continue;
+        try {
+            if (hook.stage === 'collect') {
+                const adapter = resolveAdapterEntry(projectRoot, use).entry;
+                if (hook.capability && adapter.capability !== hook.capability) {
+                    throw new AppError('adapter_capability_mismatch', `adapter capability 不符: ${use}`);
+                }
+            }
+            else {
+                pluginHook(projectRoot, hook);
+            }
+            checks.push({ hook: hook.id, use, ok: true });
+        }
+        catch (error) {
+            checks.push({
+                hook: hook.id, use, ok: false,
+                code: error instanceof AppError ? error.code : 'hook_entry_check_failed',
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return checks;
+}
+export function buildTaskInitContext(projectRoot, config, category) {
+    const categoryConfig = effectiveTaskCategories(config)[category];
+    if (!categoryConfig) {
+        throw new AppError('task_category_unavailable', `task category 已不可用，请重新生成 plan: ${category}`);
+    }
+    const rules = [];
+    if (categoryConfig.notes)
+        rules.push({ source: 'category', text: categoryConfig.notes });
+    const hooks = hooksFor(config, 'execute')
+        .filter((hook) => !hook.taskCategories || hook.taskCategories.includes(category))
+        .map((hook) => hookDescriptor(projectRoot, hook, config));
+    return { category, rules, hooks };
+}
+/**
+ * repair-verify Worker 的初始化上下文：修复可能触及任何已完成 task 的代码，
+ * 因此下发这些 task 所属分类的 notes 以及匹配其中任一分类的 execute Hook（按 id 去重，保持配置顺序）。
+ */
+export function buildRepairInitContext(projectRoot, config, categories) {
+    const effective = effectiveTaskCategories(config);
+    const unique = [...new Set(categories)].filter((category) => effective[category]);
+    const rules = [];
+    for (const category of unique) {
+        const notes = effective[category]?.notes;
+        if (notes)
+            rules.push({ source: 'category', text: `[${category}] ${notes}` });
+    }
+    const hooks = hooksFor(config, 'execute')
+        .filter((hook) => !hook.taskCategories || hook.taskCategories.some((category) => unique.includes(category)))
+        .map((hook) => hookDescriptor(projectRoot, hook, config));
+    return { rules, hooks };
+}
+/** parse/tech/plan Worker 的初始化上下文：该 stage 全部 hook 都以 descriptor 下发并要求回执。 */
+export function buildStageInitContext(projectRoot, config, stage, capabilities) {
+    return {
+        rules: [],
+        hooks: hooksFor(config, stage).filter((hook) => !hook.capability || !capabilities || capabilities.includes(hook.capability)).map((hook) => hookDescriptor(projectRoot, hook, config)),
+    };
+}
+/** verify Worker 需要登记证据的 hook 清单（command 由引擎执行，也一并列出便于核对）。 */
+export function buildVerifyHookDescriptors(projectRoot, config) {
+    return hooksFor(config, 'verify').map((hook) => hookDescriptor(projectRoot, hook, config));
+}
+/**
+ * 在项目锁定的 marketplace 插件中查找 `skills/<name>/SKILL.md`。
+ * 宿主（如 Cursor）没有把 marketplace 插件注册成 skill 时，Worker 仍可按该路径读取。
+ * 任何 marketplace 未锁定 / cache 缺失都静默返回 undefined：path 只是提示，不是硬依赖。
+ */
+export function resolveSkillPath(projectRoot, config, skillName) {
+    for (const plugin of config.plugins ?? []) {
+        let root;
+        try {
+            root = marketplaceRootForProject(projectRoot, plugin.marketplace);
+        }
+        catch {
+            continue;
+        }
+        for (const dir of discoverPluginDirs(root)) {
+            if (path.basename(dir) !== plugin.name)
+                continue;
+            const candidate = path.join(dir, 'skills', skillName, 'SKILL.md');
+            if (exists(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+export function hookDescriptor(projectRoot, hook, config) {
+    const required = hook.required ?? true;
+    const purpose = hook.purpose === undefined ? {} : { purpose: hook.purpose };
+    if (hook.use) {
+        const { binding, skillPath } = pluginHook(projectRoot, hook);
+        if (hook.type === 'skill')
+            return { ...purpose, id: hook.id, type: 'skill', required, name: hook.use, path: skillPath, plugin: binding };
+        return { ...purpose, id: hook.id, type: 'command', required, command: `plugin:${hook.use}:${binding.operation}`, plugin: binding };
+    }
+    if (hook.type === 'notes' && hook.notes)
+        return { ...purpose, id: hook.id, type: 'notes', required, notes: hook.notes };
+    if (hook.type === 'skill' && hook.name) {
+        const skillPath = resolveSkillPath(projectRoot, config, hook.name);
+        return skillPath
+            ? { ...purpose, id: hook.id, type: 'skill', required, name: hook.name, path: skillPath }
+            : { ...purpose, id: hook.id, type: 'skill', required, name: hook.name };
+    }
+    if (hook.type === 'file' && hook.path) {
+        resolveInside(projectRoot, hook.path, 'hook_file_outside_project');
+        return { ...purpose, id: hook.id, type: 'file', required, path: hook.path };
+    }
+    if (hook.type === 'check' && hook.category && hook.description) {
+        return { ...purpose, id: hook.id, type: 'check', required, category: hook.category, description: hook.description };
+    }
+    if (hook.type === 'command' && hook.command)
+        return { ...purpose, id: hook.id, type: 'command', required, command: hook.command };
+    throw new AppError('invalid_execute_hook', `${hook.stage} hook 缺少必要字段: ${hook.id}`);
+}
+/**
+ * 按 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 function collectSources(projectRoot, changeName, config, items, options = {}) {
+    const artifacts = [];
+    const sourceArtifacts = [];
+    const deferred = [];
+    const covered = [];
+    const warnings = [];
+    const byCap = new Map();
+    for (const item of items) {
+        const list = byCap.get(item.capability) ?? [];
+        list.push(item);
+        byCap.set(item.capability, list);
+    }
+    const reusable = (item, relative, fingerprint) => {
+        const abs = artifactPath(projectRoot, changeName, relative);
+        return !options.refresh && item.artifact === relative && item.collection?.fingerprint === fingerprint
+            && exists(abs) && sha256(readText(abs)) === item.collection.artifactSha256;
+    };
+    const checkpoint = (item, relative, fingerprint) => {
+        options.checkpoint?.(item.id, relative, { fingerprint, artifactSha256: sha256(readText(artifactPath(projectRoot, changeName, relative))) });
+    };
+    const handled = new Set();
+    const smartHandled = new Set();
+    if (options.refresh)
+        refreshFigma(projectRoot, changeName);
+    for (const item of items) {
+        if (item.kind !== 'url' || item.capability !== 'design')
+            continue;
+        const smart = collectSmartFigma(projectRoot, changeName, item.locator);
+        if (smart === undefined)
+            continue;
+        handled.add(item.id);
+        smartHandled.add(item.id);
+        if (smart === null)
+            deferred.push(`smart-figma:${item.id}`);
+        else {
+            artifacts.push(smart);
+            sourceArtifacts.push({ sourceId: item.id, path: smart });
+            checkpoint(item, smart, sha256(JSON.stringify(['smart-figma', 1, item.locator, smart])));
+        }
+    }
+    const manualByCap = new Map();
+    for (const item of items) {
+        if (item.kind !== 'text' && item.kind !== 'file')
+            continue;
+        const relative = manualArtifact(item);
+        const abs = artifactPath(projectRoot, changeName, relative);
+        const content = item.kind === 'file'
+            ? readText(resolveInside(projectRoot, item.locator, 'source_file_outside_project'))
+            : item.locator;
+        const fingerprint = sha256(JSON.stringify([item.id, item.capability, item.kind, item.locator, sha256(content)]));
+        if (!reusable(item, relative, fingerprint))
+            writeText(abs, content);
+        checkpoint(item, relative, fingerprint);
+        artifacts.push(relative);
+        sourceArtifacts.push({ sourceId: item.id, path: relative });
+        handled.add(item.id);
+        if (!manualByCap.has(item.capability))
+            manualByCap.set(item.capability, { sourceId: item.id, path: relative });
+    }
+    const coverOrDefer = (label, item) => {
+        const manual = manualByCap.get(item.capability);
+        if (manual) {
+            delete item.adapter;
+            sourceArtifacts.push({ sourceId: item.id, path: manual.path });
+            handled.add(item.id);
+            covered.push(`${label}:${item.id}:${manual.sourceId}`);
+            return;
+        }
+        deferred.push(`${label}:${item.id}`);
+    };
+    for (const hook of hooksFor(config, 'collect')) {
+        const capability = hook.capability;
+        if (!capability)
+            continue;
+        const matched = (byCap.get(capability) ?? []).filter((item) => item.kind === 'url' && !smartHandled.has(item.id));
+        if (matched.length === 0)
+            continue;
+        if (hook.type === 'skill' || !hook.use) {
+            for (const item of matched)
+                coverOrDefer(hook.id, item);
+            continue;
+        }
+        const resolved = resolveAdapterEntry(projectRoot, hook.use);
+        const adapter = resolved.entry;
+        if (adapter.capability !== capability)
+            throw new AppError('adapter_capability_mismatch', `adapter capability 不符: ${hook.use}`);
+        const { marketplace } = parseSelector(hook.use);
+        const locked = readMarketplaceLock(projectRoot).marketplaces.find((entry) => entry.name === marketplace);
+        for (const item of matched) {
+            const op = adapter.operations.collect ?? adapter.operations.discovery;
+            const relative = op ? uniqueArtifact(op.artifact ?? `sources/artifacts/${item.capability}.md`, item.id) : null;
+            const fingerprint = sha256(JSON.stringify([item.id, item.capability, item.kind, item.locator, hook, adapter, locked]));
+            const produced = relative && reusable(item, relative, fingerprint)
+                ? { kind: 'artifact', path: relative }
+                : runAdapter(projectRoot, changeName, adapter, item, resolved.pluginRoot);
+            if (produced.kind === 'artifact') {
+                item.adapter = { use: hook.use, identity: resolved.identity };
+                checkpoint(item, produced.path, fingerprint);
+                artifacts.push(produced.path);
+                sourceArtifacts.push({ sourceId: item.id, path: produced.path });
+                handled.add(item.id);
+            }
+            else if (produced.kind === 'deferred')
+                coverOrDefer(hook.id, item);
+            else
+                warnings.push(produced.message);
+        }
+    }
+    for (const item of items) {
+        if (item.kind !== 'url' || handled.has(item.id))
+            continue;
+        if (deferred.some((entry) => entry.endsWith(`:${item.id}`)))
+            continue;
+        coverOrDefer('unhandled', item);
+    }
+    return {
+        artifacts: [...new Set(artifacts)],
+        sourceArtifacts,
+        deferred: [...new Set(deferred)],
+        covered: [...new Set(covered)],
+        warnings,
+    };
+}
+function manualArtifact(item) {
+    const extension = item.kind === 'file' ? path.extname(item.locator) || '.txt' : '.md';
+    return `sources/artifacts/${item.id}${extension}`;
+}
+function runAdapter(projectRoot, changeName, adapter, item, pluginRoot) {
+    const op = adapter.operations.collect ?? adapter.operations.discovery;
+    if (!op || adapter.kind === 'deferred' || adapter.kind === 'skill')
+        return { kind: 'deferred' };
+    const args = (op.args ?? []).map((arg) => arg.replaceAll('{locator}', item.locator).replaceAll('{pluginRoot}', pluginRoot));
+    const result = execFile(op.command.replaceAll('{pluginRoot}', pluginRoot), args, { cwd: projectRoot, timeoutMs: op.timeoutMs });
+    if (!result.ok) {
+        throw new AppError('adapter_failed', `adapter ${adapter.id} 执行失败: ${result.stderr || result.stdout}`);
+    }
+    const relative = uniqueArtifact(op.artifact ?? `sources/artifacts/${item.capability}.md`, item.id);
+    writeText(artifactPath(projectRoot, changeName, relative), result.stdout);
+    return { kind: 'artifact', path: relative };
+}
+function uniqueArtifact(template, sourceId) {
+    if (template.includes('{sourceId}'))
+        return template.replaceAll('{sourceId}', sourceId);
+    const extension = path.posix.extname(template);
+    const base = extension ? template.slice(0, -extension.length) : template;
+    return `${base}-${sourceId}${extension}`;
+}
+export function fileHookDigest(projectRoot, hook) {
+    if (hook.type !== 'file' || !hook.path)
+        return null;
+    const abs = resolveInside(projectRoot, hook.path, 'hook_file_outside_project');
+    if (!exists(abs))
+        return null;
+    return sha256(readText(abs));
+}
+/** preset scaffold 出来的模板带此标记；团队填写完删掉它，file hook 才算就位。 */
+export const TEMPLATE_MARKER = '<!-- openspec:fill-me -->';
+export function fileHookState(projectRoot, relativePath) {
+    const abs = resolveInside(projectRoot, relativePath, 'hook_file_outside_project');
+    if (!exists(abs))
+        return 'missing';
+    return readText(abs).includes(TEMPLATE_MARKER) ? 'unfilled' : 'ready';
+}
+//# sourceMappingURL=engine.js.map

package/dist/hooks/plugin-runtime.d.ts

@@ -0,0 +1,188 @@
+import { z } from 'zod';
+import { type AdapterOperation, type PluginIdentity } from '../marketplace/adapters.js';
+import type { ProjectHook } from '../config/schema.js';
+export declare const PluginBindingSchema: z.ZodObject<{
+    use: z.ZodString;
+    kind: z.ZodEnum<{
+        hook: "hook";
+        adapter: "adapter";
+    }>;
+    operation: z.ZodEnum<{
+        preview: "preview";
+        hook: "hook";
+        read: "read";
+    }>;
+    identity: z.ZodObject<{
+        name: z.ZodString;
+        marketplace: z.ZodString;
+        resolvedSha: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    inputFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    inputDescription: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type PluginBinding = z.infer<typeof PluginBindingSchema>;
+export declare const PluginReceiptSchema: z.ZodObject<{
+    binding: z.ZodObject<{
+        use: z.ZodString;
+        kind: z.ZodEnum<{
+            hook: "hook";
+            adapter: "adapter";
+        }>;
+        operation: z.ZodEnum<{
+            preview: "preview";
+            hook: "hook";
+            read: "read";
+        }>;
+        identity: z.ZodObject<{
+            name: z.ZodString;
+            marketplace: z.ZodString;
+            resolvedSha: z.ZodString;
+            digest: z.ZodString;
+        }, z.core.$strict>;
+        input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        inputFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        inputDescription: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    inputDigest: z.ZodString;
+    files: z.ZodRecord<z.ZodString, z.ZodString>;
+    outputs: z.ZodRecord<z.ZodString, z.ZodString>;
+    workerId: z.ZodOptional<z.ZodString>;
+    stepId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type PluginReceipt = z.infer<typeof PluginReceiptSchema>;
+export declare const PluginEvidenceSchema: z.ZodObject<{
+    path: z.ZodString;
+    sha256: z.ZodString;
+    binding: z.ZodObject<{
+        use: z.ZodString;
+        kind: z.ZodEnum<{
+            hook: "hook";
+            adapter: "adapter";
+        }>;
+        operation: z.ZodEnum<{
+            preview: "preview";
+            hook: "hook";
+            read: "read";
+        }>;
+        identity: z.ZodObject<{
+            name: z.ZodString;
+            marketplace: z.ZodString;
+            resolvedSha: z.ZodString;
+            digest: z.ZodString;
+        }, z.core.$strict>;
+        input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        inputFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        inputDescription: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    workerId: z.ZodOptional<z.ZodString>;
+    stepId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type PluginEvidence = z.infer<typeof PluginEvidenceSchema>;
+/** Keep dependency closures out of control responses and shared worker indexes. */
+export declare function savePluginEvidence(root: string, outputDir: string, receipt: PluginReceipt): PluginEvidence;
+export declare function pluginEvidenceCurrent(root: string, reference: PluginEvidence): boolean;
+export declare function pluginHook(projectRoot: string, hook: ProjectHook): {
+    binding: {
+        use: string;
+        kind: "hook" | "adapter";
+        operation: "preview" | "hook" | "read";
+        identity: {
+            name: string;
+            marketplace: string;
+            resolvedSha: string;
+            digest: string;
+        };
+        input?: Record<string, unknown> | undefined;
+        inputFiles?: string[] | undefined;
+        inputDescription?: string | undefined;
+    };
+    skillPath: string;
+} | {
+    binding: {
+        use: string;
+        kind: "hook" | "adapter";
+        operation: "preview" | "hook" | "read";
+        identity: {
+            name: string;
+            marketplace: string;
+            resolvedSha: string;
+            digest: string;
+        };
+        input?: Record<string, unknown> | undefined;
+        inputFiles?: string[] | undefined;
+        inputDescription?: string | undefined;
+    };
+    skillPath?: undefined;
+};
+export declare function sameIdentity(a: PluginIdentity, b: PluginIdentity): boolean;
+export declare function pluginBindingCurrent(root: string, binding: PluginBinding): boolean;
+export declare function resolvePluginCommand(root: string, binding: PluginBinding): {
+    operation: AdapterOperation;
+    pluginRoot: string;
+};
+export interface PluginSource {
+    id: string;
+    capability: string;
+    kind: string;
+    locator: string;
+    artifact: string;
+    artifactSha256: string;
+}
+export interface PluginContext {
+    version: 1;
+    operation: 'read' | 'preview' | 'hook';
+    projectRoot: string;
+    change: {
+        name: string;
+        root: string;
+    };
+    input: Record<string, unknown>;
+    outputDir: string;
+    worker?: {
+        workerId: string;
+        stepId: string;
+    };
+    source?: PluginSource;
+    sources?: PluginSource[];
+}
+export declare function readPluginInput(root: string, binding: Pick<PluginBinding, 'input' | 'inputFiles'>, file?: string): {
+    input: {
+        [x: string]: unknown;
+    };
+    files: string[];
+};
+export declare function digestFiles(root: string, files: string[]): Record<string, string>;
+export declare function digestsMatch(root: string, files: Record<string, string>): boolean;
+/** Commands run as argv with JSON stdin. Complete stdout/stderr never share a file. */
+export declare function runPluginCommand(root: string, binding: PluginBinding, context: PluginContext, inputFiles?: string[]): {
+    ok: boolean;
+    code: number;
+    receipt: {
+        binding: {
+            use: string;
+            kind: "hook" | "adapter";
+            operation: "preview" | "hook" | "read";
+            identity: {
+                name: string;
+                marketplace: string;
+                resolvedSha: string;
+                digest: string;
+            };
+            input?: Record<string, unknown> | undefined;
+            inputFiles?: string[] | undefined;
+            inputDescription?: string | undefined;
+        };
+        inputDigest: string;
+        files: Record<string, string>;
+        outputs: Record<string, string>;
+        workerId?: string | undefined;
+        stepId?: string | undefined;
+    };
+    data: unknown;
+    stdoutPath: string;
+    stderrPath: string;
+};
+export declare function pluginReceiptCurrent(root: string, receipt: PluginReceipt): boolean;
+//# sourceMappingURL=plugin-runtime.d.ts.map