oasr 0.4.0__tar.gz → 0.5.1__tar.gz

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

@@ -4,9 +4,101 @@ 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.5.1] - 2026-02-02
 
-## [0.4.0] - TBD
+### 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
+- **🔒 Execution Policy System** — Host-level security boundaries for `oasr exec`
+  - Policy profiles define what agents can and cannot do
+  - Conservative safe defaults (fail closed)
+  - User-defined custom profiles in `config.toml`
+  - Pre-execution confirmation for risky operations
+  - Risk triggers: stdin, file prompts, non-safe profiles, network/env/shell access
+- **New CLI flags for `oasr exec`**:
+  - `--profile <name>` — Choose execution policy profile
+  - `-y/--yes` — Skip confirmation prompt
+  - `--confirm` — Force confirmation even for safe operations
+- **Configuration support for policies**:
+  - `[oasr]` section with `default_profile` setting
+  - `[profiles.<name>]` tables for custom profiles
+  - Policy field validation in config schema
+  - Built-in "safe" profile with conservative defaults
+
+### Changed
+- **Security model**: `oasr exec` now requires explicit confirmation for risky execution contexts
+- **Config schema**: Extended to support execution policy profiles
+
+### Security
+- **Prompt injection mitigation**: Policy enforcement reduces impact of malicious skill instructions
+- **Sensitive file protection**: Default deny list includes `~/.ssh`, `~/.aws`, `~/.gnupg`, `.env`, etc.
+- **Execution boundaries**: Clear limits on filesystem access, network, environment variables, and shell commands
+- **User awareness**: Policy summary shown before risky executions
+- **Fail-closed design**: Missing/malformed config falls back to safe defaults
+
+### Documentation
+- **[EXEC.md](docs/commands/EXEC.md)**: Added comprehensive Security Model section
+- **[CONFIG.md](docs/commands/CONFIG.md)**: Added Execution Policy Profiles documentation
+- **Policy examples**: Multiple profile configurations for different use cases
+
+### Technical
+- **New module**: `src/policy/` subpackage with clean API (Profile, load, assess_risk, prompt_confirmation)
+- **41 new tests**: 30 policy tests + 11 config profile tests
+- **Test coverage**: 187 total tests passing (all existing tests still pass)
+- **Backward compatible**: No breaking changes to existing commands
+
+## [0.4.2] - 2026-02-01
+
+### Added
+- **registry prune subcommand**: Added `oasr registry prune` to align with registry command taxonomy
+
+### Changed
+- **clean command**: Deprecated `oasr clean` in favor of `oasr registry prune` (will be removed in v0.6.0)
+- **documentation**: Updated REGISTRY.md with prune subcommand documentation and usage examples
+
+## [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oasr
-Version: 0.4.0
+Version: 0.5.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.0 → oasr-0.5.1}/docs/commands/.INDEX.md

@@ -3,7 +3,7 @@
 ## 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 registry](REGISTRY.md) - Manage skill registry (validate, add, remove, list, sync, prune)
 - [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)
