Add help and shell completion support to CLI

[razor-x]

This PR adds comprehensive help documentation and shell completion scripts to the Seam CLI, making it more user-friendly and discoverable.

Summary

The CLI now generates help guides and completion scripts dynamically from the API blueprint. Users can run seam --help to see available commands, seam <command> --help for command details, and install completion scripts for bash, fish, and zsh shells.

Key Changes

• Command Specification System (src/lib/command-spec.ts): Created a new module that derives a structured command specification from the API blueprint, including:

  • Converting API endpoints to command definitions with flags
  • Organizing commands into hierarchical groups
  • Defining global flags available to all commands
  • Utility functions for finding commands and groups by path

• Help Rendering (src/lib/render-help.ts): Implemented dynamic help guide generation that:

  • Renders help for the root command, command groups, and individual commands
  • Documents flags with their descriptions, required status, and known values
  • Uses the command-line-usage library for consistent formatting

• Shell Completion Scripts: Added renderers for three shells:

  • Bash (src/lib/completion/render-bash.ts): Case-based completion with flag value support
  • Zsh (src/lib/completion/render-zsh.ts): Descriptive completion with inline help text
  • Fish (src/lib/completion/render-fish.ts): Guard-based completion with helper functions
  • Completion Index (src/lib/completion/index.ts): Unified interface for rendering completions

• Completion Utilities (src/lib/completion/describe.ts): Helper to safely format descriptions for shell scripts by removing special characters and truncating to fit completion menus

• CLI Integration (src/bin/cli.ts): Updated the main CLI to:

  • Use the new help system instead of hardcoded help text
  • Support seam completion <shell> commands
  • Handle --help flag with command path awareness

• Build Process (prepack.ts): Extended to generate and package completion scripts in a completions/ directory during build

• Documentation (README.md): Added sections explaining help usage and shell completion installation

• Testing: Added comprehensive test suites for command spec derivation, help rendering, and completion generation with a test blueprint fixture

Notable Implementation Details

• The command specification system intelligently handles both API-defined endpoints and CLI-specific commands (login, logout, completion, etc.)
• Help text is derived from markdown descriptions in the API blueprint and reduced to plain text
• Completion scripts are generated from the bundled API definitions, ensuring they work offline and without authentication
• The system deduplicates commands and sorts them consistently for predictable output
• Shell-safe descriptions drop problematic characters (quotes, colons, etc.) that would break completion menus

https://claude.ai/code/session_016eYkGybhEJJE3FkaqXdwLv