@birdie_moblie/open_spec 2.1.7

package/dist/core/change.js

@@ -0,0 +1,69 @@
+import path from 'node:path';
+import { exists, listDirs, readText, writeText } from '../shared/fs.js';
+import { AppError } from '../shared/errors.js';
+import { archiveDir, changeDir, OPENSPEC_DIR, resolveInside } from '../shared/paths.js';
+import { createState, hasState, loadState, saveState } from './state.js';
+export function changeRoot(projectRoot, changeName) {
+    assertChangeName(changeName);
+    return resolveInside(projectRoot, changeDir(changeName), 'change_path_outside_project');
+}
+export function createChange(projectRoot, name, description) {
+    assertChangeName(name);
+    const dir = changeRoot(projectRoot, name);
+    if (exists(dir))
+        throw new AppError('change_exists', `change 已存在: ${name}`);
+    writeText(path.join(dir, '.openspec.yaml'), 'schema: spec-product\n');
+    if (description)
+        writeText(path.join(dir, 'README.md'), `${description}\n`);
+    const state = createState(name);
+    saveState(projectRoot, state);
+    return state;
+}
+export function listChangeNames(projectRoot) {
+    return listDirs(resolveInside(projectRoot, path.posix.join(OPENSPEC_DIR, 'changes'), 'changes_path_outside_project')).sort();
+}
+export function requireChange(projectRoot, changeName) {
+    if (!exists(changeRoot(projectRoot, changeName))) {
+        throw new AppError('change_not_found', `找不到 change: ${changeName}`);
+    }
+    if (!hasState(projectRoot, changeName)) {
+        throw new AppError('change_state_missing', `change 缺少权威状态文件: ${changeName}`);
+    }
+    return loadState(projectRoot, changeName);
+}
+export function resolveChangeName(projectRoot, requested) {
+    if (requested)
+        return requested;
+    const names = listChangeNames(projectRoot);
+    if (names.length === 1)
+        return names[0];
+    throw new AppError('change_ambiguous', '请通过 --change 指定 change 名称', { names });
+}
+export function artifactPath(projectRoot, changeName, relative) {
+    return resolveInside(changeRoot(projectRoot, changeName), relative, 'artifact_path_outside_change');
+}
+export function artifactRel(changeName, relative) {
+    assertChangeName(changeName);
+    resolveInside('/__openspec_change__', relative, 'artifact_path_outside_change');
+    return `${changeDir(changeName)}/${relative}`;
+}
+export function stampArchivePath(projectRoot, changeName) {
+    const day = new Date().toISOString().slice(0, 10);
+    let stamp = day;
+    let index = 1;
+    while (exists(resolveInside(projectRoot, archiveDir(stamp, changeName), 'archive_path_outside_project'))) {
+        index += 1;
+        stamp = `${day}-${index}`;
+    }
+    return archiveDir(stamp, changeName);
+}
+export function assertChangeName(name) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(name) || name.length > 80) {
+        throw new AppError('invalid_change_name', 'change 名称仅允许小写字母、数字与连字符');
+    }
+}
+export function readOptional(projectRoot, changeName, relative) {
+    const file = artifactPath(projectRoot, changeName, relative);
+    return exists(file) ? readText(file) : null;
+}
+//# sourceMappingURL=change.js.map

package/dist/core/code-changes.d.ts

@@ -0,0 +1,9 @@
+import type { ChangeState, WorkerPacket } from './types.js';
+/** A retry's new edits and the task's retained, still-reviewable output are distinct. */
+export declare function codeChangeScope(root: string, state: ChangeState, packet: Pick<WorkerPacket, 'workerId' | 'stepId'>): {
+    workerChangedFiles: string[];
+    changedFiles: string[];
+    changeChangedFiles: string[];
+};
+export declare function retainCodeChanges(root: string, state: ChangeState, packet: Pick<WorkerPacket, 'workerId' | 'stepId'>, files: string[], pending?: boolean): void;
+//# sourceMappingURL=code-changes.d.ts.map

package/dist/core/code-changes.js

