refactorai-cli 0.7.10__tar.gz → 0.7.12__tar.gz

{refactorai_cli-0.7.10 → refactorai_cli-0.7.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: refactorai-cli
-Version: 0.7.10
+Version: 0.7.12
 Summary: Local-first CLI for the refactor platform
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -8,7 +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.2.21
+Requires-Dist: refactorai-core>=3.2.22
 
 # refactorai-cli
 
@@ -22,6 +22,50 @@ By default, the CLI targets `https://api.refactorai.codes`.
 Use `REFACTOR_PLATFORM_URL` only when you need to override the control-plane URL
 (for self-hosted or local development environments).
 
+## Developer flow (init → setup → doctor → watch)
+
+The standard flow after creating an account and generating a developer key:
+
+```bash
+# 1. Create the project (prompts for the developer key if needed) and register
+#    it with the platform. Writes refactor.consti + refactor.config.
+refactor init
+
+# 2. Choose the execution mode and provision only what that mode needs.
+#    Mode can be chosen in the web UI or here; the two stay in sync.
+refactor setup --mode local_byok
+
+# 3. Verify readiness for the resolved mode.
+refactor doctor
+
+# 4. Start the commit loop: commit in your editor, and each commit is reviewed,
+#    refactored, verified, and merged, then it waits for the next commit.
+refactor watch
+```
+
+### Execution modes at a glance
+
+Two independent axes: where the **engine** runs, and where **verification
+(tests)** runs. See `docs/46-execution-variants-and-developer-flow.md`.
+
+| variant         | engine            | verification (tests)                 | runtime artifact |
+| --------------- | ----------------- | ------------------------------------ | ---------------- |
+| local_model     | local             | local                                | **required**     |
+| local_byok      | server            | local (Podman sandbox / toolchain)   | not required     |
+| local_managed   | server            | local (Podman sandbox / toolchain)   | not required     |
+| cloud_byok      | server            | server                               | not required     |
+| cloud_managed   | server            | server                               | not required     |
+
+`refactor setup` is mode-aware: `local_byok` provisions the local verification
+environment (Podman first) + auth only — it does **not** download the runtime
+artifact or install a local model. Only `local_model` needs the runtime artifact.
+
+The verification environment is chosen by a single OS/machine-aware seam
+(`refactor_core.verification_env`): the Podman sandbox by default, falling back to
+the managed host toolchain when no container runtime is available. `refactor
+doctor` reports the selected environment (and `refactor doctor --sandbox` shows
+its full state), so a run and diagnostics always agree.
+
 ## Local development install
 
 From repository root:
@@ -71,7 +115,7 @@ refactor login
 
 # 2A. Preferred: set BYOK directly from project env in refactor.config:
 #
-# mode: cloud_byok
+# execution_variant: cloud_byok
 # provider: openai
 # model_id: gpt-4.1-mini
 # provider_key: ${OPENAI_API_KEY}

refactorai_cli-0.7.12/README.md

@@ -0,0 +1,130 @@
+# refactorai-cli
+
+Public CLI package for Refactor.
+
+- PyPI package name: `refactorai-cli`
+- Installed command: `refactor`
+- Python module package: `refactorai_cli`
+
+By default, the CLI targets `https://api.refactorai.codes`.
+Use `REFACTOR_PLATFORM_URL` only when you need to override the control-plane URL
+(for self-hosted or local development environments).
+
+## Developer flow (init → setup → doctor → watch)
+
+The standard flow after creating an account and generating a developer key:
+
+```bash
+# 1. Create the project (prompts for the developer key if needed) and register
+#    it with the platform. Writes refactor.consti + refactor.config.
+refactor init
+
+# 2. Choose the execution mode and provision only what that mode needs.
+#    Mode can be chosen in the web UI or here; the two stay in sync.
+refactor setup --mode local_byok
+
+# 3. Verify readiness for the resolved mode.
+refactor doctor
+
+# 4. Start the commit loop: commit in your editor, and each commit is reviewed,
+#    refactored, verified, and merged, then it waits for the next commit.
+refactor watch
+```
+
+### Execution modes at a glance
+
+Two independent axes: where the **engine** runs, and where **verification
+(tests)** runs. See `docs/46-execution-variants-and-developer-flow.md`.
+
+| variant         | engine            | verification (tests)                 | runtime artifact |
+| --------------- | ----------------- | ------------------------------------ | ---------------- |
+| local_model     | local             | local                                | **required**     |
+| local_byok      | server            | local (Podman sandbox / toolchain)   | not required     |
+| local_managed   | server            | local (Podman sandbox / toolchain)   | not required     |
+| cloud_byok      | server            | server                               | not required     |
+| cloud_managed   | server            | server                               | not required     |
+
+`refactor setup` is mode-aware: `local_byok` provisions the local verification
+environment (Podman first) + auth only — it does **not** download the runtime
+artifact or install a local model. Only `local_model` needs the runtime artifact.
+
+The verification environment is chosen by a single OS/machine-aware seam
+(`refactor_core.verification_env`): the Podman sandbox by default, falling back to
+the managed host toolchain when no container runtime is available. `refactor
+doctor` reports the selected environment (and `refactor doctor --sandbox` shows
+its full state), so a run and diagnostics always agree.
+
+## Local development install
+
+From repository root:
+
+```bash
+pip install -e refactorai-core -e refactorai-cli
+```
+
+## Build
+
+From repository root:
+
+```bash
+python -m pip install --upgrade build twine
+python -m build "./refactorai-cli"
+```
+
+Artifacts are created in:
+
+- `refactorai-cli/dist/*.whl`
+- `refactorai-cli/dist/*.tar.gz`
+
+## Publish
+
+```bash
+python -m twine check ./refactorai-cli/dist/*
+python -m twine upload ./refactorai-cli/dist/*
+```
+
+## Install test (local)
+
+```bash
+python -m pip install ./refactorai-cli/dist/refactorai_cli-0.3.4-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). 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
+
+# 2A. Preferred: set BYOK directly from project env in refactor.config:
+#
+# execution_variant: 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. If you use platform-stored fallback, set credential_ref in config:
+#    credential_ref: cred_01J...
+
+# 4. Verify readiness, then run.
+refactor doctor
+refactor review .
+refactor code . --apply
+```
+
+Manage credentials:
+
+```bash
+refactor cloud credentials list
+refactor cloud credentials remove --credential-ref cred_01J...
+```

{refactorai_cli-0.7.10 → refactorai_cli-0.7.12}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "refactorai-cli"
-version = "0.7.10"
+version = "0.7.12"
 description = "Local-first CLI for the refactor platform"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -12,7 +12,7 @@ dependencies = [
   "httpx>=0.27.0",
   "rich>=13.7.0",
   "PyYAML>=6.0.1",
-  "refactorai-core>=3.2.21",
+  "refactorai-core>=3.2.22",
 ]
 
 [project.scripts]

{refactorai_cli-0.7.10 → refactorai_cli-0.7.12}/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.7.9"
+__version__ = "0.7.12"

{refactorai_cli-0.7.10 → refactorai_cli-0.7.12}/refactorai_cli/client.py

@@ -143,3 +143,68 @@ class PlatformClient:
             )
         payload = response.json()
         return payload if isinstance(payload, dict) else {}
