@zhuan-ai/zhuanspec 2.2.4 → 2.4.8

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

@@ -0,0 +1,494 @@
+/**
+ * PostToolUse Hook - Record Progress
+ *
+ * This hook runs after Write/Edit operations to:
+ * 1. Record the modification to progress.json
+ * 2. Update tasks.md status if applicable
+ * 3. Track tool calls for metrics
+ */
+import path from 'path';
+import { promises as fsPromises } from 'fs';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { PHASE_ORDER } from '../../utils/phase-utils.js';
+const fs = fsPromises;
+/**
+ * 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);
+    // Format as ISO string with +08:00 timezone
+    const year = beijingTime.getFullYear();
+    const month = String(beijingTime.getMonth() + 1).padStart(2, '0');
+    const day = String(beijingTime.getDate()).padStart(2, '0');
+    const hours = String(beijingTime.getHours()).padStart(2, '0');
+    const minutes = String(beijingTime.getMinutes()).padStart(2, '0');
+    const seconds = String(beijingTime.getSeconds()).padStart(2, '0');
+    const ms = String(beijingTime.getMilliseconds()).padStart(3, '0');
+    return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}.${ms}+08:00`;
+}
+/**
+ * Get Beijing time date string for session ID and filenames
+ * Returns format: "2026-04-19T18-35-22"
+ */
+export function getBeijingTimeForFilename() {
+    const now = new Date();
+    const beijingOffset = 8 * 60;
+    const beijingTime = new Date(now.getTime() + beijingOffset * 60 * 1000 - now.getTimezoneOffset() * 60 * 1000);
+    const year = beijingTime.getFullYear();
+    const month = String(beijingTime.getMonth() + 1).padStart(2, '0');
+    const day = String(beijingTime.getDate()).padStart(2, '0');
+    const hours = String(beijingTime.getHours()).padStart(2, '0');
+    const minutes = String(beijingTime.getMinutes()).padStart(2, '0');
+    const seconds = String(beijingTime.getSeconds()).padStart(2, '0');
+    return `${year}-${month}-${day}T${hours}-${minutes}-${seconds}`;
+}
+export async function recordProgressHook(options) {
+    // Read stdin for Claude Code hook input
+    let stdinData = {};
+    try {
+        const stdinContent = await readStdin();
+        if (stdinContent) {
+            stdinData = JSON.parse(stdinContent);
+        }
+    }
+    catch {
+        // Ignore parse errors
+    }
+    // Get file path from stdin or options
+    const filePath = stdinData.tool_input?.file_path
+        || options.file
+        || '';
+    const toolName = stdinData.tool_name || options.tool || 'Write';
+    const success = stdinData.tool_result?.success !== false
+        && options.success !== 'false';
+    const output = await runRecordProgress(filePath, toolName, success, stdinData);
+    if (options.json) {
+        console.log(JSON.stringify(output));
+    }
+    else {
+        if (output.systemMessage) {
+            console.log(output.systemMessage);
+        }
+    }
+}
+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));
+    });
+}
+// Extract MCP server name from tool name (e.g., mcp__aicodegather__beforeEditFile)
+function extractMcpServer(toolName) {
+    if (!toolName.startsWith('mcp__'))
+        return undefined;
+    const parts = toolName.split('__');
+    return parts.length >= 2 ? parts[1] : undefined;
+}
+// Extract MCP tool name from tool name
+function extractMcpTool(toolName) {
+    if (!toolName.startsWith('mcp__'))
+        return undefined;
+    const parts = toolName.split('__');
+    return parts.length >= 3 ? parts[2] : undefined;
+}
+/**
+ * Detect active change from progress.json files
+ * Scans changes directory metrics progress.json to find non-idle phase
+ * Returns null if no active change found
+ */
+async function detectActiveChange(cwd) {
+    const changesDir = path.join(cwd, 'zhuanspec', 'changes');
+    if (!await FileSystemUtils.directoryExists(changesDir)) {
+        return null;
+    }
+    const entries = await fs.readdir(changesDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'archive')
+            continue;
+        const progressPath = path.join(changesDir, entry.name, 'metrics', 'progress.json');
+        if (await FileSystemUtils.fileExists(progressPath)) {
+            try {
+                const progress = JSON.parse(await FileSystemUtils.readFile(progressPath));
+                if (progress.phase && progress.phase !== 'idle' && PHASE_ORDER.includes(progress.phase)) {
+                    return { changeId: entry.name, phase: progress.phase };
+                }
+            }
+            catch {
+                // Ignore parse errors
+            }
+        }
+    }
+    return null;
+}
+async function runRecordProgress(filePath, toolName, success, stdinData) {
+    const cwd = process.cwd();
+    // Priority: progress.json > environment variables
+    const activeChange = await detectActiveChange(cwd);
+    const phase = activeChange?.phase || process.env.ZHUANSPEC_PHASE || 'idle';
+    const changeId = activeChange?.changeId || process.env.ZHUANSPEC_CHANGE_ID || '';
+    const currentTask = process.env.ZHUANSPEC_CURRENT_TASK || '';
+    // No active change → nothing to record
+    if (!changeId || phase === 'idle') {
+        return {
+            continue: true,
+        };
+    }
+    const zhuanspecDir = path.join(cwd, 'zhuanspec');
+    const changeDir = path.join(zhuanspecDir, 'changes', changeId);
+    const metricsDir = path.join(changeDir, 'metrics');
+    // Ensure metrics directory exists
+    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
+    let progress;
+    if (await FileSystemUtils.fileExists(progressPath)) {
+        try {
+            progress = JSON.parse(await FileSystemUtils.readFile(progressPath));
+            progress.phase = progress.phase || phase;
+            progress.currentNode = progress.currentNode || phase;
+            progress.completedTasks = progress.completedTasks || [];
+            progress.toolCalls = progress.toolCalls || [];
+            progress.skillCalls = progress.skillCalls || [];
+            progress.hookTriggers = progress.hookTriggers || [];
+            progress.clarifications = progress.clarifications || [];
+            progress.filesModified = progress.filesModified || [];
+            progress.linesAdded = progress.linesAdded || 0;
+            progress.linesRemoved = progress.linesRemoved || 0;
+            progress.deviationCount = progress.deviationCount || 0;
+            progress.deviationRecords = progress.deviationRecords || [];
+            progress.reviewStats = progress.reviewStats || {
+                loopCount: 0,
+                criticalFixes: 0,
+                testFixes: 0,
+                consistencyFixes: 0,
+            };
+            progress.phaseTransitions = progress.phaseTransitions || [];
+            progress.stats = progress.stats || {
+                tokenUsageTotal: 0,
+                contextLoad: 0,
+                durationMs: { propose: 0, apply: 0, review: 0, archive: 0 },
+            };
+            progress.stats.durationMs = progress.stats.durationMs || {
+                propose: 0,
+                apply: 0,
+                review: 0,
+                archive: 0,
+            };
+        }
+        catch {
+            progress = createNewProgress(changeId);
+        }
+    }
+    else {
+        progress = createNewProgress(changeId);
+    }
+    // Record tool call with extended tool support
+    const toolInput = stdinData.tool_input || {};
+    const callId = `call-${Date.now()}`;
+    const timestamp = getBeijingTime();
+    // Detect and record Skill calls separately
+    if (toolName === 'Skill') {
+        const skillCall = {
+            callId,
+            skill: typeof toolInput.skill === 'string' ? toolInput.skill : '',
+            args: typeof toolInput.args === 'string' ? toolInput.args : undefined,
+            triggeredAt: timestamp,
+            phase,
+            success,
+        };
+        progress.skillCalls.push(skillCall);
+    }
+    // Detect and record AskQuestion calls as clarifications
+    if (toolName === 'AskUserQuestion') {
+        const questionsData = toolInput.questions || [];
+        const answersData = stdinData.tool_result || {};
+        const clarification = {
+            clarificationId: callId,
+            questions: questionsData.map(q => ({
+                question: typeof q.question === 'string' ? q.question : '',
+                header: typeof q.header === 'string' ? q.header : undefined,
+                options: (q.options || []).map(opt => ({
+                    label: typeof opt.label === 'string' ? opt.label : '',
+                    description: typeof opt.description === 'string' ? opt.description : undefined,
+                })),
+                multiSelect: typeof q.multiSelect === 'boolean' ? q.multiSelect : false,
+            })),
+            answers: answersData.answers || {},
+            annotations: answersData.annotations || undefined,
+            askedAt: timestamp,
+            answeredAt: timestamp, // Assuming answered immediately in hook context
+            phase,
+        };
+        progress.clarifications.push(clarification);
+    }
+    // Standard tool call record
+    const toolCall = {
+        callId,
+        tool: toolName,
+        input: {
+            file_path: filePath,
+            content: typeof toolInput.content === 'string' ? toolInput.content : undefined,
+            // Extended inputs
+            pattern: typeof toolInput.pattern === 'string' ? toolInput.pattern : undefined,
+            path: typeof toolInput.path === 'string' ? toolInput.path : undefined,
+            command: typeof toolInput.command === 'string' ? toolInput.command : undefined,
+            skill: typeof toolInput.skill === 'string' ? toolInput.skill : undefined,
+            args: typeof toolInput.args === 'string' ? toolInput.args : undefined,
+            agent_type: typeof toolInput.subagent_type === 'string' ? toolInput.subagent_type : undefined,
+            mcp_server: extractMcpServer(toolName),
+            mcp_tool: extractMcpTool(toolName),
+        },
+        output: {
+            success,
+        },
+        timestamp,
+        phase,
+        taskId: currentTask,
+    };
+    // Update progress
+    progress.lastUpdatedAt = getBeijingTime();
+    // Record phase transition if phase changed
+    const previousPhase = progress.phase;
+    progress.phase = phase;
+    if (previousPhase !== phase) {
+        progress.phaseTransitions.push({
+            from: previousPhase,
+            to: phase,
+            timestamp: getBeijingTime(),
+            triggeredBy: currentTask || 'manual',
+        });
+    }
+    progress.currentNode = process.env.ZHUANSPEC_CURRENT_NODE || phase;
+    progress.currentTask = currentTask || progress.currentTask;
+    progress.toolCalls.push(toolCall);
+    if (filePath && !progress.filesModified.includes(filePath)) {
+        progress.filesModified.push(filePath);
+    }
+    // Try to estimate lines from content
+    const content = stdinData.tool_input?.content;
+    if (content) {
+        const lines = content.split('\n').length;
+        if (toolName === 'Write') {
+            progress.linesAdded += lines;
+        }
+        else if (toolName === 'Edit') {
+            // For Edit, we can't easily track lines removed/added
+            progress.linesAdded += 1; // Estimate
+        }
+    }
+    const tokenUsageFromEnv = Number(process.env.ZHUANSPEC_TOKEN_USAGE || 0);
+    const contextLoadFromEnv = Number(process.env.ZHUANSPEC_CONTEXT_LOAD || 0);
+    const tokenUsageFromStdIn = Number(stdinData.tool_result?.tokenUsage || 0);
+    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));
+    // Also update tool_calls.json separately for detailed tracking
+    let toolCallsLog;
+    if (await FileSystemUtils.fileExists(toolCallsPath)) {
+        try {
+            toolCallsLog = JSON.parse(await FileSystemUtils.readFile(toolCallsPath));
+            toolCallsLog.toolCalls.push(toolCall);
+        }
+        catch {
+            toolCallsLog = {
+                changeId,
+                sessionId: progress.sessionId,
+                toolCalls: [toolCall],
+            };
+        }
+    }
+    else {
+        toolCallsLog = {
+            changeId,
+            sessionId: progress.sessionId,
+            toolCalls: [toolCall],
+        };
+    }
+    await FileSystemUtils.writeFile(toolCallsPath, JSON.stringify(toolCallsLog, null, 2));
+    // Check if this completes the current task
+    // (simplified: if file was modified and we're in apply phase, mark task as potentially complete)
+    let taskMarked = '';
+    if (phase === 'apply' && currentTask && filePath) {
+        const tasksPath = path.join(changeDir, 'tasks.md');
+        if (await FileSystemUtils.fileExists(tasksPath)) {
+            const tasksContent = await FileSystemUtils.readFile(tasksPath);
+            // Check if the task line already has [x] or needs manual confirmation
+            const taskPattern = new RegExp(`-\\s*\\[[x ]\\]\\s*${currentTask.replace('.', '\\.')}`);
+            const taskMatch = tasksContent.match(taskPattern);
+            if (taskMatch && !taskMatch[0].includes('[x]')) {
+                // Task is pending - we don't auto-mark it here, but note it for Stop hook
+                taskMarked = currentTask;
+            }
+        }
+    }
+    // Calculate progress percentage and visual bar
+    const totalTasks = progress.totalTasks || 0;
+    const completedTasks = progress.completedTasks.length;
+    const percentage = totalTasks > 0 ? (completedTasks / totalTasks) * 100 : 0;
+    const progressBar = generateProgressBar(percentage, 12);
+    const progressDisplay = totalTasks > 0
+        ? `${progressBar} ${percentage.toFixed(1)}% (${completedTasks}/${totalTasks})`
+        : '进度: N/A (任务数待定)';
+    return {
+        continue: true,
+        systemMessage: `📝 Progress recorded: ${toolName} ${filePath}
+    | Phase: ${phase} | Task: ${currentTask || 'N/A'}
+    | 进度: ${progressDisplay}`,
+        hookSpecificOutput: {
+            progressUpdated: true,
+            taskMarked,
+        },
+    };
+}
+/**
+ * Generate visual progress bar
+ * @param percentage - Progress percentage (0-100)
+ * @param blocks - Number of blocks in the bar
+ */
+function generateProgressBar(percentage, blocks) {
+    const filled = Math.round((percentage / 100) * blocks);
+    const empty = blocks - filled;
+    return '█'.repeat(filled) + '░'.repeat(empty);
+}
+function createNewProgress(changeId) {
+    const sessionId = `sess-${getBeijingTimeForFilename()}`;
+    return {
+        changeId,
+        sessionId,
+        startedAt: getBeijingTime(),
+        lastUpdatedAt: getBeijingTime(),
+        phase: process.env.ZHUANSPEC_PHASE || 'idle',
+        currentNode: process.env.ZHUANSPEC_CURRENT_NODE || process.env.ZHUANSPEC_PHASE || 'idle',
+        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,
+            },
+        },
+    };
+}
+/**
+ * Initialize progress.json at phase start
+ * This function should be called when a change is created, before any files are written.
+ * @param changeId - The change ID
+ * @param initialPhase - The initial phase to set (default: 'propose')
+ */
+export async function initializeProgress(changeId, initialPhase = 'propose') {
+    const cwd = process.cwd();
+    const zhuanspecDir = path.join(cwd, 'zhuanspec');
+    const changeDir = path.join(zhuanspecDir, 'changes', changeId);
+    const metricsDir = path.join(changeDir, 'metrics');
+    // Ensure metrics directory exists
+    await FileSystemUtils.createDirectory(metricsDir);
+    const progressPath = path.join(metricsDir, 'progress.json');
+    // Create or update progress file
+    let progress;
+    if (await FileSystemUtils.fileExists(progressPath)) {
+        try {
+            progress = JSON.parse(await FileSystemUtils.readFile(progressPath));
+            // Update phase (support phase transitions)
+            progress.phase = initialPhase;
+            progress.currentNode = initialPhase;
+        }
+        catch {
+            progress = createNewProgress(changeId);
+            progress.phase = initialPhase;
+            progress.currentNode = initialPhase;
+        }
+    }
+    else {
+        progress = createNewProgress(changeId);
+        progress.phase = initialPhase;
+        progress.currentNode = initialPhase;
+    }
+    progress.lastUpdatedAt = getBeijingTime();
+    await FileSystemUtils.writeFile(progressPath, JSON.stringify(progress, null, 2));
+}
+/**
+ * Record a hook trigger event
+ * This function can be called from other hooks to record their execution
+ * @param hookName - The name of the hook (e.g., 'init', 'deviation-check')
+ * @param hookPhase - The lifecycle phase (SessionStart, PreToolUse, PostToolUse, Stop)
+ * @param success - Whether the hook executed successfully
+ * @param options - Additional context (toolName, filePath, message, durationMs)
+ */
+export async function recordHookTrigger(hookName, hookPhase, success, options) {
+    const cwd = process.cwd();
+    const activeChange = await detectActiveChange(cwd);
+    const phase = activeChange?.phase || process.env.ZHUANSPEC_PHASE || 'idle';
+    const changeId = activeChange?.changeId || process.env.ZHUANSPEC_CHANGE_ID || '';
+    if (!changeId || phase === 'idle')
+        return;
+    const zhuanspecDir = path.join(cwd, 'zhuanspec');
+    const changeDir = path.join(zhuanspecDir, 'changes', changeId);
+    const metricsDir = path.join(changeDir, 'metrics');
+    const progressPath = path.join(metricsDir, 'progress.json');
+    if (!await FileSystemUtils.fileExists(progressPath))
+        return;
+    try {
+        const progress = JSON.parse(await FileSystemUtils.readFile(progressPath));
+        // Ensure hookTriggers array exists
+        progress.hookTriggers = progress.hookTriggers || [];
+        const hookRecord = {
+            hookId: `hook-${Date.now()}`,
+            hookName,
+            hookPhase,
+            triggeredAt: getBeijingTime(),
+            phase,
+            toolName: options?.toolName,
+            filePath: options?.filePath,
+            success,
+            durationMs: options?.durationMs,
+            message: options?.message,
+        };
+        progress.hookTriggers.push(hookRecord);
+        progress.lastUpdatedAt = getBeijingTime();
+        await FileSystemUtils.writeFile(progressPath, JSON.stringify(progress, null, 2));
+    }
+    catch {
+        // Ignore errors
+    }
+}
+//# sourceMappingURL=record-progress.js.map

