@zhuan-ai/zhuanspec 2.6.0 → 2.8.0

package/dist/utils/git-repo-detector.js

@@ -0,0 +1,275 @@
+import { execSync } from 'child_process';
+import { readdirSync, existsSync, realpathSync } from 'fs';
+import path from 'path';
+import { select, input } from '@inquirer/prompts';
+/**
+ * Git repository detector utilities for finding git repos in a directory hierarchy
+ */
+export class GitRepoDetector {
+    /**
+     * Finds the parent git repository by traversing upward from the given directory.
+     *
+     * Uses `git rev-parse --show-toplevel` to determine the repository root.
+     * Returns null if the given directory is not inside a git repository.
+     *
+     * @param zhuanspecDir - The directory to start searching from (typically the zhuanspec directory)
+     * @returns The absolute path to the git repository root, or null if not found
+     *
+     * @example
+     * const repo = GitRepoDetector.findParentGitRepo('/path/to/project/zhuanspec');
+     * // Returns '/path/to/project' if it's a git repo, or null otherwise
+     */
+    static findParentGitRepo(zhuanspecDir) {
+        try {
+            const output = execSync('git rev-parse --show-toplevel', {
+                cwd: zhuanspecDir,
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'ignore'], // Suppress stderr to avoid console pollution
+            });
+            const repoPath = output.trim();
+            if (repoPath) {
+                // Resolve symbolic links to get the real path
+                return realpathSync(repoPath);
+            }
+            return null;
+        }
+        catch {
+            // Git command failed - directory is not inside a git repository
+            return null;
+        }
+    }
+    /**
+     * Finds all child git repositories by scanning subdirectories for .git directories.
+     *
+     * Scans the given directory and its subdirectories up to the specified depth,
+     * looking for directories that contain a `.git` subdirectory.
+     *
+     * @param zhuanspecDir - The directory to start scanning from
+     * @param maxDepth - Maximum depth to scan (default: 2)
+     * @returns Array of absolute paths to discovered git repository roots
+     *
+     * @example
+     * const repos = GitRepoDetector.findChildGitRepos('/path/to/project', 3);
+     * // Returns ['/path/to/project/subdir1', '/path/to/project/subdir2'] if they have .git
+     */
+    static findChildGitRepos(zhuanspecDir, maxDepth = 2) {
+        const discoveredRepos = [];
+        /**
+         * Recursively scans directories for .git folders
+         */
+        const scanDirectory = (dir, currentDepth) => {
+            if (currentDepth > maxDepth) {
+                return;
+            }
+            try {
+                const entries = readdirSync(dir, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (!entry.isDirectory()) {
+                        continue;
+                    }
+                    const subDirPath = path.join(dir, entry.name);
+                    // Check if this directory contains a .git folder
+                    const gitDir = path.join(subDirPath, '.git');
+                    if (existsSync(gitDir)) {
+                        // Resolve symbolic links to get the real path
+                        const realPath = realpathSync(subDirPath);
+                        discoveredRepos.push(realPath);
+                    }
+                    // Continue scanning subdirectories (depth + 1)
+                    scanDirectory(subDirPath, currentDepth + 1);
+                }
+            }
+            catch {
+                // Ignore errors when reading directories (permission issues, etc.)
+            }
+        };
+        scanDirectory(zhuanspecDir, 1);
+        return discoveredRepos;
+    }
+    /**
+     * Detects all git repositories by combining upward and downward search results.
+     *
+     * Merges the parent git repository (found by traversing upward) with any
+     * child repositories (found by scanning downward). Results are deduplicated
+     * using a Set to ensure each repository appears only once.
+     *
+     * @param zhuanspecDir - The directory to start detection from
+     * @returns Array of absolute paths to all detected git repository roots
+     *
+     * @example
+     * const allRepos = GitRepoDetector.detectAllGitRepos('/path/to/project/zhuanspec');
+     * // Returns ['/path/to/project', '/path/to/project/submodule1', ...]
+     */
+    static detectAllGitRepos(zhuanspecDir) {
+        const allRepos = new Set();
+        // Find parent repository (traverse upward)
+        const parentRepo = this.findParentGitRepo(zhuanspecDir);
+        if (parentRepo) {
+            allRepos.add(parentRepo);
+        }
+        // Find child repositories (scan downward)
+        const childRepos = this.findChildGitRepos(zhuanspecDir);
+        for (const repo of childRepos) {
+            allRepos.add(repo);
+        }
+        return Array.from(allRepos);
+    }
+    /**
+     * Merges git diff results from multiple repositories, deduplicating file paths.
+     *
+     * Takes the changed files from each repository and combines them into a single
+     * deduplicated list. File paths are normalized to be relative to their respective
+     * repository roots.
+     *
+     * @param results - Array of GitDiffResult objects from different repositories
+     * @returns Deduplicated array of file paths (relative to respective repo roots)
+     *
+     * @example
+     * const merged = GitRepoDetector.mergeGitDiffs([
+     *   { repoPath: '/repo1', changedFiles: ['src/a.ts', 'src/b.ts'] },
+     *   { repoPath: '/repo2', changedFiles: ['src/a.ts', 'src/c.ts'] }
+     * ]);
+     * // Returns ['src/a.ts', 'src/b.ts', 'src/c.ts'] (deduplicated)
+     */
+    static mergeGitDiffs(results) {
+        const allFiles = new Set();
+        for (const result of results) {
+            for (const file of result.changedFiles) {
+                // Add each file path to the Set for automatic deduplication
+                allFiles.add(file);
+            }
+        }
+        return Array.from(allFiles);
+    }
+    /**
+     * Gets the list of changed files in a single repository.
+     *
+     * Executes `git diff --name-only` to get the list of modified files.
+     * Returns relative paths based on the repository root.
+     *
+     * @param repoPath - Absolute path to the git repository root
+     * @returns GitDiffResult containing the repo path and changed files
+     *
+     * @example
+     * const diff = GitRepoDetector.getGitDiff('/path/to/repo');
+     * // Returns { repoPath: '/path/to/repo', changedFiles: ['src/file1.ts', 'src/file2.ts'] }
+     */
+    static getGitDiff(repoPath) {
+        const allFiles = new Set();
+        // Get tracked changes (staged + unstaged) against HEAD
+        try {
+            const headDiff = execSync('git diff --name-only HEAD', {
+                cwd: repoPath,
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'ignore'],
+            });
+            headDiff.split('\n')
+                .map((line) => line.trim())
+                .filter((line) => line.length > 0)
+                .map((file) => path.resolve(repoPath, file))
+                .forEach((f) => allFiles.add(f));
+        }
+        catch {
+            // HEAD may not exist (empty repo) — fall through to status
+        }
+        // Also capture untracked new files via git status --porcelain
+        try {
+            const statusOutput = execSync('git status --porcelain', {
+                cwd: repoPath,
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'ignore'],
+            });
+            statusOutput.split('\n')
+                .map((line) => line.replace(/^\s*[A-Z?]+\s+/, '').trim())
+                .filter((line) => line.length > 0)
+                .map((file) => path.resolve(repoPath, file))
+                .forEach((f) => allFiles.add(f));
+        }
+        catch {
+            // Git status failed
+        }
+        if (allFiles.size === 0) {
+            return { repoPath, changedFiles: [] };
+        }
+        return {
+            repoPath,
+            changedFiles: Array.from(allFiles),
+        };
+    }
+    /**
+     * Gets all changed files across all detected repositories.
+     *
+     * Combines detectAllGitRepos with getGitDiff and mergeGitDiffs to provide
+     * a complete picture of all changes in the repository hierarchy.
+     *
+     * @param zhuanspecDir - The directory to start detection from
+     * @returns Deduplicated array of all changed file paths across all repos
+     *
+     * @example
+     * const allChanges = GitRepoDetector.getAllChanges('/path/to/project/zhuanspec');
+     * // Returns ['src/a.ts', 'submodule/src/b.ts', ...]
+     */
+    static getAllChanges(zhuanspecDir) {
+        const allRepos = this.detectAllGitRepos(zhuanspecDir);
+        const diffResults = [];
+        for (const repo of allRepos) {
+            const diff = this.getGitDiff(repo);
+            if (diff.changedFiles.length > 0) {
+                diffResults.push(diff);
+            }
+        }
+        return this.mergeGitDiffs(diffResults);
+    }
+}
+/**
+ * Prompts user for action when no git repository is detected.
+ *
+ * Provides three options:
+ * - Manual input: Enter a repository path manually
+ * - Skip: Continue execution without git checks
+ * - Abort: Terminate the current command
+ *
+ * @returns
+ * - string: The repository path entered by user (when 'manual' is selected)
+ * - 'skip': User chose to skip git checks
+ * - null: User chose to abort the command
+ *
+ * @example
+ * const result = await promptForGitRepoOrSkip();
+ * if (result === null) {
+ *   console.log('Command aborted');
+ *   process.exit(1);
+ * } else if (result === 'skip') {
+ *   console.log('Proceeding without git checks');
+ * } else {
+ *   console.log(`Using repo: ${result}`);
+ * }
+ */
+export async function promptForGitRepoOrSkip() {
+    const action = await select({
+        message: 'No git repository detected. What would you like to do?',
+        choices: [
+            { name: 'Enter repository path manually', value: 'manual' },
+            { name: 'Skip git checks and continue', value: 'skip' },
+            { name: 'Abort command', value: 'abort' },
+        ],
+    });
+    if (action === 'abort') {
+        return null;
+    }
+    if (action === 'skip') {
+        return 'skip';
+    }
+    // action === 'manual': prompt for repository path
+    const repoPath = await input({
+        message: 'Enter the git repository path:',
+        validate: (value) => {
+            if (!value.trim()) {
+                return 'Repository path cannot be empty';
+            }
+            return true;
+        },
+    });
+    return repoPath.trim();
+}
+//# sourceMappingURL=git-repo-detector.js.map

