refactorai-cli 0.2.29__tar.gz → 0.3.0__tar.gz

{refactorai_cli-0.2.29 → refactorai_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: refactorai-cli
-Version: 0.2.29
+Version: 0.3.0
 Summary: Local-first CLI for the refactor platform
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -8,6 +8,7 @@ Requires-Dist: typer>=0.12.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: rich>=13.7.0
 Requires-Dist: PyYAML>=6.0.1
+Requires-Dist: refactorai-core>=3.0.0
 
 # refactorai-cli
 
@@ -53,28 +54,34 @@ python -m twine upload ./refactorai-cli/dist/*
 ## Install test (local)
 
 ```bash
-python -m pip install ./refactorai-cli/dist/refactorai_cli-0.2.29-py3-none-any.whl
+python -m pip install ./refactorai-cli/dist/refactorai_cli-0.3.0-py3-none-any.whl
 refactor --version
 ```
 
 ## Cloud BYOK setup (bring your own provider key)
 
 Run cloud inference with your own provider credentials (no local runtime
-required). The secret is read from your environment and encrypted server-side;
-it is never written to disk or printed.
+required). Preferred path is env-key in project config (`provider_key:
+${ENV_VAR}`). Platform-stored credentials (`credential_ref`) are optional
+fallback.
 
 ```bash
 # 1. Authenticate (developer key with the run:byok entitlement).
 refactor login
 
-# 2. Register your provider secret from an env var.
+# 2A. Preferred: set BYOK directly from project env in refactor.config:
+#
+# mode: cloud_byok
+# provider: openai
+# model_id: gpt-4.1-mini
+# provider_key: ${OPENAI_API_KEY}
+#
+# 2B. Optional fallback: register a platform-stored credential from env.
 export OPENAI_API_KEY=sk-...
 refactor cloud credentials set --provider openai --from-env OPENAI_API_KEY --label "my key"
 # -> prints a credential_ref, e.g. cred_01J...
 
-# 3. Point your project at cloud_byok in refactor.config:
-#    mode: cloud_byok
-#    provider: openai
+# 3. If you use platform-stored fallback, set credential_ref in config:
 #    credential_ref: cred_01J...
 
 # 4. Verify readiness, then run.

{refactorai_cli-0.2.29 → refactorai_cli-0.3.0}/README.md

@@ -42,28 +42,34 @@ python -m twine upload ./refactorai-cli/dist/*
 ## Install test (local)
 
 ```bash
-python -m pip install ./refactorai-cli/dist/refactorai_cli-0.2.29-py3-none-any.whl
+python -m pip install ./refactorai-cli/dist/refactorai_cli-0.3.0-py3-none-any.whl
 refactor --version
 ```
 
 ## Cloud BYOK setup (bring your own provider key)
 
 Run cloud inference with your own provider credentials (no local runtime
-required). The secret is read from your environment and encrypted server-side;
-it is never written to disk or printed.
+required). Preferred path is env-key in project config (`provider_key:
+${ENV_VAR}`). Platform-stored credentials (`credential_ref`) are optional
+fallback.
 
 ```bash
 # 1. Authenticate (developer key with the run:byok entitlement).
 refactor login
 
-# 2. Register your provider secret from an env var.
+# 2A. Preferred: set BYOK directly from project env in refactor.config:
+#
+# mode: cloud_byok
+# provider: openai
+# model_id: gpt-4.1-mini
+# provider_key: ${OPENAI_API_KEY}
+#
+# 2B. Optional fallback: register a platform-stored credential from env.
 export OPENAI_API_KEY=sk-...
 refactor cloud credentials set --provider openai --from-env OPENAI_API_KEY --label "my key"
 # -> prints a credential_ref, e.g. cred_01J...
 
-# 3. Point your project at cloud_byok in refactor.config:
-#    mode: cloud_byok
-#    provider: openai
+# 3. If you use platform-stored fallback, set credential_ref in config:
 #    credential_ref: cred_01J...
 
 # 4. Verify readiness, then run.

{refactorai_cli-0.2.29 → refactorai_cli-0.3.0}/pyproject.toml

@@ -1,14 +1,18 @@
 [project]
 name = "refactorai-cli"
-version = "0.2.29"
+version = "0.3.0"
 description = "Local-first CLI for the refactor platform"
 readme = "README.md"
 requires-python = ">=3.11"
+# R21 core split: the CLI depends on the PUBLIC client core only. The proprietary
+# engine (refactor-core-engine) is never installed on a developer's machine via
+# pip; local mode runs the engine from the downloaded runtime binary instead.
 dependencies = [
   "typer>=0.12.0",
   "httpx>=0.27.0",
   "rich>=13.7.0",
   "PyYAML>=6.0.1",
+  "refactorai-core>=3.0.0",
 ]
 
 [project.scripts]

{refactorai_cli-0.2.29 → refactorai_cli-0.3.0}/refactorai_cli/__init__.py

@@ -5,4 +5,4 @@ the shared `refactor_core` pipeline from a project folder while staying
 authenticated to the hosted platform via a developer key.
 """
 
-__version__ = "0.2.29"
+__version__ = "0.3.0"

{refactorai_cli-0.2.29 → refactorai_cli-0.3.0}/refactorai_cli/commands/cloud_cmds.py

@@ -114,7 +114,8 @@ def credentials_set(
         f"[green]Credential registered[/green] for provider [bold]{data.get('provider', provider)}[/bold].\n"
         f"  credential_ref: [bold]{data.get('credential_ref', '?')}[/bold]\n"
         f"  masked_secret: {data.get('masked_secret', '****')}\n"
-        "Add the credential_ref to refactor.config under `credential_ref:` to use cloud_byok."
+        "Use this as an optional cloud_byok fallback (`credential_ref:`). "
+        "Preferred path is env-key in project config (`provider_key: ${ENV_VAR}`)."
     )
 
 

{refactorai_cli-0.2.29 → refactorai_cli-0.3.0}/refactorai_cli/commands/run_cmds.py

@@ -52,9 +52,6 @@ from refactor_core.apply import (
 )
 from refactor_core.budgeting import compute_budget
 from refactor_core.capabilities import resolve_capabilities
-from refactor_core.execution import resolve_mode, run_with_mode
-from refactor_core.execution.rr_executor import run_refactor_requests
-from refactor_core.execution.structural_ops import structural_compatibility_matrix
 from refactor_core.gate import evaluate_gate
 from refactor_core.refactor_requests import (
     DEFERRED,
@@ -70,30 +67,10 @@ from refactor_core.refactor_requests import (
 from refactor_core.refactor_ops import remediation_hint
 from refactor_core.indexing import index_target
 from refactor_core.models import Finding, GeneratedTest, PatchGroup, RunArtifact
-from refactor_core.pipeline import build_refactor_prompt, build_review_prompt
-from refactor_core.providers import get_provider, resolve_provider_name, supported_providers
 from refactor_core.rules import annotate_documents_with_rules, filter_documents_by_rules
 from refactor_core.security import merge_refactor_findings, suppress_findings_for_rr
 from refactor_core.security.semgrep_runner import EMBEDDED_SEMGREP_SENTINEL
 from refactor_core.security.suppression import SecuritySuppression
-from refactor_core.sandbox_runtime import (
-    DEFAULT_IMAGE as SANDBOX_DEFAULT_IMAGE,
-    DEFAULT_SHELL as SANDBOX_DEFAULT_SHELL,
-    attach_shell as attach_sandbox_shell,
-    command_exists_in_container,
-    command_exists_in_sandbox,
-    detect_installer_in_container,
-    detect_installer_in_sandbox,
-    ensure_sandbox,
-    exec_in_container,
-    exec_in_container_stream,
-    exec_in_sandbox,
-    exec_in_sandbox_stream,
-    remove_sandbox_container,
-    sandbox_name,
-    resolve_runtime,
-    stop_sandbox,
-)
 from refactor_core.store import (
     append_sandbox_install_history,
     clear_sandbox_state,
@@ -125,6 +102,27 @@ from refactorai_cli.setup_flow import (
 
 console = Console()
 
+# Local mirrors of engine-only sandbox defaults (R21 core split). These are used
+# as Typer option defaults, which are evaluated at import time, so they cannot be
+# lazy-imported from the engine-only ``refactor_core.enginecore.sandbox_runtime`` module.
+# They mirror ``sandbox_runtime.DEFAULT_IMAGE`` / ``DEFAULT_SHELL`` and are only
+# meaningful in local mode (where the engine is present via the runtime binary).
+SANDBOX_DEFAULT_IMAGE = "docker.io/library/alpine:3.20"
+SANDBOX_DEFAULT_SHELL = "/bin/sh"
+
+
+def _sandbox_runtime():
+    """Lazily import the engine-only sandbox runtime module (local mode only).
+
+    Cloud modes never touch the sandbox; this import is therefore reached only on
+    the local execution path, where the engine is present (inside the runtime
+    binary). A client-only install that never runs local commands never imports
+    it, keeping engine code off the developer's disk (R21 core split).
+    """
+    from refactor_core.enginecore import sandbox_runtime as _sr
+
+    return _sr
+
 
 def _read_stage_output(stage_id: str) -> dict:
     path = stage_output_path(stage_id)
@@ -167,7 +165,14 @@ def _default_config_for_init() -> tuple[str, str]:
         )
         return config_text, "local_server"
     if backend == BACKEND_BYOK:
-        return DEFAULT_CONFIG, "byok"
+        config_text = DEFAULT_CONFIG.replace("mode: local", "mode: cloud_byok", 1)
+        config_text = config_text.replace("provider: heuristic", "provider: openai", 1)
+        config_text = config_text.replace(
+            "model_id: heuristic-local-v1",
+            "model_id: gpt-4.1-mini\nprovider_key: ${OPENAI_API_KEY}\n# credential_ref: cred_01J...",
+            1,
+        )
+        return config_text, "byok"
     return DEFAULT_CONFIG, "default"
 
 _SEVERITY_STYLE = {
@@ -631,14 +636,14 @@ def _cloud_inference(
     documents, _scope_meta = filter_documents_by_rules(documents, project_root=Path(project_root))
     rule_meta = annotate_documents_with_rules(documents, project_root=Path(project_root))
 
-    if stage == "review":
-        system_prompt, user_prompt = build_review_prompt(constitution, documents, max_alerts)
-    else:
-        # Feed prior review findings into the refactor prompt so cloud `code`
-        # generates patches targeting the same issues (parity with local RR).
-        system_prompt, user_prompt = build_refactor_prompt(
-            constitution, documents, list(findings or []), max_alerts
-        )
+    # Server-side prompt building (R21): send raw indexed documents + the
+    # constitution body and let the platform build the prompts. The proprietary
+    # prompt engineering stays off the developer's machine. Prior review findings
+    # are forwarded for the refactor stage so cloud `code` targets the same
+    # issues (parity with local RR).
+    request_findings = [
+        f.model_dump() if hasattr(f, "model_dump") else dict(f) for f in (findings or [])
+    ]
 
     execution_mode = _cloud_execution_mode(constitution) or "cloud_managed"
     auth_ctx = ensure_authenticated(project_root)
@@ -646,23 +651,37 @@ def _cloud_inference(
         "stage": stage,
         "execution_mode": execution_mode,
         "constitution_hash": constitution.content_hash,
-        "system_prompt": system_prompt,
-        "user_prompt": user_prompt,
+        "documents": documents,
+        "constitution_body": getattr(constitution, "body", "") or "",
+        "findings": request_findings if stage != "review" else [],
         "max_alerts": max_alerts,
         "model_hint": model_hint or str(constitution.get_setting("model_id", "managed-default") or "managed-default"),
     }
 
     if execution_mode == "cloud_byok":
-        credential_ref = str(constitution.get_setting("credential_ref", "") or "").strip()
         provider_name = str(constitution.get_setting("provider", "") or "").strip()
-        if not credential_ref:
+        provider_key = str(constitution.get_setting("provider_key", "") or "").strip()
+        credential_ref = str(constitution.get_setting("credential_ref", "") or "").strip()
+
+        # Env-key-first BYOK path: when provider_key is configured (typically via
+        # ${ENV_VAR} interpolation), prefer it over credential_ref.
+        if provider_key:
+            if not provider_name or provider_name.lower() == "cloud":
+                raise RuntimeError(
+                    "cloud_byok with provider_key requires an explicit provider "
+                    "(e.g. provider: openai)."
+                )
+            payload["provider_key"] = provider_key
+            payload["provider"] = provider_name
+        elif credential_ref:
+            payload["credential_ref"] = credential_ref
+            if provider_name and provider_name.lower() != "cloud":
+                payload["provider"] = provider_name
+        else:
             raise RuntimeError(
-                "cloud_byok requires a `credential_ref` in refactor.config. "
-                "Register one with `refactor cloud credentials set` and copy its ref."
+                "cloud_byok requires either `provider_key` (preferred env-key path) "
+                "or `credential_ref` (platform-stored credential path) in refactor.config."
             )
-        payload["credential_ref"] = credential_ref
-        if provider_name and provider_name.lower() != "cloud":
-            payload["provider"] = provider_name
 
     idempotency_key = _stable_idempotency_key(
         account_id=auth_ctx.account_id,
@@ -911,7 +930,7 @@ def init(
     elif config_profile == "byok":
         console.print(
             "[green]Configured[/green] refactor.config for BYOK setup "
-            "(provider=heuristic; uncomment a provider block to use your key)."
+            "(mode=cloud_byok, env-key-first via provider_key; credential_ref is optional fallback)."
         )
     console.print(
         f"[green]Registered[/green] project in central store: {project_store_dir(project_root)}"
@@ -1166,6 +1185,15 @@ def _sandbox_preflight(
     workdir: str | None = None,
 ) -> tuple[bool, str]:
     """Run sandbox preflight and optionally perform approved install plan."""
+    _sr = _sandbox_runtime()
+    command_exists_in_container = _sr.command_exists_in_container
+    command_exists_in_sandbox = _sr.command_exists_in_sandbox
+    exec_in_container = _sr.exec_in_container
+    exec_in_container_stream = _sr.exec_in_container_stream
+    exec_in_sandbox = _sr.exec_in_sandbox
+    exec_in_sandbox_stream = _sr.exec_in_sandbox_stream
+    detect_installer_in_container = _sr.detect_installer_in_container
+    detect_installer_in_sandbox = _sr.detect_installer_in_sandbox
 
     has_container_ctx = bool(runtime and container_name)
     resolved_workdir = str(workdir or "/workspace")
@@ -1465,6 +1493,10 @@ def _ensure_sandbox_ready(
     continue_on_preflight_failure: bool = False,
 ) -> dict | None:
     """Ensure sandbox lifecycle + preflight for stage execution."""
+    _sr = _sandbox_runtime()
+    resolve_runtime = _sr.resolve_runtime
+    sandbox_name = _sr.sandbox_name
+    ensure_sandbox = _sr.ensure_sandbox
     sandbox_cfg = _sandbox_settings(project_config)
     lifecycle = _sandbox_lifecycle(project_config)
     ephemeral = lifecycle == "per_run" and stage in {"review", "code"}
@@ -1533,6 +1565,9 @@ def _teardown_sandbox_context(project_root: Path, ctx: dict | None) -> None:
     """Clean up ephemeral per-run sandboxes."""
     if not ctx or not ctx.get("ephemeral"):
         return
+    _sr = _sandbox_runtime()
+    remove_sandbox_container = _sr.remove_sandbox_container
+    sandbox_name = _sr.sandbox_name
     runtime = str(ctx.get("runtime") or "")
     name = str(ctx.get("container_name") or "")
     ok, msg = remove_sandbox_container(runtime=runtime, container_name=name)
@@ -1567,6 +1602,10 @@ def start(
     project_root, _constitution, project_config = _load_project()
     register_project(project_root)
 
+    _sr = _sandbox_runtime()
+    resolve_runtime = _sr.resolve_runtime
+    ensure_sandbox = _sr.ensure_sandbox
+    attach_sandbox_shell = _sr.attach_shell
     sandbox_cfg = _sandbox_settings(project_config)
     preferred_runtime = str(runtime or sandbox_cfg.get("runtime", "podman") or "podman")
     resolved_runtime, reason = resolve_runtime(preferred_runtime)
@@ -1642,7 +1681,7 @@ def stop() -> None:
             "Switch to a valid directory and retry."
         )
         raise typer.Exit(code=1) from None
-    ok, message = stop_sandbox(project_root=project_root)
+    ok, message = _sandbox_runtime().stop_sandbox(project_root=project_root)
     if ok:
         console.print(f"[green]{message}[/green]")
         return
@@ -1665,7 +1704,7 @@ def shell(
     if not sys.stdin.isatty():
         console.print("[yellow]Non-interactive terminal; cannot attach shell.[/yellow]")
         raise typer.Exit(code=1)
-    ok, message = attach_sandbox_shell(project_root=project_root, shell_path=shell_path)
+    ok, message = _sandbox_runtime().attach_shell(project_root=project_root, shell_path=shell_path)
     if ok:
         return
     console.print(f"[red]Sandbox shell failed:[/red] {message}")
@@ -1777,6 +1816,9 @@ def review(
                 model_hint=provider,
             )
         else:
+            from refactor_core.execution.orchestrator import run_with_mode
+            from refactor_core.providers import get_provider
+
             selected_provider = get_provider(
                 constitution, project_root=project_root, provider_name=provider
             )
@@ -1993,6 +2035,8 @@ def code(
                 )
         selected_provider = None
         if not cloud:
+            from refactor_core.providers import get_provider
+
             selected_provider = get_provider(
                 constitution, project_root=project_root, provider_name=provider
             )
@@ -2015,6 +2059,8 @@ def code(
                 )
                 cloud_review_findings = list(review_artifact.findings or [])
             else:
+                from refactor_core.execution.orchestrator import run_with_mode
+
                 with console.status("[cyan]review[/cyan] analyzing...", spinner="dots") as status:
                     review_progress = _agent_progress_logger(
                         "review", status=status, verbose_steps=True
@@ -2138,6 +2184,8 @@ def code(
                 )
             return
 
+        from refactor_core.execution.rr_executor import run_refactor_requests
+
         with console.status("[cyan]code[/cyan] running...", spinner="dots") as status:
             rr_config = (
                 dict(getattr(project_config, "settings", {}) or {})
@@ -2214,6 +2262,9 @@ def requests(
         if not deferred_rrs:
             console.print("[dim]No deferred requests to retry.[/dim]")
         else:
+            from refactor_core.execution.rr_executor import run_refactor_requests
+            from refactor_core.providers import get_provider
+
             selected_provider = get_provider(
                 constitution, project_root=project_root, provider_name=provider
             )
@@ -3065,60 +3116,123 @@ def _cloud_doctor(
         console.print("[dim]Run `refactor login` or set REFACTOR_API_KEY.[/dim]")
         raise typer.Exit(code=1) from exc
 
-    # BYOK requires a credential_ref in config plus a matching server-side
-    # credential owned by this account.
+    # BYOK supports two secret sources:
+    # 1) provider_key (preferred env-key path), or
+    # 2) credential_ref (platform-stored secret fallback).
     credential_ref = ""
+    provider_key = ""
+    provider_name = ""
     if execution_mode == "cloud_byok":
+        provider_name = str(constitution.get_setting("provider", "") or "").strip()
+        provider_key = str(constitution.get_setting("provider_key", "") or "").strip()
         credential_ref = str(constitution.get_setting("credential_ref", "") or "").strip()
-        if not credential_ref:
+        if not provider_name or provider_name.lower() == "cloud":
             console.print(
-                "[red]cloud_byok[/red]: no `credential_ref` in refactor.config. "
-                "Register one with `refactor cloud credentials set` and add its ref."
+                "[red]cloud_byok[/red]: set an explicit `provider` "
+                "(for example `provider: openai`)."
+            )
+            raise typer.Exit(code=1)
+        console.print(f"[bold]provider[/bold]: {provider_name}")
+        if provider_key:
+            console.print(
+                "[green]provider_key[/green]: set via config/env interpolation "
+                "(preferred BYOK path)."
+            )
+        elif credential_ref:
+            console.print(f"[green]credential_ref[/green]: {credential_ref}")
+        else:
+            console.print(
+                "[red]cloud_byok[/red]: set either `provider_key` (preferred) "
+                "or `credential_ref` in refactor.config."
             )
             raise typer.Exit(code=1)
-        console.print(f"[green]credential_ref[/green]: {credential_ref}")
-        provider_name = str(constitution.get_setting("provider", "") or "").strip()
-        if provider_name and provider_name.lower() != "cloud":
-            console.print(f"[bold]provider[/bold]: {provider_name}")
 
     if skip_ping:
         console.print("[dim]Skipping cloud endpoint reachability check (--skip-ping).[/dim]")
         return
 
-    # Verify the BYOK credential exists and is owned by this account, and that
-    # the credential endpoint is reachable.
+    # Verify BYOK readiness and endpoint reachability.
     if execution_mode == "cloud_byok":
-        try:
-            response = httpx.get(
-                f"{platform_url()}/v1/inference/credentials",
-                headers={"Authorization": f"Bearer {auth_ctx.key.key}"},
-                timeout=20.0,
-            )
-        except httpx.HTTPError as exc:
-            console.print(f"[red]cloud endpoint[/red]: unreachable ({exc}).")
-            raise typer.Exit(code=1) from exc
-        if response.status_code == 402:
-            console.print(
-                "[red]entitlement[/red]: BYOK not enabled for this account (missing `run:byok`). "
-                "Contact your admin to enable BYOK cloud execution."
-            )
-            raise typer.Exit(code=1)
-        if response.status_code == 401:
-            console.print("[red]developer key[/red]: unauthorized (invalid or revoked). Run `refactor login`.")
-            raise typer.Exit(code=1)
-        if response.status_code >= 400:
-            console.print(f"[red]cloud endpoint[/red]: credential check failed ({response.status_code}).")
-            raise typer.Exit(code=1)
-        data = response.json() if response.content else {}
-        refs = {str(row.get("credential_ref", "")) for row in (data.get("credentials", []) or [])}
-        if credential_ref not in refs:
-            console.print(
-                f"[red]credential[/red]: `{credential_ref}` not found for this account. "
-                "Check `refactor cloud credentials list`."
-            )
-            raise typer.Exit(code=1)
-        console.print("[green]credential[/green]: found and owned by this account.")
-        console.print("[green]cloud endpoint[/green]: reachable.")
+        if provider_key:
+            # Env-key path: perform a lightweight inference ping so entitlement +
+            # provider auth are validated together.
+            try:
+                response = httpx.post(
+                    f"{platform_url()}/v1/inference/refactor",
+                    headers={
+                        "Authorization": f"Bearer {auth_ctx.key.key}",
+                        "Content-Type": "application/json",
+                        "Idempotency-Key": f"doctor-cloud-byok-{uuid.uuid4().hex}",
+                    },
+                    json={
+                        "stage": "review",
+                        "execution_mode": "cloud_byok",
+                        "provider": provider_name,
+                        "provider_key": provider_key,
+                        "constitution_hash": "doctor",
+                        "system_prompt": "doctor ping",
+                        "user_prompt": "doctor ping",
+                        "max_alerts": 1,
+                    },
+                    timeout=20.0,
+                )
+            except httpx.HTTPError as exc:
+                console.print(f"[red]cloud endpoint[/red]: unreachable ({exc}).")
+                raise typer.Exit(code=1) from exc
+            if response.status_code == 402:
+                console.print(
+                    "[red]entitlement[/red]: BYOK not enabled for this account (missing `run:byok`). "
+                    "Contact your admin to enable BYOK cloud execution."
+                )
+                raise typer.Exit(code=1)
+            if response.status_code == 401:
+                console.print("[red]developer key[/red]: unauthorized (invalid or revoked). Run `refactor login`.")
+                raise typer.Exit(code=1)
+            if response.status_code >= 400:
+                detail = ""
+                try:
+                    detail = str((response.json() or {}).get("detail", ""))
+                except Exception:
+                    detail = response.text[:200]
+                console.print(
+                    f"[red]cloud BYOK ping failed[/red] ({response.status_code})"
+                    + (f": {detail}" if detail else ".")
+                )
+                raise typer.Exit(code=1)
+            console.print("[green]cloud endpoint[/green]: reachable.")
+            console.print("[green]BYOK provider auth[/green]: OK")
+        else:
+            try:
+                response = httpx.get(
+                    f"{platform_url()}/v1/inference/credentials",
+                    headers={"Authorization": f"Bearer {auth_ctx.key.key}"},
+                    timeout=20.0,
+                )
+            except httpx.HTTPError as exc:
+                console.print(f"[red]cloud endpoint[/red]: unreachable ({exc}).")
+                raise typer.Exit(code=1) from exc
+            if response.status_code == 402:
+                console.print(
+                    "[red]entitlement[/red]: BYOK not enabled for this account (missing `run:byok`). "
+                    "Contact your admin to enable BYOK cloud execution."
+                )
+                raise typer.Exit(code=1)
+            if response.status_code == 401:
+                console.print("[red]developer key[/red]: unauthorized (invalid or revoked). Run `refactor login`.")
+                raise typer.Exit(code=1)
+            if response.status_code >= 400:
+                console.print(f"[red]cloud endpoint[/red]: credential check failed ({response.status_code}).")
+                raise typer.Exit(code=1)
+            data = response.json() if response.content else {}
+            refs = {str(row.get("credential_ref", "")) for row in (data.get("credentials", []) or [])}
+            if credential_ref not in refs:
+                console.print(
+                    f"[red]credential[/red]: `{credential_ref}` not found for this account. "
+                    "Check `refactor cloud credentials list`."
+                )
+                raise typer.Exit(code=1)
+            console.print("[green]credential[/green]: found and owned by this account.")
+            console.print("[green]cloud endpoint[/green]: reachable.")
     else:
         console.print(
             "[dim]cloud_managed uses platform-managed provider credentials; "
@@ -3170,6 +3284,16 @@ def doctor(
         )
         return
 
+    # Local-mode doctor uses engine-only provider/execution helpers. These are
+    # lazily imported here so a client-only install (cloud modes) never requires
+    # the engine on disk (R21 core split); local mode has the engine via binary.
+    from refactor_core.execution.modes import resolve_mode
+    from refactor_core.providers import (
+        get_provider,
+        resolve_provider_name,
+        supported_providers,
+    )
+
     mode = str(constitution.get_setting("mode", "local") or "local")
     provider_name = resolve_provider_name(constitution, provider_name=provider)
 
@@ -3315,7 +3439,7 @@ def _report_sandbox(project_root: Path, config) -> None:
     enabled = True
     runtime_pref = str(sandbox_cfg.get("runtime", "podman") or "podman")
     image = str(sandbox_cfg.get("image") or SANDBOX_DEFAULT_IMAGE)
-    resolved_runtime, reason = resolve_runtime(runtime_pref)
+    resolved_runtime, reason = _sandbox_runtime().resolve_runtime(runtime_pref)
 
     console.print(f"[bold]project[/bold]: {project_root}")
     console.print(f"[bold]sandbox enabled[/bold]: {enabled} [dim](mandatory for local runs)[/dim]")
@@ -3365,6 +3489,10 @@ def _report_sandbox(project_root: Path, config) -> None:
 
 
 def _report_structural_readiness(project_root: Path, config) -> None:
+    # Engine-only structural ops (local doctor diagnostic); lazy so client-only
+    # installs never require the engine on disk (R21 core split).
+    from refactor_core.execution.structural_ops import structural_compatibility_matrix
+
     settings = dict(getattr(config, "settings", {}) or {})
     refactor_cfg = settings.get("refactor", {})
     if not isinstance(refactor_cfg, dict):

{refactorai_cli-0.2.29 → refactorai_cli-0.3.0}/refactorai_cli/commands/runtime_proxy_cmds.py

@@ -142,8 +142,8 @@ def _exec_runtime(command_name: str, passthrough_args: list[str]) -> None:
 
 
 def init(ctx: typer.Context) -> None:
-    """Initialize project state via proprietary runtime."""
-    _exec_runtime("init", list(ctx.args))
+    """Initialize project config locally (no runtime required)."""
+    _delegate_to_run_cmds("init", list(ctx.args))
 
 
 def start(ctx: typer.Context) -> None:

{refactorai_cli-0.2.29 → refactorai_cli-0.3.0}/refactorai_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: refactorai-cli
-Version: 0.2.29
+Version: 0.3.0
 Summary: Local-first CLI for the refactor platform
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -8,6 +8,7 @@ Requires-Dist: typer>=0.12.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: rich>=13.7.0
 Requires-Dist: PyYAML>=6.0.1
+Requires-Dist: refactorai-core>=3.0.0
 
 # refactorai-cli
 
@@ -53,28 +54,34 @@ python -m twine upload ./refactorai-cli/dist/*
 ## Install test (local)
 
 ```bash
-python -m pip install ./refactorai-cli/dist/refactorai_cli-0.2.29-py3-none-any.whl
+python -m pip install ./refactorai-cli/dist/refactorai_cli-0.3.0-py3-none-any.whl
 refactor --version
 ```
 
 ## Cloud BYOK setup (bring your own provider key)
 
 Run cloud inference with your own provider credentials (no local runtime
-required). The secret is read from your environment and encrypted server-side;
-it is never written to disk or printed.
+required). Preferred path is env-key in project config (`provider_key:
+${ENV_VAR}`). Platform-stored credentials (`credential_ref`) are optional
+fallback.
 
 ```bash
 # 1. Authenticate (developer key with the run:byok entitlement).
 refactor login
 
-# 2. Register your provider secret from an env var.
+# 2A. Preferred: set BYOK directly from project env in refactor.config:
+#
+# mode: cloud_byok
+# provider: openai
+# model_id: gpt-4.1-mini
+# provider_key: ${OPENAI_API_KEY}
+#
+# 2B. Optional fallback: register a platform-stored credential from env.
 export OPENAI_API_KEY=sk-...
 refactor cloud credentials set --provider openai --from-env OPENAI_API_KEY --label "my key"
 # -> prints a credential_ref, e.g. cred_01J...
 
-# 3. Point your project at cloud_byok in refactor.config:
-#    mode: cloud_byok
-#    provider: openai
+# 3. If you use platform-stored fallback, set credential_ref in config:
 #    credential_ref: cred_01J...
 
 # 4. Verify readiness, then run.

{refactorai_cli-0.2.29 → refactorai_cli-0.3.0}/refactorai_cli.egg-info/requires.txt

@@ -2,3 +2,4 @@ typer>=0.12.0
 httpx>=0.27.0
 rich>=13.7.0
 PyYAML>=6.0.1
+refactorai-core>=3.0.0