@@ -0,0 +1,31 @@
+import { exists, readJson, writeJson } from '../shared/fs.js';
+import { changedFilesSince, parseDiffBaseline } from '../shared/git.js';
+import { resolveInside } from '../shared/paths.js';
+import { AppError } from '../shared/errors.js';
+import { artifactRel } from './change.js';
+const union = (...lists) => [...new Set(lists.flat())].sort();
+/** A retry's new edits and the task's retained, still-reviewable output are distinct. */
+export function codeChangeScope(root, state, packet) {
+    const relative = artifactRel(state.changeName, `.opsx/workers/${packet.workerId}.baseline.json`);
+    const file = resolveInside(root, relative);
+    if (!exists(file))
+        throw new AppError('worker_baseline_missing', `缺少 worker baseline: ${packet.workerId}`);
+    const workerChangedFiles = changedFilesSince(root, parseDiffBaseline(readJson(file)));
+    if (state.codeChanges) {
+        // Preserve the original change baseline and reject HEAD drift across cancellations.
+        changedFilesSince(root, parseDiffBaseline(readJson(resolveInside(root, state.codeChanges.baseline))));
+    }
+    const retained = state.codeChanges?.filesByStep[packet.stepId] ?? [];
+    const changedFiles = union(workerChangedFiles, retained);
+    return { workerChangedFiles, changedFiles, changeChangedFiles: union(state.engineChangedFiles, changedFiles) };
+}
+export function retainCodeChanges(root, state, packet, files, pending = false) {
+    state.codeChanges ??= { baseline: artifactRel(state.changeName, `.opsx/workers/${packet.workerId}.baseline.json`), filesByStep: {} };
+    state.codeChanges.filesByStep[packet.stepId] = union(state.codeChanges.filesByStep[packet.stepId] ?? [], files);
+    state.engineChangedFiles = union(state.engineChangedFiles, files);
+    state.codeChanges.pendingSteps = pending
+        ? union(state.codeChanges.pendingSteps ?? [], files.length ? [packet.stepId] : [])
+        : (state.codeChanges.pendingSteps ?? []).filter((step) => step !== packet.stepId);
+    writeJson(resolveInside(root, artifactRel(state.changeName, '.opsx/code-changes.json')), state.codeChanges);
+}
+//# sourceMappingURL=code-changes.js.map

package/dist/core/flow.d.ts

@@ -0,0 +1,6 @@
+import { type ChangeState, type GateId, type NextAction, type Node } from './types.js';
+export declare function nextAction(state: ChangeState): NextAction;
+export declare function assertNode(state: ChangeState, allowed: Node[], action: string): void;
+export declare function assertStepAllowed(state: ChangeState, stepId: string): void;
+export declare function currentGate(state: ChangeState): GateId | null;
+//# sourceMappingURL=flow.d.ts.map

package/dist/core/flow.js

