canopy-cli 3.1.0__py3-none-any.whl

canopy/agent/runner.py

@@ -0,0 +1,129 @@
+"""Directory-safe shell exec for agents.
+
+Eliminates the agent's ``cd <wrong-dir> && command`` mistake class by
+making the agent pass ``(repo, command, feature?)`` semantically.
+canopy resolves the working directory itself.
+
+Trust boundary: the command string is shell-executed without
+sanitization. The agent IS the trust boundary. The point of this tool
+is path correctness, not command sandboxing.
+"""
+from __future__ import annotations
+
+import subprocess
+import time
+from pathlib import Path
+from typing import Any
+
+from ..actions.errors import BlockerError, FailedError, FixAction
+from ..workspace.workspace import Workspace
+
+
+def run_in_repo(
+    workspace: Workspace,
+    repo: str,
+    command: str,
+    feature: str | None = None,
+    timeout_seconds: int = 60,
+) -> dict[str, Any]:
+    """Run a shell command in a canopy-managed repo or worktree.
+
+    Resolution: if ``feature`` is set and a worktree exists for
+    ``(feature, repo)``, the command runs in the worktree. Otherwise it
+    runs in the repo's main path.
+
+    Returns ``{exit_code, stdout, stderr, cwd, duration_ms}``.
+
+    Raises:
+        BlockerError: if ``repo`` is unknown to the workspace, or
+            ``feature`` is set but doesn't exist.
+        FailedError: if the command times out.
+    """
+    cwd = _resolve_cwd(workspace, repo, feature)
+
+    started = time.monotonic()
+    try:
+        proc = subprocess.run(
+            command,
+            cwd=cwd,
+            shell=True,
+            capture_output=True,
+            text=True,
+            timeout=timeout_seconds,
+        )
+    except subprocess.TimeoutExpired as e:
+        elapsed_ms = (time.monotonic() - started) * 1000
+        raise FailedError(
+            code="timeout",
+            what=f"command exceeded {timeout_seconds}s timeout",
+            actual={"cwd": str(cwd), "command": command},
+            details={
+                "duration_ms": int(elapsed_ms),
+                "timeout_seconds": timeout_seconds,
+                "stdout": e.stdout.decode() if isinstance(e.stdout, bytes) else (e.stdout or ""),
+                "stderr": e.stderr.decode() if isinstance(e.stderr, bytes) else (e.stderr or ""),
+            },
+        )
+    elapsed_ms = (time.monotonic() - started) * 1000
+
+    return {
+        "exit_code": proc.returncode,
+        "stdout": proc.stdout,
+        "stderr": proc.stderr,
+        "cwd": str(cwd),
+        "duration_ms": int(elapsed_ms),
+    }
+
+
+def _resolve_cwd(workspace: Workspace, repo: str, feature: str | None) -> Path:
+    repo_names = {r.config.name for r in workspace.repos}
+    if repo not in repo_names:
+        raise BlockerError(
+            code="unknown_repo",
+            what=f"no repo named '{repo}' in workspace",
+            expected={"available_repos": sorted(repo_names)},
+            actual={"repo": repo},
+            fix_actions=[
+                FixAction(action="status", args={}, safe=True,
+                          preview="canopy status lists configured repos"),
+            ],
+        )
+
+    if feature is None:
+        # Fall back to the canonical-slot context if one is set.
+        # An explicit `feature` arg overrides this; passing None means
+        # "use whatever the user declared as their context (or main)".
+        from ..actions import slots as slots_mod
+        state = slots_mod.read_state(workspace)
+        if state and state.canonical and repo in state.canonical.per_repo_paths:
+            return Path(state.canonical.per_repo_paths[repo])
+        return workspace.get_repo(repo).abs_path
+
+    from ..features.coordinator import FeatureCoordinator
+    coordinator = FeatureCoordinator(workspace)
+    try:
+        resolved = coordinator._resolve_name(feature)
+    except ValueError as e:
+        raise BlockerError(
+            code="ambiguous_feature",
+            what=str(e),
+            details={"feature": feature},
+        )
+
+    features = coordinator._load_features()
+    if resolved not in features:
+        raise BlockerError(
+            code="unknown_feature",
+            what=f"no feature lane named '{feature}'",
+            actual={"feature": feature},
+            details={"resolved": resolved},
+        )
+
+    paths = coordinator.resolve_paths(resolved)
+    if repo in paths:
+        return Path(paths[repo])
+
+    # Repo isn't in the feature lane — fall back to the repo's main path
+    # rather than failing. Caller likely just wants the directory; if the
+    # repo isn't part of the feature, the worktree route doesn't apply.
+    return workspace.get_repo(repo).abs_path

