oasr 0.3.4__tar.gz → 0.4.1__tar.gz

{oasr-0.3.4 → oasr-0.4.1}/CHANGELOG.md

@@ -4,7 +4,55 @@ 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).
 
-## [Unreleased]
+## [0.4.1] - 2026-02-01
+
+### Fixed
+- **exec command**: Fixed `CompletedProcess` attribute error where code incorrectly referenced `.success`, `.output`, and `.error` attributes that don't exist. Now correctly uses `.returncode`
+- **clone documentation**: Removed non-existent `-r, --recursive` flag from CLONE.md documentation
+
+## [0.4.0] - 2026-01-31
+
+### Added
+- **🚀 `oasr exec` command** — Execute skills as CLI tools from anywhere
+  - Run skills with agent-driven execution: `oasr exec <skill> -p "prompt"`
+  - Multiple prompt input methods: inline (`-p`), file (`-i`), or stdin (pipe)
+  - Agent selection via flag (`--agent`) or config default
+  - Graceful error handling with helpful guidance
+- **`oasr config` command** — Manage OASR configuration
+  - `config set <key> <value>` — Set config values (e.g., default agent)
+  - `config get <key>` — Retrieve config values
+  - `config list` — Display all configuration with agent availability
+  - `config path` — Show config file location
+- **`oasr clone` command** — Renamed from `oasr use` for clarity
+  - Clones skills from registry to current directory
+  - Same functionality as deprecated `oasr use`
+- **Agent driver system** — Support for multiple AI agent CLIs
+  - Codex: `codex exec "<prompt>"`
+  - GitHub Copilot: `copilot -p "<prompt>"`
+  - Claude CLI: `claude <prompt> -p`
+  - OpenCode: `opencode run "<prompt>"`
+  - Auto-detection of available agent binaries
+  - Extensible driver architecture for adding new agents
+- **Multi-skill repository support** — Detect and add multiple skills from one repo
+  - `oasr registry add <repo-url>` automatically finds all SKILL.md files
+  - Interactive prompt for bulk addition: "Found 3 skills. Add all? [Y/n]"
+  - Each skill registered with proper subdirectory URL
+
+### Changed
+- **Config system refactored** — Moved to subpackage architecture
+  - `src/config/` subpackage with schema validation
+  - New `agent.default` field in config for default agent selection
+  - TOML serialization improved (strips None values)
+  - Backward compatible with existing configs
+
+### Deprecated
+- **`oasr use` command** — Use `oasr clone` instead
+  - Shows deprecation warning (suppressible with `--quiet` or `--json`)
+  - Warning: "This command will be removed in v0.5.0"
+  - Fully functional shim delegates to `oasr clone`
+
+### Fixed
+- Config validation now properly handles None values in TOML serialization
 
 ## [0.3.4] - 2026-02-01
 

