codex-autorunner 1.0.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

codex_autorunner/bootstrap.py

@@ -1,8 +1,14 @@
+import sys
 from pathlib import Path
+from typing import Optional
 
 import yaml
 
-from .core.about_car import ensure_about_car_file_for_repo
+from .core.about_car import (
+    ensure_about_car_file_for_repo,
+    ensure_ticket_flow_quickstart_file_for_repo,
+    ensure_tickets_agents_file_for_repo,
+)
 from .core.config import (
     CONFIG_FILENAME,
     DEFAULT_HUB_CONFIG,
@@ -11,19 +17,24 @@ from .core.config import (
     resolve_hub_config_data,
 )
 from .core.state import RunnerState, save_state
+from .core.ticket_linter_cli import ensure_ticket_linter
+from .core.ticket_manager_cli import ensure_ticket_manager
 from .core.utils import atomic_write
 from .manifest import load_manifest
 
 GITIGNORE_CONTENT = "*"
 GENERATED_CONFIG_HEADER = "# GENERATED by CAR - DO NOT EDIT\n"
+HUB_CAR_SHIM_MARKER = "# CAR:HUB_CLI_SHIM"
+HUB_CAR_SHIM_REL_PATH = Path(".codex-autorunner/bin/car")
+HUB_CAR_SHIM_ROOT_BASENAME = "car"
 
 
 def sample_todo() -> str:
-    return """# TODO\n\n- [ ] Replace this item with your first task\n- [ ] Add another task\n- [x] Example completed item\n"""
+    return ""
 
 
 def sample_spec() -> str:
-    return """# Spec\n\n## Context\n- Add project background and goals here.\n\n## Requirements\n- Requirement 1\n- Requirement 2\n\n## Non-goals\n- Out of scope items\n"""
+    return ""
 
 
 def _seed_doc(path: Path, force: bool, content: str) -> None:
@@ -67,6 +78,58 @@ def write_hub_config(hub_root: Path, force: bool = False) -> Path:
     return config_path
 
 
+def _build_hub_car_shim(python_executable: str) -> str:
+    content = (
+        "#!/bin/sh\n"
+        f"{HUB_CAR_SHIM_MARKER}\n"
+        "# Generated by CAR. Safe to overwrite.\n"
+        f'exec "{python_executable}" -m codex_autorunner.cli "$@"\n'
+    )
+    return content
+
+
+def _should_refresh_shim(path: Path, content: str, *, force: bool) -> bool:
+    if force or not path.exists():
+        return True
+    try:
+        existing = path.read_text(encoding="utf-8")
+    except OSError:
+        return True
+    if HUB_CAR_SHIM_MARKER not in existing:
+        return False
+    return existing != content
+
+
+def ensure_hub_car_shim(
+    hub_root: Path,
+    *,
+    python_executable: Optional[str] = None,
+    force: bool = False,
+) -> list[Path]:
+    """Ensure a hub-local car shim points at the current runtime."""
+    python_executable = python_executable or sys.executable
+    content = _build_hub_car_shim(python_executable)
+    if content and not content.endswith("\n"):
+        content += "\n"
+    targets = [
+        hub_root / HUB_CAR_SHIM_ROOT_BASENAME,
+        hub_root / HUB_CAR_SHIM_REL_PATH,
+    ]
+    written: list[Path] = []
+    for path in targets:
+        if not _should_refresh_shim(path, content, force=force):
+            continue
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+        try:
+            mode = path.stat().st_mode
+            path.chmod(mode | 0o111)
+        except OSError:
+            pass
+        written.append(path)
+    return written
+
+
 def seed_repo_files(
     repo_root: Path, force: bool = False, git_required: bool = True
 ) -> None:
@@ -102,7 +165,7 @@ def seed_repo_files(
         workspace_dir.mkdir(parents=True, exist_ok=True)
 
     _seed_doc(workspace_dir / "active_context.md", force, sample_todo())
-    _seed_doc(workspace_dir / "decisions.md", force, "# Decisions\n\n")
+    _seed_doc(workspace_dir / "decisions.md", force, "")
     _seed_doc(workspace_dir / "spec.md", force, sample_spec())
 
     # Seed an always-available briefing doc for interactive Codex sessions.
@@ -115,6 +178,21 @@ def seed_repo_files(
         },
         force=force,
     )
+    ensure_ticket_flow_quickstart_file_for_repo(repo_root, force=force)
+    ensure_tickets_agents_file_for_repo(repo_root, force=force)
+    ensure_ticket_linter(repo_root, force=force)
+    ensure_ticket_manager(repo_root, force=force)
+
+
+def ensure_pma_docs(hub_root: Path, force: bool = False) -> None:
+    ca_dir = hub_root / ".codex-autorunner"
+    pma_dir = ca_dir / "pma"
+    pma_dir.mkdir(parents=True, exist_ok=True)
+    _seed_doc(pma_dir / "prompt.md", force, pma_prompt_content())
+    _seed_doc(pma_dir / "ABOUT_CAR.md", force, pma_about_content())
+    _seed_doc(pma_dir / "AGENTS.md", force, pma_agents_content())
+    _seed_doc(pma_dir / "active_context.md", force, pma_active_context_content())
+    _seed_doc(pma_dir / "context_log.md", force, pma_context_log_content())
 
 
 def seed_hub_files(hub_root: Path, force: bool = False) -> None:
@@ -130,6 +208,9 @@ def seed_hub_files(hub_root: Path, force: bool = False) -> None:
 
     write_hub_config(hub_root, force=force)
 
+    ensure_pma_docs(hub_root, force=force)
+    ensure_hub_car_shim(hub_root, force=force)
+
     manifest_path = hub_root / DEFAULT_HUB_CONFIG["hub"]["manifest"]
     load_manifest(manifest_path, hub_root)
 
@@ -139,3 +220,144 @@ def seed_hub_files(hub_root: Path, force: bool = False) -> None:
             hub_state_path,
             '{\n  "last_scan_at": null,\n  "repos": []\n}\n',
         )
