caokit 0.3.0.dev0__py3-none-any.whl

caokit/roster.py

@@ -0,0 +1,95 @@
+"""Roster rules (guardrails) that decide whether a Config is allowed."""
+
+from dataclasses import dataclass, field
+
+from .adapters import Adapter, AdapterError, load_adapter, vendor_of
+from .config import Config
+
+
+@dataclass
+class Result:
+    """Outcome of checking a roster: errors block, warnings inform.
+
+    Attributes:
+        errors: Violations that must stop `company create` and `install`.
+        warnings: Risks the user should see but may accept.
+    """
+
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+
+def check_roster(cfg: Config) -> Result:
+    """Apply every guardrail to ``cfg`` and return all errors and warnings.
+
+    Rules: tools must exist and not be parked; a tool must be allowed to fill
+    the role; a soft-enforcement engineer or General needs an explicit opt-in; the
+    inspector must be independent of the engineer (different tool and model
+    vendor); a single-provider setup is flagged.
+
+    Args:
+        cfg: The configuration to check.
+
+    Returns:
+        All errors and warnings found; never raises for a bad roster.
+    """
+    res = Result()
+    adapters: dict[str, Adapter] = {}
+    for role, b in cfg.roles.items():
+        try:
+            a = load_adapter(b.tool)
+        except AdapterError:
+            res.errors.append(f"roles.{role}: unknown tool {b.tool!r}")
+            continue
+        adapters[role] = a
+        if a.status == "parked":
+            res.errors.append(f"roles.{role}: tool {b.tool!r} is parked and cannot be selected")
+            continue  # no point checking capabilities of an unselectable tool
+        if not a.roles[role].can_fill:
+            res.errors.append(f"roles.{role}: tool {b.tool!r} cannot fill the {role} role")
+        # Soft enforcement means CAO cannot deny tools. The engineer has write + shell, and the
+        # General is meant to have neither, so both need an explicit opt-in.
+        opt_in = {"engineer": cfg.allow_soft_engineer, "general": cfg.allow_soft_general}
+        if role in opt_in and a.enforcement == "soft":
+            if not opt_in[role]:
+                res.errors.append(
+                    f"roles.{role}: tool {b.tool!r} has soft enforcement (tool limits are "
+                    f"advisory); pass --allow-soft-{role} to accept this"
+                )
+            else:
+                res.warnings.append(
+                    f"{role} uses {b.tool!r}: its tool limits are advisory only, nothing "
+                    "stops it from writing or running anything it can reach"
+                )
+    if "engineer" in adapters and "inspector" in adapters:
+        _check_cross_provider(cfg, adapters, res)
+    if len({b.tool for b in cfg.roles.values()}) == 1:
+        res.warnings.append(
+            "single provider in use: independent cross-provider review is not possible"
+        )
+    return res
+
+
+def _check_cross_provider(cfg: Config, adapters: dict[str, Adapter], res: Result) -> None:
+    """Require the inspector to differ from the engineer in tool AND model vendor.
+
+    Args:
+        cfg: The configuration being checked.
+        adapters: Loaded adapters keyed by role (engineer and inspector present).
+        res: Result to append errors or warnings to.
+    """
+    eb, ib = cfg.roles["engineer"], cfg.roles["inspector"]
+    problems: list[str] = []
+    if eb.tool == ib.tool:
+        problems.append(f"engineer and inspector both use tool {eb.tool!r}")
+    # Vendor check catches e.g. an Antigravity inspector running a Claude model.
+    ev = vendor_of(adapters["engineer"], eb.model)
+    iv = vendor_of(adapters["inspector"], ib.model)
+    if ev == iv:
+        problems.append(f"engineer and inspector models are the same vendor ({ev})")
+    for p in problems:
+        msg = "cross-provider inspection violated: " + p
+        if cfg.allow_single_provider:
+            res.warnings.append(msg)
+        else:
+            res.errors.append(msg + " (--allow-single-provider to override)")

caokit/schedule.py

