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

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

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

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

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

{refactorai_cli-0.4.12 → refactorai_cli-0.4.16}/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.12"
+__version__ = "0.4.16"

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

@@ -16,7 +16,7 @@ from pathlib import Path
 import typer
 from rich.console import Console
 
-from refactorai_cli import commit_queue, git_scope
+from refactorai_cli import commit_queue, git_scope, watch_supervisor
 
 console = Console()
 app = typer.Typer(
@@ -137,7 +137,9 @@ def install(
         f"[green]Installed[/green] post-commit hook -> {result['hook_file']}\n"
         f"[dim]core.hooksPath = {result['rel_dir']}[/dim]\n"
         "Every commit now enqueues a local review event. "
-        "Open the Refactor Terminal with `refactor watch`."
+        "Open the Refactor Terminal with `refactor watch`.\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]"
     )
 
 
@@ -195,6 +197,42 @@ def enqueue(
         else:
             console.print(f"[dim]hook: not enqueued ({reason}).[/dim]")
 
+    # Opt-in auto-open: mirror how a dev server opens its own terminal. Best-effort
+    # and fail-open so it never affects the commit flow (docs/42 `R29`, Phase 4).
+    if enqueued:
+        _maybe_auto_open(project_root, verbose)
+
+
+def _watch_settings(project_root: Path) -> 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(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 _maybe_auto_open(project_root: Path, verbose: bool) -> None:
+    try:
+        config = _watch_settings(project_root)
+        if not watch_supervisor.auto_open_enabled(config):
+            return
+        result = watch_supervisor.ensure_watch_open(project_root, config=config)
+        if verbose:
+            console.print(f"[dim]hook: watch ensure -> {result.get('action')}.[/dim]")
+    except Exception as exc:  # fail-open
+        if verbose:
+            console.print(f"[yellow]hook: auto-open skipped ({exc}).[/yellow]")
+
 
 @app.command("status")
 def status() -> None:

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

@@ -64,11 +64,13 @@ from refactor_core.refactor_requests import (
     DEFERRED,
     RequestSuppression,
     RequestWarning,
+    clear_open_requests,
     clear_requests,
     create_requests,
     list_requests,
     load_request,
     pending_requests,
+    pending_requests_for_paths,
     save_request,
 )
 from refactor_core.refactor_ops import remediation_hint
@@ -651,6 +653,26 @@ def _is_cloud_mode(constitution) -> bool:
     return bool(_cloud_execution_mode(constitution))
 
 
+def _documents_digest(documents: list | None) -> str:
+    """Stable digest of the exact documents sent to the platform.
+
+    Folds each document's path + content so a commit-scoped review keys on the
+    code it actually reviews. Without this, two commits share the same
+    idempotency key (same account/stage/constitution/target) and the server
+    replays the FIRST commit's findings for the second commit -- re-suggesting
+    changes that were already applied/merged (docs/41 `R28`).
+    """
+    hasher = hashlib.sha256()
+    for doc in sorted(documents or [], key=lambda d: str((d or {}).get("path", ""))):
+        if not isinstance(doc, dict):
+            continue
+        hasher.update(str(doc.get("path", "")).encode("utf-8"))
+        hasher.update(b"\x00")
+        hasher.update(str(doc.get("content", "")).encode("utf-8"))
+        hasher.update(b"\x1f")
+    return hasher.hexdigest()
+
+
 def _stable_idempotency_key(
     *,
     account_id: str,
@@ -659,15 +681,29 @@ def _stable_idempotency_key(
     target: str,
     max_alerts: int,
     execution_mode: str,
+    scope_digest: str = "",
 ) -> str:
     """Deterministic idempotency key so retries replay instead of re-charging (C10).
 
-    The key MUST change when inputs change (target/constitution/stage/mode) so
-    distinct runs are not incorrectly deduplicated, and MUST be stable across
+    The key MUST change when inputs change (target/constitution/stage/mode/scope)
+    so distinct runs are not incorrectly deduplicated, and MUST be stable across
     retries of the same logical run so managed quota is not double-charged.
+
+    ``scope_digest`` folds the actual reviewed documents into the key so a
+    commit-scoped review of a different commit (or of changed code) produces a
+    distinct key and a fresh server run, instead of replaying an earlier commit's
+    cached findings.
     """
     seed = "|".join(
-        [account_id, execution_mode, stage, constitution_hash, str(target), str(int(max_alerts))]
+        [
+            account_id,
+            execution_mode,
+            stage,
+            constitution_hash,
+            str(target),
+            str(int(max_alerts)),
+            scope_digest,
+        ]
     )
     return hashlib.sha256(seed.encode("utf-8")).hexdigest()
 
@@ -707,6 +743,10 @@ def _cloud_inference(
 
     execution_mode = _cloud_execution_mode(constitution) or "cloud_managed"
     auth_ctx = ensure_authenticated(project_root)
+    # Digest the exact documents so the idempotency key keys on the reviewed
+    # code, not just account/stage/target. (The backend independently recomputes
+    # a documents hash for its own replay guard, so this need not be sent.)
+    documents_hash = _documents_digest(documents)
     payload = {
         "stage": stage,
         "execution_mode": execution_mode,
@@ -728,6 +768,7 @@ def _cloud_inference(
         target=target,
         max_alerts=max_alerts,
         execution_mode=execution_mode,
+        scope_digest=documents_hash,
     )
     try:
         response = httpx.post(
@@ -2725,6 +2766,8 @@ def review(
         compliance_canary_percent=compliance_canary_pct,
         compliance_resolution=compliance_resolution,
         artifact=artifact,
+        scope_paths=scope_paths,
+        scoped_replace=True,
     )
     _apply_compliance_gate_to_artifact(artifact)
     _apply_merge_contract_to_artifact(artifact, project_root, project_config)
@@ -2959,7 +3002,20 @@ def code(
     # *creating* a large request set; when we are resolving an existing pending
     # queue (the common `[r]` resume case) there is nothing to confirm, so a root
     # commit no longer re-prompts every run (docs/42 `R29`, Part L).
-    reused_requests = [] if (code_scope and refresh_requests) else pending_requests(project_root)
+    #
+    # Reuse is *commit-scoped*: a change-scoped `code --commit`/`[r]` only resumes
+    # pending RRs whose file lives in THIS commit's scope, so a leftover pending RR
+    # from an unrelated commit can never bleed into this commit's resolution
+    # (docs/41 `R28`, Phase 1). A full-project scope (root commit) has no path
+    # restriction, so it resumes the whole pending queue as before.
+    if code_scope and refresh_requests:
+        reused_requests = []
+    elif code_scope and code_scope.get("scope_paths") is not None:
+        reused_requests = pending_requests_for_paths(
+            project_root, code_scope.get("scope_paths")
+        )
+    else:
+        reused_requests = pending_requests(project_root)
     will_generate_requests = bool(refresh_requests) or not reused_requests
     if will_generate_requests:
         _confirm_full_project_scope(code_scope, command="code", assume_yes=yes_full_project)
@@ -3115,6 +3171,8 @@ def code(
                 compliance_canary_percent=compliance_canary_pct,
                 compliance_resolution=compliance_resolution,
                 artifact=review_artifact,
+                scope_paths=code_scope_paths,
+                scoped_replace=True,
             )
             _apply_compliance_gate_to_artifact(review_artifact)
             _apply_merge_contract_to_artifact(review_artifact, project_root, project_config)
@@ -3667,8 +3725,19 @@ def _replace_requests_with_framework_guardrails(
     compliance_canary_percent: int = 20,
     compliance_resolution: CompliancePackResolution | None = None,
     artifact: RunArtifact | None = None,
+    scope_paths: list[str] | None = None,
+    scoped_replace: bool = False,
 ) -> list:
-    clear_requests(project_root)
+    # A fresh review supersedes the OPEN requests it re-derives, but must preserve
+    # terminal (applied/denied/failed/...) history so an already-resolved finding is
+    # not re-suggested on a later commit (docs/42 `R29`, Phase 2). A commit-scoped
+    # review clears only its own scope's open queue; a full-project review clears all
+    # open requests. ``scoped_replace`` opts into this history-preserving path so
+    # callers that still want a total reset can pass ``scoped_replace=False``.
+    if scoped_replace:
+        clear_open_requests(project_root, scope_paths)
+    else:
+        clear_requests(project_root)
     requests, suppressions, warnings = create_requests(
         project_root,
         findings,

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

@@ -25,7 +25,13 @@ from typing import Callable
 import typer
 from rich.console import Console
 
-from refactorai_cli import commit_queue, git_scope, refactor_branch_store, watch_state
+from refactorai_cli import (
+    commit_queue,
+    git_scope,
+    refactor_branch_store,
+    watch_state,
+    watch_supervisor,
+)
 from refactorai_cli.auth import AuthError, ensure_authenticated
 from refactorai_cli.review_runner import ReviewRunner, SubprocessReviewRunner
 from refactorai_cli.watch_state import (
@@ -638,9 +644,38 @@ def _dispatch_key(live, project_root: Path, key: str, state: WatchState) -> None
                 _run_action(live, project_root, "diff", node, state)
             return
         if not can_review:
+            preferred = next(
+                (
+                    n
+                    for n in state.nodes_newest_first()
+                    if n.state == watch_state.REVIEWED
+                    and (n.phase == watch_state.PHASE_REVIEW or n.sha in state.forced_review)
+                    and n.rr_count > 0
+                ),
+                None,
+            )
+            fallback = preferred or next(
+                (
+                    n
+                    for n in state.nodes_newest_first()
+                    if n.state == watch_state.REVIEWED
+                    and (n.phase == watch_state.PHASE_REVIEW or n.sha in state.forced_review)
+                ),
+                None,
+            )
+            if fallback is not None and fallback.sha != node.sha:
+                state.selected_sha = fallback.sha
+                console.print(
+                    f"[dim]watch: selected {node.short_sha} ({node.branch or 'detached'} / "
+                    f"{node.phase}, requests={node.rr_count}) is not reviewable; moved "
+                    f"selection to {fallback.short_sha} (requests={fallback.rr_count}). "
+                    f"Press [{key}] again.[/dim]"
+                )
+                return
             console.print(
-                f"[dim]watch: nothing to review on {node.short_sha} "
-                f"(phase: {node.phase}).[/dim]"
+                f"[dim]watch: selected {node.short_sha} ({node.branch or 'detached'} / "
+                f"phase={node.phase}, requests={node.rr_count}) has nothing to "
+                "review. Use [↑/↓] to select a commit with open requests.[/dim]"
             )
             return
         if node.state == watch_state.REVIEWED:
@@ -695,7 +730,17 @@ def _run_tui(project_root: Path, state: WatchState, runner: ReviewRunner) -> Non
         live.stop()
 
 
+watch_app = typer.Typer(
+    name="watch",
+    help="Open the persistent Refactor Terminal (docs/41). Requires a valid key.",
+    invoke_without_command=True,
+    add_completion=False,
+)
+
+
+@watch_app.callback(invoke_without_command=True)
 def watch(
+    ctx: typer.Context,
     json_output: bool = typer.Option(
         False,
         "--json",
@@ -714,6 +759,10 @@ def watch(
     ),
 ) -> None:
     """Open the persistent Refactor Terminal (docs/41). Requires a valid key."""
+    # A subcommand (e.g. `watch ensure`) was invoked -> let it run instead.
+    if ctx.invoked_subcommand is not None:
+        return
+
     project_root = _resolve_repo(Path.cwd())
     _ensure_auth_in_window(json_output)
 
@@ -743,8 +792,95 @@ def watch(
         console.print(f"[dim]watch: reviewed {reviewed} commit(s).[/dim]")
         return
 
+    _open_watch_window(project_root, state, runner)
+
+
+def _open_watch_window(
+    project_root: Path, state: WatchState, runner: ReviewRunner
+) -> None:
+    """Run the interactive TUI while holding the single-instance lock.
+
+    The lock lets ``watch ensure`` (auto-open) detect an already-open window for
+    this repo and never spawn a duplicate (docs/42 Phase 4).
+    """
+    my_pid = os.getpid()
+    watch_supervisor.write_lock(project_root, my_pid)
     try:
         _run_tui(project_root, state, runner)
     except KeyboardInterrupt:
         pass
+    finally:
+        watch_supervisor.release_lock(project_root, pid=my_pid)
     console.print("[dim]watch: closed (the commit hook/queue are unaffected).[/dim]")
+
+
+def _load_watch_config(project_root: Path) -> 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(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 {}
+
+
+@watch_app.command("ensure")
+def ensure(
+    force: bool = typer.Option(
+        False, "--force", help="Open even if auto-open is disabled in config/env."
+    ),
+    foreground: bool = typer.Option(
+        False,
+        "--foreground",
+        "-f",
+        help="Run the Refactor Terminal inline instead of spawning a new window.",
+    ),
+) -> None:
+    """Open the Refactor Terminal if enabled and not already running (auto-open).
+
+    Invoked by the ``post-commit`` hook when auto-open is on, mirroring how a dev
+    server opens its own terminal. Fail-open and idempotent: a single-instance lock
+    prevents duplicate windows.
+    """
+    project_root = _resolve_repo(Path.cwd())
+
+    if foreground:
+        if watch_supervisor.is_watch_running(project_root) and not force:
+            console.print("[dim]watch: a Refactor Terminal is already open.[/dim]")
+            return
+        _ensure_auth_in_window(False)
+        state = WatchState(repo_name=project_root.name)
+        try:
+            state.current_branch = git_scope.current_branch(project_root) or ""
+        except Exception:
+            state.current_branch = ""
+        for event in _load_initial_events(project_root, None, 20):
+            sha = str(event.get("sha") or "")
+            if sha and not state.has(sha):
+                state.upsert_from_event(event)
+        runner: ReviewRunner = SubprocessReviewRunner(project_root)
+        _open_watch_window(project_root, state, runner)
+        return
+
+    config = _load_watch_config(project_root)
+    result = watch_supervisor.ensure_watch_open(
+        project_root, config=config, force=force
+    )
+    action = result.get("action")
+    message = result.get("message", "")
+    if action == "launched":
+        console.print(f"[green]watch:[/green] {message}")
+    elif action in ("already_running", "disabled"):
+        console.print(f"[dim]watch: {message}.[/dim]")
+    elif action == "no_launcher":
+        console.print(f"[yellow]watch:[/yellow] {message}.")
+    else:  # launch_failed / unknown
+        console.print(f"[yellow]watch: {message}.[/yellow]")

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

@@ -156,7 +156,7 @@ app.add_typer(toolchains_cmds.app, name="toolchains")
 app.add_typer(hook_cmds.app, name="hook")
 
 # Persistent Refactor Terminal (R28 Phase 3, docs/41).
-app.command()(watch_cmds.watch)
+app.add_typer(watch_cmds.watch_app, name="watch")
 
 # Local refactor branch + per-request commits (R29 Phase 3, docs/42).
 app.add_typer(branch_cmds.app, name="branch")

{refactorai_cli-0.4.12 → refactorai_cli-0.4.16}/refactorai_cli/watch_state.py

@@ -447,8 +447,9 @@ def _render_review_view(state: WatchState, *, now: datetime | None = None, width
         age = humanize_age(node.enqueued_at, now=now)
         gate = _gate_markup(node)
         selected = node.sha == state.selected_sha
+        node_lines: list[Text] = []
         # Row 1: node marker + branch + age (+ gate, right aligned). The selected
-        # node gets a filled marker and bold branch so `[r]`/`[d]` targeting is clear.
+        # node gets a filled marker + a visual box so `[r]` targets are explicit.
         if selected:
             left = Text.from_markup(
                 f"[bold bright_cyan]●[/bold bright_cyan]  [bold bright_cyan]{node.branch or '(detached)'}[/bold bright_cyan]"
@@ -461,25 +462,25 @@ def _render_review_view(state: WatchState, *, now: datetime | None = None, width
             pad = max(1, inner_width - len(left.plain) - len(gate_text.plain))
             left.append(" " * pad)
             left.append_text(gate_text)
-        lines.append(_with_pad(left))
+        node_lines.append(left)
         # Row 2: pipe + sha + subject.
         row2 = Text.from_markup(f"[cyan]|[/cyan]    [yellow]{node.short_sha}[/yellow]  ")
         row2.append(node.subject or "(no subject)")
-        lines.append(_with_pad(row2))
+        node_lines.append(row2)
         # Row 3: pipe + status.
         row3 = Text.from_markup("[cyan]|[/cyan]    ")
         row3.append_text(Text.from_markup(_status_line(node)))
-        lines.append(_with_pad(row3))
+        node_lines.append(row3)
         if node.state == REVIEWED and node.rr_preview:
             for item in node.rr_preview:
                 req = Text.from_markup("[cyan]|[/cyan]      ")
                 req.append(f"- {item}", style="magenta")
-                lines.append(_with_pad(req))
+                node_lines.append(req)
         # Row 4: intent summary (only once reviewed and present).
         if node.state in (REVIEWED,) and node.intent_summary:
             intent = Text.from_markup("[cyan]|[/cyan]    ")
             intent.append_text(Text.from_markup(f"[dim]intent: {node.intent_summary}[/dim]"))
-            lines.append(_with_pad(intent))
+            node_lines.append(intent)
         # Once a commit is resolved onto a live refactor branch, hint the finalize
         # view rather than the (now empty) review actions (docs/43 Part D).
         if node.phase == PHASE_FINALIZE and node.finalize is not None:
@@ -489,7 +490,7 @@ def _render_review_view(state: WatchState, *, now: datetime | None = None, width
                 "-> select + press [m] to finalize",
                 style="green",
             )
-            lines.append(_with_pad(hint))
+            node_lines.append(hint)
         elif node.phase == PHASE_DONE and node.finalize is not None:
             done = Text.from_markup("[cyan]|[/cyan]    ")
             if node.finalize.outcome == "merged":
@@ -500,10 +501,36 @@ def _render_review_view(state: WatchState, *, now: datetime | None = None, width
                 done.append("refactor branch dropped", style="dim")
             else:
                 done.append("refactor branch finalized", style="dim")
-            lines.append(_with_pad(done))
-        lines.append(_with_pad(Text.from_markup("[cyan]|[/cyan]")))
+            node_lines.append(done)
+        node_lines.append(Text.from_markup("[cyan]|[/cyan]"))
+
+        if selected and node_lines:
+            # Strong visual target: render the selected commit in a distinct box so
+            # `[r]`/`[f]` actions are unambiguous in long commit stacks.
+            for idx, row in enumerate(node_lines):
+                if idx == 0:
+                    glyph = "┏ "
+                elif idx == len(node_lines) - 1:
+                    glyph = "┗ "
+                else:
+                    glyph = "┃ "
+                wrapped = Text(glyph, style="bold bright_cyan")
+                wrapped.append_text(row)
+                lines.append(_with_pad(wrapped))
+        else:
+            for row in node_lines:
+                lines.append(_with_pad(row))
     lines.append(_with_pad(Text.from_markup("[cyan]+[/cyan]")))
     lines.append(_with_pad(Text("")))
+    selected = state.selected()
+    if selected is not None:
+        context = Text.from_markup("[bold bright_cyan]selected[/bold bright_cyan]: ")
+        context.append(selected.short_sha, style="yellow")
+        context.append(f"  {selected.subject or '(no subject)'}", style="dim")
+        context.append(f"  phase={selected.phase}", style="dim")
+        context.append(f"  requests={selected.rr_count}", style="dim")
+        lines.append(_with_pad(context))
+        lines.append(_with_pad(Text("")))
     lines.append(
         _with_pad(
             Text.from_markup(

refactorai_cli-0.4.16/refactorai_cli/watch_supervisor.py

@@ -0,0 +1,234 @@
+"""Auto-open supervisor for the Refactor Terminal (docs/42 `R29`, Phase 4).
+
+Opt-in: after a commit is enqueued, the ``post-commit`` hook can call
+``refactor watch ensure`` to open the Refactor Terminal in a new terminal window
+when one is not already running -- so review results appear automatically (like a
+Metro / dev-server window) instead of the developer having to remember to run
+``refactor watch``.
+
+Everything here is best-effort and fail-open: it must never delay or fail a commit.
+Auto-open is disabled unless the developer opts in, and opening a *new* window
+needs a configured terminal launcher (there is no reliable cross-platform default),
+so both are surfaced as an env var and a matching ``watch`` config key.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from refactorai_cli import commit_queue
+
+LOCK_FILENAME = "watch.lock"
+
+# Env knobs (project-config keys under a ``watch`` table mirror these names).
+ENV_AUTO_OPEN = "REFACTOR_WATCH_AUTO_OPEN"  # "1"/"true" to enable auto-open
+ENV_TERMINAL = "REFACTOR_WATCH_TERMINAL"  # launcher template, uses ``{cmd}``
+
+_TRUE_TOKENS = {"1", "true", "yes", "on"}
+# A freshly-launched window that has not yet written its own pid still counts as
+# "running" for this many seconds, so two commits in quick succession do not each
+# spawn a window before the first has come up.
+_LAUNCH_GRACE_SECONDS = 45
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _as_bool(value: object) -> bool:
+    return str(value).strip().lower() in _TRUE_TOKENS
+
+
+def lock_path(project_root: Path | str) -> Path:
+    """Per-repo lock file. Lives beside the commit queue (never tracked)."""
+    directory = commit_queue.runs_dir(project_root)
+    if directory is None:
+        # Outside a git dir (or tests): fall back to the central project store.
+        from refactorai_cli.local_paths import project_store_dir
+
+        directory = project_store_dir(project_root)
+    return Path(directory) / LOCK_FILENAME
+
+
+def _pid_alive(pid: int) -> bool:
+    if pid <= 0:
+        return False
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except OSError:
+        return False
+    return True
+
+
+def read_lock(project_root: Path | str) -> dict | None:
+    path = lock_path(project_root)
+    if not path.is_file():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def write_lock(project_root: Path | str, pid: int, *, launching: bool = False) -> None:
+    path = lock_path(project_root)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            json.dumps({"pid": int(pid), "launching": bool(launching), "at": _now_iso()}),
+            encoding="utf-8",
+        )
+    except OSError:
+        pass
+
+
+def release_lock(project_root: Path | str, *, pid: int | None = None) -> None:
+    """Remove the lock. If ``pid`` is given, only remove our own lock."""
+    data = read_lock(project_root)
+    if data is None:
+        return
+    if pid is not None and int(data.get("pid", 0) or 0) != int(pid):
+        return
+    try:
+        lock_path(project_root).unlink()
+    except OSError:
+        pass
+
+
+def _within_grace(data: dict) -> bool:
+    if not data.get("launching"):
+        return False
+    stamp = str(data.get("at", "") or "")
+    if not stamp:
+        return False
+    try:
+        started = datetime.strptime(stamp, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+    except ValueError:
+        return False
+    return (datetime.now(timezone.utc) - started).total_seconds() < _LAUNCH_GRACE_SECONDS
+
+
+def is_watch_running(project_root: Path | str) -> bool:
+    """True if a Refactor Terminal is (believed to be) open for this repo."""
+    data = read_lock(project_root)
+    if not data:
+        return False
+    if _pid_alive(int(data.get("pid", 0) or 0)):
+        return True
+    # A just-launched window may not have replaced the launch lock with its own pid
+    # yet; treat the launch marker as live for a short grace window.
+    return _within_grace(data)
+
+
+def _watch_config(config: dict | None) -> dict:
+    if not isinstance(config, dict):
+        return {}
+    watch = config.get("watch")
+    return watch if isinstance(watch, dict) else {}
+
+
+def auto_open_enabled(config: dict | None = None, env: dict | None = None) -> bool:
+    """Whether auto-open is enabled (env wins over config; default off)."""
+    env = os.environ if env is None else env
+    raw = env.get(ENV_AUTO_OPEN)
+    if raw is not None and str(raw).strip() != "":
+        return _as_bool(raw)
+    return bool(_watch_config(config).get("auto_open", False))
+
+
+def resolve_launcher(config: dict | None = None, env: dict | None = None) -> str | None:
+    """Terminal launcher template, or ``None`` if unconfigured.
+
+    The template opens a new terminal window running a command. ``{cmd}`` is
+    substituted with the (shell-quoted) ``refactor watch`` invocation; if absent the
+    command is appended. Examples::
+
+        gnome-terminal -- bash -lc {cmd}
+        xterm -e {cmd}
+        wt.exe {cmd}
+    """
+    env = os.environ if env is None else env
+    raw = env.get(ENV_TERMINAL)
+    if raw and str(raw).strip():
+        return str(raw).strip()
+    template = _watch_config(config).get("terminal")
+    return str(template).strip() if template and str(template).strip() else None
+
+
+def watch_command(executable: str = "refactor") -> list[str]:
+    """The inner command a launched window should run."""
+    return [executable, "watch"]
+
+
+def build_launch_command(template: str, inner_cmd: list[str]) -> list[str]:
+    """Render a launcher ``template`` + inner command into an argv list."""
+    inner = " ".join(shlex.quote(part) for part in inner_cmd)
+    rendered = template.replace("{cmd}", inner) if "{cmd}" in template else f"{template} {inner}"
+    return shlex.split(rendered)
+
+
+def spawn_detached(cmd: list[str], cwd: Path | str) -> int | None:
+    """Launch ``cmd`` fully detached from the current process. Returns its pid."""
+    try:
+        proc = subprocess.Popen(
+            cmd,
+            cwd=str(cwd),
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True,
+        )
+    except (OSError, ValueError):
+        return None
+    return proc.pid
+
+
+def ensure_watch_open(
+    project_root: Path | str,
+    *,
+    config: dict | None = None,
+    env: dict | None = None,
+    executable: str = "refactor",
+    force: bool = False,
+) -> dict:
+    """Open a Refactor Terminal if auto-open is enabled and none is running.
+
+    Pure-ish orchestration returning a result dict with ``action`` in
+    ``{disabled, already_running, no_launcher, launched, launch_failed}`` plus a
+    human ``message``. ``force`` bypasses the auto-open gate (used by an explicit
+    ``watch ensure --force``).
+    """
+    if not force and not auto_open_enabled(config, env):
+        return {"action": "disabled", "message": "auto-open is disabled"}
+    if is_watch_running(project_root):
+        return {"action": "already_running", "message": "Refactor Terminal already open"}
+
+    launcher = resolve_launcher(config, env)
+    if not launcher:
+        return {
+            "action": "no_launcher",
+            "message": (
+                f"set {ENV_TERMINAL} (or watch.terminal) to a terminal launcher "
+                "template to auto-open the Refactor Terminal"
+            ),
+        }
+
+    cmd = build_launch_command(launcher, watch_command(executable))
+    pid = spawn_detached(cmd, project_root)
+    if pid is None:
+        return {"action": "launch_failed", "message": f"could not launch: {' '.join(cmd)}"}
+    # Record a launch marker so a rapid second commit does not double-open before the
+    # window comes up and writes its own pid.
+    write_lock(project_root, pid, launching=True)
+    return {"action": "launched", "message": f"opened Refactor Terminal (pid {pid})", "pid": pid}

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

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

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

@@ -20,6 +20,7 @@ refactorai_cli/runtime_manager.py
 refactorai_cli/settings.py
 refactorai_cli/setup_flow.py
 refactorai_cli/watch_state.py
+refactorai_cli/watch_supervisor.py
 refactorai_cli.egg-info/PKG-INFO
 refactorai_cli.egg-info/SOURCES.txt
 refactorai_cli.egg-info/dependency_links.txt

{refactorai_cli-0.4.12 → refactorai_cli-0.4.16}/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.7
+refactorai-core>=3.2.9