@zhuan-ai/zhuanspec 1.3.0

package/dist/commands/change.d.ts

@@ -0,0 +1,35 @@
+export declare class ChangeCommand {
+    private converter;
+    constructor();
+    /**
+     * Show a change proposal.
+     * - Text mode: raw markdown passthrough (no filters)
+     * - JSON mode: minimal object with deltas; --deltas-only returns same object with filtered deltas
+     *   Note: --requirements-only is deprecated alias for --deltas-only
+     */
+    show(changeName?: string, options?: {
+        json?: boolean;
+        requirementsOnly?: boolean;
+        deltasOnly?: boolean;
+        noInteractive?: boolean;
+    }): Promise<void>;
+    /**
+     * List active changes.
+     * - Text default: IDs only; --long prints minimal details (title, counts)
+     * - JSON: array of { id, title, deltaCount, taskStatus }, sorted by id
+     */
+    list(options?: {
+        json?: boolean;
+        long?: boolean;
+    }): Promise<void>;
+    validate(changeName?: string, options?: {
+        strict?: boolean;
+        json?: boolean;
+        noInteractive?: boolean;
+    }): Promise<void>;
+    private getActiveChanges;
+    private extractTitle;
+    private countTasks;
+    private printNextSteps;
+}
+//# sourceMappingURL=change.d.ts.map

package/dist/commands/change.js

