feat: Add shell completion installation and setup commands

[razor-x]

Summary

This PR adds the ability to install and configure shell completions for bash, fish, and zsh directly from the CLI, rather than requiring manual installation or system package management.

Key Changes

• New completion installation module (src/lib/completion/install.ts):

  • detectShell(): Detects the current shell from the SHELL environment variable
  • resolveCompletionTarget(): Determines where completions should be installed based on shell type and environment variables (e.g., ZDOTDIR for zsh, XDG_CONFIG_HOME for fish)
  • installCompletion(): Handles the actual installation, with idempotent behavior for config files (appends only once) and overwrites for completion files owned by the CLI
  • Proper handling of shell-specific config locations and edge cases (e.g., bash on macOS vs Linux)

• New completion setup rendering (src/lib/render/completion/render-loader.ts):

  • renderCompletionSetup(): Generates the snippet users add to their shell config
  • renderCompletionStub(): Generates the loader for system packages (moved from index.ts)
  • completionSetupMarker: Constant used to detect already-installed snippets
  • Separate setup snippets for each shell with lazy-loading behavior

• Enhanced completion command (src/lib/commands/local/completion.ts):

  • New --install flag: Automatically installs completions into the detected shell's config
  • New --manual flag: Prints the setup snippet for manual installation
  • readCompletionAction(): Parses which action to perform (print, install, manual, or loader)
  • resolveCompletionShell(): Determines the target shell from arguments or environment
  • installCompletionForShell(): Orchestrates the installation and reports results
  • printCompletionSetup(): Prints the snippet with instructions

• Refactored completion rendering (src/lib/render/completion/):

  • Extracted shell type definitions to new shell.ts module
  • Moved loader and setup rendering to dedicated render-loader.ts
  • Updated index.ts to re-export from new modules

• Comprehensive test coverage (test/completion/install.test.ts):

  • Tests for shell detection with various SHELL values
  • Tests for target resolution with environment variables
  • Tests for idempotent installation behavior
  • Tests for shell-specific notes (e.g., zsh compinit detection)

• CLI integration (src/bin/cli.ts):

  • Routes completion command to new action handlers
  • Validates arguments against the detected shell's command definition

• Documentation updates (README.md):

  • Added shell completion section with installation instructions
  • Documented --install, --manual, and --loader flags
  • Explained the lazy-loading behavior and schema freshness benefits

Notable Implementation Details

• Idempotent installation: Config files are checked for the completionSetupMarker before appending, preventing duplicate snippets
• Lazy loading: The setup snippet runs seam completion on first use, ensuring completions always match the current CLI schema
• Shell-specific handling:
  • Fish uses a dedicated completion file (loaded on demand)
  • Zsh respects ZDOTDIR and can initialize compinit if needed
  • Bash prefers .bashrc on Linux but falls back to .bash_profile on macOS
• Safe evaluation: All loaders validate the first line of the completion script before evaluating it, preventing execution of error messages

https://claude.ai/code/session_01NS3fVoYWNDEQWAhrp3PnPj