@dynamicworks/br-openspec 1.3.1

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

@@ -0,0 +1,319 @@
+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 Bash completion scripts.
+ * Supports bash-completion package and standalone installations.
+ */
+export class BashInstaller {
+    homeDir;
+    /**
+     * Markers for .bashrc configuration management
+     */
+    BASHRC_MARKERS = {
+        start: '# OPENSPEC:START',
+        end: '# OPENSPEC:END',
+    };
+    constructor(homeDir = os.homedir()) {
+        this.homeDir = homeDir;
+    }
+    /**
+     * Check if bash-completion is installed
+     *
+     * @returns true if bash-completion directories exist
+     */
+    async isBashCompletionInstalled() {
+        const paths = [
+            '/usr/share/bash-completion', // Linux system-wide
+            '/usr/local/share/bash-completion', // Homebrew Intel (main)
+            '/opt/homebrew/etc/bash_completion.d', // Homebrew Apple Silicon
+            '/usr/local/etc/bash_completion.d', // Homebrew Intel (alt path)
+            '/etc/bash_completion.d', // Legacy fallback
+        ];
+        for (const p of paths) {
+            try {
+                const stat = await fs.stat(p);
+                if (stat.isDirectory()) {
+                    return true;
+                }
+            }
+            catch {
+                // Continue checking other paths
+            }
+        }
+        return false;
+    }
+    /**
+     * Get the appropriate installation path for the completion script
+     *
+     * @returns Installation path
+     */
+    async getInstallationPath() {
+        // Try user-local bash-completion directory first
+        const localCompletionDir = path.join(this.homeDir, '.local', 'share', 'bash-completion', 'completions');
+        // For user installation, use local directory
+        return path.join(localCompletionDir, 'openspec');
+    }
+    /**
+     * 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 .bashrc file
+     *
+     * @returns Path to .bashrc
+     */
+    getBashrcPath() {
+        return path.join(this.homeDir, '.bashrc');
+    }
+    /**
+     * Generate .bashrc configuration content
+     *
+     * @param completionsDir - Directory containing completion scripts
+     * @returns Configuration content
+     */
+    generateBashrcConfig(completionsDir) {
+        return [
+            '# BR-OpenSpec shell completions configuration',
+            `if [ -d "${completionsDir}" ]; then`,
+            `  for f in "${completionsDir}"/*; do`,
+            '    [ -f "$f" ] && . "$f"',
+            '  done',
+            'fi',
+        ].join('\n');
+    }
+    /**
+     * Configure .bashrc to enable completions
+     *
+     * @param completionsDir - Directory containing completion scripts
+     * @returns true if configured successfully, false otherwise
+     */
+    async configureBashrc(completionsDir) {
+        // Check if auto-configuration is disabled
+        if (process.env.OPENSPEC_NO_AUTO_CONFIG === '1') {
+            return false;
+        }
+        try {
+            const bashrcPath = this.getBashrcPath();
+            const config = this.generateBashrcConfig(completionsDir);
+            // Check write permissions
+            const canWrite = await FileSystemUtils.canWriteFile(bashrcPath);
+            if (!canWrite) {
+                return false;
+            }
+            // Use marker-based update
+            await FileSystemUtils.updateFileWithMarkers(bashrcPath, config, this.BASHRC_MARKERS.start, this.BASHRC_MARKERS.end);
+            return true;
+        }
+        catch (error) {
+            // Fail gracefully - don't break installation
+            console.debug(`Unable to configure .bashrc for completions: ${error.message}`);
+            return false;
+        }
+    }
+    /**
+     * Remove .bashrc configuration
+     * Used during uninstallation
+     *
+     * @returns true if removed successfully, false otherwise
+     */
+    async removeBashrcConfig() {
+        try {
+            const bashrcPath = this.getBashrcPath();
+            // Check if file exists
+            try {
+                await fs.access(bashrcPath);
+            }
+            catch {
+                // File doesn't exist, nothing to remove
+                return true;
+            }
+            // Read file content
+            const content = await fs.readFile(bashrcPath, 'utf-8');
+            // Check if markers exist
+            if (!content.includes(this.BASHRC_MARKERS.start) || !content.includes(this.BASHRC_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.BASHRC_MARKERS.start);
+            const endIndex = lines.findIndex((line) => line.trim() === this.BASHRC_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
+            while (lines.length > 0 && lines[lines.length - 1].trim() === '') {
+                lines.pop();
+            }
+            // Write back
+            await fs.writeFile(bashrcPath, lines.join('\n'), 'utf-8');
+            return true;
+        }
+        catch (error) {
+            // Fail gracefully
+            console.debug(`Unable to remove .bashrc 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 targetPath = await this.getInstallationPath();
+            // Check for bash-completion package
+            const hasBashCompletion = await this.isBashCompletionInstalled();
+            // 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,
+                        message: COMPLETION_MESSAGES.bashAlreadyInstalled,
+                        instructions: [
+                            COMPLETION_MESSAGES.bashAlreadyInstalledDetail,
+                            COMPLETION_MESSAGES.bashAlreadyInstalledHint,
+                        ],
+                    };
+                }
+                // 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 .bashrc
+            const bashrcConfigured = await this.configureBashrc(targetDir);
+            // Generate instructions if .bashrc wasn't auto-configured
+            const instructions = bashrcConfigured ? undefined : this.generateInstructions(targetPath);
+            // Collect warnings
+            const warnings = [];
+            if (!hasBashCompletion) {
+                warnings.push(COMPLETION_MESSAGES.bashCompletionNotDetected, '', COMPLETION_MESSAGES.bashCompletionRequired, COMPLETION_MESSAGES.installWith, '  brew install bash-completion@2', '', COMPLETION_MESSAGES.addToBashProfile, '  [[ -r "/opt/homebrew/etc/profile.d/bash_completion.sh" ]] && . "/opt/homebrew/etc/profile.d/bash_completion.sh"');
+            }
+            // Determine appropriate message
+            let message;
+            if (isUpdate) {
+                message = backupPath
+                    ? COMPLETION_MESSAGES.bashUpdatedWithBackup
+                    : COMPLETION_MESSAGES.bashUpdated;
+            }
+            else {
+                message = bashrcConfigured
+                    ? COMPLETION_MESSAGES.bashInstalledWithBashrc
+                    : COMPLETION_MESSAGES.bashInstalled;
+            }
+            return {
+                success: true,
+                installedPath: targetPath,
+                backupPath,
+                bashrcConfigured,
+                message,
+                instructions,
+                warnings: warnings.length > 0 ? warnings : undefined,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: COMPLETION_MESSAGES.bashFailedToInstall(error instanceof Error ? error.message : String(error)),
+            };
+        }
+    }
+    /**
+     * Generate user instructions for enabling completions
+     *
+     * @param installedPath - Path where the script was installed
+     * @returns Array of instruction strings
+     */
+    generateInstructions(installedPath) {
+        const completionsDir = path.dirname(installedPath);
+        return [
+            COMPLETION_MESSAGES.bashScriptInstalled,
+            '',
+            COMPLETION_MESSAGES.bashAddToBashrc,
+            '',
+            `  ${COMPLETION_MESSAGES.bashSourceComment}`,
+            `  if [ -d "${completionsDir}" ]; then`,
+            `    for f in "${completionsDir}"/*; do`,
+            '      [ -f "$f" ] && . "$f"',
+            '    done',
+            '  fi',
+            '',
+            COMPLETION_MESSAGES.bashThenRestartShell('exec bash'),
+        ];
+    }
+    /**
+     * Uninstall the completion script
+     *
+     * @param options - Optional uninstall options
+     * @param options.yes - Skip confirmation prompt (handled by command layer)
+     * @returns Uninstallation result
+     */
+    async uninstall(options) {
+        try {
+            const targetPath = await this.getInstallationPath();
+            // Check if installed
+            try {
+                await fs.access(targetPath);
+            }
+            catch {
+                return {
+                    success: false,
+                    message: COMPLETION_MESSAGES.bashNotInstalled,
+                };
+            }
+            // Remove the completion script
+            await fs.unlink(targetPath);
+            // Remove .bashrc configuration
+            await this.removeBashrcConfig();
+            return {
+                success: true,
+                message: COMPLETION_MESSAGES.bashUninstalled,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: COMPLETION_MESSAGES.bashFailedToUninstall(error instanceof Error ? error.message : String(error)),
+            };
+        }
+    }
+}
+//# sourceMappingURL=bash-installer.js.map

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

@@ -0,0 +1,43 @@
+import { InstallationResult } from '../factory.js';
+/**
+ * Installer for Fish completion scripts.
+ * Fish automatically loads completions from ~/.config/fish/completions/
+ */
+export declare class FishInstaller {
+    private readonly homeDir;
+    constructor(homeDir?: string);
+    /**
+     * Get the installation path for Fish completions
+     *
+     * @returns Installation path
+     */
+    getInstallationPath(): 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>;
+    /**
+     * Install the completion script
+     *
+     * @param completionScript - The completion script content to install
+     * @returns Installation result with status and instructions
+     */
+    install(completionScript: string): Promise<InstallationResult>;
+    /**
+     * 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=fish-installer.d.ts.map

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

@@ -0,0 +1,143 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+/**
+ * Installer for Fish completion scripts.
+ * Fish automatically loads completions from ~/.config/fish/completions/
+ */
+export class FishInstaller {
+    homeDir;
+    constructor(homeDir = os.homedir()) {
+        this.homeDir = homeDir;
+    }
+    /**
+     * Get the installation path for Fish completions
+     *
+     * @returns Installation path
+     */
+    getInstallationPath() {
+        return path.join(this.homeDir, '.config', 'fish', 'completions', 'openspec.fish');
+    }
+    /**
+     * 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;
+        }
+    }
+    /**
+     * Install the completion script
+     *
+     * @param completionScript - The completion script content to install
+     * @returns Installation result with status and instructions
+     */
+    async install(completionScript) {
+        try {
+            const targetPath = 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,
+                        message: 'Completion script is already installed (up to date)',
+                        instructions: [
+                            'The completion script is already installed and up to date.',
+                            'Fish automatically loads completions - they should be available immediately.',
+                        ],
+                    };
+                }
+                // 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');
+            // Determine appropriate message
+            let message;
+            if (isUpdate) {
+                message = backupPath
+                    ? 'Completion script updated successfully (previous version backed up)'
+                    : 'Completion script updated successfully';
+            }
+            else {
+                message = 'Completion script installed successfully for Fish';
+            }
+            return {
+                success: true,
+                installedPath: targetPath,
+                backupPath,
+                message,
+                instructions: [
+                    'Fish automatically loads completions from ~/.config/fish/completions/',
+                    'Completions are available immediately - no shell restart needed.',
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to install completion script: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    /**
+     * Uninstall the completion script
+     *
+     * @param options - Optional uninstall options
+     * @param options.yes - Skip confirmation prompt (handled by command layer)
+     * @returns Uninstallation result
+     */
+    async uninstall(options) {
+        try {
+            const targetPath = this.getInstallationPath();
+            // Check if installed
+            try {
+                await fs.access(targetPath);
+            }
+            catch {
+                return {
+                    success: false,
+                    message: 'Completion script is not installed',
+                };
+            }
+            // Remove the completion script
+            await fs.unlink(targetPath);
+            return {
+                success: true,
+                message: 'Completion script uninstalled successfully',
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to uninstall completion script: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+}
+//# sourceMappingURL=fish-installer.js.map

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

@@ -0,0 +1,102 @@
+import { InstallationResult } from '../factory.js';
+/**
+ * Installer for PowerShell completion scripts.
+ * Works with both Windows PowerShell 5.1 and PowerShell Core 7+
+ */
+export declare class PowerShellInstaller {
+    private readonly homeDir;
+    /**
+     * Markers for PowerShell profile configuration management
+     */
+    private readonly PROFILE_MARKERS;
+    constructor(homeDir?: string);
+    /**
+     * Detect the encoding of a file by inspecting its BOM (Byte Order Mark).
+     * Returns the Node.js BufferEncoding and the raw BOM bytes to preserve on write.
+     */
+    private detectEncoding;
+    /**
+     * Read a profile file, preserving its encoding metadata for round-trip writes.
+     * Throws if the file uses UTF-16 BE (unsupported by Node).
+     */
+    private readProfileFile;
+    /**
+     * Write a profile file, preserving the original BOM and encoding.
+     */
+    private writeProfileFile;
+    /**
+     * Get PowerShell profile path
+     * Prefers $PROFILE environment variable, falls back to platform defaults
+     *
+     * @returns Profile path
+     */
+    getProfilePath(): string;
+    /**
+     * Get all PowerShell profile paths to configure.
+     * On Windows, returns both PowerShell Core and Windows PowerShell 5.1 paths.
+     * On Unix, returns PowerShell Core path only.
+     */
+    private getAllProfilePaths;
+    /**
+     * Get the installation path for the completion script
+     *
+     * @returns Installation path
+     */
+    getInstallationPath(): 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>;
+    /**
+     * Generate PowerShell profile configuration content
+     *
+     * @param scriptPath - Path to the completion script
+     * @returns Configuration content
+     */
+    private generateProfileConfig;
+    /**
+     * Configure PowerShell profile to source the completion script
+     *
+     * @param scriptPath - Path to the completion script
+     * @returns true if configured successfully, false otherwise
+     */
+    configureProfile(scriptPath: string): Promise<boolean>;
+    /**
+     * Remove PowerShell profile configuration
+     * Used during uninstallation
+     *
+     * @returns true if removed successfully, false otherwise
+     */
+    removeProfileConfig(): 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=powershell-installer.d.ts.map