oasr 0.5.0__tar.gz → 0.5.2__tar.gz

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

@@ -4,6 +4,92 @@ 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
+- **🌍 Environment Variable Support** — Full OASR_* environment variable support for all configuration
+  - Naming convention: `OASR_<SECTION>_<KEY>` (e.g., `OASR_AGENT`, `OASR_PROFILE`)
+  - Type-aware parsing: bool, int, list (comma-separated), string
+  - Clear precedence: CLI flags > env vars > config file > defaults
+  - 17 documented environment variables
+- **✅ Enhanced Config Validation** — Early validation with helpful error messages
+  - `oasr config set` validates agent names against available drivers
+  - Profile reference validation (checks if profile exists)
+  - `--force` flag to bypass validation when needed
+  - Dotted notation support: `validation.strict`, `adapter.default`
+  - Suggestions in error messages: "Invalid agent 'foo'. Valid agents: codex, copilot..."
+- **📚 Configuration Documentation Restructure** — Progressive disclosure documentation
+  - New `docs/configuration/` directory with 12 files (~37KB)
+  - Navigation manifest: `.INDEX` file for documentation structure
+  - 7 detailed guides: Overview, Agent, Profiles, Validation, Adapter, Env Vars, Precedence
+  - 4 example configs: Minimal, Development, CI/CD, Production
+  - Easy-to-find specific information with cross-references
+
+### Changed
+- **Config loading**: Now accepts `cli_overrides` parameter for precedence merging
+- **Config command**: Enhanced validation and better error messages
+- **Documentation**: `docs/commands/CONFIG.md` updated with pointers to new structure
+
+### Technical
+- **New module**: `src/config/env.py` with parsing, type coercion, and merging logic
+- **50 new tests**: 40 env var tests + 10 integration tests (287 total tests passing)
+- **Backward compatible**: All existing functionality preserved
+- **Type safety**: Enhanced type checking and validation throughout
+
+### Documentation
+- **[docs/configuration/](docs/configuration/README.md)**: New comprehensive configuration guide
+- **[Environment Variables](docs/configuration/environment-variables.md)**: Complete OASR_* reference
+- **[Precedence](docs/configuration/precedence.md)**: Detailed precedence rules and examples
+- **[Examples](docs/configuration/examples/)**: 4 ready-to-use configuration examples
+
 ## [0.5.0] - 2026-02-02
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oasr
-Version: 0.5.0
+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.0 → 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.0 → 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.0 → oasr-0.5.2}/docs/commands/CONFIG.md

@@ -1,6 +1,25 @@
 # `oasr config`
 
-Manage OASR configuration settings. Configure default agent, validation rules, and adapter preferences.
+Manage OASR configuration settings.
+
+> **Note:** For comprehensive configuration documentation, see [`docs/configuration/`](../configuration/README.md)
+
+## Quick Reference
+
+```bash
+oasr config set <key> <value>   # Set a config value
+oasr config get <key>            # Get a config value
+oasr config list                 # Show all configuration
+oasr config path                 # Show config file location
+```
+
+**See also:**
+- [Configuration Overview](../configuration/README.md) - Complete config guide
+- [Environment Variables](../configuration/environment-variables.md) - OASR_* reference
+- [Agent Configuration](../configuration/agent.md) - Agent settings
+- [Policy Profiles](../configuration/profiles.md) - Execution policies
+
+---
 
 ## Usage
 

oasr-0.5.2/docs/configuration/.INDEX

@@ -0,0 +1,58 @@
+[[doc]]
+path = "README.md"
+title = "Configuration Overview"
+description = "Getting started with OASR configuration - quick start and common scenarios"
+
+[[doc]]
+path = "agent.md"
+title = "Agent Configuration"
+description = "Configure default agent and agent-specific settings"
+
+[[doc]]
+path = "profiles.md"
+title = "Policy Profiles"
+description = "Execution policy profiles for security and isolation"
+
+[[doc]]
+path = "validation.md"
+title = "Validation Settings"
+description = "Skill validation and reference display settings"
+
+[[doc]]
+path = "adapter.md"
+title = "Adapter Configuration"
+description = "IDE adapter targets and settings"
+
+[[doc]]
+path = "environment-variables.md"
+title = "Environment Variables"
+description = "Complete OASR_* environment variable reference"
+
+[[doc]]
+path = "precedence.md"
+title = "Configuration Precedence"
+description = "Understanding how CLI flags, env vars, config file, and defaults interact"
+
+[[section]]
+name = "Examples"
+description = "Ready-to-use configuration examples for common scenarios"
+
+[[example]]
+path = "examples/development.toml"
+title = "Development Configuration"
+description = "Permissive config for local development"
+
+[[example]]
+path = "examples/ci-cd.toml"
+title = "CI/CD Configuration"
+description = "Config for continuous integration pipelines"
+
+[[example]]
+path = "examples/production.toml"
+title = "Production Configuration"
+description = "Hardened config for production environments"
+
+[[example]]
+path = "examples/minimal.toml"
+title = "Minimal Configuration"
+description = "Bare minimum config to get started"