@@ -0,0 +1,104 @@
+"""Install a daily cron job that archives finished tasks and prunes old archived ones.
+
+cron is the only scheduler used. The entry carries a marker comment holding the project path,
+so installing twice replaces the entry and removing it touches nothing else in the crontab.
+"""
+
+import shlex
+import subprocess
+import tempfile
+from pathlib import Path
+
+from .adapters import ProcessResult, Runner, default_runner
+
+MARKER = "# caokit-tasks:"
+DEFAULT_TIME = "03:17"
+
+
+class ScheduleError(Exception):
+    """Raised when the crontab cannot be read or written."""
+
+
+def cron_line(caokit: str, repo: Path, at: str = DEFAULT_TIME) -> str:
+    """Build the crontab entry for one project.
+
+    Args:
+        caokit: Absolute path of the ``caokit`` executable (cron has a minimal PATH).
+        repo: Project root.
+        at: Time of day, ``HH:MM`` (24 hour).
+
+    Returns:
+        One crontab line ending in the project marker.
+
+    Raises:
+        ValueError: ``at`` is not a valid ``HH:MM`` time.
+    """
+    hh, _, mm = at.partition(":")
+    if not (hh.isdigit() and mm.isdigit() and 0 <= int(hh) <= 23 and 0 <= int(mm) <= 59):
+        raise ValueError(f"invalid time {at!r}: use HH:MM, 24 hour")
+    exe, root = shlex.quote(caokit), shlex.quote(str(repo))
+    cmd = f"{exe} tasks archive {root} && {exe} tasks prune {root} --yes"
+    return f"{int(mm)} {int(hh)} * * * {_escape(cmd)} {_tag(repo)}"
+
+
+def _escape(text: str) -> str:
+    """Escape ``%``: cron turns an unescaped one into a newline and feeds the rest to stdin."""
+    return text.replace("%", "\\%")
+
+
+def _tag(repo: Path) -> str:
+    return MARKER + _escape(str(repo))
+
+
+def _run(runner: Runner, argv: list[str]) -> ProcessResult:
+    try:
+        return runner(argv)
+    except (OSError, subprocess.TimeoutExpired) as e:
+        raise ScheduleError(f"could not run {argv[0]}: {e}") from e
+
+
+def _read(runner: Runner) -> list[str]:
+    r = _run(runner, ["crontab", "-l"])
+    if r.returncode != 0:
+        # Only "no crontab for user" means empty. Anything else must not be read as empty,
+        # or the next write would replace the whole crontab with one line.
+        if "no crontab" in (r.stderr or "").lower():
+            return []
+        raise ScheduleError("could not read the crontab: " + (r.stderr or "").strip())
+    return (r.stdout or "").splitlines()
+
+
+def _write(runner: Runner, lines: list[str]) -> None:
+    text = "\n".join(lines) + "\n" if lines else ""
+    with tempfile.NamedTemporaryFile("w", suffix=".cron", delete=False) as f:
+        f.write(text)
+    try:
+        r = _run(runner, ["crontab", f.name])  # the runner has no stdin, so install from a file
+    finally:
+        Path(f.name).unlink(missing_ok=True)
+    if r.returncode != 0:
+        raise ScheduleError("could not write the crontab: " + (r.stderr or "").strip())
+
+
+def _without(lines: list[str], repo: Path) -> list[str]:
+    tag = _tag(repo)
+    return [ln for ln in lines if not ln.endswith(tag)]
+
+
+def install(line: str, repo: Path, runner: Runner = default_runner) -> None:
+    """Add (or replace) the project's entry, leaving every other crontab line alone."""
+    _write(runner, [*_without(_read(runner), repo), line])
+
+
+def remove(repo: Path, runner: Runner = default_runner) -> bool:
+    """Remove the project's entry.
+
+    Returns:
+        True if an entry was removed, False if there was none.
+    """
+    before = _read(runner)
+    after = _without(before, repo)
+    if after == before:
+        return False
+    _write(runner, after)
+    return True

caokit/stack.py

