@zhuan-ai/zhuanspec 2.4.8 → 2.6.0

package/dist/core/init.js

@@ -821,7 +821,7 @@ export class InitCommand {
     syncBusinessClaudeAssets(projectPath) {
         const fallbackResult = {
             claudeMd: { source: 'none', status: 'missing' },
-            dotClaude: { source: 'none', status: 'missing' },
+            dotClaude: { source: 'none', files: { added: [], overwritten: [], skipped: [] } },
         };
         if (!this.businessDirection) {
             return fallbackResult;
@@ -839,13 +839,11 @@ export class InitCommand {
                 : null;
             const commonClaudeMd = path.join(commonClaudeRoot, 'CLAUDE.md');
             const resolvedClaudeMdSource = this.resolveClaudeAssetSource(businessClaudeMd, commonClaudeMd);
-            const businessDotClaude = businessRoot
-                ? path.join(businessRoot, '.claude')
-                : null;
+            // .claude directory: always from common directory (not business-specific)
             const commonDotClaude = path.join(commonClaudeRoot, '.claude');
             return {
                 claudeMd: this.copyClaudeFileIfNeeded(resolvedClaudeMdSource, path.join(projectPath, 'CLAUDE.md')),
-                dotClaude: this.copyClaudeDirectoryWithFallback(businessDotClaude, commonDotClaude, path.join(projectPath, '.claude')),
+                dotClaude: this.copyClaudeDirectoryFromCommon(commonDotClaude, path.join(projectPath, '.claude')),
             };
         }
         catch {
@@ -949,15 +947,27 @@ export class InitCommand {
         if (!sourceAsset) {
             return { source: 'none', status: 'missing' };
         }
+        const targetExists = existsSync(targetPath);
+        if (targetExists) {
+            const sourceContent = readFileSync(sourceAsset.path);
+            const targetContent = readFileSync(targetPath);
+            if (Buffer.compare(sourceContent, targetContent) === 0) {
+                return { source: sourceAsset.source, status: 'skipped-unchanged' };
+            }
+        }
         cpSync(sourceAsset.path, targetPath, { force: true });
-        return { source: sourceAsset.source, status: 'copied' };
+        return { source: sourceAsset.source, status: targetExists ? 'overwritten' : 'copied' };
     }
     copyClaudeDirectoryIfNeeded(sourceAsset, targetPath) {
+        const emptyResult = {
+            source: 'none',
+            files: { added: [], overwritten: [], skipped: [] },
+        };
         if (!sourceAsset) {
-            return { source: 'none', status: 'missing' };
+            return emptyResult;
         }
         if (!existsSync(sourceAsset.path)) {
-            return { source: sourceAsset.source, status: 'missing' };
+            return { source: sourceAsset.source, files: { added: [], overwritten: [], skipped: [] } };
         }
         const repoRoot = this.findGitRootForPath(sourceAsset.path);
         if (!repoRoot) {
@@ -973,26 +983,25 @@ export class InitCommand {
             path.isAbsolute(relativeSourceDir)) {
             return this.copyClaudeDirectoryByFileSystem(sourceAsset, targetPath);
         }
-        const targetAlreadyExisted = existsSync(targetPath);
-        const copiedAny = this.copyGitTrackedDirectoryFiles(canonicalRepoRoot, relativeSourceDir, targetPath);
-        if (!copiedAny) {
-            return { source: sourceAsset.source, status: 'missing' };
+        const filesResult = this.copyGitTrackedDirectoryFiles(canonicalRepoRoot, relativeSourceDir, targetPath);
+        const totalFiles = filesResult.added.length + filesResult.overwritten.length + filesResult.skipped.length;
+        if (totalFiles === 0) {
+            return { source: sourceAsset.source, files: { added: [], overwritten: [], skipped: [] } };
         }
         return {
             source: sourceAsset.source,
-            status: targetAlreadyExisted ? 'kept-existing' : 'copied',
+            files: filesResult,
         };
     }
-    copyClaudeDirectoryWithFallback(businessSourcePath, commonSourcePath, targetPath) {
-        const fromBusiness = this.copyClaudeDirectoryFromSingleSource(businessSourcePath, 'business', targetPath);
-        if (fromBusiness) {
-            return fromBusiness;
-        }
+    /**
+     * Copy .claude directory from common source (unified source, no fallback).
+     */
+    copyClaudeDirectoryFromCommon(commonSourcePath, targetPath) {
         const fromCommon = this.copyClaudeDirectoryFromSingleSource(commonSourcePath, 'common', targetPath);
         if (fromCommon) {
             return fromCommon;
         }
-        return { source: 'none', status: 'missing' };
+        return { source: 'none', files: { added: [], overwritten: [], skipped: [] } };
     }
     copyClaudeDirectoryFromSingleSource(sourcePath, sourceLabel, targetPath) {
         if (!sourcePath || !existsSync(sourcePath)) {
@@ -1025,11 +1034,42 @@ export class InitCommand {
         return false;
     }
     copyClaudeDirectoryByFileSystem(sourceAsset, targetPath) {
-        if (existsSync(targetPath)) {
-            rmSync(targetPath, { recursive: true, force: true });
-        }
-        cpSync(sourceAsset.path, targetPath, { recursive: true, force: true });
-        return { source: sourceAsset.source, status: 'copied' };
+        const result = {
+            added: [],
+            overwritten: [],
+            skipped: [],
+        };
+        const syncDir = (srcDir, dstDir, relBase) => {
+            mkdirSync(dstDir, { recursive: true });
+            const entries = readdirSync(srcDir, { withFileTypes: true });
+            for (const entry of entries) {
+                const srcPath = path.join(srcDir, entry.name);
+                const dstPath = path.join(dstDir, entry.name);
+                const relPath = relBase ? `${relBase}/${entry.name}` : entry.name;
+                if (entry.isDirectory()) {
+                    syncDir(srcPath, dstPath, relPath);
+                }
+                else {
+                    const sourceContent = readFileSync(srcPath);
+                    if (existsSync(dstPath)) {
+                        const targetContent = readFileSync(dstPath);
+                        if (Buffer.compare(sourceContent, targetContent) === 0) {
+                            result.skipped.push(relPath);
+                        }
+                        else {
+                            writeFileSync(dstPath, sourceContent);
+                            result.overwritten.push(relPath);
+                        }
+                    }
+                    else {
+                        writeFileSync(dstPath, sourceContent);
+                        result.added.push(relPath);
+                    }
+                }
+            }
+        };
+        syncDir(sourceAsset.path, targetPath, '');
+        return { source: sourceAsset.source, files: result };
     }
     findGitRootForPath(sourcePath) {
         try {
@@ -1053,6 +1093,11 @@ export class InitCommand {
         }
     }
     copyGitTrackedDirectoryFiles(gitRoot, sourceDirRelativeToGitRoot, targetDir) {
+        const result = {
+            added: [],
+            overwritten: [],
+            skipped: [],
+        };
         try {
             const sourcePrefix = sourceDirRelativeToGitRoot.endsWith('/')
                 ? sourceDirRelativeToGitRoot
@@ -1067,40 +1112,81 @@ export class InitCommand {
                 .map((line) => line.trim())
                 .filter((line) => line.length > 0);
             if (trackedFiles.length === 0) {
-                return false;
-            }
-            if (existsSync(targetDir)) {
-                rmSync(targetDir, { recursive: true, force: true });
+                return result;
             }
+            // 确保目标目录存在，但不删除已有内容
             mkdirSync(targetDir, { recursive: true });
             trackedFiles.forEach((repoFilePath) => {
                 const relativePath = repoFilePath.startsWith(sourcePrefix)
                     ? repoFilePath.slice(sourcePrefix.length)
                     : path.basename(repoFilePath);
                 const targetFilePath = path.join(targetDir, relativePath);
+                // 确保目标文件的父目录存在
                 mkdirSync(path.dirname(targetFilePath), { recursive: true });
-                const content = execSync(`git show HEAD:${repoFilePath}`, {
+                // 获取源文件内容
+                const sourceContent = execSync(`git show HEAD:${repoFilePath}`, {
                     encoding: 'buffer',
                     stdio: ['pipe', 'pipe', 'ignore'],
                     cwd: gitRoot,
                 });
-                writeFileSync(targetFilePath, content);
+                // 检查目标文件是否存在
+                if (existsSync(targetFilePath)) {
+                    // 比较内容是否相同
+                    const targetContent = readFileSync(targetFilePath);
+                    if (Buffer.compare(sourceContent, targetContent) === 0) {
+                        // 内容相同，跳过
+                        result.skipped.push(relativePath);
+                    }
+                    else {
+                        // 内容不同，覆盖
+                        writeFileSync(targetFilePath, sourceContent);
+                        result.overwritten.push(relativePath);
+                    }
+                }
+                else {
+                    // 文件不存在，新增
+                    writeFileSync(targetFilePath, sourceContent);
+                    result.added.push(relativePath);
+                }
             });
-            return true;
+            return result;
         }
         catch {
-            return false;
+            return result;
         }
     }
     describeClaudeAssetResult(assetName, result) {
-        if (result.status === 'missing') {
+        if (result.source === 'none') {
             return `${assetName} 未找到可用模板`;
         }
         const sourceText = result.source === 'business' ? '业务目录' : 'common/claude';
-        if (result.status === 'kept-existing') {
-            return `${assetName} 使用${sourceText}模板，目标已存在未覆盖`;
+        if (assetName === 'CLAUDE.md') {
+            const fileResult = result;
+            if (fileResult.status === 'missing') {
+                return `${assetName} 未找到可用模板`;
+            }
+            const statusText = fileResult.status === 'overwritten' ? '已覆盖' : '已复制';
+            return `${assetName} 已从${sourceText}模板${statusText}`;
+        }
+        // .claude 目录（统一从 common 获取）
+        const dirResult = result;
+        const { added, overwritten, skipped } = dirResult.files;
+        const total = added.length + overwritten.length + skipped.length;
+        if (total === 0) {
+            return `${assetName} 无文件需同步`;
+        }
+        const parts = [];
+        if (added.length > 0) {
+            parts.push(`新增 ${added.length} 个`);
+        }
+        if (overwritten.length > 0) {
+            parts.push(`覆盖 ${overwritten.length} 个`);
+        }
+        if (skipped.length > 0) {
+            parts.push(`跳过 ${skipped.length} 个`);
         }
-        return `${assetName} 已从${sourceText}模板复制`;
+        // .claude 目录统一从 common/claude 获取，sourceText 固定为 'common/claude'
+        return `${assetName} 已从 common/claude 模板同步：${parts.join('、')}`;
     }
     async writeTemplateFiles(zhuanspecPath, config, skipExisting) {
         const context = {};

package/dist/core/task-graph/execution-planner.d.ts

@@ -5,6 +5,12 @@
  * Uses a layer-by-layer approach: each wave contains tasks with in-degree 0.
  */
 import type { ParsedTask, ExecutionPlan } from './types.js';
+/**
+ * Detect file conflicts among tasks in the same wave.
+ * Returns a map of file path -> list of task IDs that modify it.
+ * Only entries with 2+ task IDs indicate actual conflicts.
+ */
+export declare function detectFileConflicts(tasks: ParsedTask[]): Map<string, string[]>;
 /**
  * Generates an execution plan from parsed tasks.
  *

package/dist/core/task-graph/execution-planner.js

@@ -5,6 +5,23 @@
  * Uses a layer-by-layer approach: each wave contains tasks with in-degree 0.
  */
 import { TaskGraph } from './task-graph.js';
+/**
+ * Detect file conflicts among tasks in the same wave.
+ * Returns a map of file path -> list of task IDs that modify it.
+ * Only entries with 2+ task IDs indicate actual conflicts.
+ */
+export function detectFileConflicts(tasks) {
+    const fileToTasks = new Map();
+    for (const task of tasks) {
+        for (const file of (task.files ?? [])) {
+            if (!fileToTasks.has(file)) {
+                fileToTasks.set(file, []);
+            }
+            fileToTasks.get(file).push(task.id);
+        }
+    }
+    return fileToTasks;
+}
 /**
  * Generates an execution plan from parsed tasks.
  *
@@ -24,6 +41,7 @@ export function generateExecutionPlan(tasks) {
             parallelTasks: 0,
             serialTasks: 0,
             hasCycle: false,
+            fileConflicts: [],
             errors: [],
         };
     }
@@ -38,6 +56,7 @@ export function generateExecutionPlan(tasks) {
             parallelTasks: 0,
             serialTasks: 0,
             hasCycle: true,
+            fileConflicts: [],
             errors: validation.errors,
         };
     }
@@ -96,10 +115,76 @@ export function generateExecutionPlan(tasks) {
             }
         }
     }
+    // Redistribute file conflicts across waves
+    // For each wave, detect tasks that share files and split them into subsequent waves
+    const fileConflicts = [];
+    let waveIdx = 0;
+    while (waveIdx < waves.length) {
+        const currentWave = waves[waveIdx];
+        const conflictMap = detectFileConflicts(currentWave.tasks);
+        // Collect tasks that need to be moved out of this wave
+        // Key: task ID, Value: how many waves forward to push it
+        const taskShift = new Map();
+        for (const [file, taskIds] of conflictMap) {
+            if (taskIds.length < 2)
+                continue;
+            // Sort by task ID (ascending) — first stays, rest get pushed forward
+            const sorted = [...taskIds].sort();
+            // Record conflict info (deduplicate by file)
+            if (!fileConflicts.some(fc => fc.file === file)) {
+                fileConflicts.push({ file, taskIds: sorted });
+            }
+            for (let i = 1; i < sorted.length; i++) {
+                const id = sorted[i];
+                // Push at least i waves forward; take the max if already scheduled to move
+                const existing = taskShift.get(id) ?? 0;
+                if (i > existing) {
+                    taskShift.set(id, i);
+                }
+            }
+        }
+        if (taskShift.size > 0) {
+            // Remove conflicting tasks from current wave
+            const tasksToKeep = currentWave.tasks.filter(t => !taskShift.has(t.id));
+            const tasksToMove = currentWave.tasks.filter(t => taskShift.has(t.id));
+            currentWave.tasks = tasksToKeep;
+            currentWave.parallel = tasksToKeep.length > 1;
+            // Insert moved tasks into target waves (wave+shift)
+            for (const task of tasksToMove) {
+                const shift = taskShift.get(task.id);
+                const targetIdx = waveIdx + shift;
+                if (targetIdx < waves.length) {
+                    // Insert into existing wave (maintain task ID sort order)
+                    waves[targetIdx].tasks.push(task);
+                    waves[targetIdx].tasks.sort((a, b) => a.id.localeCompare(b.id));
+                }
+                else {
+                    // Need to create new intermediate waves to fill the gap
+                    while (waves.length <= targetIdx) {
+                        waves.push({
+                            wave: waves.length + 1, // temporary, renumbered below
+                            tasks: [],
+                            parallel: false,
+                        });
+                    }
+                    waves[targetIdx].tasks.push(task);
+                    waves[targetIdx].tasks.sort((a, b) => a.id.localeCompare(b.id));
+                }
+            }
+        }
+        waveIdx++;
+    }
+    // Remove any empty waves that may have been left behind
+    const nonEmptyWaves = waves.filter(w => w.tasks.length > 0);
+    // Renumber waves sequentially from 1 and recalculate parallel flag
+    for (let i = 0; i < nonEmptyWaves.length; i++) {
+        nonEmptyWaves[i].wave = i + 1;
+        nonEmptyWaves[i].parallel = nonEmptyWaves[i].tasks.length > 1;
+    }
     // Calculate statistics
     let parallelTasks = 0;
     let serialTasks = 0;
-    for (const wave of waves) {
+    for (const wave of nonEmptyWaves) {
         if (wave.parallel) {
             parallelTasks += wave.tasks.length;
         }
@@ -108,12 +193,13 @@ export function generateExecutionPlan(tasks) {
         }
     }
     return {
-        waves,
+        waves: nonEmptyWaves,
         totalTasks: incompleteTasks.length,
         parallelTasks,
         serialTasks,
         hasCycle: false,
         errors,
+        fileConflicts,
     };
 }
 //# sourceMappingURL=execution-planner.js.map

package/dist/core/task-graph/task-parser.d.ts

@@ -4,6 +4,19 @@
  * Parses tasks.md content into structured ParsedTask array.
  */
 import type { ParsedTask } from './types.js';
+/**
+ * Extract file paths from a task description.
+ *
+ * Handles three formats:
+ * 1. Backtick code blocks: `src/core/foo.ts`, `com/example/Foo.java`
+ * 2. Bare paths with known prefixes: src/xxx/yyy.ts, components/Foo.vue,
+ *    com/example/service/FooService.java (Java package paths)
+ * 3. Quoted paths: "src/core/foo.ts" or 'com/example/Foo.java'
+ *
+ * @param description - Task description text
+ * @returns Deduplicated array of file paths
+ */
+export declare function extractFilePaths(description: string): string[];
 /**
  * Parse tasks.md content into an array of ParsedTask objects.
  *

package/dist/core/task-graph/task-parser.js

@@ -61,6 +61,62 @@ function cleanDescription(text) {
         .trim();
     return cleaned;
 }
+// File path extraction patterns
+// Backtick code blocks: `path/to/File.java` or `src/core/foo.ts`
+const CODE_BLOCK_REGEX = /`([^`]+\.[a-zA-Z]+)`/g;
+// Bare paths with common directory prefixes (language-agnostic):
+// - TypeScript/JS: src/, components/, pages/, views/, hooks/, utils/, lib/, app/
+// - Java: src/main/java/, src/test/java/, com/, org/, net/ (package paths)
+// - Relative: ./, ../
+const PATH_REGEX = /(?:(?:src|components?|pages?|views?|hooks?|utils?|lib|app|test|tests|spec|specs)\/|\.\.?\/|(?:[a-z][a-z0-9]*\.)+(?:[a-z][a-z0-9]*\/))[a-zA-Z0-9_\-/.]+\.[a-zA-Z]+/g;
+// Quoted paths: "path/to/File.java" or 'src/core/foo.ts'
+const QUOTED_PATH_REGEX = /["']([^"'\s]+\/[^"'\s]+\.[a-zA-Z]+)["']/g;
+/**
+ * Extract file paths from a task description.
+ *
+ * Handles three formats:
+ * 1. Backtick code blocks: `src/core/foo.ts`, `com/example/Foo.java`
+ * 2. Bare paths with known prefixes: src/xxx/yyy.ts, components/Foo.vue,
+ *    com/example/service/FooService.java (Java package paths)
+ * 3. Quoted paths: "src/core/foo.ts" or 'com/example/Foo.java'
+ *
+ * @param description - Task description text
+ * @returns Deduplicated array of file paths
+ */
+export function extractFilePaths(description) {
+    const paths = [];
+    // 1. Backtick code blocks
+    let match;
+    const codeBlockRegex = new RegExp(CODE_BLOCK_REGEX.source, 'g');
+    while ((match = codeBlockRegex.exec(description)) !== null) {
+        paths.push(match[1]);
+    }
+    // 2. Bare path format
+    const pathRegex = new RegExp(PATH_REGEX.source, 'g');
+    while ((match = pathRegex.exec(description)) !== null) {
+        paths.push(match[0]);
+    }
+    // 3. Quoted paths
+    const quotedPathRegex = new RegExp(QUOTED_PATH_REGEX.source, 'g');
+    while ((match = quotedPathRegex.exec(description)) !== null) {
+        paths.push(match[1]);
+    }
+    return [...new Set(paths)].filter(p => {
+        // Ignore node_modules paths
+        if (p.includes('node_modules'))
+            return false;
+        // Must have a file extension
+        if (!/\.[a-zA-Z]+$/.test(p))
+            return false;
+        // Ignore pure numeric paths like "1.1" or "2.3"
+        if (/^\d+\.\d+$/.test(p))
+            return false;
+        // Must contain at least one slash (actual path, not just a filename)
+        if (!p.includes('/'))
+            return false;
+        return true;
+    });
+}
 /**
  * Parse tasks.md content into an array of ParsedTask objects.
  *
@@ -102,6 +158,7 @@ export function parseTasks(content) {
                 description,
                 skills,
                 depends,
+                files: extractFilePaths(description),
                 completed: checkboxState.toLowerCase() === 'x',
             });
         }

package/dist/core/task-graph/types.d.ts

@@ -19,6 +19,8 @@ export interface ParsedTask {
     skills: string[];
     /** Task IDs this task depends on, e.g., ["1.1", "2.1"] */
     depends: string[];
+    /** File paths involved in this task, e.g., ["src/core/foo.ts", "src/utils/bar.ts"] */
+    files: string[];
     /** Whether the task is completed (checkbox state [x] vs [ ]) */
     completed: boolean;
 }
@@ -33,6 +35,15 @@ export interface ExecutionWave {
     /** Whether tasks can run in parallel (tasks.length > 1) */
     parallel: boolean;
 }
+/**
+ * Represents a file conflict between tasks in the same wave
+ */
+export interface FileConflict {
+    /** File path that has conflicting tasks */
+    file: string;
+    /** Task IDs that modify this file in the same wave */
+    taskIds: string[];
+}
 /**
  * Represents the complete execution plan
  */
@@ -47,6 +58,8 @@ export interface ExecutionPlan {
     serialTasks: number;
     /** Whether there is a cycle in the dependency graph */
     hasCycle: boolean;
+    /** File conflicts detected and resolved by wave reassignment */
+    fileConflicts: FileConflict[];
     /** Validation errors */
     errors: string[];
 }