@birdie_moblie/open_spec 2.1.7

package/dist/marketplace/registry.js

@@ -0,0 +1,342 @@
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { renameSync } from 'node:fs';
+import { z } from 'zod';
+import { execFile } from '../shared/exec.js';
+import { copyPath, ensureDir, exists, readJson, removePath, writeJson } from '../shared/fs.js';
+import { digestDirectory } from '../shared/hash.js';
+import { AppError } from '../shared/errors.js';
+import { resolveInside } from '../shared/paths.js';
+import { compareVersions } from '../shared/version.js';
+import { BUILTIN_MARKETPLACE } from './builtin.js';
+import { discoverPluginDirs, marketplaceCacheDir, marketplaceCacheRoot, marketplaceLockPath, marketplaceRootForProject, readManifest, readMarketplaceLock, } from './adapters.js';
+const RecordSchema = z.object({
+    name: z.string(),
+    repo: z.string().optional(),
+    ref: z.string(),
+    resolvedSha: z.string(),
+    digest: z.string(),
+    cachePath: z.string(),
+    updatedAt: z.string(),
+}).strict();
+const StateSchema = z.object({ marketplaces: z.array(RecordSchema) }).strict();
+function stateFile() {
+    return resolveInside(marketplaceCacheRoot(), 'state.json', 'marketplace_state_outside_home');
+}
+/**
+ * 用户级缓存索引只是派生数据（项目 lock 才是权威入口）。
+ * 旧格式或损坏的索引不能阻塞 init：保留仍合法的记录，其余丢弃，原文件备份为 state.json.invalid-<时间戳>。
+ */
+export function loadMarketplaceState() {
+    const file = stateFile();
+    if (!exists(file))
+        return { marketplaces: [] };
+    let raw;
+    try {
+        raw = readJson(file);
+    }
+    catch {
+        raw = null;
+    }
+    const parsed = StateSchema.safeParse(raw);
+    if (parsed.success)
+        return parsed.data;
+    const candidates = isRecordObject(raw) && Array.isArray(raw.marketplaces) ? raw.marketplaces : [];
+    const kept = candidates.flatMap((item) => {
+        const record = RecordSchema.safeParse(item);
+        return record.success ? [record.data] : [];
+    });
+    renameSync(file, `${file}.invalid-${Date.now()}`);
+    return { marketplaces: kept };
+}
+function isRecordObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function saveMarketplaceState(state) {
+    writeJson(stateFile(), StateSchema.parse(state));
+}
+export function addMarketplace(input) {
+    const record = input.dir ? addLocalMarketplace(input) : addGitMarketplace(input);
+    validateMarketplace(record.cachePath);
+    const saved = upsert(record);
+    if (input.projectRoot)
+        writeProjectLock(input.projectRoot, saved);
+    return saved;
+}
+export function listMarketplaces(projectRoot) {
+    if (projectRoot) {
+        return readMarketplaceLock(projectRoot).marketplaces.map((record) => ({ ...record, updatedAt: '' }));
+    }
+    return loadMarketplaceState().marketplaces;
+}
+export function ensurePresetMarketplaces(projectRoot, marketplaces) {
+    return marketplaces.map((item) => addMarketplace({ projectRoot, ...item }));
+}
+/** 插件版本不低于宿主声明的 minVersion；manifest 缺版本或无法解析时视为不满足。 */
+export function pluginVersionSatisfies(version, minVersion) {
+    if (!minVersion)
+        return true;
+    if (!version)
+        return false;
+    return (compareVersions(version, minVersion) ?? -1) >= 0;
+}
+export function assertPluginsPresent(projectRoot, plugins) {
+    const lock = readMarketplaceLock(projectRoot);
+    const resolved = [];
+    const missing = [];
+    const outdated = [];
+    for (const plugin of plugins) {
+        const root = marketplaceRootForProject(projectRoot, plugin.marketplace);
+        const matches = discoverPluginDirs(root).filter((dir) => path.basename(dir) === plugin.name || readManifest(dir).name === plugin.name);
+        if (matches.length === 0) {
+            missing.push(`${plugin.name}@${plugin.marketplace}`);
+            continue;
+        }
+        if (matches.length > 1)
+            throw new AppError('plugin_conflict', `marketplace 中插件重复: ${plugin.name}@${plugin.marketplace}`);
+        const pluginDir = matches[0];
+        const version = readManifest(pluginDir).version;
+        if (!pluginVersionSatisfies(version, plugin.minVersion)) {
+            outdated.push(`${plugin.name}@${plugin.marketplace}（实际 ${version ?? '未声明'}，最低 ${plugin.minVersion}）`);
+            continue;
+        }
+        const marketplace = lock.marketplaces.find((item) => item.name === plugin.marketplace);
+        if (!marketplace)
+            throw new AppError('marketplace_not_locked', `项目未锁定 marketplace: ${plugin.marketplace}`);
+        resolved.push({
+            name: plugin.name,
+            marketplace: plugin.marketplace,
+            resolvedSha: marketplace.resolvedSha,
+            digest: digestDirectory(pluginDir),
+        });
+    }
+    if (missing.length > 0) {
+        throw new AppError('plugin_missing_in_marketplace', `marketplace 缺少必需插件: ${missing.join(', ')}`);
+    }
+    if (outdated.length > 0) {
+        throw new AppError('plugin_version_too_low', `插件版本低于宿主要求: ${outdated.join(', ')}`);
+    }
+    for (const plugin of resolved) {
+        const index = lock.plugins.findIndex((item) => item.name === plugin.name && item.marketplace === plugin.marketplace);
+        if (index >= 0)
+            lock.plugins[index] = plugin;
+        else
+            lock.plugins.push(plugin);
+    }
+    writeJson(marketplaceLockPath(projectRoot), lock);
+    return plugins.map((plugin) => `${plugin.name}@${plugin.marketplace}`);
+}
+export function inspectMarketplaceDependencies(projectRoot, marketplaces, plugins) {
+    const lock = readMarketplaceLock(projectRoot);
+    const checks = [];
+    for (const expected of marketplaces) {
+        const record = lock.marketplaces.find((item) => item.name === expected.name);
+        if (!record) {
+            checks.push({ kind: 'marketplace', id: expected.name, ok: false, code: 'marketplace_not_locked' });
+            continue;
+        }
+        if (record.repo !== expected.repo || record.ref !== expected.ref) {
+            checks.push({ kind: 'marketplace', id: expected.name, ok: false, code: 'marketplace_lock_mismatch' });
+            continue;
+        }
+        try {
+            marketplaceRootForProject(projectRoot, expected.name);
+            checks.push({
+                kind: 'marketplace', id: expected.name, ok: true, digest: record.digest, resolvedSha: record.resolvedSha,
+            });
+        }
+        catch (error) {
+            checks.push({ kind: 'marketplace', id: expected.name, ok: false, code: errorCode(error) });
+        }
+    }
+    for (const expected of plugins) {
+        const id = `${expected.name}@${expected.marketplace}`;
+        const record = lock.plugins.find((item) => item.name === expected.name && item.marketplace === expected.marketplace);
+        if (!record) {
+            checks.push({ kind: 'plugin', id, ok: false, code: 'plugin_not_locked' });
+            continue;
+        }
+        try {
+            const root = marketplaceRootForProject(projectRoot, expected.marketplace);
+            const matches = discoverPluginDirs(root).filter((dir) => path.basename(dir) === expected.name || readManifest(dir).name === expected.name);
+            if (matches.length !== 1) {
+                checks.push({ kind: 'plugin', id, ok: false, code: matches.length === 0 ? 'plugin_missing_in_marketplace' : 'plugin_conflict' });
+                continue;
+            }
+            const pluginDir = matches[0];
+            const digest = digestDirectory(pluginDir);
+            const marketplace = lock.marketplaces.find((item) => item.name === expected.marketplace);
+            const identical = digest === record.digest && marketplace?.resolvedSha === record.resolvedSha;
+            const version = readManifest(pluginDir).version;
+            const satisfied = pluginVersionSatisfies(version, expected.minVersion);
+            const ok = identical && satisfied;
+            checks.push({
+                kind: 'plugin', id, ok, digest, resolvedSha: record.resolvedSha,
+                code: !identical ? 'plugin_digest_mismatch' : satisfied ? undefined : 'plugin_version_too_low',
+                ...(expected.minVersion ? { minVersion: expected.minVersion, ...(version ? { version } : {}) } : {}),
+            });
+        }
+        catch (error) {
+            checks.push({ kind: 'plugin', id, ok: false, code: errorCode(error) });
+        }
+    }
+    return checks;
+}
+/** 本地目录与 git 分支一致：缓存中不含 .git，digest 以缓存副本为准。 */
+function addLocalMarketplace(input) {
+    const source = path.resolve(input.dir ?? '');
+    if (!exists(source))
+        throw new AppError('marketplace_missing', `本地 marketplace 目录不存在: ${source}`);
+    const name = input.name ?? path.basename(source);
+    ensureDir(marketplaceCacheRoot());
+    const staged = resolveInside(marketplaceCacheRoot(), `.local-${name}-${randomUUID()}`, 'marketplace_cache_outside_home');
+    try {
+        copyPath(source, staged, { excludeNames: ['.git'] });
+        const digest = digestDirectory(staged);
+        const resolvedSha = `local-${digest.slice(0, 16)}`;
+        const cachePath = marketplaceCacheDir(name, resolvedSha);
+        if (exists(cachePath))
+            removePath(staged);
+        else {
+            ensureDir(path.dirname(cachePath));
+            renameSync(staged, cachePath);
+        }
+        return { name, ref: input.ref ?? resolvedSha, resolvedSha, digest, cachePath, repo: input.repo };
+    }
+    finally {
+        if (exists(staged))
+            removePath(staged);
+    }
+}
+function addGitMarketplace(input) {
+    const repo = input.repo ?? BUILTIN_MARKETPLACE.repo;
+    const name = input.name ?? inferName(repo);
+    const ref = input.ref ?? '';
+    if (!ref)
+        throw new AppError('marketplace_ref_required', `marketplace 必须用 --ref 指定不可变 ref（完整 Git SHA 或 refs/tags/<tag>）: ${name}`);
+    if (!isImmutableRef(ref)) {
+        throw new AppError('mutable_marketplace_ref', `marketplace ref 必须是完整 Git SHA 或 refs/tags/<tag>: ${ref}`);
+    }
+    if (/^[0-9a-f]{40}$/i.test(ref)) {
+        const cached = marketplaceCacheDir(name, ref);
+        if (exists(cached)) {
+            return { name, repo, ref, resolvedSha: ref, digest: digestDirectory(cached), cachePath: cached };
+        }
+    }
+    ensureDir(marketplaceCacheRoot());
+    const temporary = resolveInside(marketplaceCacheRoot(), `.clone-${name}-${randomUUID()}`, 'marketplace_cache_outside_home');
+    try {
+        fetchImmutableRef(repo, ref, temporary);
+        const checkout = execFile('git', ['checkout', '--detach', 'FETCH_HEAD'], { cwd: temporary });
+        if (!checkout.ok)
+            throw new AppError('marketplace_checkout_failed', checkout.stderr || checkout.stdout);
+        const resolved = execFile('git', ['rev-parse', 'HEAD'], { cwd: temporary });
+        if (!resolved.ok)
+            throw new AppError('marketplace_revision_failed', resolved.stderr || resolved.stdout);
+        const resolvedSha = resolved.stdout.trim();
+        removePath(path.join(temporary, '.git'));
+        const cachePath = marketplaceCacheDir(name, resolvedSha);
+        if (exists(cachePath))
+            removePath(temporary);
+        else {
+            ensureDir(path.dirname(cachePath));
+            renameSync(temporary, cachePath);
+        }
+        return { name, repo, ref, resolvedSha, digest: digestDirectory(cachePath), cachePath };
+    }
+    finally {
+        if (exists(temporary))
+            removePath(temporary);
+    }
+}
+/** 网络操作给足时间，且禁止 git 等待终端输入（否则会静默挂到超时）。 */
+const GIT_NETWORK_OPTIONS = { timeoutMs: 300_000, env: { GIT_TERMINAL_PROMPT: '0' } };
+/**
+ * 只拉取不可变 ref 指向的那一个提交：init + remote add + fetch --depth 1。
+ * 服务端不允许按 SHA 拉取时回退为完整 clone 后再 fetch。
+ */
+function fetchImmutableRef(repo, ref, temporary) {
+    ensureDir(temporary);
+    const init = execFile('git', ['init', '-q'], { cwd: temporary });
+    if (!init.ok)
+        throw new AppError('marketplace_clone_failed', `git init 失败: ${init.stderr || init.stdout}`);
+    const remote = execFile('git', ['remote', 'add', 'origin', repo], { cwd: temporary });
+    if (!remote.ok)
+        throw new AppError('marketplace_clone_failed', `git remote add 失败: ${remote.stderr || remote.stdout}`);
+    const shallow = execFile('git', ['fetch', '--depth', '1', 'origin', ref], { cwd: temporary, ...GIT_NETWORK_OPTIONS });
+    if (shallow.ok)
+        return;
+    removePath(temporary);
+    const clone = execFile('git', ['clone', '--no-checkout', repo, temporary], { cwd: path.dirname(temporary), ...GIT_NETWORK_OPTIONS });
+    if (!clone.ok) {
+        throw new AppError('marketplace_clone_failed', `git 拉取 ${repo} 失败。浅拉取 ${ref}: ${shallow.stderr || shallow.stdout}；完整 clone: ${clone.stderr || clone.stdout}`);
+    }
+    const fetch = execFile('git', ['fetch', '--depth', '1', 'origin', ref], { cwd: temporary, ...GIT_NETWORK_OPTIONS });
+    if (!fetch.ok)
+        throw new AppError('marketplace_fetch_failed', `git fetch ${ref} 失败: ${fetch.stderr || fetch.stdout}`);
+}
+function validateMarketplace(root) {
+    const ids = new Set();
+    const hooks = new Set();
+    for (const pluginDir of discoverPluginDirs(root)) {
+        const manifest = readManifest(pluginDir);
+        for (const hook of manifest.extensions?.['org.openspec']?.hooks ?? []) {
+            if (ids.has(hook.id))
+                throw new AppError('plugin_entry_conflict', `adapter 与 hook 入口重名: ${hook.id}`);
+            if (hooks.has(hook.id))
+                throw new AppError('hook_conflict', `marketplace 中存在重复 hook: ${hook.id}`);
+            hooks.add(hook.id);
+        }
+        for (const adapter of manifest.extensions?.['org.openspec']?.adapters ?? []) {
+            if (hooks.has(adapter.id))
+                throw new AppError('plugin_entry_conflict', `adapter 与 hook 入口重名: ${adapter.id}`);
+            if (ids.has(adapter.id))
+                throw new AppError('adapter_conflict', `marketplace 中存在重复 adapter: ${adapter.id}`);
+            ids.add(adapter.id);
+        }
+    }
+}
+function writeProjectLock(projectRoot, record) {
+    const lock = readMarketplaceLock(projectRoot);
+    const value = {
+        name: record.name,
+        repo: record.repo,
+        ref: record.ref,
+        resolvedSha: record.resolvedSha,
+        digest: record.digest,
+        cachePath: record.cachePath,
+    };
+    const index = lock.marketplaces.findIndex((item) => item.name === record.name);
+    if (index >= 0) {
+        const previous = lock.marketplaces[index];
+        lock.marketplaces[index] = value;
+        if (previous?.resolvedSha !== record.resolvedSha || previous.digest !== record.digest) {
+            lock.plugins = lock.plugins.filter((item) => item.marketplace !== record.name);
+        }
+    }
+    else
+        lock.marketplaces.push(value);
+    writeJson(marketplaceLockPath(projectRoot), lock);
+}
+function upsert(record) {
+    const state = loadMarketplaceState();
+    const next = { ...record, updatedAt: new Date().toISOString() };
+    const index = state.marketplaces.findIndex((item) => item.name === record.name && item.resolvedSha === record.resolvedSha);
+    if (index >= 0)
+        state.marketplaces[index] = next;
+    else
+        state.marketplaces.push(next);
+    saveMarketplaceState(state);
+    return next;
+}
+function inferName(repo) {
+    const base = repo.split('/').pop() ?? 'marketplace';
+    return base.replace(/\.git$/, '');
+}
+export function isImmutableRef(ref) {
+    return /^[0-9a-f]{40}$/i.test(ref) || /^refs\/tags\/[^/]+$/.test(ref);
+}
+function errorCode(error) {
+    return error instanceof AppError ? error.code : 'dependency_check_failed';
+}
+//# sourceMappingURL=registry.js.map