@@ -0,0 +1,117 @@
+"""Suggest a project validation command from what is already in the repo.
+
+Only suggests; the human confirms at task approval. Prefers forms that leave no
+generated files behind (no .pyc, no pytest cache). Agents never install, so we
+only suggest tooling that is already present.
+"""
+
+import json
+import re
+import subprocess
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from .adapters import ProcessResult, Runner
+
+PYTEST_CMD = "python3 -B -m pytest -p no:cacheprovider -q"
+UNITTEST_CMD = "python3 -B -m unittest discover"
+
+
+@dataclass
+class Suggestion:
+    """A proposed validation command; never authorised until the human confirms it."""
+
+    command: str | None  # None when only a hint is possible (e.g. CI file found)
+    reason: str  # what in the repo led to this suggestion
+    note: str = ""  # caveat shown to the human, e.g. dependencies not installed
+
+
+def _default_runner(argv: Sequence[str]) -> ProcessResult:
+    """Run ``argv`` with captured text output and a short timeout."""
+    return subprocess.run(list(argv), capture_output=True, text=True, timeout=30)
+
+
+def _read(p: Path) -> str:
+    """Read a text file, returning "" if it is missing or unreadable."""
+    try:
+        return p.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+
+
+def _uses_pytest(root: Path) -> bool:
+    """Return True if the repo configures or depends on pytest."""
+    if (root / "pytest.ini").exists() or (root / "conftest.py").exists():
+        return True
+    for name in (
+        "pyproject.toml",
+        "setup.cfg",
+        "tox.ini",
+        "requirements.txt",
+        "requirements-dev.txt",
+    ):
+        t = _read(root / name)
+        if re.search(r"pytest", t):
+            return True
+    return False
+
+
+def _has_py_tests(root: Path) -> bool:
+    """Return True if ``test*.py`` files exist in tests/, test/ or the root."""
+    for d in (root / "tests", root / "test", root):
+        if d.is_dir() and any(d.glob("test*.py")):
+            return True
+    return False
+
+
+def suggest_validation(root: Path, runner: Runner = _default_runner) -> Suggestion | None:
+    """Suggest how to validate the project at ``root``, or None if nothing is detected.
+
+    Order: package.json test script, pytest (only if importable), unittest files,
+    Makefile ``test`` target, then a CI-workflow hint.
+
+    Args:
+        root: Project root directory.
+        runner: Executes ``python3 -c "import pytest"``; injected so tests need no pytest.
+
+    Returns:
+        A :class:`Suggestion`, or None.
+    """
+    root = Path(root)
+    pkg = root / "package.json"
+    if pkg.is_file():
+        try:
+            script = json.loads(_read(pkg)).get("scripts", {}).get("test", "")
+        except (ValueError, AttributeError):
+            script = ""
+        # `npm init` writes a placeholder script that always fails; ignore it.
+        if script and "no test specified" not in script:
+            note = (
+                ""
+                if (root / "node_modules").is_dir()
+                else "node_modules is missing; agents never install, "
+                "install dependencies yourself first"
+            )
+            return Suggestion("npm test", "package.json defines a test script", note)
+    if _has_py_tests(root) or _uses_pytest(root):
+        # -B / no:cacheprovider keep the working tree clean (no .pyc or .pytest_cache).
+        if _uses_pytest(root):
+            # Agents never install anything, so only suggest pytest if it is already present.
+            try:
+                have = runner(["python3", "-c", "import pytest"]).returncode == 0
+            except (OSError, subprocess.SubprocessError):
+                have = False
+            if have:
+                return Suggestion(PYTEST_CMD, "pytest is configured and importable")
+        if _has_py_tests(root):
+            return Suggestion(UNITTEST_CMD, "test*.py files found")
+    mk = _read(root / "Makefile")
+    if re.search(r"(?m)^test\s*:", mk):
+        return Suggestion("make test", "Makefile has a test target")
+    wf = root / ".github" / "workflows"
+    if wf.is_dir():
+        files = sorted(p.name for p in wf.iterdir() if p.suffix in (".yml", ".yaml"))
+        if files:
+            return Suggestion(None, f"CI workflow found ({files[0]}): copy its test step")
+    return None

caokit/tasks.py

