oasr 0.5.2__tar.gz → 0.6.0__tar.gz

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

@@ -4,6 +4,22 @@ 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.6.0] - 2026-02-03
+
+### Added
+- **🧭 Profile selection command** — New `oasr profile` command with interactive selector or explicit profile selection.
+- **📄 Profile file support** — Auto-load `~/.oasr/profile/*.toml` profiles with inline config overrides.
+- **🔧 Config subcommands** — `oasr config agent|validation|adapter|oasr|profiles` for focused views.
+- **✅ Config validation and reference** — `oasr config validate` and `oasr config man` helpers.
+- **Default profiles** — New built-ins: `strict`, `dev`, `unsafe`.
+
+### Changed
+- **Profiles subsystem** — New `profiles` subpackage with loaders, validation, and summary helpers.
+- **Config listing** — Lists profiles with compact capability summaries and completions setting.
+
+### Documentation
+- **Config + profile docs** — Updated configuration guides and new `docs/commands/PROFILE.md`.
+
 ## [0.5.2] - 2026-02-02
 
 ### Added
@@ -25,6 +41,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Adapter, find, help commands
   - Total test count: 282 tests (all passing)
   - Ensures no regressions in existing functionality
+- **⚠️ Exec Unsafe Pass-through** — Optional unsafe mode forwarding for agent CLIs
+  - `oasr exec --unsafe` forwards `--skip-git-repo-check` to Codex
+  - `oasr exec --unsafe` forwards `--dangerously-skip-permissions` to Claude
+  - Unsupported agents (Copilot/OpenCode) emit a warning with guidance
 
 ### Documentation
 - **[docs/commands/COMPLETION.md](docs/commands/COMPLETION.md)**: Complete completion command reference
@@ -34,6 +54,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - 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
+- **[docs/commands/EXEC.md](docs/commands/EXEC.md)**: Documented `--unsafe` and trusted directory guidance
 
 ### Technical
 - **New module**: `src/commands/completion.py` (259 lines) with shell detection and installation

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oasr
-Version: 0.5.2
+Version: 0.6.0
 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
@@ -210,6 +210,7 @@ Classifier: Topic :: Software Development :: Build Tools
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Requires-Python: >=3.10
 Requires-Dist: pyyaml>=6.0
+Requires-Dist: questionary>=2.0.1
 Requires-Dist: tomli-w>=1.0.0
 Requires-Dist: tomli>=2.0.0; python_version < '3.11'
 Provides-Extra: dev
@@ -219,7 +220,7 @@ Description-Content-Type: text/markdown
 
 # OASR
 
-**Open Agent Skill Registry** — Manage reusable AI agent skills across IDEs without drift.
+**Open Agent Skill Registry** — Register, sync, and reuse AI agent skills across IDEs with a single source of truth.
 
 ---
 
@@ -229,16 +230,22 @@ You've built useful skills for your AI coding assistant. They work great in Curs
 
 Each tool expects skills in different locations with different formats:
 
-- Cursor: `.cursor/skills/`
-- Windsurf: `.windsurf/skills/`
+- Cursor: `.cursor/commands/`
+- Windsurf: `.windsurf/workflows/`
 - Claude: `.claude/commands/`
-- Copilot: `.github/.md`
+- Copilot: `.github/prompts/`
 
 So you copy your skills everywhere. Then you improve one. Now the copies are stale. You forget which version is current. Some break silently. This is **skill drift**.
 
 ## The Solution
 
-ASR keeps your skills in one place and generates thin adapters for each IDE.
+ASR keeps your skills in a registry, syncs local and remote sources, and generates thin adapters for each IDE.
+It also lets you execute skills safely with policy profiles.
+
+Key capabilities:
+- Register skills once (local folders or GitHub/GitLab URLs)
+- Sync and track drift across sources
+- Generate IDE adapters and run skills via `oasr exec`
 
 ```text
 ┌─────────────────────────────────────────────────────────┐
@@ -267,12 +274,15 @@ No copying. No drift. One source of truth.
 
 ```bash
 # Register local skills
-oasr add ~/skills/git-commit
-oasr add ~/skills/code-review
+oasr registry add ~/skills/git-commit
+oasr registry add ~/skills/code-review
+
+# List registered skills
+oasr registry list
 
 # Register remote skills from GitHub/GitLab
