sillyspec 3.26.6 → 3.26.8

package/src/progress.js

@@ -20,26 +20,21 @@ import { ChangeRegistry } from './progress/change-registry.js';
 import { StepStore } from './progress/step-store.js';
 import { StageMachine } from './progress/stage-machine.js';
 import { STAGE_ORDER, MAIN_FLOW_ORDER, VALID_STAGES, STAGE_LABELS, SPEC_DIR_NAME, CURRENT_VERSION, emptyStage } from './progress/shared.js';
+// resolveSpecDir 单一真相源在 src/run/shared.js（含 home 拒绝守卫，坑 cwd-correction-home-collision
+// 根治：home 下 .sillyspec 恒不命中，防 smoke/临时目录污染自我延续）。此处 re-export 保持
+// 既有 import 路径兼容；run/shared.js 对 progress.js 只有动态 import，无静态循环。
+import { resolveSpecDir } from './run/shared.js';
+import { checkPlatformManaged, PLATFORM_MANAGED_FILENAME } from './run/shared.js';
+export { resolveSpecDir };
 
 // 默认规范目录名（相对于 cwd）
 // SPEC_DIR_NAME → ./progress/shared.js（W6 Step9d）
 const RUNTIME_SUBDIR = '.runtime';
 
 /**
- * 向上查找含 .sillyspec 目录的祖先目录，类似 git 找 .git 的逻辑。
- * 找到则返回 <祖先>/.sillyspec，否则 fallback 到 <cwd>/.sillyspec。
+ * 向上查找含 .sillyspec 目录的祖先目录——实现已收敛至 src/run/shared.js（单一真相源，
+ * 含 home 拒绝守卫），此处 re-export。见顶部 import 说明。
  */
