@zhuan-ai/zhuanspec 2.2.4 → 2.4.8

package/dist/core/hooks/summarize.js

@@ -0,0 +1,282 @@
+/**
+ * Stop Hook - Summarize Session Progress
+ *
+ * This hook runs when Claude Code session stops or pauses:
+ * 1. Summarize current wave completion status
+ * 2. Update ZHUANSPEC_CURRENT_TASK for next task
+ * 3. Check if tasks.md is complete → trigger Review phase
+ * 4. Generate events.json entries for key events
+ */
+import path from 'path';
+import { execSync } from 'child_process';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { executePostApply } from './post-apply.js';
+import { getBeijingTime } from './record-progress.js';
+export async function summarizeHook(options) {
+    const output = await runSummarize();
+    if (options.json) {
+        console.log(JSON.stringify(output));
+    }
+    else {
+        if (output.systemMessage) {
+            console.log(output.systemMessage);
+        }
+    }
+}
+async function runSummarize() {
+    const phase = process.env.ZHUANSPEC_PHASE || 'idle';
+    const changeId = process.env.ZHUANSPEC_CHANGE_ID || '';
+    const currentTask = process.env.ZHUANSPEC_CURRENT_TASK || '';
+    // No active change → nothing to summarize
+    if (!changeId || phase === 'idle') {
+        return {
+            continue: true,
+            systemMessage: 'ℹ No active ZhuanSpec change to summarize',
+        };
+    }
+    const cwd = process.cwd();
+    const zhuanspecDir = path.join(cwd, 'zhuanspec');
+    const changeDir = path.join(zhuanspecDir, 'changes', changeId);
+    const metricsDir = path.join(changeDir, 'metrics');
+    // Load progress data
+    const progressPath = path.join(metricsDir, 'progress.json');
+    let progressData = null;
+    if (await FileSystemUtils.fileExists(progressPath)) {
+        try {
+            progressData = JSON.parse(await FileSystemUtils.readFile(progressPath));
+        }
+        catch {
+            // Ignore parse errors
+        }
+    }
+    // Load tasks.md to analyze wave structure
+    const tasksPath = path.join(changeDir, 'tasks.md');
+    let tasks = [];
+    let waves = [];
+    if (await FileSystemUtils.fileExists(tasksPath)) {
+        const tasksContent = await FileSystemUtils.readFile(tasksPath);
+        tasks = parseTasks(tasksContent);
+        waves = computeWaves(tasks);
+    }
+    // Find current wave
+    const currentWave = waves.find(w => w.tasks.includes(currentTask) || w.status === 'in_progress');
+    // Calculate completion status
+    const allTasksComplete = tasks.length > 0 && tasks.every(t => t.status === 'completed');
+    const completedTasksCount = tasks.filter(t => t.status === 'completed').length;
+    // Find next task
+    let nextTask = '';
+    if (!allTasksComplete) {
+        const pendingTasks = tasks.filter(t => t.status === 'pending');
+        if (pendingTasks.length > 0) {
+            nextTask = pendingTasks[0].taskId;
+        }
+    }
+    // Auto review trigger: only once after all apply tasks complete.
+    // First, execute post-apply hook for deviation detection
+    let autoReviewTriggered = false;
+    let autoReviewPassed = false;
+    let deviationDetected = false;
+    if (phase === 'apply' && allTasksComplete) {
+        // Execute post-apply hook to detect deviations
+        const postApplyResult = await executePostApply(changeDir, cwd);
+        if (postApplyResult.hookSpecificOutput?.deviationDetected) {
+            deviationDetected = true;
+            // Don't trigger review if deviation detected
+        }
+        else {
+            // No deviation - proceed with auto review
+            const autoReviewEnabled = process.env.ZHUANSPEC_AUTO_REVIEW !== 'false';
+            const reviewPath = path.join(metricsDir, 'review.json');
+            const hasReviewReport = await FileSystemUtils.fileExists(reviewPath);
+            if (autoReviewEnabled && !hasReviewReport) {
+                try {
+                    execSync(`zhuanspec review "${changeId}"`, {
+                        cwd,
+                        stdio: 'pipe',
+                        encoding: 'utf-8',
+                    });
+                    autoReviewTriggered = true;
+                    autoReviewPassed = true;
+                }
+                catch {
+                    autoReviewTriggered = true;
+                    autoReviewPassed = false;
+                }
+            }
+        }
+    }
+    // Calculate metrics
+    const sessionDurationMs = progressData
+        ? Date.now() - new Date(progressData.startedAt).getTime()
+        : 0;
+    // Write events.json entry
+    const eventsPath = path.join(metricsDir, 'events.json');
+    const event = {
+        eventId: `evt-${Date.now()}`,
+        type: 'session_summary',
+        timestamp: getBeijingTime(),
+        data: {
+            phase,
+            currentTask,
+            currentWaveId: currentWave?.waveId,
+            tasksCompleted: completedTasksCount,
+            tasksTotal: tasks.length,
+            allTasksComplete,
+            nextTask,
+            toolCallsCount: progressData?.toolCalls.length || 0,
+            filesModifiedCount: progressData?.filesModified.length || 0,
+            linesAdded: progressData?.linesAdded || 0,
+            sessionDurationMs,
+            tokenUsageTotal: progressData?.stats?.tokenUsageTotal || 0,
+            contextLoad: progressData?.stats?.contextLoad || 0,
+        },
+    };
+    let eventsLog;
+    if (await FileSystemUtils.fileExists(eventsPath)) {
+        try {
+            eventsLog = JSON.parse(await FileSystemUtils.readFile(eventsPath));
+            eventsLog.events.push(event);
+        }
+        catch {
+            eventsLog = {
+                changeId,
+                sessionId: progressData?.sessionId || 'unknown',
+                events: [event],
+            };
+        }
+    }
+    else {
+        eventsLog = {
+            changeId,
+            sessionId: progressData?.sessionId || 'unknown',
+            events: [event],
+        };
+    }
+    await FileSystemUtils.writeFile(eventsPath, JSON.stringify(eventsLog, null, 2));
+    // Timeout detection - check if task has been idle for too long
+    const TIMEOUT_THRESHOLD_SECONDS = Number(process.env.ZHUANSPEC_TIMEOUT_SECONDS) || 300;
+    let timeoutWarning = '';
+    if (progressData && currentTask && phase === 'apply') {
+        const lastActiveTime = new Date(progressData.lastUpdatedAt).getTime();
+        const idleSeconds = Math.round((Date.now() - lastActiveTime) / 1000);
+        if (idleSeconds > TIMEOUT_THRESHOLD_SECONDS) {
+            const idleMinutes = Math.round(idleSeconds / 60);
+            timeoutWarning = `⚠️ 超时警告: 任务 ${currentTask} 可能卡住\n最后活跃: ${idleMinutes}m ago\n建议: 检查任务执行状态\n`;
+        }
+    }
+    // Build summary message
+    let systemMessage = `📊 ZhuanSpec Session Summary\n\n`;
+    systemMessage += `Phase: ${phase}\n`;
+    systemMessage += `Change: ${changeId}\n`;
+    if (currentTask) {
+        systemMessage += `Current Task: ${currentTask}\n`;
+    }
+    if (tasks.length > 0) {
+        systemMessage += `Tasks Progress: ${completedTasksCount}/${tasks.length} completed\n`;
+        if (currentWave) {
+            systemMessage += `Current Wave: Wave ${currentWave.waveId} (${currentWave.completedTasks.length}/${currentWave.tasks.length} completed)\n`;
+        }
+    }
+    // Add timeout warning if detected
+    if (timeoutWarning) {
+        systemMessage += `\n${timeoutWarning}`;
+    }
+    if (progressData) {
+        systemMessage += `\nMetrics:\n`;
+        systemMessage += `- Tool Calls: ${progressData.toolCalls.length}\n`;
+        systemMessage += `- Files Modified: ${progressData.filesModified.length}\n`;
+        systemMessage += `- Lines Added: ${progressData.linesAdded}\n`;
+        systemMessage += `- Session Duration: ${Math.round(sessionDurationMs / 1000)}s\n`;
+        systemMessage += `- Token Usage: ${progressData.stats?.tokenUsageTotal || 0}\n`;
+        systemMessage += `- Context Load: ${progressData.stats?.contextLoad || 0}\n`;
+    }
+    if (allTasksComplete) {
+        systemMessage += `\n✅ All tasks completed! Ready for Review phase.\n`;
+        if (deviationDetected) {
+            systemMessage += `⚠️ DEVIATION DETECTED. Please update proposal (Reverse Sync) before proceeding to Review.\n`;
+        }
+        else if (autoReviewTriggered) {
+            systemMessage += autoReviewPassed
+                ? `✅ Auto review executed successfully.\n`
+                : `⚠️ Auto review executed but failed. Please check zhuanspec review output.\n`;
+        }
+    }
+    else if (nextTask) {
+        systemMessage += `\n➡️ Next Task: ${nextTask}\n`;
+    }
+    return {
+        continue: true,
+        systemMessage,
+        hookSpecificOutput: {
+            waveCompleted: currentWave?.waveId,
+            nextTask,
+            allTasksComplete,
+            autoReviewTriggered,
+            metrics: {
+                totalToolCalls: progressData?.toolCalls.length || 0,
+                totalFilesModified: progressData?.filesModified.length || 0,
+                totalLinesAdded: progressData?.linesAdded || 0,
+                sessionDurationMs,
+                tokenUsageTotal: progressData?.stats?.tokenUsageTotal || 0,
+                contextLoad: progressData?.stats?.contextLoad || 0,
+            },
+        },
+    };
+}
+function parseTasks(content) {
+    const tasks = [];
+    const lines = content.split('\n');
+    let currentWave = 0;
+    for (const line of lines) {
+        // Match wave headers: ### Wave 1, ### Wave 2, etc.
+        const waveMatch = line.match(/^###\s*Wave\s*(\d+)/i);
+        if (waveMatch) {
+            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];
+            tasks.push({
+                taskId,
+                status: statusChar === 'x' ? 'completed' : 'pending',
+                wave: currentWave,
+            });
+        }
+    }
+    return tasks;
+}
+function computeWaves(tasks) {
+    const wavesMap = new Map();
+    for (const task of tasks) {
+        if (!wavesMap.has(task.wave)) {
+            wavesMap.set(task.wave, {
+                waveId: task.wave,
+                tasks: [],
+                completedTasks: [],
+                status: 'pending',
+            });
+        }
+        const wave = wavesMap.get(task.wave);
+        wave.tasks.push(task.taskId);
+        if (task.status === 'completed') {
+            wave.completedTasks.push(task.taskId);
+        }
+    }
+    // Determine wave status
+    for (const [waveId, wave] of wavesMap) {
+        if (wave.completedTasks.length === wave.tasks.length) {
+            wave.status = 'completed';
+        }
+        else if (wave.completedTasks.length > 0) {
+            wave.status = 'in_progress';
+        }
+        else {
+            wave.status = 'pending';
+        }
+    }
+    return Array.from(wavesMap.values()).sort((a, b) => a.waveId - b.waveId);
+}
+//# sourceMappingURL=summarize.js.map