-oasr add https://github.com/user/skills-repo/tree/main/my-skill
-oasr add https://gitlab.com/org/project/tree/main/cool-skill
+oasr registry add https://github.com/user/skills-repo/tree/main/my-skill
+oasr registry add https://gitlab.com/org/project/tree/main/cool-skill
 
 # Generate adapters for a project
 oasr adapter --output-dir ~/projects/my-app
@@ -294,16 +304,16 @@ ASR supports registering skills directly from GitHub and GitLab repositories:
 
 ```bash
 # Add a skill from GitHub
-oasr add https://github.com/user/repo/tree/main/skills/my-skill
+oasr registry add https://github.com/user/repo/tree/main/skills/my-skill
 
 # Add a skill from GitLab
-oasr add https://gitlab.com/org/project/tree/dev/cool-skill
+oasr registry add https://gitlab.com/org/project/tree/dev/cool-skill
 
 # Sync remote skills (check for updates)
-oasr sync
+oasr registry sync
 
 # Use remote skills
-oasr use my-skill -d ./output
+oasr clone my-skill -d ./output
 ```
 
 **Authentication** (optional, for private repos and higher rate limits):
@@ -313,7 +323,7 @@ export GITHUB_TOKEN=ghp_your_token_here
 export GITLAB_TOKEN=glpat_your_token_here
 ```
 
-Remote skills are fetched on-demand during `adapter` and `use` operations. The registry stores the URL, and `sync` checks if the remote source has changed.
+Remote skills are fetched on-demand during `adapter` and `clone` operations. The registry stores the URL, and `oasr registry sync` checks if the remote source has changed.
 
 ---
 
@@ -345,7 +355,7 @@ See [`oasr completion --help`](docs/commands/COMPLETION.md) for details.
 
 ---
 
-## Supported `asr adapter` IDEs
+## Supported `oasr adapter` IDEs
 
 | IDE            | Adapter    | Output                        |
 |----------------|------------|-------------------------------|
@@ -367,11 +377,11 @@ See [LICENSE](LICENSE).
 
 | Command | Screenshot |
 |---------|-----------|
-| **oasr list** | ![list](docs/.images/list.png) |
-| **oasr add** (local) | ![add](docs/.images/add.png) |
-| **oasr add** (remote) | ![add-remote](docs/.images/add-remote.png) |
-| **oasr sync** | ![sync](docs/.images/sync.png) |
-| **oasr status** | ![status](docs/.images/status.png) |
+| **oasr registry list** | ![list](docs/.images/list.png) |
+| **oasr registry add** (local) | ![add](docs/.images/add.png) |
+| **oasr registry add** (remote) | ![add-remote](docs/.images/add-remote.png) |
+| **oasr registry sync** | ![sync](docs/.images/sync.png) |
+| **oasr registry -v** | ![status](docs/.images/status.png) |
 | **oasr find** | ![find](docs/.images/find.png) |
 | **oasr adapter** | ![adapter](docs/.images/adapter.png) |
 

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

@@ -1,6 +1,6 @@
 # OASR
 
-**Open Agent Skill Registry** — Manage reusable AI agent skills across IDEs without drift.
+**Open Agent Skill Registry** — Register, sync, and reuse AI agent skills across IDEs with a single source of truth.
 
 ---
 
@@ -10,16 +10,22 @@ You've built useful skills for your AI coding assistant. They work great in Curs
 
 Each tool expects skills in different locations with different formats:
 
-- Cursor: `.cursor/skills/`
-- Windsurf: `.windsurf/skills/`
+- Cursor: `.cursor/commands/`
+- Windsurf: `.windsurf/workflows/`
 - Claude: `.claude/commands/`
-- Copilot: `.github/.md`
+- Copilot: `.github/prompts/`
 
 So you copy your skills everywhere. Then you improve one. Now the copies are stale. You forget which version is current. Some break silently. This is **skill drift**.
 
 ## The Solution
 
-ASR keeps your skills in one place and generates thin adapters for each IDE.
+ASR keeps your skills in a registry, syncs local and remote sources, and generates thin adapters for each IDE.
+It also lets you execute skills safely with policy profiles.
+
+Key capabilities:
+- Register skills once (local folders or GitHub/GitLab URLs)
+- Sync and track drift across sources
+- Generate IDE adapters and run skills via `oasr exec`
 
 ```text
 ┌─────────────────────────────────────────────────────────┐
