@fission-ai/openspec 0.16.0 → 0.17.1

package/dist/core/completions/command-registry.js

@@ -0,0 +1,362 @@
+/**
+ * Common flags used across multiple commands
+ */
+const COMMON_FLAGS = {
+    json: {
+        name: 'json',
+        description: 'Output as JSON',
+    },
+    jsonValidation: {
+        name: 'json',
+        description: 'Output validation results as JSON',
+    },
+    strict: {
+        name: 'strict',
+        description: 'Enable strict validation mode',
+    },
+    noInteractive: {
+        name: 'no-interactive',
+        description: 'Disable interactive prompts',
+    },
+    type: {
+        name: 'type',
+        description: 'Specify item type when ambiguous',
+        takesValue: true,
+        values: ['change', 'spec'],
+    },
+};
+/**
+ * Registry of all OpenSpec CLI commands with their flags and metadata.
+ * This registry is used to generate shell completion scripts.
+ */
+export const COMMAND_REGISTRY = [
+    {
+        name: 'init',
+        description: 'Initialize OpenSpec in your project',
+        acceptsPositional: true,
+        positionalType: 'path',
+        flags: [
+            {
+                name: 'tools',
+                description: 'Configure AI tools non-interactively (e.g., "all", "none", or comma-separated tool IDs)',
+                takesValue: true,
+            },
+        ],
+    },
+    {
+        name: 'update',
+        description: 'Update OpenSpec instruction files',
+        acceptsPositional: true,
+        positionalType: 'path',
+        flags: [],
+    },
+    {
+        name: 'list',
+        description: 'List items (changes by default, or specs with --specs)',
+        flags: [
+            {
+                name: 'specs',
+                description: 'List specs instead of changes',
+            },
+            {
+                name: 'changes',
+                description: 'List changes explicitly (default)',
+            },
+        ],
+    },
+    {
+        name: 'view',
+        description: 'Display an interactive dashboard of specs and changes',
+        flags: [],
+    },
+    {
+        name: 'validate',
+        description: 'Validate changes and specs',
+        acceptsPositional: true,
+        positionalType: 'change-or-spec-id',
+        flags: [
+            {
+                name: 'all',
+                description: 'Validate all changes and specs',
+            },
+            {
+                name: 'changes',
+                description: 'Validate all changes',
+            },
+            {
+                name: 'specs',
+                description: 'Validate all specs',
+            },
+            COMMON_FLAGS.type,
+            COMMON_FLAGS.strict,
+            COMMON_FLAGS.jsonValidation,
+            {
+                name: 'concurrency',
+                description: 'Max concurrent validations (defaults to env OPENSPEC_CONCURRENCY or 6)',
+                takesValue: true,
+            },
+            COMMON_FLAGS.noInteractive,
+        ],
+    },
+    {
+        name: 'show',
+        description: 'Show a change or spec',
+        acceptsPositional: true,
+        positionalType: 'change-or-spec-id',
+        flags: [
+            COMMON_FLAGS.json,
+            COMMON_FLAGS.type,
+            COMMON_FLAGS.noInteractive,
+            {
+                name: 'deltas-only',
+                description: 'Show only deltas (JSON only, change-specific)',
+            },
+            {
+                name: 'requirements-only',
+                description: 'Alias for --deltas-only (deprecated, change-specific)',
+            },
+            {
+                name: 'requirements',
+                description: 'Show only requirements, exclude scenarios (JSON only, spec-specific)',
+            },
+            {
+                name: 'no-scenarios',
+                description: 'Exclude scenario content (JSON only, spec-specific)',
+            },
+            {
+                name: 'requirement',
+                short: 'r',
+                description: 'Show specific requirement by ID (JSON only, spec-specific)',
+                takesValue: true,
+            },
+        ],
+    },
+    {
+        name: 'archive',
+        description: 'Archive a completed change and update main specs',
+        acceptsPositional: true,
+        positionalType: 'change-id',
+        flags: [
+            {
+                name: 'yes',
+                short: 'y',
+                description: 'Skip confirmation prompts',
+            },
+            {
+                name: 'skip-specs',
+                description: 'Skip spec update operations',
+            },
+            {
+                name: 'no-validate',
+                description: 'Skip validation (not recommended)',
+            },
+        ],
+    },
+    {
+        name: 'change',
+        description: 'Manage OpenSpec change proposals (deprecated)',
+        flags: [],
+        subcommands: [
+            {
+                name: 'show',
+                description: 'Show a change proposal',
+                acceptsPositional: true,
+                positionalType: 'change-id',
+                flags: [
+                    COMMON_FLAGS.json,
+                    {
+                        name: 'deltas-only',
+                        description: 'Show only deltas (JSON only)',
+                    },
+                    {
+                        name: 'requirements-only',
+                        description: 'Alias for --deltas-only (deprecated)',
+                    },
+                    COMMON_FLAGS.noInteractive,
+                ],
+            },
+            {
+                name: 'list',
+                description: 'List all active changes (deprecated)',
+                flags: [
+                    COMMON_FLAGS.json,
+                    {
+                        name: 'long',
+                        description: 'Show id and title with counts',
+                    },
+                ],
+            },
+            {
+                name: 'validate',
+                description: 'Validate a change proposal',
+                acceptsPositional: true,
+                positionalType: 'change-id',
+                flags: [
+                    COMMON_FLAGS.strict,
+                    COMMON_FLAGS.jsonValidation,
+                    COMMON_FLAGS.noInteractive,
+                ],
+            },
+        ],
+    },
+    {
+        name: 'spec',
+        description: 'Manage OpenSpec specifications',
+        flags: [],
+        subcommands: [
+            {
+                name: 'show',
+                description: 'Show a specification',
+                acceptsPositional: true,
+                positionalType: 'spec-id',
+                flags: [
+                    COMMON_FLAGS.json,
+                    {
+                        name: 'requirements',
+                        description: 'Show only requirements, exclude scenarios (JSON only)',
+                    },
+                    {
+                        name: 'no-scenarios',
+                        description: 'Exclude scenario content (JSON only)',
+                    },
+                    {
+                        name: 'requirement',
+                        short: 'r',
+                        description: 'Show specific requirement by ID (JSON only)',
+                        takesValue: true,
+                    },
+                    COMMON_FLAGS.noInteractive,
+                ],
+            },
+            {
+                name: 'list',
+                description: 'List all specifications',
+                flags: [
+                    COMMON_FLAGS.json,
+                    {
+                        name: 'long',
+                        description: 'Show id and title with counts',
+                    },
+                ],
+            },
+            {
+                name: 'validate',
+                description: 'Validate a specification',
+                acceptsPositional: true,
+                positionalType: 'spec-id',
+                flags: [
+                    COMMON_FLAGS.strict,
+                    COMMON_FLAGS.jsonValidation,
+                    COMMON_FLAGS.noInteractive,
+                ],
+            },
+        ],
+    },
+    {
+        name: 'completion',
+        description: 'Manage shell completions for OpenSpec CLI',
+        flags: [],
+        subcommands: [
+            {
+                name: 'generate',
+                description: 'Generate completion script for a shell (outputs to stdout)',
+                acceptsPositional: true,
+                positionalType: 'shell',
+                flags: [],
+            },
+            {
+                name: 'install',
+                description: 'Install completion script for a shell',
+                acceptsPositional: true,
+                positionalType: 'shell',
+                flags: [
+                    {
+                        name: 'verbose',
+                        description: 'Show detailed installation output',
+                    },
+                ],
+            },
+            {
+                name: 'uninstall',
+                description: 'Uninstall completion script for a shell',
+                acceptsPositional: true,
+                positionalType: 'shell',
+                flags: [],
+            },
+        ],
+    },
+    {
+        name: 'config',
+        description: 'View and modify global OpenSpec configuration',
+        flags: [
+            {
+                name: 'scope',
+                description: 'Config scope (only "global" supported currently)',
+                takesValue: true,
+                values: ['global'],
+            },
+        ],
+        subcommands: [
+            {
+                name: 'path',
+                description: 'Show config file location',
+                flags: [],
+            },
+            {
+                name: 'list',
+                description: 'Show all current settings',
+                flags: [
+                    COMMON_FLAGS.json,
+                ],
+            },
+            {
+                name: 'get',
+                description: 'Get a specific value (raw, scriptable)',
+                acceptsPositional: true,
+                flags: [],
+            },
+            {
+                name: 'set',
+                description: 'Set a value (auto-coerce types)',
+                acceptsPositional: true,
+                flags: [
+                    {
+                        name: 'string',
+                        description: 'Force value to be stored as string',
+                    },
+                    {
+                        name: 'allow-unknown',
+                        description: 'Allow setting unknown keys',
+                    },
+                ],
+            },
+            {
+                name: 'unset',
+                description: 'Remove a key (revert to default)',
+                acceptsPositional: true,
+                flags: [],
+            },
+            {
+                name: 'reset',
+                description: 'Reset configuration to defaults',
+                flags: [
+                    {
+                        name: 'all',
+                        description: 'Reset all configuration (required)',
+                    },
+                    {
+                        name: 'yes',
+                        short: 'y',
+                        description: 'Skip confirmation prompts',
+                    },
+                ],
+            },
+            {
+                name: 'edit',
+                description: 'Open config in $EDITOR',
+                flags: [],
+            },
+        ],
+    },
+];
+//# sourceMappingURL=command-registry.js.map