@@ -0,0 +1,180 @@
+"""Read-only view of ``.company/tasks`` plus archiving of finished tasks."""
+
+import os
+import re
+import shutil
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+TERMINAL = frozenset({"ACCEPTED", "CANCELLED", "FAILED"})
+_ID = re.compile(r"TASK-\d{4}")
+_STATE = re.compile(r"^- \*\*State:\*\*\s*([A-Z_]+)", re.M)
+_DEPS = re.compile(r"^- \*\*Depends on:\*\*(.*)$", re.M)
+_TITLE = re.compile(r"^# (TASK-\d{4}):\s*(.*)$", re.M)
+
+
+class TaskError(Exception):
+    """Raised for an unreadable task folder or a dependency loop."""
+
+
+@dataclass(frozen=True)
+class Task:
+    """One task file, reduced to what listing and archiving need."""
+
+    id: str
+    title: str
+    state: str
+    depends: tuple[str, ...]
+    path: Path
+    archived: bool = False
+    blocked_by: tuple[str, ...] = field(default=(), compare=False)
+
+
+def tasks_dir(repo: Path) -> Path:
+    """Return ``<repo>/.company/tasks``, raising if the repo has none."""
+    d = repo / ".company" / "tasks"
+    if not d.is_dir():
+        raise TaskError(f"no .company/tasks folder in {repo}")
+    return d
+
+
+def parse_task(path: Path, archived: bool = False) -> Task | None:
+    """Parse a task file, or return None if it has no ``# TASK-NNNN`` heading."""
+    text = path.read_text(encoding="utf-8", errors="replace")
+    title = _TITLE.search(text)
+    if not title:
+        return None
+    state = _STATE.search(text)
+    deps = _DEPS.search(text)
+    return Task(
+        id=title.group(1),
+        title=title.group(2).strip(),
+        state=state.group(1) if state else "UNKNOWN",
+        depends=tuple(dict.fromkeys(_ID.findall(deps.group(1)))) if deps else (),
+        path=path,
+        archived=archived,
+    )
+
+
+def load_tasks(repo: Path) -> list[Task]:
+    """Load active tasks and archived ones, sorted by id."""
+    root = tasks_dir(repo)
+    found = [t for p in root.glob("TASK-*.md") if (t := parse_task(p))]
+    arch = root / "archive"
+    if arch.is_dir():
+        found += [t for p in arch.glob("TASK-*.md") if (t := parse_task(p, archived=True))]
+    return sorted(found, key=lambda t: t.id)
+
+
+def find_cycle(tasks: list[Task]) -> list[str] | None:
+    """Return one dependency loop as ``[A, B, A]``, or None if there is none."""
+    graph = {t.id: t.depends for t in tasks}
+    done: set[str] = set()
+
+    def visit(node: str, path: list[str]) -> list[str] | None:
+        if node in path:
+            return [*path[path.index(node) :], node]
+        if node in done or node not in graph:
+            return None
+        for nxt in graph[node]:
+            if (hit := visit(nxt, [*path, node])) is not None:
+                return hit
+        done.add(node)
+        return None
+
+    for tid in sorted(graph):
+        if (hit := visit(tid, [])) is not None:
+            return hit
+    return None
+
+
+def with_blockers(tasks: list[Task]) -> list[Task]:
+    """Fill ``blocked_by``: dependencies that are missing or not ACCEPTED.
+
+    Raises:
+        TaskError: if the dependencies form a loop.
+    """
+    if (loop := find_cycle(tasks)) is not None:
+        raise TaskError("dependency loop: " + " -> ".join(loop))
+    state = {t.id: t.state for t in tasks}
+    return [
+        Task(
+            t.id, t.title, t.state, t.depends, t.path, t.archived,
+            tuple(d for d in t.depends if state.get(d) != "ACCEPTED"),
+        )
+        for t in tasks
+    ]  # fmt: skip
+
+
+def format_tasks(tasks: list[Task], show_all: bool = False) -> str:
+    """Render a table of open tasks (or every task with ``show_all``)."""
+    rows = [t for t in tasks if show_all or t.state not in TERMINAL]
+    if not rows:
+        return "No open tasks."
+    lines = []
+    for t in rows:
+        wait = (
+            f"  BLOCKED by {', '.join(t.blocked_by)}"
+            if t.blocked_by and t.state not in TERMINAL
+            else ""
+        )
+        tag = " [archived]" if t.archived else ""
+        lines.append(f"{t.id}  {t.state:<19}{t.title}{wait}{tag}")
+    return "\n".join(lines)
+
+
+def archive_finished(repo: Path, delete: bool = False) -> list[Task]:
+    """Move finished tasks into ``tasks/archive/`` (or delete them).
+
+    A task is finished when its state is ACCEPTED, CANCELLED or FAILED. Running it
+    twice changes nothing the second time.
+
+    Returns:
+        The tasks that were moved or deleted.
+    """
+    root = tasks_dir(repo)
+    moved = []
+    for p in sorted(root.glob("TASK-*.md")):
+        task = parse_task(p)
+        if task is None or task.state not in TERMINAL:
+            continue
+        if delete:
+            p.unlink()
+        else:
+            (root / "archive").mkdir(exist_ok=True)
+            dest = root / "archive" / p.name
+            shutil.move(str(p), dest)
+            os.utime(dest)  # a move keeps the old mtime; the archive date is when it was archived
+        moved.append(task)
+    return moved
+
+
+def prune_archive(
+    repo: Path, days: int, apply: bool = False, now: float | None = None
+) -> list[Path]:
+    """List archived task files older than ``days``, deleting them when ``apply`` is true.
+
+    Age is measured from when the file was archived (its modification time).
+
+    Args:
+        repo: Project root.
+        days: Keep files archived within this many days.
+        apply: Delete the old files instead of only listing them.
+        now: Current time as a Unix timestamp (injectable for tests).
+
+    Returns:
+        The old archived files, oldest first. Empty when there is no archive folder.
+    """
+    arch = tasks_dir(repo) / "archive"
+    if not arch.is_dir():
+        return []
+    cutoff = (time.time() if now is None else now) - days * 86400
+    old = sorted(
+        (p for p in arch.glob("TASK-*.md") if p.stat().st_mtime < cutoff),
+        key=lambda p: p.stat().st_mtime,
+    )
+    if apply:
+        for p in old:
+            p.unlink()
+    return old