@@ -0,0 +1,99 @@
+import { AppError } from '../shared/errors.js';
+import { NODES } from './types.js';
+import { nextPendingTask } from './tasks.js';
+export function nextAction(state) {
+    if (state.lastIssue?.type === 'worker_blocked') {
+        return { action: 'need_user_input', changeName: state.changeName, questions: state.lastIssue.questions };
+    }
+    if (state.lastIssue?.type === 'worker_failed') {
+        if (state.lastIssue.stepId === 'verify' && state.lastIssue.fixable) {
+            return { action: 'fix_verify', changeName: state.changeName };
+        }
+        return {
+            action: 'retry_worker',
+            changeName: state.changeName,
+            stepId: state.lastIssue.stepId ?? currentStep(state),
+        };
+    }
+    switch (state.node) {
+        case NODES.COLLECT:
+            if (state.sourceRevision === 0)
+                return { action: 'add_sources', changeName: state.changeName };
+            if (state.collectedRevision < state.sourceRevision) {
+                return { action: 'collect_sources', changeName: state.changeName };
+            }
+            return { action: 'create_worker', changeName: state.changeName, stepId: 'parse' };
+        case NODES.PARSE:
+            return { action: 'create_worker', changeName: state.changeName, stepId: 'parse' };
+        case NODES.TECH:
+            return { action: 'create_worker', changeName: state.changeName, stepId: 'tech' };
+        case NODES.PLAN:
+            return { action: 'create_worker', changeName: state.changeName, stepId: 'plan' };
+        case NODES.GATE_A:
+            return { action: 'await_gate', changeName: state.changeName, gateId: 'gate-A' };
+        case NODES.CODE: {
+            if (state.repair) {
+                return { action: 'create_worker', changeName: state.changeName, stepId: 'repair-verify' };
+            }
+            const task = nextPendingTask(state);
+            return task
+                ? { action: 'create_worker', changeName: state.changeName, stepId: `code-${task.id}` }
+                : { action: 'await_gate', changeName: state.changeName, gateId: 'gate-B' };
+        }
+        case NODES.GATE_B:
+            return { action: 'await_gate', changeName: state.changeName, gateId: 'gate-B' };
+        case NODES.VERIFY:
+            return { action: 'create_worker', changeName: state.changeName, stepId: 'verify' };
+        case NODES.GATE_C:
+            return { action: 'await_gate', changeName: state.changeName, gateId: 'gate-C' };
+        case NODES.COMPLETED:
+            return { action: 'archive', changeName: state.changeName };
+        default:
+            return { action: 'add_sources', changeName: state.changeName };
+    }
+}
+export function assertNode(state, allowed, action) {
+    if (!allowed.includes(state.node)) {
+        throw new AppError('invalid_node', `${action} 只能在 ${allowed.join(' / ')} 执行，当前节点是 ${state.node}`);
+    }
+}
+export function assertStepAllowed(state, stepId) {
+    if (state.lastIssue?.type === 'worker_failed' || state.lastIssue?.type === 'worker_blocked') {
+        if (state.lastIssue.stepId === 'verify' && state.lastIssue.fixable) {
+            throw new AppError('fix_verify_required', '验证失败且可修复，请先运行 openspec verify fix');
+        }
+        if (state.lastIssue.stepId === stepId)
+            return;
+    }
+    if (stepId === 'parse')
+        assertNode(state, [NODES.PARSE, NODES.COLLECT], 'worker create parse');
+    else if (stepId === 'tech')
+        assertNode(state, [NODES.TECH], 'worker create tech');
+    else if (stepId === 'plan')
+        assertNode(state, [NODES.PLAN], 'worker create plan');
+    else if (stepId.startsWith('code-'))
+        assertNode(state, [NODES.CODE], `worker create ${stepId}`);
+    else if (stepId === 'repair-verify') {
+        assertNode(state, [NODES.CODE], 'worker create repair-verify');
+        if (!state.repair)
+            throw new AppError('repair_not_requested', '当前没有 verify repair 请求');
+    }
+    else if (stepId === 'verify')
+        assertNode(state, [NODES.VERIFY], 'worker create verify');
+    else
+        throw new AppError('unsupported_step', `不支持的 worker step: ${stepId}`);
+}
+export function currentGate(state) {
+    if (state.node === NODES.GATE_A)
+        return 'gate-A';
+    if (state.node === NODES.GATE_B)
+        return 'gate-B';
+    if (state.node === NODES.GATE_C)
+        return 'gate-C';
+    return null;
+}
+function currentStep(state) {
+    const next = nextAction({ ...state, lastIssue: null });
+    return next.action === 'create_worker' || next.action === 'retry_worker' ? next.stepId : 'unknown';
+}
+//# sourceMappingURL=flow.js.map

package/dist/core/gates.d.ts

@@ -0,0 +1,5 @@
+import { type ChangeState, type GateId } from './types.js';
+export declare function approveGate(projectRoot: string, changeName: string, gateId: GateId, comment?: string): ChangeState;
+export declare function rejectGate(projectRoot: string, changeName: string, gateId: GateId, reason: string): ChangeState;
+export declare function resetGates(state: ChangeState): void;
+//# sourceMappingURL=gates.d.ts.map

package/dist/core/gates.js