package/dist/core/completions/completion-provider.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Provides dynamic completion suggestions for OpenSpec items (changes and specs).
+ * Implements a 2-second cache to avoid excessive file system operations during
+ * tab completion.
+ */
+export declare class CompletionProvider {
+    private readonly cacheTTLMs;
+    private readonly projectRoot;
+    private readonly cacheTTL;
+    private changeCache;
+    private specCache;
+    /**
+     * Creates a new completion provider
+     *
+     * @param cacheTTLMs - Cache time-to-live in milliseconds (default: 2000ms)
+     * @param projectRoot - Project root directory (default: process.cwd())
+     */
+    constructor(cacheTTLMs?: number, projectRoot?: string);
+    /**
+     * Get all active change IDs for completion
+     *
+     * @returns Array of change IDs
+     */
+    getChangeIds(): Promise<string[]>;
+    /**
+     * Get all spec IDs for completion
+     *
+     * @returns Array of spec IDs
+     */
+    getSpecIds(): Promise<string[]>;
+    /**
+     * Get both change and spec IDs for completion
+     *
+     * @returns Object with changeIds and specIds arrays
+     */
+    getAllIds(): Promise<{
+        changeIds: string[];
+        specIds: string[];
+    }>;
+    /**
+     * Clear all cached data
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics for debugging
+     *
+     * @returns Cache status information
+     */
+    getCacheStats(): {
+        changeCache: {
+            valid: boolean;
+            age?: number;
+        };
+        specCache: {
+            valid: boolean;
+            age?: number;
+        };
+    };
+}
+//# sourceMappingURL=completion-provider.d.ts.map