package/dist/core/hooks/user-input-hook.d.ts

@@ -0,0 +1,25 @@
+/**
+ * User Input Hook
+ *
+ * Records user input summary during ZhuanSpec workflow.
+ * Tracks user interventions, corrections, confirmations, and additional requests.
+ */
+interface UserInputOutput {
+    continue: boolean;
+    systemMessage?: string;
+    hookSpecificOutput?: {
+        inputRecorded: boolean;
+        triggerType: string;
+        summaryLength: number;
+    };
+}
+/**
+ * Main hook function - records user input
+ */
+export declare function userInputHook(content: string, responseTimeMs?: number): Promise<UserInputOutput>;
+/**
+ * CLI entry point
+ */
+export declare function runUserInputHook(): Promise<void>;
+export {};
+//# sourceMappingURL=user-input-hook.d.ts.map

package/dist/core/hooks/user-input-hook.js

@@ -0,0 +1,179 @@
+/**
+ * User Input Hook
+ *
+ * Records user input summary during ZhuanSpec workflow.
+ * Tracks user interventions, corrections, confirmations, and additional requests.
+ */
+import path from 'path';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { getBeijingTime } from './record-progress.js';
+/**
+ * Detect trigger type from user input content
+ */
+function detectTriggerType(content) {
+    const lowerContent = content.toLowerCase();
+    // Correction patterns
+    if (lowerContent.includes('不对') || lowerContent.includes('错误') ||
+        lowerContent.includes('修复') || lowerContent.includes('修改') ||
+        lowerContent.includes('问题') || lowerContent.includes('bug')) {
+        return 'correction';
+    }
+    // Additional patterns
+    if (lowerContent.includes('另外') || lowerContent.includes('还有') ||
+        lowerContent.includes('追加') || lowerContent.includes('补充') ||
+        lowerContent.includes('加上')) {
+        return 'additional';
+    }
+    // Confirmation patterns
+    if (lowerContent.includes('好的') || lowerContent.includes('确认') ||
+        lowerContent.includes('同意') || lowerContent.includes('批准') ||
+        lowerContent.includes('继续') || lowerContent.includes('plan approved')) {
+        return 'confirmation';
+    }
+    // Clarification patterns
+    if (lowerContent.includes('?') || lowerContent.includes('为什么') ||
+        lowerContent.includes('怎么') || lowerContent.includes('如何') ||
+        lowerContent.includes('什么') || lowerContent.includes('澄清')) {
+        return 'clarification';
+    }
+    // Initial request (typically long first message)
+    if (content.length > 200) {
+        return 'initial';
+    }
+    return 'other';
+}
+/**
+ * Extract file references from user input
+ */
+function extractAffectedFiles(content) {
+    const filePatterns = [
+        /(?:file|文件|路径):\s*([^\s,]+)/gi,
+        /([a-zA-Z0-9_/-]+\.(?:java|ts|js|md|json|xml))/gi,
+        /zhuanspec\/[^\s]+/gi
+    ];
+    const files = [];
+    for (const pattern of filePatterns) {
+        const matches = content.match(pattern) || [];
+        files.push(...matches);
+    }
+    return [...new Set(files)].slice(0, 10); // Limit to 10 unique files
+}
+/**
+ * Generate summary from user input (max 200 chars)
+ */
+function generateSummary(content) {
+    // Truncate to 200 chars for summary
+    if (content.length <= 200) {
+        return content.trim();
+    }
+    // Extract first sentence or first 200 chars
+    const firstSentence = content.split(/[.!?\n]/)[0];
+    if (firstSentence.length <= 200) {
+        return firstSentence.trim();
+    }
+    return content.slice(0, 197) + '...';
+}
+/**
+ * Main hook function - records user input
+ */
+export async function userInputHook(content, responseTimeMs) {
+    const phase = process.env.ZHUANSPEC_PHASE || 'idle';
+    const changeId = process.env.ZHUANSPEC_CHANGE_ID || '';
+    // Skip if not in active phase
+    if (!changeId || phase === 'idle') {
+        return { continue: true };
+    }
+    // Skip empty content
+    if (!content || content.trim().length < 10) {
+        return { continue: true };
+    }
+    const cwd = process.cwd();
+    const zhuanspecDir = path.join(cwd, 'zhuanspec');
+    const metricsDir = path.join(zhuanspecDir, 'changes', changeId, 'metrics');
+    // Ensure metrics directory exists
+    await FileSystemUtils.createDirectory(metricsDir);
+    const userInputPath = path.join(metricsDir, 'user_inputs.json');
+    // Create input record
+    const inputRecord = {
+        inputId: `input-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        timestamp: getBeijingTime(),
+        phase,
+        summary: generateSummary(content),
+        triggerType: detectTriggerType(content),
+        affectedFiles: extractAffectedFiles(content),
+        responseTimeMs
+    };
+    // Load existing user inputs or create new
+    let userInputs;
+    if (await FileSystemUtils.fileExists(userInputPath)) {
+        try {
+            userInputs = JSON.parse(await FileSystemUtils.readFile(userInputPath));
+            userInputs.inputs.push(inputRecord);
+        }
+        catch {
+            userInputs = {
+                changeId,
+                sessionId: `sess-${Date.now()}`,
+                inputs: [inputRecord]
+            };
+        }
+    }
+    else {
+        userInputs = {
+            changeId,
+            sessionId: `sess-${Date.now()}`,
+            inputs: [inputRecord]
+        };
+    }
+    // Write user inputs file
+    await FileSystemUtils.writeFile(userInputPath, JSON.stringify(userInputs, null, 2));
+    return {
+        continue: true,
+        systemMessage: `📝 User input recorded: ${inputRecord.triggerType} (${inputRecord.summary.length} chars)`,
+        hookSpecificOutput: {
+            inputRecorded: true,
+            triggerType: inputRecord.triggerType,
+            summaryLength: inputRecord.summary.length
+        }
+    };
+}
+/**
+ * CLI entry point
+ */
+export async function runUserInputHook() {
+    // Read stdin for user message
+    let stdinData = {};
+    try {
+        const stdinContent = await readStdin();
+        if (stdinContent) {
+            stdinData = JSON.parse(stdinContent);
+        }
+    }
+    catch {
+        // Ignore parse errors
+    }
+    const content = stdinData.user_message || '';
+    const responseTimeMs = typeof stdinData.response_time_ms === 'number'
+        ? stdinData.response_time_ms
+        : undefined;
+    if (!content) {
+        console.log(JSON.stringify({ continue: true }));
+        return;
+    }
+    const output = await userInputHook(content, responseTimeMs);
+    console.log(JSON.stringify(output));
+}
+async function readStdin() {
+    return new Promise((resolve) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', chunk => data += chunk);
+        process.stdin.on('end', () => resolve(data));
+        process.stdin.on('error', () => resolve(null));
+    });
+}
+// CLI execution
+if (require.main === module) {
+    runUserInputHook();
+}
+//# sourceMappingURL=user-input-hook.js.map

package/dist/core/init.d.ts

@@ -69,7 +69,15 @@ export declare class InitCommand {
     private writeTemplateFiles;
     private configureAITools;
     private configureRootAgentsStub;
+    /**
+     * Generate Claude Code hooks configuration for ZhuanSpec workflow.
+     * Creates .claude/settings.json with hooks for SessionStart, PreToolUse, PostToolUse, and Stop.
+     */
+    private generateClaudeSettings;
+    private readExistingSettings;
+    private mergeSettings;
     private displaySuccessMessage;
+    private displayWorkflowDiagram;
     private formatToolNames;
     private renderBanner;
     private startSpinner;