canopy-cli 3.1.0__py3-none-any.whl

canopy/actions/switch_preflight.py

@@ -0,0 +1,192 @@
+"""Preflight for ``switch`` — predictable-failure detection without state mutation.
+
+Catches the classes of failure that are knowable from the current
+filesystem + git state alone:
+
+  - target branch missing in any repo (and not creatable from default)
+  - leftover warm-worktree directory from a previous failed run
+  - git index lock currently held in any participating repo
+  - cap reached + no fix path acceptable (active-rotation past warm cap)
+
+Returns ``None`` when everything checks out; raises a structured
+``BlockerError`` with all detected issues otherwise. Bundling per-repo
+failures into one error means the user sees the full picture in one
+shot instead of fixing one issue at a time.
+
+Defense-in-depth: preflight catches ~80% of failures cheaply. The rest
+(disk fills mid-op, network blip during fetch, IDE racing the checkout)
+need the rollback walker — that's PR2.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..git import repo as git
+from ..workspace.workspace import Workspace
+from . import slots as slots_mod
+from .errors import BlockerError, FixAction
+
+
+# Default cap when slots is unset. The config parser already defaults
+# `slots` to 2, so this is purely defensive.
+DEFAULT_WARM_SLOT_CAP = 2
+
+
+def warm_slot_cap(workspace: Workspace) -> int:
+    """Return the warm-slot cap honored by switch's canonical-slot logic."""
+    raw = workspace.config.slots
+    return raw if raw and raw > 0 else DEFAULT_WARM_SLOT_CAP
+
+
+def preflight(
+    workspace: Workspace,
+    feature_to_activate: str,
+    repo_branches: dict[str, str],
+    *,
+    release_current: bool = False,
+    no_evict: bool = False,
+    evict_to: str | None = None,
+) -> dict[str, Any]:
+    """Pre-validate a ``switch`` call. Raises ``BlockerError`` on failure.
+
+    Args:
+        feature_to_activate: the feature being promoted to canonical (Y).
+        repo_branches: per-repo branch map for Y, from ``repos_for_feature``.
+        release_current: if True (wind-down mode), the cap-reached check
+            is skipped (X goes cold, no warm slot consumed).
+        no_evict: in active-rotation mode, refuse to evict an LRU warm
+            worktree when the cap is full instead of asking the user.
+        evict_to: if set, the user has pinned a destination slot for X.
+            Skip the cap-fire check — the explicit-slot path (in switch)
+            handles validation + eviction of any occupant.
+
+    Returns a small fact dict the caller can use to make decisions:
+    ``{branches_to_create: [(repo, branch)], cap_will_fire: bool,
+       lru_eviction_candidate: <feature> | None,
+       previously_canonical: <feature> | None}``.
+    """
+    # Per-repo branch + path checks
+    branches_to_create: list[tuple[str, str]] = []
+    issues: list[dict[str, Any]] = []
+
+    for repo_name, branch in repo_branches.items():
+        try:
+            state = workspace.get_repo(repo_name)
+        except KeyError:
+            issues.append({
+                "repo": repo_name,
+                "kind": "repo_not_in_workspace",
+                "what": f"repo '{repo_name}' not in canopy.toml",
+            })
+            continue
+        repo_path = state.abs_path
+
+        # Lock check — git refuses to operate while index.lock exists
+        if (repo_path / ".git" / "index.lock").exists():
+            issues.append({
+                "repo": repo_name,
+                "kind": "index_lock_held",
+                "what": (
+                    f".git/index.lock present in {repo_name} — another git"
+                    " process may be running"
+                ),
+            })
+
+        # Branch existence — we'll create from default if missing
+        if not git.branch_exists(repo_path, branch):
+            branches_to_create.append((repo_name, branch))
+
+    # Read the slot state (3.0 layout). previously_canonical is the
+    # canonical feature, if any, that differs from Y.
+    state = slots_mod.read_state(workspace)
+    previously_canonical: str | None = None
+    if state and state.canonical and state.canonical.feature != feature_to_activate:
+        previously_canonical = state.canonical.feature
+
+    already_warm: set[str] = (
+        {e.feature for e in state.slots.values()} if state else set()
+    )
+
+    # Cap-will-fire check (only active-rotation mode evacuates X to warm).
+    # When the user pinned a destination via ``--evict-to``, the
+    # explicit-slot path in switch handles validation + occupant
+    # eviction, so skip the cap-fire surface here.
+    cap_will_fire = False
+    lru_eviction_candidate: str | None = None
+    if previously_canonical and not release_current and evict_to is None:
+        cap = warm_slot_cap(workspace)
+        # Y is becoming canonical, so if Y was warm it leaves the warm set;
+        # X (previously_canonical) is joining the warm set.
+        post_switch_warm = (already_warm - {feature_to_activate}) | {previously_canonical}
+        if len(post_switch_warm) > cap:
+            cap_will_fire = True
+            lru_eviction_candidate = slots_mod.lru_evictee(
+                state, exclude={feature_to_activate},
+            )
+            if no_evict or lru_eviction_candidate is None:
+                issues.append({
+                    "kind": "worktree_cap_reached",
+                    "what": (
+                        f"adding {previously_canonical} as warm would exceed"
+                        f" warm_slot_cap={cap} (currently warm:"
+                        f" {sorted(already_warm)})"
+                    ),
+                    "current_warm": sorted(already_warm),
+                    "cap": cap,
+                })
+
+    if issues:
+        cap_issue = next((i for i in issues if i.get("kind") == "worktree_cap_reached"), None)
+        if cap_issue:
+            raise BlockerError(
+                code="worktree_cap_reached",
+                what=cap_issue["what"],
+                expected={"warm_slot_cap": cap_issue["cap"]},
+                actual={"warm_now": cap_issue["current_warm"]},
+                fix_actions=[
+                    FixAction(
+                        action="switch",
+                        args={"feature": feature_to_activate, "release_current": True},
+                        safe=False,
+                        preview=(
+                            f"wind-down mode: {previously_canonical} goes"
+                            f" cold (with stash), no eviction needed"
+                        ),
+                    ),
+                    FixAction(
+                        action="switch",
+                        args={
+                            "feature": feature_to_activate,
+                            "evict": lru_eviction_candidate,
+                        } if lru_eviction_candidate else {"feature": feature_to_activate},
+                        safe=False,
+                        preview=(
+                            f"evict LRU warm worktree"
+                            f" '{lru_eviction_candidate}' to cold"
+                            if lru_eviction_candidate
+                            else "no LRU candidate found — set last_touched manually"
+                        ),
+                    ),
+                    FixAction(
+                        action="workspace_config",
+                        args={"slots": cap_issue["cap"] + 1},
+                        safe=True,
+                        preview=f"raise warm_slot_cap to {cap_issue['cap'] + 1}",
+                    ),
+                ],
+                details={"all_issues": issues},
+            )
+        # Non-cap blockers
+        raise BlockerError(
+            code="switch_preflight_failed",
+            what=f"{len(issues)} issue(s) detected before switch could proceed",
+            details={"issues": issues},
+        )
+
+    return {
+        "branches_to_create": branches_to_create,
+        "cap_will_fire": cap_will_fire,
+        "lru_eviction_candidate": lru_eviction_candidate,
+        "previously_canonical": previously_canonical,
+    }

