@zhuan-ai/zhuanspec 2.2.4 → 2.4.8

package/dist/core/hooks/post-archive.js

@@ -0,0 +1,208 @@
+import path from 'path';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { readdirSync, rmSync } from 'fs';
+import chalk from 'chalk';
+import { getBeijingTime, getBeijingTimeForFilename } from './record-progress.js';
+export async function postArchiveHook(options) {
+    const output = await runPostArchiveHook(options.archived || '');
+    if (options.json) {
+        console.log(JSON.stringify(output));
+    }
+    else if (output.systemMessage) {
+        console.log(output.systemMessage);
+    }
+}
+async function runPostArchiveHook(archivedChange) {
+    if (!archivedChange) {
+        return { continue: true, systemMessage: 'Post-archive hook skipped: no archived change provided' };
+    }
+    const repoRoot = process.cwd();
+    const zhuanspecDir = path.join(repoRoot, 'zhuanspec');
+    const knowledgeDir = path.join(zhuanspecDir, 'knowledge');
+    // 1. Update archive log
+    console.log(chalk.gray('  → 更新知识索引...'));
+    await FileSystemUtils.createDirectory(knowledgeDir);
+    const indexPath = path.join(knowledgeDir, 'index.md');
+    const line = `- ${getBeijingTime()} archived: ${archivedChange}`;
+    if (await FileSystemUtils.fileExists(indexPath)) {
+        const existing = await FileSystemUtils.readFile(indexPath);
+        await FileSystemUtils.writeFile(indexPath, `${existing.trimEnd()}\n${line}\n`);
+    }
+    else {
+        await FileSystemUtils.writeFile(indexPath, `# Knowledge Index\n\n## Archive Log\n${line}\n`);
+    }
+    // 2. Collect change knowledge (extract decisions, best practices, implicit conventions)
+    console.log(chalk.gray('  → 提取设计文档中的知识记录...'));
+    const knowledgeResult = await collectChangeKnowledge(zhuanspecDir, archivedChange, knowledgeDir);
+    if (knowledgeResult.decisions > 0) {
+        console.log(chalk.gray(`    - 决策记录：${knowledgeResult.decisions} 条`));
+    }
+    if (knowledgeResult.bestPractices > 0) {
+        console.log(chalk.gray(`    - 最佳实践：${knowledgeResult.bestPractices} 条`));
+    }
+    if (knowledgeResult.implicitConventions > 0) {
+        console.log(chalk.gray(`    - 隐式约定：${knowledgeResult.implicitConventions} 条`));
+    }
+    // 3. Cleanup temp files
+    console.log(chalk.gray('  → 清理临时文件...'));
+    const tempFilesCleaned = await cleanupTempFiles(zhuanspecDir);
+    if (tempFilesCleaned > 0) {
+        console.log(chalk.gray(`    - 已清理：${tempFilesCleaned} 个`));
+    }
+    const totalEntries = knowledgeResult.decisions + knowledgeResult.bestPractices + knowledgeResult.implicitConventions;
+    console.log(chalk.green(`✅ 知识收集完成：共 ${totalEntries} 条记录`));
+    return {
+        continue: true,
+        systemMessage: `Post-archive: knowledge updated for ${archivedChange}, ${knowledgeResult.decisions} decisions, ${knowledgeResult.bestPractices} best practices, ${knowledgeResult.implicitConventions} implicit conventions, ${tempFilesCleaned} temp files cleaned`,
+        hookSpecificOutput: {
+            decisionsCollected: knowledgeResult.decisions,
+            bestPracticesCollected: knowledgeResult.bestPractices,
+            implicitConventionsCollected: knowledgeResult.implicitConventions,
+            tempFilesCleaned,
+        },
+    };
+}
+/**
+ * Extract knowledge records from change directory (proposal.md, tasks.md, design.md, specs/*.md)
+ * and save to knowledge subdirectories
+ */
+async function collectChangeKnowledge(zhuanspecDir, archivedChange, knowledgeDir) {
+    const result = {
+        decisions: 0,
+        bestPractices: 0,
+        implicitConventions: 0,
+    };
+    // Find archived change directory
+    const archiveDir = path.join(zhuanspecDir, 'changes', 'archive', archivedChange);
+    // Source files to extract knowledge from (in priority order)
+    const sourceFiles = [
+        path.join(archiveDir, 'design.md'), // Optional, highest priority
+        path.join(archiveDir, 'proposal.md'), // Required
+        path.join(archiveDir, 'tasks.md'), // Required
+    ];
+    // Also check specs subdirectory
+    const specsDir = path.join(archiveDir, 'specs');
+    if (await FileSystemUtils.directoryExists(specsDir)) {
+        try {
+            const specEntries = readdirSync(specsDir, { withFileTypes: true });
+            for (const entry of specEntries) {
+                if (entry.isDirectory()) {
+                    const specMd = path.join(specsDir, entry.name, 'spec.md');
+                    if (await FileSystemUtils.fileExists(specMd)) {
+                        sourceFiles.push(specMd);
+                    }
+                }
+            }
+        }
+        catch {
+            // Ignore directory read errors
+        }
+    }
+    // Collect content from all available source files
+    let combinedContent = '';
+    for (const filePath of sourceFiles) {
+        if (await FileSystemUtils.fileExists(filePath)) {
+            try {
+                const content = await FileSystemUtils.readFile(filePath);
+                combinedContent += `\n\n--- Source: ${path.basename(filePath)} ---\n\n${content}`;
+            }
+            catch {
+                // Ignore file read errors
+            }
+        }
+    }
+    if (!combinedContent.trim()) {
+        return result;
+    }
+    try {
+        // Create knowledge subdirectories
+        const decisionsDir = path.join(knowledgeDir, 'decisions');
+        const bestPracticesDir = path.join(knowledgeDir, 'best-practices');
+        const implicitConventionsDir = path.join(knowledgeDir, 'implicit-conventions');
+        await FileSystemUtils.createDirectory(decisionsDir);
+        await FileSystemUtils.createDirectory(bestPracticesDir);
+        await FileSystemUtils.createDirectory(implicitConventionsDir);
+        // Define regex patterns for each knowledge type (Chinese and English)
+        const patterns = {
+            decisions: /^##\s+(决策|Decision|技术决策|架构决策)[\s\S]*?(?=^##[^#]|$)/gm,
+            bestPractices: /^##\s+(最佳实践|Best\s+Practice|Best\s+Practices|推荐做法|建议|注意事项)[\s\S]*?(?=^##[^#]|$)/gm,
+            implicitConventions: /^##\s+(隐式约定|Implicit\s+Convention|默认行为|约定|惯例|约定事项)[\s\S]*?(?=^##[^#]|$)/gm,
+        };
+        const targetDirs = {
+            decisions: decisionsDir,
+            bestPractices: bestPracticesDir,
+            implicitConventions: implicitConventionsDir,
+        };
+        // Extract and save each knowledge type
+        for (const [type, pattern] of Object.entries(patterns)) {
+            const matches = combinedContent.matchAll(pattern);
+            const entries = [];
+            for (const match of matches) {
+                const content = match[0].trim();
+                if (content.length > 50) {
+                    entries.push(content);
+                }
+            }
+            if (entries.length > 0) {
+                const timestamp = getBeijingTimeForFilename();
+                const fileName = `${archivedChange}-${type}-${timestamp}.md`;
+                const filePath = path.join(targetDirs[type], fileName);
+                const typeLabel = type === 'decisions' ? 'Decision Records' :
+                    type === 'bestPractices' ? 'Best Practices' :
+                        'Implicit Conventions';
+                const doc = `# ${typeLabel} from ${archivedChange}
+
+Extracted on: ${getBeijingTime()}
+
+${entries.join('\n\n---\n\n')}
+`;
+                await FileSystemUtils.writeFile(filePath, doc);
+                result[type] = entries.length;
+            }
+        }
+        return result;
+    }
+    catch {
+        return result;
+    }
+}
+/**
+ * Cleanup temporary files from zhuanspec directory
+ */
+async function cleanupTempFiles(zhuanspecDir) {
+    const tempPatterns = [
+        '.temp-session',
+        '.temp-progress',
+        '.temp-',
+        '.cache-',
+    ];
+    let cleanedCount = 0;
+    try {
+        const entries = readdirSync(zhuanspecDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const name = entry.name;
+            // Check if file/directory matches temp patterns
+            const isTemp = tempPatterns.some(pattern => name.startsWith(pattern));
+            if (isTemp) {
+                const fullPath = path.join(zhuanspecDir, name);
+                try {
+                    if (entry.isDirectory()) {
+                        rmSync(fullPath, { recursive: true, force: true });
+                    }
+                    else {
+                        rmSync(fullPath, { force: true });
+                    }
+                    cleanedCount++;
+                }
+                catch {
+                    // Ignore cleanup failures
+                }
+            }
+        }
+    }
+    catch {
+        // Directory read failed, return 0
+    }
+    return cleanedCount;
+}
+//# sourceMappingURL=post-archive.js.map