@@ -0,0 +1,277 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { JsonConverter } from '../core/converters/json-converter.js';
+import { Validator } from '../core/validation/validator.js';
+import { ChangeParser } from '../core/parsers/change-parser.js';
+import { isInteractive } from '../utils/interactive.js';
+import { getActiveChangeIds } from '../utils/item-discovery.js';
+// Constants for better maintainability
+const ARCHIVE_DIR = 'archive';
+const TASK_PATTERN = /^[-*]\s+\[[\sx]\]/i;
+const COMPLETED_TASK_PATTERN = /^[-*]\s+\[x\]/i;
+export class ChangeCommand {
+    converter;
+    constructor() {
+        this.converter = new JsonConverter();
+    }
+    /**
+     * Show a change proposal.
+     * - Text mode: raw markdown passthrough (no filters)
+     * - JSON mode: minimal object with deltas; --deltas-only returns same object with filtered deltas
+     *   Note: --requirements-only is deprecated alias for --deltas-only
+     */
+    async show(changeName, options) {
+        const changesPath = path.join(process.cwd(), 'zhuanspec', 'changes');
+        if (!changeName) {
+            const canPrompt = isInteractive(options);
+            const changes = await this.getActiveChanges(changesPath);
+            if (canPrompt && changes.length > 0) {
+                const { select } = await import('@inquirer/prompts');
+                const selected = await select({
+                    message: 'Select a change to show',
+                    choices: changes.map(id => ({ name: id, value: id })),
+                });
+                changeName = selected;
+            }
+            else {
+                if (changes.length === 0) {
+                    console.error('No change specified. No active changes found.');
+                }
+                else {
+                    console.error(`No change specified. Available IDs: ${changes.join(', ')}`);
+                }
+                console.error('Hint: use "zhuanspec change list" to view available changes.');
+                process.exitCode = 1;
+                return;
+            }
+        }
+        const proposalPath = path.join(changesPath, changeName, 'proposal.md');
+        try {
+            await fs.access(proposalPath);
+        }
+        catch {
+            throw new Error(`Change "${changeName}" not found at ${proposalPath}`);
+        }
+        if (options?.json) {
+            const jsonOutput = await this.converter.convertChangeToJson(proposalPath);
+            if (options.requirementsOnly) {
+                console.error('Flag --requirements-only is deprecated; use --deltas-only instead.');
+            }
+            const parsed = JSON.parse(jsonOutput);
+            const contentForTitle = await fs.readFile(proposalPath, 'utf-8');
+            const title = this.extractTitle(contentForTitle, changeName);
+            const id = parsed.name;
+            const deltas = parsed.deltas || [];
+            if (options.requirementsOnly || options.deltasOnly) {
+                const output = { id, title, deltaCount: deltas.length, deltas };
+                console.log(JSON.stringify(output, null, 2));
+            }
+            else {
+                const output = {
+                    id,
+                    title,
+                    deltaCount: deltas.length,
+                    deltas,
+                };
+                console.log(JSON.stringify(output, null, 2));
+            }
+        }
+        else {
+            const content = await fs.readFile(proposalPath, 'utf-8');
+            console.log(content);
+        }
+    }
+    /**
+     * List active changes.
+     * - Text default: IDs only; --long prints minimal details (title, counts)
+     * - JSON: array of { id, title, deltaCount, taskStatus }, sorted by id
+     */
+    async list(options) {
+        const changesPath = path.join(process.cwd(), 'zhuanspec', 'changes');
+        const changes = await this.getActiveChanges(changesPath);
+        if (options?.json) {
+            const changeDetails = await Promise.all(changes.map(async (changeName) => {
+                const proposalPath = path.join(changesPath, changeName, 'proposal.md');
+                const tasksPath = path.join(changesPath, changeName, 'tasks.md');
+                try {
+                    const content = await fs.readFile(proposalPath, 'utf-8');
+                    const changeDir = path.join(changesPath, changeName);
+                    const parser = new ChangeParser(content, changeDir);
+                    const change = await parser.parseChangeWithDeltas(changeName);
+                    let taskStatus = { total: 0, completed: 0 };
+                    try {
+                        const tasksContent = await fs.readFile(tasksPath, 'utf-8');
+                        taskStatus = this.countTasks(tasksContent);
+                    }
+                    catch (error) {
+                        // Tasks file may not exist, which is okay
+                        if (process.env.DEBUG) {
+                            console.error(`Failed to read tasks file at ${tasksPath}:`, error);
+                        }
+                    }
+                    return {
+                        id: changeName,
+                        title: this.extractTitle(content, changeName),
+                        deltaCount: change.deltas.length,
+                        taskStatus,
+                    };
+                }
+                catch (error) {
+                    return {
+                        id: changeName,
+                        title: 'Unknown',
+                        deltaCount: 0,
+                        taskStatus: { total: 0, completed: 0 },
+                    };
+                }
+            }));
+            const sorted = changeDetails.sort((a, b) => a.id.localeCompare(b.id));
+            console.log(JSON.stringify(sorted, null, 2));
+        }
+        else {
+            if (changes.length === 0) {
+                console.log('No items found');
+                return;
+            }
+            const sorted = [...changes].sort();
+            if (!options?.long) {
+                // IDs only
+                sorted.forEach(id => console.log(id));
+                return;
+            }
+            // Long format: id: title and minimal counts
+            for (const changeName of sorted) {
+                const proposalPath = path.join(changesPath, changeName, 'proposal.md');
+                const tasksPath = path.join(changesPath, changeName, 'tasks.md');
+                try {
+                    const content = await fs.readFile(proposalPath, 'utf-8');
+                    const title = this.extractTitle(content, changeName);
+                    let taskStatusText = '';
+                    try {
+                        const tasksContent = await fs.readFile(tasksPath, 'utf-8');
+                        const { total, completed } = this.countTasks(tasksContent);
+                        taskStatusText = ` [tasks ${completed}/${total}]`;
+                    }
+                    catch (error) {
+                        if (process.env.DEBUG) {
+                            console.error(`Failed to read tasks file at ${tasksPath}:`, error);
+                        }
+                    }
+                    const changeDir = path.join(changesPath, changeName);
+                    const parser = new ChangeParser(await fs.readFile(proposalPath, 'utf-8'), changeDir);
+                    const change = await parser.parseChangeWithDeltas(changeName);
+                    const deltaCountText = ` [deltas ${change.deltas.length}]`;
+                    console.log(`${changeName}: ${title}${deltaCountText}${taskStatusText}`);
+                }
+                catch {
+                    console.log(`${changeName}: (unable to read)`);
+                }
+            }
+        }
+    }
+    async validate(changeName, options) {
+        const changesPath = path.join(process.cwd(), 'zhuanspec', 'changes');
+        if (!changeName) {
+            const canPrompt = isInteractive(options);
+            const changes = await getActiveChangeIds();
+            if (canPrompt && changes.length > 0) {
+                const { select } = await import('@inquirer/prompts');
+                const selected = await select({
+                    message: 'Select a change to validate',
+                    choices: changes.map(id => ({ name: id, value: id })),
+                });
+                changeName = selected;
+            }
+            else {
+                if (changes.length === 0) {
+                    console.error('No change specified. No active changes found.');
+                }
+                else {
+                    console.error(`No change specified. Available IDs: ${changes.join(', ')}`);
+                }
+                console.error('Hint: use "zhuanspec change list" to view available changes.');
+                process.exitCode = 1;
+                return;
+            }
+        }
+        const changeDir = path.join(changesPath, changeName);
+        try {
+            await fs.access(changeDir);
+        }
+        catch {
+            throw new Error(`Change "${changeName}" not found at ${changeDir}`);
+        }
+        const validator = new Validator(options?.strict || false);
+        const report = await validator.validateChangeDeltaSpecs(changeDir);
+        if (options?.json) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else {
+            if (report.valid) {
+                console.log(`Change "${changeName}" is valid`);
+            }
+            else {
+                console.error(`Change "${changeName}" has issues`);
+                report.issues.forEach(issue => {
+                    const label = issue.level === 'ERROR' ? 'ERROR' : 'WARNING';
+                    const prefix = issue.level === 'ERROR' ? '✗' : '⚠';
+                    console.error(`${prefix} [${label}] ${issue.path}: ${issue.message}`);
+                });
+                // Next steps footer to guide fixing issues
+                this.printNextSteps();
+                if (!options?.json) {
+                    process.exitCode = 1;
+                }
+            }
+        }
+    }
+    async getActiveChanges(changesPath) {
+        try {
+            const entries = await fs.readdir(changesPath, { withFileTypes: true });
+            const result = [];
+            for (const entry of entries) {
+                if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === ARCHIVE_DIR)
+                    continue;
+                const proposalPath = path.join(changesPath, entry.name, 'proposal.md');
+                try {
+                    await fs.access(proposalPath);
+                    result.push(entry.name);
+                }
+                catch {
+                    // skip directories without proposal.md
+                }
+            }
+            return result.sort();
+        }
+        catch {
+            return [];
+        }
+    }
+    extractTitle(content, changeName) {
+        const match = content.match(/^#\s+(?:Change:\s+)?(.+)$/im);
+        return match ? match[1].trim() : changeName;
+    }
+    countTasks(content) {
+        const lines = content.split('\n');
+        let total = 0;
+        let completed = 0;
+        for (const line of lines) {
+            if (line.match(TASK_PATTERN)) {
+                total++;
+                if (line.match(COMPLETED_TASK_PATTERN)) {
+                    completed++;
+                }
+            }
+        }
+        return { total, completed };
+    }
+    printNextSteps() {
+        const bullets = [];
+        bullets.push('- Ensure change has deltas in specs/: use headers ## ADDED/MODIFIED/REMOVED/RENAMED Requirements');
+        bullets.push('- Each requirement MUST include at least one #### Scenario: block');
+        bullets.push('- Debug parsed deltas: zhuanspec change show <id> --json --deltas-only');
+        console.error('Next steps:');
+        bullets.forEach(b => console.error(`  ${b}`));
+    }
+}
+//# sourceMappingURL=change.js.map

