@zhuan-ai/zhuanspec 1.3.0

package/dist/core/archive.js

@@ -0,0 +1,438 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { getTaskProgressForChange, formatTaskStatus } from '../utils/task-progress.js';
+import { Validator } from './validation/validator.js';
+import chalk from 'chalk';
+import { findSpecUpdates, buildUpdatedSpec, writeUpdatedSpec, } from './specs-apply.js';
+export class ArchiveCommand {
+    async execute(changeName, options = {}) {
+        const targetPath = '.';
+        const changesDir = path.join(targetPath, 'zhuanspec', 'changes');
+        const archiveDir = path.join(changesDir, 'archive');
+        const mainSpecsDir = path.join(targetPath, 'zhuanspec', 'specs');
+        // Check if changes directory exists
+        try {
+            await fs.access(changesDir);
+        }
+        catch {
+            throw new Error("未找到 ZhuanSpec 变更目录。请先运行 'zhuanspec init'。");
+        }
+        // Get change name interactively if not provided
+        if (!changeName) {
+            const selectedChange = await this.selectChange(changesDir);
+            if (!selectedChange) {
+                console.log('未选择变更。已中止。');
+                return;
+            }
+            changeName = selectedChange;
+        }
+        const changeDir = path.join(changesDir, changeName);
+        // Verify change exists
+        try {
+            const stat = await fs.stat(changeDir);
+            if (!stat.isDirectory()) {
+                throw new Error(`Change '${changeName}' not found.`);
+            }
+        }
+        catch {
+            throw new Error(`Change '${changeName}' not found.`);
+        }
+        const skipValidation = options.validate === false || options.noValidate === true;
+        // Validate specs and change before archiving
+        if (!skipValidation) {
+            const validator = new Validator();
+            let hasValidationErrors = false;
+            // Validate proposal.md (non-blocking unless strict mode desired in future)
+            const changeFile = path.join(changeDir, 'proposal.md');
+            try {
+                await fs.access(changeFile);
+                const changeReport = await validator.validateChange(changeFile);
+                // Proposal validation is informative only (do not block archive)
+                if (!changeReport.valid) {
+                    console.log(chalk.yellow(`\nproposal.md 中的提案警告（非阻塞）：`));
+                    for (const issue of changeReport.issues) {
+                        const symbol = issue.level === 'ERROR' ? '⚠' : (issue.level === 'WARNING' ? '⚠' : 'ℹ');
+                        console.log(chalk.yellow(`  ${symbol} ${issue.message}`));
+                    }
+                }
+            }
+            catch {
+                // Change file doesn't exist, skip validation
+            }
+            // Validate delta-formatted spec files under the change directory if present
+            const changeSpecsDir = path.join(changeDir, 'specs');
+            let hasDeltaSpecs = false;
+            try {
+                const candidates = await fs.readdir(changeSpecsDir, { withFileTypes: true });
+                for (const c of candidates) {
+                    if (c.isDirectory()) {
+                        try {
+                            const candidatePath = path.join(changeSpecsDir, c.name, 'spec.md');
+                            await fs.access(candidatePath);
+                            const content = await fs.readFile(candidatePath, 'utf-8');
+                            if (/^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements/m.test(content)) {
+                                hasDeltaSpecs = true;
+                                break;
+                            }
+                        }
+                        catch { }
+                    }
+                }
+            }
+            catch { }
+            if (hasDeltaSpecs) {
+                const deltaReport = await validator.validateChangeDeltaSpecs(changeDir);
+                if (!deltaReport.valid) {
+                    hasValidationErrors = true;
+                    console.log(chalk.red(`\n变更增量规范中的验证错误：`));
+                    for (const issue of deltaReport.issues) {
+                        if (issue.level === 'ERROR') {
+                            console.log(chalk.red(`  ✗ ${issue.message}`));
+                        }
+                        else if (issue.level === 'WARNING') {
+                            console.log(chalk.yellow(`  ⚠ ${issue.message}`));
+                        }
+                    }
+                }
+            }
+            if (hasValidationErrors) {
+                console.log(chalk.red('\n验证失败。请在归档之前修复错误。'));
+                console.log(chalk.yellow('要跳过验证（不推荐），请使用 --no-validate 标志。'));
+                return;
+            }
+        }
+        else {
+            // Log warning when validation is skipped
+            const timestamp = new Date().toISOString();
+            if (!options.yes) {
+                const { confirm } = await import('@inquirer/prompts');
+                const proceed = await confirm({
+                    message: chalk.yellow('⚠️  警告：跳过验证可能会归档无效的规范。继续？(y/N)'),
+                    default: false
+                });
+                if (!proceed) {
+                    console.log('归档已取消。');
+                    return;
+                }
+            }
+            else {
+                console.log(chalk.yellow(`\n⚠️  警告：跳过验证可能会归档无效的规范。`));
+            }
+            console.log(chalk.yellow(`[${timestamp}] 已跳过变更的验证：${changeName}`));
+            console.log(chalk.yellow(`受影响的文件：${changeDir}`));
+        }
+        // Show progress and check for incomplete tasks
+        const progress = await getTaskProgressForChange(changesDir, changeName);
+        const status = formatTaskStatus(progress);
+        console.log(`任务状态：${status}`);
+        const incompleteTasks = Math.max(progress.total - progress.completed, 0);
+        if (incompleteTasks > 0) {
+            if (!options.yes) {
+                const { confirm } = await import('@inquirer/prompts');
+                const proceed = await confirm({
+                    message: `警告：发现 ${incompleteTasks} 个未完成的任务。继续？`,
+                    default: false
+                });
+                if (!proceed) {
+                    console.log('归档已取消。');
+                    return;
+                }
+            }
+            else {
+                console.log(`警告：发现 ${incompleteTasks} 个未完成的任务。由于 --yes 标志，继续执行。`);
+            }
+        }
+        // Handle spec updates unless skipSpecs flag is set
+        if (options.skipSpecs) {
+            console.log('跳过规范更新（已提供 --skip-specs 标志）。');
+        }
+        else {
+            // Find specs to update
+            const specUpdates = await findSpecUpdates(changeDir, mainSpecsDir);
+            if (specUpdates.length > 0) {
+                console.log('\n要更新的规范：');
+                for (const update of specUpdates) {
+                    const status = update.exists ? 'update' : 'create';
+                    const capability = path.basename(path.dirname(update.target));
+                    console.log(`  ${capability}: ${status}`);
+                }
+                let shouldUpdateSpecs = true;
+                if (!options.yes) {
+                    const { confirm } = await import('@inquirer/prompts');
+                    shouldUpdateSpecs = await confirm({
+                        message: '继续更新规范？',
+                        default: true
+                    });
+                    if (!shouldUpdateSpecs) {
+                        console.log('跳过规范更新。继续归档。');
+                    }
+                }
+                if (shouldUpdateSpecs) {
+                    // Prepare all updates first (validation pass, no writes)
+                    const prepared = [];
+                    try {
+                        for (const update of specUpdates) {
+                            const built = await buildUpdatedSpec(update, changeName);
+                            prepared.push({ update, rebuilt: built.rebuilt, counts: built.counts });
+                        }
+                    }
+                    catch (err) {
+                        console.log(String(err.message || err));
+                        console.log('已中止。未更改任何文件。');
+                        return;
+                    }
+                    // All validations passed; pre-validate rebuilt full spec and then write files and display counts
+                    let totals = { added: 0, modified: 0, removed: 0, renamed: 0 };
+                    for (const p of prepared) {
+                        const specName = path.basename(path.dirname(p.update.target));
+                        if (!skipValidation) {
+                            const report = await new Validator().validateSpecContent(specName, p.rebuilt);
+                            if (!report.valid) {
+                                console.log(chalk.red(`\n重建的规范 ${specName} 中的验证错误（不会写入更改）：`));
+                                for (const issue of report.issues) {
+                                    if (issue.level === 'ERROR')
+                                        console.log(chalk.red(`  ✗ ${issue.message}`));
+                                    else if (issue.level === 'WARNING')
+                                        console.log(chalk.yellow(`  ⚠ ${issue.message}`));
+                                }
+                                console.log('已中止。未更改任何文件。');
+                                return;
+                            }
+                        }
+                        await writeUpdatedSpec(p.update, p.rebuilt, p.counts);
+                        totals.added += p.counts.added;
+                        totals.modified += p.counts.modified;
+                        totals.removed += p.counts.removed;
+                        totals.renamed += p.counts.renamed;
+                    }
+                    console.log(`总计：+ ${totals.added}，~ ${totals.modified}，- ${totals.removed}，→ ${totals.renamed}`);
+                    console.log('规范更新成功。');
+                }
+            }
+        }
+        // Create archive directory with date prefix
+        const archiveName = `${this.getArchiveDate()}-${changeName}`;
+        const archivePath = path.join(archiveDir, archiveName);
+        // Check if archive already exists
+        try {
+            await fs.access(archivePath);
+            throw new Error(`归档 '${archiveName}' 已存在。`);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+        // Create archive directory if needed
+        await fs.mkdir(archiveDir, { recursive: true });
+        // Move change to archive (with cross-device fallback)
+        await this.moveDirectory(changeDir, archivePath);
+        console.log(`变更 '${changeName}' 已归档为 '${archiveName}'。`);
+    }
+    /**
+     * Move a directory, falling back to copy+remove when rename fails
+     * (e.g., across devices, network drives, or permission issues).
+     */
+    async moveDirectory(src, dest) {
+        try {
+            await fs.rename(src, dest);
+        }
+        catch (error) {
+            // EXDEV: cross-device link, EPERM: operation not permitted
+            if (error.code === 'EXDEV' || error.code === 'EPERM') {
+                console.log(chalk.yellow('rename 失败，回退到 copy+remove...'));
+                await this.copyDirectoryRecursive(src, dest);
+                await fs.rm(src, { recursive: true, force: true });
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    /**
+     * Recursively copy a directory.
+     */
+    async copyDirectoryRecursive(src, dest) {
+        await fs.mkdir(dest, { recursive: true });
+        const entries = await fs.readdir(src, { withFileTypes: true });
+        for (const entry of entries) {
+            const srcPath = path.join(src, entry.name);
+            const destPath = path.join(dest, entry.name);
+            if (entry.isDirectory()) {
+                await this.copyDirectoryRecursive(srcPath, destPath);
+            }
+            else {
+                await fs.copyFile(srcPath, destPath);
+            }
+        }
+    }
+    async selectChange(changesDir) {
+        const { select } = await import('@inquirer/prompts');
+        // Get all directories in changes (excluding archive)
+        const entries = await fs.readdir(changesDir, { withFileTypes: true });
+        const changeDirs = entries
+            .filter(entry => entry.isDirectory() && entry.name !== 'archive')
+            .map(entry => entry.name)
+            .sort();
+        if (changeDirs.length === 0) {
+            console.log('未找到活动变更。');
+            return null;
+        }
+        // Build choices with progress inline to avoid duplicate lists
+        let choices = changeDirs.map(name => ({ name, value: name }));
+        try {
+            const progressList = [];
+            for (const id of changeDirs) {
+                const progress = await getTaskProgressForChange(changesDir, id);
+                const status = formatTaskStatus(progress);
+                progressList.push({ id, status });
+            }
+            const nameWidth = Math.max(...progressList.map(p => p.id.length));
+            choices = progressList.map(p => ({
+                name: `${p.id.padEnd(nameWidth)}     ${p.status}`,
+                value: p.id
+            }));
+        }
+        catch {
+            // If anything fails, fall back to simple names
+            choices = changeDirs.map(name => ({ name, value: name }));
+        }
+        try {
+            const answer = await select({
+                message: '选择要归档的变更',
+                choices
+            });
+            return answer;
+        }
+        catch (error) {
+            // User cancelled (Ctrl+C)
+            return null;
+        }
+    }
+    getArchiveDate() {
+        // Returns date in YYYY-MM-DD format
+        return new Date().toISOString().split('T')[0];
+    }
+    /**
+     * Bulk archive multiple completed changes at once.
+     * Lists all active changes, lets user select multiple, then archives them sequentially.
+     */
+    async bulkArchive(options = {}) {
+        const targetPath = '.';
+        const changesDir = path.join(targetPath, 'zhuanspec', 'changes');
+        // Check if changes directory exists
+        try {
+            await fs.access(changesDir);
+        }
+        catch {
+            throw new Error("未找到 ZhuanSpec 变更目录。请先运行 'zhuanspec init'。");
+        }
+        // Get all active changes
+        const entries = await fs.readdir(changesDir, { withFileTypes: true });
+        const changeDirs = entries
+            .filter(entry => entry.isDirectory() && entry.name !== 'archive')
+            .map(entry => entry.name)
+            .sort();
+        if (changeDirs.length === 0) {
+            console.log('未找到活动变更。');
+            return;
+        }
+        // Build choices with progress
+        let choices = changeDirs.map(name => ({ name, value: name }));
+        try {
+            const progressList = [];
+            for (const id of changeDirs) {
+                const progress = await getTaskProgressForChange(changesDir, id);
+                const status = formatTaskStatus(progress);
+                progressList.push({ id, status });
+            }
+            const nameWidth = Math.max(...progressList.map(p => p.id.length));
+            choices = progressList.map(p => ({
+                name: `${p.id.padEnd(nameWidth)}     ${p.status}`,
+                value: p.id
+            }));
+        }
+        catch {
+            choices = changeDirs.map(name => ({ name, value: name }));
+        }
+        // Let user select multiple changes
+        let selectedChanges;
+        if (options.yes) {
+            // With --yes, archive all active changes
+            selectedChanges = changeDirs;
+            console.log(`将归档所有 ${changeDirs.length} 个活动变更：${changeDirs.join(', ')}`);
+        }
+        else {
+            const { checkbox } = await import('@inquirer/prompts');
+            selectedChanges = await checkbox({
+                message: '选择要归档的变更（空格选择，回车确认）',
+                choices: choices.map(c => ({ name: c.name, value: c.value })),
+            });
+        }
+        if (selectedChanges.length === 0) {
+            console.log('未选择任何变更。已中止。');
+            return;
+        }
+        // Check for overlapping specs (conflict detection)
+        const specCapabilities = new Map();
+        for (const changeName of selectedChanges) {
+            const changeDir = path.join(changesDir, changeName);
+            const changeSpecsDir = path.join(changeDir, 'specs');
+            try {
+                const specEntries = await fs.readdir(changeSpecsDir, { withFileTypes: true });
+                const capabilities = specEntries
+                    .filter(e => e.isDirectory())
+                    .map(e => e.name);
+                for (const cap of capabilities) {
+                    if (!specCapabilities.has(cap)) {
+                        specCapabilities.set(cap, []);
+                    }
+                    specCapabilities.get(cap).push(changeName);
+                }
+            }
+            catch {
+                // No specs dir, skip
+            }
+        }
+        // Warn about conflicts
+        const conflicts = Array.from(specCapabilities.entries())
+            .filter(([, changes]) => changes.length > 1);
+        if (conflicts.length > 0) {
+            console.log(chalk.yellow('\n⚠️  检测到规范冲突 - 以下功能被多个变更修改：'));
+            for (const [cap, changes] of conflicts) {
+                console.log(chalk.yellow(`  ${cap}: ${changes.join(', ')}`));
+            }
+            if (!options.yes) {
+                const { confirm } = await import('@inquirer/prompts');
+                const proceed = await confirm({
+                    message: '存在规范冲突。继续按选择顺序归档？（后归档的会覆盖先归档的规范）',
+                    default: false
+                });
+                if (!proceed) {
+                    console.log('批量归档已取消。');
+                    return;
+                }
+            }
+            else {
+                console.log(chalk.yellow('由于 --yes 标志，按顺序继续归档。'));
+            }
+        }
+        // Archive each change sequentially
+        let successCount = 0;
+        let failCount = 0;
+        for (const changeName of selectedChanges) {
+            console.log(chalk.cyan(`\n━━━ 归档: ${changeName} ━━━`));
+            try {
+                await this.execute(changeName, options);
+                successCount++;
+            }
+            catch (error) {
+                failCount++;
+                console.log(chalk.red(`归档 '${changeName}' 失败: ${error.message}`));
+            }
+        }
+        console.log(chalk.cyan(`\n━━━ 批量归档完成 ━━━`));
+        console.log(`成功: ${successCount}, 失败: ${failCount}, 总计: ${selectedChanges.length}`);
+    }
+}
+//# sourceMappingURL=archive.js.map

package/dist/core/artifact-graph/graph.d.ts

@@ -0,0 +1,56 @@
+import type { Artifact, SchemaYaml, CompletedSet, BlockedArtifacts } from './types.js';
+/**
+ * Represents an artifact dependency graph.
+ * Provides methods for querying build order, ready artifacts, and completion status.
+ */
+export declare class ArtifactGraph {
+    private artifacts;
+    private schema;
+    private constructor();
+    /**
+     * Creates an ArtifactGraph from a YAML file path.
+     */
+    static fromYaml(filePath: string): ArtifactGraph;
+    /**
+     * Creates an ArtifactGraph from YAML content string.
+     */
+    static fromYamlContent(yamlContent: string): ArtifactGraph;
+    /**
+     * Creates an ArtifactGraph from a pre-validated schema object.
+     */
+    static fromSchema(schema: SchemaYaml): ArtifactGraph;
+    /**
+     * Gets a single artifact by ID.
+     */
+    getArtifact(id: string): Artifact | undefined;
+    /**
+     * Gets all artifacts in the graph.
+     */
+    getAllArtifacts(): Artifact[];
+    /**
+     * Gets the schema name.
+     */
+    getName(): string;
+    /**
+     * Gets the schema version.
+     */
+    getVersion(): number;
+    /**
+     * Computes the topological build order using Kahn's algorithm.
+     * Returns artifact IDs in the order they should be built.
+     */
+    getBuildOrder(): string[];
+    /**
+     * Gets artifacts that are ready to be created (all dependencies completed).
+     */
+    getNextArtifacts(completed: CompletedSet): string[];
+    /**
+     * Checks if all artifacts in the graph are completed.
+     */
+    isComplete(completed: CompletedSet): boolean;
+    /**
+     * Gets blocked artifacts and their unmet dependencies.
+     */
+    getBlocked(completed: CompletedSet): BlockedArtifacts;
+}
+//# sourceMappingURL=graph.d.ts.map

package/dist/core/artifact-graph/graph.js

@@ -0,0 +1,141 @@
+import { loadSchema, parseSchema } from './schema.js';
+/**
+ * Represents an artifact dependency graph.
+ * Provides methods for querying build order, ready artifacts, and completion status.
+ */
+export class ArtifactGraph {
+    artifacts;
+    schema;
+    constructor(schema) {
+        this.schema = schema;
+        this.artifacts = new Map(schema.artifacts.map(a => [a.id, a]));
+    }
+    /**
+     * Creates an ArtifactGraph from a YAML file path.
+     */
+    static fromYaml(filePath) {
+        const schema = loadSchema(filePath);
+        return new ArtifactGraph(schema);
+    }
+    /**
+     * Creates an ArtifactGraph from YAML content string.
+     */
+    static fromYamlContent(yamlContent) {
+        const schema = parseSchema(yamlContent);
+        return new ArtifactGraph(schema);
+    }
+    /**
+     * Creates an ArtifactGraph from a pre-validated schema object.
+     */
+    static fromSchema(schema) {
+        return new ArtifactGraph(schema);
+    }
+    /**
+     * Gets a single artifact by ID.
+     */
+    getArtifact(id) {
+        return this.artifacts.get(id);
+    }
+    /**
+     * Gets all artifacts in the graph.
+     */
+    getAllArtifacts() {
+        return Array.from(this.artifacts.values());
+    }
+    /**
+     * Gets the schema name.
+     */
+    getName() {
+        return this.schema.name;
+    }
+    /**
+     * Gets the schema version.
+     */
+    getVersion() {
+        return this.schema.version;
+    }
+    /**
+     * Computes the topological build order using Kahn's algorithm.
+     * Returns artifact IDs in the order they should be built.
+     */
+    getBuildOrder() {
+        const inDegree = new Map();
+        const dependents = new Map();
+        // Initialize all artifacts
+        for (const artifact of this.artifacts.values()) {
+            inDegree.set(artifact.id, artifact.requires.length);
+            dependents.set(artifact.id, []);
+        }
+        // Build reverse adjacency (who depends on whom)
+        for (const artifact of this.artifacts.values()) {
+            for (const req of artifact.requires) {
+                dependents.get(req).push(artifact.id);
+            }
+        }
+        // Start with roots (in-degree 0), sorted for determinism
+        const queue = [...this.artifacts.keys()]
+            .filter(id => inDegree.get(id) === 0)
+            .sort();
+        const result = [];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            result.push(current);
+            // Collect newly ready artifacts, then sort before adding
+            const newlyReady = [];
+            for (const dep of dependents.get(current)) {
+                const newDegree = inDegree.get(dep) - 1;
+                inDegree.set(dep, newDegree);
+                if (newDegree === 0) {
+                    newlyReady.push(dep);
+                }
+            }
+            queue.push(...newlyReady.sort());
+        }
+        return result;
+    }
+    /**
+     * Gets artifacts that are ready to be created (all dependencies completed).
+     */
+    getNextArtifacts(completed) {
+        const ready = [];
+        for (const artifact of this.artifacts.values()) {
+            if (completed.has(artifact.id)) {
+                continue; // Already completed
+            }
+            const allDepsCompleted = artifact.requires.every(req => completed.has(req));
+            if (allDepsCompleted) {
+                ready.push(artifact.id);
+            }
+        }
+        // Sort for deterministic ordering
+        return ready.sort();
+    }
+    /**
+     * Checks if all artifacts in the graph are completed.
+     */
+    isComplete(completed) {
+        for (const artifact of this.artifacts.values()) {
+            if (!completed.has(artifact.id)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Gets blocked artifacts and their unmet dependencies.
+     */
+    getBlocked(completed) {
+        const blocked = {};
+        for (const artifact of this.artifacts.values()) {
+            if (completed.has(artifact.id)) {
+                continue; // Already completed
+            }
+            const unmetDeps = artifact.requires.filter(req => !completed.has(req));
+            if (unmetDeps.length > 0) {
+                blocked[artifact.id] = unmetDeps.sort();
+            }
+        }
+        return blocked;
+    }
+}
+//# sourceMappingURL=graph.js.map

package/dist/core/artifact-graph/index.d.ts

@@ -0,0 +1,7 @@
+export { ArtifactSchema, SchemaYamlSchema, type Artifact, type SchemaYaml, type CompletedSet, type BlockedArtifacts, } from './types.js';
+export { loadSchema, parseSchema, SchemaValidationError } from './schema.js';
+export { ArtifactGraph } from './graph.js';
+export { detectCompleted } from './state.js';
+export { resolveSchema, listSchemas, listSchemasWithInfo, getSchemaDir, getPackageSchemasDir, getUserSchemasDir, SchemaLoadError, type SchemaInfo, } from './resolver.js';
+export { loadTemplate, loadChangeContext, generateInstructions, formatChangeStatus, TemplateLoadError, type ChangeContext, type ArtifactInstructions, type DependencyInfo, type ArtifactStatus, type ChangeStatus, } from './instruction-loader.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/artifact-graph/index.js

@@ -0,0 +1,13 @@
+// Types
+export { ArtifactSchema, SchemaYamlSchema, } from './types.js';
+// Schema loading and validation
+export { loadSchema, parseSchema, SchemaValidationError } from './schema.js';
+// Graph operations
+export { ArtifactGraph } from './graph.js';
+// State detection
+export { detectCompleted } from './state.js';
+// Schema resolution
+export { resolveSchema, listSchemas, listSchemasWithInfo, getSchemaDir, getPackageSchemasDir, getUserSchemasDir, SchemaLoadError, } from './resolver.js';
+// Instruction loading
+export { loadTemplate, loadChangeContext, generateInstructions, formatChangeStatus, TemplateLoadError, } from './instruction-loader.js';
+//# sourceMappingURL=index.js.map