sillyspec 3.25.1 → 3.25.2

package/src/progress/change-registry.js

@@ -0,0 +1,217 @@
+// W6 Step9b: 变更注册表（changes 表生命周期）—— 注册/注销/重命名/隔离状态/平台同步戳/审批状态。
+// 从 src/progress.js 单体 ProgressManager 抽出。持有 pm 引用（构造注入），调 pm._ensureDB /
+// pm._changePath（persistence-core 留 facade 本体）。无共享常量依赖。
+import { existsSync, mkdirSync, renameSync } from 'fs';
+
+export class ChangeRegistry {
+  constructor(pm) {
+    this.pm = pm;
+  }
+
+  /**
+   * 列出所有活跃变更名
+   * SQL: SELECT name FROM changes WHERE status = 'active'
+   */
+  async listChanges(cwd) {
+    const db = await this.pm._ensureDB(cwd);
+    const sqlDb = db.getDb();
+    const rows = sqlDb.exec("SELECT name FROM changes WHERE status = 'active' ORDER BY name");
+    if (!rows || rows.length === 0) return [];
+    return rows[0].values.map(r => r[0]);
+  }
+
+  /**
+   * 注册变更到活跃列表
+   * SQL: INSERT OR IGNORE → 若已 archived 则 UPDATE status='active'
+   */
+  async registerChange(cwd, changeName) {
+    if (!changeName) {
+      console.warn('⚠️  registerChange: changeName 为空，跳过');
+      return;
+    }
+    const db = await this.pm._ensureDB(cwd);
+    db.transaction((sqlDb) => {
+      const now = new Date().toISOString();
+      // 尝试插入新行
+      sqlDb.run(
+        `INSERT OR IGNORE INTO changes (name, created_at, last_active)
+         VALUES (?, ?, ?)`,
+        [changeName, now, now]
+      );
+      // 注意：不复活已归档的变更——归档是不可逆操作
+      // 如果变更已存在且为 archived，保持 archived 状态不变
+    });
+  }
+
+  /**
+   * 更新变更的隔离状态
+   * @param {string} cwd - 项目根目录
+   * @param {string} changeName - 变更名
+   * @param {{ status: string, mode?: string, reason?: string }} isolation
+   */
+  async updateChangeIsolation(cwd, changeName, isolation) {
+    const db = await this.pm._ensureDB(cwd);
+    const sqlDb = db.getDb();
+    try {
+      sqlDb.run(
+        `UPDATE changes SET isolation_status = ?, isolation_mode = ?, isolation_reason = ?, last_active = ? WHERE name = ?`,
+        [isolation.status, isolation.mode || null, isolation.reason || null, new Date().toISOString(), changeName]
+      );
+      db._save();
+    } catch (err) {
+      console.warn('⚠️  更新 isolation 状态失败:', err.message);
+    }
+  }
+
+  /**
+   * 读取变更的隔离状态
+   * @param {string} cwd - 项目根目录
+   * @param {string} changeName - 变更名
+   * @returns {{ status: string|null, mode: string|null, reason: string|null }|null}
+   */
+  async readChangeIsolation(cwd, changeName) {
+    const db = await this.pm._ensureDB(cwd);
+    const sqlDb = db.getDb();
+    try {
+      const rows = sqlDb.exec(
+        `SELECT isolation_status, isolation_mode, isolation_reason FROM changes WHERE name = ?`,
+        [changeName]
+      );
+      if (!rows || rows.length === 0 || rows[0].values.length === 0) return null;
+      const [status, mode, reason] = rows[0].values[0];
+      return { status: status || null, mode: mode || null, reason: reason || null };
+    } catch {
+      return null;
+    }
+  }
+
+  async _updatePlatformLastSync(cwd, changeName) {
+    if (!changeName) return;
+    const db = await this.pm._ensureDB(cwd);
+    db.transaction((sqlDb) => {
+      sqlDb.run(
+        'UPDATE changes SET platform_last_sync = ?, platform_sync_enabled = 1 WHERE name = ?',
+        [new Date().toISOString(), changeName]
+      );
+    });
+  }
+
+  async _updateApprovalStatus(cwd, changeName, status, reason = null) {
+    if (!changeName || !status) return;
+    const db = await this.pm._ensureDB(cwd);
+    db.transaction((sqlDb) => {
+      const rows = sqlDb.exec('SELECT id FROM changes WHERE name = ?', [changeName]);
+      if (!rows || rows.length === 0 || rows[0].values.length === 0) return;
+      const changeId = rows[0].values[0][0];
+      const now = new Date().toISOString();
+      sqlDb.run(
+        `INSERT INTO approvals (change_id, status, requested_at, approved_at, rejection_reason)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(change_id) DO UPDATE SET
+           status = excluded.status,
+           approved_at = excluded.approved_at,
+           rejection_reason = excluded.rejection_reason`,
+        [
+          changeId,
+          status,
+          now,
+          status === 'approved' ? now : null,
+          status === 'rejected' ? reason : null,
+        ]
+      );
+    });
+  }
+
+  /**
+   * 重命名变更：同步更新 DB + 目录
+   * @param {string} cwd - 项目根目录
+   * @param {string} oldName - 旧变更名
+   * @param {string} newName - 新变更名
+   */
+  async renameChange(cwd, oldName, newName) {
+    if (!oldName || !newName) {
+      console.warn('⚠️  renameChange: 旧名或新名为空，跳过');
+      return;
+    }
+    if (oldName === newName) {
+      console.warn('⚠️  renameChange: 新旧名称相同，跳过');
+      return;
+    }
+    const db = await this.pm._ensureDB(cwd);
+    // 检查旧名是否存在
+    const existing = db.transaction((sqlDb) => {
+      const row = sqlDb.exec(`SELECT name, status FROM changes WHERE name = ?`, [oldName]);
+      if (!row || !row[0] || row[0].values.length === 0) return null;
+      return { name: row[0].values[0][0], status: row[0].values[0][1] };
+    });
+    if (!existing) {
+      console.error(`❌ 变更 ${oldName} 不存在`);
+      return;
+    }
+    // 检查新名是否已存在
+    const conflict = db.transaction((sqlDb) => {
+      const row = sqlDb.exec(`SELECT name FROM changes WHERE name = ?`, [newName]);
+      return row && row[0] && row[0].values.length > 0;
+    });
+    if (conflict) {
+      console.error(`❌ 变更 ${newName} 已存在`);
+      return;
+    }
+    // 先更新 DB，再重命名目录；FS 失败则回滚 DB，避免"目录已改名但 DB 旧名"的孤儿
+    // （旧实现 FS-first 无补偿：renameSync 成功后 DB transaction 抛 EPERM/EBUSY 会让
+    //  目录已是 newName、DB 仍是 oldName，read(两名) 都失联且无自动恢复）。
+    const oldDir = this.pm._changePath(cwd, oldName);
+    const newDir = this.pm._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)) {
+      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]);
+          });
+          console.error(`❌ 重命名失败：移动目录出错（${e.message}），已回滚数据库`);
+        } catch (rollbackErr) {
+          // 回滚本身也失败：DB 是 newName、目录是 oldName，两端分裂且无自动恢复。
+          // 不能再撒谎"已回滚"——必须显式报错让用户跑 doctor 修复。
+          console.error(`❌ 重命名失败且数据库回滚也失败（状态分裂，需手动修复）：原错=${e.message} 回滚错=${rollbackErr.message}。请跑 sillyspec doctor --json`);
+        }
+      }
+    } else {
+      mkdirSync(newDir, { recursive: true });
+    }
+    if (renamed) console.log(`✅ 变更已重命名：${oldName} → ${newName}`);
+  }
+
+  /**
+   * 从活跃列表移除变更（归档时调用，不物理删除）
+   * SQL: UPDATE changes SET status = 'archived'
+   */
+  async unregisterChange(cwd, changeName) {
+    if (!changeName) {
+      console.warn('⚠️  unregisterChange: changeName 为空，跳过');
+      return;
+    }
+    const db = await this.pm._ensureDB(cwd);
+    db.transaction((sqlDb) => {
+      const now = new Date().toISOString();
+      sqlDb.run(
+        `UPDATE changes SET status = 'archived', last_active = ? WHERE name = ?`,
+        [now, changeName]
+      );
+    });
+  }
+}
+