package/dist/utils/index.d.ts

@@ -1,4 +1,6 @@
 export { validateChangeName, createChange } from './change-utils.js';
 export type { ValidationResult, CreateChangeOptions } from './change-utils.js';
 export { readChangeMetadata, writeChangeMetadata, resolveSchemaForChange, validateSchemaName, ChangeMetadataError, } from './change-metadata.js';
+export { GitRepoDetector } from './git-repo-detector.js';
+export type { GitDiffResult } from './git-repo-detector.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.js

@@ -2,4 +2,6 @@
 export { validateChangeName, createChange } from './change-utils.js';
 // Change metadata utilities
 export { readChangeMetadata, writeChangeMetadata, resolveSchemaForChange, validateSchemaName, ChangeMetadataError, } from './change-metadata.js';
+// Git repository detection utilities
+export { GitRepoDetector } from './git-repo-detector.js';
 //# sourceMappingURL=index.js.map

package/dist/utils/phase-utils.d.ts

@@ -3,7 +3,7 @@
  *
  * Provides:
  * - Phase type definition
- * - setPhase: Write phase to progress.json
+ * - setPhase: Write phase to progress.json (with data preservation)
  * - getPhaseFromProgress: Read phase from progress.json
  * - getCurrentPhase: Comprehensive phase detection
  */