package/dist/core/completions/completion-provider.js

@@ -0,0 +1,102 @@
+import { getActiveChangeIds, getSpecIds } from '../../utils/item-discovery.js';
+/**
+ * Provides dynamic completion suggestions for OpenSpec items (changes and specs).
+ * Implements a 2-second cache to avoid excessive file system operations during
+ * tab completion.
+ */
+export class CompletionProvider {
+    cacheTTLMs;
+    projectRoot;
+    cacheTTL;
+    changeCache = null;
+    specCache = null;
+    /**
+     * Creates a new completion provider
+     *
+     * @param cacheTTLMs - Cache time-to-live in milliseconds (default: 2000ms)
+     * @param projectRoot - Project root directory (default: process.cwd())
+     */
+    constructor(cacheTTLMs = 2000, projectRoot = process.cwd()) {
+        this.cacheTTLMs = cacheTTLMs;
+        this.projectRoot = projectRoot;
+        this.cacheTTL = cacheTTLMs;
+    }
+    /**
+     * Get all active change IDs for completion
+     *
+     * @returns Array of change IDs
+     */
+    async getChangeIds() {
+        const now = Date.now();
+        // Check if cache is valid
+        if (this.changeCache && now - this.changeCache.timestamp < this.cacheTTL) {
+            return this.changeCache.data;
+        }
+        // Fetch fresh data
+        const changeIds = await getActiveChangeIds(this.projectRoot);
+        // Update cache
+        this.changeCache = {
+            data: changeIds,
+            timestamp: now,
+        };
+        return changeIds;
+    }
+    /**
+     * Get all spec IDs for completion
+     *
+     * @returns Array of spec IDs
+     */
+    async getSpecIds() {
+        const now = Date.now();
+        // Check if cache is valid
+        if (this.specCache && now - this.specCache.timestamp < this.cacheTTL) {
+            return this.specCache.data;
+        }
+        // Fetch fresh data
+        const specIds = await getSpecIds(this.projectRoot);
+        // Update cache
+        this.specCache = {
+            data: specIds,
+            timestamp: now,
+        };
+        return specIds;
+    }
+    /**
+     * Get both change and spec IDs for completion
+     *
+     * @returns Object with changeIds and specIds arrays
+     */
+    async getAllIds() {
+        const [changeIds, specIds] = await Promise.all([
+            this.getChangeIds(),
+            this.getSpecIds(),
+        ]);
+        return { changeIds, specIds };
+    }
+    /**
+     * Clear all cached data
+     */
+    clearCache() {
+        this.changeCache = null;
+        this.specCache = null;
+    }
+    /**
+     * Get cache statistics for debugging
+     *
+     * @returns Cache status information
+     */
+    getCacheStats() {
+        const now = Date.now();
+        return {
+            changeCache: {
+                valid: this.changeCache !== null && now - this.changeCache.timestamp < this.cacheTTL,
+                age: this.changeCache ? now - this.changeCache.timestamp : undefined,
+            },
+            specCache: {
+                valid: this.specCache !== null && now - this.specCache.timestamp < this.cacheTTL,
+                age: this.specCache ? now - this.specCache.timestamp : undefined,
+            },
+        };
+    }
+}
+//# sourceMappingURL=completion-provider.js.map