package/dist/marketplace/upgrade.d.ts

@@ -0,0 +1,39 @@
+import { type HookEntryCheck } from '../hooks/engine.js';
+import { type InstallResult } from './install.js';
+export interface MarketplaceUpgradeResult {
+    marketplace: string;
+    from: {
+        ref: string;
+        resolvedSha?: string;
+    };
+    to: {
+        ref: string;
+        resolvedSha: string;
+    };
+    plugins: Array<{
+        name: string;
+        version?: string;
+        minVersion?: string;
+    }>;
+    entries: HookEntryCheck[];
+    installs: InstallResult[];
+    status: 'complete' | 'pending_user_action' | 'partial';
+    issues: Array<{
+        scope: string;
+        error: string;
+    }>;
+}
+/**
+ * 把宿主 config 中已声明的远端 marketplace 升级到新的不可变 ref。
+ *
+ * 拉取、插件版本（minVersion）与入口解析都在原生安装之前完成，任一失败都按原字节还原 config 与锁，宿主保持旧版本。
+ * 原生安装无法靠还原文件撤销，所以安装失败时保留新锁并报告 partial，由 doctor 与重装处理。
+ * config 只改该 marketplace 的 ref 字段，保留宿主的注释与格式。
+ */
+export declare function upgradeMarketplace(input: {
+    projectRoot: string;
+    name: string;
+    ref: string;
+    allowActiveChanges?: boolean;
+}): MarketplaceUpgradeResult;
+//# sourceMappingURL=upgrade.d.ts.map

