synarcx 0.1.0

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

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

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

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

package/dist/core/completions/factory.js

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

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

@@ -0,0 +1,35 @@
+import { CompletionGenerator, CommandDefinition } from '../types.js';
+/**
+ * Generates Bash completion scripts for the synarcx CLI.
+ * Follows Bash completion conventions using complete builtin and COMPREPLY array.
+ */
+export declare class BashGenerator implements CompletionGenerator {
+    readonly shell: "bash";
+    /**
+     * Generate a Bash completion script
+     *
+     * @param commands - Command definitions to generate completions for
+     * @returns Bash completion script as a string
+     */
+    generate(commands: CommandDefinition[]): string;
+    /**
+     * Generate completion case logic for a command
+     */
+    private generateCommandCase;
+    /**
+     * Generate argument completion (flags and positional arguments)
+     */
+    private generateArgumentCompletion;
+    /**
+     * Generate positional argument completion based on type
+     */
+    private generatePositionalCompletion;
+    private generateIndexedPositionalCompletion;
+    private generateValueFlagCases;
+    private generateIndexedPositionalCase;
+    /**
+     * Escape command/subcommand names for safe use in Bash scripts
+     */
+    private escapeCommandName;
+}
+//# sourceMappingURL=bash-generator.d.ts.map

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