+
+    def get_project_execution_mode(self, developer_key: str, project_id: str) -> dict:
+        """Read a project's engine execution settings via the developer key.
+
+        Used by the CLI (``setup`` / ``doctor`` / ``watch``) to sync the server's
+        ``execution_mode`` (as chosen in the web UI) into the local
+        ``refactor.config`` -- server-wins. Returns the project record dict.
+        """
+        try:
+            response = httpx.get(
+                f"{self.base_url}/v1/projects/{project_id}/execution-mode",
+                headers={"Authorization": f"Bearer {developer_key}"},
+                timeout=self.timeout,
+            )
+        except httpx.HTTPError as exc:
+            raise PlatformError(f"Could not reach platform at {self.base_url}: {exc}") from exc
+        if response.status_code == 401:
+            raise PlatformError("Developer key is invalid or revoked", status_code=401)
+        if response.status_code == 404:
+            raise PlatformError("Project not found for this account", status_code=404)
+        if response.status_code >= 400:
+            raise PlatformError(
+                f"Could not read project execution mode ({response.status_code})",
+                status_code=response.status_code,
+            )
+        payload = response.json() if response.content else {}
+        return payload if isinstance(payload, dict) else {}
+
+    def set_project_execution_mode(
+        self, developer_key: str, project_id: str, execution_mode: str
+    ) -> dict:
+        """Push a chosen execution variant to the server project (developer key).
+
+        Lets ``refactor setup --mode`` keep the terminal and the web UI in sync.
+        Returns the updated project record dict.
+        """
+        try:
+            response = httpx.patch(
+                f"{self.base_url}/v1/projects/{project_id}/execution-mode",
+                headers={
+                    "Authorization": f"Bearer {developer_key}",
+                    "Content-Type": "application/json",
+                },
+                json={"execution_mode": execution_mode},
+                timeout=self.timeout,
+            )
+        except httpx.HTTPError as exc:
+            raise PlatformError(f"Could not reach platform at {self.base_url}: {exc}") from exc
+        if response.status_code == 401:
+            raise PlatformError("Developer key is invalid or revoked", status_code=401)
+        if response.status_code == 404:
+            raise PlatformError("Project not found for this account", status_code=404)
+        if response.status_code >= 400:
+            detail = ""
+            try:
+                detail = str((response.json() or {}).get("detail", ""))
+            except Exception:
+                detail = response.text[:200]
+            suffix = f": {detail}" if detail else ""
+            raise PlatformError(
+                f"Could not update project execution mode ({response.status_code}){suffix}",
+                status_code=response.status_code,
+            )
+        payload = response.json() if response.content else {}
+        return payload if isinstance(payload, dict) else {}