@@ -0,0 +1,71 @@
+import { AppError } from '../shared/errors.js';
+import { requireChange } from './change.js';
+import { currentGate } from './flow.js';
+import { appendEvent, emptyGates, saveState } from './state.js';
+import { NODES } from './types.js';
+import { commitSourceUpdate } from './sources.js';
+import { loadVerifiedReport } from './verify.js';
+export function approveGate(projectRoot, changeName, gateId, comment = '') {
+    const state = requireChange(projectRoot, changeName);
+    const current = currentGate(state);
+    if (current !== gateId) {
+        throw new AppError('gate_not_awaiting', `当前等待的是 ${current ?? '无'}，不能批准 ${gateId}`);
+    }
+    const now = new Date().toISOString();
+    state.gates[gateId] = { status: 'approved', comment, updatedAt: now };
+    if (gateId === 'gate-A') {
+        state.node = NODES.CODE;
+        commitSourceUpdate(projectRoot, state);
+    }
+    if (gateId === 'gate-B')
+        state.node = NODES.VERIFY;
+    if (gateId === 'gate-C') {
+        if (!state.verifyRunId)
+            throw new AppError('verify_run_missing', 'Gate-C 缺少当前 verify run');
+        const report = loadVerifiedReport(projectRoot, changeName, state.verifyRunId);
+        if (report.status !== 'passed')
+            throw new AppError('qa_not_passed', 'Gate-C 只接受当前 verify run 的 passed report');
+        state.node = NODES.COMPLETED;
+    }
+    if (state.lastIssue?.type === 'gate_rejected' && state.lastIssue.gateId === gateId) {
+        state.lastIssue = null;
+    }
+    saveState(projectRoot, state);
+    appendEvent(projectRoot, changeName, 'gate.approved', { gateId, comment });
+    return state;
+}
+export function rejectGate(projectRoot, changeName, gateId, reason) {
+    const state = requireChange(projectRoot, changeName);
+    const current = currentGate(state);
+    if (current !== gateId) {
+        throw new AppError('gate_not_awaiting', `当前等待的是 ${current ?? '无'}，不能拒绝 ${gateId}`);
+    }
+    const now = new Date().toISOString();
+    state.gates[gateId] = { status: 'rejected', reason, updatedAt: now };
+    state.lastIssue = { type: 'gate_rejected', gateId, reason, updatedAt: now };
+    if (gateId === 'gate-A') {
+        state.node = NODES.PLAN;
+        state.tasks = [];
+    }
+    else {
+        for (const task of state.tasks) {
+            if (task.status === 'completed')
+                task.status = 'pending';
+        }
+        state.node = NODES.CODE;
+        state.verifyRunId = null;
+        state.repair = null;
+        if (gateId === 'gate-C')
+            state.gates['gate-B'] = { status: 'pending' };
+        state.gates['gate-C'] = { status: 'pending' };
+        if (gateId === 'gate-B')
+            state.gates['gate-B'] = { status: 'pending' };
+    }
+    saveState(projectRoot, state);
+    appendEvent(projectRoot, changeName, 'gate.rejected', { gateId, reason });
+    return state;
+}
+export function resetGates(state) {
+    state.gates = emptyGates();
+}
+//# sourceMappingURL=gates.js.map

package/dist/core/instructions.d.ts

@@ -0,0 +1,21 @@
+import type { ChangeState, NextAction, WorkflowName, LastIssue } from './types.js';
+export interface Instructions {
+    protocol: 1;
+    workflow: WorkflowName;
+    changeName: string;
+    node: string;
+    next: NextAction;
+    nodeFile: string;
+    progress?: {
+        total: number;
+        completed: number;
+    };
+    blocker?: LastIssue;
+}
+export declare function buildInstructions(workflow: WorkflowName, state: ChangeState): Instructions;
+/** Mutation responses carry the next instruction so controllers need no status round trip. */
+export declare function controlSummary(state: ChangeState, fields?: Record<string, unknown>): Instructions & Record<string, unknown>;
+export declare function inferWorkflow(state: Pick<ChangeState, 'node' | 'repair'>): WorkflowName;
+export declare function nodeFileFor(workflow: WorkflowName, next: NextAction, state: ChangeState): string;
+export declare function skillAbs(rel: string): string;
+//# sourceMappingURL=instructions.d.ts.map

package/dist/core/instructions.js