@@ -11,7 +11,6 @@
 - [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
 - [oasr adapter](ADAPTER.md) - Generate IDE/Tooling adapters
 - [oasr update](UPDATE.md) - Update the `oasr` CLI
 - [oasr info](INFO.md) - Show detailed information about a skill
@@ -19,6 +18,9 @@
 
 ## Deprecated Commands
 
+### v0.4.1 Deprecations
+- [oasr clean](CLEAN.md) - **Deprecated**, use `oasr registry prune` instead (will be removed in v0.6.0)
+
 ### v0.4.0 Deprecations
 - [oasr use](USE.md) - **Deprecated**, use `oasr clone` instead (will be removed in v0.5.0)
 

oasr-0.5.1/docs/commands/CLEAN.md

@@ -0,0 +1,13 @@
+# `oasr clean` (DEPRECATED)
+
+> **⚠️ Warning: This command is deprecated and will be removed in v0.6.0.**  
+> Use `oasr registry prune` instead.
+
+Remove orphaned manifests and entries for missing skills.
+
+```bash
+oasr clean              # Shows deprecation warning
+oasr registry prune     # New command (recommended)
+```
+
+This command now delegates to `oasr registry prune`. See [REGISTRY.md](./REGISTRY.md#oasr-registry-prune) for full documentation.

{oasr-0.4.0 → oasr-0.5.1}/docs/commands/CLONE.md

@@ -17,7 +17,6 @@ oasr clone skill-one skill-two        # Multiple skills
 ## Options
 
 - `-d, --dest DIR` — Destination directory (default: current directory)
-- `-r, --recursive` — Create destination directory if it doesn't exist
 - `--quiet` — Suppress informational output
 - `--json` — Output results in JSON format
 

{oasr-0.4.0 → oasr-0.5.1}/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
 
@@ -241,6 +260,63 @@ Configure a different agent:
   oasr config set agent copilot
 ```
 
+## Execution Policy Profiles (v0.5.0+)
+
+Policy profiles define security boundaries for `oasr exec`. They control what agents can do during skill execution.
+
+### Default Profile
+
+Set the default execution policy profile:
+
+```bash
+oasr config set oasr.default_profile safe
+```
+
+This determines which profile is used unless overridden with `--profile`.
+
+### Defining Custom Profiles
+
+Add custom profiles to `~/.oasr/config.toml`:
+
+```toml
+[oasr]
+default_profile = "safe"
+
+# Conservative default
+[profiles.safe]
+fs_read_roots = ["./"]
+fs_write_roots = ["./out", "./.oasr"]
+deny_paths = ["~/.ssh", "~/.aws", "~/.gnupg", ".env"]
+allowed_commands = ["rg", "fd", "jq", "cat"]
+deny_shell = true
+network = false
+allow_env = false
+
+# Development profile (more permissive)
+[profiles.dev]
+fs_read_roots = ["./", "~/projects"]
+fs_write_roots = ["./", "~/projects/output"]
+deny_paths = ["~/.ssh", "~/.aws"]
+allowed_commands = ["bash", "curl", "git", "python"]
+deny_shell = false
+network = true
+allow_env = true
+```
+
+### Profile Settings Reference
+
+| Setting | Type | Description |
+|---------|------|-------------|
+| `fs_read_roots` | list[string] | Allowed filesystem read locations |
+| `fs_write_roots` | list[string] | Allowed filesystem write locations |
+| `deny_paths` | list[string] | Explicitly denied paths |
+| `allowed_commands` | list[string] | Permitted shell commands |
+| `deny_shell` | bool | Deny all shell execution |
+| `network` | bool | Allow network access |
+| `allow_env` | bool | Allow environment variable access |
+
+See [`oasr exec` documentation](EXEC.md#security-model) for detailed security model explanation.
+
 ## Advanced Usage
 
 ### Direct Config File Editing

{oasr-0.4.0 → oasr-0.5.1}/docs/commands/EXEC.md

@@ -2,6 +2,8 @@
 
 Execute skills as CLI tools from anywhere on your system. Run skills with agent-driven execution without needing to clone them first.
 
+> **🔒 Security Note**: As of v0.5.0, `oasr exec` includes host-level execution policy enforcement to protect against prompt injection and unsafe agent behavior. See [Security Model](#security-model) below.
+
 ## Usage
 
 ```bash
@@ -13,6 +15,9 @@ oasr exec <skill-name> [options]
 - `-p, --prompt TEXT` — Inline prompt/instructions for the agent
 - `-i, --instructions FILE` — Read prompt from a file
 - `-a, --agent AGENT` — Override the default agent (codex, copilot, claude, opencode)
+- `--profile PROFILE` — Use a specific execution policy profile (default: from config)
+- `-y, --yes` — Skip confirmation prompt for risky operations
+- `--confirm` — Force confirmation even for safe operations
 
 ## Features
 
@@ -311,6 +316,173 @@ This allows skills to:
 - Tracking skill versions
 - Working offline
 
+## Security Model
+
+### Overview
+
+OASR enforces **host-level execution policies** to reduce the impact of prompt injection and unsafe agent behavior. Policies define what agents can and cannot do, protecting sensitive files and preventing unauthorized actions.
+
+**Key Principles:**
+- OASR does not judge skills
+- OASR enforces user-defined host policy (execution ceilings)
+- Skills and agents cannot override policy
+- Policies stored in `~/.oasr/config.toml`
+- Conservative defaults (fail closed)
+
+### Policy Profiles
+
+Execution policies are organized into profiles. Each profile defines:
+
+| Setting | Description | Safe Default |
+|---------|-------------|--------------|
+| `fs_read_roots` | Allowed read locations | `["./"]` |
+| `fs_write_roots` | Allowed write locations | `["./out", "./.oasr"]` |
+| `deny_paths` | Explicitly denied paths | `["~/.ssh", "~/.aws", "~/.gnupg", ".env"]` |
+| `allowed_commands` | Permitted shell commands | `["rg", "fd", "jq", "cat"]` |
+| `deny_shell` | Block shell execution | `true` |
+| `network` | Allow network access | `false` |
+| `allow_env` | Allow environment access | `false` |
+
+### Risk Triggers
+
+OASR requires explicit confirmation when:
+
+1. **Input from stdin** (non-interactive/piped)
+2. **Prompt from file** (`-i/--instructions`)
+3. **Non-safe profile** in use
+4. **Environment access** enabled
+5. **Network access** enabled
+6. **Shell execution** allowed
+7. **Force confirmation** flag (`--confirm`)
+
+### Confirmation Flow
+
+When risk triggers are detected:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+EXECUTION POLICY REVIEW
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Skill:             csv-analyzer
+Agent:             codex
+Profile:           safe
+Network:           denied
+Environment:       denied
+Shell:             denied
+Allowed commands:  rg, fd, jq, cat
+Read roots:        ./
+Write roots:       ./out, ./.oasr
+Deny paths:        ~/.ssh, ~/.aws, ~/.gnupg, ~/.config, .env
+
+⚠  This execution requires confirmation due to:
+   - Input from stdin (non-interactive)
+
+Proceed? [y/N] 
+```
+
+**Default answer is No** (safe).
+
+### Configuration
+
+Define profiles in `~/.oasr/config.toml`:
+
+```toml
+[oasr]
+default_profile = "safe"
+
+[profiles.safe]
+fs_read_roots = ["./"]
+fs_write_roots = ["./out", "./.oasr"]
+deny_paths = ["~/.ssh", "~/.aws", "~/.gnupg", "~/.config", ".env"]
+allowed_commands = ["rg", "fd", "jq", "cat"]
+deny_shell = true
+network = false
+allow_env = false
+
+[profiles.dev]
+# More permissive for development
+network = true
+allow_env = true
+deny_shell = false
+allowed_commands = ["bash", "curl", "git", "python", "node"]
+```
+
+### Usage Examples
+
+#### Safe Default (No Confirmation)
+```bash
+# Interactive prompt, safe profile
+oasr exec csv-analyzer -p "Analyze data"
+# No confirmation needed
+```
+
+#### Stdin Triggers Confirmation
+```bash
+# Non-interactive input
+echo "data" | oasr exec csv-analyzer
+# Requires confirmation (unless --yes)
+```
+
+#### Skip Confirmation
+```bash
+# Use --yes to bypass (use carefully!)
+echo "data" | oasr exec csv-analyzer --yes
+```
+
+#### Use Different Profile
+```bash
+# Use 'dev' profile with more permissions
+oasr exec api-tester -p "Run tests" --profile dev
+```
+
+#### Force Confirmation
+```bash
+# Force confirmation even if safe
+oasr exec data-processor -p "Process" --confirm
+```
+
+### Best Practices
+
+1. **Use safe defaults**: Start with the built-in safe profile
+2. **Create custom profiles**: Define profiles for different trust levels
+3. **Be explicit with --yes**: Only skip confirmation when you understand the risks
+4. **Review policy before confirming**: Read the summary carefully
+5. **Protect sensitive paths**: Always include `~/.ssh`, `~/.aws`, etc. in `deny_paths`
+6. **Limit commands**: Only allow necessary commands in `allowed_commands`
+7. **Use profiles per context**: Different profiles for dev/prod/testing
+
+### What This Protects Against
+
+✅ **Prompt injection attempts** that try to access sensitive files  
+✅ **Unsafe agent behavior** (network calls, shell execution)  
+✅ **Accidental exposure** of credentials or secrets  
+✅ **Unauthorized file access** outside allowed roots  
+✅ **Malicious skill instructions** that exceed policy
+
+### What This Does NOT Do
+
+❌ NLP-based prompt injection detection  
+❌ Prompt rewriting or sanitization  
+❌ Skill correctness validation  
+❌ Agent-specific permission models  
+❌ Plan-gated execution (staged for future)
+
+### Limitations
+
+- **Confirmation is on execution, not per-action**: Policy is checked before running, not during
+- **Agent behavior is not monitored**: Once confirmed, agent runs with specified permissions
+- **Trust required**: You must trust the agent CLI itself
+- **File-level enforcement not yet implemented**: Path checks are advisory in v0.5.0
+
+### Future Enhancements
+
+Planned for future releases:
+- Plan-gated execution (structured plan approval)
+- Runtime file access enforcement
+- Command allowlist enforcement via executor
+- Network access controls
+- Real-time policy violations monitoring
+
 ## Configuration
 
 ### Set Default Agent

{oasr-0.4.0 → oasr-0.5.1}/docs/commands/REGISTRY.md

@@ -105,6 +105,40 @@ Syncing remote skills...
 Synced: 2 skills
 ```
 
+### `oasr registry prune`
+
+Clean up corrupted/missing skills and orphaned artifacts:
+
+```bash
+oasr registry prune              # Interactive cleanup
+oasr registry prune -y           # Skip confirmation
+oasr registry prune --dry-run    # Show what would be cleaned
+oasr registry prune --json       # JSON output
+```
+
+This command:
+- Removes skills whose source files/URLs are no longer accessible
+- Removes orphaned manifest files not in the registry
+- Requires confirmation unless `-y` flag is used
+
+**Example output:**
+```bash
+$ oasr registry prune
+Checking 3 remote skill(s)...
+  ↓ python-analyzer (checking GitHub...)
+  ✓ python-analyzer (checked)
+
+The following will be cleaned:
+
+Skills with missing sources:
+  ✗ old-skill (/path/to/missing)
+
+Proceed with cleanup? [y/N] y
+Removed skill: old-skill
+
+Cleaned 1 skill(s), 0 manifest(s)
+```
+
 ## Migration from v0.2.0
 
 The v0.3.0 CLI taxonomy reorganizes commands under the `registry` subcommand:
@@ -117,3 +151,5 @@ The v0.3.0 CLI taxonomy reorganizes commands under the `registry` subcommand:
 | `oasr status` | `oasr registry -v` |
 | `oasr sync` (manifest validation) | `oasr registry` |
 | `oasr sync --update` (remote sync) | `oasr registry sync` |
+
+**v0.4.1 update:** `oasr clean` → `oasr registry prune`