canopy/actions/thread_actions.py

@@ -0,0 +1,88 @@
+"""Thread action wrappers — resolve, reply, unresolve a GitHub review thread.
+
+Each wrapper calls the GitHub integration and records the event locally in
+``.canopy/state/thread_resolutions.json`` so the resume brief can attribute
+"resolved by canopy" vs "resolved on GitHub directly".
+"""
+from __future__ import annotations
+
+from ..workspace.workspace import Workspace
+from .errors import ActionError, BlockerError
+from . import thread_resolutions as tr
+
+
+def _validate_thread_id(thread_id: str) -> None:
+    if not thread_id.startswith("PRRT_"):
+        raise BlockerError(
+            code="invalid_thread_id",
+            what=f"thread_id must start with 'PRRT_'; got {thread_id!r}",
+        )
+
+
+def resolve_thread(
+    workspace: Workspace,
+    thread_id: str,
+    *,
+    feature: str,
+    via_command: str = "resolve",
+    via_commit_sha: str | None = None,
+) -> dict:
+    """Resolve a GitHub PR review thread and record it locally.
+
+    Steps:
+    1. Validate thread_id format.
+    2. Call the GitHub GraphQL mutation.
+    3. Log the resolution to ``.canopy/state/thread_resolutions.json``.
+    4. Return the combined result.
+
+    Raises:
+        BlockerError: if ``thread_id`` does not start with ``PRRT_``.
+    """
+    from ..integrations import github as gh
+
+    _validate_thread_id(thread_id)
+    gh_result = gh.resolve_thread(workspace.config.root, thread_id)
+    log_entry = tr.record(
+        workspace.config.root,
+        thread_id=thread_id,
+        feature=feature,
+        via_command=via_command,
+        via_commit_sha=via_commit_sha,
+    )
+    return {**gh_result, "logged": log_entry}
+
+
+def reply_to_thread(
+    workspace: Workspace,
+    thread_id: str,
+    body: str,
+    *,
+    feature: str,
+    resolve_after: bool = False,
+) -> dict:
+    """Post a reply to a GitHub PR review thread, optionally resolving it.
+
+    Steps:
+    1. Validate thread_id format.
+    2. Post the reply via the GitHub GraphQL mutation.
+    3. If ``resolve_after`` is True, resolve the thread and include the result.
+
+    Returns a dict with ``posted`` and optionally ``resolved`` keys.
+
+    Raises:
+        BlockerError: if ``thread_id`` does not start with ``PRRT_``.
+    """
+    from ..integrations import github as gh
+
+    _validate_thread_id(thread_id)
+    posted = gh.reply_to_thread(workspace.config.root, thread_id, body)
+    result: dict = {"posted": posted}
+    if resolve_after:
+        try:
+            res = resolve_thread(
+                workspace, thread_id, feature=feature, via_command="reply_resolve",
+            )
+            result["resolved"] = res
+        except ActionError as e:
+            result["resolved"] = {"error": e.to_dict()}
+    return result