package/dist/marketplace/upgrade.js

@@ -0,0 +1,104 @@
+import path from 'node:path';
+import { isScalar, parseDocument } from 'yaml';
+import { configPathOf, loadConfig } from '../config/load.js';
+import { listChangeNames } from '../core/change.js';
+import { inspectHookEntries } from '../hooks/engine.js';
+import { AppError } from '../shared/errors.js';
+import { exists, readText, removePath, writeText } from '../shared/fs.js';
+import { discoverPluginDirs, marketplaceLockPath, marketplaceRootForProject, parseSelector, readManifest, readMarketplaceLock, } from './adapters.js';
+import { installPlugin, readInstallReceipt, writeInstallReceipt } from './install.js';
+import { addMarketplace, assertPluginsPresent, isImmutableRef } from './registry.js';
+/**
+ * 把宿主 config 中已声明的远端 marketplace 升级到新的不可变 ref。
+ *
+ * 拉取、插件版本（minVersion）与入口解析都在原生安装之前完成，任一失败都按原字节还原 config 与锁，宿主保持旧版本。
+ * 原生安装无法靠还原文件撤销，所以安装失败时保留新锁并报告 partial，由 doctor 与重装处理。
+ * config 只改该 marketplace 的 ref 字段，保留宿主的注释与格式。
+ */
+export function upgradeMarketplace(input) {
+    const { projectRoot, name, ref } = input;
+    const config = loadConfig(projectRoot);
+    const configFile = configPathOf(projectRoot);
+    const index = (config.marketplaces ?? []).findIndex((item) => item.name === name);
+    const declared = config.marketplaces?.[index];
+    if (!configFile || !declared) {
+        throw new AppError('marketplace_not_configured', `config 未声明 marketplace: ${name}；升级只针对宿主配置中的远端 marketplace`);
+    }
+    if (!isImmutableRef(ref)) {
+        throw new AppError('mutable_marketplace_ref', `marketplace ref 必须是完整 Git SHA 或 refs/tags/<tag>: ${ref}`);
+    }
+    const active = listChangeNames(projectRoot);
+    if (active.length > 0 && !input.allowActiveChanges) {
+        throw new AppError('active_changes_present', `存在进行中的 change：${active.join(', ')}。它们的来源与回执绑定旧插件身份，升级后需重新采集或派发；确认后加 --allow-active-changes`);
+    }
+    const lockFile = marketplaceLockPath(projectRoot);
+    const original = { config: readText(configFile), lock: exists(lockFile) ? readText(lockFile) : undefined };
+    const previous = readMarketplaceLock(projectRoot).marketplaces.find((item) => item.name === name);
+    const plugins = (config.plugins ?? []).filter((item) => item.marketplace === name);
+    let entries;
+    let resolvedSha;
+    let hosts;
+    try {
+        resolvedSha = addMarketplace({ projectRoot, name, repo: declared.repo, ref }).resolvedSha;
+        const document = parseDocument(original.config);
+        // 改原 Scalar 的值而不是替换节点，保留写在 ref 行上的注释。
+        const node = document.getIn(['marketplaces', index, 'ref'], true);
+        if (isScalar(node))
+            node.value = ref;
+        else
+            document.setIn(['marketplaces', index, 'ref'], ref);
+        writeText(configFile, document.toString());
+        const next = loadConfig(projectRoot);
+        hosts = (next.tools ?? []);
+        assertPluginsPresent(projectRoot, plugins);
+        entries = inspectHookEntries(projectRoot, next).filter((entry) => parseSelector(entry.use).marketplace === name);
+        const broken = entries.filter((entry) => !entry.ok);
+        if (broken.length > 0) {
+            throw new AppError('plugin_entries_incompatible', `新 ref 下插件入口缺失或不符：${broken.map((entry) => `${entry.hook}（${entry.use}）${entry.code}`).join('；')}`, broken);
+        }
+    }
+    catch (error) {
+        writeText(configFile, original.config);
+        if (original.lock === undefined)
+            removePath(lockFile);
+        else
+            writeText(lockFile, original.lock);
+        throw error;
+    }
+    const installs = [];
+    const issues = [];
+    for (const plugin of plugins) {
+        for (const host of hosts) {
+            try {
+                const result = installPlugin({ plugin: plugin.name, marketplace: name, host, projectRoot });
+                installs.push(result);
+                if (result.status === 'failed')
+                    issues.push({ scope: `install:${plugin.name}@${host}`, error: result.error ?? '安装失败' });
+            }
+            catch (error) {
+                issues.push({ scope: `install:${plugin.name}@${host}`, error: error instanceof Error ? error.message : String(error) });
+            }
+        }
+    }
+    if (installs.length > 0) {
+        const retained = readInstallReceipt(projectRoot).filter((item) => !installs.some((result) => result.plugin === item.plugin && result.marketplace === item.marketplace && result.host === item.host));
+        writeInstallReceipt(projectRoot, [...retained, ...installs]);
+    }
+    const root = marketplaceRootForProject(projectRoot, name);
+    const pluginDirs = discoverPluginDirs(root);
+    return {
+        marketplace: name,
+        from: { ref: declared.ref, ...(previous ? { resolvedSha: previous.resolvedSha } : {}) },
+        to: { ref, resolvedSha },
+        plugins: plugins.map((plugin) => {
+            const dir = pluginDirs.find((item) => path.basename(item) === plugin.name || readManifest(item).name === plugin.name);
+            const version = dir ? readManifest(dir).version : undefined;
+            return { name: plugin.name, ...(version ? { version } : {}), ...(plugin.minVersion ? { minVersion: plugin.minVersion } : {}) };
+        }),
+        entries,
+        installs,
+        status: issues.length > 0 ? 'partial' : installs.some((item) => item.status === 'pending_user_action') ? 'pending_user_action' : 'complete',
+        issues,
+    };
+}
+//# sourceMappingURL=upgrade.js.map

