caokit 0.3.0.dev0__py3-none-any.whl

caokit/init_project.py

@@ -0,0 +1,183 @@
+"""`caokit init <repo>`: scaffold .company/, write ROSTER.md and merge .gitignore."""
+
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from importlib import resources
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .adapters import ROLES, Runner, default_runner, load_adapter
+from .config import Config
+from .gitignore import BEGIN, merge_gitignore
+from .project import PROJECT_FILE, Overrides, dump_overrides
+from .render import profile_name
+from .stack import Suggestion, suggest_validation
+
+if TYPE_CHECKING:  # typing-only: importlib.abc.Traversable is not importable at runtime on 3.14+
+    from importlib.abc import Traversable
+
+# Directories agents write into. Created even though git does not track empty
+# directories, because the whole of .company/ except contracts/ is ignored anyway.
+EMPTY_DIRS = ["artifacts", "decisions", "handoffs", "research", "reviews", "tasks"]
+
+
+class InitError(Exception):
+    """Raised when a project cannot be initialised (not a git repo, bad path)."""
+
+
+@dataclass
+class InitResult:
+    """What ``init_project`` did, for the CLI to report."""
+
+    created: list[str] = field(default_factory=list)  # scaffold files newly written
+    kept: list[str] = field(default_factory=list)  # existing files left untouched
+    warnings: list[str] = field(default_factory=list)
+    suggestion: Suggestion | None = None  # detected validation command, if any
+
+
+def render_roster_md(cfg: Config, suggestion: Suggestion | None) -> str:
+    """Render ``.company/ROSTER.md``, the file the General reads to dispatch.
+
+    Args:
+        cfg: The company configuration; one table row per role.
+        suggestion: Detected validation command, or None when nothing was detected.
+
+    Returns:
+        The Markdown text, ending in a newline.
+    """
+    rows = []
+    for role in ROLES:
+        b = cfg.roles[role]
+        a = load_adapter(b.tool)
+        model = b.model or "(tool default)"
+        rows.append(
+            f"| {role} | `{profile_name(role, b.tool, cfg.project)}` | {b.tool} | {model} "
+            f"| {a.enforcement} |"
+        )
+    lines = [
+        "# Roster",
+        "",
+        f"Generated by `caokit init` for project `{cfg.project}` from the user-level "
+        "`caokit.toml` plus `.company/caokit.toml` overrides. Regenerate; do not hand-edit."
+        if cfg.project
+        else "Generated by `caokit init` from `caokit.toml`. Regenerate; do not hand-edit.",
+        "",
+        "Dispatch **only** to the profiles listed here, using the name verbatim. "
+        "Never guess a profile name.",
+        "",
+        "| Role | CAO profile | Tool | Model | Enforcement |",
+        "|---|---|---|---|---|",
+        *rows,
+        "",
+        "`soft` enforcement means the tool's limits are advisory only.",
+        "",
+        "## Suggested validation command (unconfirmed)",
+        "",
+    ]
+    if suggestion is None:
+        lines.append(
+            "None detected. The human must supply the authorised validation command "
+            "at task approval."
+        )
+    else:
+        if suggestion.command:  # CI-only hints carry a reason but no command
+            lines += [f"`{suggestion.command}`", ""]
+        lines.append(f"Detected because: {suggestion.reason}.")
+        if suggestion.note:
+            lines += ["", f"Note: {suggestion.note}"]
+        lines += [
+            "",
+            "The human must confirm this at task approval; "
+            "never treat it as authorised until then.",
+        ]
+    return "\n".join(lines) + "\n"
+
+
+def _walk(node: "Traversable", rel: str = "") -> Iterator[tuple[str, "Traversable"]]:
+    """Yield ``(relative/posix/path, file)`` for every file under ``node``, sorted."""
+    for child in sorted(node.iterdir(), key=lambda p: p.name):
+        r = rel + child.name
+        if child.is_dir():
+            yield from _walk(child, r + "/")
+        else:
+            yield r, child
+
+
+def _ignores_whole_company(text: str) -> bool:
+    """Return True if the user's own rules ignore all of ``.company/``.
+
+    Only text before our managed block counts; our block deliberately ignores
+    ``.company/*`` while re-including ``contracts/``.
+    """
+    before = text.split(BEGIN)[0]
+    return any(
+        line.strip() in (".company", ".company/", "/.company", "/.company/")
+        for line in before.splitlines()
+    )
+
+
+def init_project(
+    repo: Path,
+    cfg: Config,
+    runner: Runner = default_runner,
+    overrides: Overrides | None = None,
+    force_project: bool = False,
+) -> InitResult:
+    """Scaffold ``.company/`` in a git repo, write ROSTER.md and merge .gitignore.
+
+    Existing scaffold files are never overwritten, so re-running is safe.
+    ROSTER.md is the exception: it is generated output and is rewritten.
+
+    Args:
+        repo: Root of the target git repository.
+        cfg: The company configuration used to render ROSTER.md.
+        runner: Command runner used by stack detection (injectable for tests).
+        overrides: New project overrides to save as ``.company/caokit.toml``, or None
+            when the project file already exists or the project is not namespaced.
+        force_project: Overwrite an existing ``.company/caokit.toml``.
+
+    Returns:
+        A summary of created and kept files, warnings and the detected
+        validation command.
+
+    Raises:
+        InitError: ``repo`` is not a directory or has no ``.git``, or a project file
+            exists and ``force_project`` is not set.
+    """
+    repo = Path(repo).resolve()
+    if not repo.is_dir():
+        raise InitError(f"not a directory: {repo}")
+    # `.git` may be a file (worktrees, submodules), so test existence, not is_dir.
+    if not (repo / ".git").exists():
+        raise InitError(f"{repo} is not a git repository root (no .git); run `git init` first")
+    project_file = repo / PROJECT_FILE
+    if overrides is not None and project_file.exists() and not force_project:
+        raise InitError(f"{project_file} already exists; edit it, or pass --force-project")
+    res = InitResult()
+    company = repo / ".company"
+    root = resources.files("caokit") / "data" / "scaffold" / "company"
+    for rel, src in _walk(root):
+        dest = company / rel
+        if dest.exists():
+            res.kept.append(".company/" + rel)  # never clobber the project's own edits
+            continue
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_bytes(src.read_bytes())
+        res.created.append(".company/" + rel)
+    for d in EMPTY_DIRS:
+        (company / d).mkdir(parents=True, exist_ok=True)
+    if overrides is not None:
+        project_file.write_text(dump_overrides(overrides), encoding="utf-8")
+        res.created.append(str(PROJECT_FILE))
+    res.suggestion = suggest_validation(repo, runner=runner)
+    (company / "ROSTER.md").write_text(render_roster_md(cfg, res.suggestion), encoding="utf-8")
+    gi = repo / ".gitignore"
+    existing = gi.read_text(encoding="utf-8") if gi.exists() else ""
+    if _ignores_whole_company(existing):
+        res.warnings.append(
+            ".gitignore already ignores all of .company/; git cannot re-include "
+            ".company/contracts/ under an ignored parent. Remove that line so "
+            "contracts are tracked."
+        )
+    gi.write_text(merge_gitignore(existing), encoding="utf-8")
+    return res

