refactor(#160) phase1: codex_refactor_loop Python package + codex_loop.py CLI(parity,不删 shell)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: loning

skills/codex-refactor-loop/scripts/codex_loop.py

@@ -0,0 +1,10 @@
+#!/usr/bin/env python3
+"""Stable controller-facing CLI for codex-refactor-loop."""
+
+from __future__ import annotations
+
+from codex_refactor_loop.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

skills/codex-refactor-loop/scripts/codex_refactor_loop/__init__.py

@@ -0,0 +1,2 @@
+"""Foundation primitives for the codex-refactor-loop controller."""
+

skills/codex-refactor-loop/scripts/codex_refactor_loop/cli.py

@@ -0,0 +1,83 @@
+"""Controller-facing command router for codex-refactor-loop."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Sequence
+
+
+SCRIPT_DIR = Path(__file__).resolve().parents[1]
+
+
+@dataclass(frozen=True)
+class CommandSpec:
+    script: str
+    description: str
+    read_only: bool = False
+
+
+COMMANDS: dict[str, CommandSpec] = {
+    "spawn-codex": CommandSpec("spawn-codex.sh", "run the existing codex spawn supervisor"),
+    "peek": CommandSpec("peek.sh", "run the existing read-only state sweep", read_only=True),
+    "restart-daemons": CommandSpec("restart-daemons.sh", "run the existing daemon restart helper"),
+    "statusline": CommandSpec("statusline.sh", "read the existing statusline snapshot", read_only=True),
+    "comment-monitor": CommandSpec("comment-monitor.sh", "run the existing comment monitor daemon"),
+    "progress-reporter": CommandSpec("codex-progress-reporter.sh", "run the existing progress reporter daemon"),
+    "merge-pr": CommandSpec("controller_lib.sh", "invoke controller_lib.sh merge_pr"),
+    "open-pr": CommandSpec("controller_lib.sh", "invoke controller_lib.sh open_pr_with_label"),
+}
+
+
+class RuntimeCommandRouter:
+    """Stable command-name router that delegates to current scripts."""
+
+    def __init__(self, script_dir: Path = SCRIPT_DIR) -> None:
+        self.script_dir = script_dir
+
+    def main(self, argv: Sequence[str] | None = None) -> int:
+        parser = argparse.ArgumentParser(
+            prog="codex_loop.py",
+            description="codex-refactor-loop controller command router",
+        )
+        parser.add_argument("command", nargs="?")
+        parser.add_argument("args", nargs=argparse.REMAINDER)
+        args = parser.parse_args(argv)
+        if not args.command:
+            parser.print_help()
+            return 0
+        return self.run(args.command, list(args.args))
+
+    def run(self, command: str, args: Sequence[str]) -> int:
+        spec = COMMANDS.get(command)
+        if spec is None:
+            sys.stderr.write(f"unknown command: {command}\n")
+            return 2
+        if command == "merge-pr":
+            return self._run_controller_lib("merge_pr", args)
+        if command == "open-pr":
+            return self._run_controller_lib("open_pr_with_label", args)
+        return self._exec_script(spec.script, args)
+
+    def _exec_script(self, script_name: str, args: Sequence[str]) -> int:
+        script = self.script_dir / script_name
+        cmd = ["bash", str(script), *args] if script.suffix == ".sh" else [sys.executable, str(script), *args]
+        return subprocess.call(cmd)
+
+    def _run_controller_lib(self, function_name: str, args: Sequence[str]) -> int:
+        quoted = " ".join(_shell_quote(arg) for arg in args)
+        call = f"{function_name} {quoted}".rstrip()
+        body = f"source {_shell_quote(str(self.script_dir / 'controller_lib.sh'))}; {call}"
+        return subprocess.call(["bash", "-c", body], env=os.environ.copy())
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    return RuntimeCommandRouter().main(argv)
+
+
+def _shell_quote(value: str) -> str:
+    return "'" + value.replace("'", "'\"'\"'") + "'"

skills/codex-refactor-loop/scripts/codex_refactor_loop/context.py

@@ -0,0 +1,223 @@
+"""Host context loading for codex-refactor-loop controller helpers."""
+
+from __future__ import annotations
+
+import os
+import re
+import shlex
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping
+
+
+class LoopContextError(RuntimeError):
+    """Raised when host context cannot be loaded safely."""
+
+
+_ASSIGNMENT_RE = re.compile(r"^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$")
+
+
+@dataclass(frozen=True)
+class LoopPaths:
+    """Stable host artifact paths used by the loop."""
+
+    refactor_loop: Path
+    logs: Path
+    prompts: Path
+    runs: Path
+    state: Path
+    dispatch_queue: Path
+    dispatch_dispatched: Path
+    dispatch_rejected: Path
+    heartbeats: Path
+    pending_events: Path
+    statusline_snapshot: Path
+    recent_pr_merges: Path
+
+
+@dataclass(frozen=True)
+class LoopContext:
+    """Resolved host repository and skill context."""
+
+    repo_root: Path
+    skill_root: Path
+    gh_repo_slug: str | None
+    paths: LoopPaths
+    host_env: dict[str, str]
+    read_only: bool = False
+    repo_root_source: str = "env"
+
+    @classmethod
+    def load(
+        cls,
+        *,
+        repo_root: str | Path | None = None,
+        skill_root: str | Path | None = None,
+        env: Mapping[str, str] | None = None,
+        read_only: bool = False,
+        allow_git_root_fallback: bool | None = None,
+        cwd: str | Path | None = None,
+    ) -> "LoopContext":
+        source_env = dict(os.environ if env is None else env)
+        resolved_skill_root = Path(skill_root or source_env.get("CODEX_REFACTOR_LOOP_SKILL_ROOT") or Path(__file__).resolve().parents[2]).resolve()
+        repo, repo_source = _resolve_repo_root(
+            explicit=repo_root,
+            env=source_env,
+            read_only=read_only,
+            allow_git_root_fallback=allow_git_root_fallback,
+            cwd=cwd,
+        )
+        host_env = _load_host_env(repo)
+        merged = {**host_env, **source_env}
+        if repo_source == "host.env":
+            merged["REPO_ROOT"] = str(repo)
+        elif "REPO_ROOT" in host_env:
+            _validate_repo_override(repo, host_env["REPO_ROOT"], "host.env")
+
+        slug = _github_repo_slug(merged)
+        paths = _paths(repo)
+        return cls(
+            repo_root=repo,
+            skill_root=resolved_skill_root,
+            gh_repo_slug=slug,
+            paths=paths,
+            host_env=host_env,
+            read_only=read_only,
+            repo_root_source=repo_source,
+        )
+
+    def env_for_subprocess(self) -> dict[str, str]:
+        result = dict(os.environ)
+        result.update(self.host_env)
+        result["REPO_ROOT"] = str(self.repo_root)
+        if self.gh_repo_slug:
+            result["GH_REPO_SLUG"] = self.gh_repo_slug
+        return result
+
+
+def _resolve_repo_root(
+    *,
+    explicit: str | Path | None,
+    env: Mapping[str, str],
+    read_only: bool,
+    allow_git_root_fallback: bool | None,
+    cwd: str | Path | None,
+) -> tuple[Path, str]:
+    if explicit:
+        return _existing_dir(explicit, "repo_root"), "arg"
+    env_root = env.get("REPO_ROOT")
+    if env_root:
+        return _existing_dir(env_root, "REPO_ROOT"), "env"
+    host_env_repo = _host_env_repo_root_from_cwd(cwd)
+    if host_env_repo is not None:
+        return host_env_repo, "host.env"
+    fallback_allowed = env.get("ALLOW_GIT_ROOT_FALLBACK") == "1" if allow_git_root_fallback is None else allow_git_root_fallback
+    if fallback_allowed:
+        if not read_only:
+            raise LoopContextError("ALLOW_GIT_ROOT_FALLBACK is only allowed for read-only commands")
+        root = _git_root(cwd)
+        if root:
+            return root, "git"
+    raise LoopContextError("REPO_ROOT is unset; source .refactor-loop/host.env or set ALLOW_GIT_ROOT_FALLBACK=1 for read-only use")
+
+
+def _host_env_repo_root_from_cwd(cwd: str | Path | None) -> Path | None:
+    base = Path(cwd or os.getcwd())
+    host_env = base / ".refactor-loop" / "host.env"
+    if not host_env.exists():
+        return None
+    values = parse_host_env(host_env)
+    raw_root = values.get("REPO_ROOT")
+    if raw_root:
+        return _existing_dir(raw_root, "host.env REPO_ROOT")
+    return base.resolve()
+
+
+def _existing_dir(value: str | Path, label: str) -> Path:
+    path = Path(value).expanduser().resolve()
+    if not path.is_dir():
+        raise LoopContextError(f"{label} is not a readable directory: {value}")
+    return path
+
+
+def _git_root(cwd: str | Path | None) -> Path | None:
+    result = subprocess.run(
+        ["git", "rev-parse", "--show-toplevel"],
+        cwd=str(cwd) if cwd else None,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        return None
+    raw = result.stdout.strip()
+    if not raw:
+        return None
+    return _existing_dir(raw, "git root")
+
+
+def _load_host_env(repo_root: Path) -> dict[str, str]:
+    for path in (repo_root / ".refactor-loop" / "host.env", repo_root / "host.env"):
+        if path.exists():
+            return parse_host_env(path)
+    return {}
+
+
+def parse_host_env(path: Path) -> dict[str, str]:
+    values: dict[str, str] = {}
+    for line in path.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        match = _ASSIGNMENT_RE.match(stripped)
+        if not match:
+            continue
+        key, raw_value = match.groups()
+        try:
+            parsed = shlex.split(raw_value, posix=True)
+        except ValueError as exc:
+            raise LoopContextError(f"invalid host.env assignment for {key}: {exc}") from exc
+        values[key] = parsed[0] if parsed else ""
+    return values
+
+
+def _validate_repo_override(repo_root: Path, raw_override: str, source: str) -> None:
+    override = Path(raw_override).expanduser().resolve()
+    if override != repo_root:
+        raise LoopContextError(f"{source} REPO_ROOT override points outside resolved repo root: {raw_override}")
+
+
+def _github_repo_slug(env: Mapping[str, str]) -> str | None:
+    slug = env.get("GH_REPO_SLUG")
+    if slug:
+        if "/" not in slug:
+            raise LoopContextError(f"GH_REPO_SLUG must be OWNER/REPO; got {slug!r}")
+        return slug
+    repo = env.get("GH_REPO")
+    if repo and "/" in repo:
+        return repo
+    owner = env.get("GH_OWNER")
+    name = env.get("GH_REPO_NAME") or repo
+    if owner and name:
+        return f"{owner}/{name}"
+    return None
+
+
+def _paths(repo_root: Path) -> LoopPaths:
+    refactor_loop = repo_root / ".refactor-loop"
+    state = refactor_loop / "state"
+    return LoopPaths(
+        refactor_loop=refactor_loop,
+        logs=refactor_loop / "logs",
+        prompts=refactor_loop / "prompts",
+        runs=refactor_loop / "runs",
+        state=state,
+        dispatch_queue=refactor_loop / "dispatch-queue",
+        dispatch_dispatched=refactor_loop / "dispatch-dispatched",
+        dispatch_rejected=refactor_loop / "dispatch-rejected",
+        heartbeats=refactor_loop / "heartbeats",
+        pending_events=refactor_loop / ".controller-pending-events.log",
+        statusline_snapshot=state / "statusline-snapshot.json",
+        recent_pr_merges=state / "recent-pr-merges.json",
+    )

skills/codex-refactor-loop/scripts/codex_refactor_loop/git.py

@@ -0,0 +1,47 @@
+"""Git subprocess primitives that preserve existing controller semantics."""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Sequence
+
+
+@dataclass(frozen=True)
+class Git:
+    repo_root: Path
+
+    def run(self, args: Sequence[str], *, check: bool = True) -> subprocess.CompletedProcess[str]:
+        result = subprocess.run(
+            ["git", "-C", str(self.repo_root), *args],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if check and result.returncode != 0:
+            raise RuntimeError(result.stderr.strip() or f"git {' '.join(args)} failed with exit {result.returncode}")
+        return result
+
+    def safe_worktree(self, iteration: str | int, cluster: str, base_ref: str) -> tuple[Path, str]:
+        wt_path = self.repo_root / ".worktrees" / f"iter{iteration}-{cluster}"
+        branch = f"refactor/iter{iteration}-{cluster}"
+        if wt_path.is_dir():
+            return wt_path, branch
+        (self.repo_root / ".worktrees").mkdir(parents=True, exist_ok=True)
+        if self.run(["show-ref", "--quiet", f"refs/heads/{branch}"], check=False).returncode == 0:
+            self.run(["worktree", "add", str(wt_path), branch])
+        else:
+            self.run(["worktree", "add", "-b", branch, str(wt_path), base_ref])
+        return wt_path, branch
+
+    def merge_ff_only(self, ref: str) -> subprocess.CompletedProcess[str]:
+        return self.run(["merge", "--ff-only", ref])
+
+    def push(self, remote: str, refspec: str, *, force_with_lease: bool = False) -> subprocess.CompletedProcess[str]:
+        args = ["push"]
+        if force_with_lease:
+            args.append("--force-with-lease")
+        args.extend([remote, refspec])
+        return self.run(args)
+