oasr 0.5.1__tar.gz → 0.5.2__tar.gz

{oasr-0.5.1 → oasr-0.5.2}/CHANGELOG.md

@@ -4,6 +4,54 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.2] - 2026-02-02
+
+### Added
+- **⌨️ Shell Completion Support** — Intelligent tab completion for all major shells
+  - Cross-platform support: Bash, Zsh, Fish, PowerShell
+  - `oasr completion install` — Auto-detect shell and install completions
+  - `oasr completion <shell>` — Output completion script for specific shell
+  - Dynamic completions: skill names, agents, profiles fetched live from registry
+  - Command, subcommand, and flag completion for all OASR commands
+  - Smart shell detection (platform + $SHELL environment variable)
+  - Installation paths: `~/.bash_completion.d/`, `~/.zsh/completion/`, `~/.config/fish/completions/`, `~/.config/powershell/`
+  - Backup mechanism: existing completions backed up before overwrite
+  - `--force` and `--dry-run` flags for installation control
+  - `oasr completion uninstall` — Remove installed completions
+  - Configuration support: `oasr.completions` config option
+- **🧪 Comprehensive E2E Tests** — 16 new end-to-end tests covering all commands
+  - Registry subcommands (list, sync, prune)
+  - Diff, sync, info, validate, clean commands
+  - Adapter, find, help commands
+  - Total test count: 282 tests (all passing)
+  - Ensures no regressions in existing functionality
+
+### Documentation
+- **[docs/commands/COMPLETION.md](docs/commands/COMPLETION.md)**: Complete completion command reference
+  - Installation instructions for all shells
+  - Shell-specific configuration notes
+  - Troubleshooting guide
+  - Examples and usage patterns
+- **[README.md](README.md)**: Added Shell Completions section with quickstart
+- **[docs/commands/.INDEX.md](docs/commands/.INDEX.md)**: Added completion to command index
+
+### Technical
+- **New module**: `src/commands/completion.py` (259 lines) with shell detection and installation
+- **Completion scripts**: 4 shell-specific scripts (~691 lines total)
+  - `src/completions/bash.sh` (197 lines)
+  - `src/completions/zsh.sh` (259 lines) with descriptions
+  - `src/completions/fish.fish` (120 lines) with native Fish syntax
+  - `src/completions/powershell.ps1` (115 lines) with ArgumentCompleter
+- **45 new tests**: 29 completion tests + 16 E2E tests
+- **Dynamic completion**: Scripts invoke `oasr` commands for live data (registry list, config keys)
+- **Cross-platform**: Handles Windows, macOS, Linux path conventions
+
+### Quality of Life
+- Tab completion reduces typing and prevents typos
+- Discovery: see available skills, agents, and profiles at your fingertips
+- Professional UX: OASR now feels like a polished CLI tool
+- Backward compatible: no changes to existing commands
+
 ## [0.5.1] - 2026-02-02
 
 ### Added

