sillyspec 3.17.0 → 3.17.2

package/package.json

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

package/src/run.js

@@ -299,7 +299,9 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
   console.log(`project: ${projectName}`)
   if (changeName) {
     console.log(`change: ${changeName}`)
-    const changeDir = join('.sillyspec', 'changes', changeName)
+    const isPlatform = platformOpts?.specRoot || platformOpts?.runtimeRoot
+    const changeDirBase = isPlatform ? platformOpts.specRoot : '.sillyspec'
+    const changeDir = join(changeDirBase, 'changes', changeName)
     console.log(`changeDir: ${changeDir}`)
   }
   console.log(`---\n`)
@@ -418,7 +420,9 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
   }
   // 路径安全规则：防止 AI 拼错变更目录
   if (changeName) {
-    const changeDir = join('.sillyspec', 'changes', changeName)
+    const isPlatform = platformOpts?.specRoot || platformOpts?.runtimeRoot
+    const changeDirBase = isPlatform ? platformOpts.specRoot : '.sillyspec'
+    const changeDir = join(changeDirBase, 'changes', changeName)
     console.log(`- **文件路径规则：所有变更文件必须写入 \`${changeDir}/\` 目录下。不要自己拼接路径，直接使用 changeDir 值。示例：\`${changeDir}/proposal.md\`**`)
   }
   const changeFlag = changeName ? ` --change ${changeName}` : ''
@@ -471,7 +475,12 @@ export async function runCommand(args, cwd, specDir = null) {
   // 首次 scan 时写入，所有后续调用（包括 run、--done、--skip）都读取
   // 优先在 specDir 下查找，否则回退到 cwd/.sillyspec/.runtime/
   const specRoot = platformOpts.specRoot || resolveSpecDir(cwd)
-  const platformOptsFile = join(specRoot, '.runtime', 'platform-scan.json')
+  // 平台参数恢复策略：
+  // 1. 优先检查 cwd/.sillyspec-platform.json（轻量指针文件，不污染 .sillyspec 结构）
+  // 2. 然后检查 specRoot/.runtime/platform-scan.json（首次 scan 写入）
+  const platformPointer = join(cwd, '.sillyspec-platform.json')
+  const platformScanFile = join(specRoot, '.runtime', 'platform-scan.json')
+  let platformOptsFile = existsSync(platformPointer) ? platformPointer : platformScanFile
   let platformFileExists = existsSync(platformOptsFile)
   // 如果命令行没传 spec-root，尝试从持久化文件恢复
   if (!platformOpts.specRoot && !platformOpts.runtimeRoot) {
@@ -499,7 +508,8 @@ export async function runCommand(args, cwd, specDir = null) {
       }
     }
   }
-  // 持久化 platformOpts（命令行传入或已恢复的都持久化）
+  // 持久化 platformOpts
+  // 在 specRoot/.runtime/ 写主文件，同时在 cwd/.sillyspec/.runtime/ 写恢复指针
   if (platformOpts.specRoot || platformOpts.runtimeRoot) {
     try {
       const { mkdirSync, writeFileSync } = await import('fs')
@@ -511,11 +521,24 @@ export async function runCommand(args, cwd, specDir = null) {
         scanRunId: platformOpts.scanRunId,
         savedAt: new Date().toISOString(),
       }, null, 2) + '\n')
+      // 恢复指针：在 cwd 下写 .sillyspec-platform.json（不在 .sillyspec 内，不污染源码结构）
+      // 供后续 --done（不带 --spec-root）找到 specDir
+      writeFileSync(join(cwd, '.sillyspec-platform.json'), JSON.stringify({
+        specRoot: platformOpts.specRoot,
+        runtimeRoot: platformOpts.runtimeRoot,
+        workspaceId: platformOpts.workspaceId,
+        scanRunId: platformOpts.scanRunId,
+        savedAt: new Date().toISOString(),
+      }, null, 2) + '\n')
     } catch {
       // 静默失败，不影响主流程
     }
   }
 
+  // 统一规范基路径：平台模式用 specRoot，本地模式用 cwd/.sillyspec
+  // runCommand 后续所有 .sillyspec/ 操作必须用 specBase
+  const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
+
   // 解析 --output
   let outputText = null
   const outputIdx = flags.indexOf('--output')
@@ -750,7 +773,7 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
         startedAt: new Date().toISOString(),
       }
       // 写入 quick-guard.json 供 worktree-guard hook 读取