package/src/progress/consistency-doctor.js

@@ -0,0 +1,259 @@
+// W6 Step9a: Revision v1 状态一致性检查 + 修复 + --force 审计日志。
+// 从 src/progress.js 单体 ProgressManager 抽出。持有 pm 引用（构造注入），调 pm.read / pm._write /
+// pm._ensureRuntimeDir / pm._runtimePath（persistence-core 留 facade 本体）。
+import { appendFileSync } from 'fs';
+import { STAGE_ORDER } from './shared.js';
+
+export class ConsistencyDoctor {
+  constructor(pm) {
+    this.pm = pm;
+  }
+
+  /**
+   * 强制状态变更的审计记录（--force 逃生口专用）。
+   * 追加到 .runtime/audit.log，供人工/doctor 追溯"谁在什么时候绕过了校验"。
+   */
+  _appendAuditLog(cwd, entry) {
+    try {
+      this.pm._ensureRuntimeDir(cwd);
+      const auditPath = this.pm._runtimePath(cwd, 'audit.log');
+      const line = JSON.stringify({ at: new Date().toISOString(), ...entry });
+      appendFileSync(auditPath, line + '\n');
+    } catch (e) {
+      console.warn(`⚠️  审计日志写入失败: ${e.message}`);
+    }
+  }
+
+  /**
+   * Revision v1 状态一致性检查
+   * 只报告，不自动修复。
+   * @param {string} cwd
+   * @param {string|null} changeName
+   * @returns {{ ok: boolean, issues: string[], warnings: string[] }}
+   */
+  async checkConsistency(cwd, changeName = null) {
+    const data = await this.pm.read(cwd, changeName);
+    if (!data) {
+      return { ok: false, issues: ['无法读取进度数据'], warnings: [] };
+    }
+
+    const issues = [];
+    const warnings = [];
+
+    for (const stageName of STAGE_ORDER) {
+      const sd = data.stages[stageName];
+      if (!sd) continue;
+
+      // a. completed stage 不能有 pending/stale steps
+      if (sd.status === 'completed' && sd.steps) {
+        const badSteps = sd.steps.filter(s => ['pending', 'stale', 'in-progress'].includes(s.status));
+        for (const step of badSteps) {
+          issues.push(`${stageName}/${step.name}: step 状态为 ${step.status}，但 stage 状态为 completed`);
+        }
+      }
+
+      // b. revising stage 应有 revision > 0 或 reopenedFromStep
+      if (sd.status === 'revising') {
+        if (!sd.revision || sd.revision < 1) {
+          issues.push(`${stageName}: 状态为 revising 但 revision 缺失或为 0`);
+        }
+        if (!sd.reopenedFromStep) {
+          warnings.push(`${stageName}: 状态为 revising 但未记录 reopenedFromStep`);
+        }
+      }
+
+      // c. stale stage 应有 staleReason
+      if (sd.status === 'stale') {
+        if (!sd.staleReason) {
+          warnings.push(`${stageName}: 状态为 stale 但缺少 staleReason`);
+        }
+      }
+
+      // d. 下游 completed 不能出现在上游 stale/revising 之后
+      const stageIdx = STAGE_ORDER.indexOf(stageName);
+      for (let i = 0; i < stageIdx; i++) {
+        const upstream = STAGE_ORDER[i];
+        const upData = data.stages[upstream];
+        if (upData && (upData.status === 'stale' || upData.status === 'revising')) {
+          if (sd.status === 'completed') {
+            issues.push(`${stageName}: 状态为 completed，但上游 ${upstream} 状态为 ${upData.status}（下游不应在上游修订/失效时保持 completed）`);
+          }
+        }
+      }
+
+      // e. step stale 时 stage 不应是 completed
+      if (sd.status === 'completed' && sd.steps) {
+        const staleSteps = sd.steps.filter(s => s.status === 'stale');
+        for (const step of staleSteps) {
+          issues.push(`${stageName}/${step.name}: step 状态为 stale，但 stage 状态为 completed`);
+        }
+      }
+    }
+
+    // 输出报告
+    console.log('');
+    console.log('  ═══════════════════════════════════════');
+    console.log('  状态一致性检查');
+    console.log('  ═══════════════════════════════════════');
+
+    if (issues.length === 0 && warnings.length === 0) {
+      console.log('  ✅ 未发现一致性问题');
+    } else {
+      if (issues.length > 0) {
+        console.log(`\n  ❌ 问题 (${issues.length}):`);
+        for (const issue of issues) console.log(`     - ${issue}`);
+      }
+      if (warnings.length > 0) {
+        console.log(`\n  ⚠️ 警告 (${warnings.length}):`);
+        for (const w of warnings) console.log(`     - ${w}`);
+      }
+    }
+    console.log('');
+
+    return { ok: issues.length === 0, issues, warnings };
+  }
+
+  /**
+   * Revision v1.2 状态修复
+   * 默认 dry-run，--apply 才真正修改 DB。
+   * 只修安全项，不碰产物文件、不 reset/reopen stage。
+   *
+   * @param {string} cwd
+   * @param {object} opts
+   * @param {boolean} [opts.apply=false]
+   * @param {string|null} [opts.changeName]
+   * @returns {{ fixable: object[], manual: string[], applied: object[] }}
+   */
+  async repairConsistency(cwd, opts = {}) {
+    const { apply = false, changeName = null } = opts;
+
+    const data = await this.pm.read(cwd, changeName);
+    if (!data) {
+      console.log('❌ 无法读取进度数据');
+      return { fixable: [], manual: ['无法读取进度数据'], applied: [] };
+    }
+
+    const fixable = []; // { stage, action, description, apply: (data) => void }
+    const manual = [];  // string
+
+    const now = new Date().toLocaleString('zh-CN', { hour12: false });
+
+    for (const stageName of STAGE_ORDER) {
+      const sd = data.stages[stageName];
+      if (!sd) continue;
+
+      // Fix a: stale stage 缺 staleReason → 补默认原因
+      if (sd.status === 'stale' && !sd.staleReason) {
+        const reason = stageName === 'archive'
+          ? 'upstream stage revised; existing archive artifacts are preserved but no longer trusted'
+          : 'unknown upstream revision';
+        fixable.push({
+          stage: stageName,
+          action: 'set_stale_reason',
+          description: `${stageName}: stale 缺 staleReason → 补 "${reason}"`,
+          apply: (d) => { d.stages[stageName].staleReason = reason; },
+        });
+      }
+
+      // Fix b: 上游 stale/revising，下游仍 completed → cascade stale
+      const stageIdx = STAGE_ORDER.indexOf(stageName);
+      for (let i = 0; i < stageIdx; i++) {
+        const upstream = STAGE_ORDER[i];
+        const upData = data.stages[upstream];
+        if (upData && (upData.status === 'stale' || upData.status === 'revising')) {
+          if (sd.status === 'completed') {
+            const upStatus = upData.status;
+            const reason = `upstream ${upstream} is ${upStatus}`;
+            fixable.push({
+              stage: stageName,
+              action: 'cascade_stale',
+              description: `${stageName}: completed → stale（上游 ${upstream} 为 ${upStatus}）`,
+              apply: (d) => {
+                d.stages[stageName].status = 'stale';
+                d.stages[stageName].staleReason = reason;
+                d.stages[stageName].completedAt = null;
+              },
+            });
+          }
+        }
+      }
+
+      // Fix c: archive stale 缺 staleReason（专用文案）
+      if (stageName === 'archive' && sd.status === 'stale' && !sd.staleReason) {
+        // 已在 Fix a 中处理，这里不重复
+      }
+
+      // Fix d: revising stage 缺 reopenedAt → 补当前时间
+      if (sd.status === 'revising' && !sd.reopenedAt) {
+        fixable.push({
+          stage: stageName,
+          action: 'set_reopened_at',
+          description: `${stageName}: revising 缺 reopenedAt → 补当前时间`,
+          apply: (d) => { d.stages[stageName].reopenedAt = now; },
+        });
+      }
+
+      // Manual a: completed stage 里有 pending/stale/in-progress steps
+      if (sd.status === 'completed' && sd.steps) {
+        const badSteps = sd.steps.filter(s => ['pending', 'stale', 'in-progress'].includes(s.status));
+        for (const step of badSteps) {
+          manual.push(`${stageName}/${step.name}: step 状态为 ${step.status}，但 stage 状态为 completed（需手动确认）`);
+        }
+      }
+
+      // Manual b: revising stage 缺 reopenedFromStep
+      if (sd.status === 'revising' && !sd.reopenedFromStep) {
+        manual.push(`${stageName}: revising 缺 reopenedFromStep（需手动确认修订起始步骤）`);
+      }
+
+      // Manual c: steps 为空但 stage completed
+      if (sd.status === 'completed' && (!sd.steps || sd.steps.length === 0)) {
+        manual.push(`${stageName}: completed 但 steps 为空（需手动确认）`);
+      }
+    }
+
+    // 输出报告
+    console.log('');
+    console.log('  ═══════════════════════════════════════');
+    console.log(`  状态修复 ${apply ? '（--apply 模式）' : '（dry-run 模式）'}`);
+    console.log('  ═══════════════════════════════════════');
+
+    if (fixable.length === 0 && manual.length === 0) {
+      console.log('  ✅ 未发现问题，无需修复');
+      console.log('');
+      return { fixable: [], manual: [], applied: [] };
+    }
+
+    const applied = [];
+
+    if (fixable.length > 0) {
+      console.log(`\n  🔧 可自动修复 (${fixable.length}):`);
+      for (const item of fixable) {
+        console.log(`     - ${item.description}`);
+        if (apply) {
+          item.apply(data);
+          applied.push({ stage: item.stage, action: item.action });
+        }
+      }
+      if (!apply) {
+        console.log('\n  💡 使用 --apply 执行修复');
+      }
+    }
+
+    if (manual.length > 0) {
+      console.log(`\n  👆 需手动处理 (${manual.length}):`);
+      for (const m of manual) console.log(`     - ${m}`);
+    }
+
+    if (apply && applied.length > 0) {
+      data.lastActive = now;
+      await this.pm._write(cwd, data, changeName);
+      console.log(`\n  ✅ 已修复 ${applied.length} 项`);
+    }
+
+    console.log('');
+
+    return { fixable, manual, applied };
+  }
+}
+