caokit/install.py

@@ -0,0 +1,242 @@
+"""Render profiles from caokit.toml and install them into CAO."""
+
+import os
+import shutil
+import tempfile
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .adapters import ROLES, ProcessResult, Runner, default_runner, load_adapter
+from .config import Config
+from .render import profile_name, render_profile
+from .roster import check_roster
+
+# Profile names used by the pre-v1 bash kit. They stay in CAO's global store
+# after migrating, so `install` offers to move them away.
+LEGACY_NAMES = [
+    "startup_captain",
+    "claude_engineer",
+    "claude_reviewer",
+    "agy_researcher",
+    "agy_reviewer",
+    "codex_engineer",
+    "codex_reviewer",
+]
+
+
+class InstallError(Exception):
+    """Raised when profiles cannot even be attempted (for example an invalid roster)."""
+
+
+@dataclass
+class InstallResult:
+    """Per-profile outcome of an install run."""
+
+    installed: list[str] = field(default_factory=list)  # installed and verified
+    failed: list[str] = field(default_factory=list)  # validate, install or verify failed
+    backup_dir: Path | None = None  # set when stale copies were moved aside
+
+
+def cao_home() -> Path:
+    """Return CAO's home directory.
+
+    Honors ``$CAO_HOME_DIR``, else ``~/.aws/cli-agent-orchestrator``. Because
+    ``~`` follows ``$HOME``, tests can redirect everything with a temp HOME.
+    """
+    env = os.environ.get("CAO_HOME_DIR")
+    return Path(env) if env else Path.home() / ".aws" / "cli-agent-orchestrator"
+
+
+def render_all(cfg: Config) -> dict[str, str]:
+    """Render every roster profile.
+
+    Args:
+        cfg: The company configuration.
+
+    Returns:
+        Mapping of concrete profile name to full profile text. Names are
+        ``<role>-<tool>``, or ``<project>_<role>-<tool>`` for a project-scoped config.
+    """
+    out = {}
+    for role in ROLES:
+        b = cfg.roles[role]
+        name = profile_name(role, b.tool, cfg.project)
+        out[name] = render_profile(role, load_adapter(b.tool), b.model, cfg.project)
+    return out
+
+
+def find_legacy(home: Path) -> list[str]:
+    """Return the legacy profile names that still have a copy under ``home``."""
+    return [
+        n
+        for n in LEGACY_NAMES
+        if (home / "agent-store" / (n + ".md")).exists()
+        or (home / "agent-context" / (n + ".md")).exists()
+    ]
+
+
+def _backup(home: Path, names: list[str], backup: Path | None) -> Path | None:
+    """Move installed copies of ``names`` into a backup folder under ``home``.
+
+    Files are moved, never deleted, so a wrong guess is recoverable by hand.
+
+    Args:
+        home: CAO home directory.
+        names: Profile names whose ``agent-context`` and ``agent-store`` copies to move.
+        backup: Existing backup folder to reuse so one run produces one folder,
+            or None to create a timestamped one on first move.
+
+    Returns:
+        The backup folder (None if nothing was moved and none was supplied).
+    """
+    for n in names:
+        for sub in ("agent-context", "agent-store"):
+            src = home / sub / (n + ".md")
+            if src.exists():
+                if backup is None:  # created lazily so a no-op leaves no empty folder
+                    backup = home / ("caokit-backup-" + time.strftime("%Y%m%d%H%M%S"))
+                (backup / sub).mkdir(parents=True, exist_ok=True)
+                shutil.move(str(src), str(backup / sub / (n + ".md")))
+    return backup
+
+
+def remove_legacy(home: Path, names: list[str]) -> Path | None:
+    """Move legacy profile copies to a backup folder (nothing is deleted).
+
+    Args:
+        home: CAO home directory.
+        names: Legacy profile names, as returned by :func:`find_legacy`.
+
+    Returns:
+        The backup folder, or None if there was nothing to move.
+    """
+    return _backup(home, names, None)
+
+
+def _failed_output(r: ProcessResult) -> bool:
+    """Return True if a ``cao`` call failed.
+
+    CAO 2.5.x prints ``Error: ...`` but exits 0 when it refuses to overwrite a
+    profile copy from an older CAO, so the exit code alone is not trustworthy.
+    """
+    return r.returncode != 0 or "Error:" in ((r.stdout or "") + (r.stderr or ""))
+
+
+def install_profiles(
+    cfg: Config,
+    home: Path | None = None,
+    runner: Runner = default_runner,
+    replace_legacy: bool = False,
+    out: Callable[[str], None] = print,
+) -> InstallResult:
+    """Render, validate, install and verify every profile in the roster.
+
+    Each profile is verified by comparing CAO's stored copy byte for byte with
+    what was rendered, because CAO stores profiles verbatim and a mismatch means
+    a stale or altered copy.
+
+    Args:
+        cfg: The company configuration.
+        home: CAO home directory (default: :func:`cao_home`).
+        runner: Command runner used to call ``cao`` (injectable for tests).
+        replace_legacy: On a refused install, move the stale copies to a
+            backup folder and retry once.
+        out: Sink for progress and failure messages.
+
+    Returns:
+        Which profiles were installed and which failed.
+
+    Raises:
+        InstallError: The roster violates a guardrail; nothing is attempted.
+    """
+    home = home or cao_home()
+    roster = check_roster(cfg)
+    if roster.errors:
+        raise InstallError("roster is invalid:\n  " + "\n  ".join(roster.errors))
+    profiles = render_all(cfg)
+    res = InstallResult()
+    with tempfile.TemporaryDirectory(prefix="caokit-") as stage:
+        for name, text in profiles.items():
+            # `cao install <file>` names the profile after the file stem, so the
+            # staged filename must be exactly the concrete profile name.
+            path = Path(stage) / (name + ".md")
+            path.write_text(text, encoding="utf-8")
+            v = runner(["cao", "profile", "validate", str(path)])
+            if v.returncode != 0:  # validate exits 1 on schema errors; warnings exit 0
+                out(f"validate FAILED for {name}:\n{(v.stdout or '') + (v.stderr or '')}")
+                res.failed.append(name)
+                continue
+            r = runner(["cao", "install", str(path)])
+            if _failed_output(r) and replace_legacy:
+                res.backup_dir = _backup(home, [name], res.backup_dir)
+                out(f"  moved stale copies of {name} to {res.backup_dir}; retrying")
+                r = runner(["cao", "install", str(path)])
+            if _failed_output(r):
+                detail = ((r.stdout or "") + (r.stderr or "")).strip()
+                out(f"install FAILED for {name}:\n{detail}")
+                res.failed.append(name)
+                continue
+            stored = home / "agent-store" / (name + ".md")
+            if not stored.is_file() or stored.read_bytes() != text.encode("utf-8"):
+                out(
+                    f"install verification FAILED for {name}: "
+                    "stored copy differs from rendered profile"
+                )
+                res.failed.append(name)
+                continue
+            out(f"  installed {name} (verified byte for byte)")
+            res.installed.append(name)
+    return res
+
+
+@dataclass
+class UninstallResult:
+    """Per-profile outcome of an uninstall run."""
+
+    removed: list[str] = field(default_factory=list)
+    missing: list[str] = field(default_factory=list)  # no copy anywhere in CAO's home
+    failed: list[str] = field(default_factory=list)
+    backup: Path | None = None  # where leftover ``agent-context`` copies were moved
+
+
+def uninstall_profiles(
+    cfg: Config,
+    home: Path | None = None,
+    runner: Runner = default_runner,
+    apply: bool = False,
+) -> UninstallResult:
+    """Remove the roster's profiles from CAO.
+
+    ``cao profile remove`` deletes only the ``agent-store`` copy. CAO also keeps an
+    ``agent-context`` copy that keeps the profile listed as installed, so that copy is
+    moved to a backup folder (never deleted). Only the names this config renders are
+    touched, so one project's ``<project>_*`` profiles go and no other project's do.
+    Reinstalling restores them.
+
+    Args:
+        cfg: The configuration whose profiles to remove.
+        home: CAO home directory (default :func:`cao_home`).
+        runner: Command runner (injectable for tests).
+        apply: Actually remove. When False nothing is run and every profile with a copy
+            is reported as ``removed``, so the caller can show what would happen.
+
+    Returns:
+        Which profiles were (or would be) removed, were not installed, or failed.
+    """
+    home = home or cao_home()
+    res = UninstallResult()
+    for name in render_all(cfg):
+        in_store = (home / "agent-store" / (name + ".md")).exists()
+        in_context = (home / "agent-context" / (name + ".md")).exists()
+        if not (in_store or in_context):
+            res.missing.append(name)
+        elif not apply:
+            res.removed.append(name)
+        elif in_store and _failed_output(runner(["cao", "profile", "remove", name, "--yes"])):
+            res.failed.append(name)
+        else:
+            res.backup = _backup(home, [name], res.backup)
+            res.removed.append(name)
+    return res

