create-yss-spec 3.5.4 → 3.5.5

package/vendor/cli-core/tests/migration-version.test.mjs

@@ -0,0 +1,8 @@
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {assertUpgradeVersion} from '../migrate.mjs';
+test('迁移版本顺序遵循预发布数字和正式版优先级',()=>{
+ for(const [from,to] of [['1.2.3-rc.2','1.2.3-rc.10'],['1.2.3-rc.10','1.2.3'],['1.2.3+old','1.2.3+new'],['1.2.3','1.3.0-beta.1']])assert.doesNotThrow(()=>assertUpgradeVersion(from,to));
+ for(const [from,to] of [['1.2.3','1.2.3-rc.1'],['1.2.3-rc.10','1.2.3-rc.2'],['2.0.0','1.9.9'],['1.2.3-beta','1.2.3-alpha'],['1.2.3-rc.1','1.2.3-rc']])assert.throws(()=>assertUpgradeVersion(from,to),e=>e.code==='VERSION');
+ for(const bad of ['1.2.3-','1.2.3-rc.01','01.2.3','latest'])assert.throws(()=>assertUpgradeVersion(bad,'2.0.0'),e=>e.code==='VERSION');
+});

package/vendor/cli-core/tests/package-contract.mjs

@@ -0,0 +1,75 @@
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {spawnSync} from 'node:child_process';
+import {verifyCore} from '../build.mjs';
+import {loadBundle} from '../bundle.mjs';
+const hash=bytes=>createHash('sha256').update(bytes).digest('hex');
+export function packageContract(root) {
+ const pkg=JSON.parse(fs.readFileSync(path.join(root,'package.json')));
+ const family=JSON.parse(fs.readFileSync(path.join(root,'config/family.json')));
+ const entry=path.join(root,'bin',pkg.name+'.js');
+ test(`${family.side}: 真实包初始化、接入、诊断、只读、同步和家族边界`,t=>{
+  const scratch=fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(),'harness-package-')));
+  t.after(()=>fs.rmSync(scratch,{recursive:true,force:true}));
+  const target=path.join(scratch,'project');
+  const run=(command,args=[],destination=target)=>{
+   const r=spawnSync(process.execPath,[entry,command,'--target-dir',destination,...args,'--json'],{encoding:'utf8',timeout:300000,maxBuffer:32*1024*1024});
+   let data;try{data=JSON.parse(r.stdout);}catch{}
+   return {...r,data};
+  };
+  const success=r=>{assert.equal(r.status,0,r.stderr || r.error?.message);assert.ok(r.data);return r.data;};
+  const init=['--project-name','验收项目','--business-domain','通用 CLI'];
+  const inputs=['template.snapshot.json','template.manifest.json','cli-core.lock.json'].map(p=>hash(fs.readFileSync(path.join(root,p))));
+  verifyCore(root);loadBundle(root);
+  success(run('init',[...init,'--dry-run']));assert.equal(fs.existsSync(target),false);
+  success(run('init',init));
+  const readme=path.join(target,'README.md'),context=path.join(target,'CONTEXT.md'),metadata=path.join(target,family.metadataFile);
+  fs.writeFileSync(readme,'# 用户文档\n');
+  const contextBefore=fs.readFileSync(context);
+  let before=fs.readFileSync(metadata);const journalCount=()=>fs.readdirSync(path.join(target,'.yss-harness-state',family.side,'transactions')).length;
+  const count=journalCount();
+  for(const command of ['doctor','diff','recover']) success(run(command));
+  success(run('sync',['--plan','--prune']));
+  assert.deepEqual(fs.readFileSync(metadata),before);assert.equal(journalCount(),count);
+  success(run('sync',['--apply','--prune']));
+  assert.equal(fs.readFileSync(readme,'utf8'),'# 用户文档\n');assert.deepEqual(fs.readFileSync(context),contextBefore);
+  before=fs.readFileSync(metadata);success(run('sync',['--apply']));assert.deepEqual(fs.readFileSync(metadata),before);
+  if(family.side==='design') {
+   const modern=JSON.parse(fs.readFileSync(metadata));
+   const legacy={metadataSchemaVersion:1,templateName:family.templateName,templateSource:family.templateSource,profileId:family.profileId,templateCommit:modern.templateCommit,templateSourceState:modern.templateSourceState,snapshotHash:modern.snapshotHash,managedFilesManifestVersion:modern.manifestHash,cliVersion:'0.5.2',variables:modern.variables,initializedAt:modern.initializedAt,managedFiles:Object.fromEntries(Object.entries(modern.managedFiles).map(([p,r])=>[p,{type:'copy',contentHash:r.baseline.digest}]))};
+   fs.writeFileSync(path.join(target,'scripts/instantiate-harness'),'historical creator');legacy.managedFiles['scripts/instantiate-harness']={type:'copy',contentHash:hash('historical creator')};
+   const legacyBytes=Buffer.from(JSON.stringify(legacy,null,2)+'\n');fs.writeFileSync(metadata,legacyBytes);
+   assert.equal(success(run('diff')).migrationRequired,true);success(run('doctor'));assert.deepEqual(fs.readFileSync(metadata),legacyBytes);
+   // Crash just after replacing metadata: recovery must still understand v1 before/v2 after.
+   const hook=path.join(scratch,'crash.mjs');fs.writeFileSync(hook,`import fs from 'node:fs';import {syncBuiltinESMExports} from 'node:module'; const rename=fs.renameSync;fs.renameSync=(a,b)=>{rename(a,b);if(String(b)===${JSON.stringify(metadata)})process.exit(73);};syncBuiltinESMExports();`);
+   const crashed=spawnSync(process.execPath,['--import',hook,entry,'sync','--target-dir',target,'--apply','--json'],{encoding:'utf8',timeout:300000});assert.equal(crashed.status,73,crashed.stderr);
+   success(run('recover'));success(run('recover',['--apply']));assert.deepEqual(fs.readFileSync(metadata),legacyBytes);
+   success(run('sync',['--apply']));assert.equal(JSON.parse(fs.readFileSync(metadata)).metadataSchemaVersion,2);assert.equal(fs.readFileSync(path.join(target,'scripts/instantiate-harness'),'utf8'),'historical creator');
+   assert.deepEqual(fs.readFileSync(context),contextBefore);
+   if(fs.existsSync(path.join(target,'scripts/verify-strategic-gate-migration'))) {
+    const active=path.join(target,'docs/.scratch/migration-fixture');fs.mkdirSync(active,{recursive:true});
+    fs.writeFileSync(path.join(active,'checkpoint.json'),JSON.stringify({repository_mode:'project-instance',gates:{'gate.domain-strategy-approved':{status:'approved'}}}));
+    const migrationRequired=run('doctor');assert.equal(migrationRequired.status,1);assert.equal(migrationRequired.data.status,'error');assert.equal(migrationRequired.data.checks.find(x=>x.name==='strategic-gate-migration')?.code,'STRATEGIC_GATE_MIGRATION_REQUIRED');
+    fs.rmSync(active,{recursive:true,force:true});success(run('doctor'));
+   }
+  }
+  const existing=path.join(scratch,'existing');fs.mkdirSync(path.join(existing,'src'),{recursive:true});
+  const userFiles={'README.md':'# existing\n','.gitignore':'private-local-rule\n','src/Main.java':'class Main {}\n','pom.xml':'<project/>\n','approved.yaml':'decision: approved\n'};
+  for(const [p,bytes]of Object.entries(userFiles))fs.writeFileSync(path.join(existing,p),bytes);
+  success(run('attach',[],existing));assert.equal(fs.existsSync(path.join(existing,'.yss-harness-state')),false);
+  success(run('attach',['--apply'],existing));success(run('doctor',[],existing));
+  for(const [p,bytes] of Object.entries(userFiles))assert.ok(p==='.gitignore'?fs.readFileSync(path.join(existing,p),'utf8').startsWith(bytes):fs.readFileSync(path.join(existing,p),'utf8')===bytes,p);
+  for(const foreign of ['.yss-template.json','.yss-harness-dev.json',...['design','backend','frontend'].filter(x=>x!==family.side).map(x=>`.yss-harness-${x}.json`)]) {
+   const dir=path.join(scratch,foreign.slice(1));fs.mkdirSync(dir);fs.writeFileSync(path.join(dir,foreign),'{}');
+   for(const args of [[],['--apply','--force']]) assert.equal(run('attach',args,dir).status,1);
+   assert.deepEqual(fs.readdirSync(dir),[foreign]);
+  }
+  assert.equal(run('init',[...init,'--force']).status,1);
+  for(const command of ['doctor','diff'])assert.equal(run(command,['--apply']).status,1);
+  assert.deepEqual(['template.snapshot.json','template.manifest.json','cli-core.lock.json'].map(p=>hash(fs.readFileSync(path.join(root,p)))),inputs);
+ });
+}