package/dist/shared/command-log.d.ts

@@ -0,0 +1,9 @@
+/** 完整 stdout/stderr 直接写磁盘，避免 execFileSync 的 maxBuffer 丢失长输出。 */
+export declare function runLoggedCommand(bin: string, args: string[], cwd: string, logPath: string, timeoutMs?: number, env?: Record<string, string>): {
+    code: number;
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    truncated: boolean;
+};
+//# sourceMappingURL=command-log.d.ts.map

package/dist/shared/command-log.js

@@ -0,0 +1,55 @@
+import { spawnSync } from 'node:child_process';
+import { closeSync, fstatSync, openSync, readSync, unlinkSync, writeSync } from 'node:fs';
+import path from 'node:path';
+import { ensureDir } from './fs.js';
+/** 完整 stdout/stderr 直接写磁盘，避免 execFileSync 的 maxBuffer 丢失长输出。 */
+export function runLoggedCommand(bin, args, cwd, logPath, timeoutMs = 120_000, env) {
+    ensureDir(path.dirname(logPath));
+    const out = openSync(logPath, 'w+');
+    const errorPath = `${logPath}.stderr`;
+    const err = openSync(errorPath, 'w+');
+    try {
+        const result = spawnSync(bin, args, { cwd, timeout: timeoutMs, stdio: ['ignore', out, err], env: env ? { ...process.env, ...env } : undefined });
+        if (result.error || result.signal) {
+            writeSync(err, `\n${result.error?.message ?? `命令被信号 ${result.signal} 终止`}\n`);
+        }
+        const outSize = fstatSync(out).size;
+        const errSize = fstatSync(err).size;
+        // 优先保留 stderr，两个流的摘要总计不超过 2KB。
+        const stderr = tail(err, errSize, 2048);
+        const stdout = tail(out, outSize, 2048 - Buffer.byteLength(stderr));
+        if (errSize) {
+            writeSync(out, '\n--- stderr ---\n');
+            const buffer = Buffer.alloc(64 * 1024);
+            for (let offset = 0; offset < errSize;) {
+                const count = readSync(err, buffer, 0, Math.min(buffer.length, errSize - offset), offset);
+                if (!count)
+                    break;
+                writeSync(out, buffer.subarray(0, count));
+                offset += count;
+            }
+        }
+        return {
+            code: result.status ?? 1,
+            ok: result.status === 0 && !result.error && !result.signal,
+            stdout,
+            stderr,
+            truncated: outSize + errSize > 2048,
+        };
+    }
+    finally {
+        closeSync(out);
+        closeSync(err);
+        unlinkSync(errorPath);
+    }
+}
+function tail(fd, size, limit) {
+    const buffer = Buffer.alloc(Math.min(size, limit));
+    readSync(fd, buffer, 0, buffer.length, size - buffer.length);
+    let start = 0;
+    // 不把 UTF-8 截断在多字节字符中间。
+    while (start < buffer.length && (buffer[start] & 0xc0) === 0x80)
+        start++;
+    return buffer.subarray(start).toString('utf8');
+}
+//# sourceMappingURL=command-log.js.map