package/dist/core/completions/factory.d.ts

@@ -0,0 +1,51 @@
+import { CompletionGenerator } from './types.js';
+import { InstallationResult } from './installers/zsh-installer.js';
+import { SupportedShell } from '../../utils/shell-detection.js';
+/**
+ * Interface for completion installers
+ */
+export interface CompletionInstaller {
+    install(script: string): Promise<InstallationResult>;
+    uninstall(): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+}
+export type { InstallationResult };
+/**
+ * Factory for creating completion generators and installers
+ * This design makes it easy to add support for additional shells
+ */
+export declare class CompletionFactory {
+    private static readonly SUPPORTED_SHELLS;
+    /**
+     * Create a completion generator for the specified shell
+     *
+     * @param shell - The target shell
+     * @returns CompletionGenerator instance
+     * @throws Error if shell is not supported
+     */
+    static createGenerator(shell: SupportedShell): CompletionGenerator;
+    /**
+     * Create a completion installer for the specified shell
+     *
+     * @param shell - The target shell
+     * @returns CompletionInstaller instance
+     * @throws Error if shell is not supported
+     */
+    static createInstaller(shell: SupportedShell): CompletionInstaller;
+    /**
+     * Check if a shell is supported
+     *
+     * @param shell - The shell to check
+     * @returns true if the shell is supported
+     */
+    static isSupported(shell: string): shell is SupportedShell;
+    /**
+     * Get list of all supported shells
+     *
+     * @returns Array of supported shell names
+     */
+    static getSupportedShells(): SupportedShell[];
+}
+//# sourceMappingURL=factory.d.ts.map

