refactorai-cli 0.4.16__tar.gz → 0.5.0__tar.gz

{refactorai_cli-0.4.16 → refactorai_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: refactorai-cli
-Version: 0.4.16
+Version: 0.5.0
 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.9
+Requires-Dist: refactorai-core>=3.2.11
 
 # refactorai-cli
 

{refactorai_cli-0.4.16 → refactorai_cli-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "refactorai-cli"
-version = "0.4.16"
+version = "0.5.0"
 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.9",
+  "refactorai-core>=3.2.11",
 ]
 
 [project.scripts]

{refactorai_cli-0.4.16 → refactorai_cli-0.5.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.4.16"
+__version__ = "0.5.0"

{refactorai_cli-0.4.16 → refactorai_cli-0.5.0}/refactorai_cli/auth.py

@@ -27,6 +27,7 @@ class AuthContext:
     account_id: str
     quota_remaining: int | None
     cached: bool
+    account_slug: str = ""
 
 
 def _fingerprint(key: str) -> str:
@@ -56,6 +57,7 @@ def _write_cache(key: str, payload: dict) -> None:
     expires_epoch = _parse_expiry(payload.get("expires_at"))
     record = {
         "account_id": payload.get("account_id"),
+        "account_slug": payload.get("account_slug"),
         "quota_remaining": payload.get("quota_remaining"),
         "validation_token": payload.get("validation_token"),
         "expires_at": payload.get("expires_at"),
@@ -100,6 +102,7 @@ def ensure_authenticated(
                 account_id=cached.get("account_id", "unknown"),
                 quota_remaining=cached.get("quota_remaining"),
                 cached=True,
+                account_slug=cached.get("account_slug") or "",
             )
 
     client = client or PlatformClient()
@@ -117,4 +120,5 @@ def ensure_authenticated(
         account_id=payload.get("account_id", "unknown"),
         quota_remaining=payload.get("quota_remaining"),
         cached=False,
+        account_slug=payload.get("account_slug") or "",
     )

{refactorai_cli-0.4.16 → refactorai_cli-0.5.0}/refactorai_cli/client.py

@@ -45,6 +45,61 @@ class PlatformClient:
             )
         return response.json()
 
+    def create_project(
+        self,
+        developer_key: str,
+        account_slug: str,
+        name: str,
+        *,
+        idempotency_key: str,
+        provider: str = "github",
+        default_branch: str = "main",
+        visibility: str = "private",
+        repo_url: str | None = None,
+    ) -> dict:
+        """Create a project under ``account_slug`` and return the created record.
+
+        Used by ``refactor init`` to auto-provision a cloud project for the local
+        commit loop. ``repo_url`` is optional; it can be attached later from the
+        web UI. Raises ``PlatformError`` on any rejection or transport failure.
+        """
+        body: dict = {
+            "name": name,
+            "provider": provider,
+            "default_branch": default_branch,
+            "visibility": visibility,
+        }
+        if repo_url:
+            body["repo_url"] = repo_url
+        try:
+            response = httpx.post(
+                f"{self.base_url}/v1/accounts/{account_slug}/projects",
+                headers={
+                    "Authorization": f"Bearer {developer_key}",
+                    "Content-Type": "application/json",
+                    "Idempotency-Key": idempotency_key,
+                },
+                json=body,
+                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 >= 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"Project creation failed ({response.status_code}){suffix}",
+                status_code=response.status_code,
+            )
+        return response.json() if response.content else {}
+
     def list_key_accounts(self, developer_key: str) -> list[dict]:
         try:
             response = httpx.get(

{refactorai_cli-0.4.16 → refactorai_cli-0.5.0}/refactorai_cli/commands/hook_cmds.py

@@ -27,6 +27,7 @@ app = typer.Typer(
 )
 
 _HOOK_MARKER = "RefactorAI post-commit hook"
+_PRE_PUSH_MARKER = "RefactorAI pre-push hook"
 _DEFAULT_HOOKS_DIR = ".githooks"
 
 # Non-blocking + fail-open: capture HEAD, then detach the enqueue so `git commit`
@@ -46,6 +47,18 @@ fi
 exit 0
 """
 
+# Blocking-capable pre-push gate. `refactor pre-push` is itself fail-open and only
+# ever exits non-zero under a `strict` policy, so the default (warn) never blocks.
+_PRE_PUSH_SCRIPT = """#!/usr/bin/env bash
+# RefactorAI pre-push hook (docs/44 Phase 2 gate).
+# Delegates to `refactor pre-push`, which enforces the project's pre-push policy.
+if ! command -v refactor >/dev/null 2>&1; then
+  exit 0
+fi
+refactor pre-push
+exit $?
+"""
+
 
 def _require_repo(project_root: Path) -> str:
     root = git_scope.repo_root(project_root)
@@ -98,14 +111,39 @@ def perform_install(
             "message": "could not set core.hooksPath",
         }
 
+    pre_push_status = _install_pre_push(hooks_path, force=force)
+
     return {
         "status": "installed",
         "rel_dir": rel_dir,
         "hook_file": hook_file,
+        "pre_push_status": pre_push_status,
+        "pre_push_file": hooks_path / "pre-push",
         "message": f"installed post-commit hook -> {hook_file}",
     }
 
 
+def _install_pre_push(hooks_path: Path, *, force: bool) -> str:
+    """Write the pre-push gate hook. Additive + best-effort (never fails install).
+
+    Returns ``installed`` (written/refreshed), ``exists_foreign`` (a non-RefactorAI
+    pre-push hook is present and ``force`` was not set) or ``error``.
+    """
+    pre_push_file = hooks_path / "pre-push"
+    if (
+        pre_push_file.exists()
+        and _PRE_PUSH_MARKER not in _safe_read(pre_push_file)
+        and not force
+    ):
+        return "exists_foreign"
+    try:
+        pre_push_file.write_text(_PRE_PUSH_SCRIPT, encoding="utf-8")
+        pre_push_file.chmod(pre_push_file.stat().st_mode | 0o755)
+    except OSError:
+        return "error"
+    return "installed"
+
+
 @app.command("install")
 def install(
     hooks_dir: str | None = typer.Option(
@@ -133,11 +171,24 @@ def install(
         console.print(f"[red]hook: could not install:[/red] {result['message']}")
         raise typer.Exit(code=1)
 
+    pre_push_status = result.get("pre_push_status")
+    if pre_push_status == "installed":
+        pre_push_line = f"[green]Installed[/green] pre-push gate hook -> {result.get('pre_push_file')}\n"
+    elif pre_push_status == "exists_foreign":
+        pre_push_line = (
+            "[yellow]Skipped pre-push hook:[/yellow] a non-RefactorAI pre-push hook already exists "
+            "(re-run with --force to overwrite).\n"
+        )
+    else:
+        pre_push_line = "[yellow]Could not install the pre-push gate hook.[/yellow]\n"
+
     console.print(
         f"[green]Installed[/green] post-commit hook -> {result['hook_file']}\n"
+        f"{pre_push_line}"
         f"[dim]core.hooksPath = {result['rel_dir']}[/dim]\n"
         "Every commit now enqueues a local review event. "
         "Open the Refactor Terminal with `refactor watch`.\n"
+        "[dim]The pre-push gate is advisory (warn) until a platform admin sets it to strict.[/dim]\n"
         "[dim]Tip: set watch.auto_open + watch.terminal (or REFACTOR_WATCH_AUTO_OPEN / "
         "REFACTOR_WATCH_TERMINAL) to open it automatically on each commit.[/dim]"
     )
@@ -155,23 +206,32 @@ def uninstall(
     root = Path(_require_repo(Path.cwd()))
     rel_dir = git_scope.get_config(root, "core.hooksPath") or _DEFAULT_HOOKS_DIR
     hook_file = (root / rel_dir / "post-commit").resolve()
+    pre_push_file = (root / rel_dir / "pre-push").resolve()
 
-    removed = False
+    removed = []
     if hook_file.exists() and _HOOK_MARKER in _safe_read(hook_file):
         try:
             hook_file.unlink()
-            removed = True
+            removed.append("post-commit")
         except OSError as exc:
             console.print(f"[red]hook: could not remove hook:[/red] {exc}")
             raise typer.Exit(code=1) from exc
 
+    if pre_push_file.exists() and _PRE_PUSH_MARKER in _safe_read(pre_push_file):
+        try:
+            pre_push_file.unlink()
+            removed.append("pre-push")
+        except OSError as exc:
+            console.print(f"[red]hook: could not remove pre-push hook:[/red] {exc}")
+            raise typer.Exit(code=1) from exc
+
     if reset_hooks_path:
         git_scope.unset_config(root, "core.hooksPath")
 
     if removed:
-        console.print("[green]Removed[/green] the RefactorAI post-commit hook.")
+        console.print(f"[green]Removed[/green] the RefactorAI {' and '.join(removed)} hook(s).")
     else:
-        console.print("[dim]hook: no RefactorAI post-commit hook found to remove.[/dim]")
+        console.print("[dim]hook: no RefactorAI hooks found to remove.[/dim]")
 
 
 @app.command("enqueue")
@@ -201,6 +261,23 @@ def enqueue(
     # and fail-open so it never affects the commit flow (docs/42 `R29`, Phase 4).
     if enqueued:
         _maybe_auto_open(project_root, verbose)
+        _maybe_report_commit(project_root, event, verbose)
+
+
+def _maybe_report_commit(project_root: Path, event: dict | None, verbose: bool) -> None:
+    """Best-effort opt-in commit telemetry (docs/44 Phase 3). Never raises."""
+    if not event:
+        return
+    try:
+        from refactorai_cli import commit_telemetry
+
+        body = commit_telemetry.build_commit_event_from_queue(event)
+        posted = commit_telemetry.post_commit_event(project_root, body)
+        if verbose and posted:
+            console.print("[dim]hook: reported commit telemetry.[/dim]")
+    except Exception as exc:  # fail-open
+        if verbose:
+            console.print(f"[yellow]hook: telemetry skipped ({exc}).[/yellow]")
 
 
 def _watch_settings(project_root: Path) -> dict:
@@ -245,7 +322,9 @@ def status() -> None:
 
     rel_dir = git_scope.get_config(root, "core.hooksPath")
     hook_file = (root / (rel_dir or _DEFAULT_HOOKS_DIR) / "post-commit").resolve()
+    pre_push_file = (root / (rel_dir or _DEFAULT_HOOKS_DIR) / "pre-push").resolve()
     is_ours = hook_file.exists() and _HOOK_MARKER in _safe_read(hook_file)
+    pre_push_ours = pre_push_file.exists() and _PRE_PUSH_MARKER in _safe_read(pre_push_file)
     q_path = commit_queue.queue_path(root)
 
     console.print(f"Repository: [bold]{root}[/bold]")
@@ -256,6 +335,12 @@ def status() -> None:
         console.print(f"post-commit hook: [yellow]present but not RefactorAI[/yellow] ({hook_file})")
     else:
         console.print("post-commit hook: [red]not installed[/red] (run `refactor hook install`)")
+    if pre_push_ours:
+        console.print(f"pre-push hook: [green]installed[/green] ({pre_push_file})")
+    elif pre_push_file.exists():
+        console.print(f"pre-push hook: [yellow]present but not RefactorAI[/yellow] ({pre_push_file})")
+    else:
+        console.print("pre-push hook: [red]not installed[/red] (run `refactor hook install`)")
     console.print(f"Queue: {q_path}")
     console.print(f"Pending events: [bold]{commit_queue.pending_count(root)}[/bold]")
 

refactorai_cli-0.5.0/refactorai_cli/commands/pre_push_cmds.py

@@ -0,0 +1,151 @@
+"""`refactor pre-push`: the local pre-push quality gate (docs/44 Phase 2).
+
+Invoked by the installed git ``pre-push`` hook. It reads the project's pre-push
+policy from ``refactor.config`` (falling back to safe defaults), inspects the
+local Refactor Request store, and decides whether to allow the push.
+
+Contract:
+- Fail-open: any unexpected error allows the push (exit 0). The gate must never
+  wedge a developer because of a local error.
+- ``off``/``warn`` never block. Only ``strict`` can exit non-zero.
+- Escape hatch: ``REFACTOR_SKIP=1`` bypasses a strict block when policy allows;
+  ``REFACTOR_SKIP_REASON`` supplies the reason (recorded when auditing is on).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from refactorai_cli import git_scope, pre_push_gate
+
+console = Console()
+
+_TRUTHY = {"1", "true", "yes", "on"}
+_HIGH_SEVERITIES = {"high", "critical"}
+
+
+def _project_root() -> Path:
+    root = git_scope.repo_root(Path.cwd())
+    return Path(root) if root else Path.cwd()
+
+
+def _load_policy(project_root: Path) -> dict:
+    """Best-effort read of the ``pre_push`` policy from refactor.config settings."""
+    policy = dict(pre_push_gate.DEFAULT_POLICY)
+    policy["block_on"] = list(pre_push_gate.DEFAULT_POLICY["block_on"])
+    try:
+        from refactor_core.constitution import CONFIG_FILENAME, find_project_files, load_config
+
+        consti_path, _ = find_project_files(project_root)
+        if consti_path is None:
+            return policy
+        cfg = load_config(consti_path.parent / CONFIG_FILENAME)
+        settings = dict(getattr(cfg, "settings", {}) or {})
+        stored = settings.get("pre_push")
+        if isinstance(stored, dict):
+            policy.update(stored)
+            if not isinstance(policy.get("block_on"), (list, tuple)):
+                policy["block_on"] = list(pre_push_gate.DEFAULT_POLICY["block_on"])
+    except Exception:
+        # Fail-open on any config error: keep defaults (warn).
+        pass
+    return policy
+
+
+def _count_requests(project_root: Path) -> tuple[int, int]:
+    """Return ``(open_requests, high_severity_open)`` from the local RR store."""
+    try:
+        from refactor_core.refactor_requests import pending_requests
+
+        pending = pending_requests(project_root)
+    except Exception:
+        return 0, 0
+    high = sum(1 for r in pending if str(getattr(r, "severity", "")).lower() in _HIGH_SEVERITIES)
+    return len(pending), high
+
+
+def _record_skip(project_root: Path, *, reasons: list[str], reason: str) -> None:
+    try:
+        from refactor_core.paths import ensure_dir, project_store_dir
+
+        audit_path = ensure_dir(project_store_dir(project_root)) / "pre_push_audit.jsonl"
+        entry = {
+            "at": datetime.now(timezone.utc).isoformat(),
+            "event": "pre_push_bypass",
+            "reason": reason,
+            "blockers": reasons,
+            "user": os.environ.get("USER") or os.environ.get("USERNAME") or "",
+        }
+        with audit_path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(entry) + "\n")
+    except Exception:
+        # Auditing is best-effort and must never affect the push decision.
+        pass
+
+
+def pre_push(
+    ctx: typer.Context,
+    json_out: bool = typer.Option(False, "--json", help="Emit the gate decision as JSON."),
+) -> None:
+    """Evaluate the pre-push gate for the current repository."""
+    try:
+        project_root = _project_root()
+        policy = _load_policy(project_root)
+        open_requests, high_severity_open = _count_requests(project_root)
+        skip_requested = str(os.environ.get("REFACTOR_SKIP", "")).strip().lower() in _TRUTHY
+        skip_reason = os.environ.get("REFACTOR_SKIP_REASON", "")
+
+        decision = pre_push_gate.evaluate(
+            policy,
+            open_requests=open_requests,
+            high_severity_open=high_severity_open,
+            skip_requested=skip_requested,
+            skip_reason=skip_reason,
+        )
+
+        if decision.skipped and policy.get("audit_skips", True):
+            _record_skip(project_root, reasons=decision.reasons, reason=decision.skip_reason)
+
+        if json_out:
+            console.print_json(
+                data={
+                    "allow": decision.allow,
+                    "mode": decision.mode,
+                    "reasons": decision.reasons,
+                    "skipped": decision.skipped,
+                }
+            )
+        else:
+            _render(decision)
+
+        if not decision.allow:
+            raise typer.Exit(code=1)
+    except typer.Exit:
+        raise
+    except Exception as exc:  # fail-open: never wedge a push on a local error
+        console.print(f"[yellow]pre-push: gate skipped (fail-open): {exc}[/yellow]")
+
+
+def _render(decision: pre_push_gate.GateDecision) -> None:
+    if decision.mode == "off":
+        return
+    if not decision.reasons:
+        console.print("[green]pre-push:[/green] gate passed — nothing blocking this push.")
+        return
+    heading = "[red]pre-push: push blocked[/red]" if not decision.allow else "[yellow]pre-push: warnings[/yellow]"
+    console.print(heading)
+    for reason in decision.reasons:
+        console.print(f"  • {reason}")
+    if decision.skipped:
+        console.print("[yellow]  bypassed via REFACTOR_SKIP[/yellow]")
+    elif not decision.allow:
+        console.print(
+            "[dim]  Resolve with `refactor watch` / `refactor code`, or bypass with "
+            "REFACTOR_SKIP=1 git push.[/dim]"
+        )

{refactorai_cli-0.4.16 → refactorai_cli-0.5.0}/refactorai_cli/commands/run_cmds.py

@@ -102,11 +102,13 @@ from refactor_core.store import (
 )
 from refactor_core.testcmd import resolve_test_command
 
-from refactorai_cli.auth import AuthError, ensure_authenticated
+from refactorai_cli.auth import AuthContext, AuthError, ensure_authenticated
+from refactorai_cli.client import PlatformClient, PlatformError
+from refactorai_cli.credentials import load_credentials, save_credentials
 from refactorai_cli.dotenv_loader import DotenvResult, load_project_dotenv
 from refactorai_cli.local_engine_runtime import DEFAULT_ENGINE_PORT, read_engine_state
 from refactorai_cli.runtime_manager import runtime_status, runtime_version_dir
-from refactorai_cli.settings import platform_url
+from refactorai_cli.settings import mask_key, platform_url
 from refactorai_cli.setup_flow import (
     BACKEND_BYOK,
     BACKEND_LOCAL_SERVER,
@@ -1033,7 +1035,14 @@ def init(
         help=f"Overwrite existing {CONSTITUTION_FILENAME} and {CONFIG_FILENAME}.",
     ),
 ) -> None:
-    """Create `refactor.consti` + `refactor.config` and register the project."""
+    """Create `refactor.consti` + `refactor.config` and register the project.
+
+    `init` is online-first: it authenticates (prompting for a developer key when
+    needed) and auto-creates a cloud project so the local commit loop reports to
+    the platform out of the box. The folder name becomes the project name (edit
+    it later in the web UI) and the generated project id is written to
+    `refactor.config`. No provider or repository details are required here.
+    """
     try:
         project_root = Path.cwd()
     except OSError:
@@ -1052,14 +1061,48 @@ def init(
             "Use --force to overwrite."
         )
         raise typer.Exit(code=1)
+
+    # Authenticate and provision the cloud project BEFORE writing any files, so a
+    # failure leaves the working tree untouched (fail-fast, no partial state).
+    auth_ctx = _ensure_init_auth(project_root)
+    account_slug = auth_ctx.account_slug or load_credentials().get("active_account_slug") or ""
+    if not account_slug:
+        console.print(
+            "[red]Could not resolve your account.[/red] Run `refactor login` and retry."
+        )
+        raise typer.Exit(code=1)
+
+    project_name = project_root.name or "refactor-project"
+    client = PlatformClient()
+    try:
+        created = client.create_project(
+            auth_ctx.key.key,
+            account_slug,
+            project_name,
+            idempotency_key=str(uuid.uuid4()),
+        )
+    except PlatformError as exc:
+        console.print(f"[red]Could not create cloud project:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+    project_id = str(created.get("id") or "").strip()
+    if not project_id:
+        console.print("[red]Cloud project creation returned no id.[/red] Please retry.")
+        raise typer.Exit(code=1)
+
     consti_target.write_text(DEFAULT_CONSTITUTION, encoding="utf-8")
     config_text, config_profile = _default_config_for_init()
+    config_text = _inject_project_id(config_text, project_id)
     config_target.write_text(config_text, encoding="utf-8")
 
     constitution = load_constitution(consti_target)
     record = register_project(project_root, constitution_hash=constitution.content_hash)
     console.print(f"[green]Created[/green] {consti_target}")
     console.print(f"[green]Created[/green] {config_target}")
+    console.print(
+        f"[green]Linked[/green] to cloud project [bold]{project_name}[/bold] "
+        f"(account {account_slug}). The project id is saved in {CONFIG_FILENAME}; "
+        "rename the project or attach a repository anytime from the web UI."
+    )
     if config_profile == "local_server":
         console.print(
             "[green]Configured[/green] refactor.config for local server setup "
@@ -1081,6 +1124,79 @@ def init(
     _offer_commit_hook(project_root)
 
 
+def _ensure_init_auth(project_root: Path) -> AuthContext:
+    """Return a validated ``AuthContext`` for `init`, prompting to log in if needed.
+
+    Tries the resolved developer key first (env/config/credentials). When none is
+    configured or it is rejected, an interactive session prompts for a developer
+    key and stores it in the central credentials file. Non-interactive runs fail
+    fast with guidance rather than hanging on a prompt.
+    """
+    try:
+        return ensure_authenticated(project_root, force_remote=True)
+    except AuthError:
+        pass
+
+    if not sys.stdin.isatty():
+        console.print(
+            "[red]`refactor init` requires authentication.[/red] "
+            "Set REFACTOR_API_KEY or run `refactor login` first."
+        )
+        raise typer.Exit(code=1)
+
+    console.print("[bold]Sign in to Refactor[/bold] to create your cloud project.")
+    console.print(
+        f"[dim]No account yet? Create one and generate a developer key at "
+        f"{platform_url()}, then paste it below.[/dim]"
+    )
+    developer_key = typer.prompt("Developer key", hide_input=True).strip()
+    if not developer_key:
+        console.print("[red]No key provided.[/red]")
+        raise typer.Exit(code=1)
+
+    client = PlatformClient()
+    try:
+        payload = client.validate_key(developer_key)
+    except PlatformError as exc:
+        console.print(f"[red]Login failed:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+    if not payload.get("valid", False):
+        console.print("[red]Login failed:[/red] key is invalid or revoked.")
+        raise typer.Exit(code=1)
+
+    creds = load_credentials()
+    creds.update(
+        {
+            "developer_key": developer_key,
+            "account_id": payload.get("account_id"),
+            "active_account_id": payload.get("account_id"),
+            "active_account_slug": payload.get("account_slug"),
+            "platform_url": platform_url(),
+            "masked_key": mask_key(developer_key),
+        }
+    )
+    save_credentials(creds)
+    console.print(
+        f"[green]Logged in[/green] as account "
+        f"[bold]{payload.get('account_id', 'unknown')}[/bold] ({mask_key(developer_key)})."
+    )
+    return ensure_authenticated(project_root, force_remote=False)
+
+
+def _inject_project_id(config_text: str, project_id: str) -> str:
+    """Persist the bound cloud ``project_id`` into refactor.config text.
+
+    Written as a top-level key so ``constitution.load_config`` exposes it under
+    ``settings['project_id']`` (which the commit-loop telemetry reads). Inserted
+    right after the ``version:`` line, or prepended if that anchor is absent.
+    """
+    line = f"project_id: {project_id}\n"
+    anchor = "version: 1\n"
+    if anchor in config_text:
+        return config_text.replace(anchor, anchor + line, 1)
+    return line + config_text
+
+
 def _offer_commit_hook(project_root: Path) -> None:
     """Offer to wire the local commit-review hook during `init` (docs/41 `R28`).
 
@@ -4518,7 +4634,34 @@ def _cloud_doctor(
     if execution_mode == "cloud_byok":
         if provider_key:
             # Env-key path: perform a lightweight inference ping so entitlement +
-            # provider auth are validated together.
+            # provider auth are validated together. Forward the configured
+            # ``model_id`` (already ${ENV} interpolated by the constitution) so the
+            # ping validates the *same* model real runs use. Doctor must not let the
+            # backend/provider silently choose a default model because that can pass
+            # while the configured run model is missing or unreachable.
+            model_hint = str(constitution.get_setting("model_id", "") or "").strip()
+            if not model_hint:
+                console.print(
+                    "[red]model[/red]: no `model_id` configured in refactor.config."
+                )
+                console.print(
+                    "[yellow]doctor[/yellow]: you need to set `model_id` in "
+                    "refactor.config for the selected provider before doctor can "
+                    "validate model reachability."
+                )
+                raise typer.Exit(code=1)
+            console.print(f"[bold]model[/bold]: {model_hint}")
+            payload = {
+                "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,
+                "model_hint": model_hint,
+            }
             try:
                 response = httpx.post(
                     f"{platform_url()}/v1/inference/refactor",
@@ -4527,16 +4670,7 @@ def _cloud_doctor(
                         "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,
-                    },
+                    json=payload,
                     timeout=20.0,
                 )
             except httpx.HTTPError as exc:
@@ -4561,6 +4695,11 @@ def _cloud_doctor(
                     f"[red]cloud BYOK ping failed[/red] ({response.status_code})"
                     + (f": {detail}" if detail else ".")
                 )
+                console.print(
+                    "[yellow]doctor[/yellow]: could not reach the configured model. "
+                    "Set a reachable `model_id` in refactor.config for the selected "
+                    "provider, then rerun `refactor doctor`."
+                )
                 raise typer.Exit(code=1)
             console.print("[green]cloud endpoint[/green]: reachable.")
             console.print("[green]BYOK provider auth[/green]: OK")

{refactorai_cli-0.4.16 → refactorai_cli-0.5.0}/refactorai_cli/commands/watch_cmds.py

@@ -316,6 +316,20 @@ def _load_initial_events(project_root: Path, since: str | None, limit: int) -> l
     return events
 
 
+def _report_node(project_root: Path, node) -> None:
+    """Best-effort opt-in commit telemetry for a node transition (docs/44 Phase 3).
+
+    Fail-open: no-ops instantly unless the repo is bound to a platform project
+    (``REFACTOR_PROJECT_ID`` / ``project_id`` in config) and never raises.
+    """
+    try:
+        from refactorai_cli import commit_telemetry
+
+        commit_telemetry.emit_node(project_root, node)
+    except Exception:
+        pass
+
+
 def process_pending(
     project_root: Path,
     state: WatchState,
@@ -349,6 +363,7 @@ def process_pending(
         state.mark_reviewing(node.sha)
         if on_update:
             on_update(state)
+        _report_node(project_root, node)
         intent = intent_for(node.sha) if intent_for else None
         outcome = runner.run(
             sha=node.sha,
@@ -361,6 +376,7 @@ def process_pending(
         reviewed += 1
         if on_update:
             on_update(state)
+        _report_node(project_root, node)
     # docs/43 Phase 1: fold current refactor-branch data into reviewed nodes so
     # their phase (review/finalize/done) reflects any branch built by `[r]`.
     refresh_finalize(project_root, state)
@@ -765,6 +781,7 @@ def watch(
 
     project_root = _resolve_repo(Path.cwd())
     _ensure_auth_in_window(json_output)
+    _report_heartbeat(project_root)
 
     state = WatchState(repo_name=project_root.name)
     try:
@@ -814,6 +831,23 @@ def _open_watch_window(
     console.print("[dim]watch: closed (the commit hook/queue are unaffected).[/dim]")
 
 
+def _report_heartbeat(project_root: Path) -> None:
+    """Best-effort opt-in watch liveness ping (docs/44 Phase 3). Never raises."""
+    try:
+        import socket
+
+        from refactorai_cli import commit_telemetry
+
+        branch = ""
+        try:
+            branch = git_scope.current_branch(project_root) or ""
+        except Exception:
+            branch = ""
+        commit_telemetry.post_heartbeat(project_root, host=socket.gethostname(), branch=branch)
+    except Exception:
+        pass
+
+
 def _load_watch_config(project_root: Path) -> dict:
     """Best-effort project-config settings dict (never raises)."""
     try:

refactorai_cli-0.5.0/refactorai_cli/commit_telemetry.py

@@ -0,0 +1,196 @@
+"""Commit-loop telemetry: build + post commit events to the platform (docs/44 Phase 3).
+
+The local loop is authoritative and offline-first (docs/41 Part G): telemetry is
+strictly opt-in and *fail-open*. Every function here swallows errors and returns a
+falsey result rather than raising, so a network hiccup, missing key, or unbound
+repo can never delay or break a commit / review / push.
+
+Telemetry only activates when the repo is bound to a platform project — resolved
+from ``REFACTOR_PROJECT_ID`` or a ``project_id`` setting in ``refactor.config`` —
+and can be turned off entirely with ``REFACTOR_NO_TELEMETRY=1``.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import httpx
+
+from refactorai_cli import __version__
+from refactorai_cli.settings import platform_url
+
+ENV_PROJECT_ID = "REFACTOR_PROJECT_ID"
+ENV_DISABLE = "REFACTOR_NO_TELEMETRY"
+WATCH_VERSION = __version__
+
+_TRUTHY = {"1", "true", "yes", "on"}
+
+# Local watch-node states -> server commit-event states.
+_STATE_MAP = {
+    "queued": "queued",
+    "reviewing": "reviewing",
+    "reviewed": "reviewed",
+    "resolved": "resolved",
+    "pushed": "pushed",
+    "error": "error",
+}
+# Local gate labels -> server gate_status enum.
+_GATE_MAP = {
+    "": "unknown",
+    "unknown": "unknown",
+    "passed": "passed",
+    "pass": "passed",
+    "warn": "warn",
+    "warning": "warn",
+    "high": "high",
+    "blocked": "high",
+}
+
+
+def telemetry_disabled() -> bool:
+    return str(os.environ.get(ENV_DISABLE, "")).strip().lower() in _TRUTHY
+
+
+def _load_settings(project_root: Path | str) -> dict:
+    """Best-effort project-config settings dict (never raises)."""
+    try:
+        from refactor_core.constitution import (
+            CONFIG_FILENAME,
+            find_project_files,
+            load_config,
+        )
+
+        consti_path, _ = find_project_files(Path(project_root))
+        if consti_path is None:
+            return {}
+        cfg = load_config(consti_path.parent / CONFIG_FILENAME)
+        return dict(getattr(cfg, "settings", {}) or {})
+    except Exception:
+        return {}
+
+
+def resolve_project_id(project_root: Path | str, config: dict | None = None) -> str:
+    """Resolve the bound platform project id, or ``""`` when unbound."""
+    env_pid = os.environ.get(ENV_PROJECT_ID, "").strip()
+    if env_pid:
+        return env_pid
+    settings = config if isinstance(config, dict) else _load_settings(project_root)
+    value = settings.get("project_id") if isinstance(settings, dict) else None
+    return str(value).strip() if value else ""
+
+
+def build_commit_event(node_contract: dict, *, source: str = "local_commit") -> dict:
+    """Map a watch node contract (``watch_state.to_contract``) to the ingest body."""
+    nc = node_contract or {}
+    scope = nc.get("scope") or {}
+    gate = nc.get("gate") or {}
+    state = _STATE_MAP.get(str(nc.get("state") or "").strip().lower(), "reviewed")
+    gate_status = _GATE_MAP.get(str(gate.get("status") or "").strip().lower(), "unknown")
+    return {
+        "sha": str(nc.get("sha") or ""),
+        "branch": str(nc.get("branch") or ""),
+        "subject": str(nc.get("subject") or ""),
+        "intent_summary": str(nc.get("intent_summary") or ""),
+        "state": state,
+        "gate_status": gate_status,
+        "high_findings": int(gate.get("high_findings") or 0),
+        "refactor_request_count": int(nc.get("refactor_requests") or 0),
+        "changed_files": int(scope.get("changed") or 0),
+        "associated_files": int(scope.get("associated") or 0),
+        "push_eligible": bool(nc.get("push_eligible", False)),
+        "source": source,
+    }
+
+
+def build_commit_event_from_queue(event: dict) -> dict:
+    """Map a raw commit-queue event (post-commit hook) to a ``queued`` ingest body."""
+    ev = event or {}
+    changed = ev.get("changed_files")
+    if isinstance(changed, list):
+        changed_count = len(changed)
+    else:
+        try:
+            changed_count = int(changed or 0)
+        except (TypeError, ValueError):
+            changed_count = 0
+    return {
+        "sha": str(ev.get("sha") or ""),
+        "branch": str(ev.get("branch") or ""),
+        "subject": str(ev.get("subject") or ""),
+        "intent_summary": "",
+        "state": "queued",
+        "gate_status": "unknown",
+        "high_findings": 0,
+        "refactor_request_count": 0,
+        "changed_files": changed_count,
+        "associated_files": 0,
+        "push_eligible": False,
+        "source": str(ev.get("trigger_source") or "local_commit"),
+    }
+
+
+def _auth_and_project(project_root: Path | str, config: dict | None) -> tuple[object | None, str]:
+    if telemetry_disabled():
+        return None, ""
+    project_id = resolve_project_id(project_root, config)
+    if not project_id:
+        return None, ""
+    try:
+        from refactorai_cli.auth import ensure_authenticated
+
+        auth = ensure_authenticated(Path(project_root))
+    except Exception:
+        return None, ""
+    return auth, project_id
+
+
+def _post(url: str, key: str, body: dict, timeout: float) -> bool:
+    try:
+        resp = httpx.post(
+            url,
+            headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
+            json=body,
+            timeout=timeout,
+        )
+        return resp.status_code < 400
+    except Exception:
+        return False
+
+
+def post_commit_event(
+    project_root: Path | str, body: dict, *, config: dict | None = None, timeout: float = 8.0
+) -> bool:
+    """Upsert one commit event. Best-effort + fail-open (returns success flag)."""
+    auth, project_id = _auth_and_project(project_root, config)
+    if not auth or not project_id:
+        return False
+    url = f"{platform_url()}/v1/projects/{project_id}/commit-events"
+    return _post(url, auth.key.key, body, timeout)
+
+
+def post_heartbeat(
+    project_root: Path | str,
+    *,
+    host: str = "",
+    branch: str = "",
+    watch_version: str = WATCH_VERSION,
+    config: dict | None = None,
+    timeout: float = 8.0,
+) -> bool:
+    """Report a ``refactor watch`` liveness ping. Best-effort + fail-open."""
+    auth, project_id = _auth_and_project(project_root, config)
+    if not auth or not project_id:
+        return False
+    url = f"{platform_url()}/v1/projects/{project_id}/watch/heartbeat"
+    body = {"host": host, "branch": branch, "watch_version": watch_version}
+    return _post(url, auth.key.key, body, timeout)
+
+
+def emit_node(project_root: Path | str, node, *, config: dict | None = None) -> bool:
+    """Build + post a commit event from a watch ``CommitNode``. Never raises."""
+    try:
+        body = build_commit_event(node.to_contract())
+        return post_commit_event(project_root, body, config=config)
+    except Exception:
+        return False

{refactorai_cli-0.4.16 → refactorai_cli-0.5.0}/refactorai_cli/main.py

@@ -16,6 +16,7 @@ from refactorai_cli.commands import (
     engine_cmds,
     hook_cmds,
     model_cmds,
+    pre_push_cmds,
     request_cmds,
     runtime_cmds,
     runtime_proxy_cmds,
@@ -155,6 +156,11 @@ app.add_typer(toolchains_cmds.app, name="toolchains")
 # Local commit-triggered review hook (R28 Phase 2, docs/41).
 app.add_typer(hook_cmds.app, name="hook")
 
+# Pre-push quality gate (docs/44 Phase 2); invoked by the git pre-push hook.
+app.command("pre-push", context_settings={"ignore_unknown_options": True, "allow_extra_args": True})(
+    pre_push_cmds.pre_push
+)
+
 # Persistent Refactor Terminal (R28 Phase 3, docs/41).
 app.add_typer(watch_cmds.watch_app, name="watch")
 

refactorai_cli-0.5.0/refactorai_cli/pre_push_gate.py

@@ -0,0 +1,112 @@
+"""Pure pre-push gate evaluation (docs/44 Phase 2).
+
+Dependency-free so it is trivially unit-testable and safe to import from the
+``refactor pre-push`` command. The command layer supplies the observed counts
+(pending refactor requests, high-severity count, doctor status) and the resolved
+policy; this module decides whether the push is allowed and why.
+
+Modes:
+- ``off``    — never inspect; always allow.
+- ``warn``   — surface blockers but always allow the push (never exit non-zero).
+- ``strict`` — block the push when a selected condition is unmet, unless the
+  developer uses the escape hatch (``REFACTOR_SKIP``) and policy permits it.
+
+The gate is fail-open by contract: the *command* wraps evaluation in a
+try/except and allows the push on any unexpected error. This module only encodes
+the policy decision for well-formed inputs.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+VALID_MODES = ("off", "warn", "strict")
+
+DEFAULT_POLICY: dict = {
+    "mode": "warn",
+    "block_on": ["high_severity", "unresolved_requests"],
+    "allow_skip": True,
+    "require_skip_reason": False,
+    "audit_skips": True,
+}
+
+
+@dataclass
+class GateDecision:
+    allow: bool
+    mode: str
+    reasons: list[str] = field(default_factory=list)
+    skipped: bool = False
+    skip_reason: str = ""
+
+
+def _normalize_mode(policy: dict) -> str:
+    mode = str((policy or {}).get("mode") or "warn").strip().lower()
+    return mode if mode in VALID_MODES else "warn"
+
+
+def blocking_reasons(
+    policy: dict,
+    *,
+    open_requests: int,
+    high_severity_open: int,
+    doctor_failed: bool = False,
+) -> list[str]:
+    """Reasons the push would be gated, independent of mode/escape-hatch."""
+    block_on = set((policy or {}).get("block_on") or [])
+    reasons: list[str] = []
+    if "high_severity" in block_on and high_severity_open > 0:
+        reasons.append(
+            f"{high_severity_open} high-severity refactor request(s) still open"
+        )
+    if "unresolved_requests" in block_on and open_requests > 0:
+        reasons.append(f"{open_requests} unresolved refactor request(s)")
+    if "failed_doctor" in block_on and doctor_failed:
+        reasons.append("engine doctor check is failing")
+    return reasons
+
+
+def evaluate(
+    policy: dict,
+    *,
+    open_requests: int,
+    high_severity_open: int,
+    doctor_failed: bool = False,
+    skip_requested: bool = False,
+    skip_reason: str = "",
+) -> GateDecision:
+    """Decide whether a push is allowed under ``policy``."""
+    mode = _normalize_mode(policy)
+    reasons = blocking_reasons(
+        policy,
+        open_requests=open_requests,
+        high_severity_open=high_severity_open,
+        doctor_failed=doctor_failed,
+    )
+
+    if mode == "off" or not reasons:
+        return GateDecision(allow=True, mode=mode, reasons=[])
+
+    if mode == "warn":
+        # Surface the blockers but never stop the push.
+        return GateDecision(allow=True, mode=mode, reasons=reasons)
+
+    # strict
+    allow_skip = bool((policy or {}).get("allow_skip", True))
+    require_reason = bool((policy or {}).get("require_skip_reason", False))
+    if skip_requested and allow_skip:
+        if require_reason and not str(skip_reason or "").strip():
+            return GateDecision(
+                allow=False,
+                mode=mode,
+                reasons=reasons + ["bypass requires a reason (set REFACTOR_SKIP_REASON)"],
+            )
+        return GateDecision(
+            allow=True,
+            mode=mode,
+            reasons=reasons,
+            skipped=True,
+            skip_reason=str(skip_reason or "").strip(),
+        )
+
+    return GateDecision(allow=False, mode=mode, reasons=reasons)

{refactorai_cli-0.4.16 → refactorai_cli-0.5.0}/refactorai_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: refactorai-cli
-Version: 0.4.16
+Version: 0.5.0
 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.9
+Requires-Dist: refactorai-core>=3.2.11
 
 # refactorai-cli
 

{refactorai_cli-0.4.16 → refactorai_cli-0.5.0}/refactorai_cli.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ refactorai_cli/auth.py
 refactorai_cli/client.py
 refactorai_cli/cloud_rr.py
 refactorai_cli/commit_queue.py
+refactorai_cli/commit_telemetry.py
 refactorai_cli/control_plane.py
 refactorai_cli/credentials.py
 refactorai_cli/dotenv_loader.py
@@ -14,6 +15,7 @@ refactorai_cli/local_engine_runtime.py
 refactorai_cli/local_paths.py
 refactorai_cli/main.py
 refactorai_cli/model_policy.py
+refactorai_cli/pre_push_gate.py
 refactorai_cli/refactor_branch_store.py
 refactorai_cli/review_runner.py
 refactorai_cli/runtime_manager.py
@@ -35,6 +37,7 @@ refactorai_cli/commands/cloud_cmds.py
 refactorai_cli/commands/engine_cmds.py
 refactorai_cli/commands/hook_cmds.py
 refactorai_cli/commands/model_cmds.py
+refactorai_cli/commands/pre_push_cmds.py
 refactorai_cli/commands/request_cmds.py
 refactorai_cli/commands/rules_cmds.py
 refactorai_cli/commands/run_cmds.py

{refactorai_cli-0.4.16 → refactorai_cli-0.5.0}/refactorai_cli.egg-info/requires.txt

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