@dynamicworks/br-openspec 1.3.1

package/dist/commands/change.js

@@ -0,0 +1,278 @@
+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';
+import { CHANGE_MESSAGES, UTILS_MESSAGES } from '../messages/index.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(), 'openspec', '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: CHANGE_MESSAGES.selectChangeToShow,
+                    choices: changes.map(id => ({ name: id, value: id })),
+                });
+                changeName = selected;
+            }
+            else {
+                if (changes.length === 0) {
+                    console.error(CHANGE_MESSAGES.noChangeSpecifiedNoActive);
+                }
+                else {
+                    console.error(CHANGE_MESSAGES.noChangeSpecifiedAvailable(changes.join(', ')));
+                }
+                console.error(CHANGE_MESSAGES.hintViewChanges);
+                process.exitCode = 1;
+                return;
+            }
+        }
+        const proposalPath = path.join(changesPath, changeName, 'proposal.md');
+        try {
+            await fs.access(proposalPath);
+        }
+        catch {
+            throw new Error(CHANGE_MESSAGES.changeNotFound(changeName, proposalPath));
+        }
+        if (options?.json) {
+            const jsonOutput = await this.converter.convertChangeToJson(proposalPath);
+            if (options.requirementsOnly) {
+                console.error(CHANGE_MESSAGES.requirementsOnlyDeprecated);
+            }
+            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(), 'openspec', '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(UTILS_MESSAGES.failedToReadTasks(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(CHANGE_MESSAGES.noItemsFound);
+                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 = ` ${CHANGE_MESSAGES.tasks(completed, total)}`;
+                    }
+                    catch (error) {
+                        if (process.env.DEBUG) {
+                            console.error(UTILS_MESSAGES.failedToReadTasks(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 = CHANGE_MESSAGES.deltas(change.deltas.length);
+                    console.log(`${changeName}: ${title}${deltaCountText}${taskStatusText}`);
+                }
+                catch {
+                    console.log(`${changeName}: ${CHANGE_MESSAGES.unableToRead}`);
+                }
+            }
+        }
+    }
+    async validate(changeName, options) {
+        const changesPath = path.join(process.cwd(), 'openspec', '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: CHANGE_MESSAGES.selectChangeToValidate,
+                    choices: changes.map(id => ({ name: id, value: id })),
+                });
+                changeName = selected;
+            }
+            else {
+                if (changes.length === 0) {
+                    console.error(CHANGE_MESSAGES.noChangeSpecifiedNoActive);
+                }
+                else {
+                    console.error(CHANGE_MESSAGES.noChangeSpecifiedAvailable(changes.join(', ')));
+                }
+                console.error(CHANGE_MESSAGES.hintViewChanges);
+                process.exitCode = 1;
+                return;
+            }
+        }
+        const changeDir = path.join(changesPath, changeName);
+        try {
+            await fs.access(changeDir);
+        }
+        catch {
+            throw new Error(CHANGE_MESSAGES.changeNotFound(changeName, 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_MESSAGES.changeIsValid(changeName));
+            }
+            else {
+                console.error(CHANGE_MESSAGES.changeHasIssues(changeName));
+                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(CHANGE_MESSAGES.ensureDeltasInSpecs);
+        bullets.push(CHANGE_MESSAGES.eachRequirementNeedsScenario);
+        bullets.push(CHANGE_MESSAGES.debugParsedDeltas);
+        console.error(CHANGE_MESSAGES.nextSteps);
+        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 BR-OpenSpec 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,258 @@
+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';
+import { COMPLETION_MESSAGES } from '../messages/index.js';
+/**
+ * Command for managing shell completions for BR-OpenSpec 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(COMPLETION_MESSAGES.shellNotSupported(detectionResult.detected, CompletionFactory.getSupportedShells().join(', ')));
+                process.exitCode = 1;
+                return null;
+            }
+            // No shell specified and cannot auto-detect
+            console.error(COMPLETION_MESSAGES.couldNotDetectShell);
+            console.error(COMPLETION_MESSAGES.usageCompletion(operationName));
+            console.error(COMPLETION_MESSAGES.currentlySupported(CompletionFactory.getSupportedShells().join(', ')));
+            process.exitCode = 1;
+            return null;
+        }
+        if (!CompletionFactory.isSupported(normalizedShell)) {
+            console.error(COMPLETION_MESSAGES.shellNotSupported(normalizedShell, 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(COMPLETION_MESSAGES.installingCompletion(shell)).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(COMPLETION_MESSAGES.installSuccess(result.message));
+                if (verbose && result.installedPath) {
+                    console.log(COMPLETION_MESSAGES.installedTo(result.installedPath));
+                    if (result.backupPath) {
+                        console.log(COMPLETION_MESSAGES.backupCreated(result.backupPath));
+                    }
+                    // Check if any shell config was updated
+                    const configWasUpdated = result.zshrcConfigured || result.bashrcConfigured || result.profileConfigured;
+                    if (configWasUpdated) {
+                        const configPaths = {
+                            zsh: '~/.zshrc',
+                            bash: '~/.bashrc',
+                            fish: '~/.config/fish/config.fish',
+                            powershell: '$PROFILE',
+                        };
+                        const configPath = configPaths[shell] || 'config file';
+                        console.log(COMPLETION_MESSAGES.configFileConfigured(configPath));
+                    }
+                }
+                // Display warnings if present
+                if (result.warnings && result.warnings.length > 0) {
+                    console.log('');
+                    for (const warning of result.warnings) {
+                        console.log(warning);
+                    }
+                }
+                // 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 {
+                    // Check if any shell config was updated (InstallationResult has: zshrcConfigured, bashrcConfigured, profileConfigured)
+                    const configWasUpdated = result.zshrcConfigured || result.bashrcConfigured || result.profileConfigured;
+                    if (configWasUpdated) {
+                        console.log('');
+                        // Shell-specific reload instructions
+                        const reloadCommands = {
+                            zsh: 'exec zsh',
+                            bash: 'exec bash',
+                            fish: 'exec fish',
+                            powershell: '. $PROFILE',
+                        };
+                        const reloadCmd = reloadCommands[shell] || `restart your ${shell} shell`;
+                        console.log(COMPLETION_MESSAGES.restartShell(reloadCmd));
+                    }
+                }
+            }
+            else {
+                console.error(COMPLETION_MESSAGES.installFailed(result.message));
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            spinner.stop();
+            console.error(COMPLETION_MESSAGES.failedToInstall(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');
+            // Get shell-specific config file path
+            const configPaths = {
+                zsh: '~/.zshrc',
+                bash: '~/.bashrc',
+                fish: 'Fish configuration', // Fish doesn't modify profile, just removes script file
+                powershell: '$PROFILE',
+            };
+            const configPath = configPaths[shell] || `${shell} configuration`;
+            const confirmed = await confirm({
+                message: COMPLETION_MESSAGES.removeConfigConfirm(configPath),
+                default: false,
+            });
+            if (!confirmed) {
+                console.log(COMPLETION_MESSAGES.uninstallCancelled);
+                return;
+            }
+        }
+        const spinner = ora(COMPLETION_MESSAGES.uninstallingCompletion(shell)).start();
+        try {
+            const result = await installer.uninstall();
+            spinner.stop();
+            if (result.success) {
+                console.log(COMPLETION_MESSAGES.uninstallSuccess(result.message));
+            }
+            else {
+                console.error(COMPLETION_MESSAGES.uninstallFailed(result.message));
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            spinner.stop();
+            console.error(COMPLETION_MESSAGES.failedToUninstall(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}\t${COMPLETION_MESSAGES.activeChange}`);
+                    }
+                    break;
+                }
+                case 'specs': {
+                    const specIds = await this.completionProvider.getSpecIds();
+                    for (const id of specIds) {
+                        console.log(`${id}\t${COMPLETION_MESSAGES.specification}`);
+                    }
+                    break;
+                }
+                case 'archived-changes': {
+                    const archivedIds = await getArchivedChangeIds();
+                    for (const id of archivedIds) {
+                        console.log(`${id}\t${COMPLETION_MESSAGES.archivedChange}`);
+                    }
+                    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,36 @@
+import { Command } from 'commander';
+import { GlobalConfig } from '../core/global-config.js';
+import type { Profile, Delivery } from '../core/global-config.js';
+interface ProfileState {
+    profile: Profile;
+    delivery: Delivery;
+    workflows: string[];
+}
+interface ProfileStateDiff {
+    hasChanges: boolean;
+    lines: string[];
+}
+/**
+ * Resolve the effective current profile state from global config defaults.
+ */
+export declare function resolveCurrentProfileState(config: GlobalConfig): ProfileState;
+/**
+ * Derive profile type from selected workflows.
+ */
+export declare function deriveProfileFromWorkflowSelection(selectedWorkflows: string[]): Profile;
+/**
+ * Format a compact workflow summary for the profile header.
+ */
+export declare function formatWorkflowSummary(workflows: readonly string[], profile: Profile): string;
+/**
+ * Build a user-facing diff summary between two profile states.
+ */
+export declare function diffProfileState(before: ProfileState, after: ProfileState): ProfileStateDiff;
+/**
+ * Register the config command and all its subcommands.
+ *
+ * @param program - The Commander program instance
+ */
+export declare function registerConfigCommand(program: Command): void;
+export {};
+//# sourceMappingURL=config.d.ts.map