sillyspec 3.15.0 → 3.16.0

package/src/worktree-apply.js

@@ -92,9 +92,17 @@ export function applyWorktree(changeName, { cwd, checkOnly = false } = {}) {
   // 同时检测 untracked 新文件（git diff 不包含 untracked）
   let changedFiles;
   try {
-    // tracked 文件的变更（modified/deleted）
-    const trackedRaw = git(worktreePath, `diff --name-only ${diffBase}`);
-    const trackedFiles = trackedRaw ? trackedRaw.split('\n').filter(Boolean) : [];
+    // 用 --name-status 捕获 rename/delete（--name-only 会丢失 rename 源文件）
+    const statusRaw = git(worktreePath, `diff --name-status ${diffBase}`);
+    const statusFiles = new Set();
+    if (statusRaw) {
+      for (const line of statusRaw.split('\n').filter(Boolean)) {
+        const parts = line.split('\t');
+        // R100 old.txt new.txt → 提取两个文件
+        if (parts.length >= 2) statusFiles.add(parts[parts.length - 1]);
+        if (parts.length >= 3) statusFiles.add(parts[parts.length - 2]);
+      }
+    }
 
     // untracked 新文件（diffBase 中不存在的文件）
     const untrackedRaw = gitQuiet(worktreePath, `ls-files --others --exclude-standard`);
@@ -102,7 +110,7 @@ export function applyWorktree(changeName, { cwd, checkOnly = false } = {}) {
       ? untrackedRaw.split('\n').filter(Boolean).filter(f => !f.startsWith('.sillyspec/') && f !== 'meta.json')
       : [];
 
-    changedFiles = [...new Set([...trackedFiles, ...untrackedFiles])];
+    changedFiles = [...new Set([...statusFiles, ...untrackedFiles])];
   } catch (e) {
     result.errors.push(`获取变更文件列表失败: ${e.message}`);
     return result;
@@ -216,8 +224,11 @@ export function applyWorktree(changeName, { cwd, checkOnly = false } = {}) {
 
     // 分 tracked 变更和 untracked 新文件生成 patch
     const trackedFiles = patchFiles.filter(f => {
-      // untracked 文件在 baseHash 的 tree 中不存在
-      return gitQuiet(worktreePath, `cat-file -e ${diffBase}:${f}`) !== null;
+      // 文件在 diffBase 的 tree 中存在 → tracked（包括 rename 目标可能的情况）
+      if (gitQuiet(worktreePath, `cat-file -e ${diffBase}:${f}`) !== null) return true;
+      // 文件在工作区 index 中已存在（比如被 git mv 处理过）→ 也视为 tracked
+      if (gitQuiet(worktreePath, `ls-files --error-unmatch ${f}`) !== null) return true;
+      return false;
     });
     const untrackedPatchFiles = patchFiles.filter(f => !trackedFiles.includes(f));
 
@@ -290,3 +301,105 @@ export function applyWorktree(changeName, { cwd, checkOnly = false } = {}) {
 
   return result;
 }
+
+/**
+ * 格式化 execute run summary（人类可读）
+ *
+ * 只展示 CLI 真实掌握的信息，不声称知道 per-task 状态。
+ * @param {object} opts
+ * @param {string} opts.changeName - 变更名
+ * @param {number} opts.stepsCompleted - 已完成步骤数
+ * @param {number} opts.stepsTotal - 总步骤数
+ * @param {string} opts.agentSummary - Agent 最终输出摘要
+ * @param {string} [opts.cwd] - 项目根目录（默认 process.cwd()）
+ * @returns {string} 格式化的 summary 文本
+ */
+export function formatExecuteSummary({ changeName, stepsCompleted, stepsTotal, agentSummary, cwd }) {
+  const wm = new WorktreeManager({ cwd });
+  const meta = wm.getMeta(changeName);
+  const lines = [];
+
+  const SEPARATOR = '─'.repeat(32);
+
+  // --- Header ---
+  lines.push(`Execute Summary`);
+  lines.push(SEPARATOR);
+
+  // --- Status ---
+  if (!meta) {
+    // worktree 不存在（可能已 cleanup 或没有用过 worktree）
+    lines.push(`Status:     COMPLETED`);
+    lines.push(`Steps:      ${stepsCompleted} / ${stepsTotal}`);
+    lines.push(`Apply:      N/A`);
+  } else {
+    const hasBaseline = meta.baselineCommit != null;
+    const wtExists = existsSync(meta.worktreePath);
+
+    const applyStatus = wtExists ? 'pending' : 'applied';
+    const baselineCount = meta.baselineFiles?.length || 0;
+    const baselineStatus = hasBaseline
+      ? `dirty (${baselineCount} baseline file${baselineCount === 1 ? '' : 's'} protected)`
+      : 'clean';
+
+    // Worktree 最终状态
+    const mode = meta.mode || 'worktree';
+    let worktreeStatus;
+    if (mode === 'native-worktree') {
+      worktreeStatus = 'kept (external worktree)';
+    } else if (mode === 'in-place-fallback') {
+      worktreeStatus = 'none (in-place)';
+    } else if (!wtExists) {
+      worktreeStatus = 'cleaned';
+    } else {
+      worktreeStatus = 'exists';
+    }
+
+    lines.push(`Status:     COMPLETED`);
+    lines.push(`Steps:      ${stepsCompleted} / ${stepsTotal}`);
+    lines.push(`Baseline:   ${baselineStatus}`);
+    lines.push(`Apply:      ${applyStatus}`);
+    lines.push(`Worktree:   ${worktreeStatus}`);
+  }
+
+  // --- Changed files ---
+  // 从主工作区 diff 获取（worktree 已 apply）或从 worktree diff 获取
+  if (meta && existsSync(meta.worktreePath)) {
+    // worktree 还在，用 baselineCommit 或 baseHash 做 diff
+    try {
+      const diffBase = meta.baselineCommit || meta.baseHash;
+      const { execSync: es } = require('child_process');
+      const filesRaw = es(`git -C ${meta.worktreePath} diff --name-only ${diffBase} 2>/dev/null`, { encoding: 'utf8' });
+      const files = filesRaw ? filesRaw.trim().split('\n').filter(Boolean) : [];
+      if (files.length > 0) {
+        lines.push(``);
+        const maxShow = 10;
+        const showFiles = files.slice(0, maxShow);
+        const remain = files.length - maxShow;
+        lines.push(`Changed Files (${files.length})`);
+        showFiles.forEach(f => lines.push(`  ${f}`));
+        if (remain > 0) {
+          lines.push(`  ... ${remain} more`);
+        }
+      }
+    } catch {}
+  }
+
+  // --- Agent Summary ---
+  if (agentSummary) {
+    lines.push(``);
+    lines.push(`Agent Summary`);
+    // 缩进每行，截断过长内容
+    const maxLen = 200;
+    const summary = agentSummary.length > maxLen
+      ? agentSummary.slice(0, maxLen) + '...'
+      : agentSummary;
+    summary.split('\n').forEach(l => lines.push(`  ${l}`));
+  }
+
+  // --- Next ---
+  lines.push(``);
+  lines.push(`Next`);
+  lines.push(`  → sillyspec run verify`);
+
+  return lines.join('\n');
+}

package/src/worktree.js

@@ -17,6 +17,45 @@ const WORKTREES_REL = '.sillyspec/.runtime/worktrees';
 const BRANCH_PREFIX = 'sillyspec/';
 const META_FILE = 'meta.json';
 
+/**
+ * 检测当前目录的隔离状态
+ * 返回 { inWorktree: boolean, inSubmodule: boolean }
+ *
+ * 用 git rev-parse --git-dir 和 --git-common-dir 判断：
+ * - GIT_DIR != GIT_COMMON 通常是 linked worktree
+ * - 但在 git submodule 里也会出现这种情况
+ * - 所以必须额外检查 --show-superproject-working-tree 排除 submodule
+ */
+export function detectIsolation(cwd = process.cwd()) {
+  try {
+    const gitDir = execSync('git rev-parse --git-dir', { cwd, encoding: 'utf8', stdio: ['pipe','pipe','pipe'] }).trim();
+    const gitCommonDir = execSync('git rev-parse --git-common-dir', { cwd, encoding: 'utf8', stdio: ['pipe','pipe','pipe'] }).trim();
+    const superProject = gitQuiet(cwd, 'rev-parse --show-superproject-working-tree');
+
+    const inWorktree = gitDir !== gitCommonDir && !superProject;
+    const inSubmodule = !!superProject;
+
+    return { inWorktree, inSubmodule, gitDir, gitCommonDir };
+  } catch {
+    return { inWorktree: false, inSubmodule: false, gitDir: null, gitCommonDir: null };
+  }
+}
+
+/**
+ * 检查 worktree 存储目录是否被 .gitignore 忽略
+ * @param {string} cwd - 项目根目录
+ * @returns {{ ignored: boolean, path: string }}
+ */
+export function checkWorktreeDirIgnored(cwd = process.cwd()) {
+  const relPath = WORKTREES_REL;
+  try {
+    execSync(`git check-ignore -q ${relPath}`, { cwd, encoding: 'utf8', stdio: ['pipe','pipe','pipe'] });
+    return { ignored: true, path: relPath };
+  } catch {
+    return { ignored: false, path: relPath };
+  }
+}
+
 function git(cwd, args) {
   return execSync(`git ${args}`, { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
 }
@@ -115,7 +154,37 @@ export class WorktreeManager {
     const worktreePath = this.getWorktreePath(name);
     const branch = BRANCH_PREFIX + name;
 
-    // 1. 检查 worktree 是否已存在
+    // 0. 检测当前环境隔离状态（submodule guard）
+    const isolation = detectIsolation(this.cwd);
+    if (isolation.inSubmodule) {
+      throw new Error(
+        '当前目录在 git submodule 内，SillySpec worktree 不支持在 submodule 中创建。' +
+        '\n请在主仓库中执行，或使用 --no-worktree 跳过隔离。'
+      );
+    }
+    if (isolation.inWorktree) {
+      // 已在 linked worktree 中，复用当前目录作为 worktree 路径
+      console.log(`ℹ️  已在 linked worktree 中（git-dir: ${isolation.gitDir}），复用当前隔离环境。`);
+      return this._createInPlaceMeta(name, {
+        worktreePath: this.cwd,
+        branch: gitQuiet(this.cwd, 'symbolic-ref --short HEAD') || 'detached',
+        mode: 'native-worktree',
+        base,
+      });
+    }
+
+    // 1. 检查 worktree 目录是否被 gitignore
+    const ignoreStatus = checkWorktreeDirIgnored(this.cwd);
+    if (!ignoreStatus.ignored) {
+      throw new Error(
+        `worktree 存储目录 ${ignoreStatus.path} 未被 .gitignore 忽略，` +
+        `创建 worktree 可能导致内容被误提交。\n` +
+        `请先在 .gitignore 中添加: ${ignoreStatus.path}/\n` +
+        `或运行 sillyspec doctor 检查修复。`
+      );
+    }
+
+    // 2. 检查 worktree 是否已存在
     if (existsSync(worktreePath)) {
       // 目录在但 meta.json 不存在（幽灵状态），自动清理
       if (!this.getMeta(name)) {
@@ -147,7 +216,7 @@ export class WorktreeManager {
       mkdirSync(this.worktreeBase, { recursive: true });
     }
 
-    // 5. 创建 worktree（含版本检测）
+    // 5. 创建 worktree（含版本检测 + sandbox fallback）
     try {
       git(this.cwd, `worktree add ${worktreePath} -b ${branch} ${baseHash}`);
     } catch (e) {
@@ -155,7 +224,16 @@ export class WorktreeManager {
       if (!check.supported) {
         throw new Error(`git worktree add 失败: ${e.stderr || e.message}\n\n${check.reason ? `原因: ${check.reason}` : ''}\n建议: 使用 --no-worktree 标志跳过隔离，或升级 git 到 >= 2.15`);
       }
-      throw new Error(`git worktree add 失败: ${e.stderr || e.message}`);
+      // sandbox/permission fallback: 降级为 in-place + baseline protection
+      console.log(`⚠️  git worktree add 失败（可能是沙箱权限限制），降级为 in-place 模式 + baseline protection`);
+      console.log(`   原因: ${e.stderr || e.message}`);
+      return this._createInPlaceMeta(name, {
+        worktreePath: this.cwd,
+        branch,
+        baseBranch,
+        baseHash,
+        mode: 'in-place-fallback',
+      });
     }
 
     // 5.5 自动同步远程最新代码（防止 worktree 基于过时的 commit）
@@ -206,15 +284,99 @@ export class WorktreeManager {
       actualBaseHash: gitQuiet(worktreePath, 'rev-parse HEAD') || baseHash,
       createdAt: new Date().toISOString(),
       worktreePath,
+      mode: 'worktree',
       baselineFiles,
       baselineCommit,
-      baselineHash,  // 有 dirty baseline 时指向 checkpoint commit
+      baselineHash,
     };
 
     const metaPath = join(worktreePath, META_FILE);
     writeFileSync(metaPath, JSON.stringify(meta, null, 2) + '\n');
 
-    return { branch, worktreePath, baseHash };
+    return { branch, worktreePath, baseHash, mode: meta.mode };
+  }
+
+  /**
+   * 创建 in-place 模式的 meta.json（降级路径）
+   * 不创建 git worktree，直接在当前目录记录 baseline 并写入 meta
+   * @private
+   */
+  _createInPlaceMeta(name, { worktreePath, branch, baseBranch, baseHash, mode } = {}) {
+    // 解析 base
+    if (!baseHash) {
+      baseBranch = baseBranch || gitQuiet(this.cwd, 'symbolic-ref --short HEAD') || gitQuiet(this.cwd, 'rev-parse HEAD');
+      baseHash = git(this.cwd, 'rev-parse HEAD');
+    }
+
+    const baselineResult = this._overlayBaseline(this.cwd, this.cwd);
+    const baselineFiles = baselineResult.files;
+    const baselineHash = baselineResult.baselineHash;
+
+    let baselineCommit = null;
+    if (baselineFiles.length > 0) {
+      baselineCommit = this._createBaselineCheckpoint(this.cwd, name);
+    }
+
+    const meta = {
+      changeName: name,
+      branch: branch || BRANCH_PREFIX + name,
+      baseBranch,
+      baseHash,
+      actualBaseHash: gitQuiet(worktreePath, 'rev-parse HEAD') || baseHash,
+      createdAt: new Date().toISOString(),
+      worktreePath,
+      mode: mode || 'in-place-fallback',
+      baselineFiles,
+      baselineCommit,
+      baselineHash,
+    };
+
+    // in-place 模式下 meta 写入 worktreeBase（避免污染主工作区）
+    if (!existsSync(this.worktreeBase)) {
+      mkdirSync(this.worktreeBase, { recursive: true });
+    }
+    const metaPath = join(this.worktreeBase, name, META_FILE);
+    const metaDir = join(this.worktreeBase, name);
+    if (!existsSync(metaDir)) {
+      mkdirSync(metaDir, { recursive: true });
+    }
+    writeFileSync(metaPath, JSON.stringify(meta, null, 2) + '\n');
+
+    return { branch: meta.branch, worktreePath, baseHash, mode: meta.mode };
+  }
+
+  /**
+   * 构建 isolation 信息对象，用于写入 gate-status.json
+   * @param {string} changeName
+   * @returns {{ status: string, mode: string, path: string } | null}
+   */
+  getIsolationInfo(changeName) {
+    const meta = this.getMeta(changeName);
+    if (!meta) return null;
+
+    const mode = meta.mode || 'worktree';
+    const statusMap = {
+      'worktree': 'verified',
+      'native-worktree': 'verified',
+      'in-place-fallback': 'degraded',
+    };
+
+    return {
+      status: statusMap[mode] || 'verified',
+      mode,
+      path: meta.worktreePath,
+      branch: meta.branch,
+    };
+  }
+
+  /**
+   * 获取 worktree 的运行模式
+   * @param {string} changeName
+   * @returns {'worktree'|'native-worktree'|'in-place-fallback'|null}
+   */
+  getMode(changeName) {
+    const meta = this.getMeta(changeName);
+    return meta?.mode || null;
   }
 
   /**
@@ -239,6 +401,7 @@ export class WorktreeManager {
         baseBranch: meta.baseBranch,
         createdAt: meta.createdAt,
         worktreePath: meta.worktreePath,
+        mode: meta.mode || 'worktree',
       });
     }
 
@@ -246,24 +409,43 @@ export class WorktreeManager {
   }
 
   /**
-   * 清理 worktree（强制删除，不 apply）
+   * 清理 worktree（仅限 SillySpec 创建的临时 worktree）
    * @param {string} changeName
-   * @throws {Error} worktree 不存在
+   * @param {{ force?: boolean }} opts - force: 跳过 mode 安检（仅用于 worktree 目录本身）
+   * @throws {Error} worktree 不存在、不允许删除
+   * @returns {{ result: 'cleaned'|'skipped'|'kept', mode: string }}
    */
-  cleanup(changeName) {
+  cleanup(changeName, { force = false } = {}) {
     const name = validateChangeName(changeName);
     const meta = this.getMeta(name);
     const worktreePath = this.getWorktreePath(name);
 
     if (!meta && !existsSync(worktreePath)) {
-      throw new Error(`worktree not found: ${name}。meta.json 不存在，目录也不存在，可能已被清理或从未创建。`);
+      return { result: 'skipped', mode: null };
+    }
+
+    const mode = meta?.mode || 'worktree';
+
+    // 安全检查：只有 SillySpec 创建的 worktree 才允许删除
+    if (!force) {
+      if (mode === 'native-worktree') {
+        throw new Error(
+          `当前 worktree 是外部/原生隔离环境（mode: native-worktree），SillySpec 不允许删除。\n` +
+          `此 worktree 不是由 SillySpec 创建的，请手动管理。\n` +
+          `如需强制清理，使用 --force 标志。`
+        );
+      }
+      if (mode === 'in-place-fallback') {
+        return { result: 'skipped', mode };
+      }
     }
 
     // 1. 尝试 git worktree remove
+    let gitRemoveOk = true;
     try {
       git(this.cwd, `worktree remove ${worktreePath} --force`);
-    } catch {
-      // git worktree remove 失败，尝试直接删除目录
+    } catch (e) {
+      gitRemoveOk = false;
     }
     const branch = (meta && meta.branch) || BRANCH_PREFIX + name;
 
@@ -283,6 +465,14 @@ export class WorktreeManager {
     if (existsSync(worktreePath)) {
       rmSync(worktreePath, { recursive: true, force: true });
     }
+
+    // 5. 清除 meta 目录（如果 worktree 目录在 worktreeBase 下）
+    const metaDir = join(this.worktreeBase, name);
+    if (existsSync(metaDir)) {
+      rmSync(metaDir, { recursive: true, force: true });
+    }
+
+    return { result: gitRemoveOk ? 'cleaned' : 'force-cleaned', mode };
   }
 
   /**
@@ -302,10 +492,11 @@ export class WorktreeManager {
       const staged = gitQuiet(mainCwd, 'diff --cached --name-only') || '';
       if (staged) {
         try {
-          const patchContent = execSync(`git diff --cached --binary`, { cwd: mainCwd, encoding: 'utf8', stdio: ['pipe','pipe','pipe'] });
-          if (patchContent) {
+          // 用 Buffer 模式读取，避免二进制 patch 被 UTF-8 解码损坏
+          const patchBuf = execSync(`git diff --cached --binary`, { cwd: mainCwd, stdio: ['pipe','pipe','pipe'] });
+          if (patchBuf && patchBuf.length > 0) {
             const patchFile = join(worktreePath, '.sillyspec-baseline-staged.patch');
-            writeFileSync(patchFile, patchContent);
+            writeFileSync(patchFile, patchBuf);
             git(worktreePath, `apply --binary ${patchFile}`);
             rmSync(patchFile, { force: true });
           }
@@ -319,10 +510,11 @@ export class WorktreeManager {
       const unstaged = gitQuiet(mainCwd, 'diff --name-only') || '';
       if (unstaged) {
         try {
-          const patchContent = execSync(`git diff --binary`, { cwd: mainCwd, encoding: 'utf8', stdio: ['pipe','pipe','pipe'] });
-          if (patchContent) {
+          // 用 Buffer 模式读取，避免二进制 patch 被 UTF-8 解码损坏
+          const patchBuf = execSync(`git diff --binary`, { cwd: mainCwd, stdio: ['pipe','pipe','pipe'] });
+          if (patchBuf && patchBuf.length > 0) {
             const patchFile = join(worktreePath, '.sillyspec-baseline-unstaged.patch');
-            writeFileSync(patchFile, patchContent);
+            writeFileSync(patchFile, patchBuf);
             git(worktreePath, `apply --binary ${patchFile}`);
             rmSync(patchFile, { force: true });
           }

package/test/scan-paths.test.mjs

@@ -0,0 +1,68 @@
+/**
+ * 防回归测试：scan.js 中不允许硬编码 .sillyspec/docs/<project>/ 作为写入路径
+ * 所有正式文档路径必须使用 {DOCS_ROOT} 占位符
+ */
+import { readFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const scanPath = join(__dirname, '..', 'src', 'stages', 'scan.js')
+const content = readFileSync(scanPath, 'utf8')
+
+const banned = [
+  '.sillyspec/docs/<project>/scan/',
+  '.sillyspec/docs/<project>/modules/',
+  '.sillyspec/docs/<project>/flows/',
+  '.sillyspec/docs/<project>/glossary.md',
+]
+
+const required = [
+  '{DOCS_ROOT}/scan/',
+  '{DOCS_ROOT}/modules/',
+  '{DOCS_ROOT}/flows/',
+]
+
+let failed = false
+
+// 禁止硬编码路径
+for (const pattern of banned) {
+  if (content.includes(pattern)) {
+    console.error(`❌ FAIL: scan.js 仍包含硬编码路径 "${pattern}"`)
+    failed = true
+  } else {
+    console.log(`✅ PASS: 不包含 "${pattern}"`)
+  }
+}
+
+// 必须包含占位符
+for (const pattern of required) {
+  if (content.includes(pattern)) {
+    console.log(`✅ PASS: 包含占位符 "${pattern}"`)
+  } else {
+    console.error(`❌ FAIL: scan.js 缺少占位符 "${pattern}"`)
+    failed = true
+  }
+}
+
+// 禁止硬编码 projects 路径
+if (content.includes('.sillyspec/projects/')) {
+  console.error('❌ FAIL: scan.js 仍包含硬编码 ".sillyspec/projects/"')
+  failed = true
+} else {
+  console.log('✅ PASS: 不包含 ".sillyspec/projects/"')
+}
+
+if (content.includes('{PROJECTS_ROOT}/')) {
+  console.log('✅ PASS: 包含占位符 "{PROJECTS_ROOT}/"')
+} else {
+  console.error('❌ FAIL: scan.js 缺少占位符 "{PROJECTS_ROOT}/"')
+  failed = true
+}
+
+if (failed) {
+  console.error('\n💥 有测试失败！scan.js 路径占位符可能被回退为硬编码。')
+  process.exit(1)
+} else {
+  console.log('\n✅ 全部通过 — scan.js 路径占位符防回归测试 OK')
+}