mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-09-14 20:16:53 +08:00
Tabish Bidiwale
5e1cef3b3b
Update the cli-completion spec to match the actual implementation: - Change `completion zsh` to `completion generate [shell]` command structure - Update uninstall behavior to reflect confirmation prompt cancels entire operation - Change "not installed" uninstall exit code from 0 to 1 - Update shell detection error message to match implementation - Replace Purpose placeholder with actual description
288 lines
12 KiB
Markdown
288 lines
12 KiB
Markdown
# cli-completion Specification
|
|
|
|
## Purpose
|
|
Provide shell completion scripts for the OpenSpec CLI, enabling tab-completion for commands, flags, and dynamic values (change IDs, spec IDs) in supported shells. Currently supports Zsh with architecture designed for future shell expansion.
|
|
## Requirements
|
|
### Requirement: Native Shell Behavior Integration
|
|
|
|
The completion system SHALL respect and integrate with Zsh's native completion patterns and user interaction model.
|
|
|
|
#### Scenario: Zsh native completion
|
|
|
|
- **WHEN** generating Zsh completion scripts
|
|
- **THEN** use Zsh completion system with `_arguments`, `_describe`, and `compadd`
|
|
- **AND** completions SHALL trigger on single TAB (standard Zsh behavior)
|
|
- **AND** display as an interactive menu that users navigate with TAB/arrow keys
|
|
- **AND** support Oh My Zsh's enhanced menu styling automatically
|
|
|
|
#### Scenario: No custom UX patterns
|
|
|
|
- **WHEN** implementing Zsh completion
|
|
- **THEN** do NOT attempt to customize completion trigger behavior
|
|
- **AND** do NOT override Zsh-specific navigation patterns
|
|
- **AND** ensure completions feel native to experienced Zsh users
|
|
|
|
### Requirement: Command Structure
|
|
|
|
The completion command SHALL follow a subcommand pattern for generating and managing completion scripts.
|
|
|
|
#### Scenario: Available subcommands
|
|
|
|
- **WHEN** user executes `openspec completion --help`
|
|
- **THEN** display available subcommands:
|
|
- `generate [shell]` - Generate completion script for a shell (outputs to stdout)
|
|
- `install [shell]` - Install completion for Zsh (auto-detects or requires explicit shell)
|
|
- `uninstall [shell]` - Remove completion for Zsh (auto-detects or requires explicit shell)
|
|
|
|
### Requirement: Shell Detection
|
|
|
|
The completion system SHALL automatically detect the user's current shell environment.
|
|
|
|
#### Scenario: Detecting Zsh from environment
|
|
|
|
- **WHEN** no shell is explicitly specified
|
|
- **THEN** read the `$SHELL` environment variable
|
|
- **AND** extract the shell name from the path (e.g., `/bin/zsh` → `zsh`)
|
|
- **AND** validate the shell is `zsh`
|
|
- **AND** throw an error if the shell is not `zsh`, with message indicating only Zsh is currently supported
|
|
|
|
#### Scenario: Non-Zsh shell detection
|
|
|
|
- **WHEN** shell path indicates bash, fish, powershell, or other non-Zsh shell
|
|
- **THEN** throw error: "Shell '<name>' is not supported yet. Currently supported: zsh"
|
|
|
|
### Requirement: Completion Generation
|
|
|
|
The completion command SHALL generate Zsh completion scripts on demand.
|
|
|
|
#### Scenario: Generating Zsh completion
|
|
|
|
- **WHEN** user executes `openspec completion generate zsh`
|
|
- **THEN** output a complete Zsh completion script to stdout
|
|
- **AND** include completions for all commands: init, list, show, validate, archive, view, update, change, spec, completion
|
|
- **AND** include all command-specific flags and options
|
|
- **AND** use Zsh's `_arguments` and `_describe` built-in functions
|
|
- **AND** support dynamic completion for change and spec IDs
|
|
|
|
### Requirement: Dynamic Completions
|
|
|
|
The completion system SHALL provide context-aware dynamic completions for project-specific values.
|
|
|
|
#### Scenario: Completing change IDs
|
|
|
|
- **WHEN** completing arguments for commands that accept change names (show, validate, archive)
|
|
- **THEN** discover active changes from `openspec/changes/` directory
|
|
- **AND** exclude archived changes in `openspec/changes/archive/`
|
|
- **AND** return change IDs as completion suggestions
|
|
- **AND** only provide suggestions when inside an OpenSpec-enabled project
|
|
|
|
#### Scenario: Completing spec IDs
|
|
|
|
- **WHEN** completing arguments for commands that accept spec names (show, validate)
|
|
- **THEN** discover specs from `openspec/specs/` directory
|
|
- **AND** return spec IDs as completion suggestions
|
|
- **AND** only provide suggestions when inside an OpenSpec-enabled project
|
|
|
|
#### Scenario: Completion caching
|
|
|
|
- **WHEN** dynamic completions are requested
|
|
- **THEN** cache discovered change and spec IDs for 2 seconds
|
|
- **AND** reuse cached values for subsequent requests within cache window
|
|
- **AND** automatically refresh cache after expiration
|
|
|
|
#### Scenario: Project detection
|
|
|
|
- **WHEN** user requests completions outside an OpenSpec project
|
|
- **THEN** skip dynamic change/spec ID completions
|
|
- **AND** only suggest static commands and flags
|
|
|
|
### Requirement: Installation Automation
|
|
|
|
The completion command SHALL automatically install completion scripts into shell configuration files.
|
|
|
|
#### Scenario: Installing for Oh My Zsh
|
|
|
|
- **WHEN** user executes `openspec completion install zsh`
|
|
- **THEN** detect if Oh My Zsh is installed by checking for `$ZSH` environment variable or `~/.oh-my-zsh/` directory
|
|
- **AND** create custom completions directory at `~/.oh-my-zsh/custom/completions/` if it doesn't exist
|
|
- **AND** write completion script to `~/.oh-my-zsh/custom/completions/_openspec`
|
|
- **AND** ensure `~/.oh-my-zsh/custom/completions` is in `$fpath` by updating `~/.zshrc` if needed
|
|
- **AND** display success message with instruction to run `exec zsh` or restart terminal
|
|
|
|
#### Scenario: Installing for standard Zsh
|
|
|
|
- **WHEN** user executes `openspec completion install zsh` and Oh My Zsh is not detected
|
|
- **THEN** create completions directory at `~/.zsh/completions/` if it doesn't exist
|
|
- **AND** write completion script to `~/.zsh/completions/_openspec`
|
|
- **AND** add `fpath=(~/.zsh/completions $fpath)` to `~/.zshrc` if not already present
|
|
- **AND** add `autoload -Uz compinit && compinit` to `~/.zshrc` if not already present
|
|
- **AND** display success message with instruction to run `exec zsh` or restart terminal
|
|
|
|
#### Scenario: Auto-detecting Zsh for installation
|
|
|
|
- **WHEN** user executes `openspec completion install` without specifying a shell
|
|
- **THEN** detect current shell using shell detection logic
|
|
- **AND** install completion if detected shell is Zsh
|
|
- **AND** throw error if detected shell is not Zsh
|
|
- **AND** display which shell was detected
|
|
|
|
#### Scenario: Already installed
|
|
|
|
- **WHEN** completion is already installed for the target shell
|
|
- **THEN** display message indicating completion is already installed
|
|
- **AND** offer to reinstall/update by overwriting existing files
|
|
- **AND** exit with code 0
|
|
|
|
### Requirement: Uninstallation
|
|
|
|
The completion command SHALL remove installed completion scripts and configuration.
|
|
|
|
#### Scenario: Uninstalling Oh My Zsh completion
|
|
|
|
- **WHEN** user executes `openspec completion uninstall zsh`
|
|
- **THEN** prompt for confirmation before proceeding (unless `--yes` flag provided)
|
|
- **AND** if user declines, cancel uninstall and display "Uninstall cancelled."
|
|
- **AND** if user confirms, remove `~/.oh-my-zsh/custom/completions/_openspec` if Oh My Zsh is detected
|
|
- **AND** remove `~/.zsh/completions/_openspec` if standard Zsh setup is detected
|
|
- **AND** remove fpath modifications from `~/.zshrc`
|
|
- **AND** display success message
|
|
|
|
#### Scenario: Auto-detecting Zsh for uninstallation
|
|
|
|
- **WHEN** user executes `openspec completion uninstall` without specifying a shell
|
|
- **THEN** detect current shell and uninstall completion if shell is Zsh
|
|
- **AND** throw error if detected shell is not Zsh
|
|
|
|
#### Scenario: Not installed
|
|
|
|
- **WHEN** attempting to uninstall completion that isn't installed
|
|
- **THEN** display error message indicating completion is not installed
|
|
- **AND** exit with code 1
|
|
|
|
### Requirement: Architecture Patterns
|
|
|
|
The completion implementation SHALL follow clean architecture principles with TypeScript best practices.
|
|
|
|
#### Scenario: Shell-specific generators
|
|
|
|
- **WHEN** implementing completion generators
|
|
- **THEN** create `ZshCompletionGenerator` class for Zsh
|
|
- **AND** implement a common `CompletionGenerator` interface with methods:
|
|
- `generate(): string` - Returns complete shell script
|
|
- `getInstallPath(): string` - Returns target installation path
|
|
- `getConfigFile(): string` - Returns shell configuration file path
|
|
- **AND** design interface to be extensible for future shells (bash, fish, powershell)
|
|
|
|
#### Scenario: Dynamic completion providers
|
|
|
|
- **WHEN** implementing dynamic completions
|
|
- **THEN** create a `CompletionProvider` class that encapsulates project discovery logic
|
|
- **AND** implement methods:
|
|
- `getChangeIds(): Promise<string[]>` - Discovers active change IDs
|
|
- `getSpecIds(): Promise<string[]>` - Discovers spec IDs
|
|
- `isOpenSpecProject(): boolean` - Checks if current directory is OpenSpec-enabled
|
|
- **AND** implement caching with 2-second TTL using class properties
|
|
|
|
#### Scenario: Command registry
|
|
|
|
- **WHEN** defining completable commands
|
|
- **THEN** create a centralized `CommandDefinition` type with properties:
|
|
- `name: string` - Command name
|
|
- `description: string` - Help text
|
|
- `flags: FlagDefinition[]` - Available flags
|
|
- `acceptsChangeId: boolean` - Whether command takes change ID argument
|
|
- `acceptsSpecId: boolean` - Whether command takes spec ID argument
|
|
- `subcommands?: CommandDefinition[]` - Nested subcommands
|
|
- **AND** export a `COMMAND_REGISTRY` constant with all command definitions
|
|
- **AND** generators consume this registry to ensure consistency
|
|
|
|
#### Scenario: Type-safe shell detection
|
|
|
|
- **WHEN** implementing shell detection
|
|
- **THEN** define a `SupportedShell` type as literal type: `'zsh'`
|
|
- **AND** implement `detectShell()` function that returns 'zsh' or throws error
|
|
- **AND** design type to be extensible (e.g., future: `'bash' | 'zsh' | 'fish' | 'powershell'`)
|
|
|
|
### Requirement: Error Handling
|
|
|
|
The completion command SHALL provide clear error messages for common failure scenarios.
|
|
|
|
#### Scenario: Unsupported shell
|
|
|
|
- **WHEN** user requests completion for unsupported shell (bash, fish, powershell, etc.)
|
|
- **THEN** display error message: "Shell '<name>' is not supported yet. Currently supported: zsh"
|
|
- **AND** exit with code 1
|
|
|
|
#### Scenario: Permission errors during installation
|
|
|
|
- **WHEN** installation fails due to file permission issues
|
|
- **THEN** display clear error message indicating permission problem
|
|
- **AND** suggest using appropriate permissions or alternative installation method
|
|
- **AND** exit with code 1
|
|
|
|
#### Scenario: Missing shell configuration directory
|
|
|
|
- **WHEN** expected shell configuration directory doesn't exist
|
|
- **THEN** create the directory automatically (with user notification)
|
|
- **AND** proceed with installation
|
|
|
|
#### Scenario: Shell not detected
|
|
|
|
- **WHEN** `openspec completion install` cannot detect current shell or detects non-Zsh shell
|
|
- **THEN** display error: "Could not auto-detect shell. Please specify shell explicitly."
|
|
- **AND** display usage hint: "Usage: openspec completion <operation> [shell]"
|
|
- **AND** exit with code 1
|
|
|
|
### Requirement: Output Format
|
|
|
|
The completion command SHALL provide machine-parseable and human-readable output.
|
|
|
|
#### Scenario: Script generation output
|
|
|
|
- **WHEN** generating completion script to stdout
|
|
- **THEN** output only the completion script content (no extra messages)
|
|
- **AND** allow redirection to files: `openspec completion generate zsh > /path/to/_openspec`
|
|
|
|
#### Scenario: Installation success output
|
|
|
|
- **WHEN** installation completes successfully
|
|
- **THEN** display formatted success message with:
|
|
- Checkmark indicator
|
|
- Installation location
|
|
- Next steps (shell reload instructions)
|
|
- **AND** use colors when terminal supports it (unless `--no-color` is set)
|
|
|
|
#### Scenario: Verbose installation output
|
|
|
|
- **WHEN** user provides `--verbose` flag during installation
|
|
- **THEN** display detailed steps:
|
|
- Shell detection result
|
|
- Target file paths
|
|
- Configuration modifications
|
|
- File creation confirmations
|
|
|
|
### Requirement: Testing Support
|
|
|
|
The completion implementation SHALL be testable with unit and integration tests.
|
|
|
|
#### Scenario: Mock shell environment
|
|
|
|
- **WHEN** writing tests for shell detection
|
|
- **THEN** allow overriding `$SHELL` environment variable
|
|
- **AND** use dependency injection for file system operations
|
|
|
|
#### Scenario: Generator output verification
|
|
|
|
- **WHEN** testing completion generators
|
|
- **THEN** verify generated scripts contain expected patterns
|
|
- **AND** test that command registry is properly consumed
|
|
- **AND** ensure dynamic completion placeholders are present
|
|
|
|
#### Scenario: Installation simulation
|
|
|
|
- **WHEN** testing installation logic
|
|
- **THEN** use temporary test directories instead of actual home directories
|
|
- **AND** verify file creation without modifying real shell configurations
|
|
- **AND** test path resolution logic independently
|
|
|