package/dist/commands/completion.d.ts

@@ -0,0 +1,72 @@
+interface GenerateOptions {
+    shell?: string;
+}
+interface InstallOptions {
+    shell?: string;
+    verbose?: boolean;
+}
+interface UninstallOptions {
+    shell?: string;
+    yes?: boolean;
+}
+interface CompleteOptions {
+    type: string;
+}
+/**
+ * Command for managing shell completions for ZhuanSpec CLI
+ */
+export declare class CompletionCommand {
+    private completionProvider;
+    constructor();
+    /**
+     * Resolve shell parameter or exit with error
+     *
+     * @param shell - The shell parameter (may be undefined)
+     * @param operationName - Name of the operation (for error messages)
+     * @returns Resolved shell or null if should exit
+     */
+    private resolveShellOrExit;
+    /**
+     * Generate completion script and output to stdout
+     *
+     * @param options - Options for generation (shell type)
+     */
+    generate(options?: GenerateOptions): Promise<void>;
+    /**
+     * Install completion script to the appropriate location
+     *
+     * @param options - Options for installation (shell type, verbose output)
+     */
+    install(options?: InstallOptions): Promise<void>;
+    /**
+     * Uninstall completion script from the installation location
+     *
+     * @param options - Options for uninstallation (shell type, yes flag)
+     */
+    uninstall(options?: UninstallOptions): Promise<void>;
+    /**
+     * Generate completion script for a specific shell
+     */
+    private generateForShell;
+    /**
+     * Install completion script for a specific shell
+     */
+    private installForShell;
+    /**
+     * Uninstall completion script for a specific shell
+     */
+    private uninstallForShell;
+    /**
+     * Output machine-readable completion data for shell consumption
+     * Format: tab-separated "id\tdescription" per line
+     *
+     * @param options - Options specifying completion type
+     */
+    complete(options: CompleteOptions): Promise<void>;
+    /**
+     * Normalize shell parameter to lowercase
+     */
+    private normalizeShell;
+}
+export {};
+//# sourceMappingURL=completion.d.ts.map