@@ -0,0 +1,230 @@
+import { BASH_DYNAMIC_HELPERS } from '../templates/bash-templates.js';
+/**
+ * Generates Bash completion scripts for the synarcx CLI.
+ * Follows Bash completion conventions using complete builtin and COMPREPLY array.
+ */
+export class BashGenerator {
+    shell = 'bash';
+    /**
+     * Generate a Bash completion script
+     *
+     * @param commands - Command definitions to generate completions for
+     * @returns Bash completion script as a string
+     */
+    generate(commands) {
+        // Build command list for top-level completions
+        const commandList = commands.map(c => this.escapeCommandName(c.name)).join(' ');
+        // Build command cases using push() for loop clarity
+        const caseLines = [];
+        for (const cmd of commands) {
+            caseLines.push(`    ${cmd.name})`);
+            caseLines.push(...this.generateCommandCase(cmd, '      '));
+            caseLines.push('      ;;');
+        }
+        const commandCases = caseLines.join('\n');
+        // Dynamic completion helpers from template
+        const helpers = BASH_DYNAMIC_HELPERS;
+        // Assemble final script with template literal
+        return `# Bash completion script for synarcx CLI
+# Auto-generated - do not edit manually
+
+_synarcx_completion() {
+  local cur prev words cword
+
+  # Use _init_completion if available (from bash-completion package)
+  # The -n : option prevents colons from being treated as word separators
+  # (important for spec/change IDs that may contain colons)
+  # Otherwise, fall back to manual initialization
+  if declare -F _init_completion >/dev/null 2>&1; then
+    _init_completion -n : || return
+  else
+    # Manual fallback when bash-completion is not installed
+    COMPREPLY=()
+    cur="\${COMP_WORDS[COMP_CWORD]}"
+    prev="\${COMP_WORDS[COMP_CWORD-1]}"
+    words=("\${COMP_WORDS[@]}")
+    cword=$COMP_CWORD
+  fi
+
+  local cmd="\${words[1]}"
+  local subcmd="\${words[2]}"
+
+  # Top-level commands
+  if [[ $cword -eq 1 ]]; then
+    local commands="${commandList}"
+    COMPREPLY=($(compgen -W "$commands" -- "$cur"))
+    return 0
+  fi
+
+  # Command-specific completion
+  case "$cmd" in
+${commandCases}
+  esac
+
+  return 0
+}
+
+${helpers}
+complete -F _synarcx_completion synarcx
+`;
+    }
+    /**
+     * Generate completion case logic for a command
+     */
+    generateCommandCase(cmd, indent) {
+        const lines = [];
+        // Handle subcommands
+        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 [[ "$cur" == -* ]]; then`);
+                const flags = cmd.flags.map(f => {
+                    const parts = [];
+                    if (f.short)
+                        parts.push(`-${f.short}`);
+                    parts.push(`--${f.name}`);
+                    return parts.join(' ');
+                }).join(' ');
+                lines.push(`${indent}  local flags="${flags}"`);
+                lines.push(`${indent}  COMPREPLY=($(compgen -W "$flags" -- "$cur"))`);
+                lines.push(`${indent}  return 0`);
+                lines.push(`${indent}fi`);
+                lines.push('');
+            }
+            lines.push(`${indent}if [[ $cword -eq 2 ]]; then`);
+            lines.push(`${indent}  local subcommands="` + cmd.subcommands.map(s => this.escapeCommandName(s.name)).join(' ') + '"');
+            lines.push(`${indent}  COMPREPLY=($(compgen -W "$subcommands" -- "$cur"))`);
+            lines.push(`${indent}  return 0`);
+            lines.push(`${indent}fi`);
+            lines.push('');
+            lines.push(`${indent}case "$subcmd" in`);
+            for (const subcmd of cmd.subcommands) {
+                lines.push(`${indent}  ${subcmd.name})`);
+                lines.push(...this.generateArgumentCompletion(subcmd, indent + '    ', 3));
+                lines.push(`${indent}    ;;`);
+            }
+            lines.push(`${indent}esac`);
+        }
+        else {
+            // No subcommands, just complete arguments
+            lines.push(...this.generateArgumentCompletion(cmd, indent, 2));
+        }
+        return lines;
+    }
+    /**
+     * Generate argument completion (flags and positional arguments)
+     */
+    generateArgumentCompletion(cmd, indent, firstPositionalWordIndex) {
+        const lines = [];
+        // Check for flag completion
+        if (cmd.flags.length > 0) {
+            lines.push(`${indent}if [[ "$cur" == -* ]]; then`);
+            const flags = cmd.flags.map(f => {
+                const parts = [];
+                if (f.short)
+                    parts.push(`-${f.short}`);
+                parts.push(`--${f.name}`);
+                return parts.join(' ');
+            }).join(' ');
+            lines.push(`${indent}  local flags="${flags}"`);
+            lines.push(`${indent}  COMPREPLY=($(compgen -W "$flags" -- "$cur"))`);
+            lines.push(`${indent}  return 0`);
+            lines.push(`${indent}fi`);
+            lines.push('');
+        }
+        // Handle positional completions
+        if (cmd.positionals && cmd.positionals.length > 0) {
+            lines.push(...this.generateIndexedPositionalCompletion(cmd.positionals, cmd.flags, firstPositionalWordIndex, indent));
+        }
+        else if (cmd.acceptsPositional) {
+            lines.push(...this.generatePositionalCompletion(cmd.positionalType, indent));
+        }
+        return lines;
+    }
+    /**
+     * Generate positional argument completion based on type
+     */
+    generatePositionalCompletion(positionalType, indent) {
+        const lines = [];
+        switch (positionalType) {
+            case 'change-id':
+                lines.push(`${indent}_synarcx_complete_changes`);
+                break;
+            case 'spec-id':
+                lines.push(`${indent}_synarcx_complete_specs`);
+                break;
+            case 'change-or-spec-id':
+                lines.push(`${indent}_synarcx_complete_items`);
+                break;
+            case 'schema-name':
+                lines.push(`${indent}_synarcx_complete_schemas`);
+                break;
+            case 'shell':
+                lines.push(`${indent}local shells="zsh bash fish powershell"`);
+                lines.push(`${indent}COMPREPLY=($(compgen -W "$shells" -- "$cur"))`);
+                break;
+            case 'path':
+                lines.push(`${indent}COMPREPLY=($(compgen -f -- "$cur"))`);
+                break;
+        }
+        return lines;
+    }
+    generateIndexedPositionalCompletion(positionals, flags, firstPositionalWordIndex, indent) {
+        const lines = [];
+        const valueFlagCases = this.generateValueFlagCases(flags);
+        if (valueFlagCases.length > 0) {
+            lines.push(`${indent}case "$prev" in`);
+            lines.push(`${indent}  ${valueFlagCases.join('|')}) return 0 ;;`);
+            lines.push(`${indent}esac`);
+            lines.push('');
+        }
+        lines.push(`${indent}local positional_index=0`);
+        lines.push(`${indent}local skip_next=0`);
+        lines.push(`${indent}local i`);
+        lines.push(`${indent}for ((i = ${firstPositionalWordIndex}; i < cword; i++)); do`);
+        lines.push(`${indent}  if [[ $skip_next -eq 1 ]]; then`);
+        lines.push(`${indent}    skip_next=0`);
+        lines.push(`${indent}    continue`);
+        lines.push(`${indent}  fi`);
+        lines.push(`${indent}  case "\${words[i]}" in`);
+        if (valueFlagCases.length > 0) {
+            lines.push(`${indent}    ${valueFlagCases.join('|')}) skip_next=1 ;;`);
+            lines.push(`${indent}    ${valueFlagCases.map((flag) => `${flag}=*`).join('|')}) ;;`);
+        }
+        lines.push(`${indent}    -*) ;;`);
+        lines.push(`${indent}    *) ((positional_index++)) ;;`);
+        lines.push(`${indent}  esac`);
+        lines.push(`${indent}done`);
+        lines.push('');
+        lines.push(`${indent}case "$positional_index" in`);
+        for (const [index, positional] of positionals.entries()) {
+            const completion = this.generateIndexedPositionalCase(positional, indent + '  ');
+            if (completion.length === 0)
+                continue;
+            lines.push(`${indent}  ${index})`);
+            lines.push(...completion);
+            lines.push(`${indent}    ;;`);
+        }
+        lines.push(`${indent}esac`);
+        return lines;
+    }
+    generateValueFlagCases(flags) {
+        return flags
+            .filter((flag) => flag.takesValue)
+            .flatMap((flag) => [
+            `--${flag.name}`,
+            ...(flag.short ? [`-${flag.short}`] : []),
+        ]);
+    }
+    generateIndexedPositionalCase(positional, indent) {
+        return this.generatePositionalCompletion(positional.type, indent);
+    }
+    /**
+     * Escape command/subcommand names for safe use in Bash scripts
+     */
+    escapeCommandName(name) {
+        // Escape shell metacharacters to prevent command injection
+        return name.replace(/["\$`\\]/g, '\\$&');
+    }
+}
+//# sourceMappingURL=bash-generator.js.map

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

@@ -0,0 +1,32 @@
+import { CompletionGenerator, CommandDefinition } from '../types.js';
+/**
+ * Generates Fish completion scripts for the synarcx CLI.
+ * Follows Fish completion conventions using the complete command.
+ */
+export declare class FishGenerator implements CompletionGenerator {
+    readonly shell: "fish";
+    /**
+     * Generate a Fish completion script
+     *
+     * @param commands - Command definitions to generate completions for
+     * @returns Fish completion script as a string
+     */
+    generate(commands: CommandDefinition[]): string;
+    /**
+     * Generate completions for a specific command
+     */
+    private generateCommandCompletions;
+    /**
+     * Generate flag completion
+     */
+    private generateFlagCompletion;
+    /**
+     * Generate positional argument completion
+     */
+    private generatePositionalCompletion;
+    /**
+     * Escape description text for Fish
+     */
+    private escapeDescription;
+}
+//# sourceMappingURL=fish-generator.d.ts.map