caokit/launch.py

@@ -0,0 +1,102 @@
+"""Build the ``cao`` argv for launching, inspecting, messaging and stopping a company session.
+
+Every command is a pure function from arguments to an argv list, so tests can check exactly
+what would run. The CLI layer is the only caller that executes them.
+"""
+
+import hashlib
+import re
+from pathlib import Path
+
+SESSION_PREFIX = "cao-"  # CAO prepends this to the --session-name it is given
+
+
+def session_name(project: Path, slug: str | None) -> str:
+    """Pick the CAO session name for a project.
+
+    Args:
+        project: Project directory.
+        slug: The project's namespace slug if it has one.
+
+    Returns:
+        ``slug`` if given, else the directory name reduced to lowercase letters, digits and
+        ``-`` plus a short hash of the full path, so two checkouts that share a directory
+        name (``a/app`` and ``b/app``) still get different sessions.
+    """
+    if slug:
+        return slug
+    root = Path(project).resolve()
+    name = re.sub(r"[^a-z0-9]+", "-", root.name.lower()).strip("-")[:40].strip("-") or "company"
+    return f"{name}-{hashlib.sha1(str(root).encode()).hexdigest()[:6]}"
+
+
+def session_id(name: str) -> str:
+    """Return the ID CAO gives a session started with ``--session-name name``.
+
+    CAO adds its prefix only when the name does not already start with it, so a project
+    called ``cao-foo`` is the session ``cao-foo``, not ``cao-cao-foo``.
+    """
+    return name if name.startswith(SESSION_PREFIX) else SESSION_PREFIX + name
+
+
+def build_launch_argv(
+    project: Path,
+    profile: str,
+    session: str | None = None,
+    prompt: str | None = None,
+    headless: bool = False,
+    auto_approve: bool = False,
+    wait: bool = True,
+) -> list[str]:
+    """Build the argv that launches a CAO session for ``profile`` in ``project``.
+
+    The working directory is always explicit and absolute: without it CAO uses
+    the caller's cwd, which once led the General to start in the kit repo
+    instead of the project.
+
+    Args:
+        project: Project directory the session must run in (relative paths are resolved).
+        profile: Concrete CAO profile name, e.g. ``general-claude``.
+        session: Optional CAO session name.
+        prompt: Optional first message for the General.
+        headless: Start detached instead of attaching to the terminal.
+        auto_approve: Skip CAO's launch confirmation. Never grants extra tool access.
+        wait: With ``headless`` and a prompt, wait up to 300s for the General's reply. False
+            passes ``--async``: return once the prompt is delivered.
+
+    Returns:
+        The argv list, starting with ``cao launch``. Never includes ``--yolo``.
+
+    Raises:
+        ValueError: If ``project`` is not an existing directory.
+    """
+    root = Path(project).resolve()
+    if not root.is_dir():
+        raise ValueError(f"project directory does not exist: {root}")
+    argv = ["cao", "launch", "--agents", profile, "--working-directory", str(root)]
+    if session:
+        argv += ["--session-name", session]
+    if headless:
+        argv.append("--headless")
+    if auto_approve:
+        argv.append("--auto-approve")
+    if not wait:
+        argv.append("--async")
+    if prompt:
+        argv += ["--", prompt]  # "--" so a prompt starting with "-" is not read as an option
+    return argv
+
+
+def build_status_argv(session: str) -> list[list[str]]:
+    """Build the commands that show every session and one session's workers."""
+    return [["cao", "session", "list"], ["cao", "session", "status", session, "--workers"]]
+
+
+def build_send_argv(session: str, message: str, timeout: int = 600) -> list[str]:
+    """Build the command that sends ``message`` to a session's General."""
+    return ["cao", "session", "send", "--timeout", str(timeout), "--", session, message]
+
+
+def build_stop_argv(session: str) -> list[str]:
+    """Build the command that shuts one session down. It asks no confirmation."""
+    return ["cao", "shutdown", "--session", session]