@@ -11,8 +11,8 @@ export type Phase = 'idle' | 'techDesign' | 'propose' | 'apply' | 'review' | 'ar
 export declare const PHASE_ORDER: Phase[];
 export declare const PHASE_MARKERS: Partial<Record<Phase, string>>;
 /**
- * Set phase in progress.json
- * Creates or updates progress.json with the new phase value
+ * Set phase in progress.json with full data preservation
+ * Uses three-layer recovery strategy to prevent data loss
  */
 export declare function setPhase(changeDir: string, phase: Phase): Promise<void>;
 /**

package/dist/utils/phase-utils.js

@@ -3,12 +3,13 @@
  *
  * Provides:
  * - Phase type definition
- * - setPhase: Write phase to progress.json
+ * - setPhase: Write phase to progress.json (with data preservation)
  * - getPhaseFromProgress: Read phase from progress.json
  * - getCurrentPhase: Comprehensive phase detection
  */
 import path from 'path';
 import { FileSystemUtils } from './file-system.js';
+import { recoverProgressJsonForWrite, getBeijingTime, atomicWriteJson, } from '../core/hooks/record-progress.js';
 export const PHASE_ORDER = ['idle', 'techDesign', 'propose', 'apply', 'review', 'archive'];
 export const PHASE_MARKERS = {
     techDesign: '.tech-design',
@@ -16,28 +17,150 @@ export const PHASE_MARKERS = {
     review: 'review-report.md',
 };
 /**
- * Set phase in progress.json
- * Creates or updates progress.json with the new phase value
+ * Set phase in progress.json with full data preservation
+ * Uses three-layer recovery strategy to prevent data loss
  */
 export async function setPhase(changeDir, phase) {
     const metricsDir = path.join(changeDir, 'metrics');
     await FileSystemUtils.createDirectory(metricsDir);
     const progressPath = path.join(metricsDir, 'progress.json');
+    const timestamp = getBeijingTime();
     let progress;
+    // Use three-layer recovery strategy to preserve all data
     if (await FileSystemUtils.fileExists(progressPath)) {
-        try {
-            progress = JSON.parse(await FileSystemUtils.readFile(progressPath));
+        const recovered = await recoverProgressJsonForWrite(progressPath);
+        if (recovered) {
+            progress = recovered;
+            // Fill missing arrays/objects with defaults
+            progress.toolCalls = progress.toolCalls || [];
+            progress.skillCalls = progress.skillCalls || [];
+            progress.hookTriggers = progress.hookTriggers || [];
+            progress.clarifications = progress.clarifications || [];
+            progress.filesModified = progress.filesModified || [];
+            progress.completedTasks = progress.completedTasks || [];
+            progress.deviationRecords = progress.deviationRecords || [];
+            progress.phaseTransitions = progress.phaseTransitions || [];
+            progress.phaseDurations = progress.phaseDurations || [];
+            progress.reviewStats = progress.reviewStats || {
+                loopCount: 0,
+                criticalFixes: 0,
+                testFixes: 0,
+                consistencyFixes: 0,
+            };
+            progress.stats = progress.stats || {
+                tokenUsageTotal: 0,
+                contextLoad: 0,
+                durationMs: { propose: 0, apply: 0, review: 0, archive: 0 },
+            };
         }
-        catch {
-            progress = { phase };
+        else {
+            // Recovery failed - create minimal valid structure instead of empty object
+            progress = {
+                changeId: path.basename(changeDir),
+                sessionId: '',
+                startedAt: timestamp,
+                lastUpdatedAt: timestamp,
+                phase,
+                currentNode: phase,
+                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: [],
+                phaseDurations: [{
+                        phase,
+                        startedAt: timestamp,
+                        durationMs: 0,
+                        taskCount: 0,
+                        completedTaskCount: 0,
+                    }],
+                stats: { tokenUsageTotal: 0, contextLoad: 0, durationMs: { propose: 0, apply: 0, review: 0, archive: 0 } },
+            };
         }
     }
     else {
-        progress = { phase };
+        // No existing file - create new structure
+        progress = {
+            changeId: path.basename(changeDir),
+            sessionId: '',
+            startedAt: timestamp,
+            lastUpdatedAt: timestamp,
+            phase,
+            currentNode: phase,
+            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: [],
+            phaseDurations: [{
+                    phase,
+                    startedAt: timestamp,
+                    durationMs: 0,
+                    taskCount: 0,
+                    completedTaskCount: 0,
+                }],
+            stats: { tokenUsageTotal: 0, contextLoad: 0, durationMs: { propose: 0, apply: 0, review: 0, archive: 0 } },
+        };
+    }
+    // Record phase transition
+    const previousPhase = progress.phase;
+    // Ensure phaseDurations has at least one entry for current phase
+    if (progress.phaseDurations.length === 0) {
+        progress.phaseDurations.push({
+            phase,
+            startedAt: timestamp,
+            durationMs: 0,
+            taskCount: 0,
+            completedTaskCount: 0,
+        });
+    }
+    if (previousPhase !== phase) {
+        progress.phaseTransitions.push({
+            from: previousPhase,
+            to: phase,
+            timestamp,
+            triggeredBy: 'setPhase',
+        });
+        // Update phaseDurations: fill endedAt for previous phase
+        const prevPhaseDuration = progress.phaseDurations.find(pd => pd.phase === previousPhase && !pd.endedAt);
+        if (prevPhaseDuration) {
+            prevPhaseDuration.endedAt = timestamp;
+            const startTime = new Date(prevPhaseDuration.startedAt).getTime();
+            const endTime = new Date(timestamp).getTime();
+            prevPhaseDuration.durationMs = endTime > startTime ? endTime - startTime : 0;
+        }
+        // Add new phase duration record
+        progress.phaseDurations.push({
+            phase,
+            startedAt: timestamp,
+            durationMs: 0,
+            taskCount: 0,
+            completedTaskCount: 0,
+        });
     }
     progress.phase = phase;
-    progress.lastUpdatedAt = new Date().toISOString();
-    await FileSystemUtils.writeFile(progressPath, JSON.stringify(progress, null, 2));
+    progress.currentNode = phase;
+    progress.lastUpdatedAt = timestamp;
+    // Use atomic write to prevent corruption
+    await atomicWriteJson(progressPath, progress);
 }
 /**
  * Get phase from progress.json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuan-ai/zhuanspec",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "zhuanspec",