@@ -48,12 +54,15 @@ No copying. No drift. One source of truth.
 
 ```bash
 # Register local skills
-oasr add ~/skills/git-commit
-oasr add ~/skills/code-review
+oasr registry add ~/skills/git-commit
+oasr registry add ~/skills/code-review
+
+# List registered skills
+oasr registry list
 
 # Register remote skills from GitHub/GitLab
-oasr add https://github.com/user/skills-repo/tree/main/my-skill
-oasr add https://gitlab.com/org/project/tree/main/cool-skill
+oasr registry add https://github.com/user/skills-repo/tree/main/my-skill
+oasr registry add https://gitlab.com/org/project/tree/main/cool-skill
 
 # Generate adapters for a project
 oasr adapter --output-dir ~/projects/my-app
@@ -75,16 +84,16 @@ ASR supports registering skills directly from GitHub and GitLab repositories:
 
 ```bash
 # Add a skill from GitHub
-oasr add https://github.com/user/repo/tree/main/skills/my-skill
+oasr registry add https://github.com/user/repo/tree/main/skills/my-skill
 
 # Add a skill from GitLab
-oasr add https://gitlab.com/org/project/tree/dev/cool-skill
+oasr registry add https://gitlab.com/org/project/tree/dev/cool-skill
 
 # Sync remote skills (check for updates)
-oasr sync
+oasr registry sync
 
 # Use remote skills
-oasr use my-skill -d ./output
+oasr clone my-skill -d ./output
 ```
 
 **Authentication** (optional, for private repos and higher rate limits):
@@ -94,7 +103,7 @@ export GITHUB_TOKEN=ghp_your_token_here
 export GITLAB_TOKEN=glpat_your_token_here
 ```
 
-Remote skills are fetched on-demand during `adapter` and `use` operations. The registry stores the URL, and `sync` checks if the remote source has changed.
+Remote skills are fetched on-demand during `adapter` and `clone` operations. The registry stores the URL, and `oasr registry sync` checks if the remote source has changed.
 
 ---
 
@@ -126,7 +135,7 @@ See [`oasr completion --help`](docs/commands/COMPLETION.md) for details.
 
 ---
 
-## Supported `asr adapter` IDEs
+## Supported `oasr adapter` IDEs
 
 | IDE            | Adapter    | Output                        |
 |----------------|------------|-------------------------------|
@@ -148,11 +157,11 @@ See [LICENSE](LICENSE).
 
 | Command | Screenshot |
 |---------|-----------|
-| **oasr list** | ![list](docs/.images/list.png) |
-| **oasr add** (local) | ![add](docs/.images/add.png) |
-| **oasr add** (remote) | ![add-remote](docs/.images/add-remote.png) |
-| **oasr sync** | ![sync](docs/.images/sync.png) |
-| **oasr status** | ![status](docs/.images/status.png) |
+| **oasr registry list** | ![list](docs/.images/list.png) |
+| **oasr registry add** (local) | ![add](docs/.images/add.png) |
+| **oasr registry add** (remote) | ![add-remote](docs/.images/add-remote.png) |
+| **oasr registry sync** | ![sync](docs/.images/sync.png) |
+| **oasr registry -v** | ![status](docs/.images/status.png) |
 | **oasr find** | ![find](docs/.images/find.png) |
 | **oasr adapter** | ![adapter](docs/.images/adapter.png) |
 

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

@@ -7,9 +7,10 @@
 - [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 profile](PROFILE.md) - Select execution profile (NEW in v0.6.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 completion](COMPLETION.md) - Shell tab completion (NEW in v0.6.0)
 - [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 → oasr-0.6.0}/docs/commands/CLONE.md

@@ -11,6 +11,7 @@ Clone skills from the registry to a target directory. Supports glob patterns and
 oasr clone skill-name
 oasr clone skill-name -d /path/to/project
 oasr clone "git-*"                    # Glob pattern
+oasr clone "*"                        # Clone all skills (quote to avoid shell expansion)
 oasr clone skill-one skill-two        # Multiple skills
 ```
 
@@ -28,8 +29,11 @@ Clone multiple skills matching a pattern:
 ```bash
 oasr clone "python-*"     # All Python-related skills
 oasr clone "*-api"        # All API-related skills