{refactorai_cli-0.7.10 → refactorai_cli-0.7.12}/refactorai_cli/cloud_rr.py

@@ -148,6 +148,43 @@ def _run_test(
     return False, (proc.stdout or proc.stderr or "")[-500:]
 
 
+def _make_sandbox_verifier(
+    sandbox_ctx: dict,
+) -> tuple[Callable[[str | None], tuple[bool, str]] | None, str, str]:
+    """Build a test runner that executes inside the project's sandbox container.
+
+    docs/46: ``local_byok`` / ``local_managed`` run the engine on the Refactor
+    server but verify on the developer's machine. The per-project sandbox
+    (created + preflighted by the CLI, mounting ``project_root`` at ``workdir``)
+    is reused here so applied diffs and the installed toolchain are both visible.
+
+    Returns ``(runner, container_name, error)``. ``runner`` is ``None`` when the
+    context is incomplete, with a human-readable ``error``.
+    """
+    runtime = str(sandbox_ctx.get("runtime") or "podman")
+    container = str(sandbox_ctx.get("container_name") or "")
+    workdir = str(sandbox_ctx.get("workdir") or "/workspace")
+    if not container:
+        return None, "", "sandbox context is missing a container name"
+
+    from refactor_core import sandbox_runtime as _sr
+
+    def _runner(test_command: str | None) -> tuple[bool, str]:
+        if not test_command or not str(test_command).strip():
+            return False, "no test command configured; cannot verify behavior preservation"
+        command = str(test_command).strip()
+        if command == "npm test":
+            command = "CI=true npm test -- --watch=false"
+        return _sr.exec_in_container(
+            runtime=runtime,
+            container_name=container,
+            command=command,
+            workdir=workdir,
+        )
+
+    return _runner, container, ""
+
+
 def _run_command_with_progress(
     execution_root: Path,
     command: str,
@@ -1546,7 +1583,31 @@ def run_cloud_refactor_requests(
         test_command=test_command or "",
         execution_env="cloud",
     )
-    execution_root = _prepare_managed_workspace(project_root, progress_cb=progress_cb)
+    # docs/46: for local-verification variants (local_byok / local_managed) the
+    # CLI passes the ready project sandbox via ``_sandbox_context``. When present,
+    # verification runs INSIDE that container (which mounts project_root and has
+    # the preflight-installed toolchain), so we verify against project_root
+    # directly and skip host toolchain provisioning. _apply_and_verify still backs
+    # up before applying and reverts on red, preserving the "never leave a red
+    # tree" guarantee. Cloud_* variants keep the managed-workspace mirror + host
+    # verification path unchanged.
+    sandbox_ctx = config.get("_sandbox_context") if isinstance(config, dict) else None
+    verify_runner: Callable[[str | None], tuple[bool, str]] | None = None
+    if sandbox_ctx:
+        verify_runner, _verify_container, verify_err = _make_sandbox_verifier(sandbox_ctx)
+        if verify_runner is None:
+            reason = f"sandbox verification unavailable: {verify_err}"
+            _emit(progress_cb, phase="rr", event="preflight_failed", reason=reason)
+            notes.append(reason)
+            return _build_artifact(
+                run_store, run_id, constitution, model_id, outcomes, counts,
+                notes, stopped=True, stop_reason=reason, test_command=test_command,
+            )
+
+    if verify_runner is not None:
+        execution_root = project_root
+    else:
+        execution_root = _prepare_managed_workspace(project_root, progress_cb=progress_cb)
     status_before = _git_status_porcelain(project_root)
 
     # Managed host toolchain: when the resolved command's runtime is missing from
@@ -1563,17 +1624,22 @@ def run_cloud_refactor_requests(
             apply_byok_payload=apply_byok_payload,
         )
 
-    toolchain_env, toolchain_note = _provision_toolchain(
-        execution_root,
-        test_command,
-        config,
-        consent_cb=toolchain_consent_cb,
-        progress_cb=progress_cb,
-        dep_locator_cb=_dep_locator,
-    )
-    toolchain_env = _workspace_env(project_root, toolchain_env)
+    if verify_runner is not None:
+        # Sandbox verification (docs/46): the container supplies the toolchain, so
+        # no host runtime is provisioned and the host working tree is untouched.
+        toolchain_env, toolchain_note = None, "verification runs in the project sandbox"
+    else:
+        toolchain_env, toolchain_note = _provision_toolchain(
+            execution_root,
+            test_command,
+            config,
+            consent_cb=toolchain_consent_cb,
+            progress_cb=progress_cb,
+            dep_locator_cb=_dep_locator,
+        )
+        toolchain_env = _workspace_env(project_root, toolchain_env)
     status_after_toolchain = _git_status_porcelain(project_root)
-    if status_after_toolchain != status_before:
+    if verify_runner is None and status_after_toolchain != status_before:
         reason = (
             "managed workspace invariant violated: toolchain/dependency setup changed the project "
             "working tree before any RR patch was applied; aborting run."
@@ -1607,7 +1673,7 @@ def run_cloud_refactor_requests(
     # we did NOT provision a managed runtime (managed provisioning already
     # supplies a `python`). Prevents a `python: not found` baseline failure and
     # the endless-defer loop it caused.
-    if toolchain_env is None and test_command:
+    if verify_runner is None and toolchain_env is None and test_command:
         normalized = _normalize_command_interpreters(test_command)
         if normalized and normalized != test_command:
             _emit(
@@ -1626,23 +1692,25 @@ def run_cloud_refactor_requests(
     # Run-level dependency preflight: always attempt dependency restoration for
     # runtimes implied by the configured test command, even when binaries are
     # already present on PATH. This prevents import-time baseline failures from
-    # deferring requests one-by-one later in the loop.
-    for runtime in _command_runtimes(test_command):
-        _restore_dependencies(
-            execution_root,
-            runtime,
-            toolchain_env,
-            progress_cb,
-            config=config,
-            dep_locator_cb=_dep_locator,
-        )
+    # deferring requests one-by-one later in the loop. Skipped for sandbox
+    # verification (docs/46): the container's preflight already provisioned deps.
+    if verify_runner is None:
+        for runtime in _command_runtimes(test_command):
+            _restore_dependencies(
+                execution_root,
+                runtime,
+                toolchain_env,
+                progress_cb,
+                config=config,
+                dep_locator_cb=_dep_locator,
+            )
 
     # Fail-fast: if a test command is configured but STILL not runnable after
     # provisioning + interpreter normalization, stop up front with an actionable
     # message instead of opening a session and deferring every RR behind an
     # opaque `python: not found`. (A run with NO test command keeps prior
     # behavior: the server decides per-RR whether it can proceed.)
-    if test_command and not _client_preflight_command(
+    if verify_runner is None and test_command and not _client_preflight_command(
         project_root, test_command, env=toolchain_env
     ):
         missing = _missing_binaries(test_command, env=toolchain_env)
@@ -1669,7 +1737,10 @@ def run_cloud_refactor_requests(
     # Run-level baseline characterization: execute ONCE and reuse for all RR
     # steps. If baseline is red, stop the run before opening the RR session so
     # requests are not deferred one-by-one for dependency/env failures.
-    baseline_ok, baseline_detail = _run_test(execution_root, test_command, env=toolchain_env)
+    if verify_runner is not None:
+        baseline_ok, baseline_detail = verify_runner(test_command)
+    else:
+        baseline_ok, baseline_detail = _run_test(execution_root, test_command, env=toolchain_env)
     _emit(
         progress_cb,
         phase="rr",
@@ -1677,7 +1748,7 @@ def run_cloud_refactor_requests(
         rr_id="",
         passed=baseline_ok,
         detail=baseline_detail,
-        execution_env="host+toolchain" if toolchain_env else "host",
+        execution_env="sandbox" if verify_runner is not None else ("host+toolchain" if toolchain_env else "host"),
     )
     if not baseline_ok:
         reason = (
@@ -1784,7 +1855,7 @@ def run_cloud_refactor_requests(
             passed, detail = cached_baseline
             _emit(progress_cb, phase="rr", event="baseline_test", rr_id=current_rr_id,
                   passed=passed, detail=detail,
-                  execution_env="host+toolchain" if toolchain_env else "host")
+                  execution_env="sandbox" if verify_runner is not None else ("host+toolchain" if toolchain_env else "host"))
             action = session.step(
                 _step_payload(token, current_rr_id, "baseline_result", by_id, project_root,
                               baseline_passed=passed, baseline_detail=detail)
@@ -1864,6 +1935,7 @@ def run_cloud_refactor_requests(
                     diff_text,
                     test_command,
                     env=toolchain_env,
+                    verify_cmd=verify_runner,
                 )
                 pending.applied = True
                 if passed:
@@ -1970,6 +2042,7 @@ def _apply_and_verify(
     test_command,
     *,
     env: dict | None = None,
+    verify_cmd: Callable[[str | None], tuple[bool, str]] | None = None,
 ) -> tuple[bool, str, list[str]]:
     """Apply the diff (with backup), run the test; revert on red.
 
@@ -1977,6 +2050,10 @@ def _apply_and_verify(
     from the diff BEFORE applying (the tree is mutated in place afterward, so it
     cannot be recomputed against the modified files). ``env`` optionally supplies
     the managed-toolchain environment used to run the test.
+
+    ``verify_cmd`` (docs/46) optionally overrides host execution: for
+    ``local_byok`` / ``local_managed`` it runs the test inside the project
+    sandbox container so verification happens in the developer's environment.
     """
     if not diff_text:
         return False, "empty diff", []
@@ -1993,7 +2070,10 @@ def _apply_and_verify(
         apply_changes(execution_root, verify_backup_dir, changes)
     except Exception as exc:
         return False, f"apply failed: {exc}", changed_files
-    passed, detail = _run_test(execution_root, test_command, env=env)
+    if verify_cmd is not None:
+        passed, detail = verify_cmd(test_command)
+    else:
+        passed, detail = _run_test(execution_root, test_command, env=env)
     if not passed:
         try:
             revert_from_backup(execution_root, verify_backup_dir)