sillyspec 3.24.8 → 3.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.24.8",
+  "version": "3.25.0",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/src/constants.js

@@ -80,3 +80,16 @@ export const SCAN_REQUIRED_DOCS = Object.freeze([
   'CONCERNS.md',
   'PROJECT.md',
 ])
+
+// ── 辅助 stage 清单（stage-contract 转移规则 与 stages/index 注册表 共用单一真相源）──
+// 曾在 stage-contract.js 与 stages/index.js 逐字重复定义，新增/调整辅助 stage 需同步改两处
+// 易分叉。现收敛一处。（注意：主流程序 STAGE_ORDER/mainFlowStages/flowStages 语义不同、
+// 各自用途正确，不在本清单范围。）
+export const AUXILIARY_STAGES = Object.freeze([
+  'scan',
+  'quick',
+  'explore',
+  'archive',
+  'status',
+  'doctor',
+])

package/src/contract-matrix.js

@@ -14,6 +14,7 @@ import {
   scanBackendEndpoints,
   scanFrontendApiCalls,
   normalizePath,
+  diffApiParity,
 } from './endpoint-extractor.js'
 import { parseTaskContracts } from './stages/plan-postcheck.js'
 
@@ -59,8 +60,12 @@ export function buildContractMatrix(planContent, changeDir) {
   const taskDeps = parseTaskDependencies(planContent)
 
   // 读取各 task 文档，分类 provider/consumer
+  // classify consumers（taskDeps keys）+ providers（deps 值）。
+  // 旧实现只 classify consumers → provider task 不在 keys 里 → providerClass 恒 undefined
+  // → contracts 恒空 → 端点契约管线（buildConsumerInjection / extractArtifactsForChange）全失效。
   const taskClasses = {}
-  for (const taskName of Object.keys(taskDeps)) {
+  const allTaskNames = new Set([...Object.keys(taskDeps), ...Object.values(taskDeps).flat()])
+  for (const taskName of allTaskNames) {
     const taskFile = join(changeDir, 'tasks', `${taskName}.md`)
     if (existsSync(taskFile)) {
       taskClasses[taskName] = classifyTask(readFileSync(taskFile, 'utf8'))
@@ -103,7 +108,9 @@ function parseTaskDependencies(planContent) {
   const deps = {}
 
   // 方式 1: 表格形式 | task-04 | ... | 01,02 |
-  const tableRows = planContent.matchAll(/\|[^|]*task-(\d+)[^|]*\|[^|]*\|[^|]*(?:task-)?(\d+(?:\s*[,，]\s*\d+)*)[^|]*\|/gi)
+  // 列前缀用 [^|\d]*（不吃数字）：旧 [^|]* 贪婪会吃掉 deps 列前导 0（" 01" → g2=1 → task-1），
+  // 导致 provider task-1.md 不存在 → contracts 恒空，端点契约管线失效。
+  const tableRows = planContent.matchAll(/\|[^|]*task-(\d+)[^|]*\|[^|]*\|[^|\d]*(?:task-)?(\d+(?:\s*[,，]\s*\d+)*)[^|]*\|/gi)
   for (const match of tableRows) {
     const task = `task-${match[1]}`
     const depList = match[2].split(/[,，\s]+/).map(d => `task-${d.trim()}`).filter(d => d.startsWith('task-'))
@@ -137,7 +144,9 @@ function parseTaskDependencies(planContent) {
 export function extractProviderArtifact(changeDir, worktreePath, specBase, taskName, runtimeRoot) {
   // 平台模式 contract-artifacts 落 runtimeRoot；否则落 specBase/.runtime
   const artifactRoot = runtimeRoot || join(specBase, '.runtime')
-  const artifactDir = join(artifactRoot, 'contract-artifacts', taskName)
+  // 跨变更隔离：contract-artifacts/<changeName>/<taskName>/，避免不同变更同名 task 互相覆盖污染对账
+  const changeName = changeDir ? basename(changeDir) : '_unknown'
+  const artifactDir = join(artifactRoot, 'contract-artifacts', changeName, taskName)
   const artifactPath = join(artifactDir, 'endpoints.json')
 
   if (!worktreePath || !existsSync(worktreePath)) {
@@ -171,6 +180,28 @@ export function extractProviderArtifact(changeDir, worktreePath, specBase, taskN
   }
 }
 
+/**
+ * 汇总提取一个变更内所有 provider task 的 endpoint artifact。
+ * run.js completeStep 在 execute Wave 完成时调用：扫 worktree → 按 buildContractMatrix 识别的
+ * provider task，各自落 contract-artifacts/<changeName>/<taskName>/endpoints.json。
+ * @param {{ changeDir: string, specBase: string, changeName: string, worktreePath: string|null }} args
+ * @returns {string|null} 日志摘要；无 provider/无 plan/worktree 缺失时返回 null（不打扰）
+ */
+export function extractArtifactsForChange({ changeDir, specBase, changeName, worktreePath }) {
+  if (!worktreePath || !changeDir || !existsSync(changeDir)) return null
+  const planFile = join(changeDir, 'plan.md')
+  if (!existsSync(planFile)) return null
+  const contracts = buildContractMatrix(readFileSync(planFile, 'utf8'), changeDir)
+  const providers = [...new Set(contracts.map(c => c.provider))]
+  if (providers.length === 0) return null
+  let withEndpoints = 0
+  for (const taskName of providers) {
+    const r = extractProviderArtifact(changeDir, worktreePath, specBase, taskName)
+    if (r.ok && r.endpoints.length > 0) withEndpoints++
+  }
+  return `📦 契约 artifact 提取: providers=${providers.join(',')}（${withEndpoints}/${providers.length} 含端点）`
+}
+
 // ─── Execute 阶段：前端 task 开始时注入契约 ─────────────────────────────
 
 /**
@@ -184,12 +215,13 @@ export function extractProviderArtifact(changeDir, worktreePath, specBase, taskN
 export function buildConsumerInjection(changeDir, specBase, taskName, contracts, runtimeRoot) {
   // 平台模式 contract-artifacts 落 runtimeRoot；否则落 specBase/.runtime
   const artifactRoot = runtimeRoot || join(specBase, '.runtime')
+  const changeName = changeDir ? basename(changeDir) : '_unknown'
   const myContracts = contracts.filter(c => c.consumer === taskName)
   if (myContracts.length === 0) return null
 
   const parts = []
   for (const contract of myContracts) {
-    const artifactDir = join(artifactRoot, 'contract-artifacts', contract.provider)
+    const artifactDir = join(artifactRoot, 'contract-artifacts', changeName, contract.provider)
     const artifactFile = join(artifactDir, 'endpoints.json')
 
     let endpoints = []
@@ -295,15 +327,16 @@ export function buildContractFieldInjection(changeDir, taskName) {
  * verify 阶段执行 API parity check
  * @param {string} specBase - .sillyspec 目录
  * @param {string} worktreePath - worktree 路径
- * @returns {{ ok: boolean, missingBackend: Array, unusedBackend: Array, summary: string }}
+ * @returns {{ ok: boolean, missingBackend: Array, unusedBackend: Array, summary: string, backendCount: number, frontendCount: number }}
  */
-export function verifyApiParity(specBase, worktreePath, runtimeRoot) {
-  const { diffApiParity } = require('./endpoint-extractor.js')
-
+export function verifyApiParity(specBase, scanRoot, runtimeRoot, changeName = null) {
   // 平台模式 contract-artifacts 落 runtimeRoot；否则落 specBase/.runtime
   const artifactRoot = runtimeRoot || join(specBase, '.runtime')
-  // 读取所有 provider artifacts
-  const artifactBase = join(artifactRoot, 'contract-artifacts')
+  // 读取该变更的所有 provider artifacts（contract-artifacts/<changeName>/*/endpoints.json）。
+  // changeName 缺失时回退扫顶层 contract-artifacts（CLI contractScan 跨变更场景兼容）。
+  const artifactBase = changeName
+    ? join(artifactRoot, 'contract-artifacts', changeName)
+    : join(artifactRoot, 'contract-artifacts')
   const allProviderEndpoints = []
 
   if (existsSync(artifactBase)) {
@@ -325,17 +358,12 @@ export function verifyApiParity(specBase, worktreePath, runtimeRoot) {
     }
   }
 
-  // 扫描前端调用
-  if (!worktreePath || !existsSync(worktreePath)) {
-    return {
-      ok: true,
-      missingBackend: [],
-      unusedBackend: [],
-      summary: 'No worktree to scan for parity check',
-    }
+  // 扫描前端调用（scanRoot 通常 = 主工作区 cwd：verify 时代码已 apply 到主工作区）
+  if (!scanRoot || !existsSync(scanRoot)) {
+    return { ok: true, missingBackend: [], unusedBackend: [], summary: 'No scan root for parity check', backendCount: allProviderEndpoints.length, frontendCount: 0 }
   }
 
-  const frontendCalls = scanFrontendApiCalls(worktreePath)
+  const frontendCalls = scanFrontendApiCalls(scanRoot)
   const { missingBackend, unusedBackend } = diffApiParity(frontendCalls, allProviderEndpoints)
 
   const ok = missingBackend.length === 0
@@ -347,5 +375,5 @@ export function verifyApiParity(specBase, worktreePath, runtimeRoot) {
     summary += ` | ${unusedBackend.length} backend endpoints unused by frontend`
   }
 
-  return { ok, missingBackend, unusedBackend, summary }
+  return { ok, missingBackend, unusedBackend, summary, backendCount: allProviderEndpoints.length, frontendCount: frontendCalls.length }
 }

package/src/endpoint-extractor.js

@@ -75,14 +75,96 @@ export function extractFastApiEndpoints(filePath) {
 }
 
 /**
- * 从目录递归扫描所有 Python router 文件的端点
+ * 从单个文件提取 Express（Node）路由端点。
+ * 支持 router/app.get|post|put|delete|patch("path") 与链式 router.route("path").<method>()。
+ * app.use("prefix", router) 的前缀只做同文件近似（跨文件追踪不在首版范围）。
+ *
+ * @param {string} filePath - 文件绝对路径
+ * @returns {Array<{ method: string, path: string, source: string, line: number }>}
+ */
+export function extractExpressEndpoints(filePath) {
+  const content = readFileSync(filePath, 'utf8')
+  const lines = content.split('\n')
+  const endpoints = []
+
+  // 同文件内最后一个 app.use("prefix", ...) 作为前缀近似
+  let routerPrefix = ''
+  for (const line of lines) {
+    const useMatch = line.match(/\bapp\.use\s*\(\s*["'`]([^"'`]+)["'`]/)
+    if (useMatch) routerPrefix = useMatch[1]
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const m = line.match(/\b(?:app|router)\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]+)["'`]/i)
+    if (m) {
+      endpoints.push({ method: m[1].toUpperCase(), path: routerPrefix + m[2], source: filePath, line: i + 1 })
+      continue
+    }
+    const routeChain = line.match(/\.route\s*\(\s*["'`]([^"'`]+)["'`]/)
+    if (routeChain) {
+      // 链式 .route(path).get(h).put(h) —— 同行所有 method 配上 path
+      const chainPath = routerPrefix + routeChain[1]
+      for (const mm of line.matchAll(/\.(get|post|put|delete|patch)\s*\(/gi)) {
+        endpoints.push({ method: mm[1].toUpperCase(), path: chainPath, source: filePath, line: i + 1 })
+      }
+    }
+  }
+
+  return endpoints
+}
+
+/**
+ * 从单个文件提取 Spring（Java）端点。
+ * 支持 @GetMapping/@PostMapping/.../@PatchMapping 与旧式 @RequestMapping(value="path", method=RequestMethod.X)；
+ * 类级 @RequestMapping("api") 前缀合并（取文件内第一个作类前缀，近似）。
+ *
+ * @param {string} filePath - 文件绝对路径
+ * @returns {Array<{ method: string, path: string, source: string, line: number }>}
+ */
+export function extractSpringEndpoints(filePath) {
+  const content = readFileSync(filePath, 'utf8')
+  const lines = content.split('\n')
+  const endpoints = []
+
+  let classPrefix = ''
+  for (const line of lines) {
+    const cm = line.match(/@RequestMapping\s*\(\s*(?:value\s*=\s*)?["'`]([^"'`]+)["'`]/)
+    if (cm) { classPrefix = cm[1]; break }
+  }
+
+  const methodMap = { get: 'GET', post: 'POST', put: 'PUT', delete: 'DELETE', patch: 'PATCH' }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const shortMatch = line.match(/@(Get|Post|Put|Delete|Patch)Mapping\s*\(\s*(?:value\s*=\s*)?["'`]([^"'`]+)["'`]/i)
+    if (shortMatch) {
+      endpoints.push({ method: methodMap[shortMatch[1].toLowerCase()], path: classPrefix + shortMatch[2], source: filePath, line: i + 1 })
+      continue
+    }
+    const oldMatch = line.match(/@RequestMapping\s*\(\s*(?:value\s*=\s*)?["'`]([^"'`]+)["'`][^)]*?method\s*=\s*RequestMethod\.(\w+)/i)
+    if (oldMatch) {
+      endpoints.push({ method: oldMatch[2].toUpperCase(), path: classPrefix + oldMatch[1], source: filePath, line: i + 1 })
+    }
+  }
+
+  return endpoints
+}
+
+/**
+ * 从目录递归扫描后端端点（多框架）。
+ * 按扩展名分派：.py→FastAPI / .js,.ts→Express / .java→Spring。
+ * 保留 excludePatterns（向后兼容 opts）；filePattern 在多框架分派下不再适用。
  * @param {string} dir
- * @param {{ filePattern?: RegExp, excludePatterns?: RegExp[] }} opts
+ * @param {{ excludePatterns?: RegExp[] }} opts
  * @returns {Array<{ method: string, path: string, source: string, line: number }>}
  */
 export function scanBackendEndpoints(dir, opts = {}) {
-  const filePattern = opts.filePattern || /(?:router|routes|api|endpoint|controller)\.py$/i
-  const excludePatterns = opts.excludePatterns || [/__pycache__/, /node_modules/, /\.venv/, /test/i]
+  const excludePatterns = opts.excludePatterns || [
+    /^__pycache__$/, /^node_modules$/, /^\.venv$/, /^\.git$/, /^\.gradle$/,
+    /^(dist|build|target|out)$/i,
+    /test/i,
+  ]
 
   const results = []
   if (!existsSync(dir)) return results
@@ -93,9 +175,12 @@ export function scanBackendEndpoints(dir, opts = {}) {
       if (entry.isDirectory()) {
         if (excludePatterns.some(p => p.test(entry.name))) continue
         walk(full)
-      } else if (entry.isFile() && filePattern.test(entry.name)) {
+      } else if (entry.isFile()) {
+        const ext = extname(entry.name).toLowerCase()
         try {
-          results.push(...extractFastApiEndpoints(full))
+          if (ext === '.py') results.push(...extractFastApiEndpoints(full))
+          else if (ext === '.js' || ext === '.ts') results.push(...extractExpressEndpoints(full))
+          else if (ext === '.java') results.push(...extractSpringEndpoints(full))
         } catch {}
       }
     }
@@ -224,6 +309,7 @@ export function normalizePath(rawPath) {
     .replace(/\$\{[^}]+\}/g, '{param}')
     .replace(/:\w+/g, '{param}')
     .replace(/\$\w+/g, '{param}')
+    .replace(/\{[^}]+\}/g, '{param}')   // Spring {planId} / FastAPI {plan_id} → {param}
 }
 
 // ─── 对账 ───────────────────────────────────────────────────────────────

package/src/hooks/worktree-guard.js

@@ -267,7 +267,11 @@ function queryDbFirstCell(cwd, sql) {
 }
 
 export { queryDbFirstCell as _queryDbFirstCellForTest };
-
+export {
+  matchReadonlyWhitelist as _matchReadonlyWhitelistForTest,
+  matchDangerBlacklist as _matchDangerBlacklistForTest,
+  isSingleCommandReadonly as _isSingleCommandReadonlyForTest,
+};
 /**
  * 从 sillyspec.db 读取 currentStage
  * 优先级：gate-status.json > sillyspec.db
@@ -472,7 +476,11 @@ function isSingleCommandReadonly(cmd, extraReadonlyCommands = []) {
     // node/npm/npx 需要进一步检查子命令
     if (cmdName === 'node' || cmdName === 'npm' || cmdName === 'npx') {
       const rest = parts.slice(1).join(' ')
-      return rest.includes('--version') || rest.includes('-v') && parts.length <= 3 || rest === 'run test' || rest.startsWith('test')
+      // 仅纯版本查询（`npm --version` / `node -v`，恰好两段）放行。
+      // 不能用 rest.includes('--version')：`npx any-pkg --version` 会执行 any-pkg，
+      // 旧实现因 && 优先级高于 || 使 --version 分支无长度约束，可绕过只读白名单。
+      const isBareVersionQuery = parts.length === 2 && (parts[1] === '--version' || parts[1] === '-v')
+      return isBareVersionQuery || rest === 'run test' || rest.startsWith('test')
     }
     return true
   }
@@ -531,8 +539,12 @@ function isSingleCommandDangerous(cmd) {
  * @returns {string[]}
  */
 function splitCommandParts(command) {
-  // 按管道和链式操作符拆分
-  return command.split(/(?:\|\|&&|&&|\|)/g).map(s => s.trim()).filter(Boolean)
+  // 按管道、链式操作符、语句分隔、重定向拆分。
+  // 必须覆盖 `||`/`&&`/`;`/`&`/`|`/`>`/`<`：否则 `echo foo; rm -rf x`、
+  // `cat f > /etc/passwd` 会被当成单一片段，首命令命中只读白名单 → 整条放行，
+  // 后半段的危险/写入操作绕过只读白名单与危险黑名单两道门。
+  // （`$(...)`/反引号命令替换需 shell-token 化，与零依赖风格冲突，暂不覆盖。）
+  return command.split(/\|\||&&|;|&|\||>|</g).map(s => s.trim()).filter(Boolean)
 }
 
 /**

package/src/index.js

@@ -9,6 +9,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'fs';
 import { writeAtomicSync } from './fs-atomic.js';
 import { join, resolve } from 'path';
+import { execSync } from 'child_process';
 import { cmdInit, getVersion } from './init.js';
 import { ProgressManager, resolvePlatformSpecDir } from './progress.js';
 import { detectLocalYaml } from './local-detect.js';
@@ -186,7 +187,6 @@ async function main() {
   function resolveEffectiveDir(baseDir) {
     if (existsSync(join(baseDir, '.sillyspec'))) return baseDir
     try {
-      const { execSync } = require('child_process')
       const gitRoot = execSync('git rev-parse --show-toplevel', {
         cwd: baseDir, encoding: 'utf8', timeout: 5000
       }).trim()

package/src/progress.js

@@ -225,44 +225,6 @@ export class ProgressManager {
     };
   }
 
-  async writeGlobal(cwd, data) {
-    // SQL: UPDATE project + UPSERT changes status
-    const db = await this._ensureDB(cwd);
-    db.transaction((sqlDb) => {
-      const now = new Date().toISOString();
-
-      // UPSERT project 行
-      sqlDb.run(`
-        INSERT INTO project (id, name, schema_version, created_at, updated_at)
-        VALUES (1, ?, ?, ?, ?)
-        ON CONFLICT(id) DO UPDATE SET
-          name = excluded.name,
-          schema_version = excluded.schema_version,
-          updated_at = excluded.updated_at
-      `, [data.project || '', data._version || CURRENT_VERSION, now, now]);
-
-      // 同步 changes 表：确保 activeChanges 列表中的变更存在且为 active，
-      // 不在列表中的设为 archived
-      const activeChanges = data.activeChanges || [];
-      for (const cn of activeChanges) {
-        sqlDb.run(`
-          INSERT INTO changes (name, status, created_at, last_active)
-          VALUES (?, 'active', ?, ?)
-          ON CONFLICT(name) DO UPDATE SET status = 'active', last_active = excluded.last_active
-        `, [cn, now, now]);
-      }
-      if (activeChanges.length > 0) {
-        sqlDb.run(`
-          UPDATE changes SET status = 'archived'
-          WHERE status = 'active' AND name NOT IN (${activeChanges.map(() => '?').join(',')})
-        `, activeChanges);
-      } else {
-        // 没有活跃变更，将所有 active 归档
-        sqlDb.run("UPDATE changes SET status = 'archived' WHERE status = 'active'");
-      }
-    });
-  }
-
   // ── 变更级别状态 ──
 
   /**
@@ -658,20 +620,38 @@ export class ProgressManager {
       console.error(`❌ 变更 ${newName} 已存在`);
       return;
     }
-    // 重命名目录
+    // 先更新 DB，再重命名目录；FS 失败则回滚 DB，避免"目录已改名但 DB 旧名"的孤儿
+    // （旧实现 FS-first 无补偿：renameSync 成功后 DB transaction 抛 EPERM/EBUSY 会让
+    //  目录已是 newName、DB 仍是 oldName，read(两名) 都失联且无自动恢复）。
     const oldDir = this._changePath(cwd, oldName);
     const newDir = this._changePath(cwd, newName);
+    const now = new Date().toISOString();
+    try {
+      db.transaction((sqlDb) => {
+        sqlDb.run(`UPDATE changes SET name = ?, last_active = ? WHERE name = ?`, [newName, now, oldName]);
+      });
+    } catch (e) {
+      console.error(`❌ 重命名失败：更新数据库时出错（${e.message}）`);
+      return;
+    }
+    let renamed = true;
     if (existsSync(oldDir)) {
-      renameSync(oldDir, newDir);
+      try {
+        renameSync(oldDir, newDir);
+      } catch (e) {
+        renamed = false;
+        // FS 重命名失败：回滚 DB 恢复 oldName，保持 DB 与目录一致
+        try {
+          db.transaction((sqlDb) => {
+            sqlDb.run(`UPDATE changes SET name = ?, last_active = ? WHERE name = ?`, [oldName, now, newName]);
+          });
+        } catch {}
+        console.error(`❌ 重命名失败：移动目录出错（${e.message}），已回滚数据库`);
+      }
     } else {
       mkdirSync(newDir, { recursive: true });
     }
-    // 更新 DB
-    const now = new Date().toISOString();
-    db.transaction((sqlDb) => {
-      sqlDb.run(`UPDATE changes SET name = ?, last_active = ? WHERE name = ?`, [newName, now, oldName]);
-    });
-    console.log(`✅ 变更已重命名：${oldName} → ${newName}`);
+    if (renamed) console.log(`✅ 变更已重命名：${oldName} → ${newName}`);
   }
 
   /**