@birdie_moblie/open_spec 2.1.7

package/dist/hooks/plugin-runtime.js

@@ -0,0 +1,198 @@
+import path from 'node:path';
+import { closeSync, openSync, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { z } from 'zod';
+import { exists, ensureDir, readJson, readText, writeJson, writeText } from '../shared/fs.js';
+import { sha256, sha256File } from '../shared/hash.js';
+import { resolveInside } from '../shared/paths.js';
+import { checkoutFingerprint } from '../shared/git.js';
+import { AppError } from '../shared/errors.js';
+import { PluginIdentitySchema, resolveAdapterEntry, resolveHookEntry } from '../marketplace/adapters.js';
+export const PluginBindingSchema = z.object({
+    use: z.string(), kind: z.enum(['adapter', 'hook']), operation: z.enum(['read', 'preview', 'hook']),
+    identity: PluginIdentitySchema, input: z.record(z.string(), z.unknown()).optional(),
+    inputFiles: z.array(z.string()).optional(), inputDescription: z.string().optional(),
+}).strict();
+export const PluginReceiptSchema = z.object({
+    binding: PluginBindingSchema, inputDigest: z.string(),
+    files: z.record(z.string(), z.string()), outputs: z.record(z.string(), z.string()),
+    workerId: z.string().optional(), stepId: z.string().optional(),
+}).strict();
+export const PluginEvidenceSchema = z.object({
+    path: z.string(), sha256: z.string(), binding: PluginBindingSchema,
+    workerId: z.string().optional(), stepId: z.string().optional(),
+}).strict();
+/** Keep dependency closures out of control responses and shared worker indexes. */
+export function savePluginEvidence(root, outputDir, receipt) {
+    const file = resolveInside(outputDir, 'receipt.json');
+    writeJson(file, receipt);
+    return { path: path.relative(root, file), sha256: sha256File(file), binding: receipt.binding,
+        ...(receipt.workerId ? { workerId: receipt.workerId } : {}), ...(receipt.stepId ? { stepId: receipt.stepId } : {}) };
+}
+export function pluginEvidenceCurrent(root, reference) {
+    try {
+        const file = resolveInside(root, reference.path, 'plugin_evidence_outside_project');
+        if (sha256File(file) !== reference.sha256)
+            return false;
+        const receipt = PluginReceiptSchema.parse(readJson(file));
+        return JSON.stringify(receipt.binding) === JSON.stringify(reference.binding)
+            && receipt.workerId === reference.workerId && receipt.stepId === reference.stepId
+            && pluginReceiptCurrent(root, receipt);
+    }
+    catch {
+        return false;
+    }
+}
+export function pluginHook(projectRoot, hook) {
+    const use = hook.use;
+    const preview = hook.operation === 'preview';
+    const resolved = preview ? resolveAdapterEntry(projectRoot, use) : resolveHookEntry(projectRoot, use);
+    const entry = resolved.entry;
+    if (preview) {
+        if (!('operations' in entry) || entry.kind !== 'command' || !entry.operations.preview)
+            throw new AppError('adapter_operation_missing', `adapter 不支持 preview: ${use}`);
+    }
+    else if (!('stages' in entry) || entry.type !== hook.type || hook.stage === 'collect' || !entry.stages.includes(hook.stage)) {
+        throw new AppError('plugin_hook_mismatch', `插件 Hook 类型或阶段不符: ${use} (${hook.stage}/${hook.type})`);
+    }
+    const inputDescription = 'operations' in entry ? entry.operations.preview?.inputDescription : entry.inputDescription;
+    const binding = {
+        use, kind: preview ? 'adapter' : 'hook', operation: preview ? 'preview' : 'hook', identity: resolved.identity,
+        ...(hook.input ? { input: hook.input } : {}), ...(hook.inputFiles ? { inputFiles: hook.inputFiles } : {}),
+        ...(inputDescription ? { inputDescription } : {}),
+    };
+    if ('type' in entry && entry.type === 'skill') {
+        const skillPath = resolveInside(resolved.pluginRoot, entry.path, 'plugin_skill_outside_root');
+        if (!exists(skillPath) || !statSync(skillPath).isFile())
+            throw new AppError('plugin_skill_missing', `插件技能不存在: ${use}`);
+        return { binding, skillPath };
+    }
+    return { binding };
+}
+export function sameIdentity(a, b) {
+    return a.name === b.name && a.marketplace === b.marketplace && a.resolvedSha === b.resolvedSha && a.digest === b.digest;
+}
+export function pluginBindingCurrent(root, binding) {
+    try {
+        const resolved = binding.kind === 'adapter' ? resolveAdapterEntry(root, binding.use) : resolveHookEntry(root, binding.use);
+        return sameIdentity(binding.identity, resolved.identity);
+    }
+    catch {
+        return false;
+    }
+}
+export function resolvePluginCommand(root, binding) {
+    const resolved = binding.kind === 'adapter' ? resolveAdapterEntry(root, binding.use) : resolveHookEntry(root, binding.use);
+    if (!sameIdentity(binding.identity, resolved.identity))
+        throw new AppError('plugin_identity_changed', `锁定插件已变化，停止旧 Worker 命令后用 worker create --refresh 显式刷新: ${binding.use}`);
+    const entry = resolved.entry;
+    const operation = 'operations' in entry
+        ? binding.operation === 'hook' ? undefined : entry.operations[binding.operation]
+        : entry.type === 'command' ? entry : undefined;
+    if (!operation)
+        throw new AppError('plugin_operation_missing', `入口不支持 ${binding.operation}: ${binding.use}`);
+    for (const token of [operation.command, ...(operation.args ?? [])]) {
+        if (!token.includes('{pluginRoot}'))
+            continue;
+        if (!token.startsWith('{pluginRoot}/') || token.indexOf('{pluginRoot}', 1) !== -1)
+            throw new AppError('plugin_entry_path_invalid', 'pluginRoot 必须是独立文件参数');
+        const file = resolveInside(resolved.pluginRoot, token.slice('{pluginRoot}/'.length), 'plugin_entry_outside_root');
+        if (!exists(file) || !statSync(file).isFile())
+            throw new AppError('plugin_entry_missing', `插件入口文件不存在: ${token}`);
+    }
+    return { operation, pluginRoot: resolved.pluginRoot };
+}
+export function readPluginInput(root, binding, file) {
+    const dynamic = file ? z.record(z.string(), z.unknown()).parse(readJson(resolveInside(root, file, 'plugin_input_outside_project'))) : {};
+    return { input: { ...binding.input, ...dynamic }, files: [...(binding.inputFiles ?? []), ...(file ? [file] : [])] };
+}
+export function digestFiles(root, files) {
+    return Object.fromEntries([...new Set(files)].map((file) => {
+        const absolute = resolveInside(root, file, 'plugin_dependency_outside_project');
+        if (!exists(absolute) || !statSync(absolute).isFile())
+            throw new AppError('plugin_dependency_missing', `依赖文件不存在: ${file}`);
+        return [path.relative(root, absolute).replaceAll('\\', '/'), sha256File(absolute)];
+    }));
+}
+export function digestsMatch(root, files) {
+    try {
+        return Object.entries(files).every(([file, digest]) => digestFiles(root, [file])[file] === digest);
+    }
+    catch {
+        return false;
+    }
+}
+/** Commands run as argv with JSON stdin. Complete stdout/stderr never share a file. */
+export function runPluginCommand(root, binding, context, inputFiles = []) {
+    const { operation, pluginRoot } = resolvePluginCommand(root, binding);
+    const substitute = (value) => value.replaceAll('{pluginRoot}', pluginRoot);
+    const checkoutBefore = binding.operation === 'hook' ? undefined : checkoutFingerprint(root);
+    const sourceFiles = [...(context.source ? [context.source] : []), ...(context.sources ?? [])]
+        .map((source) => path.relative(root, source.artifact));
+    const before = digestFiles(root, [...inputFiles, ...sourceFiles]);
+    ensureDir(context.outputDir);
+    const stdoutPath = resolveInside(context.outputDir, 'stdout.json');
+    const stderrPath = resolveInside(context.outputDir, 'stderr.log');
+    const inputPath = resolveInside(context.outputDir, 'input.json');
+    writeJson(inputPath, context);
+    const stdout = openSync(stdoutPath, 'w');
+    const stderr = openSync(stderrPath, 'w');
+    let result;
+    try {
+        result = spawnSync(substitute(operation.command), (operation.args ?? []).map(substitute), {
+            cwd: root, input: JSON.stringify(context), stdio: ['pipe', stdout, stderr],
+            timeout: operation.timeoutMs ?? 120000, killSignal: 'SIGKILL',
+        });
+    }
+    finally {
+        closeSync(stdout);
+        closeSync(stderr);
+    }
+    let ok = result.status === 0 && !result.error;
+    let error = result.error?.message ?? (result.signal ? `命令终止: ${result.signal}` : '');
+    let data;
+    let dependencies = [];
+    let artifacts = [];
+    try {
+        if (ok) {
+            const envelope = z.object({ data: z.unknown(), dependencies: z.array(z.string()).optional(), artifacts: z.array(z.string()).optional() }).strict().parse(readJson(stdoutPath));
+            if (!Object.hasOwn(envelope, 'data'))
+                throw new Error('stdout 缺少 data');
+            data = envelope.data;
+            dependencies = envelope.dependencies ?? [];
+            artifacts = (envelope.artifacts ?? []).map((file) => path.relative(root, resolveInside(context.outputDir, file, 'plugin_artifact_outside_output')));
+        }
+        // A reader may never alter its frozen source or the supplied input document.
+        if (checkoutBefore && checkoutFingerprint(root) !== checkoutBefore)
+            throw new Error('只读操作修改了宿主工作树');
+        if (binding.operation !== 'hook' && !digestsMatch(root, before))
+            throw new Error('只读操作修改了来源或输入文件');
+        digestFiles(root, dependencies);
+        digestFiles(root, artifacts);
+    }
+    catch (failure) {
+        ok = false;
+        error = String(failure);
+        dependencies = [];
+        artifacts = [];
+    }
+    if (error)
+        writeText(stderrPath, `${readText(stderrPath)}\n${error}\n`);
+    const receipt = {
+        binding, inputDigest: sha256(JSON.stringify(context.input)),
+        files: ok ? digestFiles(root, [...inputFiles, ...sourceFiles, ...dependencies]) : before,
+        outputs: digestFiles(root, [stdoutPath, stderrPath, inputPath, ...artifacts].map((file) => path.isAbsolute(file) ? path.relative(root, file) : file)),
+        ...(context.worker ?? {}),
+    };
+    return { ok, code: ok ? 0 : result.status || 1, receipt, data, stdoutPath, stderrPath };
+}
+export function pluginReceiptCurrent(root, receipt) {
+    try {
+        resolvePluginCommand(root, receipt.binding);
+    }
+    catch {
+        return false;
+    }
+    return digestsMatch(root, receipt.files) && digestsMatch(root, receipt.outputs);
+}
+//# sourceMappingURL=plugin-runtime.js.map

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+import { listPresets, loadPreset, type ScaffoldResult } from './config/presets.js';
+import { effectiveTaskCategories, type ProjectConfig } from './config/schema.js';
+import { createChange, listChangeNames, requireChange, resolveChangeName } from './core/change.js';
+import { nextAction } from './core/flow.js';
+import { buildInstructions } from './core/instructions.js';
+import { addSources, collect, abortUpdate, parseSourceArg, parseSourceFileArg } from './core/sources.js';
+import { createWorker, acceptWorker, answerWorker, cancelWorker } from './core/worker.js';
+import { approveGate, rejectGate } from './core/gates.js';
+import { runVerifyCommands, recordEvidence, writeReport, renderReportMarkdown, requestFix, changedFilesFromState } from './core/verify.js';
+import { collectPendingWork, renderPendingWork } from './core/todo.js';
+import { archiveChange } from './core/archive.js';
+import { isKnownGate } from './core/state.js';
+import { deliverSkills, verifyDelivery, verifyInstallCli, type HostId } from './delivery/skills.js';
+import { addMarketplace, listMarketplaces, assertPluginsPresent, inspectMarketplaceDependencies } from './marketplace/registry.js';
+import { installPlugin, type InstallResult } from './marketplace/install.js';
+import { BUILTIN_MARKETPLACE } from './marketplace/builtin.js';
+import { inspectHookEntries } from './hooks/engine.js';
+import type { GateId, WorkflowName } from './core/types.js';
+import { PACKAGE_NAME, VERSION } from './shared/version.js';
+export { VERSION, PACKAGE_NAME };
+export declare function project(cwd?: string): {
+    projectRoot: string;
+    config: {
+        schema: "spec-product";
+        taskCategories?: Record<string, {
+            notes?: string | undefined;
+        } | null> | undefined;
+        hooks?: {
+            id: string;
+            stage: "collect" | "parse" | "tech" | "plan" | "execute" | "verify";
+            type?: "command" | "skill" | "notes" | "file" | "check" | undefined;
+            capability?: "requirements" | "interfaces" | "design" | undefined;
+            use?: string | undefined;
+            operation?: "preview" | undefined;
+            input?: Record<string, unknown> | undefined;
+            inputFiles?: string[] | undefined;
+            name?: string | undefined;
+            notes?: string | undefined;
+            taskCategories?: string[] | undefined;
+            command?: string | undefined;
+            target?: "project" | "inScopeChangedFiles" | undefined;
+            include?: string[] | undefined;
+            exclude?: string[] | undefined;
+            allowEmpty?: boolean | undefined;
+            required?: boolean | undefined;
+            purpose?: string | undefined;
+            path?: string | undefined;
+            category?: string | undefined;
+            description?: string | undefined;
+        }[] | undefined;
+        verify?: {
+            reviewScope?: {
+                includeDirs?: string[] | undefined;
+                excludeDirs?: string[] | undefined;
+            } | undefined;
+            failurePolicy?: {
+                failOnHookFailure?: boolean | undefined;
+                failOnRequiredCommandFailure?: boolean | undefined;
+            } | undefined;
+        } | undefined;
+        plugins?: {
+            name: string;
+            marketplace: string;
+            minVersion?: string | undefined;
+        }[] | undefined;
+        marketplaces?: {
+            name: string;
+            repo: string;
+            ref: string;
+        }[] | undefined;
+        tools?: ("claude" | "codex" | "cursor")[] | undefined;
+    };
+};
+export declare function initProject(input: {
+    cwd?: string;
+    tools?: HostId[];
+    preset?: string;
+    yes?: boolean;
+    skipPlugins?: boolean;
+    /** 每个耗时步骤开始前调用一次，供 CLI 在终端反馈进度；缺省静默。 */
+    onProgress?: (message: string) => void;
+}): {
+    projectRoot: string;
+    config: ProjectConfig;
+    delivery: ReturnType<typeof deliverSkills>;
+    plugins: string[];
+    pluginInstalls: InstallResult[];
+    status: 'complete' | 'pending_user_action' | 'partial' | 'skipped';
+    issues: Array<{
+        scope: string;
+        error: string;
+    }>;
+    scaffold: ScaffoldResult[];
+};
+export { createChange, listChangeNames, requireChange, resolveChangeName, nextAction, buildInstructions, addSources, collect, abortUpdate, parseSourceArg, parseSourceFileArg, createWorker, acceptWorker, answerWorker, cancelWorker, approveGate, rejectGate, isKnownGate, runVerifyCommands, recordEvidence, writeReport, renderReportMarkdown, requestFix, changedFilesFromState, archiveChange, collectPendingWork, renderPendingWork, listPresets, loadPreset, addMarketplace, listMarketplaces, installPlugin, verifyDelivery, verifyInstallCli, effectiveTaskCategories, BUILTIN_MARKETPLACE, assertPluginsPresent, inspectMarketplaceDependencies, inspectHookEntries, };
+export type { HostId, GateId, WorkflowName, ProjectConfig };
+export { analyzeUsage, renderUsageMarkdown } from './usage/analyze.js';
+export type { UsageReport, UsageOptions, Tokens, RateCard, Billing } from './usage/types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,185 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { stringify as stringifyYaml } from 'yaml';
+import { appendText, exists, writeText, ensureDir, writeJson } from './shared/fs.js';
+import { findProjectRoot, loadConfig, saveConfig, defaultConfig, configPathOf } from './config/load.js';
+import { keptMarketplaceRefs, listPresets, loadPreset, mergePreset, scaffoldPreset } from './config/presets.js';
+import { effectiveTaskCategories } from './config/schema.js';
+import { createChange, listChangeNames, requireChange, resolveChangeName } from './core/change.js';
+import { nextAction } from './core/flow.js';
+import { buildInstructions } from './core/instructions.js';
+import { addSources, collect, abortUpdate, parseSourceArg, parseSourceFileArg } from './core/sources.js';
+import { createWorker, acceptWorker, answerWorker, cancelWorker } from './core/worker.js';
+import { approveGate, rejectGate } from './core/gates.js';
+import { runVerifyCommands, recordEvidence, writeReport, renderReportMarkdown, requestFix, changedFilesFromState } from './core/verify.js';
+import { collectPendingWork, renderPendingWork } from './core/todo.js';
+import { archiveChange } from './core/archive.js';
+import { isKnownGate } from './core/state.js';
+import { deliverSkills, writeInstallCli, verifyDelivery, verifyInstallCli } from './delivery/skills.js';
+import { addMarketplace, listMarketplaces, ensurePresetMarketplaces, assertPluginsPresent, inspectMarketplaceDependencies } from './marketplace/registry.js';
+import { installPlugin, writeInstallReceipt } from './marketplace/install.js';
+import { BUILTIN_MARKETPLACE } from './marketplace/builtin.js';
+import { inspectHookEntries } from './hooks/engine.js';
+import { OPENSPEC_DIR, resolveInside } from './shared/paths.js';
+import { PACKAGE_NAME, VERSION } from './shared/version.js';
+import { AppError, isAppError } from './shared/errors.js';
+export { VERSION, PACKAGE_NAME };
+export function project(cwd = process.cwd()) {
+    const projectRoot = findProjectRoot(cwd);
+    const config = loadConfig(projectRoot);
+    return { projectRoot, config };
+}
+export function initProject(input) {
+    const projectRoot = path.resolve(input.cwd ?? process.cwd());
+    const progress = input.onProgress ?? (() => { });
+    let scaffold = [];
+    ensureDir(resolveInside(projectRoot, path.posix.join(OPENSPEC_DIR, 'changes'), 'openspec_path_outside_project'));
+    ensureDir(resolveInside(projectRoot, path.posix.join(OPENSPEC_DIR, 'archive'), 'openspec_path_outside_project'));
+    const hadConfig = Boolean(configPathOf(projectRoot));
+    let config = hadConfig ? loadConfig(projectRoot) : defaultConfig();
+    if (input.tools !== undefined)
+        config = { ...config, tools: input.tools };
+    if (input.preset) {
+        progress(`应用 preset ${input.preset}`);
+        const preset = loadPreset(input.preset);
+        for (const kept of keptMarketplaceRefs(config, preset)) {
+            progress(`  保留宿主 marketplace ${kept.name}@${kept.ref.slice(0, 12)}（preset 基线 ${kept.presetRef.slice(0, 12)}）`);
+        }
+        config = mergePreset(config, preset);
+        scaffold = scaffoldPreset(projectRoot, preset);
+        for (const item of scaffold) {
+            progress(item.status === 'created' ? `  生成 ${item.path}（模板，需填写）` : `  保留已有 ${item.path}`);
+        }
+        const lockedMarketplaces = (preset.marketplaces ?? []).map((item) => requireImmutableMarketplace(item));
+        writeText(resolveInside(projectRoot, path.posix.join(OPENSPEC_DIR, 'preset-lock.yaml'), 'preset_lock_outside_project'), stringifyYaml({
+            schemaVersion: preset.schemaVersion,
+            id: preset.id,
+            version: preset.version,
+            marketplaces: lockedMarketplaces,
+            plugins: preset.plugins ?? [],
+        }, { lineWidth: 0 }));
+    }
+    const presetPlugins = config.plugins ?? [];
+    const presetMarketplaces = (config.marketplaces ?? []).map((item) => requireImmutableMarketplace(item));
+    const rewriteConfig = !hadConfig || input.tools !== undefined || Boolean(input.preset);
+    if (rewriteConfig)
+        saveConfig(projectRoot, config);
+    writeInstallCli(projectRoot, VERSION, PACKAGE_NAME);
+    appendGitignore(projectRoot);
+    const hosts = config.tools ?? [];
+    const mode = input.skipPlugins ? 'skip' : input.yes ? 'install' : 'pending';
+    progress(rewriteConfig
+        ? `写入 openspec/config.yaml 与 install-cli.mjs`
+        : `刷新 install-cli.mjs 与宿主交付（保留已有 config.yaml）`);
+    if (hosts.length > 0)
+        progress(`交付 OpenSpec skills → ${hosts.join(', ')}（${mode}）`);
+    const delivery = hosts.length > 0 ? deliverSkills(projectRoot, hosts, mode) : [];
+    const plugins = [];
+    const pluginInstalls = [];
+    const issues = [];
+    if (mode === 'install') {
+        for (const marketplace of presetMarketplaces) {
+            progress(`拉取 marketplace ${marketplace.name}@${marketplace.ref.slice(0, 12)}（${marketplace.repo}）`);
+            try {
+                const [record] = ensurePresetMarketplaces(projectRoot, [marketplace]);
+                progress(`  已锁定 ${marketplace.name} → ${record?.resolvedSha.slice(0, 12) ?? marketplace.ref.slice(0, 12)}`);
+            }
+            catch (error) {
+                progress(`  失败: ${marketplace.name}`);
+                issues.push({ scope: `marketplace:${marketplace.name}`, error: errorMessage(error) });
+            }
+        }
+        for (const plugin of presetPlugins) {
+            try {
+                plugins.push(...assertPluginsPresent(projectRoot, [plugin]));
+            }
+            catch (error) {
+                issues.push({ scope: `plugin:${plugin.name}@${plugin.marketplace}`, error: errorMessage(error) });
+                continue;
+            }
+            for (const host of hosts) {
+                progress(`安装插件 ${plugin.name}@${plugin.marketplace} → ${host}`);
+                try {
+                    const result = installPlugin({
+                        plugin: plugin.name,
+                        marketplace: plugin.marketplace,
+                        host: host,
+                        projectRoot,
+                    });
+                    pluginInstalls.push(result);
+                    progress(`  ${result.status}${result.status === 'failed' && result.error ? `: ${result.error}` : ''}`);
+                    if (result.status === 'failed')
+                        issues.push({ scope: `install:${plugin.name}@${host}`, error: result.error ?? '安装失败' });
+                }
+                catch (error) {
+                    progress(`  失败: ${errorMessage(error)}`);
+                    issues.push({ scope: `install:${plugin.name}@${host}`, error: errorMessage(error) });
+                }
+            }
+        }
+        if (pluginInstalls.length > 0)
+            writeInstallReceipt(projectRoot, pluginInstalls);
+        // 入口在安装时就解析一遍；marketplace 未锁定已在上面记为 issue，不重复记。
+        for (const entry of inspectHookEntries(projectRoot, config)) {
+            if (!entry.ok && entry.code !== 'marketplace_not_locked') {
+                issues.push({ scope: `entry:${entry.hook}`, error: `${entry.code}: ${entry.error}` });
+            }
+        }
+    }
+    for (const item of delivery) {
+        if (item.status === 'failed')
+            issues.push({ scope: `delivery:${item.host}`, error: item.error ?? '交付失败' });
+    }
+    const hasPending = delivery.some((item) => item.status === 'pending_user_action')
+        || pluginInstalls.some((item) => item.status === 'pending_user_action')
+        || (mode === 'pending' && (hosts.length > 0 || presetPlugins.length > 0 || presetMarketplaces.length > 0));
+    const status = issues.length > 0
+        ? 'partial'
+        : mode === 'skip'
+            ? 'skipped'
+            : hasPending
+                ? 'pending_user_action'
+                : 'complete';
+    const result = { projectRoot, config, delivery, plugins, pluginInstalls, status, issues, scaffold };
+    writeJson(resolveInside(projectRoot, path.posix.join(OPENSPEC_DIR, '.runtime/init.json'), 'runtime_path_outside_project'), {
+        recordedAt: new Date().toISOString(),
+        mode,
+        status,
+        pendingPlugins: mode === 'pending' ? presetPlugins.map((item) => `${item.name}@${item.marketplace}`) : [],
+        skippedPlugins: mode === 'skip' ? presetPlugins.map((item) => `${item.name}@${item.marketplace}`) : [],
+        delivery,
+        pluginInstalls,
+        issues,
+        scaffold,
+    });
+    return result;
+}
+export { createChange, listChangeNames, requireChange, resolveChangeName, nextAction, buildInstructions, addSources, collect, abortUpdate, parseSourceArg, parseSourceFileArg, createWorker, acceptWorker, answerWorker, cancelWorker, approveGate, rejectGate, isKnownGate, runVerifyCommands, recordEvidence, writeReport, renderReportMarkdown, requestFix, changedFilesFromState, archiveChange, collectPendingWork, renderPendingWork, listPresets, loadPreset, addMarketplace, listMarketplaces, installPlugin, verifyDelivery, verifyInstallCli, effectiveTaskCategories, BUILTIN_MARKETPLACE, assertPluginsPresent, inspectMarketplaceDependencies, inspectHookEntries, };
+function appendGitignore(projectRoot) {
+    const file = resolveInside(projectRoot, '.gitignore', 'gitignore_outside_project');
+    const entries = [
+        'openspec/changes/**/.opsx/',
+        'openspec/.runtime/',
+    ];
+    if (!exists(file)) {
+        writeText(file, `${entries.join('\n')}\n`);
+        return;
+    }
+    const current = readFileSync(file, 'utf8');
+    const missing = entries.filter((entry) => !current.split(/\r?\n/).includes(entry));
+    if (missing.length > 0)
+        appendText(file, `${current.endsWith('\n') ? '' : '\n'}${missing.join('\n')}\n`);
+}
+/** issue 文本带上错误码，便于在 init 文本输出与回执中定位。 */
+function errorMessage(error) {
+    if (isAppError(error))
+        return `${error.code}: ${error.message}`;
+    return error instanceof Error ? error.message : String(error);
+}
+function requireImmutableMarketplace(item) {
+    if (!item.ref)
+        throw new AppError('marketplace_ref_required', `marketplace 缺少不可变 ref: ${item.name}`);
+    return { ...item, ref: item.ref };
+}
+export { analyzeUsage, renderUsageMarkdown } from './usage/analyze.js';
+//# sourceMappingURL=index.js.map