codex-autorunner 0.1.0__py3-none-any.whl

codex_autorunner/codex_cli.py

@@ -0,0 +1,79 @@
+import subprocess
+from functools import lru_cache
+from typing import Iterable, Optional
+
+SUBCOMMAND_HINTS = ("exec", "resume")
+
+
+def extract_flag_value(args: Iterable[str], flag: str) -> Optional[str]:
+    if not args:
+        return None
+    for arg in args:
+        if not isinstance(arg, str):
+            continue
+        if arg.startswith(f"{flag}="):
+            return arg.split("=", 1)[1] or None
+    args_list = [str(a) for a in args]
+    for idx, arg in enumerate(args_list):
+        if arg == flag and idx + 1 < len(args_list):
+            return args_list[idx + 1]
+    return None
+
+
+def inject_flag(
+    args: Iterable[str],
+    flag: str,
+    value: Optional[str],
+    *,
+    subcommands: Iterable[str] = SUBCOMMAND_HINTS,
+) -> list[str]:
+    if not value:
+        return [str(a) for a in args]
+    args_list = [str(a) for a in args]
+    if extract_flag_value(args_list, flag):
+        return args_list
+    insert_at = None
+    for cmd in subcommands:
+        try:
+            insert_at = args_list.index(cmd)
+            break
+        except ValueError:
+            continue
+    if insert_at is None:
+        return [flag, value] + args_list
+    return args_list[:insert_at] + [flag, value] + args_list[insert_at:]
+
+
+def apply_codex_options(
+    args: Iterable[str],
+    *,
+    model: Optional[str] = None,
+    reasoning: Optional[str] = None,
+    supports_reasoning: Optional[bool] = None,
+) -> list[str]:
+    with_model = inject_flag(args, "--model", model)
+    if reasoning and supports_reasoning is False:
+        return with_model
+    return inject_flag(with_model, "--reasoning", reasoning)
+
+
+def _read_help_text(binary: str) -> str:
+    try:
+        result = subprocess.run(
+            [binary, "--help"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError:
+        return ""
+    return "\n".join(filter(None, [result.stdout, result.stderr]))
+
+
+@lru_cache(maxsize=8)
+def supports_flag(binary: str, flag: str) -> bool:
+    return flag in _read_help_text(binary)
+
+
+def supports_reasoning(binary: str) -> bool:
+    return supports_flag(binary, "--reasoning")

codex_autorunner/codex_runner.py

@@ -0,0 +1,17 @@
+from .core.codex_runner import (
+    CodexRunnerError,
+    CodexTimeoutError,
+    build_codex_command,
+    resolve_codex_binary,
+    run_codex_capture_async,
+    run_codex_streaming,
+)
+
+__all__ = [
+    "CodexRunnerError",
+    "CodexTimeoutError",
+    "build_codex_command",
+    "resolve_codex_binary",
+    "run_codex_capture_async",
+    "run_codex_streaming",
+]

codex_autorunner/core/__init__.py

@@ -0,0 +1 @@
+"""Core runtime primitives."""

codex_autorunner/core/about_car.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Mapping, Optional
+
+from .config import ROOT_CONFIG_FILENAME, ROOT_OVERRIDE_FILENAME, Config
+
+ABOUT_CAR_BASENAME = "ABOUT_CAR.md"
+ABOUT_CAR_REL_PATH = Path(".codex-autorunner") / ABOUT_CAR_BASENAME
+
+# If this marker is present, codex-autorunner may safely refresh the file content.
+ABOUT_CAR_GENERATED_MARKER = "<!-- CAR:AUTOGENERATED -->"
+
+
+def _display_path(repo_root: Path, path: Path) -> str:
+    try:
+        return str(path.relative_to(repo_root))
+    except ValueError:
+        return str(path)
+
+
+def build_about_car_markdown(
+    *,
+    repo_root: Path,
+    todo_path: Path,
+    progress_path: Path,
+    opinions_path: Path,
+    spec_path: Path,
+    summary_path: Path,
+    config_path: Optional[Path] = None,
+) -> str:
+    config_path = config_path or (repo_root / ".codex-autorunner" / "config.yml")
+    root_config_path = repo_root / ROOT_CONFIG_FILENAME
+    root_override_path = repo_root / ROOT_OVERRIDE_FILENAME
+    todo_disp = _display_path(repo_root, todo_path)
+    progress_disp = _display_path(repo_root, progress_path)
+    opinions_disp = _display_path(repo_root, opinions_path)
+    spec_disp = _display_path(repo_root, spec_path)
+    summary_disp = _display_path(repo_root, summary_path)
+    config_disp = _display_path(repo_root, config_path)
+    root_config_disp = _display_path(repo_root, root_config_path)
+    root_override_disp = _display_path(repo_root, root_override_path)
+
+    return (
+        f"{ABOUT_CAR_GENERATED_MARKER}\n"
+        "# ABOUT_CAR — Codex Autorunner (CAR)\n\n"
+        "You are running inside **Codex Autorunner (CAR)**.\n\n"
+        "CAR uses a small set of markdown **work docs** as the control surface for long-horizon work. "
+        "These docs live under the repo-local, gitignored `.codex-autorunner/` directory.\n\n"
+        "## Work docs (canonical)\n"
+        "- **TODO** — ordered checklist of high-level tasks: "
+        f"`{todo_disp}`\n"
+        "- **PROGRESS** — running notes / validation / context: "
+        f"`{progress_disp}`\n"
+        "- **OPINIONS** — constraints + style guidelines: "
+        f"`{opinions_disp}`\n"
+        "- **SPEC** — source-of-truth requirements and scope: "
+        f"`{spec_disp}`\n"
+        "- **SUMMARY** — user-facing report + external/user action items: "
+        f"`{summary_disp}`\n\n"
+        "## Critical rules\n"
+        f'- When the user says **"add this to the TODOs"**, edit `{todo_disp}`.\n'
+        "- Do **not** create new copies of TODO/PROGRESS/OPINIONS/SPEC/SUMMARY elsewhere in the repo.\n"
+        "- Treat `.codex-autorunner/` as intentional project structure even though it is hidden/gitignored.\n\n"
+        "## How CAR works (short)\n"
+        "- `car run/once` repeatedly runs Codex non-interactively, feeding it the work docs (and the prior run tail).\n"
+        "- `car serve` starts a local web UI. The **Terminal** tab launches the configured `codex` binary in a PTY.\n"
+        f"- Repo config lives at `{config_disp}` (doc paths, codex args, server host/port).\n"
+        f"- Root defaults live at `{root_config_disp}` with optional `{root_override_disp}` overrides.\n"
+    )
+
+
+def ensure_about_car_file_for_repo(
+    repo_root: Path,
+    *,
+    doc_paths: Mapping[str, Path],
+    force: bool = False,
+) -> Path:
+    """
+    Ensure `.codex-autorunner/ABOUT_CAR.md` exists for this repo.
+
+    If the file already exists and contains the generated marker, it may be refreshed
+    (unless force=False and content already matches).
+    """
+    path = repo_root / ABOUT_CAR_REL_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    content = build_about_car_markdown(
+        repo_root=repo_root,
+        todo_path=doc_paths["todo"],
+        progress_path=doc_paths["progress"],
+        opinions_path=doc_paths["opinions"],
+        spec_path=doc_paths["spec"],
+        summary_path=doc_paths["summary"],
+        config_path=repo_root / ".codex-autorunner" / "config.yml",
+    )
+    if content and not content.endswith("\n"):
+        content += "\n"
+
+    if path.exists() and not force:
+        try:
+            existing = path.read_text(encoding="utf-8")
+        except OSError:
+            existing = ""
+        # Only overwrite if it's our generated file (marker) and content changed.
+        if ABOUT_CAR_GENERATED_MARKER not in existing:
+            return path
+        if existing == content:
+            return path
+
+    path.write_text(content, encoding="utf-8")
+    return path
+
+
+def ensure_about_car_file(config: Config, *, force: bool = False) -> Path:
+    """Config-aware wrapper that uses configured doc paths."""
+    repo_root = config.root
+    docs = {
+        "todo": config.doc_path("todo"),
+        "progress": config.doc_path("progress"),
+        "opinions": config.doc_path("opinions"),
+        "spec": config.doc_path("spec"),
+        "summary": config.doc_path("summary"),
+    }
+    return ensure_about_car_file_for_repo(repo_root, doc_paths=docs, force=force)

codex_autorunner/core/codex_runner.py

@@ -0,0 +1,100 @@
+import asyncio
+import subprocess
+from pathlib import Path
+from typing import Callable, Optional
+
+from ..codex_cli import apply_codex_options, supports_reasoning
+from .config import Config, ConfigError
+from .utils import resolve_executable, subprocess_env
+
+
+class CodexRunnerError(Exception):
+    """Raised when a Codex subprocess fails at the runner boundary."""
+
+
+class CodexTimeoutError(CodexRunnerError):
+    """Raised when a Codex subprocess exceeds the timeout."""
+
+
+def resolve_codex_binary(config: Config) -> str:
+    resolved = resolve_executable(config.codex_binary)
+    if not resolved:
+        raise ConfigError(f"Codex binary not found: {config.codex_binary}")
+    return resolved
+
+
+def build_codex_command(
+    config: Config, prompt: str, *, resolved_binary: Optional[str] = None
+) -> list[str]:
+    binary = resolved_binary or resolve_codex_binary(config)
+    reasoning_supported = supports_reasoning(binary)
+    args = apply_codex_options(
+        config.codex_args,
+        model=config.codex_model,
+        reasoning=config.codex_reasoning,
+        supports_reasoning=reasoning_supported,
+    )
+    return [binary] + args + [prompt]
+
+
+def run_codex_streaming(
+    config: Config,
+    repo_root: Path,
+    prompt: str,
+    *,
+    on_stdout_line: Optional[Callable[[str], None]] = None,
+    cmd: Optional[list[str]] = None,
+) -> int:
+    cmd = cmd or build_codex_command(config, prompt)
+    try:
+        proc = subprocess.Popen(
+            cmd,
+            cwd=str(repo_root),
+            env=subprocess_env(),
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            bufsize=1,
+        )
+    except FileNotFoundError as exc:
+        raise ConfigError(f"Codex binary not found: {config.codex_binary}") from exc
+
+    if proc.stdout:
+        for line in proc.stdout:
+            if on_stdout_line:
+                on_stdout_line(line.rstrip("\n"))
+
+    return proc.wait()
+
+
+async def run_codex_capture_async(
+    config: Config,
+    repo_root: Path,
+    prompt: str,
+    *,
+    timeout_seconds: Optional[int] = None,
+    cmd: Optional[list[str]] = None,
+) -> tuple[int, str]:
+    cmd = cmd or build_codex_command(config, prompt)
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            cwd=str(repo_root),
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.STDOUT,
+        )
+    except FileNotFoundError as exc:
+        raise ConfigError(f"Codex binary not found: {config.codex_binary}") from exc
+
+    try:
+        stdout, _ = await asyncio.wait_for(proc.communicate(), timeout=timeout_seconds)
+    except asyncio.TimeoutError as exc:
+        proc.kill()
+        await proc.wait()
+        raise CodexTimeoutError("Codex process timed out") from exc
+
+    output = stdout.decode("utf-8", errors="ignore") if stdout else ""
+    returncode = proc.returncode
+    if returncode is None:
+        returncode = await proc.wait()
+    return returncode, output