+oasr clone "*"            # All skills in registry
 ```
 
+> **Note:** Always quote `*` or glob patterns to prevent your shell from expanding them before OASR receives the pattern.
+
 ### Remote Skill Fetching
 
 Remote skills are automatically fetched during clone:

{oasr-0.5.2 → oasr-0.6.0}/docs/commands/CONFIG.md

@@ -10,6 +10,13 @@ Manage OASR configuration settings.
 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 agent                # Show agent configuration
+oasr config validation           # Show validation settings
+oasr config adapter              # Show adapter settings
+oasr config oasr                 # Show core OASR settings
+oasr config profiles             # Show available profiles
+oasr config man                  # Show config reference
+oasr config validate             # Validate config file
 oasr config path                 # Show config file location
 ```
 
@@ -27,6 +34,13 @@ oasr config path                 # Show config file location
 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 agent                 # Show agent configuration
+oasr config validation            # Show validation settings
+oasr config adapter               # Show adapter settings
+oasr config oasr                  # Show core OASR settings
+oasr config profiles              # Show available profiles
+oasr config man                   # Show config reference
+oasr config validate              # Validate config file
 oasr config path                  # Show config file location
 ```
 
@@ -59,44 +73,62 @@ Returns the value or indicates if not set:
 codex
 ```
 
-### `config list`
+### `config agent`
 
-Display all configuration with formatted output:
+Show default agent and availability:
 
 ```bash
-oasr config list
+oasr config agent
 ```
 
-**Example output:**
+### `config validation`
+
+Show validation configuration:
+
+```bash
+oasr config validation
 ```
-╭─────────────────────────────────────────╮
-│ 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     │
-│                                         │
-╰─────────────────────────────────────────╯
+
+### `config adapter`
+
+Show adapter configuration:
+
+```bash
+oasr config adapter
 ```
 
-**Agent Availability Indicators:**
-- ✓ — Agent CLI binary found in PATH
-- ✗ — Agent CLI binary not installed
+### `config oasr`
+
+Show core OASR settings:
+
+```bash
+oasr config oasr
+```
+
+### `config profiles`
+
+Show available profiles (built-in + custom + profile files):
+
+```bash
+oasr config profiles
+oasr config profiles --names
+```
+
+### `config man`
+
+Show a concise configuration reference:
+
+```bash
+oasr config man
+```
+
+### `config validate`
+
+Validate your config file (creates default if missing):
+
+```bash
+oasr config validate
+```
 
 ### `config path`
 
@@ -106,11 +138,45 @@ Show the location of the configuration file:
 oasr config path
 ```
 
-Returns:
+### `config list`
+
+Display all configuration with formatted output:
+
+```bash
+oasr config list
+```
+
+**Example output:**
 ```
-/home/user/.oasr/config.toml
+Configuration:
+
+  [agent]
+    default = codex ✓
+
+  Available agents: codex, copilot
+
+  [validation]
+    reference_max_lines = 500
+    strict = false
+
+  [adapter]
+    default_targets = cursor, windsurf
+
+  [oasr]
+    default_profile = safe
+    completions = true
+
+  [profiles]
+    safe         network=off env=off shell=off
+    strict       network=off env=off shell=off
+    dev          network=on env=on shell=on
+    unsafe       network=on env=on shell=on
 ```
 
+**Agent Availability Indicators:**
+- ✓ — Agent CLI binary found in PATH
+- ✗ — Agent CLI binary not installed
+
 ## Configuration Structure
 
 The config file uses TOML format:
@@ -125,6 +191,13 @@ strict = false
 
 [adapter]
 default_targets = ["cursor", "windsurf"]
+
+[oasr]
+default_profile = "safe"
+completions = true
+
+[profiles.safe]
+# built-in safe profile (override if desired)
 ```
 
 ## Agent Configuration
@@ -234,7 +307,7 @@ oasr config set agent unknown-agent
 
 Output:
 ```
-Error: 'unknown-agent' is not a valid agent
+Error: Invalid agent 'unknown-agent'
 Valid agents: codex, copilot, claude, opencode
 ```
 
@@ -260,6 +333,12 @@ Configure a different agent:
   oasr config set agent copilot
 ```
 
+### Config Validation
+
+```bash
+oasr config validate
+```
+
 ## Execution Policy Profiles (v0.5.0+)
 
 Policy profiles define security boundaries for `oasr exec`. They control what agents can do during skill execution.
@@ -270,6 +349,7 @@ Set the default execution policy profile:
 
 ```bash
 oasr config set oasr.default_profile safe
+oasr profile dev
 ```
 
 This determines which profile is used unless overridden with `--profile`.
@@ -317,6 +397,10 @@ allow_env = true
 
 See [`oasr exec` documentation](EXEC.md#security-model) for detailed security model explanation.
 
+### Profile Files
+
+Place profile files under `~/.oasr/profile/<name>.toml` (body keys only). Inline profiles override files with the same name.
+
 ## Advanced Usage
 
 ### Direct Config File Editing

{oasr-0.5.2 → oasr-0.6.0}/docs/commands/EXEC.md

@@ -15,9 +15,10 @@ 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)
+- `--profile PROFILE` — Use a specific execution policy profile (default: from config; built-ins: safe, strict, dev, unsafe)
 - `-y, --yes` — Skip confirmation prompt for risky operations
 - `--confirm` — Force confirmation even for safe operations
+- `--unsafe` — Pass unsafe mode flags to the agent CLI (see [Unsafe Mode](#unsafe-mode))
 
 ## Features
 
@@ -80,6 +81,40 @@ oasr exec my-skill -p "Do something"
 oasr exec my-skill --agent copilot -p "Generate code"
 ```
 
+### Unsafe Mode
+
+If your agent refuses to run outside a trusted directory or Git repo, you can pass `--unsafe` to forward the agent's unsafe-mode flags.
+
+```bash
+# Codex: skip git repo trust check
+oasr exec my-skill --unsafe -p "Run in this folder"
+
+# Claude: bypass permission prompts
+oasr exec my-skill --agent claude --unsafe -p "Analyze this project"
+```
+
+**Agent behavior:**
+
+- **Codex**: adds `--skip-git-repo-check` (Codex CLI requires git repo by default; see Codex non-interactive docs)
+- **Claude**: adds `--dangerously-skip-permissions` (bypasses Claude permission prompts)
+- **Copilot / OpenCode**: `--unsafe` is not forwarded; configure permissions in their own configs
+
+**Trusted directory guidance:**
+
+- **Codex**: You can avoid `--unsafe` by initializing a git repo (`git init`) or adding trusted directories via Codex config (`--add-dir`).
+- **Claude**: Use `--add-dir` or configure allowed tools/permissions in Claude settings.
+- **OpenCode**: Use `permission.external_directory` in `opencode.json` to allow external paths.
+
+### Profile Selection
+
+```bash
+# Set default profile
+oasr profile dev
+
+# Override per execution
+oasr exec my-skill --profile strict -p "prompt"
+```
+
 ### Skill Execution Flow
 
 1. **Load skill** from registry by name

{oasr-0.5.2 → oasr-0.6.0}/docs/commands/HELP.md

@@ -9,4 +9,5 @@ Show help for any command.
 oasr help
 oasr help list
 oasr help adapter
+oasr help profile
 ```

oasr-0.6.0/docs/commands/PROFILE.md

@@ -0,0 +1,25 @@
+# `oasr profile`
+
+List and select execution policy profiles.
+
+```bash
+oasr profile              # Interactive selector (TTY only)
+oasr profile <name>       # Set default profile
+```
+
+**Non-interactive behavior:** prints profiles and exits with a hint.
+
+## Examples
+
+```bash
+# List and select interactively
+oasr profile
+
+# Set default profile
+oasr profile dev
+```
+
+## Related
+
+- [Policy Profiles](../configuration/profiles.md)
+- [Config command](CONFIG.md)

{oasr-0.5.2 → oasr-0.6.0}/docs/commands/UPDATE.md

@@ -17,8 +17,8 @@ oasr update --quiet              # Suppress info messages
 - Remote must be configured (typically GitHub)
 
 > **NOTE**
-> PyPI installations are not available yet, but will be coming soon.
-> Current `oasr update` command only works with git installations.
+> `oasr update` targets git installs. For PyPI installs, use:
+> `pip install --upgrade oasr`
 
 **Behavior:**
 
@@ -27,6 +27,7 @@ oasr update --quiet              # Suppress info messages
 - Displays truncated changelog with commit count
 - Reinstalls package with `uv pip install -e .` or falls back to `pip`
 - Suppresses verbose git output
+- If already up to date, checks PyPI and prints update hints to **stderr** when a newer version exists (to preserve stdout for piping)
 
 **JSON Output:**