package/src/progress/shared.js

@@ -0,0 +1,33 @@
+// W6 Step9 共享常量：progress.js facade 与 src/progress/* 子模块共用，避免 facade↔子模块循环引用。
+// 9a: STAGE_ORDER/MAIN_FLOW_ORDER；9c: VALID_STAGES/STAGE_LABELS；9d: SPEC_DIR_NAME/CURRENT_VERSION/emptyStage。
+
+export const SPEC_DIR_NAME = '.sillyspec';
+
+// 合法阶段名（含辅助阶段 scan/quick/explore）
+export const VALID_STAGES = ['scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore'];
+
+// 阶段展示文案
+export const STAGE_LABELS = {
+  brainstorm: '🧠 需求探索',
+  plan: '📐 实现计划',
+  execute: '⚡ 波次执行',
+  verify: '🔍 验证确认',
+  scan: '🔍 代码扫描',
+  quick: '⚡ 快速任务',
+  explore: '🧭 自由探索',
+  archive: '📦 归档变更',
+};
+
+// 完整主流程顺序（含 scan），用于下游 cascade / 一致性检查
+export const STAGE_ORDER = ['scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive'];
+// 主流程阶段（不含 scan/quick/explore 等辅助阶段）—— 当前与 STAGE_ORDER 同值
+export const MAIN_FLOW_ORDER = STAGE_ORDER;
+
+// progress 数据版本（v3 = SQLite）
+export const CURRENT_VERSION = 3;
+
+// 空阶段骨架
+export function emptyStage() {
+  return { status: 'pending', steps: [], startedAt: null, completedAt: null };
+}
+