package/dist/core/hooks/pre-apply.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Pre-Apply Hook
+ *
+ * Checks before entering Apply phase:
+ * 1. proposal.md exists
+ * 2. tasks.md exists
+ * 3. specs/ directory exists and non-empty
+ * 4. validate --strict passes
+ * 5. .approved file exists (Plan Approved gate)
+ */
+interface PreApplyOptions {
+    json?: boolean;
+    change?: string;
+}
+interface HookOutput {
+    continue: boolean;
+    stopReason?: string;
+    systemMessage?: string;
+    checks?: {
+        proposalExists: boolean;
+        tasksExists: boolean;
+        specsExists: boolean;
+        validationPassed: boolean;
+        approved: boolean;
+    };
+}
+export declare function preApplyHook(options: PreApplyOptions): Promise<void>;
+/**
+ * Check pre-apply conditions for a change directory.
+ * This function is exported for use by other hooks (e.g., deviation-check).
+ */
+export declare function checkPreApplyConditions(changeDir: string): Promise<HookOutput>;
+export {};
+//# sourceMappingURL=pre-apply.d.ts.map

package/dist/core/hooks/pre-apply.js

@@ -0,0 +1,139 @@
+/**
+ * Pre-Apply Hook
+ *
+ * Checks before entering Apply phase:
+ * 1. proposal.md exists
+ * 2. tasks.md exists
+ * 3. specs/ directory exists and non-empty
+ * 4. validate --strict passes
+ * 5. .approved file exists (Plan Approved gate)
+ */
+import path from 'path';
+import { Validator } from '../validation/validator.js';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { readdirSync } from 'fs';
+export async function preApplyHook(options) {
+    const output = await runPreApplyHook(options.change || '');
+    if (options.json) {
+        console.log(JSON.stringify(output));
+    }
+    else if (output.systemMessage) {
+        if (output.continue) {
+            console.log(`✓ ${output.systemMessage}`);
+        }
+        else {
+            console.error(`✗ ${output.systemMessage}`);
+        }
+    }
+    if (!output.continue) {
+        process.exit(1);
+    }
+}
+async function runPreApplyHook(changeId) {
+    if (!changeId) {
+        return {
+            continue: false,
+            stopReason: 'missing-change',
+            systemMessage: 'Pre-apply check failed: Missing --change parameter',
+        };
+    }
+    const changeDir = path.join(process.cwd(), 'zhuanspec', 'changes', changeId);
+    return await checkPreApplyConditions(changeDir);
+}
+/**
+ * Check pre-apply conditions for a change directory.
+ * This function is exported for use by other hooks (e.g., deviation-check).
+ */
+export async function checkPreApplyConditions(changeDir) {
+    const checks = {
+        proposalExists: false,
+        tasksExists: false,
+        specsExists: false,
+        validationPassed: false,
+        approved: false,
+    };
+    // Check 1: proposal.md exists
+    const proposalPath = path.join(changeDir, 'proposal.md');
+    checks.proposalExists = await FileSystemUtils.fileExists(proposalPath);
+    if (!checks.proposalExists) {
+        return {
+            continue: false,
+            stopReason: 'missing-proposal',
+            systemMessage: 'Pre-apply check failed: missing proposal.md',
+            checks,
+        };
+    }
+    // Check 2: tasks.md exists
+    const tasksPath = path.join(changeDir, 'tasks.md');
+    checks.tasksExists = await FileSystemUtils.fileExists(tasksPath);
+    if (!checks.tasksExists) {
+        return {
+            continue: false,
+            stopReason: 'missing-tasks',
+            systemMessage: 'Pre-apply check failed: missing tasks.md',
+            checks,
+        };
+    }
+    // Check 3: specs/ directory exists and non-empty
+    const specsDir = path.join(changeDir, 'specs');
+    checks.specsExists = await FileSystemUtils.directoryExists(specsDir);
+    if (!checks.specsExists) {
+        return {
+            continue: false,
+            stopReason: 'missing-specs',
+            systemMessage: 'Pre-apply check failed: missing specs directory',
+            checks,
+        };
+    }
+    // Check specs directory has content
+    try {
+        const entries = readdirSync(specsDir, { withFileTypes: true });
+        const hasContent = entries.some(e => e.isDirectory() || e.name === 'spec.md');
+        if (!hasContent) {
+            return {
+                continue: false,
+                stopReason: 'empty-specs',
+                systemMessage: 'Pre-apply check failed: specs directory is empty',
+                checks,
+            };
+        }
+    }
+    catch {
+        return {
+            continue: false,
+            stopReason: 'specs-read-error',
+            systemMessage: 'Pre-apply check failed: cannot read specs directory',
+            checks,
+        };
+    }
+    // Check 4: validate --strict passes
+    const validator = new Validator(true);
+    const report = await validator.validateChangeDeltaSpecs(changeDir);
+    checks.validationPassed = report.valid;
+    if (!checks.validationPassed) {
+        const errorCount = report.issues.filter(i => i.level === 'ERROR').length;
+        return {
+            continue: false,
+            stopReason: 'validation-failed',
+            systemMessage: `Pre-apply check failed: validate --strict has ${errorCount} errors`,
+            checks,
+        };
+    }
+    // Check 5: .approved file exists (Plan Approved gate)
+    const approvedPath = path.join(changeDir, '.approved');
+    checks.approved = await FileSystemUtils.fileExists(approvedPath);
+    if (!checks.approved) {
+        return {
+            continue: false,
+            stopReason: 'not-approved',
+            systemMessage: 'Pre-apply check failed: Plan not approved (missing .approved file)',
+            checks,
+        };
+    }
+    return {
+        continue: true,
+        systemMessage: 'Pre-apply check passed - all checks OK',
+        checks,
+    };
+}
+//# sourceMappingURL=pre-apply.js.map

