feat!: remove OCI layer, deprecated aliases, and stub methods

Remove the OCI module and constants, drop deprecated `api_key`/`api_url`
parameter aliases from `configure()`, remove unimplemented stub methods
(`install_vscode_skills`, `write_lockfile`, `verify`), and add dynamic
version resolution from package metadata.

BREAKING CHANGE: `OCI_MEDIA_TYPE_ASSET`, `OCI_MEDIA_TYPE_CONFIG`,
`api_key`, `api_url`, `install_vscode_skills()`, `write_lockfile()`,
and `verify()` have been removed from the public API.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: justinmerrell

.github/release-please/config.json

@@ -9,13 +9,6 @@
       "include-component-in-tag": false,
       "bump-minor-pre-major": true,
       "bump-patch-for-minor-pre-major": true,
-      "extra-files": [
-        {
-          "type": "toml",
-          "path": "pyproject.toml",
-          "jsonpath": "$.project.version"
-        }
-      ],
       "changelog-sections": [
         { "type": "feat", "section": "Features" },
         { "type": "fix", "section": "Bug Fixes" },

.github/release-please/manifest.json

@@ -1,3 +1,3 @@
-{
-  ".": "0.1.1"
-}
+{
+  ".": "0.1.1"
+}

.github/workflows/release.yml

@@ -7,8 +7,6 @@ on:
 permissions:
   contents: write
   pull-requests: write
-  id-token: write
-  attestations: write
 
 jobs:
   release-please:
@@ -27,6 +25,10 @@ jobs:
     needs: release-please
     if: ${{ needs.release-please.outputs.release_created }}
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
     steps:
       - uses: actions/checkout@v4
 
@@ -53,6 +55,8 @@ jobs:
     needs: build
     runs-on: ubuntu-latest
     environment: testpypi
+    permissions:
+      id-token: write
     steps:
       - uses: actions/download-artifact@v4
         with:
@@ -62,19 +66,18 @@ jobs:
       - uses: pypa/gh-action-pypi-publish@release/v1
         with:
           repository-url: https://test.pypi.org/legacy/
-          password: ${{ secrets.TEST_PYPI_API_TOKEN }}
 
   publish-pypi:
     needs: [build, release-please]
     if: ${{ !contains(needs.release-please.outputs.tag_name, '-') }}
     runs-on: ubuntu-latest
     environment: release
+    permissions:
+      id-token: write
     steps:
       - uses: actions/download-artifact@v4
         with:
           name: dist
           path: dist/
 
       - uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          password: ${{ secrets.PYPI_API_TOKEN }}

CHANGELOG.md

@@ -1,13 +1,13 @@
-# Changelog
-
-## [0.1.1](https://github.com/musher-dev/python-sdk/compare/0.1.0...0.1.1) (2026-03-24)
-
-
-### Features
-
-* stub out musher Python SDK package ([a1d952b](https://github.com/musher-dev/python-sdk/commit/a1d952b56a2f1acf20f968ed6bcf841241789d0b))
-
-
-### Bug Fixes
-
-* remove CRLF line endings from post-create.sh ([4f85ffa](https://github.com/musher-dev/python-sdk/commit/4f85ffabddfeb9b54022b99c7c67dfd8b19df041))
+# Changelog
+
+## [0.1.1](https://github.com/musher-dev/python-sdk/compare/0.1.0...0.1.1) (2026-03-24)
+
+
+### Features
+
+* stub out musher Python SDK package ([a1d952b](https://github.com/musher-dev/python-sdk/commit/a1d952b56a2f1acf20f968ed6bcf841241789d0b))
+
+
+### Bug Fixes
+
+* remove CRLF line endings from post-create.sh ([4f85ffa](https://github.com/musher-dev/python-sdk/commit/4f85ffabddfeb9b54022b99c7c67dfd8b19df041))

README.md

@@ -17,7 +17,7 @@ pip install musher-sdk
 import musher
 
 # Explicit token
-musher.configure(api_key="your-token")
+musher.configure(token="your-token")
 
 bundle = musher.pull("myorg/my-bundle:1.0.0")
 
@@ -64,8 +64,8 @@ import musher
 
 # All parameters are optional — omitted values auto-discover
 musher.configure(
-    api_key="your-token",  # or token="your-token"
-    api_url="https://custom.dev",  # or registry_url="https://custom.dev"
+    token="your-token",
+    registry_url="https://custom.dev",
     cache_dir=Path("/tmp/cache"),
 )
 ```
@@ -87,12 +87,8 @@ The SDK uses a content-addressable disk cache:
 - Sync (`Client`) and async (`AsyncClient`) clients
 - Content-addressable cache with TTL and garbage collection
 - Typed handles: skills, prompts, toolsets, agent specs
-
-## What's Stubbed
-
-- `export_claude_plugin()`, `install_vscode_skills()`, `install_claude_skills()`
-- `write_lockfile()`, `verify()`
-- OCI direct pull (`OCIClient`)
+- `export_claude_plugin()` — export bundle as a Claude plugin
+- `install_claude_skills()` — install skills to a directory
 
 ## License
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "musher-sdk"
-version = "0.1.0"
+version = "0.1.1"
 description = "Python SDK for the Musher bundle distribution platform"
 readme = "README.md"
 license = "Apache-2.0"

src/musher/__init__.py

@@ -1,5 +1,7 @@
 """Musher Python SDK — programmatic access to the Musher bundle registry."""
 
+from importlib.metadata import PackageNotFoundError, version as _metadata_version
+
 from musher._auth import resolve_registry_url
 from musher._bundle import Asset, Bundle, Manifest, ManifestAsset, ResolveResult
 from musher._client import AsyncClient, Client
@@ -25,18 +27,19 @@
     ToolsetHandle,
 )
 from musher._types import (
-    OCI_MEDIA_TYPE_ASSET,
-    OCI_MEDIA_TYPE_CONFIG,
     AssetType,
     BundleRef,
     BundleSourceType,
     BundleVersionState,
     BundleVisibility,
 )
 
+try:
+    __version__ = _metadata_version("musher-sdk")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
 __all__ = [
-    "OCI_MEDIA_TYPE_ASSET",
-    "OCI_MEDIA_TYPE_CONFIG",
     "APIError",
     "AgentSpecHandle",
     "Asset",
@@ -68,6 +71,7 @@
     "SkillHandle",
     "ToolsetHandle",
     "VersionNotFoundError",
+    "__version__",
     "configure",
     "get_config",
     "pull",

src/musher/_bundle.py

@@ -182,7 +182,7 @@ class Bundle:
     _toolset_handles: dict[str, ToolsetHandle] | None = field(default=None, repr=False)
     _agent_spec_handles: dict[str, AgentSpecHandle] | None = field(default=None, repr=False)
 
-    # ── File access (replaces asset/assets/assets_by_type) ──────────
+    # ── File access ──────────────────────────────────────────────
 
     def file(self, logical_path: str) -> FileHandle | None:
         """Get a single file by logical path."""
@@ -288,7 +288,7 @@ def select(
             _files=sel_files,
         )
 
-    # ── Export / install stubs ──────────────────────────────────────
+    # ── Export / install ───────────────────────────────────────────
 
     def export_claude_plugin(
         self,
@@ -299,16 +299,6 @@ def export_claude_plugin(
         """Export bundle as a Claude plugin."""
         return self.select(skills=skills).export_claude_plugin(plugin_name, dest=dest)
 
-    def install_vscode_skills(
-        self,
-        _dest: Path,
-        _skills: list[str] | None = None,
-        *,
-        _clean: bool = False,
-    ) -> None:
-        """Install skills to a VS Code skills directory. Raises NotImplementedError (stub)."""
-        raise NotImplementedError
-
     def install_claude_skills(
         self,
         dest: Path,
@@ -345,14 +335,6 @@ def install_claude_skills(
                 _json.dumps(marker_data, indent=2) + "\n", encoding="utf-8"
             )
 
-    def write_lockfile(self, _dest: Path | None = None) -> Path:
-        """Write a lockfile for the current bundle. Raises NotImplementedError (stub)."""
-        raise NotImplementedError
-
-    def verify(self) -> bool:
-        """Verify all asset checksums. Raises NotImplementedError (stub)."""
-        raise NotImplementedError
-
     # ── Internal ────────────────────────────────────────────────────
 
     def _build_handles(self) -> None:

src/musher/_config.py

@@ -39,9 +39,7 @@ class MusherConfig:
 def configure(  # noqa: PLR0913
     *,
     token: object = _UNSET,
-    api_key: object = _UNSET,
     registry_url: str | None = None,
-    api_url: str | None = None,
     cache_dir: Path | None = None,
     config_dir: Path | None = None,
     data_dir: Path | None = None,
@@ -52,23 +50,20 @@ def configure(  # noqa: PLR0913
 ) -> None:
     """Set global SDK configuration.
 
-    ``api_key`` is an alias for ``token``; ``api_url`` is an alias for
-    ``registry_url``.  When neither ``token`` nor ``api_key`` is provided,
-    the credential chain is used to auto-discover a token.
+    When ``token`` is not provided, the credential chain is used to
+    auto-discover a token.
     """
     from musher._auth import resolve_registry_url, resolve_token  # noqa: PLC0415
 
     global _global_config  # noqa: PLW0603
 
     # Resolve URL and data_dir first so token resolution can use them
-    resolved_url = registry_url or api_url or resolve_registry_url()
+    resolved_url = registry_url or resolve_registry_url()
     resolved_data_dir = data_dir or _default_data_dir()
 
-    # Resolve token: explicit token > explicit api_key > credential chain
+    # Resolve token: explicit token > credential chain
     if token is not _UNSET:
         resolved_token = cast("str | None", token)
-    elif api_key is not _UNSET:
-        resolved_token = cast("str | None", api_key)
     else:
         resolved_token = resolve_token(registry_url=resolved_url, data_dir=resolved_data_dir)
 

src/musher/_http.py

@@ -17,6 +17,16 @@
     from musher._config import MusherConfig
 
 
+def _get_version() -> str:
+    """Read version from package metadata, with fallback."""
+    from importlib.metadata import version  # noqa: PLC0415
+
+    try:
+        return version("musher-sdk")
+    except Exception:  # noqa: BLE001
+        return "0.0.0"
+
+
 class HTTPTransport:
     """Thin wrapper around ``httpx.AsyncClient`` with auth and error mapping."""
 
@@ -26,7 +36,7 @@ def __init__(self, config: MusherConfig) -> None:
 
     def _ensure_client(self) -> httpx.AsyncClient:
         if self._client is None:
-            headers: dict[str, str] = {"User-Agent": "musher-python/0.1.0"}
+            headers: dict[str, str] = {"User-Agent": f"musher-python/{_get_version()}"}
             if self._config.token:
                 headers["Authorization"] = f"Bearer {self._config.token}"