{oasr-0.5.1 → oasr-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oasr
-Version: 0.5.1
+Version: 0.5.2
 Summary: CLI for managing agent skills across IDE integrations
 Project-URL: Homepage, https://github.com/jgodau/asr
 Project-URL: Repository, https://github.com/jgodau/asr
@@ -317,6 +317,26 @@ Remote skills are fetched on-demand during `adapter` and `use` operations. The r
 
 ---
 
+## Shell Completions
+
+OASR supports intelligent tab completion for Bash, Zsh, Fish, and PowerShell:
+
+```bash
+# Install for your current shell
+oasr completion install
+
+# Now try it:
+oasr <TAB>          # Complete commands
+oasr info <TAB>     # Complete skill names
+oasr exec --<TAB>   # Complete flags
+```
+
+Completions are **dynamic** — skill names, agents, and profiles are fetched live from your registry.
+
+See [`oasr completion --help`](docs/commands/COMPLETION.md) for details.
+
+---
+
 ## Documentation
 
 - **[Quickstart](docs/QUICKSTART.md)** — Installation and first steps

{oasr-0.5.1 → oasr-0.5.2}/README.md

@@ -98,6 +98,26 @@ Remote skills are fetched on-demand during `adapter` and `use` operations. The r
 
 ---
 
+## Shell Completions
+
+OASR supports intelligent tab completion for Bash, Zsh, Fish, and PowerShell:
+
+```bash
+# Install for your current shell
+oasr completion install
+
+# Now try it:
+oasr <TAB>          # Complete commands
+oasr info <TAB>     # Complete skill names
+oasr exec --<TAB>   # Complete flags
+```
+
+Completions are **dynamic** — skill names, agents, and profiles are fetched live from your registry.
+
+See [`oasr completion --help`](docs/commands/COMPLETION.md) for details.
+
+---
+
 ## Documentation
 
 - **[Quickstart](docs/QUICKSTART.md)** — Installation and first steps

{oasr-0.5.1 → oasr-0.5.2}/docs/commands/.INDEX.md

@@ -9,6 +9,7 @@
 - [oasr config](CONFIG.md) - Manage configuration (NEW in v0.4.0)
 - [oasr clone](CLONE.md) - Clone skill(s) to target directory (NEW in v0.4.0)
 - [oasr exec](EXEC.md) - Execute skills as CLI tools (NEW in v0.4.0)
+- [oasr completion](COMPLETION.md) - Shell tab completion (NEW in v0.5.2)
 - [oasr find](FIND.md) - Find/discover skills in your file system
 - [oasr validate](VALIDATE.md) - Validate a skill
 - [oasr adapter](ADAPTER.md) - Generate IDE/Tooling adapters

oasr-0.5.2/docs/commands/COMPLETION.md

@@ -0,0 +1,324 @@
+# `oasr completion`
+
+Enable shell tab completion for OASR commands, subcommands, and dynamic resources (skills, agents, profiles).
+
+---
+
+## Overview
+
+The `oasr completion` command provides intelligent tab completion across all major shells:
+
+- **Bash** — Traditional completion with dynamic skill/agent/profile suggestions
+- **Zsh** — Rich completions with descriptions and type hints
+- **Fish** — Native Fish completions with helper functions
+- **PowerShell** — ArgumentCompleter with tooltips
+
+Completions are **dynamic**: skill names, agents, and profiles are fetched live from your registry.
+
+---
+
+## Usage
+
+```bash
+# Output completion script for current shell (auto-detected)
+oasr completion
+
+# Output for specific shell
+oasr completion bash
+oasr completion zsh
+oasr completion fish
+oasr completion powershell
+
+# Install to standard location for current shell
+oasr completion install
+
+# Install for specific shell
+oasr completion install bash
+oasr completion install --force  # Overwrite existing
+
+# Uninstall
+oasr completion uninstall
+
+# Dry run (show what would be done)
+oasr completion install --dry-run
+```
+
+---
+
+## Installation
+
+### Automatic (Recommended)
+
+```bash
+# Auto-detect shell and install
+oasr completion install
+
+# Restart your shell or source the completion file
+# Bash:
+source ~/.bash_completion.d/oasr
+
+# Zsh:
+source ~/.zsh/completion/_oasr
+
+# Fish: (automatically loaded)
+
+# PowerShell: (add to profile if not present)
+. ~/.config/powershell/oasr_completion.ps1
+```
+
+### Manual Installation
+
+If you prefer manual control, output the script and place it yourself:
+
+```bash
+# Bash
+oasr completion bash > ~/.bash_completion.d/oasr
+source ~/.bash_completion.d/oasr
+
+# Zsh
+oasr completion zsh > ~/.zsh/completion/_oasr
+# Add to ~/.zshrc:
+# fpath=(~/.zsh/completion $fpath)
+# autoload -Uz compinit && compinit
+
+# Fish
+oasr completion fish > ~/.config/fish/completions/oasr.fish
+
+# PowerShell
+oasr completion powershell > ~/.config/powershell/oasr_completion.ps1
+# Add to $PROFILE:
+# . ~/.config/powershell/oasr_completion.ps1
+```
+
+---
+
+## What Gets Completed
+
+### Commands & Subcommands
+
+```bash
+oasr <TAB>
+# Shows: add, adapter, clean, clone, completion, config, diff, exec, find, help, info, list, registry, rm, status, sync, update, use, validate
+
+oasr registry <TAB>
+# Shows: add, list, prune, rm, sync, validate
+
+oasr config <TAB>
+# Shows: get, list, set, unset, validate
+```
+
+### Dynamic Resources
+
+```bash
+# Skill names (from your registry)
+oasr info <TAB>
+# Shows: git-commit, code-review, doc-generator, ...
+
+oasr exec <TAB>
+# Shows: git-commit, code-review, doc-generator, ...
+
+# Agent types
+oasr config set agent <TAB>
+# Shows: codex, copilot, claude, openai, gemini
+
+# Profiles
+oasr exec --profile <TAB>
+# Shows: safe, default, permissive, ...
+
+# Config keys
+oasr config get <TAB>
+# Shows: agent, profile, validation.strict, adapter.default, ...
+```
+
+### Flags & Options
+
+All commands provide flag completion:
+
+```bash
+oasr add --<TAB>
+# Shows: --source, --no-track, --help
+
+oasr exec --<TAB>
+# Shows: --profile, --yes, --confirm, --help
+
+oasr adapter --<TAB>
+# Shows: --output-dir, --adapter, --force, --help
+```
+
+---
+
+## Configuration
+
+### Enable/Disable via Config
+
+```toml
+# ~/.config/oasr/config.toml
+[oasr]
+completions = true  # Enable (default)
+# completions = false  # Disable
+```
+
+Or via environment variable:
+
+```bash
+export OASR_OASR_COMPLETIONS=true
+```
+
+When disabled, `oasr completion install` will skip installation.
+
+### Installation Paths
+
+Completions are installed to standard shell-specific locations:
+
+| Shell       | Path                                      |
+|-------------|-------------------------------------------|
+| Bash        | `~/.bash_completion.d/oasr`              |
+| Zsh         | `~/.zsh/completion/_oasr`                |
+| Fish        | `~/.config/fish/completions/oasr.fish`   |
+| PowerShell  | `~/.config/powershell/oasr_completion.ps1` |
+
+### Backup on Overwrite
+
+If you run `oasr completion install` and a completion file already exists, it will:
+
+1. **Without `--force`**: Prompt for confirmation
+2. **With `--force`**: Create a backup at `<path>.backup` before overwriting
+
+---
+
+## Shell-Specific Notes
+
+### Bash
+
+- Requires `bash-completion` package on most systems
+- Sources files from `~/.bash_completion.d/` automatically (if configured)
+- Add to `~/.bashrc` if not auto-loaded:
+  ```bash
+  [ -f ~/.bash_completion.d/oasr ] && source ~/.bash_completion.d/oasr
+  ```
+
+### Zsh
+
+- Uses `#compdef` directive for native Zsh completion system
+- Provides rich descriptions for subcommands
+- Add to `~/.zshrc` if not auto-loaded:
+  ```zsh
+  fpath=(~/.zsh/completion $fpath)
+  autoload -Uz compinit && compinit
+  ```
+
+### Fish
+
+- Uses native `complete -c` syntax
+- Automatically loaded from `~/.config/fish/completions/`
+- No additional configuration needed
+
+### PowerShell
+
+- Uses `Register-ArgumentCompleter` API
+- Provides tooltips for commands
+- Add to PowerShell profile:
+  ```powershell
+  . ~/.config/powershell/oasr_completion.ps1
+  ```
+- Find profile location: `echo $PROFILE`
+
+---
+
+## Troubleshooting
+
+### Completions Not Working
+
+1. **Verify installation**:
+   ```bash
+   oasr completion install
+   ```
+
+2. **Check shell detection**:
+   ```bash
+   oasr completion  # Should output script for current shell
+   ```
+
+3. **Restart shell** or source the completion file manually
+
+4. **Check shell configuration**:
+   - Bash: `~/.bashrc` should source `~/.bash_completion.d/oasr`
+   - Zsh: `~/.zshrc` should have `fpath` and `compinit`
+   - Fish: Automatically loaded
+   - PowerShell: `$PROFILE` should source the completion script
+
+### Dynamic Completions Slow
+
+If skill/agent/profile completions are slow:
+
+- Dynamic completions call `oasr` commands (e.g., `oasr registry list --quiet`)
+- Large registries may cause slight delays
+- Completions are generated on-demand (not cached)
+
+### Wrong Shell Detected
+
+Specify the shell explicitly:
+
+```bash
+oasr completion install zsh
+```
+
+Or set `$SHELL` environment variable:
+
+```bash
+export SHELL=/bin/zsh
+oasr completion install
+```
+
+---
+
+## Examples
+
+### Install for Current Shell
+
+```bash
+$ oasr completion install
+Installing completion for zsh...
+Completion installed to: /home/user/.zsh/completion/_oasr
+
+To activate:
+  source ~/.zsh/completion/_oasr
+  # Or restart your shell
+```
+
+### Generate Script for Manual Review
+
+```bash
+$ oasr completion bash > /tmp/oasr_completion.bash
+$ less /tmp/oasr_completion.bash
+# Review script before installing
+$ cp /tmp/oasr_completion.bash ~/.bash_completion.d/oasr
+```
+
+### Install with Dry Run
+
+```bash
+$ oasr completion install --dry-run
+[DRY RUN] Would install completion for zsh
+[DRY RUN] Target path: /home/user/.zsh/completion/_oasr
+[DRY RUN] File exists: False
+[DRY RUN] Would create directory: /home/user/.zsh/completion
+[DRY RUN] Would write 259 bytes
+```
+
+### Force Overwrite
+
+```bash
+$ oasr completion install --force
+Backing up existing completion to: /home/user/.zsh/completion/_oasr.backup
+Installing completion for zsh...
+Completion installed to: /home/user/.zsh/completion/_oasr
+```
+
+---
+
+## See Also
+
+- [`oasr config`](CONFIG.md) — Configure completion behavior
+- [`oasr help`](HELP.md) — Get help on commands
+- [Commands Index](.INDEX.md) — All available commands

{oasr-0.5.1 → oasr-0.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oasr"
-version = "0.5.1"
+version = "0.5.2"
 description = "CLI for managing agent skills across IDE integrations"
 readme = "README.md"
 requires-python = ">=3.10"

{oasr-0.5.1 → oasr-0.5.2}/src/cli.py

@@ -13,7 +13,7 @@ from pathlib import Path
 from commands import adapter, clean, clone, config, diff, exec, find, registry, sync, update, use, validate
 from commands import help as help_cmd
 
-__version__ = "0.5.1"
+__version__ = "0.5.2"
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -88,6 +88,11 @@ def create_parser() -> argparse.ArgumentParser:
 
     info_cmd.register(subparsers)
 
+    # Import and register completion command
+    from commands import completion as completion_cmd
+
+    completion_cmd.register_parser(subparsers)
+
     help_cmd.register(subparsers, parser)
 
     return parser