canopy/agent_setup/__init__.py

@@ -0,0 +1,264 @@
+"""Agent setup — install bundled skills and wire canopy MCP into a workspace.
+
+Skills live at ``skills/<name>/SKILL.md`` inside this package and are copied
+into ``~/.claude/skills/<name>/SKILL.md`` so any Claude Code session knows
+to use them. The MCP config (``.mcp.json`` at the workspace root) registers
+canopy-mcp as an MCP server with ``CANOPY_ROOT`` pointing at the workspace.
+
+Both pieces are independent — install skills, MCP, both, or neither.
+``setup_agent`` returns a structured report describing what was done so
+callers can render it.
+
+The bundled skill set today: ``using-canopy`` (always installed by default)
+and ``augment-canopy`` (opt-in via ``--skill augment-canopy``).
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, asdict
+from pathlib import Path
+
+_SKILLS_DIR = Path(__file__).parent / "skills"
+
+DEFAULT_SKILL = "using-canopy"
+
+
+def _user_skills_dir() -> Path:
+    """Resolved at call time so tests that monkeypatch ``HOME`` work."""
+    return Path.home() / ".claude" / "skills"
+
+# Backward-compat alias — doctor.py imports this directly. Points at the
+# bundled source for the default skill.
+_SKILL_SOURCE = _SKILLS_DIR / DEFAULT_SKILL / "SKILL.md"
+
+
+def available_skills() -> tuple[str, ...]:
+    """Return the names of all bundled skills (directories under ``skills/``)."""
+    if not _SKILLS_DIR.exists():
+        return ()
+    return tuple(sorted(
+        d.name for d in _SKILLS_DIR.iterdir()
+        if d.is_dir() and (d / "SKILL.md").exists()
+    ))
+
+
+def skill_source(name: str = DEFAULT_SKILL) -> Path:
+    """Path to the bundled SKILL.md for the named skill."""
+    return _SKILLS_DIR / name / "SKILL.md"
+
+
+def skill_install_target(name: str = DEFAULT_SKILL) -> Path:
+    """Default install location for the named skill."""
+    return _user_skills_dir() / name / "SKILL.md"
+
+
+def mcp_config_path(workspace_root: Path) -> Path:
+    """Default location for the workspace's MCP config."""
+    return workspace_root / ".mcp.json"
+
+
+@dataclass
+class SkillResult:
+    action: str        # "installed", "reinstalled", "skipped"
+    path: str
+    reason: str | None = None
+    name: str = DEFAULT_SKILL
+
+
+@dataclass
+class McpResult:
+    action: str        # "added", "updated", "skipped", "created"
+    path: str
+    reason: str | None = None
+
+
+def install_skill(name: str = DEFAULT_SKILL, *, reinstall: bool = False) -> SkillResult:
+    """Install the named skill into ~/.claude/skills/<name>/SKILL.md.
+
+    If a skill file already exists and isn't ours, leaves it alone unless
+    ``reinstall=True``. Detection: the source skill file's full body is
+    written verbatim, so we can byte-compare to know if it's ours.
+
+    Raises ``FileNotFoundError`` if the named skill isn't bundled.
+    """
+    source = skill_source(name)
+    if not source.exists():
+        raise FileNotFoundError(
+            f"No bundled skill named '{name}'. Available: {', '.join(available_skills()) or '(none)'}",
+        )
+    target = skill_install_target(name)
+    source_text = source.read_text()
+
+    if target.exists():
+        existing = target.read_text()
+        if existing == source_text:
+            return SkillResult(
+                action="skipped", path=str(target), name=name,
+                reason="already up to date",
+            )
+        if not reinstall and f"name: {name}" not in existing:
+            return SkillResult(
+                action="skipped", path=str(target), name=name,
+                reason="foreign skill present; use --reinstall to overwrite",
+            )
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(source_text)
+        return SkillResult(action="reinstalled", path=str(target), name=name)
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(source_text)
+    return SkillResult(action="installed", path=str(target), name=name)
+
+
+def install_mcp(workspace_root: Path, *, reinstall: bool = False) -> McpResult:
+    """Add (or update) a 'canopy' entry in the workspace's .mcp.json.
+
+    Merges with any existing ``mcpServers`` block. If a 'canopy' entry
+    already exists with the right shape, leaves it alone unless
+    ``reinstall=True``.
+    """
+    workspace_root = workspace_root.resolve()
+    target = mcp_config_path(workspace_root)
+    desired = {
+        "command": "canopy-mcp",
+        "args": [],
+        "env": {"CANOPY_ROOT": str(workspace_root)},
+    }
+
+    config: dict
+    created = False
+    if target.exists():
+        try:
+            config = json.loads(target.read_text())
+        except json.JSONDecodeError:
+            return McpResult(action="skipped", path=str(target),
+                              reason="existing .mcp.json is not valid JSON; refusing to overwrite")
+        if not isinstance(config, dict):
+            return McpResult(action="skipped", path=str(target),
+                              reason="existing .mcp.json root is not an object")
+    else:
+        config = {}
+        created = True
+
+    servers = config.setdefault("mcpServers", {})
+    if not isinstance(servers, dict):
+        return McpResult(action="skipped", path=str(target),
+                          reason="existing mcpServers block is not an object")
+
+    if "canopy" in servers and not reinstall:
+        existing = servers["canopy"]
+        if (isinstance(existing, dict)
+                and existing.get("command") == "canopy-mcp"
+                and (existing.get("env") or {}).get("CANOPY_ROOT") == desired["env"]["CANOPY_ROOT"]):
+            return McpResult(action="skipped", path=str(target),
+                              reason="canopy entry already present and current")
+
+    servers["canopy"] = desired
+    target.write_text(json.dumps(config, indent=2) + "\n")
+    return McpResult(
+        action=("created" if created else ("added" if "canopy" not in (servers or {}) else "updated")),
+        path=str(target),
+    )
+
+
+def check_status(workspace_root: Path) -> dict:
+    """Report what's installed without changing anything.
+
+    Returns ``{skill, skills, mcp}``:
+
+    - ``skill`` — the default ``using-canopy`` entry (kept for
+      backward-compat with existing callers / dashboard).
+    - ``skills`` — every bundled skill's install state, including
+      opt-ins like ``augment-canopy`` once they're installed (M4
+      revealed that ``--check`` only reported the default; F-9).
+    - ``mcp`` — the workspace's ``.mcp.json`` canopy entry state.
+    """
+    skill_state = check_skill_status(DEFAULT_SKILL)
+    skills_state = [check_skill_status(name) for name in available_skills()]
+
+    mcp_target = mcp_config_path(workspace_root)
+    mcp_state = {"path": str(mcp_target), "configured": False}
+    if mcp_target.exists():
+        try:
+            cfg = json.loads(mcp_target.read_text())
+            servers = (cfg.get("mcpServers") if isinstance(cfg, dict) else {}) or {}
+            entry = servers.get("canopy") if isinstance(servers, dict) else None
+            mcp_state["configured"] = bool(
+                isinstance(entry, dict) and entry.get("command") == "canopy-mcp"
+            )
+            mcp_state["env"] = (entry or {}).get("env", {}) if isinstance(entry, dict) else {}
+        except json.JSONDecodeError:
+            mcp_state["error"] = "invalid JSON"
+
+    return {"skill": skill_state, "skills": skills_state, "mcp": mcp_state}
+
+
+def check_skill_status(name: str) -> dict:
+    """Report install state for a single named skill."""
+    source = skill_source(name)
+    target = skill_install_target(name)
+    state = {
+        "name": name,
+        "path": str(target),
+        "installed": target.exists(),
+        "is_canopy_skill": False,
+        "up_to_date": False,
+    }
+    if target.exists() and source.exists():
+        existing = target.read_text()
+        state["is_canopy_skill"] = f"name: {name}" in existing
+        state["up_to_date"] = existing == source.read_text()
+    return state
+
+
+def setup_agent(
+    workspace_root: Path | None,
+    *,
+    skills: tuple[str, ...] = (DEFAULT_SKILL,),
+    do_mcp: bool = True,
+    reinstall: bool = False,
+    do_skill: bool | None = None,
+) -> dict:
+    """Install one or more skills + (optionally) wire MCP.
+
+    ``skills`` is the tuple of bundled skill names to install. Defaults to
+    just ``using-canopy``. Pass ``()`` to skip all skill installs.
+
+    ``do_skill`` is a backward-compat alias — when ``do_skill=False`` is
+    passed, no skills are installed regardless of the ``skills`` arg.
+    """
+    if do_skill is False:
+        skills = ()
+
+    out: dict = {}
+    if skills:
+        results = []
+        for name in skills:
+            try:
+                results.append(asdict(install_skill(name, reinstall=reinstall)))
+            except FileNotFoundError as e:
+                results.append({
+                    "action": "skipped",
+                    "path": str(skill_install_target(name)),
+                    "name": name,
+                    "reason": str(e),
+                })
+        # Preserve legacy single-skill report at "skill" for callers that
+        # only know about the default skill.
+        default = next(
+            (r for r in results if r.get("name") == DEFAULT_SKILL),
+            results[0] if results else None,
+        )
+        if default is not None:
+            out["skill"] = default
+        out["skills"] = results
+
+    if do_mcp:
+        if workspace_root is None:
+            out["mcp"] = {
+                "action": "skipped", "path": "",
+                "reason": "no workspace_root (run from inside a canopy workspace)",
+            }
+        else:
+            out["mcp"] = asdict(install_mcp(workspace_root, reinstall=reinstall))
+    return out