+
+
+def pma_prompt_content() -> str:
+    return """# Project Management Agent (PMA)
+
+You are the hub-level Project Management Agent (PMA), the user's primary interface for coordinating work across repos.
+
+## Role
+
+You are an **abstraction layer, not an executor**. Coordinate tickets and flows across multiple repos by delegating to repo agents.
+
+## Guidance
+
+- Use CAR-native artifacts (tickets, ticket_flow, dispatch, PMA inbox/outbox).
+- Ask questions when requirements are ambiguous; keep updates concise.
+- Treat this prompt as code: keep it short and stable.
+- See `.codex-autorunner/pma/ABOUT_CAR.md` for operational how-to.
+
+## Worktrees (hub-managed)
+
+- Prefer hub-owned worktrees:
+  - Hub UI: “New Worktree”
+  - CLI: `car hub worktree create <base_repo_id> <branch> [--start-point <ref>]`
+- If a worktree was created manually (e.g. `git worktree add`), it MUST be registered:
+  - `car hub scan --path <hub_root>`
+- Never copy `.codex-autorunner/` between worktrees. Each worktree has its own CAR state/docs.
+
+## PMA durable workspace
+
+Prefer writing durable guidance and recurring best-practices to `.codex-autorunner/pma/AGENTS.md`.
+Keep short-lived working context in `.codex-autorunner/pma/active_context.md` and prune it when it grows.
+When pruning, append the prior context to `.codex-autorunner/pma/context_log.md` with a timestamp.
+"""
+
+
+def pma_notes_content() -> str:
+    return """# PMA Operations Guide
+
+## Tickets (create/modify)
+
+- Tickets live per repo at `<repo>/.codex-autorunner/tickets/`.
+- Create or edit `TICKET-###*.md` files directly; keep diffs small and single-purpose.
+- Set `done: true` in the ticket frontmatter only when the ticket is complete.
+
+## Ticket flow (start/resume)
+
+- Bootstrap (creates TICKET-001 if missing):
+  `car flow ticket_flow bootstrap --repo <path>`
+- Start/resume:
+  `car flow ticket_flow start --repo <path>`
+  `car flow ticket_flow resume --repo <path> [--run-id <uuid>]`
+- Status/stop:
+  `car flow ticket_flow status --repo <path> [--run-id <uuid>]`
+  `car flow ticket_flow stop --repo <path> [--run-id <uuid>]`
+- See `<repo>/.codex-autorunner/TICKET_FLOW_QUICKSTART.md` for CLI entrypoints + gotchas.
+
+## Worktrees 101 (Hub-managed)
+
+Canonical worktree creation:
+- Hub UI: “New Worktree”
+- CLI (from hub root):
+  `car hub worktree create <base_repo_id> <branch> [--start-point <ref>]`
+
+Registering a manually-created worktree:
+- If you used `git worktree add`, run:
+  `car hub scan --path <hub_root>`
+- Worktrees should live under the hub’s configured worktrees root and be shallow (depth=1) discoverable.
+
+Naming / grouping:
+- Prefer worktree directory names like:
+  `<base_repo_id>--<branch>`
+- This enables `worktree_of` inference during scan and grouping in the hub UI.
+
+Do NOT copy `.codex-autorunner/` between worktrees:
+- Each worktree is a full repo with its own `.codex-autorunner/` state/docs.
+- Copying can introduce stale locks and confusing run metadata.
+
+## Dispatch pauses (handle)
+
+- Paused runs appear in the hub inbox snapshot with `repo_id`, `run_id`, and `open_url`.
+- Read the latest dispatch, respond to the user, then resume the run.
+- Dispatch history lives under:
+  `<repo>/.codex-autorunner/runs/<run_id>/dispatch_history/####/DISPATCH.md`
+
+## PMA file handoff
+
+- User uploads arrive in `.codex-autorunner/pma/inbox/`.
+- Send user-facing files by writing to `.codex-autorunner/pma/outbox/`.
+"""
+
+
+def pma_about_content() -> str:
+    return pma_notes_content()
+
+
+def pma_agents_content() -> str:
+    return """# PMA AGENTS (durable guidance + defaults)
+
+This document is jointly maintained by the user and PMA.
+
+## What belongs here
+
+- Durable best-practices you want PMA to apply repeatedly ("defaults").
+- Stable preferences (how to structure tickets, review habits, PR conventions).
+- Template shortcuts / references that PMA should re-use.
+
+## What does NOT belong here
+
+- Temporary work-in-progress details (put those in `active_context.md`).
+- Long transcripts.
+
+## Template shortcuts (optional)
+
+- Add references to frequently used ticket templates here (repo/path/ref) and when to apply them.
+
+## Defaults (examples)
+
+- After implementation work, add a final review ticket, then a ticket to open a PR.
+"""
+
+
+def pma_active_context_content() -> str:
+    return """# PMA active context (short-lived)
+
+Use this file for the current working set: active projects, open questions, links, and immediate next steps.
+
+Pruning guidance:
+- Keep this file compact (prefer bullet points).
+- When it grows too large, summarize older items and move durable guidance to `AGENTS.md`.
+- Before a major prune, append a timestamped snapshot to `context_log.md`.
+"""
+
+
+def pma_context_log_content() -> str:
+    return """# PMA context log (append-only)
+
+This file is an append-only history of past `active_context.md` snapshots.
+
+- Add a new section with an ISO timestamp when you perform a major prune.
+- Keep entries concise; the goal is searchability and historical recall.
+"""