package/dist/shared/errors.d.ts

@@ -0,0 +1,7 @@
+export declare class AppError extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(code: string, message: string, details?: unknown);
+}
+export declare function isAppError(error: unknown): error is AppError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/shared/errors.js

@@ -0,0 +1,14 @@
+export class AppError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = 'AppError';
+        this.code = code;
+        this.details = details;
+    }
+}
+export function isAppError(error) {
+    return error instanceof AppError;
+}
+//# sourceMappingURL=errors.js.map

package/dist/shared/exec.d.ts

@@ -0,0 +1,16 @@
+export interface ExecResult {
+    ok: boolean;
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export declare function execFile(command: string, args: string[], options: {
+    cwd: string;
+    timeoutMs?: number;
+    env?: Record<string, string>;
+}): ExecResult;
+export declare function splitCommand(command: string): {
+    bin: string;
+    args: string[];
+};
+//# sourceMappingURL=exec.d.ts.map

package/dist/shared/exec.js

@@ -0,0 +1,86 @@
+import { execFileSync } from 'node:child_process';
+import { AppError } from './errors.js';
+export function execFile(command, args, options) {
+    const timeout = options.timeoutMs ?? 120_000;
+    try {
+        const stdout = execFileSync(command, args, {
+            cwd: options.cwd,
+            encoding: 'utf8',
+            timeout,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: options.env ? { ...process.env, ...options.env } : process.env,
+        });
+        return { ok: true, code: 0, stdout: String(stdout), stderr: '' };
+    }
+    catch (error) {
+        const err = error;
+        const stderr = String(err.stderr ?? '');
+        // 被超时终止时 status 为 null 且带 signal；此时 stderr 往往只有进度输出，必须把真实原因写出来
+        const timedOut = err.code === 'ETIMEDOUT' || (err.status == null && Boolean(err.signal));
+        const reason = timedOut
+            ? `命令在 ${Math.round(timeout / 1000)}s 内未完成，已终止: ${command} ${args.join(' ')}`
+            : '';
+        return {
+            ok: false,
+            code: typeof err.status === 'number' ? err.status : 1,
+            stdout: String(err.stdout ?? ''),
+            stderr: [reason, stderr || (reason ? '' : String(err.message ?? ''))].filter(Boolean).join('\n'),
+        };
+    }
+}
+export function splitCommand(command) {
+    const parts = parseArgv(command);
+    const bin = parts[0] ?? '';
+    if (!bin)
+        throw new AppError('invalid_command', 'command 不能为空');
+    return { bin, args: parts.slice(1) };
+}
+function parseArgv(command) {
+    const parts = [];
+    let current = '';
+    let started = false;
+    let quote = null;
+    let escaped = false;
+    const push = () => {
+        if (started)
+            parts.push(current);
+        current = '';
+        started = false;
+    };
+    for (const char of command.trim()) {
+        if (escaped) {
+            current += char;
+            started = true;
+            escaped = false;
+            continue;
+        }
+        if (char === '\\' && quote !== 'single') {
+            escaped = true;
+            continue;
+        }
+        if (char === "'" && quote !== 'double') {
+            started = true;
+            quote = quote === 'single' ? null : 'single';
+            continue;
+        }
+        if (char === '"' && quote !== 'single') {
+            started = true;
+            quote = quote === 'double' ? null : 'double';
+            continue;
+        }
+        if (!quote && /[|;&<>]/.test(char)) {
+            throw new AppError('unsupported_shell_syntax', `command 不支持 shell 运算符: ${char}`);
+        }
+        if (!quote && /\s/.test(char)) {
+            push();
+            continue;
+        }
+        current += char;
+        started = true;
+    }
+    if (quote || escaped)
+        throw new AppError('invalid_command', 'command 包含未闭合的引号或转义');
+    push();
+    return parts;
+}
+//# sourceMappingURL=exec.js.map