caokit/worktrees.py

@@ -0,0 +1,107 @@
+"""Per-task git worktrees through CAO's ``use_worktree``.
+
+CAO gives one engineer terminal its own ``git worktree`` at ``<repo>/.cao/worktrees/<terminal-id>``
+on branch ``cao/<terminal-id>``, cut from the repo's HEAD. It removes the checkout when the
+terminal is deleted and keeps the branch only if it holds commits. The agents do the dispatching
+(see the role files); this module is what caokit itself knows about it: whether a repo can use
+worktrees, and what CAO has left in one.
+"""
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from .adapters import Runner, default_runner
+
+BRANCH_PREFIX = (
+    "cao/"  # CAO's own branch naming; see cli_agent_orchestrator.services.worktree_service
+)
+WORKTREE_SUBDIR = ".cao/worktrees"
+
+
+@dataclass
+class TaskWorktree:
+    """One branch CAO created for an engineer terminal.
+
+    Attributes:
+        branch: ``cao/<terminal-id>``.
+        path: The checkout, or None once CAO has removed it (the branch outlives it).
+        ahead: Commits on the branch that HEAD does not have (work not yet merged).
+        dirty: True if the checkout has uncommitted changes, which CAO discards on teardown.
+    """
+
+    branch: str
+    path: Path | None
+    ahead: int
+    dirty: bool
+
+
+def _git(runner: Runner, repo: Path, *args: str) -> tuple[int, str]:
+    try:
+        r = runner(["git", "-C", str(repo), *args])
+    except (OSError, subprocess.TimeoutExpired) as e:
+        return 1, str(e)
+    return r.returncode, ((r.stdout or "") if r.returncode == 0 else (r.stderr or "")).strip()
+
+
+def problems(repo: Path, runner: Runner = default_runner) -> tuple[list[str], list[str]]:
+    """Check that ``repo`` can give each engineer a worktree.
+
+    Args:
+        repo: Project root.
+        runner: Command runner (injectable for tests).
+
+    Returns:
+        ``(errors, warnings)``. Errors mean CAO's ``use_worktree`` would fail or lose work;
+        warnings are things the human should know first.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+    code, out = _git(runner, repo, "rev-parse", "--show-toplevel")
+    if code != 0:
+        return [f"{repo} is not a git repository, so there is nothing to make worktrees from"], []
+    if Path(out).resolve() != Path(repo).resolve():
+        errors.append(f"{repo} is inside the repository at {out}; run caokit on its root")
+    if _git(runner, repo, "rev-parse", "--verify", "HEAD")[0] != 0:
+        errors.append("the repository has no commits yet; a worktree is cut from HEAD")
+    code, out = _git(runner, repo, "status", "--porcelain", "--untracked-files=no")
+    if code == 0 and out:
+        warnings.append(
+            "uncommitted changes in the main checkout are not in a new worktree "
+            "(it starts from the last commit)"
+        )
+    return errors, warnings
+
+
+def list_task_worktrees(repo: Path, runner: Runner = default_runner) -> list[TaskWorktree]:
+    """Return every ``cao/*`` branch in ``repo`` with its checkout and unmerged work.
+
+    Args:
+        repo: Project root.
+        runner: Command runner (injectable for tests).
+
+    Returns:
+        One entry per branch, sorted by branch name. Empty if there are none or git fails.
+    """
+    code, out = _git(runner, repo, "worktree", "list", "--porcelain")
+    paths: dict[str, Path] = {}
+    if code == 0:
+        path = None
+        for line in out.splitlines():
+            if line.startswith("worktree "):
+                path = Path(line[len("worktree ") :])
+            elif line.startswith("branch refs/heads/") and path is not None:
+                paths[line[len("branch refs/heads/") :]] = path
+    code, out = _git(runner, repo, "for-each-ref", "--format=%(refname:short)", "refs/heads/cao/")
+    if code != 0:
+        return []
+    found = []
+    for branch in sorted(out.split()):
+        c, n = _git(runner, repo, "rev-list", "--count", f"HEAD..{branch}")
+        path = paths.get(branch)
+        dirty = False
+        if path is not None:
+            _, status = _git(runner, path, "status", "--porcelain")
+            dirty = bool(status)
+        found.append(TaskWorktree(branch, path, int(n) if c == 0 and n.isdigit() else 0, dirty))
+    return found