-      const guardFile = join(cwd, '.sillyspec', '.runtime', 'quick-guard.json')
+      const guardFile = join(specBase, '.runtime', 'quick-guard.json')
       writeFileSync(guardFile, JSON.stringify(progress.quickGuard, null, 2))
       const parts = [`${baselineFiles.length} 个已有脏文件`]
       if (allowedFiles.length > 0) parts.push(`${allowedFiles.length} 个 allowedFiles`)
@@ -775,8 +798,8 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
   }
 }
 
-function validateMetadata(cwd, stageName) {
-  const changesDir = join(cwd, '.sillyspec', 'changes')
+function validateMetadata(cwd, stageName, specBase) {
+  const changesDir = join(specBase, 'changes')
   if (!existsSync(changesDir)) return
 
   const cutoff = Date.now() - 10 * 60 * 1000
@@ -810,11 +833,11 @@ function validateMetadata(cwd, stageName) {
  * 验证关键文件是否存在于正确的变更目录下
  * 防止 AI 将文件写到错误的路径
  */
-function validateFileLocations(cwd, stageName, progress, changeName) {
+function validateFileLocations(cwd, stageName, progress, changeName, specBase) {
   const effectiveChange = changeName || progress.currentChange
   if (!effectiveChange) return
 
-  const changeDir = join(cwd, '.sillyspec', 'changes', effectiveChange)
+  const changeDir = join(specBase, 'changes', effectiveChange)
   if (!existsSync(changeDir)) return
 
   // 每个阶段完成后预期存在的文件
@@ -840,7 +863,7 @@ function validateFileLocations(cwd, stageName, progress, changeName) {
     console.log(`  变更目录：${changeDir.replace(cwd + '/', '')}/`)
     for (const f of missing) {
       // 检查是否写到了错误的位置
-      const wrongPath = join(cwd, '.sillyspec', 'changes', 'change', effectiveChange, f)
+      const wrongPath = join(specBase, 'changes', 'change', effectiveChange, f)
       if (existsSync(wrongPath)) {
         console.log(`  ❌ ${f} — 不存在，但发现了错误路径：${wrongPath.replace(cwd + '/', '')}`)
         console.log(`     提示：应该写入 ${changeDir.replace(cwd + '/', '')}/${f}`)
@@ -860,7 +883,7 @@ async function archiveChangeDirectory(pm, cwd, progress) {
     console.error('❌ 归档失败：未找到当前变更名（currentChange）')
     process.exit(1)
   }
-  const changesDir = join(cwd, '.sillyspec', 'changes')
+  const changesDir = join(specBase, 'changes')
   const archiveDir = join(changesDir, 'archive')
   const srcDir = join(changesDir, archiveChangeName)
   const date = new Date().toISOString().slice(0, 10)
@@ -888,6 +911,7 @@ async function archiveChangeDirectory(pm, cwd, progress) {
 
 async function completeStep(pm, progress, stageName, cwd, outputText, inputText = null, options = {}) {
   const { printNext = true, confirm = false, changeName, platformOpts = {} } = options
+  const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
   const stageData = progress.stages[stageName]
   if (!stageData || !stageData.steps) {
     console.error(`❌ 阶段 ${stageName} 未初始化`)
@@ -911,7 +935,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
       // 平台模式：artifact 写入 runtime-root，否则写 .sillyspec/.runtime/artifacts
       const artifactBase = platformOpts?.runtimeRoot
         ? join(platformOpts.runtimeRoot, 'scan-runs', platformOpts.scanRunId || 'unknown')
-        : join(cwd, '.sillyspec', '.runtime', 'artifacts')
+        : join(specBase, '.runtime', 'artifacts')
       mkdirSync(artifactBase, { recursive: true })
       const ts = new Date().toISOString().slice(0,19).replace(/[-T:]/g, '')
       writeFileSync(join(artifactBase, `${changeName || 'unknown'}-${stageName}-step${currentIdx + 1}-${ts}.txt`), outputText)
@@ -992,7 +1016,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
     if (projectNames.length === 0) {
       // 回退：读取所有已注册项目
       console.warn('⚠️ 未能从 step 2 输出解析项目列表，回退扫描所有注册项目')
-      const projectsDir = join(cwd, '.sillyspec', 'projects')
+      const projectsDir = join(specBase, 'projects')
       if (existsSync(projectsDir)) {
         projectNames = readdirSync(projectsDir)
           .filter(f => f.endsWith('.yaml'))
@@ -1004,8 +1028,8 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
     }
 
     // 保存到 runtime 供后续使用 + 防重复展开
-    const scanStatePath = join(cwd, '.sillyspec', '.runtime', 'scan-projects.json')
-    mkdirSync(join(cwd, '.sillyspec', '.runtime'), { recursive: true })
+    const scanStatePath = join(specBase, '.runtime', 'scan-projects.json')
+    mkdirSync(join(specBase, '.runtime'), { recursive: true })
     let scanState = { projects: projectNames, expanded: false }
     if (existsSync(scanStatePath)) {
       try { scanState = JSON.parse(readFileSync(scanStatePath, 'utf8')) } catch {}
@@ -1024,14 +1048,14 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
       let insertPos = insertBase
       for (const pName of projectNames) {
         // 读取项目配置获取 projectRoot
-        const projYaml = join(cwd, '.sillyspec', 'projects', `${pName}.yaml`)
+        const projYaml = join(specBase, 'projects', `${pName}.yaml`)
         let projectRoot = '.'
         if (existsSync(projYaml)) {
           const yamlContent = readFileSync(projYaml, 'utf8')
           const pathMatch = yamlContent.match(/^path:\s*(.+)/m)
           if (pathMatch) projectRoot = pathMatch[1].trim()
         }
-        const docOutputDir = `.sillyspec/docs/${pName}`
+        const docOutputDir = platformOpts.specRoot ? `${specBase}/docs/${pName}` : `.sillyspec/docs/${pName}`
         const contextPrefix = `\n---\n## 当前项目\n- **项目名**: ${pName}\n- **项目路径**: ${projectRoot}\n- **文档输出**: ${docOutputDir}\n\n⚠️ 本步骤只处理上面这个项目，不要处理其他项目。\n---\n\n`
 
         for (const ppStep of perProjectSteps) {
@@ -1071,7 +1095,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
 
     // Append to user-inputs.md
     if (outputText) {
-      const inputsPath = join(cwd, '.sillyspec', '.runtime', 'user-inputs.md')
+      const inputsPath = join(specBase, '.runtime', 'user-inputs.md')
       const entry = `\n## ${new Date().toLocaleString('zh-CN',{hour12:false})} | ${changeName || '?'} | ${stageName}: ${steps[currentIdx].name}\n${inputText ? "- 输入：" + inputText + "\n" : ""}- 输出：${outputText}\n`
       appendFileSync(inputsPath, entry)
     }
@@ -1082,7 +1106,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         const { mkdirSync, writeFileSync } = await import('fs')
         const { join } = await import('path')
         const { execSync } = await import('child_process')
-        const manifestDir = join(platformOpts.specRoot, '.sillyspec')
+        const manifestDir = platformOpts.specRoot
         mkdirSync(manifestDir, { recursive: true })
         let sourceCommit = null
         try {
@@ -1149,10 +1173,10 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
       printScanPostCheckResult(postResult)
     }
 
-    validateMetadata(cwd, stageName)
+    validateMetadata(cwd, stageName, specBase)
 
     // 验证关键文件是否在正确的变更目录下
-    validateFileLocations(cwd, stageName, progress, changeName)
+    validateFileLocations(cwd, stageName, progress, changeName, specBase)
 
     // 辅助阶段完成后重置步骤
     const stageDef = stageRegistry[stageName]
@@ -1224,7 +1248,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
     // 清理 quick-guard.json
     try {
       const { unlinkSync } = await import('fs')
-      const guardFile = join(cwd, '.sillyspec', '.runtime', 'quick-guard.json')
+      const guardFile = join(specBase, '.runtime', 'quick-guard.json')
       unlinkSync(guardFile)
     } catch {}
     if (review.status === 'blocked') {
@@ -1249,7 +1273,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
 
   // Append to user-inputs.md
   if (outputText) {
-    const inputsPath = join(cwd, '.sillyspec', '.runtime', 'user-inputs.md')
+    const inputsPath = join(specBase, '.runtime', 'user-inputs.md')
     const entry = `\n## ${new Date().toLocaleString('zh-CN',{hour12:false})} | ${changeName || '?'} | ${stageName}: ${steps[currentIdx].name}\n${inputText ? "- 输入：" + inputText + "\n" : ""}- 输出：${outputText}\n`
     appendFileSync(inputsPath, entry)
   }
@@ -1275,7 +1299,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
           projectsToCheck = [currentProjectName]
         } else {
           // 兼容旧模式（未展开）：检查所有项目
-          const projectsDir = join(cwd, '.sillyspec', 'projects')
+          const projectsDir = join(specBase, 'projects')
           const projectFiles = existsSync(projectsDir)
             ? readdirSync(projectsDir).filter(f => f.endsWith('.yaml'))
             : []

package/src/stage-contract.js

@@ -33,9 +33,12 @@ function validateScanOutputs(cwd, changeName, context = {}) {
   const { projectName, specRoot } = context
   // 平台模式使用 specRoot，本地模式使用 cwd
   const base = specRoot || cwd
+  // 如果 base 已经是 specDir（有 docs/ 子目录），直接用 base/docs/
+  // 否则按传统模式拼接 .sillyspec/docs/
+  const isSpecDir = existsSync(join(base, 'docs'))
   const docsRoot = projectName
-    ? join(base, '.sillyspec', 'docs', projectName, 'scan')
-    : join(base, '.sillyspec', 'docs', 'scan')
+    ? join(base, isSpecDir ? 'docs' : '.sillyspec/docs', projectName, 'scan')
+    : join(base, isSpecDir ? 'docs' : '.sillyspec/docs', 'scan')
 
   const requiredDocs = [
     'ARCHITECTURE.md',
@@ -58,8 +61,8 @@ function validateScanOutputs(cwd, changeName, context = {}) {
 
   // 检查 modules 目录
   const modulesRoot = projectName
-    ? join(base, '.sillyspec', 'docs', projectName, 'modules')
-    : join(base, '.sillyspec', 'docs', 'modules')
+    ? join(base, isSpecDir ? 'docs' : '.sillyspec/docs', projectName, 'modules')
+    : join(base, isSpecDir ? 'docs' : '.sillyspec/docs', 'modules')
   if (!existsSync(modulesRoot)) {
     warnings.push('modules 目录不存在')
   } else {

package/test/platform-recovery.test.mjs

@@ -0,0 +1,141 @@
+/**
+ * platform-recovery.test.mjs — 平台模式参数恢复 + stage-contract 路径测试
+ */
+
+import { join, resolve, dirname, basename } from 'path'
+import { existsSync, mkdirSync, writeFileSync, rmSync, readFileSync } from 'fs'
+import { fileURLToPath, pathToFileURL } from 'url'
+import { execSync } from 'child_process'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const root = resolve(__dirname, '..')
+const binCLI = join(root, 'bin', 'sillyspec.js')
+
+let passed = 0, failed = 0
+
+function assert(cond, msg) {
+  if (cond) { console.log(`  ✅ PASS: ${msg}`); passed++ }
+  else { console.log(`  ❌ FAIL: ${msg}`); failed++ }
+}
+
+const P = 'recover'
+function setup(name) {
+  const d = join('/tmp', `${P}-${name}`)
+  mkdirSync(d, { recursive: true })
+  return d
+}
+function spec(name) {
+  const d = join('/tmp', `${P}-${name}-spec`)
+  mkdirSync(d, { recursive: true })
+  return d
+}
+function clean(...dirs) { for (const d of dirs) try { rmSync(d, { recursive: true, force: true }) } catch {} }
+
+function run(cmd) {
+  return execSync(cmd, { encoding: 'utf8', timeout: 15000, stdio: ['pipe', 'pipe', 'pipe'] })
+}
+
+const DOCS = ['ARCHITECTURE.md','CONVENTIONS.md','STRUCTURE.md','INTEGRATIONS.md','TESTING.md','CONCERNS.md','PROJECT.md']
+function writeSpecDocs(dir) {
+  for (const d of DOCS) {
+    const p = join(dir, 'scan', d)
+    mkdirSync(dirname(p), { recursive: true })
+    writeFileSync(p, 'author: bot\ncreated_at: now\n# doc\n')
+  }
+}
+function writeLocalDocs(cwd) {
+  for (const d of DOCS) {
+    const p = join(cwd, '.sillyspec', 'docs', basename(cwd), 'scan', d)
+    mkdirSync(dirname(p), { recursive: true })
+    writeFileSync(p, 'author: bot\ncreated_at: now\n# doc\n')
+  }
+}
+
+// ── Test 1: platform-scan.json 写入位置 ──
+console.log('\n=== Test 1: platform-scan.json 写入位置 ===')
+{
+  const cwd = setup('t1'), sd = spec('t1')
+  run(`node "${binCLI}" init "${cwd}" --spec-dir "${sd}"`)
+  run(`node "${binCLI}" --dir "${cwd}" --spec-dir "${sd}" run scan --spec-root "${sd}" --runtime-root "${sd}/runtime" --workspace-id ws1 --scan-run-id sr1`)
+
+  const inSpecDir = join(sd, '.runtime', 'platform-scan.json')
+  const pointerFile = join(cwd, '.sillyspec-platform.json')
+  assert(existsSync(inSpecDir), `platform-scan.json 在 specDir/.runtime/`)
+  assert(existsSync(pointerFile), `恢复指针在 cwd/.sillyspec-platform.json（不在 .sillyspec 内）`)
+
+  const content = JSON.parse(readFileSync(inSpecDir, 'utf8'))
+  assert(content.specRoot === sd, `specRoot 指向 specDir`)
+  assert(content.workspaceId === 'ws1', `workspaceId 保存正确`)
+  assert(content.scanRunId === 'sr1', `scanRunId 保存正确`)
+  // 关键：cwd/.sillyspec/ 不应被创建
+  assert(!existsSync(join(cwd, '.sillyspec')), `cwd/.sillyspec/ 未被创建（源码零污染）`)
+  clean(cwd, sd)
+}
+
+// ── Test 2: --done 不带 --spec-root 时恢复 ──
+console.log('\n=== Test 2: --done 恢复平台参数 ===')
+{
+  const cwd = setup('t2'), sd = spec('t2')
+  run(`node "${binCLI}" init "${cwd}" --spec-dir "${sd}"`)
+  run(`node "${binCLI}" --dir "${cwd}" --spec-dir "${sd}" run scan --spec-root "${sd}" --runtime-root "${sd}/runtime" --workspace-id ws2 --scan-run-id sr2`)
+  // --done 不带任何平台参数
+  const output = run(`node "${binCLI}" --dir "${cwd}" run scan --done --change default --dir "${cwd}" --input "test" --output "test done" 2>&1`)
+  assert(output.includes('平台模式'), `恢复成功：包含平台模式指令`)
+  assert(output.includes(sd), `恢复成功：包含 specDir 路径`)
+  clean(cwd, sd)
+}
+
+// ── Test 3-6: stage-contract 路径（通过 runValidators） ──
+const { runValidators } = await import(pathToFileURL(join(root, 'src', 'stage-contract.js')).href)
+
+console.log('\n=== Test 3: specDir 有文档 → 校验通过 ===')
+{
+  const cwd = setup('t3'), sd = spec('t3')
+  const proj = basename(cwd)
+  const scanDir = join(sd, 'docs', proj)
+  writeSpecDocs(scanDir)
+  const result = runValidators('scan', cwd, 'default', { projectName: proj, specRoot: sd })
+  assert(result.ok, `specDir 有文档: ok=${result.ok}, errors=${JSON.stringify(result.errors)}`)
+  clean(cwd, sd)
+}
+
+console.log('\n=== Test 4: specDir 缺文档 → 校验失败，路径不含 .sillyspec ===')
+{
+  const cwd = setup('t4'), sd = spec('t4')
+  const proj = basename(cwd)
+  mkdirSync(join(sd, 'docs'), { recursive: true })
+  const result = runValidators('scan', cwd, 'default', { projectName: proj, specRoot: sd })
+  assert(!result.ok, `specDir 缺文档: ok=${result.ok}`)
+  assert(result.errors.length > 0, `有 errors`)
+  const errMsg = result.errors[0]
+  assert(!errMsg.includes('.sillyspec/docs'), `路径不含 .sillyspec: ${errMsg}`)
+  assert(errMsg.includes('/docs/'), `路径含 /docs/: ${errMsg}`)
+  clean(cwd, sd)
+}
+
+console.log('\n=== Test 5: 非平台模式有文档 → 校验通过 ===')
+{
+  const cwd = setup('t5')
+  const proj = basename(cwd)
+  writeLocalDocs(cwd)
+  const result = runValidators('scan', cwd, 'default', { projectName: proj })
+  assert(result.ok, `非平台有文档: ok=${result.ok}`)
+  clean(cwd)
+}
+
+console.log('\n=== Test 6: 非平台模式缺文档 → 路径含 .sillyspec ===')
+{
+  const cwd = setup('t6')
+  const proj = basename(cwd)
+  const result = runValidators('scan', cwd, 'default', { projectName: proj })
+  assert(!result.ok, `非平台缺文档: ok=${result.ok}`)
+  const errMsg = result.errors[0]
+  assert(errMsg.includes('.sillyspec/docs'), `路径含 .sillyspec/docs/: ${errMsg}`)
+  clean(cwd)
+}
+
+console.log(`\n${'='.repeat(50)}`)
+console.log(`✅ 通过: ${passed}  ❌ 失败: ${failed}`)
+console.log(`${'='.repeat(50)}`)
+process.exit(failed > 0 ? 1 : 0)