@zhuan-ai/zhuanspec 2.4.8 → 2.6.0

package/dist/commands/progress.d.ts

@@ -7,6 +7,12 @@
  * - Estimated remaining time
  */
 export declare class ProgressCommand {
+    /**
+     * Recover damaged progress.json using three-tier fallback strategy
+     * @param filePath - Path to progress.json file
+     * @returns Recovered ProgressData or null if unrecoverable
+     */
+    private recoverProgressJson;
     /**
      * Show progress for a specific change
      * Usage: zhuanspec progress show <change-id>

package/dist/commands/progress.js

@@ -12,6 +12,69 @@ import { FileSystemUtils } from '../utils/file-system.js';
 import { PHASE_ORDER } from '../utils/phase-utils.js';
 import { initializeProgress } from '../core/hooks/record-progress.js';
 export class ProgressCommand {
+    /**
+     * Recover damaged progress.json using three-tier fallback strategy
+     * @param filePath - Path to progress.json file
+     * @returns Recovered ProgressData or null if unrecoverable
+     */
+    async recoverProgressJson(filePath) {
+        const content = await FileSystemUtils.readFile(filePath);
+        // Layer 1: Standard JSON parse
+        try {
+            return JSON.parse(content);
+        }
+        catch {
+            // Continue to Layer 2
+        }
+        // Layer 2: Extract first top-level JSON object (handle trailing corruption)
+        try {
+            // Find the first complete JSON object
+            const objectStart = content.indexOf('{');
+            if (objectStart === -1)
+                return null;
+            // Track brace depth to find object boundary
+            let depth = 0;
+            let objectEnd = -1;
+            for (let i = objectStart; i < content.length; i++) {
+                if (content[i] === '{')
+                    depth++;
+                else if (content[i] === '}') {
+                    depth--;
+                    if (depth === 0) {
+                        objectEnd = i + 1;
+                        break;
+                    }
+                }
+            }
+            if (objectEnd > objectStart) {
+                const objectContent = content.slice(objectStart, objectEnd);
+                return JSON.parse(objectContent);
+            }
+        }
+        catch {
+            // Continue to Layer 3
+        }
+        // Layer 3: Minimal field extraction using regex
+        const phaseMatch = content.match(/"phase"\s*:\s*"([^"]+)"/);
+        const currentTaskMatch = content.match(/"currentTask"\s*:\s*"([^"]+)"/);
+        const totalTasksMatch = content.match(/"totalTasks"\s*:\s*(\d+)/);
+        const changeIdMatch = content.match(/"changeId"\s*:\s*"([^"]+)"/);
+        const sessionIdMatch = content.match(/"sessionId"\s*:\s*"([^"]+)"/);
+        if (phaseMatch || changeIdMatch) {
+            return {
+                changeId: changeIdMatch?.[1] || '',
+                sessionId: sessionIdMatch?.[1] || '',
+                startedAt: '',
+                lastUpdatedAt: '',
+                phase: phaseMatch?.[1] || 'unknown',
+                currentNode: phaseMatch?.[1] || 'unknown',
+                currentTask: currentTaskMatch?.[1] || '',
+                completedTasks: [],
+                totalTasks: totalTasksMatch ? parseInt(totalTasksMatch[1], 10) : 0,
+            };
+        }
+        return null;
+    }
     /**
      * Show progress for a specific change
      * Usage: zhuanspec progress show <change-id>
@@ -24,16 +87,11 @@ export class ProgressCommand {
         if (!await FileSystemUtils.directoryExists(changeDir)) {
             throw new Error(`Change '${changeId}' not found`);
         }
-        // Read progress.json
+        // Read progress.json with recovery support
         const progressPath = path.join(metricsDir, 'progress.json');
         let progress = null;
         if (await FileSystemUtils.fileExists(progressPath)) {
-            try {
-                progress = JSON.parse(await FileSystemUtils.readFile(progressPath));
-            }
-            catch {
-                // Ignore parse errors
-            }
+            progress = await this.recoverProgressJson(progressPath);
         }
         // Read tasks.md
         const tasksPath = path.join(changeDir, 'tasks.md');
@@ -67,16 +125,11 @@ export class ProgressCommand {
         }
         const changeDir = path.join(zhuanspecDir, 'changes', changeId);
         const metricsDir = path.join(changeDir, 'metrics');
-        // Read progress.json
+        // Read progress.json with recovery support
         const progressPath = path.join(metricsDir, 'progress.json');
         let progress = null;
         if (await FileSystemUtils.fileExists(progressPath)) {
-            try {
-                progress = JSON.parse(await FileSystemUtils.readFile(progressPath));
-            }
-            catch {
-                // Ignore parse errors
-            }
+            progress = await this.recoverProgressJson(progressPath);
         }
         // Read tasks.md
         const tasksPath = path.join(changeDir, 'tasks.md');
@@ -126,18 +179,36 @@ export class ProgressCommand {
                 currentWave = parseInt(waveMatch[1], 10);
                 continue;
             }
-            // Match task lines: - [ ] X.Y description or - [x] X.Y description
-            const taskMatch = line.match(/^-\s*\[([x ])\]\s*(\d+\.\d+)\s*(.+)/);
-            if (taskMatch) {
-                const statusChar = taskMatch[1];
-                const taskId = taskMatch[2];
-                const description = taskMatch[3].trim();
+            // Match new format task lines: - [ ] X.Y description or - [x] X.Y description
+            const newFormatMatch = line.match(/^-\s*\[([x ])\]\s*(\d+\.\d+)\s*(.+)/);
+            if (newFormatMatch) {
+                const statusChar = newFormatMatch[1];
+                const taskId = newFormatMatch[2];
+                const description = newFormatMatch[3].trim();
                 tasks.push({
                     taskId,
                     status: statusChar === 'x' ? 'completed' : 'pending',
                     wave: currentWave,
                     description: description.split('@')[0].trim(), // Remove @skill/@depends tags
                 });
+                continue;
+            }
+            // Match legacy format task headers: #### T1: description or #### T2: description
+            const legacyMatch = line.match(/^####\s*(T\d+)\s*:\s*(.+)$/);
+            if (legacyMatch) {
+                const taskId = legacyMatch[1];
+                const rawDescription = legacyMatch[2].trim();
+                // Check if description ends with ✅ (completed marker)
+                const isCompleted = rawDescription.endsWith('✅');
+                const description = isCompleted
+                    ? rawDescription.slice(0, -1).trim()
+                    : rawDescription;
+                tasks.push({
+                    taskId,
+                    status: isCompleted ? 'completed' : 'pending',
+                    wave: currentWave,
+                    description: description.split('@')[0].trim(), // Remove @skill/@depends tags
+                });
             }
         }
         return tasks;
@@ -211,11 +282,9 @@ export class ProgressCommand {
             ? Math.round((durationMin / completedCount) * (totalTasks - completedCount))
             : 0;
         console.log('');
-        console.log(`📊 变更进度: ${changeId}`);
+        console.log(`📊 变更进度: ${changeId}  |  Phase: ${phase} (${phaseIndex}/${phases.length})  |  ${progressBar} ${percentage.toFixed(1)}% (${completedCount}/${totalTasks})`);
         console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
         console.log('');
-        console.log(`Phase: ${phase} (${phaseIndex}/${phases.length})`);
-        console.log('');
         // Wave status
         for (const wave of waves) {
             const waveStatusEmoji = wave.status === 'completed' ? '✅' : wave.status === 'in_progress' ? '🔄' : '⏳';
@@ -229,8 +298,6 @@ export class ProgressCommand {
             }
             console.log('');
         }
-        // Overall progress
-        console.log(`整体: ${progressBar} ${percentage.toFixed(1)}% (${completedCount}/${totalTasks})`);
         // Duration info
         if (durationMin > 0) {
             console.log(`耗时: ${durationMin}m | 预计剩余: ~${estimatedRemaining}m`);

package/dist/core/hooks/record-progress.js

@@ -11,15 +11,118 @@ import { promises as fsPromises } from 'fs';
 import { FileSystemUtils } from '../../utils/file-system.js';
 import { PHASE_ORDER } from '../../utils/phase-utils.js';
 const fs = fsPromises;
+/**
+ * Atomic write JSON file: write to temp file first, then rename
+ * This prevents half-written files during crashes or concurrent writes
+ * @param filePath - Target file path
+ * @param data - Data to write (will be JSON stringified)
+ */
+async function atomicWriteJson(filePath, data) {
+    const tmpPath = `${filePath}.tmp`;
+    const content = JSON.stringify(data, null, 2);
+    try {
+        // Write to temp file first
+        await FileSystemUtils.writeFile(tmpPath, content);
+        // Rename to final path (atomic on most filesystems)
+        await fs.rename(tmpPath, filePath);
+    }
+    catch {
+        // On failure, try to clean up temp file
+        try {
+            await fs.unlink(tmpPath);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        // Do not throw - preserve original file and continue silently
+    }
+}
+/**
+ * Recover damaged progress.json for write operations
+ * Uses same three-tier strategy as read side
+ * @param filePath - Path to progress.json
+ * @returns Recovered ProgressData or null
+ */
+async function recoverProgressJsonForWrite(filePath) {
+    try {
+        const content = await FileSystemUtils.readFile(filePath);
+        // Layer 1: Standard JSON parse
+        try {
+            return JSON.parse(content);
+        }
+        catch {
+            // Continue to Layer 2
+        }
+        // Layer 2: Extract first top-level JSON object
+        const objectStart = content.indexOf('{');
+        if (objectStart === -1)
+            return null;
+        let depth = 0;
+        let objectEnd = -1;
+        for (let i = objectStart; i < content.length; i++) {
+            if (content[i] === '{')
+                depth++;
+            else if (content[i] === '}') {
+                depth--;
+                if (depth === 0) {
+                    objectEnd = i + 1;
+                    break;
+                }
+            }
+        }
+        if (objectEnd > objectStart) {
+            try {
+                return JSON.parse(content.slice(objectStart, objectEnd));
+            }
+            catch {
+                // Continue to Layer 3
+            }
+        }
+        // Layer 3: Minimal field extraction
+        const phaseMatch = content.match(/"phase"\s*:\s*"([^"]+)"/);
+        const changeIdMatch = content.match(/"changeId"\s*:\s*"([^"]+)"/);
+        const sessionIdMatch = content.match(/"sessionId"\s*:\s*"([^"]+)"/);
+        if (phaseMatch || changeIdMatch) {
+            return {
+                changeId: changeIdMatch?.[1] || '',
+                sessionId: sessionIdMatch?.[1] || '',
+                startedAt: '',
+                lastUpdatedAt: '',
+                phase: phaseMatch?.[1] || 'unknown',
+                currentNode: phaseMatch?.[1] || 'unknown',
+                currentTask: '',
+                completedTasks: [],
+                totalTasks: 0,
+                toolCalls: [],
+                skillCalls: [],
+                hookTriggers: [],
+                clarifications: [],
+                filesModified: [],
+                linesAdded: 0,
+                linesRemoved: 0,
+                deviationCount: 0,
+                deviationRecords: [],
+                reviewStats: { loopCount: 0, criticalFixes: 0, testFixes: 0, consistencyFixes: 0 },
+                phaseTransitions: [],
+                stats: { tokenUsageTotal: 0, contextLoad: 0, durationMs: { propose: 0, apply: 0, review: 0, archive: 0 } },
+            };
+        }
+    }
+    catch {
+        // File read error - return null
+    }
+    return null;
+}
 /**
  * Get Beijing time (UTC+8) as ISO string format
  * Returns format: "2026-04-19T18:35:22.934+08:00"
  */
 export function getBeijingTime() {
     const now = new Date();
-    // Beijing time is UTC+8
-    const beijingOffset = 8 * 60; // 8 hours in minutes
-    const beijingTime = new Date(now.getTime() + beijingOffset * 60 * 1000 - now.getTimezoneOffset() * 60 * 1000);
+    // Get UTC time and add 8 hours for Beijing
+    const utcMs = now.getTime() + now.getTimezoneOffset() * 60 * 1000;
+    const beijingMs = utcMs + 8 * 60 * 60 * 1000;
+    const beijingTime = new Date(beijingMs);
     // Format as ISO string with +08:00 timezone
     const year = beijingTime.getFullYear();
     const month = String(beijingTime.getMonth() + 1).padStart(2, '0');
@@ -36,8 +139,10 @@ export function getBeijingTime() {
  */
 export function getBeijingTimeForFilename() {
     const now = new Date();
-    const beijingOffset = 8 * 60;
-    const beijingTime = new Date(now.getTime() + beijingOffset * 60 * 1000 - now.getTimezoneOffset() * 60 * 1000);
+    // Get UTC time and add 8 hours for Beijing
+    const utcMs = now.getTime() + now.getTimezoneOffset() * 60 * 1000;
+    const beijingMs = utcMs + 8 * 60 * 60 * 1000;
+    const beijingTime = new Date(beijingMs);
     const year = beijingTime.getFullYear();
     const month = String(beijingTime.getMonth() + 1).padStart(2, '0');
     const day = String(beijingTime.getDate()).padStart(2, '0');
@@ -147,11 +252,12 @@ async function runRecordProgress(filePath, toolName, success, stdinData) {
     await FileSystemUtils.createDirectory(metricsDir);
     const progressPath = path.join(metricsDir, 'progress.json');
     const toolCallsPath = path.join(metricsDir, 'tool_calls.json');
-    // Load existing progress or create new
+    // Load existing progress or create new (with recovery support)
     let progress;
     if (await FileSystemUtils.fileExists(progressPath)) {
-        try {
-            progress = JSON.parse(await FileSystemUtils.readFile(progressPath));
+        const recovered = await recoverProgressJsonForWrite(progressPath);
+        if (recovered) {
+            progress = recovered;
             progress.phase = progress.phase || phase;
             progress.currentNode = progress.currentNode || phase;
             progress.completedTasks = progress.completedTasks || [];
@@ -183,7 +289,7 @@ async function runRecordProgress(filePath, toolName, success, stdinData) {
                 archive: 0,
             };
         }
-        catch {
+        else {
             progress = createNewProgress(changeId);
         }
     }
@@ -290,17 +396,26 @@ async function runRecordProgress(filePath, toolName, success, stdinData) {
     const contextLoadFromStdIn = Number(stdinData.tool_result?.contextLoad || 0);
     progress.stats.tokenUsageTotal += tokenUsageFromEnv + tokenUsageFromStdIn;
     progress.stats.contextLoad += contextLoadFromEnv + contextLoadFromStdIn;
-    const elapsedMs = Date.now() - new Date(progress.startedAt).getTime();
-    if (phase === 'propose')
-        progress.stats.durationMs.propose = elapsedMs;
-    if (phase === 'apply')
-        progress.stats.durationMs.apply = elapsedMs;
-    if (phase === 'review')
-        progress.stats.durationMs.review = elapsedMs;
-    if (phase === 'archive')
-        progress.stats.durationMs.archive = elapsedMs;
-    // Write progress file
-    await FileSystemUtils.writeFile(progressPath, JSON.stringify(progress, null, 2));
+    // Calculate duration for current phase from phaseTransitions
+    // Find the last transition to current phase
+    const transitionsToCurrentPhase = progress.phaseTransitions.filter((t) => t.to === phase);
+    const currentPhaseStart = transitionsToCurrentPhase[transitionsToCurrentPhase.length - 1];
+    if (currentPhaseStart) {
+        const startTime = new Date(currentPhaseStart.timestamp).getTime();
+        const elapsedMs = Date.now() - startTime;
+        if (elapsedMs > 0) {
+            if (phase === 'propose')
+                progress.stats.durationMs.propose = elapsedMs;
+            if (phase === 'apply')
+                progress.stats.durationMs.apply = elapsedMs;
+            if (phase === 'review')
+                progress.stats.durationMs.review = elapsedMs;
+            if (phase === 'archive')
+                progress.stats.durationMs.archive = elapsedMs;
+        }
+    }
+    // Write progress file atomically
+    await atomicWriteJson(progressPath, progress);
     // Also update tool_calls.json separately for detailed tracking
     let toolCallsLog;
     if (await FileSystemUtils.fileExists(toolCallsPath)) {
@@ -423,16 +538,16 @@ export async function initializeProgress(changeId, initialPhase = 'propose') {
     // Ensure metrics directory exists
     await FileSystemUtils.createDirectory(metricsDir);
     const progressPath = path.join(metricsDir, 'progress.json');
-    // Create or update progress file
+    // Create or update progress file (with recovery support)
     let progress;
     if (await FileSystemUtils.fileExists(progressPath)) {
-        try {
-            progress = JSON.parse(await FileSystemUtils.readFile(progressPath));
-            // Update phase (support phase transitions)
+        const recovered = await recoverProgressJsonForWrite(progressPath);
+        if (recovered) {
+            progress = recovered;
             progress.phase = initialPhase;
             progress.currentNode = initialPhase;
         }
-        catch {
+        else {
             progress = createNewProgress(changeId);
             progress.phase = initialPhase;
             progress.currentNode = initialPhase;
@@ -444,7 +559,7 @@ export async function initializeProgress(changeId, initialPhase = 'propose') {
         progress.currentNode = initialPhase;
     }
     progress.lastUpdatedAt = getBeijingTime();
-    await FileSystemUtils.writeFile(progressPath, JSON.stringify(progress, null, 2));
+    await atomicWriteJson(progressPath, progress);
 }
 /**
  * Record a hook trigger event
@@ -485,7 +600,7 @@ export async function recordHookTrigger(hookName, hookPhase, success, options) {
         };
         progress.hookTriggers.push(hookRecord);
         progress.lastUpdatedAt = getBeijingTime();
-        await FileSystemUtils.writeFile(progressPath, JSON.stringify(progress, null, 2));
+        await atomicWriteJson(progressPath, progress);
     }
     catch {
         // Ignore errors

package/dist/core/init.d.ts

@@ -58,7 +58,10 @@ export declare class InitCommand {
     private resolveClaudeAssetSource;
     private copyClaudeFileIfNeeded;
     private copyClaudeDirectoryIfNeeded;
-    private copyClaudeDirectoryWithFallback;
+    /**
+     * Copy .claude directory from common source (unified source, no fallback).
+     */
+    private copyClaudeDirectoryFromCommon;
     private copyClaudeDirectoryFromSingleSource;
     private directoryHasAtLeastOneFile;
     private copyClaudeDirectoryByFileSystem;