@peterxiaoyang/superspec 0.1.13 → 0.1.15-alpha

package/dist/openspec.js

@@ -0,0 +1,41 @@
+// SuperSpec 流程引擎 — OpenSpec 探测
+import { execSync, execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+/** B2 修复：校验 change 字符集，防 shell 注入 */
+function validateChange(change) {
+    if (!/^[A-Za-z0-9._-]+$/.test(change)) {
+        throw new Error(`change 名称含非法字符：${change}（只允许字母数字._-）`);
+    }
+}
+export function probeOpenSpec(projectRoot, change) {
+    try {
+        const version = execSync("openspec --version 2>/dev/null", { encoding: "utf8" }).trim();
+        let changeExists = false;
+        if (change) {
+            validateChange(change);
+            changeExists = existsSync(join(projectRoot, "openspec", "changes", change));
+        }
+        return { available: true, version, changeExists };
+    }
+    catch {
+        return { available: false, version: null, changeExists: false, error: "openspec CLI 不可用" };
+    }
+}
+export function openspecStatus(projectRoot, change) {
+    validateChange(change);
+    try {
+        // B2 修复：用 execFileSync 数组传参，彻底避免 shell 解析
+        const result = execFileSync("openspec", ["status", "--change", change, "--json"], {
+            encoding: "utf8", cwd: projectRoot, stdio: ["pipe", "pipe", "ignore"],
+        });
+        return "sha256:" + createHash("sha256").update(result).digest("hex");
+    }
+    catch {
+        return "sha256:unknown";
+    }
+}
+export function changeRoot(projectRoot, change) {
+    return join(projectRoot, "openspec", "changes", change);
+}

package/dist/record.d.ts

@@ -0,0 +1,20 @@
+import type { RecordResult, Job } from "./types.ts";
+/** record job-submit：登记工作项结果 */
+export declare function recordJobSubmit(projectRoot: string, change: string, changeRoot: string, jobId: string, reportFile: string): RecordResult;
+/** record user-decision：登记用户决策 */
+export declare function recordUserDecision(projectRoot: string, change: string, inputFile: string): RecordResult;
+/** jobs list（HIGH-1 修复：从 transition_commit.new_jobs 提取，不再依赖已删除的 job_requested 事件） */
+export declare function jobsList(projectRoot: string, change: string): {
+    open: Job[];
+    accepted: Job[];
+    rejected: {
+        job_id: string;
+        role: string;
+    }[];
+};
+/** jobs packet：返回工作项执行说明 */
+export declare function jobsPacket(projectRoot: string, change: string, jobId: string): {
+    found: boolean;
+    packet?: Record<string, unknown>;
+    message: string;
+};

package/dist/record.js

@@ -0,0 +1,211 @@
+// SuperSpec 流程引擎 — record：工作项结果登记
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { ensureChangeLayout, readEvents, appendEvent, makeEvent, sha256File, withLock, } from "./store.js";
+/** 从 events 中查找 job（H4 修复：job 只在 transition_commit 的 new_jobs payload 里） */
+function findJob(events, jobId) {
+    for (const ev of events) {
+        if (ev.event_type === "transition_commit") {
+            const newJobs = ev.payload.new_jobs ?? [];
+            const job = newJobs.find(j => j.job_id === jobId);
+            if (job)
+                return job;
+        }
+    }
+    return null;
+}
+/** 检查 job 是否已终态 */
+function jobTerminalState(events, jobId) {
+    for (const ev of events) {
+        if (ev.event_type === "job_accepted" && ev.payload.job_id === jobId)
+            return "accepted";
+        if (ev.event_type === "job_rejected" && ev.payload.job_id === jobId)
+            return "rejected";
+    }
+    return null;
+}
+/** record job-submit：登记工作项结果 */
+export function recordJobSubmit(projectRoot, change, changeRoot, jobId, reportFile) {
+    return withLock(projectRoot, change, () => {
+        ensureChangeLayout(projectRoot, change);
+        const events = readEvents(projectRoot, change);
+        // 查找 job
+        const job = findJob(events, jobId);
+        if (!job) {
+            return { event_type: "job_rejected", accepted: false, message: `工作项 ${jobId} 不存在` };
+        }
+        // 检查终态
+        const terminal = jobTerminalState(events, jobId);
+        if (terminal) {
+            // 幂等检查：同 report_digest → 返回旧结果
+            const reportDigest = sha256File(reportFile) ?? "sha256:unknown";
+            const existing = events.find(e => (e.event_type === "job_accepted" || e.event_type === "job_rejected")
+                && e.payload.job_id === jobId
+                && e.payload.report_digest === reportDigest);
+            if (existing) {
+                return {
+                    event_type: existing.event_type,
+                    accepted: existing.event_type === "job_accepted",
+                    message: "幂等返回：同 report 已提交",
+                    job_state: existing.event_type === "job_accepted" ? "accepted" : "rejected",
+                };
+            }
+            // 终态 job + 不同 report → 拒绝
+            return {
+                event_type: "job_rejected",
+                accepted: false,
+                message: `工作项 ${jobId} 已终态（${terminal}），不接受新报告。需要新工作项请重跑 transition。`,
+            };
+        }
+        // 读报告
+        if (!existsSync(reportFile)) {
+            return { event_type: "job_rejected", accepted: false, message: `报告文件不存在：${reportFile}` };
+        }
+        const reportContent = readFileSync(reportFile, "utf8");
+        const reportDigest = sha256File(reportFile) ?? "sha256:unknown";
+        // acceptance checks
+        const checks = [];
+        // 0. 报告角色匹配（HIGH 5 修复）
+        try {
+            const report = JSON.parse(reportContent);
+            if (report.role && report.role !== job.role) {
+                checks.push(`报告角色 ${report.role} 与工作项角色 ${job.role} 不匹配`);
+            }
+        }
+        catch {
+            // 非 JSON 报告，Phase 1 允许（Phase 2 加正式 schema）
+        }
+        // 1. boundFiles 仍匹配当前文档（missing 也算不匹配）
+        for (const bf of job.boundFiles) {
+            const currentSha = sha256File(join(changeRoot, bf.path)) ?? "sha256:missing";
+            if (currentSha !== bf.sha) {
+                checks.push(`绑定文件 ${bf.path} 已变化（${bf.sha} → ${currentSha}）`);
+            }
+        }
+        // 2. 报告格式基本校验（非空 JSON 或文本）
+        if (!reportContent.trim()) {
+            checks.push("报告内容为空");
+        }
+        if (checks.length > 0) {
+            // 拒绝
+            const rejectEvent = makeEvent(change, "job_rejected", {
+                job_id: jobId,
+                role: job.role,
+                report_digest: reportDigest,
+                reason: checks.join("; "),
+            });
+            appendEvent(projectRoot, change, rejectEvent);
+            return {
+                event_type: "job_rejected",
+                accepted: false,
+                message: `工作项 ${jobId} 被拒绝：${checks.join("; ")}`,
+                job_state: "rejected",
+            };
+        }
+        // 接受
+        const acceptEvent = makeEvent(change, "job_accepted", {
+            job_id: jobId,
+            role: job.role,
+            report_digest: reportDigest,
+            accepted_at: new Date().toISOString(),
+        });
+        appendEvent(projectRoot, change, acceptEvent);
+        return {
+            event_type: "job_accepted",
+            accepted: true,
+            message: `工作项 ${jobId}（${job.role}）已接受`,
+            job_state: "accepted",
+        };
+    });
+}
+/** record user-decision：登记用户决策 */
+export function recordUserDecision(projectRoot, change, inputFile) {
+    return withLock(projectRoot, change, () => {
+        ensureChangeLayout(projectRoot, change);
+        if (!existsSync(inputFile)) {
+            appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", { accepted: false, reason: "file_not_found", path: inputFile }));
+            return { event_type: "user_decision_recorded", accepted: false, message: `决策文件不存在：${inputFile}` };
+        }
+        const content = readFileSync(inputFile, "utf8");
+        let decision;
+        try {
+            decision = JSON.parse(content);
+        }
+        catch {
+            appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", { accepted: false, reason: "invalid_json" }));
+            return { event_type: "user_decision_recorded", accepted: false, message: "决策文件不是有效 JSON" };
+        }
+        if (!decision.scope || !decision.answer) {
+            appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", { accepted: false, reason: "missing_scope_or_answer" }));
+            return { event_type: "user_decision_recorded", accepted: false, message: "决策文件缺少 scope 或 answer" };
+        }
+        const event = makeEvent(change, "user_decision_recorded", {
+            scope: decision.scope,
+            question: decision.question ?? "",
+            answer: decision.answer,
+            input_digest: sha256File(inputFile) ?? "sha256:unknown",
+        });
+        appendEvent(projectRoot, change, event);
+        return {
+            event_type: "user_decision_recorded",
+            accepted: true,
+            message: `用户决策已登记：scope=${decision.scope}`,
+        };
+    });
+}
+/** jobs list（HIGH-1 修复：从 transition_commit.new_jobs 提取，不再依赖已删除的 job_requested 事件） */
+export function jobsList(projectRoot, change) {
+    const events = readEvents(projectRoot, change);
+    const open = [];
+    const accepted = [];
+    const rejected = [];
+    for (const ev of events) {
+        if (ev.event_type === "transition_commit") {
+            const newJobs = ev.payload.new_jobs ?? [];
+            for (const job of newJobs) {
+                if (!open.some(j => j.job_id === job.job_id) && !accepted.some(j => j.job_id === job.job_id) && !rejected.some(r => r.job_id === job.job_id)) {
+                    open.push(job);
+                }
+            }
+        }
+        else if (ev.event_type === "job_accepted") {
+            const { job_id } = ev.payload;
+            const idx = open.findIndex(j => j.job_id === job_id);
+            if (idx >= 0) {
+                const job = open.splice(idx, 1)[0];
+                job.state = "accepted";
+                accepted.push(job);
+            }
+        }
+        else if (ev.event_type === "job_rejected") {
+            const { job_id, role } = ev.payload;
+            const idx = open.findIndex(j => j.job_id === job_id);
+            if (idx >= 0)
+                open.splice(idx, 1)[0];
+            rejected.push({ job_id, role });
+        }
+    }
+    return { open, accepted, rejected };
+}
+/** jobs packet：返回工作项执行说明 */
+export function jobsPacket(projectRoot, change, jobId) {
+    const events = readEvents(projectRoot, change);
+    const job = findJob(events, jobId);
+    if (!job) {
+        return { found: false, message: `工作项 ${jobId} 不存在` };
+    }
+    return {
+        found: true,
+        packet: {
+            job_id: job.job_id,
+            role: job.role,
+            boundFiles: job.boundFiles,
+            packet_digest: job.packet_digest,
+            required_output_kind: "report",
+            output_instructions: `请审查 ${job.boundFiles.map(f => f.path).join(", ")}，产出审查报告`,
+            stop_conditions: ["审查完成后提交报告，不要修改文档"],
+            created_from_transition: job.created_from_transition,
+        },
+        message: `工作项 ${jobId} 的执行说明`,
+    };
+}

package/dist/skill_loop.d.ts

@@ -0,0 +1,23 @@
+import type { NextOutput } from "./types.ts";
+export interface LoopStep {
+    step: number;
+    state: string;
+    path: string;
+    action: string;
+    detail?: string;
+}
+export interface LoopResult {
+    completed: boolean;
+    steps: LoopStep[];
+    finalState: string;
+    message: string;
+}
+/**
+ * 执行 agent 循环逻辑（不实际执行命令，只模拟状态推进）。
+ * 用于测试 next 返回值链是否自洽。
+ *
+ * @param nextFn next 函数（可 mock）
+ * @param executeFn 命令执行函数（可 mock，返回是否成功）
+ * @param maxSteps 防无限循环
+ */
+export declare function simulateLoop(nextFn: () => NextOutput, executeFn: (output: NextOutput) => boolean, maxSteps?: number): LoopResult;

package/dist/skill_loop.js

@@ -0,0 +1,58 @@
+// SuperSpec 流程引擎 — skill-loop：薄适配循环驱动
+/**
+ * skillLoop 是 agent 适配层的核心函数。
+ * 它不是 CLI 命令（实际 agent 循环由 LLM 驱动），
+ * 而是一个可测试的逻辑函数，验证 next→execute→record 循环的正确性。
+ */
+import { next } from "./next.js";
+/**
+ * 执行 agent 循环逻辑（不实际执行命令，只模拟状态推进）。
+ * 用于测试 next 返回值链是否自洽。
+ *
+ * @param nextFn next 函数（可 mock）
+ * @param executeFn 命令执行函数（可 mock，返回是否成功）
+ * @param maxSteps 防无限循环
+ */
+export function simulateLoop(nextFn, executeFn, maxSteps = 20) {
+    const steps = [];
+    let completed = false;
+    for (let i = 0; i < maxSteps; i++) {
+        const output = nextFn();
+        const step = {
+            step: i + 1,
+            state: output.state,
+            path: output.path,
+            action: "",
+        };
+        switch (output.path) {
+            case "done":
+                step.action = "stop";
+                step.detail = output.reason;
+                steps.push(step);
+                completed = true;
+                return { completed, steps, finalState: output.state, message: output.reason };
+            case "next_command":
+                step.action = "execute";
+                step.detail = output.next_command;
+                steps.push(step);
+                if (!executeFn(output)) {
+                    return { completed: false, steps, finalState: output.state, message: `执行失败：${output.next_command}` };
+                }
+                break;
+            case "required_job":
+                step.action = "job";
+                step.detail = output.required_jobs.map(j => `${j.role}(${j.job_id})`).join(", ");
+                steps.push(step);
+                if (!executeFn(output)) {
+                    return { completed: false, steps, finalState: output.state, message: `工作项执行失败` };
+                }
+                break;
+            case "ask_user":
+                step.action = "ask";
+                step.detail = output.ask_user.question;
+                steps.push(step);
+                return { completed: false, steps, finalState: output.state, message: `需要用户确认：${output.ask_user.question}` };
+        }
+    }
+    return { completed: false, steps, finalState: steps[steps.length - 1]?.state ?? "unknown", message: "达到最大步数" };
+}

package/dist/store.d.ts

@@ -0,0 +1,31 @@
+import type { Event, Snapshot, Ref } from "./types.ts";
+export declare function engineRoot(projectRoot: string): string;
+export declare function changeDir(projectRoot: string, change: string): string;
+export declare function eventsFile(projectRoot: string, change: string): string;
+export declare function snapshotFile(projectRoot: string, change: string): string;
+export declare function lockFile(projectRoot: string, change: string): string;
+export declare function stagingDir(projectRoot: string, change: string, transitionId: string): string;
+export declare function jobsDir(projectRoot: string, change: string): string;
+export declare function ensureChangeLayout(projectRoot: string, change: string): void;
+export declare function sha256Text(text: string): string;
+export declare function sha256File(filePath: string): string | null;
+export declare function computeDocumentDigests(changeRoot: string, docPaths: string[]): Record<string, string>;
+export declare function digestOf(obj: unknown): string;
+export declare function appendEvent(projectRoot: string, change: string, event: Event): void;
+export declare function readEvents(projectRoot: string, change: string): Event[];
+export declare function makeEvent(change: string, eventType: Event["event_type"], payload: Record<string, unknown>, opts?: {
+    transitionId?: string | null;
+    idempotencyKey?: string | null;
+    prevSnapshotDigest?: string | null;
+    inputRefs?: Ref[];
+    outputRefs?: Ref[];
+}): Event;
+export declare function eventsDigest(events: Event[]): string;
+export declare function writeSnapshot(projectRoot: string, change: string, snapshot: Snapshot): void;
+export declare function readSnapshot(projectRoot: string, change: string): Snapshot | null;
+export declare function snapshotDigest(snapshot: Snapshot): string;
+export declare function acquireLock(projectRoot: string, change: string): void;
+export declare function releaseLock(projectRoot: string, change: string): void;
+export declare function withLock<T>(projectRoot: string, change: string, fn: () => T): T;
+export declare function idempotencyKey(transitionName: string, inputs: Record<string, unknown>, prevSnapshotDigest: string | null): string;
+export declare function ref(path: string, projectRoot: string): Ref;

package/dist/store.js

@@ -0,0 +1,213 @@
+// SuperSpec 流程引擎 — 存储层：路径、指纹、事件日志、快照、锁
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, openSync, closeSync, unlinkSync, statSync, renameSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { hostname } from "node:os";
+// ===== 路径 =====
+export function engineRoot(projectRoot) {
+    return join(projectRoot, ".superspec");
+}
+export function changeDir(projectRoot, change) {
+    return join(engineRoot(projectRoot), "changes", change);
+}
+export function eventsFile(projectRoot, change) {
+    return join(changeDir(projectRoot, change), "events.jsonl");
+}
+export function snapshotFile(projectRoot, change) {
+    return join(changeDir(projectRoot, change), "snapshot.json");
+}
+export function lockFile(projectRoot, change) {
+    return join(changeDir(projectRoot, change), "lock");
+}
+export function stagingDir(projectRoot, change, transitionId) {
+    return join(changeDir(projectRoot, change), "staging", transitionId);
+}
+export function jobsDir(projectRoot, change) {
+    return join(changeDir(projectRoot, change), "jobs");
+}
+export function ensureChangeLayout(projectRoot, change) {
+    const dir = changeDir(projectRoot, change);
+    mkdirSync(dir, { recursive: true });
+    mkdirSync(join(dir, "jobs"), { recursive: true });
+    mkdirSync(join(dir, "staging"), { recursive: true });
+    mkdirSync(join(dir, "raw"), { recursive: true });
+    const ef = eventsFile(projectRoot, change);
+    if (!existsSync(ef))
+        writeFileSync(ef, "", "utf8");
+}
+// ===== 指纹 =====
+export function sha256Text(text) {
+    return "sha256:" + createHash("sha256").update(text, "utf8").digest("hex");
+}
+export function sha256File(filePath) {
+    if (!existsSync(filePath) || !statSync(filePath).isFile())
+        return null;
+    return "sha256:" + createHash("sha256").update(readFileSync(filePath)).digest("hex");
+}
+export function computeDocumentDigests(changeRoot, docPaths) {
+    const digests = {};
+    for (const p of docPaths) {
+        const full = join(changeRoot, p);
+        digests[p] = sha256File(full) ?? "sha256:missing";
+    }
+    return digests;
+}
+export function digestOf(obj) {
+    const keys = Object.keys(obj).sort();
+    return sha256Text(JSON.stringify(obj, keys));
+}
+// ===== 事件日志 =====
+let eventSeq = 0;
+export function appendEvent(projectRoot, change, event) {
+    const line = JSON.stringify(event) + "\n";
+    const ef = eventsFile(projectRoot, change);
+    // append
+    const fd = openSync(ef, "a");
+    try {
+        writeFileSync(fd, line, "utf8");
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function readEvents(projectRoot, change) {
+    const ef = eventsFile(projectRoot, change);
+    if (!existsSync(ef))
+        return [];
+    const content = readFileSync(ef, "utf8");
+    // H3 修复：逐行解析，跳过损坏行（截断 JSON），不整体崩溃
+    const events = [];
+    for (const line of content.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch {
+            // 截断/损坏行跳过（崩溃恢复：最后一条可能是半写入的）
+        }
+    }
+    return events;
+}
+export function makeEvent(change, eventType, payload, opts = {}) {
+    const base = {
+        change_id: change,
+        event_type: eventType,
+        transition_id: opts.transitionId ?? null,
+        idempotency_key: opts.idempotencyKey ?? null,
+        created_at: new Date().toISOString(),
+        actor: process.env.SUPERSPEC_ACTOR ?? "cli",
+        prev_snapshot_digest: opts.prevSnapshotDigest ?? null,
+        input_refs: opts.inputRefs ?? [],
+        output_refs: opts.outputRefs ?? [],
+        payload,
+    };
+    const event_digest = digestOf(base);
+    const event_id = `EVT-${Date.now()}-${++eventSeq}`;
+    return { event_id, ...base, event_digest };
+}
+export function eventsDigest(events) {
+    return sha256Text(events.map(e => e.event_digest).join("\n"));
+}
+// ===== 快照 =====
+export function writeSnapshot(projectRoot, change, snapshot) {
+    writeFileSync(snapshotFile(projectRoot, change), JSON.stringify(snapshot, null, 2) + "\n", "utf8");
+}
+export function readSnapshot(projectRoot, change) {
+    const sf = snapshotFile(projectRoot, change);
+    if (!existsSync(sf))
+        return null;
+    try {
+        return JSON.parse(readFileSync(sf, "utf8"));
+    }
+    catch {
+        // H3 修复：损坏的 snapshot.json 返回 null（让调用方走 sync 重建）
+        return null;
+    }
+}
+export function snapshotDigest(snapshot) {
+    return sha256Text(JSON.stringify({
+        state: snapshot.state,
+        events_digest: snapshot.events_digest,
+        document_digests: snapshot.document_digests,
+        tasks_structure_digest: snapshot.tasks_structure_digest,
+        open_jobs: snapshot.open_jobs.map(j => j.job_id),
+        accepted_jobs: snapshot.accepted_jobs.map(j => j.job_id),
+        // H5 修复：纳入 task 状态（否则幂等键不反映任务世界状态）
+        active_task_attempts: (snapshot.active_task_attempts ?? []).map(a => a.attempt_id),
+        task_statuses: snapshot.task_statuses,
+    }));
+}
+// ===== 锁（per-change 文件锁，PID + staleness 回收）=====
+const LOCK_STALE_MS = 5 * 60 * 1000;
+export function acquireLock(projectRoot, change) {
+    ensureChangeLayout(projectRoot, change); // 确保 change 目录存在（含 events.jsonl）
+    const lf = lockFile(projectRoot, change);
+    const info = {
+        pid: process.pid,
+        hostname: hostname(),
+        created_at: new Date().toISOString(),
+    };
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = openSync(lf, "wx");
+            try {
+                writeFileSync(fd, JSON.stringify(info) + "\n", "utf8");
+            }
+            finally {
+                closeSync(fd);
+            }
+            return;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            // 尝试回收 stale lock
+            const existing = readLockInfo(lf);
+            if (existing && isLockStale(existing)) {
+                unlinkSync(lf);
+                continue; // retry
+            }
+            throw new Error(`Lock contention: ${lf} held by pid=${existing?.pid} on ${existing?.hostname}. ` +
+                `If no engine process is active, remove the lock file manually.`);
+        }
+    }
+    throw new Error(`Failed to acquire lock after stale recovery: ${lf}`);
+}
+export function releaseLock(projectRoot, change) {
+    try {
+        unlinkSync(lockFile(projectRoot, change));
+    }
+    catch { /* best effort */ }
+}
+function readLockInfo(lf) {
+    try {
+        return JSON.parse(readFileSync(lf, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function isLockStale(info) {
+    const age = Date.now() - new Date(info.created_at).getTime();
+    return age > LOCK_STALE_MS;
+}
+export function withLock(projectRoot, change, fn) {
+    acquireLock(projectRoot, change);
+    try {
+        return fn();
+    }
+    finally {
+        releaseLock(projectRoot, change);
+    }
+}
+// ===== 幂等键 =====
+export function idempotencyKey(transitionName, inputs, prevSnapshotDigest) {
+    // strip 时间戳/审计字段；保留安全前提 digest
+    const stripped = { transition: transitionName, ...inputs, _world: prevSnapshotDigest };
+    return sha256Text(JSON.stringify(stripped, Object.keys(stripped).sort()));
+}
+// ===== 工具 =====
+export function ref(path, projectRoot) {
+    return { path, sha: sha256File(join(projectRoot, path)) ?? "sha256:missing" };
+}

package/dist/sync.d.ts

@@ -0,0 +1,3 @@
+import type { Snapshot } from "./types.ts";
+/** 重建 snapshot（sync 的核心） */
+export declare function rebuildSnapshot(projectRoot: string, change: string, changeRoot: string, openspecStatusDigest?: string): Snapshot;