feat: Add help and shell completion support to CLI - #594
Merged
Conversation
Add 'seam completion <bash|fish|zsh>', which prints a completion script derived from the API definitions bundled with the CLI. The script completes command paths, per-command flags, and flag values for enum and boolean parameters. Write the same scripts to completions/ on prepack and publish them, so a system package can install them without running the CLI. Completions are always generated from the bundled definitions so that they work offline and without logging in. They may lag the definitions served by Seam when config use-remote-api-defs is enabled. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016eYkGybhEJJE3FkaqXdwLv
Help was one static page listing four examples and a single option, no matter which command it followed. Render it from the same command spec that drives completions instead, so it answers the command it is passed with: seam --help every top level command seam devices --help the commands under seam devices seam devices list --help the options seam devices list accepts Command help documents every parameter of the endpoint, marking the required ones and naming the values of enum and boolean parameters. An unrecognized command path reports itself rather than printing the root guide. Move the command spec out of lib/completion, since completions are now one of its two consumers, and keep shell quoting in the completion renderers so help can carry the full text of a description. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016eYkGybhEJJE3FkaqXdwLv
Adapt shell completions and help to the cached blueprint: - prepack generates completions from the latest published API definitions using a temporary cache, since the blueprint is no longer bundled. - seam completion and seam --help use the cached definitions and accept --update to refresh them first. - Add the wizard command and the --update flag to the command spec, so they complete and appear in help. - Attach the completion scripts to GitHub releases and install them for bash, fish, and zsh in the seam-bin AUR package. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016eYkGybhEJJE3FkaqXdwLv
The root guide listed every top level name in one table, burying login, wizard, and the other commands of the CLI itself among the API routes. Split it: a Commands section for the CLI's own commands first, then an API Commands section for the commands that call the Seam API, then the options and examples. health counts as an API command, since it calls the Seam API. Deeper guides keep a single Commands section: a group holds commands of one kind, so the split adds nothing there. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016eYkGybhEJJE3FkaqXdwLv
Replace the packaged completion scripts with loaders that run 'seam completion' the first time the shell completes a seam command. Installed completions now always match the CLI's current Seam API definitions instead of the definitions packaged at release time, and never go stale between package updates. Each shell loads its completion file on demand, so the CLI runs once per shell session at first completion, never at shell startup, and the loaders degrade to no completions when the seam command is missing or cannot produce a script. Search the whole funcstack in the zsh dispatch, since eval pushes '(eval)' onto funcstack: the top entry is not _seam when the loader evaluates the script, and the previous check deferred the completion menu to the second tab. Packing no longer needs the API definitions: the loaders are static text, so prepack is offline again. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016eYkGybhEJJE3FkaqXdwLv
Enum values were already allowlisted and descriptions sanitized, but command path words and flag names were embedded in single-quoted shell strings unvalidated. Drop endpoints and flags whose names a shell could read as syntax, so nothing from the API definitions can escape its quoting in a generated completion script. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016eYkGybhEJJE3FkaqXdwLv
Adapt help and completions: - Root help gains the Output section, the new -i, -y, and --json flags, and the piping examples, all rendered from the command spec. - The help and completion paths write through the output so stdout stays clean, and report unknown commands on stderr. - The static help block from main is dropped: renderHelp covers it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016eYkGybhEJJE3FkaqXdwLv
razor-x
changed the title
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016eYkGybhEJJE3FkaqXdwLv
Command help listed the request parameters and the CLI's own flags in one Options table, putting --device-id next to --version. Document the command's parameters under a Parameters section and keep Options for the flags every seam command takes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016eYkGybhEJJE3FkaqXdwLv
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 --helpto see available commands,seam <command> --helpfor 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:Help Rendering (
src/lib/render-help.ts): Implemented dynamic help guide generation that:command-line-usagelibrary for consistent formattingShell Completion Scripts: Added renderers for three shells:
src/lib/completion/render-bash.ts): Case-based completion with flag value supportsrc/lib/completion/render-zsh.ts): Descriptive completion with inline help textsrc/lib/completion/render-fish.ts): Guard-based completion with helper functionssrc/lib/completion/index.ts): Unified interface for rendering completionsCompletion Utilities (
src/lib/completion/describe.ts): Helper to safely format descriptions for shell scripts by removing special characters and truncating to fit completion menusCLI Integration (
src/bin/cli.ts): Updated the main CLI to:seam completion <shell>commands--helpflag with command path awarenessBuild Process (
prepack.ts): Extended to generate and package completion scripts in acompletions/directory during buildDocumentation (
README.md): Added sections explaining help usage and shell completion installationTesting: Added comprehensive test suites for command spec derivation, help rendering, and completion generation with a test blueprint fixture
Notable Implementation Details
https://claude.ai/code/session_016eYkGybhEJJE3FkaqXdwLv