@peterxiaoyang/superspec 0.1.14 → 0.1.16-alpha

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;

package/dist/sync.js

@@ -0,0 +1,135 @@
+// SuperSpec 流程引擎 — sync：从当前文档 + events.jsonl 重建 snapshot
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { readEvents, eventsDigest, computeDocumentDigests, sha256File, sha256Text, ensureChangeLayout, } from "./store.js";
+const TRACKED_DOCS = [
+    "proposal.md", "design.md", "tasks.md",
+    ".superspec/artifacts/discovery.md",
+    ".superspec/artifacts/business-invariants.md",
+    ".superspec/artifacts/test-contract.md",
+];
+/** 从 events.jsonl 推导：当前状态、jobs、attempts、pending decisions */
+function replayEvents(events) {
+    let state = "init";
+    const openJobs = [];
+    const acceptedJobs = [];
+    const activeAttempts = [];
+    const taskStatuses = {};
+    let lastTransition = null;
+    for (const ev of events) {
+        switch (ev.event_type) {
+            case "transition_commit": {
+                const p = ev.payload;
+                state = p.to_state;
+                if (ev.transition_id)
+                    lastTransition = ev.transition_id;
+                // HIGH 6 修复：从 commit payload replay job
+                const created = ev.payload.created_job_ids ?? [];
+                const payloadJobs = ev.payload.new_jobs ?? [];
+                for (const jid of created) {
+                    const job = payloadJobs.find(j => j.job_id === jid);
+                    if (job && !openJobs.some(j => j.job_id === jid))
+                        openJobs.push(job);
+                }
+                break;
+            }
+            // H4 修复：删除 job_requested / job_invalidated 死分支——job 只通过 transition_commit 的 new_jobs payload 创建，staleness 只在 sync 内存计算（不写事件）
+            case "job_accepted": {
+                const { job_id } = ev.payload;
+                const idx = openJobs.findIndex(j => j.job_id === job_id);
+                if (idx >= 0) {
+                    const job = openJobs.splice(idx, 1)[0];
+                    job.state = "accepted";
+                    acceptedJobs.push(job);
+                }
+                break;
+            }
+            case "job_rejected": {
+                const { job_id } = ev.payload;
+                const idx = openJobs.findIndex(j => j.job_id === job_id);
+                if (idx >= 0) {
+                    openJobs.splice(idx, 1)[0]; // remove from open
+                }
+                break;
+            }
+            // H4：job_invalidated 事件从不发射（删除死分支）
+            case "task_started": {
+                const attempt = ev.payload;
+                activeAttempts.push(attempt);
+                taskStatuses[attempt.task_id] = "doing";
+                break;
+            }
+            case "task_completed": {
+                const { task_id, attempt_id } = ev.payload;
+                const idx = activeAttempts.findIndex(a => a.attempt_id === attempt_id);
+                if (idx >= 0)
+                    activeAttempts[idx].state = "closed";
+                taskStatuses[task_id] = "done";
+                break;
+            }
+            case "task_abandoned": {
+                const { attempt_id } = ev.payload;
+                const idx = activeAttempts.findIndex(a => a.attempt_id === attempt_id);
+                if (idx >= 0)
+                    activeAttempts.splice(idx, 1);
+                break;
+            }
+        }
+    }
+    return { state, openJobs, acceptedJobs, activeAttempts, taskStatuses, lastTransition };
+}
+/** 粗粒度失效：检查 accepted job 的 boundFiles 是否仍匹配当前文档 */
+function checkStaleJobs(acceptedJobs, documentDigests) {
+    const stale = [];
+    for (const job of acceptedJobs) {
+        for (const bf of job.boundFiles) {
+            const current = documentDigests[bf.path];
+            if (current && current !== bf.sha) {
+                stale.push({
+                    job_id: job.job_id,
+                    reason: `绑定文件 ${bf.path} 已变化（${bf.sha} → ${current}）`,
+                });
+                break; // 一个文件变就够了
+            }
+        }
+    }
+    return stale;
+}
+/** 解析 tasks.md 结构指纹（复选框归一化） */
+function tasksStructureDigest(changeRoot) {
+    const tasksPath = join(changeRoot, "tasks.md");
+    if (!existsSync(tasksPath))
+        return null;
+    const content = readFileSync(tasksPath, "utf8");
+    // 复选框归一化：- [x] → - [ ]
+    const normalized = content.replace(/- \[[xX]\]/g, "- [ ]");
+    return sha256Text(normalized);
+}
+/** 重建 snapshot（sync 的核心） */
+export function rebuildSnapshot(projectRoot, change, changeRoot, openspecStatusDigest = "sha256:unknown") {
+    ensureChangeLayout(projectRoot, change);
+    const events = readEvents(projectRoot, change);
+    const evDigest = eventsDigest(events);
+    const documentDigests = computeDocumentDigests(changeRoot, TRACKED_DOCS);
+    const tsDigest = tasksStructureDigest(changeRoot);
+    const { state, openJobs, acceptedJobs, activeAttempts, taskStatuses, lastTransition } = replayEvents(events);
+    // 粗粒度失效检查（只读，不写事件）
+    const staleInfo = checkStaleJobs(acceptedJobs, documentDigests);
+    // stale 的 job 从 accepted 移除（sync 只反映当前事实）
+    const freshAccepted = acceptedJobs.filter(j => !staleInfo.some(s => s.job_id === j.job_id));
+    return {
+        change_id: change,
+        state,
+        openspec_status_digest: openspecStatusDigest,
+        events_digest: evDigest,
+        document_digests: documentDigests,
+        tasks_structure_digest: tsDigest,
+        task_statuses: taskStatuses,
+        open_jobs: openJobs,
+        accepted_jobs: freshAccepted,
+        active_task_attempts: activeAttempts,
+        pending_user_decisions: [],
+        last_transition: lastTransition,
+        computed_at: new Date().toISOString(),
+    };
+}