@@ -0,0 +1,102 @@
+import path from 'node:path';
+import { packageRoot } from '../shared/pkg.js';
+import { nextAction } from './flow.js';
+import { taskProgress } from './tasks.js';
+export function buildInstructions(workflow, state) {
+    const next = nextAction(state);
+    const payload = {
+        protocol: 1,
+        workflow,
+        changeName: state.changeName,
+        node: state.node,
+        next,
+        nodeFile: skillAbs(nodeFileFor(workflow, next, state)),
+    };
+    if (state.tasks.length > 0)
+        payload.progress = taskProgress(state);
+    return payload;
+}
+/** Mutation responses carry the next instruction so controllers need no status round trip. */
+export function controlSummary(state, fields = {}) {
+    return { ...buildInstructions(inferWorkflow(state), state), ...(state.lastIssue ? { blocker: state.lastIssue } : {}), ...fields };
+}
+export function inferWorkflow(state) {
+    if (state.repair && state.node === 'code')
+        return 'opsx-fix-verify';
+    if (['collect', 'parse', 'tech', 'plan', 'gate_a'].includes(state.node))
+        return 'opsx-propose';
+    if (['code', 'gate_b'].includes(state.node))
+        return 'opsx-apply';
+    if (['verify', 'gate_c'].includes(state.node))
+        return 'opsx-verify';
+    return 'opsx-archive';
+}
+export function nodeFileFor(workflow, next, state) {
+    const base = `skills/${workflow}/nodes`;
+    const entryNodes = {
+        'opsx-source-update': 'update', 'opsx-archive': 'archive', 'opsx-gate-decision': 'decide',
+        'opsx-resume': 'route', 'opsx-explore': 'explore',
+    };
+    if (entryNodes[workflow])
+        return `${base}/${entryNodes[workflow]}.md`;
+    if (next.action === 'need_user_input' || next.action === 'retry_worker') {
+        return workflow === 'opsx-fix-verify' ? `${base}/repair.md` : `${base}/blocked.md`;
+    }
+    if (workflow === 'opsx-apply') {
+        if (next.action === 'await_gate' && next.gateId === 'gate-A')
+            return `${base}/gate-a.md`;
+        if (next.action === 'create_worker' && next.stepId.startsWith('code-'))
+            return `${base}/code-task.md`;
+        if (next.action === 'await_gate' && next.gateId === 'gate-B')
+            return `${base}/stop.md`;
+        return `${base}/blocked.md`;
+    }
+    if (workflow === 'opsx-propose') {
+        if (next.action === 'add_sources' || next.action === 'collect_sources')
+            return `${base}/collect.md`;
+        if (next.action === 'create_worker' && next.stepId === 'parse')
+            return `${base}/parse.md`;
+        if (next.action === 'create_worker' && next.stepId === 'tech')
+            return `${base}/tech.md`;
+        if (next.action === 'create_worker' && next.stepId === 'plan')
+            return `${base}/plan.md`;
+        if (next.action === 'await_gate' && next.gateId === 'gate-A')
+            return `${base}/stop.md`;
+        return `${base}/blocked.md`;
+    }
+    if (workflow === 'opsx-verify') {
+        if (next.action === 'await_gate' && next.gateId === 'gate-B')
+            return `${base}/gate-b.md`;
+        if (next.action === 'create_worker' && next.stepId === 'verify')
+            return `${base}/verify.md`;
+        if (next.action === 'await_gate' && next.gateId === 'gate-C')
+            return `${base}/stop.md`;
+        if (next.action === 'fix_verify')
+            return `${base}/failed.md`;
+        return `${base}/blocked.md`;
+    }
+    if (workflow === 'opsx-fix-verify') {
+        if (next.action === 'fix_verify' || (next.action === 'create_worker' && next.stepId === 'repair-verify')) {
+            return `${base}/repair.md`;
+        }
+        if (next.action === 'create_worker' && next.stepId === 'verify')
+            return `${base}/reverify.md`;
+        return `${base}/stop.md`;
+    }
+    if (workflow === 'opsx-archive')
+        return `${base}/archive.md`;
+    if (workflow === 'opsx-source-update')
+        return `${base}/update.md`;
+    if (workflow === 'opsx-gate-decision')
+        return `${base}/decide.md`;
+    if (workflow === 'opsx-resume')
+        return `${base}/route.md`;
+    if (workflow === 'opsx-explore')
+        return `${base}/explore.md`;
+    void state;
+    return `${base}/blocked.md`;
+}
+export function skillAbs(rel) {
+    return path.join(packageRoot(), rel);
+}
+//# sourceMappingURL=instructions.js.map