{oasr-0.3.4 → oasr-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oasr
-Version: 0.3.4
+Version: 0.4.1
 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

oasr-0.4.1/docs/QUICKSTART.md

@@ -0,0 +1,140 @@
+# Quickstart
+
+---
+
+## Option A: Global Installation
+
+To make `oasr` available system-wide:
+
+```bash
+# macOS/Linux
+./install.sh
+
+# Windows (PowerShell)
+.\install.ps1
+```
+
+This installs into an isolated environment and adds shims to your PATH (`~/.local/bin` on Unix, `%LOCALAPPDATA%\oasr\bin` on Windows).
+
+## Option B: Install from PyPI with `pip`
+
+```bash
+pip install oasr
+```
+
+## Option C: Install from PyPI with `uv`
+
+```bash
+uv pip install oasr
+```
+
+## Option D: Install from source
+
+```bash
+git clone https://github.com/JordanGunn/oasr.git
+cd oasr
+uv pip install -e .
+```
+
+---
+
+## Verify Installation
+
+```bash
+oasr --version
+```
+
+---
+
+## First Steps
+
+### Basic Workflow
+
+```bash
+# Register a skill
+oasr registry add /path/to/your/skill
+
+# Or add from a remote repository
+oasr registry add https://github.com/user/skill-repo
+
+# List registered skills
+oasr registry list
+
+# Clone a skill to your workspace (with tracking)
+oasr clone my-skill
+
+# Check status of tracked skills
+oasr diff
+```
+
+### Execute Skills (v0.4.0)
+
+```bash
+# Configure your preferred agent
+oasr config set agent codex
+
+# Execute a skill from anywhere
+oasr exec my-skill -p "Your prompt here"
+
+# Use with pipes for powerful workflows
+git diff | oasr exec code-reviewer -p "Review these changes"
+```
+
+### IDE Integration
+
+```bash
+# Generate adapters for your IDE
+oasr adapter cursor
+oasr adapter windsurf
+```
+
+## Common Workflows
+
+### Workflow 1: Clone and Use in IDE
+Best for repeated manual use with IDE integration.
+
+```bash
+# Add skills to registry
+oasr registry add https://github.com/user/skills
+
+# Clone to your project
+cd ~/my-project
+oasr clone csv-analyzer
+
+# Adapt for your IDE
+oasr adapter cursor
+```
+
+### Workflow 2: Direct Execution
+Best for automation, scripts, and one-off tasks.
+
+```bash
+# Configure default agent once
+oasr config set agent codex
+
+# Execute skills directly (no cloning needed)
+oasr exec data-analyzer -p "Summarize report.csv"
+oasr exec test-generator -p "Generate tests for api.py"
+
+# Use in shell scripts
+#!/bin/bash
+git log -10 | oasr exec commit-summarizer > summary.txt
+```
+
+### Workflow 3: Multi-skill Repository
+Work with repositories containing multiple skills.
+
+```bash
+# Add repository (auto-detects all skills)
+oasr registry add https://github.com/org/skill-collection
+# Found 5 skills. Add all? [Y/n]: y
+
+# List added skills
+oasr registry list
+
+# Use any skill from the collection
+oasr exec python-formatter -p "Format all Python files"
+oasr exec doc-generator -p "Generate API docs"
+```
+
+See [Command Documentation](commands/.INDEX.md) for the full command reference.

{oasr-0.3.4 → oasr-0.4.1}/docs/commands/.INDEX.md

@@ -1,12 +1,14 @@
 # Commands
 
-## Core Commands (v0.3.0)
+## Core Commands (v0.4.0)
 
 - [oasr](ROOT.md) - Global flags and options
 - [oasr registry](REGISTRY.md) - Manage skill registry (validate, add, remove, list, sync)
-- [oasr diff](DIFF.md) - Show status of tracked skills (NEW in v0.3.0)
-- [oasr sync](SYNC.md) - Refresh outdated tracked skills (CHANGED in v0.3.0)
-- [oasr use](USE.md) - Copy skill(s) to target directory (with tracking)
+- [oasr diff](DIFF.md) - Show status of tracked skills
+- [oasr sync](SYNC.md) - Refresh outdated tracked skills
+- [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 find](FIND.md) - Find/discover skills in your file system
 - [oasr validate](VALIDATE.md) - Validate a skill
 - [oasr clean](CLEAN.md) - Clean up the registry
@@ -15,10 +17,13 @@
 - [oasr info](INFO.md) - Show detailed information about a skill
 - [oasr help](HELP.md) - Show the help menu
 
-## Deprecated Commands (v0.2.0)
+## Deprecated Commands
 
-These commands have been reorganized in v0.3.0:
+### v0.4.0 Deprecations
+- [oasr use](USE.md) - **Deprecated**, use `oasr clone` instead (will be removed in v0.5.0)
 
+### v0.3.0 Reorganization
+These commands were reorganized in v0.3.0:
 - [oasr add](ADD.md) - **Moved to** `oasr registry add`
 - [oasr list](LIST.md) - **Moved to** `oasr registry list`
 - [oasr rm](RM.md) - **Moved to** `oasr registry rm`

oasr-0.4.1/docs/commands/CLONE.md

@@ -0,0 +1,109 @@
+# `oasr clone`
+
+Clone skills from the registry to a target directory. Supports glob patterns and works with both local and remote skills.
+
+> **note**  
+> `oasr clone` provides an open-closed extension mechanism for using skills with any agentic provider.
+
+## Usage
+
+```bash
+oasr clone skill-name
+oasr clone skill-name -d /path/to/project
+oasr clone "git-*"                    # Glob pattern
+oasr clone skill-one skill-two        # Multiple skills
+```
+
+## Options
+
+- `-d, --dest DIR` — Destination directory (default: current directory)
+- `--quiet` — Suppress informational output
+- `--json` — Output results in JSON format
+
+## Features
+
+### Glob Pattern Support
+
+Clone multiple skills matching a pattern:
+```bash
+oasr clone "python-*"     # All Python-related skills
+oasr clone "*-api"        # All API-related skills
+```
+
+### Remote Skill Fetching
+
+Remote skills are automatically fetched during clone:
+```bash
+oasr registry add https://github.com/user/skill-repo
+oasr clone my-remote-skill
+```
+
+### Tracking Metadata
+
+Cloned skills include tracking metadata in their frontmatter:
+```yaml
+---
+metadata:
+  oasr:
+    hash: "abc123..."
+    source: "~/.oasr/registry/my-skill"
+    synced_at: "2026-02-01T12:00:00Z"
+---
+```
+
+This enables:
+- `oasr diff` — Check if cloned skills are up-to-date
+- `oasr sync` — Update outdated skills from registry
+
+## Examples
+
+### Basic Clone
+```bash
+# Clone to current directory
+oasr clone csv-analyzer
+
+# Clone to specific project
+oasr clone csv-analyzer -d ~/projects/data-pipeline
+```
+
+### Bulk Clone
+```bash
+# Clone multiple skills
+oasr clone python-test-generator python-docstring-writer
+
+# Clone with glob patterns
+oasr clone "test-*" -d ~/projects/testing-tools
+```
+
+### Integration with Adapters
+
+After cloning, use with IDE adapters:
+```bash
+# Clone skills first
+oasr clone my-skill
+
+# Then adapt for your IDE
+oasr adapter cursor
+```
+
+## Related Commands
+
+- [`oasr exec`](EXEC.md) — Execute skills as CLI tools (no cloning needed)
+- [`oasr registry add`](REGISTRY.md) — Add skills to registry before cloning
+- [`oasr diff`](DIFF.md) — Check status of cloned skills
+- [`oasr sync`](SYNC.md) — Update cloned skills from registry
+
+## Migration from `oasr use`
+
+`oasr clone` replaces the deprecated `oasr use` command. The functionality is identical—only the name has changed for clarity:
+
+```bash
+# Old (deprecated)
+oasr use my-skill
+
+# New
+oasr clone my-skill
+```
+
+> **warning**  
+> `oasr use` will be removed in v0.5.0. Update your scripts and workflows to use `oasr clone`.

oasr-0.4.1/docs/commands/CONFIG.md

@@ -0,0 +1,264 @@
+# `oasr config`
+
+Manage OASR configuration settings. Configure default agent, validation rules, and adapter preferences.
+
+## Usage
+
+```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
+```
+
+## Subcommands
+
+### `config set`
+
+Set configuration values:
+
+```bash
+oasr config set agent codex         # Set default agent
+oasr config set agent copilot
+oasr config set agent claude
+oasr config set agent opencode
+```
+
+**Agent Validation**: Only supported agents can be set. The command validates against available agent drivers.
+
+### `config get`
+
+Retrieve configuration values:
+
+```bash
+oasr config get agent               # Get default agent
+oasr config get validation.strict   # Get validation strictness
+```
+
+Returns the value or indicates if not set:
+```
+codex
+```
+
+### `config list`
+
+Display all configuration with formatted output:
+
+```bash
+oasr config list
+```
+
+**Example output:**
+```
+╭─────────────────────────────────────────╮
+│ OASR Configuration                      │
+├─────────────────────────────────────────┤
+│                                         │
+│ 📍 Config: ~/.oasr/config.toml         │
+│                                         │
+│ Agent Configuration                     │
+│   Default: codex                        │
+│                                         │
+│ Available Agents                        │
+│   ✓ codex                               │
+│   ✓ copilot                             │
+│   ✗ claude                              │
+│   ✗ opencode                            │
+│                                         │
+│ Validation Settings                     │
+│   Reference max lines: 500              │
+│   Strict mode: false                    │
+│                                         │
+│ Adapter Settings                        │
+│   Default targets: cursor, windsurf     │
+│                                         │
+╰─────────────────────────────────────────╯
+```
+
+**Agent Availability Indicators:**
+- ✓ — Agent CLI binary found in PATH
+- ✗ — Agent CLI binary not installed
+
+### `config path`
+
+Show the location of the configuration file:
+
+```bash
+oasr config path
+```
+
+Returns:
+```
+/home/user/.oasr/config.toml
+```
+
+## Configuration Structure
+
+The config file uses TOML format:
+
+```toml
+[agent]
+default = "codex"
+
+[validation]
+reference_max_lines = 500
+strict = false
+
+[adapter]
+default_targets = ["cursor", "windsurf"]
+```
+
+## Agent Configuration
+
+### Setting a Default Agent
+
+Configure which agent `oasr exec` uses by default:
+
+```bash
+oasr config set agent codex
+```
+
+This allows you to run skills without specifying `--agent` each time:
+
+```bash
+# Uses configured default agent
+oasr exec my-skill -p "Do something"
+```
+
+### Supported Agents
+
+| Agent | CLI Binary | Command Format |
+|-------|-----------|----------------|
+| **Codex** | `codex` | `codex exec "<prompt>"` |
+| **Copilot** | `copilot` | `copilot -p "<prompt>"` |
+| **Claude** | `claude` | `claude <prompt> -p` |
+| **OpenCode** | `opencode` | `opencode run "<prompt>"` |
+
+### Checking Agent Availability
+
+Use `oasr config list` to see which agents are installed and available:
+
+```bash
+oasr config list
+```
+
+Look for the **Available Agents** section with ✓/✗ indicators.
+
+## Examples
+
+### Initial Setup
+
+Configure your preferred agent after installation:
+
+```bash
+# Set default agent
+oasr config set agent codex
+
+# Verify configuration
+oasr config get agent
+# Output: codex
+
+# See full config
+oasr config list
+```
+
+### Switching Agents
+
+Change your default agent at any time:
+
+```bash
+# Switch to Copilot
+oasr config set agent copilot
+
+# Verify change
+oasr config get agent
+# Output: copilot
+```
+
+### Troubleshooting
+
+Find your config file location:
+
+```bash
+oasr config path
+```
+
+Check which agents are available:
+
+```bash
+oasr config list | grep -A 5 "Available Agents"
+```
+
+## Related Commands
+
+- [`oasr exec`](EXEC.md) — Execute skills using configured agent
+- [`oasr registry`](REGISTRY.md) — Manage skill registry
+
+## Configuration File Location
+
+Default: `~/.oasr/config.toml`
+
+Override with `--config` flag:
+```bash
+oasr --config /custom/path/config.toml config list
+```
+
+## Error Handling
+
+### Agent Not Available
+
+If you try to set an unavailable agent:
+
+```bash
+oasr config set agent unknown-agent
+```
+
+Output:
+```
+Error: 'unknown-agent' is not a valid agent
+Valid agents: codex, copilot, claude, opencode
+```
+
+### Agent Binary Not Found
+
+If the configured agent binary is not in your PATH:
+
+```bash
+oasr exec my-skill -p "test"
+```
+
+Output:
+```
+Error: Agent 'codex' is not available
+
+Available agents:
+  ✗ codex
+  ✓ copilot
+  ✗ claude
+  ✗ opencode
+
+Configure a different agent:
+  oasr config set agent copilot
+```
+
+## Advanced Usage
+
+### Direct Config File Editing
+
+The config file is plain TOML and can be edited directly:
+
+```bash
+# Open in editor
+$EDITOR ~/.oasr/config.toml
+```
+
+**Warning**: Manual edits bypass validation. Use `oasr config set` when possible.
+
+### Config Validation
+
+OASR validates configuration on load:
+- Agent names must be in supported list
+- Numeric values must be positive integers
+- Boolean values must be true/false
+
+Invalid configs are rejected with helpful error messages.