@fission-ai/openspec 0.16.0 → 0.17.0

package/README.md

@@ -85,42 +85,49 @@ See the full comparison in [How OpenSpec Compares](#how-openspec-compares).
 
 ### Supported AI Tools
 
-#### Native Slash Commands
+<details>
+<summary><strong>Native Slash Commands</strong> (click to expand)</summary>
+
 These tools have built-in OpenSpec commands. Select the OpenSpec integration when prompted.
 
 | Tool | Commands |
 |------|----------|
+| **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` (`.amazonq/prompts/`) |
+| **Antigravity** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.agent/workflows/`) |
+| **Auggie (Augment CLI)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.augment/commands/`) |
 | **Claude Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` |
+| **Cline** | Workflows in `.clinerules/workflows/` directory (`.clinerules/workflows/openspec-*.md`) |
 | **CodeBuddy Code (CLI)** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.codebuddy/commands/`) — see [docs](https://www.codebuddy.ai/cli) |
+| **Codex** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (global: `~/.codex/prompts`, auto-installed) |
 | **CoStrict** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.cospec/openspec/commands/`) — see [docs](https://costrict.ai)|
-| **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
-| **Cline** | Workflows in `.clinerules/workflows/` directory (`.clinerules/workflows/openspec-*.md`) |
 | **Crush** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.crush/commands/openspec/`) |
-| **RooCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.roo/commands/`) |
+| **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
 | **Factory Droid** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.factory/commands/`) |
 | **Gemini CLI** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.gemini/commands/openspec/`) |
-| **OpenCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
+| **GitHub Copilot** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.github/prompts/`) |
+| **iFlow (iflow-cli)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.iflow/commands/`) |
 | **Kilo Code** | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` (`.kilocode/workflows/`) |
+| **OpenCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
 | **Qoder (CLI)** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.qoder/commands/openspec/`) — see [docs](https://qoder.com/cli) |
-| **Antigravity** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.agent/workflows/`) |
-| **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.windsurf/workflows/`) |
-| **Codex** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (global: `~/.codex/prompts`, auto-installed) |
-| **GitHub Copilot** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.github/prompts/`) |
-| **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` (`.amazonq/prompts/`) |
-| **Auggie (Augment CLI)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.augment/commands/`) |
 | **Qwen Code** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.qwen/commands/`) |
-| **iFlow (iflow-cli)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.iflow/commands/`) |
-
+| **RooCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.roo/commands/`) |
+| **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.windsurf/workflows/`) |
 
 Kilo Code discovers team workflows automatically. Save the generated files under `.kilocode/workflows/` and trigger them from the command palette with `/openspec-proposal.md`, `/openspec-apply.md`, or `/openspec-archive.md`.
 
-#### AGENTS.md Compatible
+</details>
+
+<details>
+<summary><strong>AGENTS.md Compatible</strong> (click to expand)</summary>
+
 These tools automatically read workflow instructions from `openspec/AGENTS.md`. Ask them to follow the OpenSpec workflow if they need a reminder. Learn more about the [AGENTS.md convention](https://agents.md/).
 
 | Tools |
 |-------|
 | Amp • Jules • Others |
 
+</details>
+
 ### Install & Initialize
 
 #### Prerequisites

package/dist/cli/index.js

@@ -3,7 +3,6 @@ import { createRequire } from 'module';
 import ora from 'ora';
 import path from 'path';
 import { promises as fs } from 'fs';
-import { InitCommand } from '../core/init.js';
 import { AI_TOOLS } from '../core/config.js';
 import { UpdateCommand } from '../core/update.js';
 import { ListCommand } from '../core/list.js';
@@ -13,6 +12,8 @@ import { registerSpecCommand } from '../commands/spec.js';
 import { ChangeCommand } from '../commands/change.js';
 import { ValidateCommand } from '../commands/validate.js';
 import { ShowCommand } from '../commands/show.js';
+import { CompletionCommand } from '../commands/completion.js';
+import { registerConfigCommand } from '../commands/config.js';
 const program = new Command();
 const require = createRequire(import.meta.url);
 const { version } = require('../../package.json');
@@ -25,7 +26,7 @@ program.option('--no-color', 'Disable color output');
 // Apply global flags before any command runs
 program.hook('preAction', (thisCommand) => {
     const opts = thisCommand.opts();
-    if (opts.noColor) {
+    if (opts.color === false) {
         process.env.NO_COLOR = '1';
     }
 });
@@ -57,6 +58,7 @@ program
                 throw new Error(`Cannot access path "${targetPath}": ${error.message}`);
             }
         }
+        const { InitCommand } = await import('../core/init.js');
         const initCommand = new InitCommand({
             tools: options?.tools,
         });
@@ -192,6 +194,7 @@ program
     }
 });
 registerSpecCommand(program);
+registerConfigCommand(program);
 // Top-level validate command
 program
     .command('validate [item-name]')
@@ -242,5 +245,67 @@ program
         process.exit(1);
     }
 });
+// Completion command with subcommands
+const completionCmd = program
+    .command('completion')
+    .description('Manage shell completions for OpenSpec CLI');
+completionCmd
+    .command('generate [shell]')
+    .description('Generate completion script for a shell (outputs to stdout)')
+    .action(async (shell) => {
+    try {
+        const completionCommand = new CompletionCommand();
+        await completionCommand.generate({ shell });
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+completionCmd
+    .command('install [shell]')
+    .description('Install completion script for a shell')
+    .option('--verbose', 'Show detailed installation output')
+    .action(async (shell, options) => {
+    try {
+        const completionCommand = new CompletionCommand();
+        await completionCommand.install({ shell, verbose: options?.verbose });
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+completionCmd
+    .command('uninstall [shell]')
+    .description('Uninstall completion script for a shell')
+    .option('-y, --yes', 'Skip confirmation prompts')
+    .action(async (shell, options) => {
+    try {
+        const completionCommand = new CompletionCommand();
+        await completionCommand.uninstall({ shell, yes: options?.yes });
+    }
+    catch (error) {
+        console.log();
+        ora().fail(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
+// Hidden command for machine-readable completion data
+program
+    .command('__complete <type>', { hidden: true })
+    .description('Output completion data in machine-readable format (internal use)')
+    .action(async (type) => {
+    try {
+        const completionCommand = new CompletionCommand();
+        await completionCommand.complete({ type });
+    }
+    catch (error) {
+        // Silently fail for graceful shell completion experience
+        process.exitCode = 1;
+    }
+});
 program.parse();
 //# sourceMappingURL=index.js.map

package/dist/commands/change.js

@@ -1,6 +1,5 @@
 import { promises as fs } from 'fs';
 import path from 'path';
-import { select } from '@inquirer/prompts';
 import { JsonConverter } from '../core/converters/json-converter.js';
 import { Validator } from '../core/validation/validator.js';
 import { ChangeParser } from '../core/parsers/change-parser.js';
@@ -24,9 +23,10 @@ export class ChangeCommand {
     async show(changeName, options) {
         const changesPath = path.join(process.cwd(), 'openspec', 'changes');
         if (!changeName) {
-            const canPrompt = isInteractive(options?.noInteractive);
+            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 })),
@@ -172,9 +172,10 @@ export class ChangeCommand {
     async validate(changeName, options) {
         const changesPath = path.join(process.cwd(), 'openspec', 'changes');
         if (!changeName) {
-            const canPrompt = isInteractive(options?.noInteractive);
+            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 })),

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 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,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 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(`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: openspec 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 OpenSpec 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