canopy/agent_setup/skills/augment-canopy/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: augment-canopy
+description: Use when the user wants to customize how canopy operations behave for this workspace — overriding the preflight command, listing which review-comment authors count as bots, choosing a custom test command, or otherwise tuning canopy.toml's [augments] block. Lets the agent edit canopy.toml directly and confirm the new behavior takes effect on the next operation.
+---
+
+# augment-canopy
+
+Per-workspace customization for canopy operations that vary by team or codebase. Lives in `canopy.toml` under an `[augments]` block (workspace defaults) plus optional per-repo overrides on `[[repos]]` entries.
+
+## When to invoke
+
+Listen for cues like:
+
+- *"Use ruff for preflight here, not pre-commit."*
+- *"Track CodeRabbit and Korbit comments; ignore Copilot."*
+- *"This workspace runs `make check` before commits."*
+- *"For the api repo specifically, run `uv run pytest tests/fast` as preflight."*
+- *"Make `canopy preflight` run X."*
+
+These are all augment edits — read canopy.toml, mutate the right block, atomic-write back, confirm with the user.
+
+Do **not** invoke for:
+
+- Adding/removing repos (use `canopy init` or edit `[[repos]]` blocks normally — that's structural config, not behavioral augments).
+- Changing which issue tracker the workspace uses (that's `[issue_provider]`, a separate concern with its own provider abstraction).
+- Per-feature overrides (not supported in v1 — augments are workspace + per-repo only).
+
+## Schema
+
+Workspace defaults under `[augments]`; per-repo overrides on each `[[repos]]` entry. **Per-repo wins on key collision.**
+
+```toml
+[augments]
+preflight_cmd = "make check"             # workspace default for all repos
+test_cmd = "pytest"                      # consumed by future `canopy test`
+review_bots = ["coderabbit", "korbit"]   # case-insensitive author substring (M3 bot-tracking)
+
+[[repos]]
+name = "api"
+path = "./api"
+augments = { preflight_cmd = "uv run pytest tests/fast" }   # api-only override
+```
+
+### Recognized keys (v1)
+
+| Key | Type | Consumed by | Notes |
+|---|---|---|---|
+| `preflight_cmd` | string | `canopy preflight` (and `review_prep` path inside `coordinator.py`) | Runs via `sh -c` so pipes / `&&` chains work |
+| `test_cmd` | string | future `canopy test` (not v1) | Schema-reserved; safe to set |
+| `review_bots` | list[string] | M3 bot-comment tracking | Workspace-level only; per-repo overrides ignored for this key |
+| `auto_resolve_threads_on_address` | bool | `canopy commit --address <id>` | When true, `canopy commit --address <id>` auto-resolves the corresponding GH review thread after push. `--no-resolve-thread` overrides. Default: false. |
+
+Unknown keys are silently preserved by the parser — future augments don't require schema migration.
+
+## How to mutate canopy.toml safely
+
+The augment block is **not** reachable through `canopy config get/set` in v1 (that command is flat-only). Edit the TOML file directly. Use this recipe:
+
+1. **Resolve the path.** The workspace root is the directory containing `canopy.toml`. If the user is in a feature worktree, walk up to find it. The MCP tool `mcp__canopy__workspace_status` returns `workspace_root` if you need it.
+2. **Read + parse.** Use `tomllib` (Python ≥3.11) or `tomli`. Preserve unknown keys.
+3. **Mutate the right block.**
+   - Workspace default: `data.setdefault("augments", {})[key] = value`
+   - Per-repo override: find the matching entry in `data["repos"]` by `name`, then `entry.setdefault("augments", {})[key] = value`
+4. **Atomic write.** Write to a temp file in the same directory, then `os.replace(tmp, canopy_toml)`. This avoids partial writes if the process is interrupted.
+5. **Confirm with the user.** Echo the change back: *"Set `augments.preflight_cmd = 'ruff check .'` in canopy.toml. The next `canopy preflight` run will use it."*
+
+No canopy restart needed — every operation re-reads canopy.toml. Changes take effect on the next call.
+
+## Worked example
+
+User: *"Set up this workspace to run `ruff check . && pyright` before every commit, and to track CodeRabbit + Korbit as the bot reviewers I care about."*
+
+Agent should:
+
+1. Find `canopy.toml` (current dir or via `workspace_status`).
+2. Read + parse it.
+3. Add or update the `[augments]` block:
+   ```python
+   data.setdefault("augments", {})
+   data["augments"]["preflight_cmd"] = "ruff check . && pyright"
+   data["augments"]["review_bots"] = ["coderabbit", "korbit"]
+   ```
+4. Atomic write back.
+5. Reply:
+   > Updated canopy.toml:
+   > - `augments.preflight_cmd = "ruff check . && pyright"`
+   > - `augments.review_bots = ["coderabbit", "korbit"]`
+   >
+   > The next `canopy preflight` will run the new command. Bot-comment tracking uses the `review_bots` list.
+
+## Per-repo override example
+
+User: *"For the api repo only, preflight should be `uv run pytest tests/fast` — keep the workspace default for everything else."*
+
+```python
+api_entry = next(r for r in data["repos"] if r["name"] == "api")
+api_entry.setdefault("augments", {})
+api_entry["augments"]["preflight_cmd"] = "uv run pytest tests/fast"
+```
+
+Atomic write, confirm:
+
+> Set per-repo augment for `api`: `preflight_cmd = "uv run pytest tests/fast"`. Other repos still use the workspace default (`make check`).
+
+## Edge cases
+
+- **No `[augments]` block yet.** Create it. The parser handles a missing block as `{}`.
+- **Concurrent edits.** Two agents writing simultaneously can clobber each other; the atomic-write minimizes the race window. If you read-then-write and the file mtime changed in between, re-read and retry once. On second failure, surface a `BlockerError`.
+- **Symlinked canopy.toml.** Resolve via `Path.resolve()`; write to the resolved directory.
+- **Invalid command in `preflight_cmd`.** Surfaces as a non-zero exit code at run time. Doesn't crash canopy. The user can fix by re-invoking this skill.
+
+## Don't
+
+- Don't add validation logic here — the parser is intentionally lenient. Validation (typo detection, unknown-key warnings) lives in `canopy doctor`.
+- Don't introduce nested-key syntax via `canopy config augments.preflight_cmd` — that's a future refactor of `cmd_config`. v1 writes TOML directly.
+- Don't alter `[issue_provider]` or `[[repos]]` structural fields from this skill — those are different concerns.