package/dist/commands/completion.js

@@ -0,0 +1,221 @@
+import ora from 'ora';
+import { CompletionFactory } from '../core/completions/factory.js';
+import { COMMAND_REGISTRY } from '../core/completions/command-registry.js';
+import { detectShell } from '../utils/shell-detection.js';
+import { CompletionProvider } from '../core/completions/completion-provider.js';
+import { getArchivedChangeIds } from '../utils/item-discovery.js';
+/**
+ * Command for managing shell completions for ZhuanSpec CLI
+ */
+export class CompletionCommand {
+    completionProvider;
+    constructor() {
+        this.completionProvider = new CompletionProvider();
+    }
+    /**
+     * Resolve shell parameter or exit with error
+     *
+     * @param shell - The shell parameter (may be undefined)
+     * @param operationName - Name of the operation (for error messages)
+     * @returns Resolved shell or null if should exit
+     */
+    resolveShellOrExit(shell, operationName) {
+        const normalizedShell = this.normalizeShell(shell);
+        if (!normalizedShell) {
+            const detectionResult = detectShell();
+            if (detectionResult.shell && CompletionFactory.isSupported(detectionResult.shell)) {
+                return detectionResult.shell;
+            }
+            // Shell was detected but not supported
+            if (detectionResult.detected && !detectionResult.shell) {
+                console.error(`Error: Shell '${detectionResult.detected}' is not supported yet. Currently supported: ${CompletionFactory.getSupportedShells().join(', ')}`);
+                process.exitCode = 1;
+                return null;
+            }
+            // No shell specified and cannot auto-detect
+            console.error('Error: Could not auto-detect shell. Please specify shell explicitly.');
+            console.error(`Usage: zhuanspec completion ${operationName} [shell]`);
+            console.error(`Currently supported: ${CompletionFactory.getSupportedShells().join(', ')}`);
+            process.exitCode = 1;
+            return null;
+        }
+        if (!CompletionFactory.isSupported(normalizedShell)) {
+            console.error(`Error: Shell '${normalizedShell}' is not supported yet. Currently supported: ${CompletionFactory.getSupportedShells().join(', ')}`);
+            process.exitCode = 1;
+            return null;
+        }
+        return normalizedShell;
+    }
+    /**
+     * Generate completion script and output to stdout
+     *
+     * @param options - Options for generation (shell type)
+     */
+    async generate(options = {}) {
+        const shell = this.resolveShellOrExit(options.shell, 'generate');
+        if (!shell)
+            return;
+        await this.generateForShell(shell);
+    }
+    /**
+     * Install completion script to the appropriate location
+     *
+     * @param options - Options for installation (shell type, verbose output)
+     */
+    async install(options = {}) {
+        const shell = this.resolveShellOrExit(options.shell, 'install');
+        if (!shell)
+            return;
+        await this.installForShell(shell, options.verbose || false);
+    }
+    /**
+     * Uninstall completion script from the installation location
+     *
+     * @param options - Options for uninstallation (shell type, yes flag)
+     */
+    async uninstall(options = {}) {
+        const shell = this.resolveShellOrExit(options.shell, 'uninstall');
+        if (!shell)
+            return;
+        await this.uninstallForShell(shell, options.yes || false);
+    }
+    /**
+     * Generate completion script for a specific shell
+     */
+    async generateForShell(shell) {
+        const generator = CompletionFactory.createGenerator(shell);
+        const script = generator.generate(COMMAND_REGISTRY);
+        console.log(script);
+    }
+    /**
+     * Install completion script for a specific shell
+     */
+    async installForShell(shell, verbose) {
+        const generator = CompletionFactory.createGenerator(shell);
+        const installer = CompletionFactory.createInstaller(shell);
+        const spinner = ora(`Installing ${shell} completion script...`).start();
+        try {
+            // Generate the completion script
+            const script = generator.generate(COMMAND_REGISTRY);
+            // Install it
+            const result = await installer.install(script);
+            spinner.stop();
+            if (result.success) {
+                console.log(`✓ ${result.message}`);
+                if (verbose && result.installedPath) {
+                    console.log(`  Installed to: ${result.installedPath}`);
+                    if (result.backupPath) {
+                        console.log(`  Backup created: ${result.backupPath}`);
+                    }
+                    if (result.zshrcConfigured) {
+                        console.log(`  ~/.zshrc configured automatically`);
+                    }
+                }
+                // Print instructions (only shown if .zshrc wasn't auto-configured)
+                if (result.instructions && result.instructions.length > 0) {
+                    console.log('');
+                    for (const instruction of result.instructions) {
+                        console.log(instruction);
+                    }
+                }
+                else if (result.zshrcConfigured) {
+                    console.log('');
+                    console.log('Restart your shell or run: exec zsh');
+                }
+            }
+            else {
+                console.error(`✗ ${result.message}`);
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            spinner.stop();
+            console.error(`✗ Failed to install completion script: ${error instanceof Error ? error.message : String(error)}`);
+            process.exitCode = 1;
+        }
+    }
+    /**
+     * Uninstall completion script for a specific shell
+     */
+    async uninstallForShell(shell, skipConfirmation) {
+        const installer = CompletionFactory.createInstaller(shell);
+        // Prompt for confirmation unless --yes flag is provided
+        if (!skipConfirmation) {
+            const { confirm } = await import('@inquirer/prompts');
+            const confirmed = await confirm({
+                message: 'Remove ZhuanSpec configuration from ~/.zshrc?',
+                default: false,
+            });
+            if (!confirmed) {
+                console.log('Uninstall cancelled.');
+                return;
+            }
+        }
+        const spinner = ora(`Uninstalling ${shell} completion script...`).start();
+        try {
+            const result = await installer.uninstall();
+            spinner.stop();
+            if (result.success) {
+                console.log(`✓ ${result.message}`);
+            }
+            else {
+                console.error(`✗ ${result.message}`);
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            spinner.stop();
+            console.error(`✗ Failed to uninstall completion script: ${error instanceof Error ? error.message : String(error)}`);
+            process.exitCode = 1;
+        }
+    }
+    /**
+     * Output machine-readable completion data for shell consumption
+     * Format: tab-separated "id\tdescription" per line
+     *
+     * @param options - Options specifying completion type
+     */
+    async complete(options) {
+        const type = options.type.toLowerCase();
+        try {
+            switch (type) {
+                case 'changes': {
+                    const changeIds = await this.completionProvider.getChangeIds();
+                    for (const id of changeIds) {
+                        console.log(`${id}\tactive change`);
+                    }
+                    break;
+                }
+                case 'specs': {
+                    const specIds = await this.completionProvider.getSpecIds();
+                    for (const id of specIds) {
+                        console.log(`${id}\tspecification`);
+                    }
+                    break;
+                }
+                case 'archived-changes': {
+                    const archivedIds = await getArchivedChangeIds();
+                    for (const id of archivedIds) {
+                        console.log(`${id}\tarchived change`);
+                    }
+                    break;
+                }
+                default:
+                    // Invalid type - silently exit with no output for graceful shell completion failure
+                    process.exitCode = 1;
+                    break;
+            }
+        }
+        catch {
+            // Silently fail for graceful shell completion experience
+            process.exitCode = 1;
+        }
+    }
+    /**
+     * Normalize shell parameter to lowercase
+     */
+    normalizeShell(shell) {
+        return shell?.toLowerCase();
+    }
+}
+//# sourceMappingURL=completion.js.map

package/dist/commands/config.d.ts

@@ -0,0 +1,8 @@
+import { Command } from 'commander';
+/**
+ * Register the config command and all its subcommands.
+ *
+ * @param program - The Commander program instance
+ */
+export declare function registerConfigCommand(program: Command): void;
+//# sourceMappingURL=config.d.ts.map