sillyspec 3.15.2 → 3.16.0

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 };
   }
 
   /**

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')
+}