package/dist/core/source-operations.d.ts

@@ -0,0 +1,25 @@
+import { type PluginBinding, type PluginContext } from '../hooks/plugin-runtime.js';
+export declare function operationContext(root: string, change: string, binding: PluginBinding, outputDir: string, inputFile?: string, worker?: PluginContext['worker']): {
+    context: PluginContext;
+    files: string[];
+};
+export declare function readSource(root: string, change: string, sourceId: string, inputFile?: string, use?: string): {
+    sourceId: string;
+    artifact: string;
+    artifactSha256: string;
+    raw: string;
+    runId?: undefined;
+    data?: undefined;
+    result?: undefined;
+    receipt?: undefined;
+} | {
+    sourceId: string;
+    runId: `${string}-${string}-${string}-${string}-${string}`;
+    data: unknown;
+    result: string;
+    receipt: string;
+    artifact?: undefined;
+    artifactSha256?: undefined;
+    raw?: undefined;
+};
+//# sourceMappingURL=source-operations.d.ts.map

package/dist/core/source-operations.js

@@ -0,0 +1,94 @@
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { configPathOf } from '../config/load.js';
+import { resolveAdapterEntry } from '../marketplace/adapters.js';
+import { readPluginInput, runPluginCommand, sameIdentity } from '../hooks/plugin-runtime.js';
+import { sha256File } from '../shared/hash.js';
+import { readText, writeJson } from '../shared/fs.js';
+import { AppError } from '../shared/errors.js';
+import { artifactPath, artifactRel, requireChange } from './change.js';
+import { loadLedger } from './sources.js';
+export function operationContext(root, change, binding, outputDir, inputFile, worker) {
+    const state = requireChange(root, change);
+    const params = readPluginInput(root, binding, inputFile);
+    const context = {
+        version: 1, operation: binding.operation, projectRoot: root,
+        change: { name: change, root: artifactPath(root, change, '.') },
+        input: params.input, outputDir, ...(worker ? { worker } : {}),
+    };
+    const configPath = configPathOf(root);
+    if (configPath)
+        params.files.push(path.relative(root, configPath));
+    if (binding.kind === 'adapter') {
+        if (state.sourceRevision !== state.collectedRevision)
+            throw new AppError('source_not_collected', '来源尚未完成采集');
+        const { sourceId, sourceIds } = params.input;
+        const plural = Object.hasOwn(params.input, 'sourceIds');
+        const singular = Object.hasOwn(params.input, 'sourceId');
+        const ids = plural ? sourceIds : [sourceId];
+        if (plural === singular || !Array.isArray(ids) || ids.length === 0
+            || ids.some((id) => typeof id !== 'string' || !id.trim()) || new Set(ids).size !== ids.length) {
+            throw new AppError('invalid_source_selection', 'input.sourceId 与非空、无重复的 sourceIds 二选一');
+        }
+        const ledger = loadLedger(root, change, state.sourceRevision);
+        const adapter = resolveAdapterEntry(root, binding.use);
+        const sources = ids.map((id) => {
+            const item = ledger.items.find((item) => item.id === id);
+            if (!item?.artifact)
+                throw new AppError('source_artifact_missing', `来源未采集: ${id}`);
+            if (item.adapter && (item.adapter.use !== binding.use || !sameIdentity(item.adapter.identity, binding.identity)))
+                throw new AppError('source_adapter_mismatch', `操作入口与冻结来源的 adapter 不一致: ${id}`);
+            if (adapter.entry.capability !== item.capability)
+                throw new AppError('adapter_capability_mismatch', `adapter 与来源 capability 不一致: ${id}`);
+            const artifact = artifactPath(root, change, item.artifact);
+            const artifactSha256 = sha256File(artifact);
+            if (item.artifactSha256 && item.artifactSha256 !== artifactSha256)
+                throw new AppError('source_artifact_changed', `冻结来源已变化，请走 source update: ${id}`);
+            return { id: item.id, capability: item.capability, kind: item.kind, locator: item.locator, artifact, artifactSha256 };
+        });
+        if (plural)
+            context.sources = sources;
+        else
+            context.source = sources[0];
+        params.files.push(artifactRel(change, `sources/sources-r${state.sourceRevision}.json`));
+    }
+    return { context, files: params.files };
+}
+export function readSource(root, change, sourceId, inputFile, use) {
+    const state = requireChange(root, change);
+    if (state.sourceRevision !== state.collectedRevision)
+        throw new AppError('source_not_collected', '来源尚未完成采集');
+    const source = loadLedger(root, change, state.sourceRevision).items.find((item) => item.id === sourceId);
+    if (!source?.artifact)
+        throw new AppError('source_artifact_missing', `来源未采集: ${sourceId}`);
+    const absolute = artifactPath(root, change, source.artifact);
+    const digest = sha256File(absolute);
+    if (source.artifactSha256 && source.artifactSha256 !== digest)
+        throw new AppError('source_artifact_changed', '冻结来源已变化，请走 source update');
+    const selector = use ?? source.adapter?.use;
+    if (!selector) {
+        if (inputFile)
+            throw new AppError('source_reader_unbound', '定向读取需要显式 --use；原文读取无需 input');
+        return { sourceId, artifact: source.artifact, artifactSha256: digest, raw: readText(absolute) };
+    }
+    const resolved = resolveAdapterEntry(root, selector);
+    if (!resolved.entry.operations.read) {
+        if (use || inputFile)
+            throw new AppError('adapter_operation_missing', `adapter 未声明 read: ${selector}`);
+        return { sourceId, artifact: source.artifact, artifactSha256: digest, raw: readText(absolute) };
+    }
+    const params = readPluginInput(root, {}, inputFile);
+    if (Object.hasOwn(params.input, 'sourceIds') || (Object.hasOwn(params.input, 'sourceId') && params.input.sourceId !== sourceId)) {
+        throw new AppError('invalid_source_selection', 'sources read 的 --source 不能被 input 覆盖或同时提供 sourceIds');
+    }
+    const binding = { use: selector, kind: 'adapter', operation: 'read', identity: resolved.identity, input: { ...params.input, sourceId } };
+    const runId = randomUUID();
+    const outputDir = artifactPath(root, change, `.opsx/operations/${runId}`);
+    const prepared = operationContext(root, change, binding, outputDir);
+    const result = runPluginCommand(root, binding, prepared.context, [...prepared.files, ...params.files]);
+    writeJson(path.join(outputDir, 'receipt.json'), { runId, ok: result.ok, code: result.code, ...result.receipt });
+    if (!result.ok)
+        throw new AppError('source_read_failed', '来源读取失败，查看完整输出', { outputDir, stderr: result.stderrPath });
+    return { sourceId, runId, data: result.data, result: path.relative(root, result.stdoutPath), receipt: path.relative(root, path.join(outputDir, 'receipt.json')) };
+}
+//# sourceMappingURL=source-operations.js.map

