coding-cli-runtime 0.1.0__tar.gz → 0.2.0__tar.gz

{coding_cli_runtime-0.1.0 → coding_cli_runtime-0.2.0}/CHANGELOG.md

@@ -6,38 +6,50 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-04-08
+
+### Added
+- **ProviderContract API** — structured, nested metadata for all four provider CLIs
+  (Claude, Codex, Gemini, Copilot). Composed of `AuthContract`, `PathContract`,
+  `HeadlessContract`, `PromptTransport`, `ApprovalContract`, `SandboxContract`.
+- `get_provider_contract(provider_id)` — returns structured contract for a provider.
+- `build_env_overlay(contract, api_key, base_url)` — builds provider-specific env
+  var overlay from contract metadata.
+- `resolve_config_paths(contract, containerized)` — resolves host and container
+  config directory paths.
+- `render_prompt(transport, prompt)` — resolves prompt delivery into argv args +
+  stdin text based on provider transport mode.
+- `PromptPayload` dataclass for resolved prompt delivery.
+- `__version__` attribute in `coding_cli_runtime`.
+- `CONTRIBUTING.md`, `MANIFEST.in`, `.pre-commit-config.yaml`.
+- PyPI / Python / Build / License badges in `README.md`.
+- `bump-my-version` configuration syncing `pyproject.toml` and `__init__.py`.
+- `ruff`, `mypy` (strict), and `pytest-cov` added to dev dependencies.
+- CI quality gates: ruff check, ruff format, mypy, pytest-cov.
+- README section documenting the new ProviderContract API with examples.
+- 75 new tests for provider contracts, helpers, internal builder, failure
+  classification, codex_cli, schema validation (including nested), reasoning,
+  redaction, json_io, provider_controls, and auth. Package coverage 47% → 62%.
+
 ### Changed
 - Consolidated `shared_cli_runtime` into `coding_cli_runtime`. The package now
   ships a single top-level package; the `shared_cli_runtime` directory is removed.
 - `MANIFEST.in` and docs updated to reference `coding_cli_runtime` paths.
-- Minimum Python version remains `>=3.10`.
 - `run_interactive_session()` observability kwargs (`provider_label`, `job_name`,
   `phase_tag`, `process_label`, `timeout_seconds`) now have sensible defaults so
   external callers don't need to supply internal batch-system labels.
 - Provider model catalogs are now resolved with a three-tier fallback:
   user override file > live CLI discovery > hardcoded fallback.
-  - **Codex**: reads `~/.codex/models_cache.json` (auto-refreshed by the CLI)
-    when present; falls back to the hardcoded catalog on any parse failure.
-  - **All providers**: place a JSON file at
-    `~/.config/coding-cli-runtime/providers/<provider>.json` (or set
-    `CODING_CLI_RUNTIME_CONFIG_DIR`) to override the model list and default
-    model without waiting for a package update.
-
-### Added
-- `__version__` attribute in both `coding_cli_runtime` and `shared_cli_runtime`.
-- `CONTRIBUTING.md`, `MANIFEST.in`, `.pre-commit-config.yaml`.
-- PyPI / Python / Build / License badges in `README.md`.
-- `bump-my-version` configuration syncing `pyproject.toml` and both `__init__.py` files.
-- `ruff`, `mypy` (strict), and `pytest-cov` added to dev dependencies.
-- CI quality gates: ruff check, ruff format, mypy, pytest-cov.
-
-### Changed
+- `auth.py`: `_PROVIDER_ENV_HINTS` now derived from `provider_contracts.py`
+  (single source of truth for auth env var names).
 - `CliRunResult.command` type widened from `tuple[str, ...]` to `Sequence[str]`.
 - Publish workflow path corrected (`shared-cli-runtime` → `coding-cli-runtime`).
 
 ### Fixed
-- mypy strict compliance: return-type annotations, per-module overrides, targeted type-ignore comments.
+- mypy strict compliance: return-type annotations, per-module overrides.
 - ruff lint and format compliance across all source and test files.
+- Copilot BYOK (`COPILOT_PROVIDER_API_KEY`) now discoverable via contract
+  but not reported as "required" in `resolve_auth()` — BYOK is opt-in.
 
 ## [0.1.0] - 2026-04-07
 

