claude-select 0.1.0__py3-none-any.whl

claude_select/__init__.py

@@ -0,0 +1,5 @@
+"""Public package interface for claude-select."""
+
+from claude_select.manager import ProfileManager, build_sdk_env
+
+__all__ = ["ProfileManager", "build_sdk_env"]

claude_select/__main__.py

@@ -0,0 +1,8 @@
+"""Module entry point for `python -m claude_select`."""
+
+from __future__ import annotations
+
+from claude_select.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

claude_select/cli.py

@@ -0,0 +1,115 @@
+"""Command line interface for claude-select."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from claude_select.exceptions import ClaudeSwitchError
+from claude_select.manager import ProfileManager
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Create the CLI parser."""
+    parser = argparse.ArgumentParser(description="Manage multiple Claude auth profiles.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    capture = subparsers.add_parser("capture", help="Capture the current Claude CLI login state.")
+    capture.add_argument("profile")
+
+    sync = subparsers.add_parser(
+        "sync",
+        help="Sync a stored profile from the current Claude CLI login state.",
+    )
+    sync.add_argument("profile", nargs="?")
+
+    list_cmd = subparsers.add_parser("list", help="List stored profiles.")
+    list_cmd.add_argument("--json", action="store_true", dest="as_json")
+
+    current = subparsers.add_parser("current", help="Show current CLI and default SDK profiles.")
+    current.add_argument("--json", action="store_true", dest="as_json")
+
+    use = subparsers.add_parser("use", help="Switch Claude CLI live state to a profile.")
+    use.add_argument("profile")
+
+    remove = subparsers.add_parser("remove", help="Remove a stored profile.")
+    remove.add_argument("profile")
+
+    set_default = subparsers.add_parser("set-default-sdk", help="Set the default SDK profile.")
+    set_default.add_argument("profile")
+
+    inspect = subparsers.add_parser("inspect", help="Inspect one stored profile.")
+    inspect.add_argument("profile")
+    inspect.add_argument("--json", action="store_true", dest="as_json")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the CLI."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    manager = ProfileManager()
+
+    try:
+        if args.command == "capture":
+            result = manager.capture_cli_profile(args.profile)
+            print(f"Captured profile '{result['id']}' for {result['email']}.")
+            return 0
+        if args.command == "sync":
+            result = manager.sync_cli_profile(args.profile)
+            print(f"Synchronized profile '{result['id']}'.")
+            return 0
+        if args.command == "list":
+            profiles = manager.list_profiles()
+            if args.as_json:
+                print(json.dumps(profiles, indent=2, sort_keys=True))
+            else:
+                for profile in profiles:
+                    print(
+                        f"{profile['id']}\t{profile['email']}\t{profile['auth_state']}\t"
+                        f"{profile['organization_name'] or '-'}"
+                    )
+            return 0
+        if args.command == "current":
+            payload = {
+                "current_cli_profile": manager.get_current_cli_profile(),
+                "default_sdk_profile": manager.get_default_sdk_profile(),
+            }
+            if args.as_json:
+                print(json.dumps(payload, indent=2, sort_keys=True))
+            else:
+                print(f"current_cli_profile={payload['current_cli_profile']}")
+                print(f"default_sdk_profile={payload['default_sdk_profile']}")
+            return 0
+        if args.command == "use":
+            result = manager.switch_cli(args.profile)
+            print(f"Switched CLI to profile '{result['id']}'.")
+            if result.get("refresh_error"):
+                print(
+                    f"Profile requires reauthentication: {result['refresh_error']}",
+                    file=sys.stderr,
+                )
+            return 0
+        if args.command == "remove":
+            manager.remove_profile(args.profile)
+            print(f"Removed profile '{args.profile}'.")
+            return 0
+        if args.command == "set-default-sdk":
+            manager.set_default_sdk_profile(args.profile)
+            print(f"Default SDK profile set to '{args.profile}'.")
+            return 0
+        if args.command == "inspect":
+            profile = manager.inspect_profile(args.profile)
+            if args.as_json:
+                print(json.dumps(profile, indent=2, sort_keys=True))
+            else:
+                print(json.dumps(profile, indent=2, sort_keys=True))
+            return 0
+    except ClaudeSwitchError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+    parser.error(f"Unhandled command: {args.command}")
+    return 2

claude_select/exceptions.py

@@ -0,0 +1,29 @@
+"""Project-specific exceptions."""
+
+
+class ClaudeSwitchError(Exception):
+    """Base error for the package."""
+
+
+class ConfigError(ClaudeSwitchError):
+    """Raised when local Claude configuration is invalid or missing."""
+
+
+class ProfileNotFoundError(ClaudeSwitchError):
+    """Raised when a named profile does not exist."""
+
+
+class ProfileValidationError(ClaudeSwitchError):
+    """Raised when profile input is invalid."""
+
+
+class ProfileReauthRequired(ClaudeSwitchError):
+    """Raised when a profile requires the user to login again."""
+
+
+class OAuthRefreshError(ClaudeSwitchError):
+    """Raised when an OAuth token refresh fails."""
+
+
+class LockTimeoutError(ClaudeSwitchError):
+    """Raised when a store lock cannot be acquired."""

claude_select/live_state.py

@@ -0,0 +1,176 @@
+"""Claude live state backends."""
+
+from __future__ import annotations
+
+import getpass
+import json
+import os
+import platform
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any, Protocol
+
+from claude_select.exceptions import ConfigError
+from claude_select.models import LiveState
+from claude_select.paths import get_credentials_path, get_global_config_path
+
+
+class CredentialStore(Protocol):
+    """Read and write Claude credentials."""
+
+    def read(self) -> dict[str, Any]:
+        """Read the current credentials payload."""
+
+    def write(self, credentials: dict[str, Any]) -> None:
+        """Write the current credentials payload."""
+
+    def backup(self, destination_dir: Path) -> None:
+        """Back up the credential store if supported."""
+
+
+class FileCredentialStore:
+    """File-backed Claude credential storage."""
+
+    def __init__(self, path: Path):
+        self.path = path
+
+    def read(self) -> dict[str, Any]:
+        if not self.path.exists():
+            raise ConfigError(f"Claude credentials file not found: {self.path}")
+        with self.path.open("r", encoding="utf-8") as handle:
+            return json.load(handle)
+
+    def write(self, credentials: dict[str, Any]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile(
+            "w",
+            encoding="utf-8",
+            dir=self.path.parent,
+            delete=False,
+        ) as handle:
+            json.dump(credentials, handle, indent=2, sort_keys=True)
+            handle.write("\n")
+            temp_name = handle.name
+        os.replace(temp_name, self.path)
+        if os.name != "nt":
+            os.chmod(self.path, 0o600)
+
+    def backup(self, destination_dir: Path) -> None:
+        if not self.path.exists():
+            return
+        destination_dir.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(self.path, destination_dir / self.path.name)
+
+
+class MacOSKeychainCredentialStore:
+    """macOS keychain-backed Claude credential storage."""
+
+    def __init__(
+        self,
+        service_name: str = "Claude Code-credentials",
+        account_name: str | None = None,
+    ):
+        self.service_name = service_name
+        self.account_name = account_name or getpass.getuser()
+
+    def read(self) -> dict[str, Any]:
+        try:
+            result = subprocess.run(
+                ["security", "find-generic-password", "-s", self.service_name, "-w"],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+        except subprocess.CalledProcessError as exc:
+            raise ConfigError("Claude credentials not found in macOS Keychain.") from exc
+        return json.loads(result.stdout)
+
+    def write(self, credentials: dict[str, Any]) -> None:
+        result = subprocess.run(
+            [
+                "security",
+                "add-generic-password",
+                "-U",
+                "-s",
+                self.service_name,
+                "-a",
+                self.account_name,
+                "-w",
+                json.dumps(credentials, separators=(",", ":")),
+            ],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0:
+            raise ConfigError(
+                f"Failed to write macOS Keychain credentials: {result.stderr.strip()}"
+            )
+
+    def backup(self, destination_dir: Path) -> None:
+        destination_dir.mkdir(parents=True, exist_ok=True)
+        backup_file = destination_dir / "keychain-credentials.json"
+        backup_file.write_text(
+            json.dumps(self.read(), indent=2, sort_keys=True),
+            encoding="utf-8",
+        )
+
+
+def create_default_credential_store(env: dict[str, str] | None = None) -> CredentialStore:
+    """Create the default credential store for the current platform."""
+    if platform.system() == "Darwin":
+        return MacOSKeychainCredentialStore()
+    return FileCredentialStore(get_credentials_path(env))
+
+
+class ClaudeLiveStateBackend:
+    """Reads and writes Claude's live runtime auth state."""
+
+    def __init__(
+        self,
+        config_path: Path | None = None,
+        credential_store: CredentialStore | None = None,
+        backup_dir: Path | None = None,
+        env: dict[str, str] | None = None,
+    ):
+        self.config_path = config_path or get_global_config_path(env)
+        self.credential_store = credential_store or create_default_credential_store(env)
+        self.backup_dir = backup_dir or (self.config_path.parent / ".claude-select-backups")
+
+    def read(self) -> LiveState:
+        """Read Claude's current live config and credentials."""
+        if not self.config_path.exists():
+            raise ConfigError(f"Claude config file not found: {self.config_path}")
+        with self.config_path.open("r", encoding="utf-8") as handle:
+            config = json.load(handle)
+        credentials = self.credential_store.read()
+        oauth_account = config.get("oauthAccount")
+        if not isinstance(oauth_account, dict) or not oauth_account.get("emailAddress"):
+            raise ConfigError("Claude config does not contain a valid oauthAccount.")
+        if not isinstance(credentials.get("claudeAiOauth"), dict):
+            raise ConfigError("Claude credentials do not contain a valid claudeAiOauth payload.")
+        return LiveState(config=config, credentials=credentials)
+
+    def write(self, live_state: LiveState) -> None:
+        """Write Claude's current live config and credentials."""
+        self.backup()
+        self.config_path.parent.mkdir(parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile(
+            "w",
+            encoding="utf-8",
+            dir=self.config_path.parent,
+            delete=False,
+        ) as handle:
+            json.dump(live_state.config, handle, indent=2, sort_keys=True)
+            handle.write("\n")
+            temp_name = handle.name
+        os.replace(temp_name, self.config_path)
+        self.credential_store.write(live_state.credentials)
+
+    def backup(self) -> None:
+        """Create backups for the live config and credentials."""
+        self.backup_dir.mkdir(parents=True, exist_ok=True)
+        if self.config_path.exists():
+            shutil.copy2(self.config_path, self.backup_dir / self.config_path.name)
+        self.credential_store.backup(self.backup_dir)

claude_select/locking.py

@@ -0,0 +1,65 @@
+"""Cross-platform file locking."""
+
+from __future__ import annotations
+
+import sys
+import time
+from pathlib import Path
+from typing import IO
+
+from claude_select.exceptions import LockTimeoutError
+
+if sys.platform == "win32":
+    import msvcrt
+else:
+    import fcntl
+
+
+class FileLock:
+    """A simple cross-process file lock."""
+
+    def __init__(self, path: Path):
+        self.path = path
+        self._handle: IO[str] | None = None
+        self._locked = False
+
+    def acquire(self, timeout: float = 10.0) -> None:
+        """Acquire an exclusive lock or raise on timeout."""
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._handle = self.path.open("a+", encoding="utf-8")
+        deadline = time.monotonic() + timeout
+        while True:
+            try:
+                if sys.platform == "win32":
+                    msvcrt.locking(self._handle.fileno(), msvcrt.LK_NBLCK, 1)
+                else:
+                    fcntl.flock(self._handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+                self._locked = True
+                return
+            except OSError as exc:
+                if time.monotonic() >= deadline:
+                    self.release()
+                    raise LockTimeoutError(f"Timed out waiting for lock: {self.path}") from exc
+                time.sleep(0.05)
+
+    def release(self) -> None:
+        """Release the lock if held."""
+        if not self._handle:
+            return
+        try:
+            if self._locked:
+                if sys.platform == "win32":
+                    msvcrt.locking(self._handle.fileno(), msvcrt.LK_UNLCK, 1)
+                else:
+                    fcntl.flock(self._handle.fileno(), fcntl.LOCK_UN)
+        finally:
+            self._handle.close()
+            self._handle = None
+            self._locked = False
+
+    def __enter__(self) -> FileLock:
+        self.acquire()
+        return self
+
+    def __exit__(self, *_args: object) -> None:
+        self.release()

claude_select/manager.py

@@ -0,0 +1,260 @@
+"""ProfileManager implementation."""
+
+from __future__ import annotations
+
+import copy
+import os
+import re
+from dataclasses import asdict
+from typing import Any
+
+from claude_select.exceptions import (
+    ConfigError,
+    ProfileNotFoundError,
+    ProfileReauthRequired,
+    ProfileValidationError,
+)
+from claude_select.live_state import ClaudeLiveStateBackend
+from claude_select.models import (
+    AUTH_STATE_REFRESHABLE,
+    PROFILE_KIND_OAUTH,
+    LiveState,
+    ProfileMetadata,
+    SecretPayload,
+    utc_now_iso,
+)
+from claude_select.oauth import (
+    classify_auth_state,
+    mark_refresh_failure,
+    mark_refresh_success,
+    refresh_secret_payload,
+    update_profile_auth_metadata,
+)
+from claude_select.store import FileProfileStore
+
+PROFILE_NAME_RE = re.compile(r"^[A-Za-z0-9._-]+$")
+CONFLICTING_AUTH_ENV_VARS = {
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN",
+    "CLAUDE_CODE_USE_BEDROCK",
+    "CLAUDE_CODE_USE_VERTEX",
+    "CLAUDE_CODE_USE_FOUNDRY",
+    "CLAUDE_CODE_OAUTH_TOKEN",
+    "CLAUDE_CODE_OAUTH_REFRESH_TOKEN",
+    "CLAUDE_CODE_OAUTH_SCOPES",
+}
+
+
+class ProfileManager:
+    """Main entry point for profile management."""
+
+    def __init__(
+        self,
+        store: FileProfileStore | None = None,
+        live_state_backend: ClaudeLiveStateBackend | None = None,
+        refresh_request=None,
+    ):
+        self.store = store or FileProfileStore()
+        self.live_state_backend = live_state_backend or ClaudeLiveStateBackend()
+        self.refresh_request = refresh_request
+
+    def list_profiles(self) -> list[dict[str, Any]]:
+        """Return profile metadata dictionaries."""
+        profiles = []
+        for profile in self.store.list_profiles():
+            secret = self.store.get_secret(profile.secret_ref)
+            update_profile_auth_metadata(profile, secret)
+            self.store.update_profile(profile)
+            profiles.append(asdict(profile))
+        return profiles
+
+    def capture_cli_profile(self, name: str) -> dict[str, Any]:
+        """Capture the current Claude CLI live state into a named profile."""
+        profile_name = self._validate_profile_name(name)
+        live_state = self.live_state_backend.read()
+        profile, secret = self._build_profile_from_live_state(profile_name, live_state)
+        self.store.upsert_profile(profile, secret)
+        self.store.set_current_cli_profile(profile_name)
+        if self.get_default_sdk_profile() is None:
+            self.store.set_default_sdk_profile(profile_name)
+        return asdict(profile)
+
+    def sync_cli_profile(self, name: str | None = None) -> dict[str, Any]:
+        """Update a named profile using the current Claude CLI live state."""
+        state = self.store.load_state()
+        profile_name = name or state.current_cli_profile
+        if not profile_name:
+            raise ProfileValidationError(
+                "No profile name provided and no current CLI profile is set."
+            )
+        if profile_name not in state.profiles:
+            raise ProfileNotFoundError(f"Profile '{profile_name}' was not found.")
+        live_state = self.live_state_backend.read()
+        profile, secret = self._build_profile_from_live_state(profile_name, live_state)
+        self.store.upsert_profile(profile, secret)
+        return asdict(profile)
+
+    def switch_cli(self, name: str) -> dict[str, Any]:
+        """Switch Claude's live state to a named profile."""
+        profile, secret = self._load_profile(name)
+        profile, secret, refresh_error = self._refresh_profile_if_needed(
+            profile,
+            secret,
+            allow_failure=True,
+        )
+        try:
+            current_live_state = self.live_state_backend.read()
+            next_config = copy.deepcopy(current_live_state.config)
+        except ConfigError:
+            next_config = {}
+        next_config["oauthAccount"] = copy.deepcopy(secret.oauth_account)
+        live_state = LiveState(
+            config=next_config,
+            credentials=copy.deepcopy(secret.credentials),
+        )
+        self.live_state_backend.write(live_state)
+        profile.updated_at = utc_now_iso()
+        self.store.upsert_profile(profile, secret)
+        self.store.set_current_cli_profile(profile.id)
+        result = asdict(profile)
+        result["refresh_error"] = refresh_error
+        return result
+
+    def set_default_sdk_profile(self, name: str) -> None:
+        """Set the default profile for SDK env generation."""
+        self._load_profile(name)
+        self.store.set_default_sdk_profile(name)
+
+    def get_default_sdk_profile(self) -> str | None:
+        """Return the default SDK profile if configured."""
+        return self.store.load_state().default_sdk_profile
+
+    def get_current_cli_profile(self) -> str | None:
+        """Return the currently selected CLI profile."""
+        return self.store.load_state().current_cli_profile
+
+    def inspect_profile(self, name: str) -> dict[str, Any]:
+        """Return detailed metadata for one profile."""
+        profile, secret = self._load_profile(name)
+        update_profile_auth_metadata(profile, secret)
+        self.store.update_profile(profile)
+        details = asdict(profile)
+        details["scopes"] = self._get_scopes(secret)
+        return details
+
+    def remove_profile(self, name: str) -> None:
+        """Remove a stored profile."""
+        self._load_profile(name)
+        self.store.remove_profile(name)
+
+    def build_sdk_env(
+        self,
+        name: str | None = None,
+        base_env: dict[str, str] | None = None,
+    ) -> dict[str, str]:
+        """Build a clean environment mapping for the requested profile."""
+        profile_name = name or self.get_default_sdk_profile()
+        if not profile_name:
+            raise ProfileValidationError(
+                "No profile specified and no default SDK profile is configured."
+            )
+        profile, secret = self._load_profile(profile_name)
+        profile, secret, _refresh_error = self._refresh_profile_if_needed(
+            profile,
+            secret,
+            allow_failure=False,
+        )
+        env = dict(base_env if base_env is not None else os.environ)
+        for key in CONFLICTING_AUTH_ENV_VARS:
+            env.pop(key, None)
+        oauth = secret.credentials["claudeAiOauth"]
+        env["CLAUDE_CODE_OAUTH_TOKEN"] = str(oauth["accessToken"])
+        refresh_token = oauth.get("refreshToken")
+        if refresh_token:
+            env["CLAUDE_CODE_OAUTH_REFRESH_TOKEN"] = str(refresh_token)
+        scopes = oauth.get("scopes")
+        if isinstance(scopes, list) and scopes:
+            env["CLAUDE_CODE_OAUTH_SCOPES"] = " ".join(str(scope) for scope in scopes)
+        return env
+
+    def _load_profile(self, name: str) -> tuple[ProfileMetadata, SecretPayload]:
+        state = self.store.load_state()
+        if name not in state.profiles:
+            raise ProfileNotFoundError(f"Profile '{name}' was not found.")
+        return state.profiles[name], self.store.get_secret(state.profiles[name].secret_ref)
+
+    def _validate_profile_name(self, name: str) -> str:
+        normalized = name.strip()
+        if not normalized:
+            raise ProfileValidationError("Profile name cannot be empty.")
+        if not PROFILE_NAME_RE.match(normalized):
+            raise ProfileValidationError(
+                "Profile name must only contain letters, numbers, dot, underscore, or dash."
+            )
+        return normalized
+
+    def _build_profile_from_live_state(
+        self,
+        name: str,
+        live_state: LiveState,
+    ) -> tuple[ProfileMetadata, SecretPayload]:
+        oauth_account = live_state.config.get("oauthAccount")
+        if not isinstance(oauth_account, dict):
+            raise ConfigError("Claude config does not contain oauthAccount.")
+        email = oauth_account.get("emailAddress")
+        if not email:
+            raise ConfigError("Claude config oauthAccount is missing emailAddress.")
+        secret = SecretPayload(
+            oauth_account=copy.deepcopy(oauth_account),
+            credentials=copy.deepcopy(live_state.credentials),
+        )
+        profile = ProfileMetadata(
+            id=name,
+            kind=PROFILE_KIND_OAUTH,
+            label=name,
+            email=str(email),
+            organization_id=str(oauth_account.get("organizationUuid", "") or ""),
+            organization_name=str(oauth_account.get("organizationName", "") or ""),
+            account_uuid=str(oauth_account.get("accountUuid", "") or ""),
+            secret_ref=name,
+        )
+        update_profile_auth_metadata(profile, secret)
+        return profile, secret
+
+    def _refresh_profile_if_needed(
+        self,
+        profile: ProfileMetadata,
+        secret: SecretPayload,
+        *,
+        allow_failure: bool,
+    ) -> tuple[ProfileMetadata, SecretPayload, str | None]:
+        auth_state, _expires_at = classify_auth_state(secret)
+        if auth_state != AUTH_STATE_REFRESHABLE:
+            update_profile_auth_metadata(profile, secret)
+            self.store.update_profile(profile)
+            return profile, secret, None
+        try:
+            refreshed_secret = refresh_secret_payload(secret, request_refresh=self.refresh_request)
+        except Exception as exc:
+            error = str(exc)
+            mark_refresh_failure(profile, error)
+            self.store.upsert_profile(profile, secret)
+            if allow_failure:
+                return profile, secret, error
+            raise ProfileReauthRequired(
+                f"Profile '{profile.id}' requires reauthentication: {error}"
+            ) from exc
+        mark_refresh_success(profile, refreshed_secret)
+        self.store.upsert_profile(profile, refreshed_secret)
+        return profile, refreshed_secret, None
+
+    @staticmethod
+    def _get_scopes(secret: SecretPayload) -> list[str]:
+        oauth = secret.credentials.get("claudeAiOauth", {})
+        scopes = oauth.get("scopes", [])
+        return [str(scope) for scope in scopes] if isinstance(scopes, list) else []
+
+
+def build_sdk_env(profile: str, base_env: dict[str, str] | None = None) -> dict[str, str]:
+    """Convenience wrapper around ProfileManager.build_sdk_env."""
+    return ProfileManager().build_sdk_env(profile, base_env=base_env)