openspec-cn 0.23.0

package/dist/core/completions/generators/powershell-generator.js

@@ -0,0 +1,207 @@
+import { POWERSHELL_DYNAMIC_HELPERS } from '../templates/powershell-templates.js';
+/**
+ * Generates PowerShell completion scripts for the OpenSpec CLI.
+ * Uses Register-ArgumentCompleter for command completion.
+ */
+export class PowerShellGenerator {
+    shell = 'powershell';
+    stripTrailingCommaFromLastLine(lines) {
+        if (lines.length === 0)
+            return;
+        lines[lines.length - 1] = lines[lines.length - 1].replace(/,\s*$/, '');
+    }
+    /**
+     * Generate a PowerShell completion script
+     *
+     * @param commands - Command definitions to generate completions for
+     * @returns PowerShell completion script as a string
+     */
+    generate(commands) {
+        // Build top-level commands using push() for loop clarity
+        const commandLines = [];
+        for (const cmd of commands) {
+            commandLines.push(`            @{Name="${cmd.name}"; Description="${this.escapeDescription(cmd.description)}"},`);
+        }
+        this.stripTrailingCommaFromLastLine(commandLines);
+        const topLevelCommands = commandLines.join('\n');
+        // Build command cases using push() for loop clarity
+        const commandCaseLines = [];
+        for (const cmd of commands) {
+            commandCaseLines.push(`        "${cmd.name}" {`);
+            commandCaseLines.push(...this.generateCommandCase(cmd, '            '));
+            commandCaseLines.push('        }');
+        }
+        const commandCases = commandCaseLines.join('\n');
+        // Dynamic completion helpers from template
+        const helpers = POWERSHELL_DYNAMIC_HELPERS;
+        // Assemble final script with template literal
+        return `# PowerShell completion script for OpenSpec CLI
+# Auto-generated - do not edit manually
+
+${helpers}
+$openspecCompleter = {
+    param($wordToComplete, $commandAst, $cursorPosition)
+
+    $tokens = $commandAst.ToString() -split "\\s+"
+    $commandCount = ($tokens | Measure-Object).Count
+
+    # Top-level commands
+    if ($commandCount -eq 1 -or ($commandCount -eq 2 -and $wordToComplete)) {
+        $commands = @(
+${topLevelCommands}
+        )
+        $commands | Where-Object { $_.Name -like "$wordToComplete*" } | ForEach-Object {
+            [System.Management.Automation.CompletionResult]::new($_.Name, $_.Name, "ParameterValue", $_.Description)
+        }
+        return
+    }
+
+    $command = $tokens[1]
+
+    switch ($command) {
+${commandCases}
+    }
+}
+
+Register-ArgumentCompleter -CommandName openspec -ScriptBlock $openspecCompleter
+`;
+    }
+    /**
+     * Generate completion case for a command
+     */
+    generateCommandCase(cmd, indent) {
+        const lines = [];
+        if (cmd.subcommands && cmd.subcommands.length > 0) {
+            // First, check if user is typing a flag for the parent command
+            if (cmd.flags.length > 0) {
+                lines.push(`${indent}if ($wordToComplete -like "-*") {`);
+                lines.push(`${indent}    $flags = @(`);
+                for (const flag of cmd.flags) {
+                    const longFlag = `--${flag.name}`;
+                    const shortFlag = flag.short ? `-${flag.short}` : undefined;
+                    if (shortFlag) {
+                        lines.push(`${indent}        @{Name="${longFlag}"; Description="${this.escapeDescription(flag.description)}"},`);
+                        lines.push(`${indent}        @{Name="${shortFlag}"; Description="${this.escapeDescription(flag.description)}"},`);
+                    }
+                    else {
+                        lines.push(`${indent}        @{Name="${longFlag}"; Description="${this.escapeDescription(flag.description)}"},`);
+                    }
+                }
+                this.stripTrailingCommaFromLastLine(lines);
+                lines.push(`${indent}    )`);
+                lines.push(`${indent}    $flags | Where-Object { $_.Name -like "$wordToComplete*" } | ForEach-Object {`);
+                lines.push(`${indent}        [System.Management.Automation.CompletionResult]::new($_.Name, $_.Name, "ParameterName", $_.Description)`);
+                lines.push(`${indent}    }`);
+                lines.push(`${indent}    return`);
+                lines.push(`${indent}}`);
+                lines.push('');
+            }
+            // Handle subcommands
+            lines.push(`${indent}if ($commandCount -eq 2 -or ($commandCount -eq 3 -and $wordToComplete)) {`);
+            lines.push(`${indent}    $subcommands = @(`);
+            for (const subcmd of cmd.subcommands) {
+                lines.push(`${indent}        @{Name="${subcmd.name}"; Description="${this.escapeDescription(subcmd.description)}"},`);
+            }
+            this.stripTrailingCommaFromLastLine(lines);
+            lines.push(`${indent}    )`);
+            lines.push(`${indent}    $subcommands | Where-Object { $_.Name -like "$wordToComplete*" } | ForEach-Object {`);
+            lines.push(`${indent}        [System.Management.Automation.CompletionResult]::new($_.Name, $_.Name, "ParameterValue", $_.Description)`);
+            lines.push(`${indent}    }`);
+            lines.push(`${indent}    return`);
+            lines.push(`${indent}}`);
+            lines.push('');
+            lines.push(`${indent}$subcommand = if ($commandCount -gt 2) { $tokens[2] } else { "" }`);
+            lines.push(`${indent}switch ($subcommand) {`);
+            for (const subcmd of cmd.subcommands) {
+                lines.push(`${indent}    "${subcmd.name}" {`);
+                lines.push(...this.generateArgumentCompletion(subcmd, indent + '        '));
+                lines.push(`${indent}    }`);
+            }
+            lines.push(`${indent}}`);
+        }
+        else {
+            // No subcommands
+            lines.push(...this.generateArgumentCompletion(cmd, indent));
+        }
+        return lines;
+    }
+    /**
+     * Generate argument completion (flags and positional)
+     */
+    generateArgumentCompletion(cmd, indent) {
+        const lines = [];
+        // Flag completion
+        if (cmd.flags.length > 0) {
+            lines.push(`${indent}if ($wordToComplete -like "-*") {`);
+            lines.push(`${indent}    $flags = @(`);
+            for (const flag of cmd.flags) {
+                const longFlag = `--${flag.name}`;
+                const shortFlag = flag.short ? `-${flag.short}` : undefined;
+                if (shortFlag) {
+                    lines.push(`${indent}        @{Name="${longFlag}"; Description="${this.escapeDescription(flag.description)}"},`);
+                    lines.push(`${indent}        @{Name="${shortFlag}"; Description="${this.escapeDescription(flag.description)}"},`);
+                }
+                else {
+                    lines.push(`${indent}        @{Name="${longFlag}"; Description="${this.escapeDescription(flag.description)}"},`);
+                }
+            }
+            this.stripTrailingCommaFromLastLine(lines);
+            lines.push(`${indent}    )`);
+            lines.push(`${indent}    $flags | Where-Object { $_.Name -like "$wordToComplete*" } | ForEach-Object {`);
+            lines.push(`${indent}        [System.Management.Automation.CompletionResult]::new($_.Name, $_.Name, "ParameterName", $_.Description)`);
+            lines.push(`${indent}    }`);
+            lines.push(`${indent}    return`);
+            lines.push(`${indent}}`);
+            lines.push('');
+        }
+        // Positional completion
+        if (cmd.acceptsPositional) {
+            lines.push(...this.generatePositionalCompletion(cmd.positionalType, indent));
+        }
+        return lines;
+    }
+    /**
+     * Generate positional argument completion
+     */
+    generatePositionalCompletion(positionalType, indent) {
+        const lines = [];
+        switch (positionalType) {
+            case 'change-id':
+                lines.push(`${indent}Get-OpenSpecChanges | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {`);
+                lines.push(`${indent}    [System.Management.Automation.CompletionResult]::new($_, $_, "ParameterValue", "Change: $_")`);
+                lines.push(`${indent}}`);
+                break;
+            case 'spec-id':
+                lines.push(`${indent}Get-OpenSpecSpecs | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {`);
+                lines.push(`${indent}    [System.Management.Automation.CompletionResult]::new($_, $_, "ParameterValue", "Spec: $_")`);
+                lines.push(`${indent}}`);
+                break;
+            case 'change-or-spec-id':
+                lines.push(`${indent}$items = @(Get-OpenSpecChanges) + @(Get-OpenSpecSpecs)`);
+                lines.push(`${indent}$items | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {`);
+                lines.push(`${indent}    [System.Management.Automation.CompletionResult]::new($_, $_, "ParameterValue", $_)`);
+                lines.push(`${indent}}`);
+                break;
+            case 'shell':
+                lines.push(`${indent}$shells = @("zsh", "bash", "fish", "powershell")`);
+                lines.push(`${indent}$shells | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {`);
+                lines.push(`${indent}    [System.Management.Automation.CompletionResult]::new($_, $_, "ParameterValue", "Shell: $_")`);
+                lines.push(`${indent}}`);
+                break;
+            case 'path':
+                // PowerShell handles file path completion automatically
+                break;
+        }
+        return lines;
+    }
+    /**
+     * Escape description text for PowerShell
+     */
+    escapeDescription(description) {
+        return description
+            .replace(/`/g, '``') // Backticks (escape sequences)
+            .replace(/\$/g, '`$') // Dollar signs (prevents $())
+            .replace(/"/g, '""'); // Double quotes
+    }
+}
+//# sourceMappingURL=powershell-generator.js.map

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

@@ -0,0 +1,44 @@
+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 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

package/dist/core/completions/generators/zsh-generator.js

@@ -0,0 +1,250 @@
+import { ZSH_DYNAMIC_HELPERS } from '../templates/zsh-templates.js';
+/**
+ * Generates Zsh completion scripts for the OpenSpec CLI.
+ * Follows Zsh completion system conventions using the _openspec function.
+ */
+export class ZshGenerator {
+    shell = 'zsh';
+    /**
+     * Generate a Zsh completion script
+     *
+     * @param commands - Command definitions to generate completions for
+     * @returns Zsh completion script as a string
+     */
+    generate(commands) {
+        // Build command list using push() for loop clarity
+        const commandLines = [];
+        for (const cmd of commands) {
+            const escapedDesc = this.escapeDescription(cmd.description);
+            commandLines.push(`    '${cmd.name}:${escapedDesc}'`);
+        }
+        const commandList = commandLines.join('\n');
+        // Build command cases using push() for loop clarity
+        const commandCaseLines = [];
+        for (const cmd of commands) {
+            commandCaseLines.push(`        ${cmd.name})`);
+            commandCaseLines.push(`          _openspec_${this.sanitizeFunctionName(cmd.name)}`);
+            commandCaseLines.push('          ;;');
+        }
+        const commandCases = commandCaseLines.join('\n');
+        // Build command functions using push() for loop clarity
+        const commandFunctionLines = [];
+        for (const cmd of commands) {
+            commandFunctionLines.push(...this.generateCommandFunction(cmd));
+            commandFunctionLines.push('');
+        }
+        const commandFunctions = commandFunctionLines.join('\n');
+        // Dynamic completion helpers from template
+        const helpers = ZSH_DYNAMIC_HELPERS;
+        // Assemble final script with template literal
+        return `#compdef openspec
+
+# Zsh completion script for OpenSpec CLI
+# Auto-generated - do not edit manually
+
+_openspec() {
+  local context state line
+  typeset -A opt_args
+
+  local -a commands
+  commands=(
+${commandList}
+  )
+
+  _arguments -C \\
+    "1: :->command" \\
+    "*::arg:->args"
+
+  case $state in
+    command)
+      _describe "openspec command" commands
+      ;;
+    args)
+      case $words[1] in
+${commandCases}
+      esac
+      ;;
+  esac
+}
+
+${commandFunctions}
+${helpers}
+compdef _openspec openspec
+`;
+    }
+    /**
+     * Generate completion function for a specific command
+     */
+    generateCommandFunction(cmd) {
+        const funcName = `_openspec_${this.sanitizeFunctionName(cmd.name)}`;
+        const lines = [];
+        lines.push(`${funcName}() {`);
+        // If command has subcommands, handle them
+        if (cmd.subcommands && cmd.subcommands.length > 0) {
+            lines.push('  local context state line');
+            lines.push('  typeset -A opt_args');
+            lines.push('');
+            lines.push('  local -a subcommands');
+            lines.push('  subcommands=(');
+            for (const subcmd of cmd.subcommands) {
+                const escapedDesc = this.escapeDescription(subcmd.description);
+                lines.push(`    '${subcmd.name}:${escapedDesc}'`);
+            }
+            lines.push('  )');
+            lines.push('');
+            lines.push('  _arguments -C \\');
+            // Add command flags
+            for (const flag of cmd.flags) {
+                lines.push('    ' + this.generateFlagSpec(flag) + ' \\');
+            }
+            lines.push('    "1: :->subcommand" \\');
+            lines.push('    "*::arg:->args"');
+            lines.push('');
+            lines.push('  case $state in');
+            lines.push('    subcommand)');
+            lines.push('      _describe "subcommand" subcommands');
+            lines.push('      ;;');
+            lines.push('    args)');
+            lines.push('      case $words[1] in');
+            for (const subcmd of cmd.subcommands) {
+                lines.push(`        ${subcmd.name})`);
+                lines.push(`          _openspec_${this.sanitizeFunctionName(cmd.name)}_${this.sanitizeFunctionName(subcmd.name)}`);
+                lines.push('          ;;');
+            }
+            lines.push('      esac');
+            lines.push('      ;;');
+            lines.push('  esac');
+        }
+        else {
+            // Command without subcommands
+            lines.push('  _arguments \\');
+            // Add flags
+            for (const flag of cmd.flags) {
+                lines.push('    ' + this.generateFlagSpec(flag) + ' \\');
+            }
+            // Add positional argument completion
+            if (cmd.acceptsPositional) {
+                const positionalSpec = this.generatePositionalSpec(cmd.positionalType);
+                lines.push('    ' + positionalSpec);
+            }
+            else {
+                // Remove trailing backslash from last flag
+                if (lines[lines.length - 1].endsWith(' \\')) {
+                    lines[lines.length - 1] = lines[lines.length - 1].slice(0, -2);
+                }
+            }
+        }
+        lines.push('}');
+        // Generate subcommand functions if they exist
+        if (cmd.subcommands) {
+            for (const subcmd of cmd.subcommands) {
+                lines.push('');
+                lines.push(...this.generateSubcommandFunction(cmd.name, subcmd));
+            }
+        }
+        return lines;
+    }
+    /**
+     * Generate completion function for a subcommand
+     */
+    generateSubcommandFunction(parentName, subcmd) {
+        const funcName = `_openspec_${this.sanitizeFunctionName(parentName)}_${this.sanitizeFunctionName(subcmd.name)}`;
+        const lines = [];
+        lines.push(`${funcName}() {`);
+        lines.push('  _arguments \\');
+        // Add flags
+        for (const flag of subcmd.flags) {
+            lines.push('    ' + this.generateFlagSpec(flag) + ' \\');
+        }
+        // Add positional argument completion
+        if (subcmd.acceptsPositional) {
+            const positionalSpec = this.generatePositionalSpec(subcmd.positionalType);
+            lines.push('    ' + positionalSpec);
+        }
+        else {
+            // Remove trailing backslash from last flag
+            if (lines[lines.length - 1].endsWith(' \\')) {
+                lines[lines.length - 1] = lines[lines.length - 1].slice(0, -2);
+            }
+        }
+        lines.push('}');
+        return lines;
+    }
+    /**
+     * Generate flag specification for _arguments
+     */
+    generateFlagSpec(flag) {
+        const parts = [];
+        // Handle mutually exclusive short and long forms
+        if (flag.short) {
+            parts.push(`'(-${flag.short} --${flag.name})'{-${flag.short},--${flag.name}}'`);
+        }
+        else {
+            parts.push(`'--${flag.name}`);
+        }
+        // Add description
+        const escapedDesc = this.escapeDescription(flag.description);
+        parts.push(`[${escapedDesc}]`);
+        // Add value completion if flag takes a value
+        if (flag.takesValue) {
+            if (flag.values && flag.values.length > 0) {
+                // Provide specific value completions
+                const valueList = flag.values.map(v => this.escapeValue(v)).join(' ');
+                parts.push(`:value:(${valueList})`);
+            }
+            else {
+                // Generic value placeholder
+                parts.push(':value:');
+            }
+        }
+        // Close the quote (needed for both short and long forms)
+        parts.push("'");
+        return parts.join('');
+    }
+    /**
+     * Generate positional argument specification
+     */
+    generatePositionalSpec(positionalType) {
+        switch (positionalType) {
+            case 'change-id':
+                return "'*: :_openspec_complete_changes'";
+            case 'spec-id':
+                return "'*: :_openspec_complete_specs'";
+            case 'change-or-spec-id':
+                return "'*: :_openspec_complete_items'";
+            case 'path':
+                return "'*:path:_files'";
+            case 'shell':
+                return "'*:shell:(zsh bash fish powershell)'";
+            default:
+                return "'*: :_default'";
+        }
+    }
+    /**
+     * Escape special characters in descriptions
+     */
+    escapeDescription(desc) {
+        return desc
+            .replace(/\\/g, '\\\\')
+            .replace(/'/g, "\\'")
+            .replace(/\[/g, '\\[')
+            .replace(/]/g, '\\]')
+            .replace(/:/g, '\\:');
+    }
+    /**
+     * Escape special characters in values
+     */
+    escapeValue(value) {
+        return value
+            .replace(/\\/g, '\\\\')
+            .replace(/'/g, "\\'")
+            .replace(/ /g, '\\ ');
+    }
+    /**
+     * Sanitize command names for use in function names
+     */
+    sanitizeFunctionName(name) {
+        return name.replace(/-/g, '_');
+    }
+}
+//# sourceMappingURL=zsh-generator.js.map

package/dist/core/completions/installers/bash-installer.d.ts

@@ -0,0 +1,87 @@
+import { InstallationResult } from '../factory.js';
+/**
+ * Installer for Bash completion scripts.
+ * Supports bash-completion package and standalone installations.
+ */
+export declare class BashInstaller {
+    private readonly homeDir;
+    /**
+     * Markers for .bashrc configuration management
+     */
+    private readonly BASHRC_MARKERS;
+    constructor(homeDir?: string);
+    /**
+     * Check if bash-completion is installed
+     *
+     * @returns true if bash-completion directories exist
+     */
+    isBashCompletionInstalled(): Promise<boolean>;
+    /**
+     * Get the appropriate installation path for the completion script
+     *
+     * @returns Installation path
+     */
+    getInstallationPath(): Promise<string>;
+    /**
+     * Backup an existing completion file if it exists
+     *
+     * @param targetPath - Path to the file to backup
+     * @returns Path to the backup file, or undefined if no backup was needed
+     */
+    backupExistingFile(targetPath: string): Promise<string | undefined>;
+    /**
+     * Get the path to .bashrc file
+     *
+     * @returns Path to .bashrc
+     */
+    private getBashrcPath;
+    /**
+     * Generate .bashrc configuration content
+     *
+     * @param completionsDir - Directory containing completion scripts
+     * @returns Configuration content
+     */
+    private generateBashrcConfig;
+    /**
+     * Configure .bashrc to enable completions
+     *
+     * @param completionsDir - Directory containing completion scripts
+     * @returns true if configured successfully, false otherwise
+     */
+    configureBashrc(completionsDir: string): Promise<boolean>;
+    /**
+     * Remove .bashrc configuration
+     * Used during uninstallation
+     *
+     * @returns true if removed successfully, false otherwise
+     */
+    removeBashrcConfig(): Promise<boolean>;
+    /**
+     * Install the completion script
+     *
+     * @param completionScript - The completion script content to install
+     * @returns Installation result with status and instructions
+     */
+    install(completionScript: string): Promise<InstallationResult>;
+    /**
+     * Generate user instructions for enabling completions
+     *
+     * @param installedPath - Path where the script was installed
+     * @returns Array of instruction strings
+     */
+    private generateInstructions;
+    /**
+     * Uninstall the completion script
+     *
+     * @param options - Optional uninstall options
+     * @param options.yes - Skip confirmation prompt (handled by command layer)
+     * @returns Uninstallation result
+     */
+    uninstall(options?: {
+        yes?: boolean;
+    }): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+}
+//# sourceMappingURL=bash-installer.d.ts.map