@dynamicworks/br-openspec 1.3.1

package/dist/core/completions/installers/zsh-installer.js

@@ -0,0 +1,450 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import { FileSystemUtils } from '../../../utils/file-system.js';
+import { COMPLETION_MESSAGES } from '../../../messages/index.js';
+/**
+ * Installer for Zsh completion scripts.
+ * Supports both Oh My Zsh and standard Zsh configurations.
+ */
+export class ZshInstaller {
+    homeDir;
+    /**
+     * Markers for .zshrc configuration management
+     */
+    ZSHRC_MARKERS = {
+        start: '# OPENSPEC:START',
+        end: '# OPENSPEC:END',
+    };
+    constructor(homeDir = os.homedir()) {
+        this.homeDir = homeDir;
+    }
+    /**
+     * Check if Oh My Zsh is installed
+     *
+     * @returns true if Oh My Zsh is detected via $ZSH env var or directory exists
+     */
+    async isOhMyZshInstalled() {
+        // First check for $ZSH environment variable (standard OMZ setup)
+        if (process.env.ZSH) {
+            return true;
+        }
+        // Fall back to checking for ~/.oh-my-zsh directory
+        const ohMyZshPath = path.join(this.homeDir, '.oh-my-zsh');
+        try {
+            const stat = await fs.stat(ohMyZshPath);
+            return stat.isDirectory();
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get the appropriate installation path for the completion script
+     *
+     * @returns Object with installation path and whether it's Oh My Zsh
+     */
+    async getInstallationPath() {
+        const isOhMyZsh = await this.isOhMyZshInstalled();
+        if (isOhMyZsh) {
+            // Oh My Zsh custom completions directory
+            return {
+                path: path.join(this.homeDir, '.oh-my-zsh', 'custom', 'completions', '_openspec'),
+                isOhMyZsh: true,
+            };
+        }
+        else {
+            // Standard Zsh completions directory
+            return {
+                path: path.join(this.homeDir, '.zsh', 'completions', '_openspec'),
+                isOhMyZsh: false,
+            };
+        }
+    }
+    /**
+     * 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
+     */
+    async backupExistingFile(targetPath) {
+        try {
+            await fs.access(targetPath);
+            // File exists, create a backup
+            const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+            const backupPath = `${targetPath}.backup-${timestamp}`;
+            await fs.copyFile(targetPath, backupPath);
+            return backupPath;
+        }
+        catch {
+            // File doesn't exist, no backup needed
+            return undefined;
+        }
+    }
+    /**
+     * Get the path to .zshrc file
+     *
+     * @returns Path to .zshrc
+     */
+    getZshrcPath() {
+        return path.join(this.homeDir, '.zshrc');
+    }
+    /**
+     * Generate .zshrc configuration content
+     *
+     * @param completionsDir - Directory containing completion scripts
+     * @returns Configuration content
+     */
+    generateZshrcConfig(completionsDir) {
+        return [
+            '# BR-OpenSpec shell completions configuration',
+            `fpath=("${completionsDir}" $fpath)`,
+            'autoload -Uz compinit',
+            'compinit',
+        ].join('\n');
+    }
+    /**
+     * Configure .zshrc to enable completions
+     * Only applies to standard Zsh (not Oh My Zsh)
+     *
+     * @param completionsDir - Directory containing completion scripts
+     * @returns true if configured successfully, false otherwise
+     */
+    async configureZshrc(completionsDir) {
+        // Check if auto-configuration is disabled
+        if (process.env.OPENSPEC_NO_AUTO_CONFIG === '1') {
+            return false;
+        }
+        try {
+            const zshrcPath = this.getZshrcPath();
+            const config = this.generateZshrcConfig(completionsDir);
+            // Check write permissions
+            const canWrite = await FileSystemUtils.canWriteFile(zshrcPath);
+            if (!canWrite) {
+                return false;
+            }
+            // Use marker-based update
+            await FileSystemUtils.updateFileWithMarkers(zshrcPath, config, this.ZSHRC_MARKERS.start, this.ZSHRC_MARKERS.end);
+            return true;
+        }
+        catch (error) {
+            // Fail gracefully - don't break installation
+            console.debug(`Unable to configure .zshrc for completions: ${error.message}`);
+            return false;
+        }
+    }
+    /**
+     * Check if .zshrc has OpenSpec configuration markers
+     *
+     * @returns true if .zshrc exists and has markers
+     */
+    async hasZshrcConfig() {
+        try {
+            const zshrcPath = this.getZshrcPath();
+            const content = await fs.readFile(zshrcPath, 'utf-8');
+            return content.includes(this.ZSHRC_MARKERS.start) && content.includes(this.ZSHRC_MARKERS.end);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Check if fpath configuration is needed for a given directory
+     * Used to verify if Oh My Zsh (or other) completions directory is already in fpath
+     *
+     * @param completionsDir - Directory to check for in fpath
+     * @returns true if configuration is needed, false if directory is already referenced
+     */
+    async needsFpathConfig(completionsDir) {
+        try {
+            const zshrcPath = this.getZshrcPath();
+            const content = await fs.readFile(zshrcPath, 'utf-8');
+            // Check if fpath already includes this directory
+            return !content.includes(completionsDir);
+        }
+        catch (error) {
+            // If we can't read .zshrc, assume config is needed
+            console.debug(`Unable to read .zshrc to check fpath config: ${error instanceof Error ? error.message : String(error)}`);
+            return true;
+        }
+    }
+    /**
+     * Remove .zshrc configuration
+     * Used during uninstallation
+     *
+     * @returns true if removed successfully, false otherwise
+     */
+    async removeZshrcConfig() {
+        try {
+            const zshrcPath = this.getZshrcPath();
+            // Check if file exists
+            try {
+                await fs.access(zshrcPath);
+            }
+            catch {
+                // File doesn't exist, nothing to remove
+                return true;
+            }
+            // Read file content
+            const content = await fs.readFile(zshrcPath, 'utf-8');
+            // Check if markers exist
+            if (!content.includes(this.ZSHRC_MARKERS.start) || !content.includes(this.ZSHRC_MARKERS.end)) {
+                // Markers don't exist, nothing to remove
+                return true;
+            }
+            // Remove content between markers (including markers)
+            const lines = content.split('\n');
+            const startIndex = lines.findIndex((line) => line.trim() === this.ZSHRC_MARKERS.start);
+            const endIndex = lines.findIndex((line) => line.trim() === this.ZSHRC_MARKERS.end);
+            if (startIndex === -1 || endIndex === -1 || endIndex < startIndex) {
+                // Invalid marker placement
+                return false;
+            }
+            // Remove lines between markers (inclusive)
+            lines.splice(startIndex, endIndex - startIndex + 1);
+            // Remove trailing empty lines at the start if the markers were at the top
+            while (lines.length > 0 && lines[0].trim() === '') {
+                lines.shift();
+            }
+            // Write back
+            await fs.writeFile(zshrcPath, lines.join('\n'), 'utf-8');
+            return true;
+        }
+        catch (error) {
+            // Fail gracefully
+            console.debug(`Unable to remove .zshrc configuration: ${error.message}`);
+            return false;
+        }
+    }
+    /**
+     * Install the completion script
+     *
+     * @param completionScript - The completion script content to install
+     * @returns Installation result with status and instructions
+     */
+    async install(completionScript) {
+        try {
+            const { path: targetPath, isOhMyZsh } = await this.getInstallationPath();
+            // Check if already installed with same content
+            let isUpdate = false;
+            try {
+                const existingContent = await fs.readFile(targetPath, 'utf-8');
+                if (existingContent === completionScript) {
+                    // Already installed and up to date
+                    return {
+                        success: true,
+                        installedPath: targetPath,
+                        isOhMyZsh,
+                        message: COMPLETION_MESSAGES.zshAlreadyInstalled,
+                        instructions: [
+                            COMPLETION_MESSAGES.zshAlreadyInstalledDetail,
+                            COMPLETION_MESSAGES.zshAlreadyInstalledHint,
+                        ],
+                    };
+                }
+                // File exists but content is different - this is an update
+                isUpdate = true;
+            }
+            catch (error) {
+                // File doesn't exist or can't be read, proceed with installation
+                console.debug(`Unable to read existing completion file at ${targetPath}: ${error.message}`);
+            }
+            // Ensure the directory exists
+            const targetDir = path.dirname(targetPath);
+            await fs.mkdir(targetDir, { recursive: true });
+            // Backup existing file if updating
+            const backupPath = isUpdate ? await this.backupExistingFile(targetPath) : undefined;
+            // Write the completion script
+            await fs.writeFile(targetPath, completionScript, 'utf-8');
+            // Auto-configure .zshrc
+            let zshrcConfigured = false;
+            if (isOhMyZsh) {
+                // For Oh My Zsh, verify that custom/completions is in fpath
+                // If not, add it to .zshrc
+                const needsConfig = await this.needsFpathConfig(targetDir);
+                if (needsConfig) {
+                    zshrcConfigured = await this.configureZshrc(targetDir);
+                }
+            }
+            else {
+                // Standard Zsh always needs .zshrc configuration
+                zshrcConfigured = await this.configureZshrc(targetDir);
+            }
+            // Generate instructions (only if .zshrc wasn't auto-configured)
+            let instructions = zshrcConfigured ? undefined : this.generateInstructions(isOhMyZsh, targetPath);
+            // Add fpath guidance for Oh My Zsh installations
+            if (isOhMyZsh) {
+                const fpathGuidance = this.generateOhMyZshFpathGuidance(targetDir);
+                if (fpathGuidance) {
+                    instructions = instructions ? [...instructions, '', ...fpathGuidance] : fpathGuidance;
+                }
+            }
+            // Determine appropriate message based on update status
+            let message;
+            if (isUpdate) {
+                message = backupPath
+                    ? COMPLETION_MESSAGES.zshUpdatedWithBackup
+                    : COMPLETION_MESSAGES.zshUpdated;
+            }
+            else {
+                message = isOhMyZsh
+                    ? COMPLETION_MESSAGES.zshInstalledOhMyZsh
+                    : zshrcConfigured
+                        ? COMPLETION_MESSAGES.zshInstalledWithZshrc
+                        : COMPLETION_MESSAGES.zshInstalled;
+            }
+            return {
+                success: true,
+                installedPath: targetPath,
+                backupPath,
+                isOhMyZsh,
+                zshrcConfigured,
+                message,
+                instructions,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                isOhMyZsh: false,
+                message: COMPLETION_MESSAGES.zshFailedToInstall(error instanceof Error ? error.message : String(error)),
+            };
+        }
+    }
+    /**
+     * Generate Oh My Zsh fpath verification guidance
+     *
+     * @param completionsDir - Custom completions directory path
+     * @returns Array of guidance strings, or undefined if not needed
+     */
+    generateOhMyZshFpathGuidance(completionsDir) {
+        return [
+            COMPLETION_MESSAGES.zshOhMyZshFpathNote,
+            COMPLETION_MESSAGES.zshOhMyZshFpathVerify(completionsDir),
+            '  echo $fpath | grep "custom/completions"',
+            '',
+            COMPLETION_MESSAGES.zshOhMyZshFpathRestart,
+        ];
+    }
+    /**
+     * Generate user instructions for enabling completions
+     *
+     * @param isOhMyZsh - Whether Oh My Zsh is being used
+     * @param installedPath - Path where the script was installed
+     * @returns Array of instruction strings
+     */
+    generateInstructions(isOhMyZsh, installedPath) {
+        if (isOhMyZsh) {
+            return [
+                COMPLETION_MESSAGES.zshOhMyZshInstalledDir,
+                COMPLETION_MESSAGES.restartShell('exec zsh'),
+                COMPLETION_MESSAGES.zshOhMyZshAutoActivate,
+            ];
+        }
+        else {
+            const completionsDir = path.dirname(installedPath);
+            const zshrcPath = path.join(this.homeDir, '.zshrc');
+            return [
+                COMPLETION_MESSAGES.zshInstalledDir,
+                '',
+                COMPLETION_MESSAGES.zshAddToZshrc,
+                '',
+                `  ${COMPLETION_MESSAGES.zshFpathComment}`,
+                `  fpath=(${completionsDir} $fpath)`,
+                '',
+                `  ${COMPLETION_MESSAGES.zshCompinitComment}`,
+                '  autoload -Uz compinit',
+                '  compinit',
+                '',
+                COMPLETION_MESSAGES.zshThenRestartShell('exec zsh'),
+                '',
+                COMPLETION_MESSAGES.zshCheckExistingLines(zshrcPath),
+            ];
+        }
+    }
+    /**
+     * Uninstall the completion script
+     *
+     * @returns true if uninstalled successfully, false otherwise
+     */
+    async uninstall() {
+        try {
+            const { path: targetPath, isOhMyZsh } = await this.getInstallationPath();
+            // Try to remove completion script
+            let scriptRemoved = false;
+            try {
+                await fs.access(targetPath);
+                await fs.unlink(targetPath);
+                scriptRemoved = true;
+            }
+            catch {
+                // Script not installed
+            }
+            // Try to remove .zshrc configuration (only for standard Zsh)
+            let zshrcWasPresent = false;
+            let zshrcCleaned = false;
+            if (!isOhMyZsh) {
+                zshrcWasPresent = await this.hasZshrcConfig();
+                if (zshrcWasPresent) {
+                    zshrcCleaned = await this.removeZshrcConfig();
+                }
+            }
+            if (!scriptRemoved && !zshrcWasPresent) {
+                return {
+                    success: false,
+                    message: 'Completion script is not installed',
+                };
+            }
+            const messages = [];
+            if (scriptRemoved) {
+                messages.push(COMPLETION_MESSAGES.zshScriptRemoved(targetPath));
+            }
+            if (zshrcCleaned && !isOhMyZsh) {
+                messages.push(COMPLETION_MESSAGES.zshConfigRemoved);
+            }
+            return {
+                success: true,
+                message: messages.join('. '),
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: COMPLETION_MESSAGES.failedToUninstall(error instanceof Error ? error.message : String(error)),
+            };
+        }
+    }
+    /**
+     * Check if completion script is currently installed
+     *
+     * @returns true if the completion script exists
+     */
+    async isInstalled() {
+        try {
+            const { path: targetPath } = await this.getInstallationPath();
+            await fs.access(targetPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get information about the current installation
+     *
+     * @returns Installation status information
+     */
+    async getInstallationInfo() {
+        const installed = await this.isInstalled();
+        if (!installed) {
+            return { installed: false };
+        }
+        const { path: targetPath, isOhMyZsh } = await this.getInstallationPath();
+        return {
+            installed: true,
+            path: targetPath,
+            isOhMyZsh,
+        };
+    }
+}
+//# sourceMappingURL=zsh-installer.js.map

package/dist/core/completions/templates/bash-templates.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Static template strings for Bash completion scripts.
+ * These are Bash-specific helper functions that never change.
+ */
+export declare const BASH_DYNAMIC_HELPERS = "# Dynamic completion helpers\n\n_openspec_complete_changes() {\n  local changes\n  changes=$(openspec __complete changes 2>/dev/null | cut -f1)\n  COMPREPLY=($(compgen -W \"$changes\" -- \"$cur\"))\n}\n\n_openspec_complete_specs() {\n  local specs\n  specs=$(openspec __complete specs 2>/dev/null | cut -f1)\n  COMPREPLY=($(compgen -W \"$specs\" -- \"$cur\"))\n}\n\n_openspec_complete_items() {\n  local items\n  items=$(openspec __complete changes 2>/dev/null | cut -f1; openspec __complete specs 2>/dev/null | cut -f1)\n  COMPREPLY=($(compgen -W \"$items\" -- \"$cur\"))\n}";
+//# sourceMappingURL=bash-templates.d.ts.map

package/dist/core/completions/templates/bash-templates.js

@@ -0,0 +1,24 @@
+/**
+ * Static template strings for Bash completion scripts.
+ * These are Bash-specific helper functions that never change.
+ */
+export const BASH_DYNAMIC_HELPERS = `# Dynamic completion helpers
+
+_openspec_complete_changes() {
+  local changes
+  changes=$(openspec __complete changes 2>/dev/null | cut -f1)
+  COMPREPLY=($(compgen -W "$changes" -- "$cur"))
+}
+
+_openspec_complete_specs() {
+  local specs
+  specs=$(openspec __complete specs 2>/dev/null | cut -f1)
+  COMPREPLY=($(compgen -W "$specs" -- "$cur"))
+}
+
+_openspec_complete_items() {
+  local items
+  items=$(openspec __complete changes 2>/dev/null | cut -f1; openspec __complete specs 2>/dev/null | cut -f1)
+  COMPREPLY=($(compgen -W "$items" -- "$cur"))
+}`;
+//# sourceMappingURL=bash-templates.js.map

package/dist/core/completions/templates/fish-templates.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Static template strings for Fish completion scripts.
+ * These are Fish-specific helper functions that never change.
+ */
+export declare const FISH_STATIC_HELPERS = "# Helper function to check if a subcommand is present\nfunction __fish_openspec_using_subcommand\n    set -l cmd (commandline -opc)\n    set -e cmd[1]\n    for i in $argv\n        if contains -- $i $cmd\n            return 0\n        end\n    end\n    return 1\nend\n\nfunction __fish_openspec_no_subcommand\n    set -l cmd (commandline -opc)\n    test (count $cmd) -eq 1\nend";
+export declare const FISH_DYNAMIC_HELPERS = "# Dynamic completion helpers\n\nfunction __fish_openspec_changes\n    openspec __complete changes 2>/dev/null | while read -l id desc\n        printf '%s\\t%s\\n' \"$id\" \"$desc\"\n    end\nend\n\nfunction __fish_openspec_specs\n    openspec __complete specs 2>/dev/null | while read -l id desc\n        printf '%s\\t%s\\n' \"$id\" \"$desc\"\n    end\nend\n\nfunction __fish_openspec_items\n    __fish_openspec_changes\n    __fish_openspec_specs\nend";
+//# sourceMappingURL=fish-templates.d.ts.map

package/dist/core/completions/templates/fish-templates.js

@@ -0,0 +1,39 @@
+/**
+ * Static template strings for Fish completion scripts.
+ * These are Fish-specific helper functions that never change.
+ */
+export const FISH_STATIC_HELPERS = `# Helper function to check if a subcommand is present
+function __fish_openspec_using_subcommand
+    set -l cmd (commandline -opc)
+    set -e cmd[1]
+    for i in $argv
+        if contains -- $i $cmd
+            return 0
+        end
+    end
+    return 1
+end
+
+function __fish_openspec_no_subcommand
+    set -l cmd (commandline -opc)
+    test (count $cmd) -eq 1
+end`;
+export const FISH_DYNAMIC_HELPERS = `# Dynamic completion helpers
+
+function __fish_openspec_changes
+    openspec __complete changes 2>/dev/null | while read -l id desc
+        printf '%s\\t%s\\n' "$id" "$desc"
+    end
+end
+
+function __fish_openspec_specs
+    openspec __complete specs 2>/dev/null | while read -l id desc
+        printf '%s\\t%s\\n' "$id" "$desc"
+    end
+end
+
+function __fish_openspec_items
+    __fish_openspec_changes
+    __fish_openspec_specs
+end`;
+//# sourceMappingURL=fish-templates.js.map

package/dist/core/completions/templates/powershell-templates.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Static template strings for PowerShell completion scripts.
+ * These are PowerShell-specific helper functions that never change.
+ */
+export declare const POWERSHELL_DYNAMIC_HELPERS = "# Dynamic completion helpers\n\nfunction Get-BROpenSpecChanges {\n    $output = openspec __complete changes 2>$null\n    if ($output) {\n        $output | ForEach-Object {\n            ($_ -split \"\\t\")[0]\n        }\n    }\n}\n\nfunction Get-BROpenSpecSpecs {\n    $output = openspec __complete specs 2>$null\n    if ($output) {\n        $output | ForEach-Object {\n            ($_ -split \"\\t\")[0]\n        }\n    }\n}\n";
+//# sourceMappingURL=powershell-templates.d.ts.map

package/dist/core/completions/templates/powershell-templates.js

@@ -0,0 +1,25 @@
+/**
+ * Static template strings for PowerShell completion scripts.
+ * These are PowerShell-specific helper functions that never change.
+ */
+export const POWERSHELL_DYNAMIC_HELPERS = `# Dynamic completion helpers
+
+function Get-BROpenSpecChanges {
+    $output = openspec __complete changes 2>$null
+    if ($output) {
+        $output | ForEach-Object {
+            ($_ -split "\\t")[0]
+        }
+    }
+}
+
+function Get-BROpenSpecSpecs {
+    $output = openspec __complete specs 2>$null
+    if ($output) {
+        $output | ForEach-Object {
+            ($_ -split "\\t")[0]
+        }
+    }
+}
+`;
+//# sourceMappingURL=powershell-templates.js.map

package/dist/core/completions/templates/zsh-templates.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Static template strings for Zsh completion scripts.
+ * These are Zsh-specific helper functions that never change.
+ */
+export declare const ZSH_DYNAMIC_HELPERS = "# Dynamic completion helpers\n\n# Use openspec __complete to get available changes\n_openspec_complete_changes() {\n  local -a changes\n  while IFS=$'\\t' read -r id desc; do\n    changes+=(\"$id:$desc\")\n  done < <(openspec __complete changes 2>/dev/null)\n  _describe \"change\" changes\n}\n\n# Use openspec __complete to get available specs\n_openspec_complete_specs() {\n  local -a specs\n  while IFS=$'\\t' read -r id desc; do\n    specs+=(\"$id:$desc\")\n  done < <(openspec __complete specs 2>/dev/null)\n  _describe \"spec\" specs\n}\n\n# Get both changes and specs\n_openspec_complete_items() {\n  local -a items\n  while IFS=$'\\t' read -r id desc; do\n    items+=(\"$id:$desc\")\n  done < <(openspec __complete changes 2>/dev/null)\n  while IFS=$'\\t' read -r id desc; do\n    items+=(\"$id:$desc\")\n  done < <(openspec __complete specs 2>/dev/null)\n  _describe \"item\" items\n}";
+//# sourceMappingURL=zsh-templates.d.ts.map

package/dist/core/completions/templates/zsh-templates.js

@@ -0,0 +1,36 @@
+/**
+ * Static template strings for Zsh completion scripts.
+ * These are Zsh-specific helper functions that never change.
+ */
+export const ZSH_DYNAMIC_HELPERS = `# Dynamic completion helpers
+
+# Use openspec __complete to get available changes
+_openspec_complete_changes() {
+  local -a changes
+  while IFS=$'\\t' read -r id desc; do
+    changes+=("$id:$desc")
+  done < <(openspec __complete changes 2>/dev/null)
+  _describe "change" changes
+}
+
+# Use openspec __complete to get available specs
+_openspec_complete_specs() {
+  local -a specs
+  while IFS=$'\\t' read -r id desc; do
+    specs+=("$id:$desc")
+  done < <(openspec __complete specs 2>/dev/null)
+  _describe "spec" specs
+}
+
+# Get both changes and specs
+_openspec_complete_items() {
+  local -a items
+  while IFS=$'\\t' read -r id desc; do
+    items+=("$id:$desc")
+  done < <(openspec __complete changes 2>/dev/null)
+  while IFS=$'\\t' read -r id desc; do
+    items+=("$id:$desc")
+  done < <(openspec __complete specs 2>/dev/null)
+  _describe "item" items
+}`;
+//# sourceMappingURL=zsh-templates.js.map

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

@@ -0,0 +1,79 @@
+import { SupportedShell } from '../../utils/shell-detection.js';
+/**
+ * Definition of a command-line flag/option
+ */
+export interface FlagDefinition {
+    /**
+     * Flag name without dashes (e.g., "json", "strict", "no-interactive")
+     */
+    name: string;
+    /**
+     * Short flag name without dash (e.g., "y" for "-y")
+     */
+    short?: string;
+    /**
+     * Human-readable description of what the flag does
+     */
+    description: string;
+    /**
+     * Whether the flag takes an argument value
+     */
+    takesValue?: boolean;
+    /**
+     * Possible values for the flag (for completion suggestions)
+     */
+    values?: string[];
+}
+/**
+ * Definition of a CLI command
+ */
+export interface CommandDefinition {
+    /**
+     * Command name (e.g., "init", "validate", "show")
+     */
+    name: string;
+    /**
+     * Human-readable description of the command
+     */
+    description: string;
+    /**
+     * Flags/options supported by this command
+     */
+    flags: FlagDefinition[];
+    /**
+     * Subcommands (e.g., "change show", "spec validate")
+     */
+    subcommands?: CommandDefinition[];
+    /**
+     * Whether this command accepts a positional argument (e.g., item name, path)
+     */
+    acceptsPositional?: boolean;
+    /**
+     * Type of positional argument for dynamic completion
+     * - 'change-id': Complete with active change IDs
+     * - 'spec-id': Complete with spec IDs
+     * - 'change-or-spec-id': Complete with both changes and specs
+     * - 'path': Complete with file paths
+     * - 'shell': Complete with supported shell names
+     * - 'schema-name': Complete with available schema names
+     * - undefined: No specific completion
+     */
+    positionalType?: 'change-id' | 'spec-id' | 'change-or-spec-id' | 'path' | 'shell' | 'schema-name';
+}
+/**
+ * Interface for shell-specific completion script generators
+ */
+export interface CompletionGenerator {
+    /**
+     * The shell type this generator targets
+     */
+    readonly shell: SupportedShell;
+    /**
+     * Generate the completion script content
+     *
+     * @param commands - Command definitions to generate completions for
+     * @returns The shell-specific completion script as a string
+     */
+    generate(commands: CommandDefinition[]): string;
+}
+//# sourceMappingURL=types.d.ts.map