-export function resolveSpecDir(startDir) {
-  let dir = resolve(startDir);
-  while (true) {
-    const candidate = join(dir, SPEC_DIR_NAME);
-    if (existsSync(candidate)) return candidate;
-    const parent = dirname(dir);
-    if (parent === dir) break; // 到达根目录
-    dir = parent;
-  }
-  return join(resolve(startDir), SPEC_DIR_NAME);
-}
 
 /**
  * 平台指针不可达错误。pointer 存在但失效时抛出，阻止静默回退到本地孤儿 db。
@@ -59,6 +54,26 @@ export class PointerUnreachableError extends Error {
   }
 }
 
+/**
+ * 平台接管声明生效错误（指针缺失但声明存在）。fail-closed 入口一：
+ * 防指针被 cleanup/STALE 清理或项目挪动后裸调静默建本地进度库（状态分裂根因）。
+ *
+ * ⚠️ 不覆写 this.name（保持父类的 'PointerUnreachableError'）——CLI 顶层 catch 按
+ * err?.name === 'PointerUnreachableError' 严格字符串匹配（index.js），子类改名会
+ * 落通用错误分支打 stack noise。靠 message 首行"平台接管声明生效"区分场景。
+ */
+export class PlatformManagedError extends PointerUnreachableError {
+  constructor({ declarationPath, specRoot }) {
+    super({
+      pointerPath: declarationPath,
+      specRoot,
+      reason: `平台接管声明生效——本项目已由平台托管，但恢复指针缺失（可能被 platform pointer --cleanup 清理或项目目录被移动），拒绝静默回退本地模式`,
+      hint: `① 重跑平台 scan/init（带 --spec-root）重建指针；② 确认不再使用平台：sillyspec platform disconnect（删除接管声明）；③ 显式 --spec-dir <路径> 临时指定目录`,
+    });
+    this.declarationPath = declarationPath;
+  }
+}
+
 /**
  * 平台感知的 specDir 解析（fail-closed，所有 CLI 子命令统一入口）。
  *
@@ -75,6 +90,15 @@ export function resolvePlatformSpecDir(cwd, explicitSpecDir = null) {
   if (explicitSpecDir) return resolve(explicitSpecDir);
   const pointerPath = join(resolve(cwd), '.sillyspec-platform.json');
   if (!existsSync(pointerPath)) {
+    // 指针缺失：查平台接管声明（fail-closed 入口一）。声明存在 = 项目进过平台模式，
+    // 指针丢失不该静默当纯本地项目处理（会建本地进度库 → 状态分裂）。
+    const decl = checkPlatformManaged(cwd);
+    if (decl) {
+      throw new PlatformManagedError({
+        declarationPath: join(resolve(cwd), PLATFORM_MANAGED_FILENAME),
+        specRoot: decl.specRoot,
+      });
+    }
     return resolveSpecDir(cwd);
   }
   // pointer 存在 = 进过平台模式，严格校验，不静默回退

package/src/quicklog.js

@@ -81,6 +81,14 @@ export function sanitizeDesc(description) {
   return s.length > 120 ? s.slice(0, 120) + '…' : s
 }
 
+// git user.name → 文件名安全形式：白名单保留字母数字._- 与中文等 Unicode 字，
+// 剥路径元字符（/ \ ..）与控制字符。防 QUICKLOG-<user>.md / 锁文件 / 轮转归档穿越写。
+export function sanitizeQuicklogUser(user) {
+  const s = String(user || '').replace(/[\\/\r\n\0]/g, '').replace(/\.{2,}/g, '.').trim()
+  if (!s) return ''
+  return s.length > 64 ? s.slice(0, 64) : s
+}
+
 // 从关联变更的 proposal/design 提取首个 # 标题（去「提案书（Proposal）— / 设计文档（Design）—」固定前缀）。
 // 让 quick --linked-changes 启动时（用户常不带 --input）也能拿到语义标题，而非 (quick 任务) 占位。
 // 读不到任何标题返回 ''（调用方再回退占位符，保持向后兼容）。
@@ -134,6 +142,9 @@ export function getQuickFileNotes() { return _pendingFileNotes }
  */
 export function parseFileNotes(raw) {
   if (!raw) return []
+  // note 单行化 + 限长：bullet 是「数组元素内嵌 \n」落盘（flipEntryInContent），note 带换行会伪造
+  // QUICKLOG 条目结构（\n## ql-… 可伪造后续条目头）。与 sanitizeDesc 同风格。
+  const sanitizeNote = (n) => n.replace(/[\r\n]+/g, ' ').trim().slice(0, 200)
   return String(raw)
     .split('||')
     .map((seg) => {
@@ -141,7 +152,7 @@ export function parseFileNotes(raw) {
       if (!s) return null
       const idx = s.indexOf('::')
       const path = (idx === -1 ? s : s.slice(0, idx)).replace(/\\/g, '/').trim()
-      const note = idx === -1 ? '' : s.slice(idx + 2).trim()
+      const note = idx === -1 ? '' : sanitizeNote(s.slice(idx + 2))
       return path ? { path, note } : null
     })
     .filter(Boolean)
@@ -234,7 +245,7 @@ async function rotateIfNeeded(userFile, gitUser) {
   const dateStr = lastDate
     ? `${lastDate.slice(0, 4)}-${lastDate.slice(4, 6)}-${lastDate.slice(6, 8)}`
     : nowDatetime().slice(0, 10)
-  const archiveFile = join(dirname(userFile), `QUICKLOG-${gitUser}-${dateStr}.md`)
+  const archiveFile = join(dirname(userFile), `QUICKLOG-${sanitizeQuicklogUser(gitUser) || 'unknown'}-${dateStr}.md`)
   // 同日已轮转过：两步各自原子化（append+clear 无法单原子，reader 容忍中间态——见 writeAtomic 注释）
   if (existsSync(archiveFile)) {
     const existing = readFileSync(archiveFile, 'utf8')
@@ -394,7 +405,9 @@ function flipEntryInContent(content, qlId, result, changedFiles = [], fileNotes
 export async function allocateQuicklogEntry(specBase, gitUser, { description, linkedChanges = [], allowedFiles = [] } = {}) {
   const quicklogDir = join(specBase, 'quicklog')
   mkdirSync(quicklogDir, { recursive: true })
-  const user = gitUser || 'unknown'
+  // git user.name 无字符限制，可含 / \ .. 等路径元字符（git config 或 .git/config 可控）——
+  // 白名单消毒防穿越写（QUICKLOG-<user>.md / 锁文件 / 轮转归档三处拼接），与 assertSafeChangeName 同风格
+  const user = sanitizeQuicklogUser(gitUser) || 'unknown'
   const userFile = join(quicklogDir, `QUICKLOG-${user}.md`)
   const lockPath = join(quicklogDir, `.QUICKLOG-${user}.md.lock`)
   const desc = sanitizeDesc(description)
@@ -437,7 +450,9 @@ export async function allocateQuicklogEntry(specBase, gitUser, { description, li
  */
 export async function completeQuicklogEntry(specBase, gitUser, qlId, { resultText = '', linkedChanges = [], changedFiles = [] } = {}) {
   const quicklogDir = join(specBase, 'quicklog')
-  const lockPath = join(quicklogDir, `.QUICKLOG-${(gitUser || 'unknown')}.md.lock`)
+  // 与 allocateQuicklogEntry 同源消毒：锁文件路径含 user（防穿越写，两入口必须一致否则锁不上同一文件）
+  const user = sanitizeQuicklogUser(gitUser) || 'unknown'
+  const lockPath = join(quicklogDir, `.QUICKLOG-${user}.md.lock`)
   const result = sanitizeResult(resultText)
   const linked = Array.isArray(linkedChanges) ? linkedChanges : []
   // 实际改动文件（调用方 complete-handlers 已用 isQuickMetadata 过滤 quick 自身元数据）。空 → 不动文件行。

package/src/run/command.js

@@ -23,7 +23,7 @@ import { join, resolve, dirname } from 'node:path'
 import { existsSync, readdirSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs'
 import { randomBytes, randomUUID } from 'node:crypto'
 import { writeAtomicSync } from '../fs-atomic.js'
-import { resolveSpecDir, countAncestorSpecDirs, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift, resolveRuntimeRoot } from './shared.js'
+import { resolveSpecDir, countAncestorSpecDirs, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift, resolveRuntimeRoot, writePlatformPointer, checkPlatformManaged, PLATFORM_MANAGED_FILENAME } from './shared.js'
 import { resolveQuickLinkedChanges } from './quick-audit.js'
 import { outputStep } from './prompt.js'
 import { completeStep, skipStep, waitStep, continueStep } from './complete.js'
@@ -125,6 +125,31 @@ export async function ensureStageSteps(progress, stageName, cwd, specDir = null)
   return false
 }
 
+/**
+ * run <stage> --help/-h 的用法帮助（runCommand 内 --help 短路调用）。
+ * 只打印不落盘：帮助查询不该有副作用（建会话/写 QUICKLOG）。
+ */
+function printStageUsage(stageName) {
+  const stage = stageRegistry[stageName]
+  console.log(`
+sillyspec run ${stageName}${stage && stage.title ? ` — ${stage.title}` : ''}${stage && stage.description ? `\n  ${stage.description}` : ''}
+
+用法:
+  sillyspec run ${stageName}                    开始/继续该阶段（输出下一步 prompt）
+  sillyspec run ${stageName} --status           查看阶段进度
+  sillyspec run ${stageName} --done --output "摘要" [--input "用户原话"]   完成当前步骤
+  sillyspec run ${stageName} --change <名>      指定变更（多活跃变更必填）
+
+  通用参数: --done --output --input --status --skip --reset --reopen --from-step
+            --wait --continue --answer --change --spec-dir --non-interactive
+            --interactive --skip-approval --json(不支持)
+  quick 专属: --linked-changes none|a,b --files a.js,b.js --allow-new
+             --allow-delete --force-baseline --confirm --file-notes
+  scan  专属: --quick --standard --deep --force-rescan
+  archive专属: --confirm
+`)
+}
+
 /**
  * sillyspec run <stage> 主命令
  */
@@ -289,31 +314,27 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
       }
     }
   }
+  // ── 平台接管声明 fail-closed（入口二，D-B@v2）──
+  // runCommand 有独立指针恢复链（不经 resolvePlatformSpecDir），指针缺失时若不在此
+  // 封堵，run/quick/scan 等全部 stage 命令会静默落本地库（与入口一行为分裂）。
+  // 触发条件：命令行没传平台参数 + 指针与 platform-scan.json 皆未命中 + 接管声明存在。
+  // 显式 --spec-dir/--spec-root 传参时 platformOpts.specRoot 已赋值，天然不进此分支（逃生口）。
+  if (!platformOpts.specRoot && !platformOpts.runtimeRoot && !platformFileExists) {
+    const decl = checkPlatformManaged(cwd)
+    if (decl) {
+      console.error(`❌ 平台接管声明生效：本项目已由平台托管（原 specRoot: ${decl.specRoot || '(未记录)'}），但恢复指针缺失，拒绝静默回退本地模式。`)
+      console.error(`   声明文件: ${join(cwd, PLATFORM_MANAGED_FILENAME)}`)
+      console.error('   恢复：① 重跑平台 scan/init（带 --spec-root）重建指针；② 确认不再使用平台：sillyspec platform disconnect（删除接管声明）；③ 显式 --spec-dir <路径> 临时指定目录。')
+      // exit(1) 而非邻近环境错的 exit(2)：这是"状态保护阻断"（对齐 PointerUnreachableError
+      // 顶层 catch 语义），非"用法/环境错"——见 design.md §5.3 v2 复审观察 (a)
+      process.exit(1)
+    }
+  }
   // 持久化 platformOpts
-  // 在 specRoot/.runtime/ 写主文件，同时在 cwd/.sillyspec/.runtime/ 写恢复指针
+  // 在 specRoot/.runtime/ 写主文件，同时在 cwd 下写恢复指针
+  // （writePlatformPointer 收敛双写逻辑，cmdInit 平台模式共用，防两处字段漂移）
   if (platformOpts.specRoot || platformOpts.runtimeRoot) {
-    try {
-      const { mkdirSync, writeFileSync } = await import('fs')
-      mkdirSync(join(specRoot, '.runtime'), { recursive: true })
-      writeFileSync(platformOptsFile, JSON.stringify({
-        specRoot: platformOpts.specRoot,
-        runtimeRoot: platformOpts.runtimeRoot,
-        workspaceId: platformOpts.workspaceId,
-        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 {
-      // 静默失败，不影响主流程
-    }
+    writePlatformPointer(cwd, platformOpts)
   }
 
   // 统一规范基路径：平台模式用 specRoot，本地模式用 cwd/.sillyspec
@@ -513,6 +534,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     '--json', '--dir', '--help',
     '--reopen', '--from-step', '--mode',
     '--deep', '--quick', '--standard', // scan profile 三档显式选择（scan-profile.js 从 argv 读；互斥见下方 PROFILE_FLAGS 检测）
+    '-h',
   ])
   for (let i = 0; i < flags.length; i++) {
     const f = flags[i]
@@ -531,6 +553,14 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     }
   }
 
+  // ── --help/-h 短路：flag 校验通过后、任何副作用（cwd 纠正/会话创建/QUICKLOG 落盘）之前 ──
+  // --help 此前在 knownFlags 白名单里被静默吞掉，run quick --help 会误开 quick 会话+写骨架
+  // 条目（查询意图不该有副作用）；-h 更是被当未知参数 exit 2。帮助查询 = 用法展示 = 退出 0。
+  if (flags.includes('--help') || flags.includes('-h')) {
+    printStageUsage(stageName)
+    process.exit(0)
+  }
+
   const isAuxiliary = auxiliaryStages.includes(stageName)
   // scan 元数据追踪（存储在 stageData.scanMeta 中，completeStep 通过 progress 访问）