canopy/actions/thread_resolutions.py

@@ -0,0 +1,101 @@
+"""Thread resolution log — persistent record of threads resolved via canopy.
+
+State file: .canopy/state/thread_resolutions.json (atomic temp+rename writes).
+
+Schema::
+
+    {
+      "PRRT_abc": {
+        "resolved_by_canopy_at": "2026-05-29T12:00:00Z",
+        "feature": "auth-flow",
+        "via_command": "resolve" | "commit_address" | "reply_resolve",
+        "via_commit_sha": "abc1234" | null
+      }
+    }
+
+Used by the resume brief to attribute "resolved by canopy" vs "resolved on
+GitHub directly" — only canopy-initiated resolutions appear here.
+"""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def _state_path(workspace_root: Path) -> Path:
+    return workspace_root / ".canopy" / "state" / "thread_resolutions.json"
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def load(workspace_root: Path) -> dict:
+    """Return the full log dict. Missing file returns an empty dict."""
+    path = _state_path(workspace_root)
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text())
+        if isinstance(data, dict):
+            return data
+    except (OSError, json.JSONDecodeError):
+        pass
+    return {}
+
+
+def record(
+    workspace_root: Path,
+    *,
+    thread_id: str,
+    feature: str,
+    via_command: str,
+    via_commit_sha: str | None = None,
+) -> dict:
+    """Append or overwrite a thread resolution entry. Returns the entry written.
+
+    Atomic write: mkstemp in same dir → write → os.replace.
+    """
+    log = load(workspace_root)
+    entry = {
+        "resolved_by_canopy_at": _now_iso(),
+        "feature": feature,
+        "via_command": via_command,
+        "via_commit_sha": via_commit_sha,
+    }
+    log[thread_id] = entry
+
+    path = _state_path(workspace_root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    fd, tmp_path = tempfile.mkstemp(dir=path.parent, suffix=".json.tmp")
+    try:
+        with os.fdopen(fd, "w") as fh:
+            json.dump(log, fh, indent=2)
+        os.replace(tmp_path, path)
+    except Exception:
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise
+
+    return entry
+
+
+def filter_since(workspace_root: Path, since_iso: str) -> dict:
+    """Return only entries with ``resolved_by_canopy_at`` >= ``since_iso``.
+
+    Comparison is lexicographic on the ISO 8601 Z strings (safe because they
+    are always produced in the same zero-padded format by ``_now_iso``).
+    """
+    log = load(workspace_root)
+    return {
+        tid: entry
+        for tid, entry in log.items()
+        if isinstance(entry, dict)
+        and entry.get("resolved_by_canopy_at", "") >= since_iso
+    }

canopy/actions/triage.py

@@ -0,0 +1,286 @@
+"""triage(author) — the agent's daily entry point.
+
+Enumerates open PRs across all configured repos, groups by feature lane
+(explicit from features.json or implicit by shared branch name), runs
+each group's review comments through the temporal classifier, and tags
+each feature with a priority tier:
+
+    changes_requested  > review_required_with_bot_comments
+                       > review_required
+                       > approved
+
+Designed for the user's morning workflow: ``canopy triage`` returns a
+single ordered list of "what needs my attention right now".
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from ..integrations import github as gh
+from ..workspace.workspace import Workspace
+from . import slots as slots_mod
+from .aliases import _resolve_owner_slug
+from .errors import BlockerError
+from .review_filter import classify_threads
+
+
+_PRIORITY_ORDER = {
+    "changes_requested": 0,
+    "review_required_with_bot_comments": 1,
+    "review_required": 2,
+    "approved": 3,
+    "unknown": 4,
+}
+
+
+def triage(
+    workspace: Workspace,
+    author: str = "@me",
+    repos: list[str] | None = None,
+) -> dict[str, Any]:
+    """Return prioritized list of features needing user attention.
+
+    Args:
+        workspace: loaded workspace.
+        author: GitHub username/handle to filter PRs by; ``@me`` is
+            the gh CLI shorthand for the authenticated user.
+        repos: subset of canopy repos to scan (default: all).
+
+    Returns:
+        ``{author, canonical_feature, features: [{feature, linear_issue,
+        linear_url, linear_title, priority, is_canonical, physical_state,
+        repos: {<r>: {pr_number, pr_url, pr_title, branch, review_decision,
+        actionable_count, likely_resolved_count, has_actionable_bot_thread,
+        physical_state, path}}}]}`` ordered most-urgent first.
+
+        ``physical_state`` per feature is ``canonical | warm | cold | none``
+        (none = no worktree, branch may not even be checked out anywhere).
+        Per-repo ``physical_state`` + ``path`` lets the agent decide
+        whether to switch first or just `canopy_run` against the recorded
+        path.
+
+    Raises:
+        BlockerError: if no GitHub transport is available, or if a
+            requested repo is unknown.
+    """
+    target_repos = _select_repos(workspace, repos)
+    prs_by_repo = _fetch_open_prs(workspace, target_repos, author)
+    feature_groups = _group_by_feature(workspace, prs_by_repo)
+    state = slots_mod.read_state(workspace)
+    canonical_feature = state.canonical.feature if state and state.canonical else None
+    enriched = [_enrich(workspace, g, canonical_feature) for g in feature_groups]
+    enriched.sort(key=lambda f: _PRIORITY_ORDER.get(f["priority"], 99))
+    return {
+        "author": author,
+        "canonical_feature": canonical_feature,
+        "features": enriched,
+    }
+
+
+def _fetch_open_prs(
+    workspace: Workspace, target_repos: list[str], author: str,
+) -> dict[str, list[dict]]:
+    out: dict[str, list[dict]] = {}
+    for repo_name in target_repos:
+        try:
+            owner, slug = _resolve_owner_slug(workspace, repo_name)
+        except BlockerError:
+            # Repo with no parseable github remote — skip silently
+            out[repo_name] = []
+            continue
+        try:
+            out[repo_name] = gh.list_open_prs(
+                workspace.config.root, owner, slug, author=author,
+            )
+        except gh.GitHubNotConfiguredError as e:
+            from .errors import FixAction
+            payload = e.payload or {}
+            fix_actions = [
+                FixAction(action=fa["action"], args=fa.get("args", {}),
+                          safe=fa.get("safe", True), preview=fa.get("preview"))
+                for fa in payload.get("fix_actions", [])
+            ]
+            raise BlockerError(
+                code=payload.get("code", "github_not_configured"),
+                what=payload.get("what", str(e)),
+                fix_actions=fix_actions,
+                details={"repo": repo_name},
+            )
+    return out
+
+
+def _group_by_feature(
+    workspace: Workspace, prs_by_repo: dict[str, list[dict]],
+) -> list[dict]:
+    """Group PRs into feature lanes.
+
+    Strategy:
+      1. Build (repo, branch) → pr index.
+      2. For each explicit feature in features.json, claim PRs whose
+         branch matches the lane's expected branch *for that repo*
+         (using the per-repo ``branches`` override map when set, else
+         feature name). This is what groups
+         ``auth-flow`` (api) + ``auth-flow-v2`` (ui) into one
+         feature lane.
+      3. Remaining (repo, branch) pairs that weren't consumed become
+         implicit features: each branch becomes a feature, multi-repo
+         when the same branch appears in 2+ repos, single-repo otherwise.
+    """
+    from ..features.coordinator import FeatureCoordinator
+
+    by_repo_branch: dict[tuple[str, str], dict] = {}
+    for repo_name, prs in prs_by_repo.items():
+        for pr in prs:
+            branch = pr.get("head_branch") or ""
+            if not branch:
+                continue
+            by_repo_branch[(repo_name, branch)] = pr
+
+    coord = FeatureCoordinator(workspace)
+    features = coord._load_features()
+    consumed: set[tuple[str, str]] = set()
+    groups: list[dict] = []
+
+    for feature_name, feature_data in features.items():
+        if feature_data.get("status") != "active":
+            continue
+        feature_repos = list(feature_data.get("repos") or [])
+        branches_map = feature_data.get("branches") or {}
+
+        repos_for_feature: dict[str, dict] = {}
+        for repo_name in feature_repos:
+            expected_branch = branches_map.get(repo_name, feature_name)
+            key = (repo_name, expected_branch)
+            if key in by_repo_branch and key not in consumed:
+                repos_for_feature[repo_name] = by_repo_branch[key]
+                consumed.add(key)
+
+        if not repos_for_feature:
+            continue
+        groups.append({
+            "feature": feature_name,
+            "linear_issue": feature_data.get("linear_issue", ""),
+            "linear_url": feature_data.get("linear_url", ""),
+            "linear_title": feature_data.get("linear_title", ""),
+            "repos": repos_for_feature,
+        })
+
+    # Remaining (repo, branch) pairs become implicit feature groups.
+    # Same branch across repos → one group; otherwise per-branch group.
+    remaining_by_branch: dict[str, dict[str, dict]] = {}
+    for (repo_name, branch), pr in by_repo_branch.items():
+        if (repo_name, branch) in consumed:
+            continue
+        remaining_by_branch.setdefault(branch, {})[repo_name] = pr
+
+    for branch, repos in remaining_by_branch.items():
+        groups.append({
+            "feature": branch,
+            "linear_issue": "",
+            "linear_url": "",
+            "linear_title": "",
+            "repos": repos,
+        })
+
+    return groups
+
+
+def _enrich(
+    workspace: Workspace, group: dict, canonical_feature: str | None,
+) -> dict:
+    feature_name = group["feature"]
+    is_canonical = canonical_feature == feature_name
+    per_repo: dict[str, dict] = {}
+    for canopy_repo, pr in group["repos"].items():
+        owner, slug = _resolve_owner_slug(workspace, canopy_repo)
+        comments, _resolved = gh.get_review_comments(
+            workspace.config.root, owner, slug, pr["number"],
+        )
+        state = workspace.get_repo(canopy_repo)
+        classification = classify_threads(
+            comments, state.abs_path, pr.get("head_branch") or "",
+        )
+        actionable = classification["actionable_threads"]
+
+        # Physical state per repo: where this feature lives right now.
+        slot_id = slots_mod.slot_for_feature(workspace, feature_name)
+        wt = (
+            slots_mod.slot_worktree_path(workspace, slot_id, canopy_repo)
+            if slot_id else None
+        )
+        if is_canonical:
+            phys = "canonical"
+            path = str(state.abs_path.resolve())
+        elif wt is not None and wt.exists() and (wt / ".git").exists():
+            phys = "warm"
+            path = str(wt.resolve())
+        else:
+            phys = "cold"
+            path = ""    # no on-disk home yet; switch will create one
+
+        per_repo[canopy_repo] = {
+            "pr_number": pr["number"],
+            "pr_url": pr.get("url", ""),
+            "pr_title": pr.get("title", ""),
+            "branch": pr.get("head_branch", ""),
+            "review_decision": pr.get("review_decision", ""),
+            "actionable_count": len(actionable),
+            "likely_resolved_count": len(classification["likely_resolved_threads"]),
+            "has_actionable_bot_thread": any(
+                t.get("author_type") == "Bot" for t in actionable
+            ),
+            "physical_state": phys,
+            "path": path,
+        }
+
+    # Top-level physical_state is the highest-resolution per-repo state.
+    # canonical > warm > cold. (If repos disagree we report the warmest.)
+    states = {r["physical_state"] for r in per_repo.values()}
+    if "canonical" in states:
+        feat_phys = "canonical"
+    elif "warm" in states:
+        feat_phys = "warm" if states <= {"warm", "cold"} else "mixed"
+    else:
+        feat_phys = "cold"
+
+    return {
+        "feature": feature_name,
+        "linear_issue": group["linear_issue"],
+        "linear_url": group["linear_url"],
+        "linear_title": group["linear_title"],
+        "priority": _compute_priority(per_repo),
+        "is_canonical": is_canonical,
+        "physical_state": feat_phys,
+        "repos": per_repo,
+    }
+
+
+def _compute_priority(per_repo: dict[str, dict]) -> str:
+    decisions = {info.get("review_decision", "") for info in per_repo.values()}
+    bot_actionable = any(
+        info.get("has_actionable_bot_thread") for info in per_repo.values()
+    )
+
+    if "CHANGES_REQUESTED" in decisions:
+        return "changes_requested"
+    non_empty = {d for d in decisions if d}
+    if non_empty and non_empty <= {"APPROVED"}:
+        return "approved"
+    if bot_actionable:
+        return "review_required_with_bot_comments"
+    return "review_required"
+
+
+def _select_repos(workspace: Workspace, requested: list[str] | None) -> list[str]:
+    all_names = [r.config.name for r in workspace.repos]
+    if requested is None:
+        return all_names
+    unknown = [r for r in requested if r not in set(all_names)]
+    if unknown:
+        raise BlockerError(
+            code="unknown_repo",
+            what=f"unknown repos: {', '.join(unknown)}",
+            expected={"available_repos": sorted(all_names)},
+            details={"requested": list(requested)},
+        )
+    return list(requested)

canopy/agent/__init__.py

@@ -0,0 +1,5 @@
+"""Agent-facing surface: tools that exist primarily to make agent tool
+calls mistake-proof (path resolution, ad-hoc command exec, etc.)."""
+from .runner import run_in_repo
+
+__all__ = ["run_in_repo"]