package/dist/core/hooks/pre-archive.d.ts

@@ -0,0 +1,7 @@
+interface PreArchiveOptions {
+    json?: boolean;
+    change?: string;
+}
+export declare function preArchiveHook(options: PreArchiveOptions): Promise<void>;
+export {};
+//# sourceMappingURL=pre-archive.d.ts.map

package/dist/core/hooks/pre-archive.js

@@ -0,0 +1,50 @@
+import path from 'path';
+import { FileSystemUtils } from '../../utils/file-system.js';
+export async function preArchiveHook(options) {
+    const output = await runPreArchiveHook(options.change || '');
+    if (options.json) {
+        console.log(JSON.stringify(output));
+    }
+    else if (output.systemMessage) {
+        console.log(output.systemMessage);
+    }
+    if (!output.continue) {
+        process.exit(1);
+    }
+}
+async function runPreArchiveHook(changeId) {
+    if (!changeId) {
+        return { continue: false, stopReason: 'missing-change', systemMessage: 'Missing --change for pre-archive check' };
+    }
+    const changeDir = path.join(process.cwd(), 'zhuanspec', 'changes', changeId);
+    const reviewPath = path.join(changeDir, 'metrics', 'review.json');
+    const testsPath = path.join(changeDir, 'metrics', 'tests.json');
+    const reviewReportPath = path.join(changeDir, 'review-report.md');
+    if (!(await FileSystemUtils.fileExists(reviewPath)) ||
+        !(await FileSystemUtils.fileExists(testsPath)) ||
+        !(await FileSystemUtils.fileExists(reviewReportPath))) {
+        return {
+            continue: false,
+            stopReason: 'review-or-tests-missing',
+            systemMessage: 'Pre-archive check failed: missing review.json/tests.json/review-report.md',
+        };
+    }
+    const review = JSON.parse(await FileSystemUtils.readFile(reviewPath));
+    const tests = JSON.parse(await FileSystemUtils.readFile(testsPath));
+    const reviewPassed = Boolean(review.passed);
+    const testPassed = Number(tests.failed ?? 1) === 0;
+    const specConsistencyPassed = review?.checks?.specCompliance === true;
+    const critical = Number(review?.summary?.critical ?? 0);
+    if (!reviewPassed || !testPassed || critical > 0 || !specConsistencyPassed) {
+        return {
+            continue: false,
+            stopReason: 'quality-gate-failed',
+            systemMessage: `Pre-archive check failed: review=${reviewPassed}, tests=${testPassed}, specConsistency=${specConsistencyPassed}, critical=${critical}`,
+        };
+    }
+    return {
+        continue: true,
+        systemMessage: 'Pre-archive check passed',
+    };
+}
+//# sourceMappingURL=pre-archive.js.map

package/dist/core/hooks/record-progress.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 { Phase } from '../../utils/phase-utils.js';
+/**
+ * Get Beijing time (UTC+8) as ISO string format
+ * Returns format: "2026-04-19T18:35:22.934+08:00"
+ */
+export declare function getBeijingTime(): string;
+/**
+ * Get Beijing time date string for session ID and filenames
+ * Returns format: "2026-04-19T18-35-22"
+ */
+export declare function getBeijingTimeForFilename(): string;
+interface RecordProgressOptions {
+    json?: boolean;
+    file?: string;
+    tool?: string;
+    success?: string;
+}
+export declare function recordProgressHook(options: RecordProgressOptions): Promise<void>;
+/**
+ * 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 declare function initializeProgress(changeId: string, initialPhase?: Phase): Promise<void>;
+/**
+ * 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 declare function recordHookTrigger(hookName: string, hookPhase: string, success: boolean, options?: {
+    toolName?: string;
+    filePath?: string;
+    message?: string;
+    durationMs?: number;
+}): Promise<void>;
+export {};
+//# sourceMappingURL=record-progress.d.ts.map