package/dist/task.d.ts

@@ -0,0 +1,7 @@
+/** tasks.md 结构指纹（委托给 format.ts 统一实现） */
+export declare function tasksStructureDigestOf(changeRoot: string): string | null;
+/** record test-run：登记测试运行记录 */
+export declare function recordTestRun(projectRoot: string, change: string, inputFile: string): {
+    accepted: boolean;
+    message: string;
+};

package/dist/task.js

@@ -0,0 +1,44 @@
+// SuperSpec 流程引擎 — task：测试运行记录 + 任务结构指纹工具
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { sha256Text, ensureChangeLayout, appendEvent, makeEvent, withLock } from "./store.js";
+import { tasksStructureDigest as formatDigest } from "./format.js";
+/** tasks.md 结构指纹（委托给 format.ts 统一实现） */
+export function tasksStructureDigestOf(changeRoot) {
+    const p = join(changeRoot, "tasks.md");
+    if (!existsSync(p))
+        return null;
+    const content = readFileSync(p, "utf8");
+    return formatDigest(content, sha256Text);
+}
+/** record test-run：登记测试运行记录 */
+export function recordTestRun(projectRoot, change, inputFile) {
+    return withLock(projectRoot, change, () => {
+        ensureChangeLayout(projectRoot, change);
+        if (!existsSync(inputFile))
+            return { accepted: false, message: `文件不存在：${inputFile}` };
+        let tr;
+        try {
+            tr = JSON.parse(readFileSync(inputFile, "utf8"));
+        }
+        catch {
+            return { accepted: false, message: "无效 JSON" };
+        }
+        if (!tr.test_id || !tr.task_structure_digest) {
+            return { accepted: false, message: "缺少 test_id 或 task_structure_digest" };
+        }
+        const event = makeEvent(change, "test_run_recorded", {
+            test_id: tr.test_id,
+            task_structure_digest: tr.task_structure_digest,
+            attempt_id: tr.attempt_id ?? null,
+            command: tr.command ?? "",
+            cwd: tr.cwd ?? "",
+            exit_code: tr.exit_code ?? -1,
+            semantic_status: tr.semantic_status ?? "unknown",
+            target_fingerprint: tr.target_fingerprint ?? null,
+            raw_log_ref: tr.raw_log_ref ?? null,
+        });
+        appendEvent(projectRoot, change, event);
+        return { accepted: true, message: `测试运行已登记：test_id=${tr.test_id}` };
+    });
+}

package/dist/transition.d.ts

@@ -0,0 +1,34 @@
+import type { Snapshot, State, Job, TransitionResult } from "./types.ts";
+interface Decision {
+    fromState: State;
+    toState: State;
+    outcome: "advanced" | "job_created";
+    newJobs?: Job[];
+    reason: string;
+    extraEvents?: {
+        type: string;
+        payload: Record<string, unknown>;
+    }[];
+    postCommit?: (projectRoot: string, change: string, changeRoot: string) => void;
+}
+/**
+ * 统一 transition 提交协议——所有校验在锁内。
+ */
+export declare function commitTransition(projectRoot: string, change: string, changeRoot: string, opts: {
+    name: string;
+    decide: (snapshot: Snapshot) => Decision | {
+        skip: true;
+        message: string;
+    };
+    idempotencyInputs?: Record<string, unknown>;
+}): TransitionResult;
+export declare function proposeReady(projectRoot: string, change: string, changeRoot: string, risk?: "minimal" | "normal" | "strict"): TransitionResult;
+export declare function transitionInit(projectRoot: string, change: string, changeRoot: string): TransitionResult;
+export declare function transitionExplore(projectRoot: string, change: string, changeRoot: string, risk?: "minimal" | "normal" | "strict"): TransitionResult;
+export declare function startApply(projectRoot: string, change: string, changeRoot: string): TransitionResult;
+export declare function taskStart(projectRoot: string, change: string, changeRoot: string, taskId: string): TransitionResult;
+export declare function reviewReady(projectRoot: string, change: string, changeRoot: string, risk?: "minimal" | "normal" | "strict"): TransitionResult;
+export declare function accept(projectRoot: string, change: string, changeRoot: string): TransitionResult;
+export declare function archive(projectRoot: string, change: string, changeRoot: string): TransitionResult;
+export declare function taskComplete(projectRoot: string, change: string, changeRoot: string, taskId: string): TransitionResult;
+export {};