{coding_cli_runtime-0.1.0 → coding_cli_runtime-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-cli-runtime
-Version: 0.1.0
+Version: 0.2.0
 Summary: Reusable CLI runtime primitives for provider-backed automation workflows
 Author-email: LLM Eval maintainers <llm-eval-maintainers@users.noreply.github.com>
 License-Expression: MIT
@@ -148,6 +148,38 @@ else:
 Works for all four providers. Recognizes auth failures, rate limits,
 network transients, and other provider-specific error patterns.
 
+### Look up provider contract metadata
+
+```python
+from coding_cli_runtime import get_provider_contract, build_env_overlay, resolve_config_paths, render_prompt
+
+# Get structured metadata for any supported provider
+contract = get_provider_contract("claude")
+print(contract.binary)                        # "claude"
+print(contract.auth.api_key_env_var)          # "CLAUDE_API_KEY"
+print(contract.paths.config_dir)              # "~/.claude"
+print(contract.headless.approval.flag)        # "--dangerously-skip-permissions"
+
+# Build env var overlay for subprocess
+env = build_env_overlay(contract, api_key="sk-...", base_url="https://custom.example.com")
+# {"CLAUDE_API_KEY": "sk-...", "ANTHROPIC_BASE_URL": "https://custom.example.com"}
+
+# Resolve config paths for container mounts
+host_dir, container_dir = resolve_config_paths(contract, containerized=True)
+# ("/home/user/.claude", "/root/.claude")
+
+# Resolve prompt delivery (stdin vs flag vs activation)
+payload = render_prompt(contract.headless.prompt, "Fix the bug")
+# payload.args = ()            (stdin delivery for Claude)
+# payload.stdin_text = "Fix the bug"
+```
+
+`ProviderContract` is structured as nested sub-contracts
+(`AuthContract`, `PathContract`, `HeadlessContract`) so consumers
+can drill into whichever aspect they need. This is reference metadata,
+not a command-construction control plane — consumers keep their own
+command assembly and adopt contract fields selectively.
+
 ## Key types
 
 | Type | Purpose |
@@ -156,6 +188,7 @@ network transients, and other provider-specific error patterns.
 | `CliRunResult` | Result: returncode, stdout/stderr, duration, error code |
 | `ErrorCode` | `none` · `spawn_failed` · `timed_out` · `non_zero_exit` |
 | `ProviderSpec` | Provider catalog entry with models, controls, defaults |
+| `ProviderContract` | Structured provider CLI metadata (auth, paths, headless launch) |
 | `FailureClassification` | Classified error with retryable flag and category |
 
 `run_interactive_session()` manages long-running CLI processes with

{coding_cli_runtime-0.1.0 → coding_cli_runtime-0.2.0}/README.md

@@ -122,6 +122,38 @@ else:
 Works for all four providers. Recognizes auth failures, rate limits,
 network transients, and other provider-specific error patterns.
 
+### Look up provider contract metadata
+
+```python
+from coding_cli_runtime import get_provider_contract, build_env_overlay, resolve_config_paths, render_prompt
+
+# Get structured metadata for any supported provider
+contract = get_provider_contract("claude")
+print(contract.binary)                        # "claude"
+print(contract.auth.api_key_env_var)          # "CLAUDE_API_KEY"
+print(contract.paths.config_dir)              # "~/.claude"
+print(contract.headless.approval.flag)        # "--dangerously-skip-permissions"
+
+# Build env var overlay for subprocess
+env = build_env_overlay(contract, api_key="sk-...", base_url="https://custom.example.com")
+# {"CLAUDE_API_KEY": "sk-...", "ANTHROPIC_BASE_URL": "https://custom.example.com"}
+
+# Resolve config paths for container mounts
+host_dir, container_dir = resolve_config_paths(contract, containerized=True)
+# ("/home/user/.claude", "/root/.claude")
+
+# Resolve prompt delivery (stdin vs flag vs activation)
+payload = render_prompt(contract.headless.prompt, "Fix the bug")
+# payload.args = ()            (stdin delivery for Claude)
+# payload.stdin_text = "Fix the bug"
+```
+
+`ProviderContract` is structured as nested sub-contracts
+(`AuthContract`, `PathContract`, `HeadlessContract`) so consumers
+can drill into whichever aspect they need. This is reference metadata,
+not a command-construction control plane — consumers keep their own
+command assembly and adopt contract fields selectively.
+
 ## Key types
 
 | Type | Purpose |
@@ -130,6 +162,7 @@ network transients, and other provider-specific error patterns.
 | `CliRunResult` | Result: returncode, stdout/stderr, duration, error code |
 | `ErrorCode` | `none` · `spawn_failed` · `timed_out` · `non_zero_exit` |
 | `ProviderSpec` | Provider catalog entry with models, controls, defaults |
+| `ProviderContract` | Structured provider CLI metadata (auth, paths, headless launch) |
 | `FailureClassification` | Classified error with retryable flag and category |
 
 `run_interactive_session()` manages long-running CLI processes with

{coding_cli_runtime-0.1.0 → coding_cli_runtime-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "coding-cli-runtime"
-version = "0.1.0"
+version = "0.2.0"
 description = "Reusable CLI runtime primitives for provider-backed automation workflows"
 readme = {file = "README.md", content-type = "text/markdown"}
 license = "MIT"
@@ -94,7 +94,7 @@ disallow_untyped_defs = false
 warn_return_any = false
 
 [tool.bumpversion]
-current_version = "0.1.0"
+current_version = "0.2.0"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 commit = true

{coding_cli_runtime-0.1.0 → coding_cli_runtime-0.2.0}/src/coding_cli_runtime/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 from .auth import AuthResolution, resolve_auth
 from .codex_cli import CodexExecSpec, build_codex_exec_spec
@@ -15,6 +15,20 @@ from .contracts import (
     ErrorCode,
 )
 from .failure_classification import FailureClassification, classify_provider_failure
+from .provider_contracts import (
+    ApprovalContract,
+    AuthContract,
+    HeadlessContract,
+    PathContract,
+    PromptPayload,
+    PromptTransport,
+    ProviderContract,
+    SandboxContract,
+    build_env_overlay,
+    get_provider_contract,
+    render_prompt,
+    resolve_config_paths,
+)
 from .provider_controls import build_model_id, resolve_provider_model_controls
 from .provider_specs import (
     ChoiceSpec,
@@ -56,6 +70,8 @@ from .session_logs import (
 from .subprocess_runner import run_cli_command, run_cli_command_sync
 
 __all__ = [
+    "ApprovalContract",
+    "AuthContract",
     "AuthMode",
     "AuthResolution",
     "CliRunRequest",
@@ -67,14 +83,21 @@ __all__ = [
     "ControlSpec",
     "ErrorCode",
     "FailureClassification",
+    "HeadlessContract",
     "ModelSpec",
+    "PathContract",
+    "PromptPayload",
+    "PromptTransport",
+    "ProviderContract",
     "ProviderSpec",
+    "SandboxContract",
     "SchemaValidationError",
     "InteractiveCliRunResult",
     "SessionProgressEvent",
     "SessionRetryDecision",
     "SessionExecutionTimeoutError",
     "TranscriptMirrorStrategy",
+    "build_env_overlay",
     "get_claude_default_model",
     "get_claude_effort_levels",
     "get_claude_model_candidates",
@@ -85,14 +108,17 @@ __all__ = [
     "get_copilot_model_catalog",
     "get_gemini_default_model",
     "get_gemini_model_options",
+    "get_provider_contract",
     "get_provider_spec",
     "list_provider_specs",
     "build_model_id",
     "build_codex_exec_spec",
     "classify_provider_failure",
     "load_schema",
+    "render_prompt",
     "resolve_auth",
     "resolve_claude_reasoning_policy",
+    "resolve_config_paths",
     "resolve_provider_model_controls",
     "redact_text",
     "claude_project_key",

{coding_cli_runtime-0.1.0 → coding_cli_runtime-0.2.0}/src/coding_cli_runtime/auth.py

@@ -6,6 +6,7 @@ import os
 from dataclasses import dataclass
 
 from .contracts import AuthMode
+from .provider_contracts import _CONTRACTS
 
 
 @dataclass(frozen=True)
@@ -18,15 +19,30 @@ class AuthResolution:
     hint: str
 
 
-_PROVIDER_ENV_HINTS: dict[str, tuple[tuple[str, ...], str]] = {
-    "claude": (("CLAUDE_API_KEY",), "Use `claude login` or set CLAUDE_API_KEY."),
-    "copilot": (
-        tuple(),
-        "Use `copilot auth login` (CLI login is the default authentication mode).",
-    ),
-    "codex": (("OPENAI_API_KEY",), "Use Codex login flow or set OPENAI_API_KEY."),
-    "gemini": (("GEMINI_API_KEY",), "Use `gemini auth login` or set GEMINI_API_KEY."),
-}
+def _build_provider_env_hints() -> dict[str, tuple[tuple[str, ...], str]]:
+    """Derive auth env hints from the authoritative provider contracts.
+
+    Only ``api_key_env_var`` (primary auth) populates ``required_env``.
+    ``byok_api_key_env_var`` is an opt-in override and should not appear
+    as "required" or "missing" — callers discover BYOK via the contract.
+    """
+    hints: dict[str, tuple[tuple[str, ...], str]] = {}
+    for provider_id, contract in _CONTRACTS.items():
+        auth = contract.auth
+        env_vars: list[str] = []
+        if auth.api_key_env_var:
+            env_vars.append(auth.api_key_env_var)
+        if env_vars:
+            hint = f"Use CLI login or set {env_vars[0]}."
+        elif auth.byok_api_key_env_var:
+            hint = f"Use CLI login. BYOK available via {auth.byok_api_key_env_var}."
+        else:
+            hint = "Use CLI login (no env-based auth path available)."
+        hints[provider_id] = (tuple(env_vars), hint)
+    return hints
+
+
+_PROVIDER_ENV_HINTS = _build_provider_env_hints()
 
 
 def resolve_auth(provider: str, env: dict[str, str] | None = None) -> AuthResolution: