Add typed handles, exports, bundle APIs, and tests

Introduce typed resource handles and export result types, refactor Bundle to expose file/skill/prompt/toolset/agent_spec accessors and selection logic, and add comprehensive tests and examples. Key changes:

- New modules: src/musher/_handles.py (FileHandle, SkillHandle, PromptHandle, ToolsetHandle, AgentSpecHandle, BundleSelection) and src/musher/_export.py (ClaudePluginExport, OpenAILocalSkill, OpenAIInlineSkill).
- Refactor src/musher/_bundle.py to build typed handles from raw assets, add file()/files(), skill()/skills(), prompt()/prompts(), toolset()/toolsets(), agent_spec()/agent_specs(), select(), and stubs for export/install/write_lockfile; internal helper functions for handle construction added.
- Export new types and handles from src/musher/__init__.py.
- Adjust AssetType names in src/musher/_types.py (AGENT_SPEC, TOOLSET) and update tests in tests/test_types.py.
- Add many unit tests: tests/test_handles.py, tests/test_export.py, tests/test_bundle.py (updated) to cover the new APIs and behaviors.
- Add example scripts demonstrating exports, skill installation, selections, and lockfile usage (examples/*.py) and a lefthook.yml example.
- Devcontainer changes: removed the Claude devcontainer feature and added base_install_claude_code() to .devcontainer/scripts/lib/base-setup.sh to install Claude Code via its installer; small API update in examples/pull_bundle.py (asset->file, assets->files, file.text()).

Note: export/install methods are currently stubs raising NotImplementedError; tests assert that behavior where applicable.

Author: justinmerrell

.devcontainer/devcontainer.json

@@ -54,9 +54,6 @@
     // --- Linting ---
     "ghcr.io/lukewiwa/features/shellcheck:0": { "version": "stable" },
 
-    // --- AI tooling ---
-    "ghcr.io/anthropics/devcontainer-features/claude-code:1": {}
-
     // --- Optional: Infrastructure tooling (uncomment as needed) ---
     // "ghcr.io/devcontainers-extra/features/opentofu:1": {},
     // "ghcr.io/devcontainers-extra/features/digitalocean-cli:1": {},

.devcontainer/scripts/lib/base-setup.sh

@@ -66,6 +66,23 @@ base_fix_nvm_permissions() {
   fix_nvm_permissions
 }
 
+# --- Claude Code ---
+
+# Installs Claude Code via the native installer if not already present.
+#
+# Outputs:
+#   Writes progress to stderr via log()
+# Returns:
+#   0 on success, non-zero on failure
+base_install_claude_code() {
+  if has_cmd claude; then
+    log "Claude Code already installed, skipping"
+    return 0
+  fi
+  log "Installing Claude Code via native installer..."
+  curl -fsSL https://claude.ai/install.sh | bash
+}
+
 # --- Codex CLI ---
 
 # Installs the Codex CLI if not already present.
@@ -121,6 +138,7 @@ base_setup() {
   base_setup_config_dirs
   base_setup_cache_dirs
   base_fix_nvm_permissions
+  base_install_claude_code
   base_install_codex
   base_install_lefthook
   base_verify_tools

examples/claude_install_skills.py

@@ -0,0 +1,23 @@
+"""Example: Install skills to a Claude skills directory.
+
+Replaces fragile symlink-based workflows with a real directory install.
+Handles file copying, cleanup of stale skills, and directory structure.
+"""
+
+from pathlib import Path
+
+import musher
+
+musher.configure(token="your-token-here")
+
+# Pull the bundle (will raise NotImplementedError until pull is implemented)
+bundle = musher.pull("acme/agent-toolkit:2.0.0")
+
+# Install all skills to the Claude skills directory, cleaning up old versions
+skills_dir = Path.home() / ".claude" / "skills"
+bundle.install_claude_skills(skills_dir, clean=True)
+
+print(f"Installed {len(bundle.skills())} skills to {skills_dir}")
+for skill in bundle.skills():
+    print(f"  {skill.name}: {skill.description}")
+    print(f"    Files: {len(skill.files())}")

examples/claude_safe_skills.py

@@ -0,0 +1,25 @@
+"""Example: Select a subset of skills and export as a Claude plugin.
+
+Demonstrates per-session skill narrowing — only expose the skills your agent
+actually needs, reducing the attack surface and avoiding tool overload.
+"""
+
+from pathlib import Path
+
+import musher
+
+musher.configure(token="your-token-here")
+
+# Pull the full bundle (will raise NotImplementedError until pull is implemented)
+bundle = musher.pull("acme/agent-toolkit:2.0.0")
+
+# Select only the skills needed for this session
+selection = bundle.select(skills=["web-search", "calculator"])
+
+# Export the selection as a Claude plugin
+plugin = selection.export_claude_plugin("safe-tools", dest=Path("./plugins"))
+print(f"Plugin exported to: {plugin.path}")
+
+# Verify only 2 skills are present
+for skill in selection.skills():
+    print(f"  Skill: {skill.name} — {skill.description}")

examples/openai_local_hosted.py

@@ -0,0 +1,27 @@
+"""Example: Export a skill for both OpenAI local-path and inline-zip formats.
+
+Demonstrates dual-format export from a single skill — useful when you need
+the same skill available as a local directory (for development) and as an
+inline zip (for deployment/sharing).
+"""
+
+import musher
+
+musher.configure(token="your-token-here")
+
+# Pull the bundle (will raise NotImplementedError until pull is implemented)
+bundle = musher.pull("acme/agent-toolkit:2.0.0")
+
+# Get a single skill
+search = bundle.skill("web-search")
+
+# Export as local directory for development
+local = search.export_openai_local_skill()
+print(f"Local skill: {local.name} at {local.path}")
+print(f"  Registration dict: {local.to_dict()}")
+
+# Export as inline zip for deployment
+inline = search.export_openai_inline_skill()
+print(f"Inline skill: {inline.name}")
+print(f"  Base64 size: {len(inline.content_base64)} chars")
+print(f"  Registration dict: {inline.to_dict()}")

examples/pinned_release.py

@@ -0,0 +1,24 @@
+"""Example: Digest-pinned pull with verification and lockfile.
+
+Demonstrates pulling a specific bundle version by digest, verifying integrity,
+and writing a lockfile for reproducible deployments.
+"""
+
+import musher
+
+musher.configure(token="your-token-here")
+
+# Pull by digest for reproducibility (will raise NotImplementedError until pull is implemented)
+bundle = musher.pull("acme/agent-toolkit@sha256:abc123def456")
+
+# Verify all asset checksums match the manifest
+bundle.verify()
+print(f"Bundle verified: {bundle.ref} v{bundle.version}")
+
+# Write a lockfile for CI/CD reproducibility
+lockfile_path = bundle.write_lockfile()
+print(f"Lockfile written to: {lockfile_path}")
+
+# Inspect contents
+for fh in bundle.files():
+    print(f"  {fh.logical_path} ({fh.media_type or 'unknown'})")

examples/pull_bundle.py

@@ -1,4 +1,4 @@
-"""Example: Pull a bundle and list its assets."""
+"""Example: Pull a bundle and list its files."""
 
 import musher
 
@@ -8,11 +8,11 @@
 # Pull a bundle (will raise NotImplementedError until implemented)
 bundle = musher.pull("myorg/my-bundle:1.0.0")
 
-# List all assets
-for asset in bundle.assets():
-    print(f"{asset.logical_path} ({asset.asset_type}): {asset.size_bytes} bytes")
+# List all files
+for fh in bundle.files():
+    print(f"{fh.logical_path} ({fh.media_type or 'unknown'})")
 
-# Get a specific asset
-prompt = bundle.asset("prompts/main.txt")
+# Get a specific file
+prompt = bundle.file("prompts/main.txt")
 if prompt:
-    print(f"Prompt content: {prompt.content.decode()}")
+    print(f"Prompt content: {prompt.text()}")

examples/pydantic_ai_prompts.py

@@ -0,0 +1,33 @@
+"""Example: Use versioned prompts and toolsets from a Musher bundle.
+
+Demonstrates pulling prompt templates and tool configurations from a bundle
+for use with PydanticAI or similar frameworks that consume structured config.
+"""
+
+import musher
+
+musher.configure(token="your-token-here")
+
+# Pull a bundle with prompts and toolsets (will raise NotImplementedError until pull is implemented)
+bundle = musher.pull("acme/prompt-library:1.2.0")
+
+# Access versioned prompts by name
+system_prompt = bundle.prompt("system")
+print(f"System prompt: {system_prompt.text()[:80]}...")
+
+# List all available prompts
+print(f"\nAvailable prompts ({len(bundle.prompts())}):")
+for p in bundle.prompts():
+    print(f"  {p.name}: {p.text()[:60]}...")
+
+# Access toolset configuration
+print(f"\nAvailable toolsets ({len(bundle.toolsets())}):")
+for t in bundle.toolsets():
+    config = t.parse_json()
+    print(f"  {t.name}: {config}")
+
+# Access agent specs
+print(f"\nAvailable agent specs ({len(bundle.agent_specs())}):")
+for a in bundle.agent_specs():
+    spec = a.parse_json()
+    print(f"  {a.name}: {spec.get('name', 'unnamed')}")

lefthook.yml

@@ -0,0 +1,42 @@
+# EXAMPLE USAGE:
+#
+#   Refer for explanation to following link:
+#   https://lefthook.dev/configuration/
+#
+# pre-push:
+#   jobs:
+#     - name: packages audit
+#       tags:
+#         - frontend
+#         - security
+#       run: yarn audit
+#
+#     - name: gems audit
+#       tags:
+#         - backend
+#         - security
+#       run: bundle audit
+#
+# pre-commit:
+#   parallel: true
+#   jobs:
+#     - run: yarn eslint {staged_files}
+#       glob: "*.{js,ts,jsx,tsx}"
+#
+#     - name: rubocop
+#       glob: "*.rb"
+#       exclude:
+#         - config/application.rb
+#         - config/routes.rb
+#       run: bundle exec rubocop --force-exclusion -- {all_files}
+#
+#     - name: govet
+#       files: git ls-files -m
+#       glob: "*.go"
+#       run: go vet -- {files}
+#
+#     - script: "hello.js"
+#       runner: node
+#
+#     - script: "hello.go"
+#       runner: go run

src/musher/__init__.py

@@ -14,6 +14,15 @@
     RegistryError,
     VersionNotFoundError,
 )
+from musher._export import ClaudePluginExport, OpenAIInlineSkill, OpenAILocalSkill
+from musher._handles import (
+    AgentSpecHandle,
+    BundleSelection,
+    FileHandle,
+    PromptHandle,
+    SkillHandle,
+    ToolsetHandle,
+)
 from musher._types import (
     OCI_MEDIA_TYPE_ASSET,
     OCI_MEDIA_TYPE_CONFIG,
@@ -29,6 +38,7 @@
     "OCI_MEDIA_TYPE_CONFIG",
     # Errors
     "APIError",
+    "AgentSpecHandle",
     # Models
     "Asset",
     # Types
@@ -39,20 +49,28 @@
     "Bundle",
     "BundleNotFoundError",
     "BundleRef",
+    "BundleSelection",
     "BundleSourceType",
     "BundleVersionState",
     "BundleVisibility",
     "CacheError",
+    "ClaudePluginExport",
     "Client",
+    "FileHandle",
     "IntegrityError",
     "Manifest",
     "ManifestAsset",
     # Config
     "MusherConfig",
     "MusherError",
+    "OpenAIInlineSkill",
+    "OpenAILocalSkill",
+    "PromptHandle",
     "RateLimitError",
     "RegistryError",
     "ResolveResult",
+    "SkillHandle",
+    "ToolsetHandle",
     "VersionNotFoundError",
     "configure",
     "get_config",