package/dist/core/sources.d.ts

@@ -0,0 +1,33 @@
+import type { ProjectConfig } from '../config/schema.js';
+import { type ChangeState, type SourceCapability, type SourceItem, type SourcesLedger } from './types.js';
+export declare function addSources(projectRoot: string, changeName: string, input: {
+    notes?: string;
+    sources?: Array<{
+        capability: string;
+        kind: SourceItem['kind'];
+        locator: string;
+    }>;
+}): SourcesLedger;
+export declare function collect(projectRoot: string, changeName: string, config: ProjectConfig, options?: {
+    refresh?: boolean;
+}): {
+    ledger: SourcesLedger;
+    artifacts: string[];
+    deferred: string[];
+    covered: string[];
+    warnings: string[];
+};
+export declare function abortUpdate(projectRoot: string, changeName: string, reason: string): SourcesLedger;
+export declare function commitSourceUpdate(projectRoot: string, state: ChangeState): void;
+export declare function loadLedger(projectRoot: string, changeName: string, revision: number): SourcesLedger;
+export declare function parseSourceArg(raw: string): {
+    capability: SourceCapability;
+    kind: SourceItem['kind'];
+    locator: string;
+};
+export declare function parseSourceFileArg(raw: string): {
+    capability: SourceCapability;
+    kind: 'file';
+    locator: string;
+};
+//# sourceMappingURL=sources.d.ts.map