package/dist/core/hooks/review-hooks.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Review Hooks - Result Checkers for Review Phase
+ *
+ * Three independent hooks for Review phase (Phase 3):
+ * 1. code-review-result: Check code-review-expert skill output
+ * 2. unit-test-result: Check generate-mockito-unit-test-skill output
+ * 3. spec-consistency-result: Check spec-code-consistency output
+ *
+ * Each hook:
+ * - Reads skill output file
+ * - Extracts key metrics (Critical count, coverage, consistency)
+ * - Decides if fix loop is needed
+ * - Controls loop count (max 3)
+ */
+declare const MAX_LOOP_COUNT = 3;
+interface CodeReviewOutput {
+    criticalCount: number;
+    importantCount: number;
+    infoCount: number;
+    issues: Array<{
+        level: 'critical' | 'important' | 'info';
+        file: string;
+        line?: number;
+        message: string;
+        ruleId?: string;
+    }>;
+    sonarStatus?: 'pass' | 'fail' | 'skip';
+    loopCount?: number;
+}
+interface HookResult {
+    pass: boolean;
+    needFix: boolean;
+    loopCount: number;
+    metrics: Record<string, unknown>;
+    fixPrompt?: string;
+    nextAction?: 'continue' | 'fix' | 'stop';
+}
+export declare function codeReviewResultCheck(changeId: string, skillOutput?: CodeReviewOutput): Promise<HookResult>;
+interface UnitTestOutput {
+    testPassed: boolean;
+    passRate: number;
+    coverage: number;
+    coverageThreshold: number;
+    newTestsGenerated: string[];
+    failedTests: string[];
+    loopCount?: number;
+}
+export declare function unitTestResultCheck(changeId: string, skillOutput?: UnitTestOutput): Promise<HookResult>;
+interface SpecConsistencyOutput {
+    consistencyRate: number;
+    totalRequirements: number;
+    totalScenarios: number;
+    coveredScenarios: number;
+    uncoveredScenarios: Array<{
+        requirementId: string;
+        scenarioId: string;
+        description: string;
+    }>;
+    mapping: Array<{
+        requirementId: string;
+        scenarioId: string;
+        codeFile: string;
+        codeLine?: number;
+        status: 'covered' | 'partial' | 'missing';
+    }>;
+    loopCount?: number;
+}
+export declare function specConsistencyResultCheck(changeId: string, skillOutput?: SpecConsistencyOutput): Promise<HookResult>;
+export declare function writeCodeReviewOutput(changeId: string, output: CodeReviewOutput): Promise<void>;
+export declare function writeUnitTestOutput(changeId: string, output: UnitTestOutput): Promise<void>;
+export declare function writeSpecConsistencyOutput(changeId: string, output: SpecConsistencyOutput): Promise<void>;
+export { writeSkillOutput };
+declare function writeSkillOutput(changeId: string, filename: string, data: unknown): Promise<void>;
+export interface ReviewReport {
+    changeId: string;
+    timestamp: string;
+    codeReview: HookResult;
+    unitTest: HookResult;
+    specConsistency: HookResult;
+    overallPass: boolean;
+    canArchive: boolean;
+}
+export declare function generateReviewReport(changeId: string, results: {
+    codeReview: HookResult;
+    unitTest: HookResult;
+    specConsistency: HookResult;
+}): Promise<string>;
+export { CodeReviewOutput, UnitTestOutput, SpecConsistencyOutput, HookResult, MAX_LOOP_COUNT, };
+//# sourceMappingURL=review-hooks.d.ts.map