package/vendor/cli-core/transaction.mjs

@@ -0,0 +1,529 @@
+import * as fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import os from "node:os";
+import { spawnSync } from "node:child_process";
+import {
+  ensure,
+  safe,
+  stat,
+  descriptor,
+  same,
+  write,
+  readJson,
+  json,
+  hash,
+  targetPath,
+  governance,
+} from "./io.mjs";
+import { guardNestedRepository, gitlinks } from "./identity.mjs";
+const STATE = ".yss-harness-state";
+function syncDirectory(directory) {
+  const fd = fs.openSync(directory, "r");
+  try { fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+}
+function dirtyParents(root, ref, directories) {
+  let parent = path.dirname(ref);
+  while (parent !== ".") { directories.add(parent); parent = path.dirname(parent); }
+  directories.add(".");
+}
+function flushDirectories(root, directories) {
+  // Child directory entries reach disk before the parent which makes them reachable.
+  for (const ref of [...directories].sort((a, b) => (b === "." ? 0 : b.split("/").length) - (a === "." ? 0 : a.split("/").length))) {
+    const directory = ref === "." ? root : safe(root, ref);
+    if (stat(directory)?.isDirectory()) syncDirectory(directory);
+  }
+  directories.clear();
+}
+function operationTemporaryPath(ref, id, index) {
+  return `${ref}.${hash(`${id}:${index}`).slice(0, 36)}.tmp`;
+}
+function durable(root, ref, bytes, mode = 0o644, directories, temporaryPath, onCreated) {
+  const file = safe(root, ref);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = temporaryPath ? safe(root, temporaryPath) : file + "." + randomUUID() + ".tmp";
+  let temporaryIdentity;
+  try {
+    const fd = fs.openSync(temp, "wx", mode);
+    try {
+      temporaryIdentity = fs.fstatSync(fd);
+      onCreated?.();
+      fs.writeFileSync(fd, bytes);
+      fs.fchmodSync(fd, mode);
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    fs.renameSync(temp, file);
+    if (directories) dirtyParents(root, ref, directories);
+    else syncDirectory(path.dirname(file));
+  } finally {
+    const remaining = temporaryIdentity && stat(temp);
+    if (remaining && remaining.dev === temporaryIdentity.dev && remaining.ino === temporaryIdentity.ino) fs.unlinkSync(temp);
+  }
+}
+function readWal(target, base, journal) {
+  const wal = safe(target, `${base}/intent.wal`);
+  if (!stat(wal)) { ensure(journal.phase === "backup", "事务 WAL 缺失", "STATE"); return; }
+  const bytes = fs.readFileSync(wal, "utf8");
+  // An incomplete final append precedes its fsync, therefore no target write was allowed.
+  const complete = bytes.slice(0, bytes.lastIndexOf("\n") + 1);
+  const created = new Set();
+  journal.operations.forEach(op => { op.attempted = false; });
+  let index = 0;
+  for (const line of complete.split("\n").filter(Boolean)) {
+    const record = JSON.parse(line);
+    ensure(record.schemaVersion === 1 && record.index === index && index < journal.operations.length && Array.isArray(record.createdDirectories), "事务 WAL 损坏", "STATE");
+    const op = journal.operations[index++];
+    for (const ref of record.createdDirectories) {
+      ensure(typeof ref === "string" && op.path.startsWith(ref + "/"), "WAL 目录不在操作范围", "STATE");
+      safe(target, ref); created.add(ref);
+    }
+    op.attempted = true;
+  }
+  if (journal.phase === "verify") ensure(index === journal.operations.length, "已验证事务的 WAL 不完整", "STATE");
+  journal.createdDirectories = [...created];
+}
+export function inspectState(target, family) {
+  const state = safe(target, STATE);
+  if (!stat(state)) return { pending: [] };
+  ensure(stat(state).isDirectory(), "状态路径不是目录", "STATE");
+  const owner = readJson(target, `${STATE}/owner.json`);
+  ensure(
+    owner.schemaVersion === 1 && owner.profileId === family.profileId,
+    "未知或异族状态目录，不覆盖",
+    "STATE",
+  );
+  const transactions = safe(target, `${STATE}/${family.side}/transactions`);
+  ensure(stat(transactions)?.isDirectory(), "状态目录不完整", "STATE");
+  const pending = [];
+  for (const name of fs.readdirSync(transactions)) {
+    ensure(/^[a-f0-9-]{36}$/.test(name), "未知事务目录", "STATE");
+    const base = `${STATE}/${family.side}/transactions/${name}`,
+      journal = readJson(target, `${base}/journal.json`);
+    ensure(
+      [1, 2].includes(journal.schemaVersion) &&
+        journal.id === name &&
+        journal.profileId === family.profileId &&
+        Array.isArray(journal.operations),
+      "事务日志损坏",
+      "STATE",
+    );
+    if (!["committed", "rolled-back"].includes(journal.phase)) {
+      for (const [index, op] of journal.operations.entries()) {
+        if (op.path !== family.metadataFile) governance(op.path);
+        safe(target, op.path);
+        if (op.temporaryPath != null) ensure(
+          journal.schemaVersion === 2 && op.after !== null &&
+          op.temporaryPath === operationTemporaryPath(op.path, journal.id, index),
+          "恢复临时文件不在事务操作范围", "STATE",
+        );
+        for (const d of [op.before, op.after])
+          ensure(
+            d === null ||
+              (d?.type === "file" &&
+                /^[a-f0-9]{64}$/.test(d.digest) &&
+                Number.isInteger(d.mode) &&
+                d.mode >= 0 &&
+                d.mode <= 0o777),
+            "恢复日志描述损坏",
+            "STATE",
+          );
+      }
+      if (journal.schemaVersion === 2) readWal(target, base, journal);
+      else if (stat(safe(target, `${base}/progress.json`))) {
+        const progress = readJson(target, `${base}/progress.json`);
+        ensure(
+          Number.isInteger(progress.index) &&
+            progress.index >= 0 &&
+            progress.index < journal.operations.length,
+          "恢复进度损坏",
+          "STATE",
+        );
+        journal.operations.forEach(
+          (op, i) => (op.attempted = i <= progress.index),
+        );
+        journal.createdDirectories = progress.createdDirectories;
+      }
+      pending.push({ base, journal });
+    }
+  }
+  return { pending };
+}
+export function applyTransaction(
+  target,
+  family,
+  operations,
+  validate,
+  id = randomUUID(),
+  gitInit = false,
+  verify = () => {},
+) {
+  targetPath(target);
+  const initial = stat(target);
+  const newTargetParents = [];
+  for (let directory = target; !stat(directory); directory = path.dirname(directory)) {
+    newTargetParents.push(path.dirname(directory));
+  }
+  if (!initial) fs.mkdirSync(target, { recursive: true });
+  const prior = inspectState(target, family);
+  ensure(!prior.pending.length, "发现中断事务，请先恢复", "INTERRUPTED");
+  const createdState = !stat(safe(target, STATE));
+  if (createdState) {
+    fs.mkdirSync(safe(target, STATE));
+    durable(
+      target,
+      `${STATE}/owner.json`,
+      json({ schemaVersion: 1, profileId: family.profileId }),
+    );
+    fs.mkdirSync(safe(target, `${STATE}/${family.side}/transactions`), {
+      recursive: true,
+    });
+  }
+  clearStaleLock(target);
+  const lockRef = `${STATE}/lock.json`,
+    lock = safe(target, lockRef);
+  let acquired = false,
+    base,
+    journal,
+    wal;
+  const directories = new Set();
+  try {
+    const fd = fs.openSync(lock, "wx");
+    acquired = true;
+    fs.writeFileSync(fd, json({ pid: process.pid, host: os.hostname() }));
+    fs.closeSync(fd);
+    validate();
+    for (const op of operations)
+      ensure(
+        same(descriptor(target, op.path), op.before),
+        `计划已过期: ${op.path}`,
+        "CONCURRENT",
+      );
+    base = `${STATE}/${family.side}/transactions/${id}`;
+    fs.mkdirSync(safe(target, base));
+    journal = {
+      schemaVersion: 2,
+      id,
+      profileId: family.profileId,
+      phase: "backup",
+      createdAt: new Date().toISOString(),
+      createdDirectories: [],
+      operations: operations.map(({ path, before, after }, index) => ({
+        path,
+        before,
+        after,
+        attempted: false,
+        temporaryPath: after ? operationTemporaryPath(path, id, index) : null,
+      })),
+    };
+    durable(target, `${base}/journal.json`, json(journal));
+    dirtyParents(target, `${base}/journal.json`, directories);
+    flushDirectories(target, directories);
+    // mkdir(recursive) can create ancestors outside the transaction root. Make
+    // those directory entries durable before any operation is allowed to start.
+    for (const parent of newTargetParents) syncDirectory(parent);
+    for (let i = 0; i < operations.length; i++) {
+      const op = operations[i];
+      if (op.before) {
+        const bytes = fs.readFileSync(safe(target, op.path));
+        ensure(
+          hash(bytes) === op.before.digest,
+          "备份期间发生并发变化",
+          "CONCURRENT",
+        );
+        durable(target, `${base}/backup/${i}`, bytes, op.before.mode);
+      }
+    }
+    durable(target, `${base}/intent.wal`, Buffer.alloc(0));
+    wal = fs.openSync(safe(target, `${base}/intent.wal`), "a");
+    journal.phase = "apply";
+    durable(target, `${base}/journal.json`, json(journal));
+    const createdDirectories = new Set();
+    for (let i = 0; i < operations.length; i++) {
+      const op = operations[i];
+      if (op.path === family.metadataFile) flushDirectories(target, directories);
+      targetPath(target);
+      validate(op);
+      ensure(
+        same(descriptor(target, op.path), op.before),
+        `写入前发生并发变化: ${op.path}`,
+        "CONCURRENT",
+      );
+      const missing = [];
+      let parent = path.dirname(op.path);
+      while (parent !== "." && !stat(safe(target, parent))) {
+        missing.unshift(parent);
+        parent = path.dirname(parent);
+      }
+      const added = missing.filter(dir => !createdDirectories.has(dir));
+      const state = journal.operations[i];
+      if (state.temporaryPath) ensure(!stat(safe(target, state.temporaryPath)), "事务临时路径已有文件", "CONCURRENT");
+      fs.writeFileSync(wal, JSON.stringify({ schemaVersion: 1, index: i, createdDirectories: added }) + "\n");
+      fs.fsyncSync(wal);
+      for (const dir of added) { createdDirectories.add(dir); journal.createdDirectories.push(dir); }
+      journal.operations[i].attempted = true;
+      if (op.after) {
+        state.temporaryCreated = false;
+        durable(target, op.path, op.bytes, op.after.mode, directories, state.temporaryPath, () => { state.temporaryCreated = true; });
+      }
+      else { fs.unlinkSync(safe(target, op.path)); dirtyParents(target, op.path, directories); }
+    }
+    // Retired managed files must not leave discoverable empty skill roots.
+    // Only walk ancestors of deletions; never remove nonempty user directories.
+    for (const op of operations.filter((item) => !item.after)) {
+      let parent = path.dirname(op.path);
+      while (parent !== ".") {
+        guardRecoveryPath(target, parent + "/__retirement_check__");
+        const directory = safe(target, parent);
+        if (!stat(directory)?.isDirectory() || fs.readdirSync(directory).length) break;
+        fs.rmdirSync(directory);
+        parent = path.dirname(parent);
+      }
+    }
+    flushDirectories(target, directories);
+    validate();
+    journal.phase = "verify";
+    durable(target, `${base}/journal.json`, json(journal));
+    for (const op of operations)
+      ensure(
+        same(descriptor(target, op.path), op.after),
+        `应用后校验失败: ${op.path}`,
+        "VERIFY",
+      );
+    verify();
+    if (gitInit) {
+      const work = safe(target, `${base}/git-staging`);
+      fs.mkdirSync(work);
+      const run = spawnSync(
+        "git",
+        ["-c", "init.templateDir=", "init", "--initial-branch=main", work],
+        { encoding: "utf8" },
+      );
+      ensure(run.status === 0, `git init 失败: ${run.stderr}`, "GIT");
+      journal.gitConfigHash = hash(
+        fs.readFileSync(path.join(work, ".git/config")),
+      );
+      durable(target, `${base}/journal.json`, json(journal));
+      ensure(!stat(safe(target, ".git")), "Git 路径并发冲突", "CONCURRENT");
+      fs.renameSync(path.join(work, ".git"), safe(target, ".git"));
+      syncDirectory(target);
+    }
+    journal.phase = "committed";
+    durable(target, `${base}/journal.json`, json(journal));
+    return { transactionId: id, backupPath: path.join(target, base) };
+  } catch (error) {
+    if (wal !== undefined) { fs.closeSync(wal); wal = undefined; }
+    if (journal) {
+      const unrestored = restore(target, base, journal, validate);
+      if (unrestored.length)
+        throw Object.assign(
+          new Error(
+            `${error.message}；自动恢复未完成: ${unrestored.join(", ")}；恢复清单: ${path.join(target, base)}`,
+          ),
+          { code: "RECOVERY_FAILED" },
+        );
+    }
+    throw error;
+  } finally {
+    if (wal !== undefined) fs.closeSync(wal);
+    if (acquired && stat(lock)) fs.unlinkSync(lock);
+  }
+}
+function inspectTemporary(target, op) {
+  if (!op.temporaryPath) return null;
+  guardRecoveryPath(target, op.temporaryPath);
+  const current = descriptor(target, op.temporaryPath);
+  ensure(!current || (op.temporaryCreated !== false && same(current, op.after)),
+    `恢复临时文件无法证明归属或已有后续修改: ${op.temporaryPath}`, "RECOVERY_FAILED");
+  return current;
+}
+function restore(target, base, journal, validate = () => {}) {
+  const failed = [];
+  const directories = new Set();
+  if (journal.gitConfigHash && stat(safe(target, ".git"))) {
+    try {
+      ensure(
+        hash(fs.readFileSync(safe(target, ".git/config"))) ===
+          journal.gitConfigHash && !stat(safe(target, ".git/index")),
+        "Git 已有后续修改",
+      );
+      fs.rmSync(safe(target, ".git"), { recursive: true });
+      syncDirectory(target);
+    } catch {
+      failed.push(".git");
+    }
+  }
+  for (let i = journal.operations.length - 1; i >= 0; i--) {
+    const op = journal.operations[i];
+    if (!op.attempted) continue;
+    let failedPath = op.path;
+    try {
+      validate(op);
+      guardRecoveryPath(target, op.path);
+      dirtyParents(target, op.path, directories);
+      if (op.temporaryPath) {
+        failedPath = op.temporaryPath;
+        if (inspectTemporary(target, op)) fs.unlinkSync(safe(target, op.temporaryPath));
+        failedPath = op.path;
+      }
+      const current = descriptor(target, op.path);
+      if (same(current, op.before)) continue;
+      ensure(
+        same(current, op.after),
+        `检测到后续修改: ${op.path}`,
+        "CONCURRENT",
+      );
+      if (op.before) {
+        const bytes = fs.readFileSync(safe(target, `${base}/backup/${i}`));
+        ensure(hash(bytes) === op.before.digest, "备份摘要损坏");
+        durable(target, op.path, bytes, op.before.mode);
+      } else if (current) {
+        fs.unlinkSync(safe(target, op.path));
+        syncDirectory(path.dirname(safe(target, op.path)));
+      }
+    } catch {
+      failed.push(failedPath);
+    }
+  }
+  for (const dir of [...(journal.createdDirectories || [])].reverse()) {
+    try {
+      ensure(
+        journal.operations.some((op) => op.path.startsWith(dir + "/")),
+        "恢复目录不在事务范围",
+      );
+      guardRecoveryPath(target, dir + "/__recovery_check__");
+      const p = safe(target, dir);
+      if (stat(p)?.isDirectory() && !fs.readdirSync(p).length) { fs.rmdirSync(p); syncDirectory(path.dirname(p)); }
+    } catch {
+      failed.push(dir);
+    }
+  }
+  try { flushDirectories(target, directories); } catch { failed.push("directory-persistence"); }
+  journal.phase = failed.length ? "recovery-failed" : "rolled-back";
+  journal.unrestored = failed;
+  durable(target, `${base}/journal.json`, json(journal));
+  return failed;
+}
+function checkedRecoveryLock(target) {
+  const lock = safe(target, `${STATE}/lock.json`);
+  if (stat(lock)) {
+    const holder = readJson(target, `${STATE}/lock.json`);
+    ensure(
+      holder.host === os.hostname() &&
+        Number.isInteger(holder.pid) &&
+        holder.pid > 0,
+      "无法判断事务持有者，保留恢复清单",
+      "LOCKED",
+    );
+    let alive = true;
+    try {
+      process.kill(holder.pid, 0);
+    } catch (e) {
+      if (e.code === "ESRCH") alive = false;
+      else throw e;
+    }
+    ensure(!alive, "另一个 CLI 正在运行", "LOCKED");
+
+  }
+  return lock;
+}
+export function recoveryPreview(target, family, state, validateIdentity = () => {}) {
+  // All recovery inputs are checked before touching even the stale lock.
+  validateIdentity();
+  for (const { base, journal } of state.pending) {
+    for (let i = 0; i < journal.operations.length; i++) {
+      const op = journal.operations[i];
+      if (!op.attempted) continue;
+      guardRecoveryPath(target, op.path);
+      inspectTemporary(target, op);
+      const current = descriptor(target, op.path);
+      ensure(
+        same(current, op.before) || same(current, op.after),
+        `恢复目标已有后续修改: ${op.path}`,
+        "RECOVERY_FAILED",
+      );
+      if (op.before && !same(current, op.before)) {
+        const bytes = fs.readFileSync(safe(target, `${base}/backup/${i}`));
+        ensure(
+          hash(bytes) === op.before.digest,
+          `恢复备份摘要损坏: ${op.path}`,
+          "RECOVERY_FAILED",
+        );
+      }
+    }
+    for (const dir of journal.createdDirectories || []) {
+      ensure(
+        journal.operations.some((op) => op.path.startsWith(dir + "/")),
+        "恢复目录不在事务范围",
+        "STATE",
+      );
+      guardRecoveryPath(target, dir + "/__recovery_check__");
+    }
+  }
+  if (state.pending.length) checkedRecoveryLock(target);
+  return {schemaVersion:1,command:'recover',status:'preview',target,transactions:state.pending.map(({journal,base})=>({id:journal.id,phase:journal.phase,backupPath:path.join(target,base),paths:journal.operations.filter(op=>op.attempted).map(op=>op.path)}))};
+}
+export function recover(target, family, state, validateIdentity) {
+  recoveryPreview(target, family, state, validateIdentity);
+  const lock = checkedRecoveryLock(target);
+  if (stat(lock)) fs.unlinkSync(lock);
+  const fd = fs.openSync(lock, "wx");
+  fs.writeFileSync(fd, json({ pid: process.pid, host: os.hostname() }));
+  fs.closeSync(fd);
+  try {
+    const recovered = [];
+    for (const { base, journal } of state.pending) {
+      const failed = restore(target, base, journal, validateIdentity);
+      ensure(
+        !failed.length,
+        `自动恢复未完成: ${failed.join(", ")}；保留 ${path.join(target, base)}`,
+        "RECOVERY_FAILED",
+      );
+      recovered.push(journal.id);
+    }
+    return {
+      schemaVersion: 1,
+      status: "recovered",
+      target,
+      transactions: recovered,
+      message: "中断事务已恢复，请重新执行预览或 apply",
+    };
+  } finally {
+    fs.unlinkSync(lock);
+  }
+}
+
+function clearStaleLock(target) {
+  const ref = `${STATE}/lock.json`,
+    file = safe(target, ref);
+  if (!stat(file)) return;
+  const holder = readJson(target, ref);
+  ensure(
+    holder.host === os.hostname() &&
+      Number.isInteger(holder.pid) &&
+      holder.pid > 0,
+    "无法判断锁持有者",
+    "LOCKED",
+  );
+  let alive = true;
+  try {
+    process.kill(holder.pid, 0);
+  } catch (e) {
+    if (e.code === "ESRCH") alive = false;
+    else throw e;
+  }
+  ensure(!alive, "另一个 CLI 正在运行", "LOCKED");
+  fs.unlinkSync(file);
+}
+
+function guardRecoveryPath(target, ref) {
+  targetPath(target);
+  safe(target, ref);
+  guardNestedRepository(target, ref);
+  ensure(
+    !gitlinks(target).some((x) => ref === x || ref.startsWith(x + "/")),
+    `受保护恢复 gitlink: ${ref}`,
+    "PROTECTED",
+  );
+}