package/dist/core/completions/factory.js

@@ -0,0 +1,57 @@
+import { ZshGenerator } from './generators/zsh-generator.js';
+import { ZshInstaller } from './installers/zsh-installer.js';
+/**
+ * Factory for creating completion generators and installers
+ * This design makes it easy to add support for additional shells
+ */
+export class CompletionFactory {
+    static SUPPORTED_SHELLS = ['zsh'];
+    /**
+     * Create a completion generator for the specified shell
+     *
+     * @param shell - The target shell
+     * @returns CompletionGenerator instance
+     * @throws Error if shell is not supported
+     */
+    static createGenerator(shell) {
+        switch (shell) {
+            case 'zsh':
+                return new ZshGenerator();
+            default:
+                throw new Error(`Unsupported shell: ${shell}`);
+        }
+    }
+    /**
+     * Create a completion installer for the specified shell
+     *
+     * @param shell - The target shell
+     * @returns CompletionInstaller instance
+     * @throws Error if shell is not supported
+     */
+    static createInstaller(shell) {
+        switch (shell) {
+            case 'zsh':
+                return new ZshInstaller();
+            default:
+                throw new Error(`Unsupported shell: ${shell}`);
+        }
+    }
+    /**
+     * Check if a shell is supported
+     *
+     * @param shell - The shell to check
+     * @returns true if the shell is supported
+     */
+    static isSupported(shell) {
+        return this.SUPPORTED_SHELLS.includes(shell);
+    }
+    /**
+     * Get list of all supported shells
+     *
+     * @returns Array of supported shell names
+     */
+    static getSupportedShells() {
+        return [...this.SUPPORTED_SHELLS];
+    }
+}
+//# sourceMappingURL=factory.js.map

package/dist/core/completions/generators/zsh-generator.d.ts

@@ -0,0 +1,58 @@
+import { CompletionGenerator, CommandDefinition } from '../types.js';
+/**
+ * Generates Zsh completion scripts for the OpenSpec CLI.
+ * Follows Zsh completion system conventions using the _openspec function.
+ */
+export declare class ZshGenerator implements CompletionGenerator {
+    readonly shell: "zsh";
+    /**
+     * Generate a Zsh completion script
+     *
+     * @param commands - Command definitions to generate completions for
+     * @returns Zsh completion script as a string
+     */
+    generate(commands: CommandDefinition[]): string;
+    /**
+     * Generate a single completion function
+     *
+     * @param functionName - Name of the completion function
+     * @param varName - Name of the local array variable
+     * @param varLabel - Label for the completion items
+     * @param commandLines - Command line(s) to populate the array
+     * @param comment - Optional comment describing the function
+     */
+    private generateCompletionFunction;
+    /**
+     * Generate dynamic completion helper functions for change and spec IDs
+     */
+    private generateDynamicCompletionHelpers;
+    /**
+     * Generate completion function for a specific command
+     */
+    private generateCommandFunction;
+    /**
+     * Generate completion function for a subcommand
+     */
+    private generateSubcommandFunction;
+    /**
+     * Generate flag specification for _arguments
+     */
+    private generateFlagSpec;
+    /**
+     * Generate positional argument specification
+     */
+    private generatePositionalSpec;
+    /**
+     * Escape special characters in descriptions
+     */
+    private escapeDescription;
+    /**
+     * Escape special characters in values
+     */
+    private escapeValue;
+    /**
+     * Sanitize command names for use in function names
+     */
+    private sanitizeFunctionName;
+}
+//# sourceMappingURL=zsh-generator.d.ts.map