synarcx 0.1.0

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

@@ -0,0 +1,274 @@
+import { ZSH_DYNAMIC_HELPERS } from '../templates/zsh-templates.js';
+/**
+ * Generates Zsh completion scripts for the synarcx CLI.
+ * Follows Zsh completion system conventions using the _synarcx 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(`          _synarcx_${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 synarcx
+
+# Zsh completion script for synarcx CLI
+# Auto-generated - do not edit manually
+
+_synarcx() {
+  local context state line
+  typeset -A opt_args
+
+  local -a commands
+  commands=(
+${commandList}
+  )
+
+  _arguments -C \\
+    "1: :->command" \\
+    "*::arg:->args"
+
+  case $state in
+    command)
+      _describe "synarcx command" commands
+      ;;
+    args)
+      case $words[1] in
+${commandCases}
+      esac
+      ;;
+  esac
+}
+
+${commandFunctions}
+${helpers}
+compdef _synarcx synarcx
+`;
+    }
+    /**
+     * Generate completion function for a specific command
+     */
+    generateCommandFunction(cmd) {
+        const funcName = `_synarcx_${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(`          _synarcx_${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) + ' \\');
+            }
+            this.appendPositionalSpecs(lines, cmd);
+        }
+        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 = `_synarcx_${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) + ' \\');
+        }
+        this.appendPositionalSpecs(lines, subcmd);
+        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 "'*: :_synarcx_complete_changes'";
+            case 'spec-id':
+                return "'*: :_synarcx_complete_specs'";
+            case 'change-or-spec-id':
+                return "'*: :_synarcx_complete_items'";
+            case 'schema-name':
+                return "'*: :_synarcx_complete_schemas'";
+            case 'path':
+                return "'*:path:_files'";
+            case 'shell':
+                return "'*:shell:(zsh bash fish powershell)'";
+            default:
+                return "'*: :_default'";
+        }
+    }
+    appendPositionalSpecs(lines, cmd) {
+        const positionalSpecs = this.generatePositionalSpecs(cmd);
+        if (positionalSpecs.length === 0) {
+            if (lines[lines.length - 1].endsWith(' \\')) {
+                lines[lines.length - 1] = lines[lines.length - 1].slice(0, -2);
+            }
+            return;
+        }
+        for (const [index, spec] of positionalSpecs.entries()) {
+            const suffix = index === positionalSpecs.length - 1 ? '' : ' \\';
+            lines.push('    ' + spec + suffix);
+        }
+    }
+    generatePositionalSpecs(cmd) {
+        if (cmd.positionals && cmd.positionals.length > 0) {
+            return cmd.positionals.map((positional, index) => this.generateIndexedPositionalSpec(positional, index + 1));
+        }
+        if (cmd.acceptsPositional) {
+            return [this.generatePositionalSpec(cmd.positionalType)];
+        }
+        return [];
+    }
+    generateIndexedPositionalSpec(positional, index) {
+        const name = this.escapeDescription(positional.name);
+        const separator = positional.optional ? '::' : ':';
+        switch (positional.type) {
+            case 'change-id':
+                return `'${index}${separator}${name}:_synarcx_complete_changes'`;
+            case 'spec-id':
+                return `'${index}${separator}${name}:_synarcx_complete_specs'`;
+            case 'change-or-spec-id':
+                return `'${index}${separator}${name}:_synarcx_complete_items'`;
+            case 'schema-name':
+                return `'${index}${separator}${name}:_synarcx_complete_schemas'`;
+            case 'path':
+                return `'${index}${separator}${name}:_files'`;
+            case 'shell':
+                return `'${index}${separator}${name}:(zsh bash fish powershell)'`;
+            default:
+                return `'${index}${separator}${name}:'`;
+        }
+    }
+    /**
+     * 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

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

@@ -0,0 +1,318 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import { FileSystemUtils } from '../../../utils/file-system.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, 'synarcx');
+    }
+    /**
+     * 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 [
+            '# synarcx 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 script is already installed (up to date)',
+                        instructions: [
+                            'The completion script is already installed and up to date.',
+                            'If completions are not working, try: exec bash',
+                        ],
+                    };
+                }
+                // 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('⚠️  Warning: bash-completion package not detected', '', 'The completion script requires bash-completion to function.', 'Install it with:', '  brew install bash-completion@2', '', 'Then add to your ~/.bash_profile:', '  [[ -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 script updated successfully (previous version backed up)'
+                    : 'Completion script updated successfully';
+            }
+            else {
+                message = bashrcConfigured
+                    ? 'Completion script installed and .bashrc configured successfully'
+                    : 'Completion script installed successfully for Bash';
+            }
+            return {
+                success: true,
+                installedPath: targetPath,
+                backupPath,
+                bashrcConfigured,
+                message,
+                instructions,
+                warnings: warnings.length > 0 ? warnings : undefined,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to install completion script: ${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 script installed successfully.',
+            '',
+            'To enable completions, add the following to your ~/.bashrc file:',
+            '',
+            `  # Source synarcx completions`,
+            `  if [ -d "${completionsDir}" ]; then`,
+            `    for f in "${completionsDir}"/*; do`,
+            '      [ -f "$f" ] && . "$f"',
+            '    done',
+            '  fi',
+            '',
+            'Then restart your shell or run: 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 script is not installed',
+                };
+            }
+            // Remove the completion script
+            await fs.unlink(targetPath);
+            // Remove .bashrc configuration
+            await this.removeBashrcConfig();
+            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=bash-installer.js.map