canopy-cli 3.1.0__py3-none-any.whl

canopy/actions/last_visit.py

@@ -0,0 +1,83 @@
+"""Per-feature last-visit anchor for the feature-resume brief.
+
+State file: .canopy/state/visits.json
+Schema: {"<feature>": {"last_visit": "ISO", "previous_visit": "ISO|null"}}
+
+Bumped by switch (T13). Read by resume (T6+). Atomic temp+replace writes.
+"""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from ..workspace.workspace import Workspace
+
+
+_STATE = ".canopy/state/visits.json"
+
+
+def _path(workspace: Workspace) -> Path:
+    return workspace.config.root / _STATE
+
+
+def _load(workspace: Workspace) -> dict[str, dict[str, Any]]:
+    p = _path(workspace)
+    if not p.exists():
+        return {}
+    try:
+        return json.loads(p.read_text())
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _save(workspace: Workspace, data: dict) -> None:
+    p = _path(workspace)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(
+        prefix=f".{p.name}.", suffix=".tmp", dir=str(p.parent)
+    )
+    try:
+        with os.fdopen(fd, "w") as f:
+            json.dump(data, f, indent=2, sort_keys=True)
+        os.replace(tmp, p)
+    except Exception:
+        try:
+            os.unlink(tmp)
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def get_last_visit(workspace: Workspace, feature: str) -> dict[str, Any] | None:
+    """Return the visit entry for a feature, or None if not visited."""
+    return _load(workspace).get(feature)
+
+
+def mark_visited(workspace: Workspace, feature: str) -> str:
+    """Bump last_visit to now; carry old value to previous_visit.
+
+    Returns the new timestamp (ISO 8601 Z format).
+    """
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    data = _load(workspace)
+    prev = data.get(feature, {}).get("last_visit")
+    data[feature] = {"last_visit": now, "previous_visit": prev}
+    _save(workspace, data)
+    return now
+
+
+def reset_anchor(workspace: Workspace, feature: str) -> bool:
+    """Drop the feature entry from the visits log.
+
+    Returns True if the entry existed and was removed, False otherwise.
+    """
+    data = _load(workspace)
+    if feature not in data:
+        return False
+    del data[feature]
+    _save(workspace, data)
+    return True

canopy/actions/migrate_slots.py

@@ -0,0 +1,313 @@
+"""One-shot migration: pre-3.0 feature-named worktrees → 3.0 generic slots.
+
+Refuses to run if slots.json already exists. Idempotent only in the
+"nothing to do" sense — once migrated, calling again raises.
+
+Steps:
+  1. Read old active_feature.json (preserve last_touched + canonical).
+  2. Scan .canopy/worktrees/<feature>/<repo>/ on disk.
+  3. Allocate sequential slot ids (worktree-1, worktree-2, ...).
+  4. `git worktree move` each repo dir into its slot.
+  5. Rewrite canopy.toml: max_worktrees → slots.
+  6. Write slots.json.
+  7. Delete active_feature.json.
+  8. rmdir the now-empty feature parent dirs.
+"""
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib  # type: ignore[import-not-found]
+
+from ..git import repo as git
+from . import slots as slots_mod
+from .errors import BlockerError
+
+
+class AlreadyMigratedError(Exception):
+    pass
+
+
+class NotLegacyError(Exception):
+    """No old state and no feature-named worktrees — nothing to migrate."""
+
+
+def migrate(workspace_root: Path) -> dict[str, Any]:
+    """Migrate a pre-3.0 canopy workspace to the 3.0 slot layout.
+
+    Takes a path (not a Workspace) because the legacy canopy.toml has
+    max_worktrees which load_config rejects after T3.
+
+    Returns:
+        {moved: [{from, to}, ...], slots: {slot_id: feature}, canonical, slot_count}
+
+    Raises:
+        AlreadyMigratedError: slots.json already exists.
+        NotLegacyError: nothing to migrate (no active_feature.json and no feature dirs).
+    """
+    root = Path(workspace_root)
+    slots_json = root / ".canopy/state/slots.json"
+    if slots_json.exists():
+        raise AlreadyMigratedError(f"slots.json already exists at {slots_json}")
+
+    toml_path = root / "canopy.toml"
+    if not toml_path.exists():
+        raise NotLegacyError(f"no canopy.toml at {toml_path}")
+
+    # Parse the toml directly (load_config rejects max_worktrees per T3).
+    with open(toml_path, "rb") as f:
+        toml_data = tomllib.load(f)
+    repos_cfg = toml_data.get("repos", [])
+    repo_paths_by_name: dict[str, Path] = {}
+    for r in repos_cfg:
+        name = r.get("name")
+        rel_path = r.get("path", name)
+        if name:
+            repo_paths_by_name[name] = root / rel_path
+
+    old_active = root / ".canopy/state/active_feature.json"
+    wt_base = root / ".canopy/worktrees"
+
+    if not old_active.exists() and not wt_base.is_dir():
+        raise NotLegacyError("no active_feature.json and no .canopy/worktrees/")
+
+    old: dict[str, Any] = {}
+    if old_active.exists():
+        try:
+            old = json.loads(old_active.read_text())
+        except (OSError, json.JSONDecodeError):
+            old = {}
+
+    # 1. Inventory feature-named dirs (skip any already-named worktree-N dirs)
+    legacy: dict[str, list[str]] = {}  # feature → list of repos
+    if wt_base.is_dir():
+        for feat_dir in sorted(wt_base.iterdir()):
+            if not feat_dir.is_dir():
+                continue
+            if re.fullmatch(r"worktree-\d+", feat_dir.name):
+                raise AlreadyMigratedError(
+                    f"found slot dir {feat_dir.name} without slots.json"
+                )
+            repos = sorted(d.name for d in feat_dir.iterdir()
+                           if d.is_dir() and (d / ".git").exists())
+            if repos:
+                legacy[feat_dir.name] = repos
+
+    # 2. Allocate slot ids
+    slot_assignment: dict[str, str] = {}
+    for i, feature in enumerate(sorted(legacy.keys()), start=1):
+        slot_assignment[feature] = f"worktree-{i}"
+
+    # 3a. Dry-run preflight: validate every move target BEFORE touching disk.
+    # Avoids the half-migrated state that wedges the user (some dirs at the
+    # new slot path, others at the old feature path, no slots.json yet).
+    preflight_issues: list[dict[str, Any]] = []
+    for feature, repos in legacy.items():
+        slot_id = slot_assignment[feature]
+        for repo_name in repos:
+            old_path = wt_base / feature / repo_name
+            new_path = wt_base / slot_id / repo_name
+            main_repo = repo_paths_by_name.get(repo_name)
+            if main_repo is None or not main_repo.exists():
+                preflight_issues.append({
+                    "kind": "main_repo_missing", "repo": repo_name,
+                    "feature": feature, "main_repo": str(main_repo) if main_repo else None,
+                })
+                continue
+            if not old_path.exists():
+                preflight_issues.append({
+                    "kind": "source_missing", "repo": repo_name,
+                    "feature": feature, "path": str(old_path),
+                })
+                continue
+            if not (old_path / ".git").exists():
+                preflight_issues.append({
+                    "kind": "source_not_a_worktree", "repo": repo_name,
+                    "feature": feature, "path": str(old_path),
+                })
+                continue
+            if new_path.exists():
+                preflight_issues.append({
+                    "kind": "destination_exists", "repo": repo_name,
+                    "feature": feature, "path": str(new_path),
+                })
+                continue
+            # Validate the worktree is registered with git (catches locked worktrees).
+            try:
+                listed = git.worktree_list(main_repo)
+                listed_paths = {Path(w.get("path", "")).resolve() for w in listed}
+                if old_path.resolve() not in listed_paths:
+                    preflight_issues.append({
+                        "kind": "worktree_unregistered", "repo": repo_name,
+                        "feature": feature, "path": str(old_path),
+                    })
+            except Exception as e:  # noqa: BLE001 — surface as a single issue
+                preflight_issues.append({
+                    "kind": "worktree_list_failed", "repo": repo_name,
+                    "feature": feature, "error": str(e),
+                })
+
+    if preflight_issues:
+        raise BlockerError(
+            code="migration_preflight_failed",
+            what=(
+                f"{len(preflight_issues)} issue(s) detected before migration could begin — "
+                f"refusing to start so the workspace stays in the pre-3.0 layout"
+            ),
+            details={"issues": preflight_issues},
+        )
+
+    # 3b. Move each repo dir via `git worktree move`. If any move fails
+    # mid-loop, attempt to undo the completed ones so the user lands back
+    # on the pre-3.0 layout rather than a half-migrated wedge.
+    moved: list[dict[str, str]] = []
+    try:
+        for feature, repos in legacy.items():
+            slot_id = slot_assignment[feature]
+            (wt_base / slot_id).mkdir(parents=True, exist_ok=True)
+            for repo_name in repos:
+                old_path = wt_base / feature / repo_name
+                new_path = wt_base / slot_id / repo_name
+                main_repo = repo_paths_by_name.get(repo_name)
+                if main_repo is None or not main_repo.exists():
+                    continue
+                git.worktree_move(main_repo, old_path, new_path)
+                moved.append({"from": str(old_path), "to": str(new_path)})
+    except Exception as move_err:  # noqa: BLE001
+        # Best-effort rollback: move each completed entry back to its old path.
+        unrolled: list[dict[str, str]] = []
+        rollback_failures: list[dict[str, str]] = []
+        for m in reversed(moved):
+            new_path = Path(m["to"])
+            old_path = Path(m["from"])
+            # Figure out which repo this was so we can address the main repo.
+            repo_name = new_path.name
+            main_repo = repo_paths_by_name.get(repo_name)
+            if main_repo is None:
+                rollback_failures.append({**m, "error": "no main repo"})
+                continue
+            try:
+                old_path.parent.mkdir(parents=True, exist_ok=True)
+                git.worktree_move(main_repo, new_path, old_path)
+                unrolled.append({"from": str(new_path), "to": str(old_path)})
+            except Exception as e:  # noqa: BLE001
+                rollback_failures.append({**m, "error": str(e)})
+        # Best-effort cleanup of empty slot dirs we created during the failed pass.
+        for feature in legacy:
+            slot_id = slot_assignment[feature]
+            slot_dir = wt_base / slot_id
+            try:
+                if slot_dir.exists() and not any(slot_dir.iterdir()):
+                    slot_dir.rmdir()
+            except OSError:
+                pass
+        if rollback_failures:
+            raise BlockerError(
+                code="migration_partial",
+                what=(
+                    "migration failed mid-loop AND rollback could not return"
+                    " every dir to its pre-3.0 location — manual cleanup required"
+                ),
+                details={
+                    "underlying_error": str(move_err),
+                    "moved_dirs": moved,
+                    "unrolled_dirs": unrolled,
+                    "rollback_failures": rollback_failures,
+                },
+            )
+        raise BlockerError(
+            code="migration_aborted",
+            what=(
+                "migration failed mid-loop; reverted to pre-3.0 layout — "
+                "re-run after resolving the underlying error"
+            ),
+            details={
+                "underlying_error": str(move_err),
+                "rolled_back_dirs": unrolled,
+            },
+        )
+
+    # 4. Rewrite canopy.toml: max_worktrees → slots
+    text = toml_path.read_text()
+    new_text, n = re.subn(
+        r"(?m)^(\s*)max_worktrees(\s*=\s*\d+)\s*$",
+        r"\1slots\2",
+        text,
+    )
+    if n == 0 and not re.search(r"(?m)^\s*slots\s*=", text):
+        # Insert default `slots = 2` under [workspace]
+        new_text = re.sub(
+            r"(?m)^(\[workspace\][^\n]*\n(?:[^\[\n][^\n]*\n)*)",
+            r"\1slots = 2\n",
+            text, count=1,
+        )
+    toml_path.write_text(new_text)
+
+    # 5. Build slots.json
+    canonical_feature = old.get("feature")
+    canonical: slots_mod.CanonicalEntry | None = None
+    if canonical_feature:
+        per_repo = old.get("per_repo_paths") or {}
+        if isinstance(per_repo, dict) and all(Path(p).exists() for p in per_repo.values()):
+            canonical = slots_mod.CanonicalEntry(
+                feature=canonical_feature,
+                activated_at=old.get("activated_at", slots_mod.now_iso()),
+                per_repo_paths=dict(per_repo),
+            )
+
+    slot_entries = {
+        slot_assignment[feat]: slots_mod.SlotEntry(
+            feature=feat, occupied_at=slots_mod.now_iso(),
+        )
+        for feat in legacy
+    }
+
+    last_touched = {
+        str(k): str(v) for k, v in (old.get("last_touched") or {}).items()
+    }
+
+    # Re-parse the rewritten toml for slot_count
+    with open(toml_path, "rb") as f:
+        new_toml_data = tomllib.load(f)
+    slot_count = int(new_toml_data.get("workspace", {}).get("slots", 2))
+
+    state = slots_mod.SlotState(
+        slot_count=slot_count,
+        canonical=canonical,
+        previous_canonical=old.get("previous_feature"),
+        slots=slot_entries,
+        last_touched=last_touched,
+    )
+
+    # Write slots.json directly (write_state requires a Workspace object)
+    state_path = root / ".canopy/state/slots.json"
+    state_path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = state_path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(state.to_dict(), indent=2))
+    tmp.replace(state_path)
+
+    # 6. Delete active_feature.json
+    if old_active.exists():
+        old_active.unlink()
+
+    # 7. rmdir the now-empty feature parent dirs
+    for feature in legacy:
+        old_dir = wt_base / feature
+        try:
+            old_dir.rmdir()
+        except OSError:
+            pass  # not empty — leave for the user to clean up
+
+    return {
+        "moved": moved,
+        "slots": {sid: e.feature for sid, e in slot_entries.items()},
+        "canonical": canonical_feature,
+        "slot_count": slot_count,
+    }

canopy/actions/preflight_state.py

@@ -0,0 +1,97 @@
+"""Persist preflight results so feature_state can tell IN_PROGRESS from READY_TO_COMMIT.
+
+State file: ``<workspace_root>/.canopy/state/preflight.json``
+
+Schema (one entry per feature)::
+
+    {
+      "<feature_name>": {
+        "passed": bool,
+        "ran_at": "ISO 8601",
+        "head_sha_per_repo": {"<repo>": "sha"},
+        "all_passed": bool,
+        "summary": "..."
+      }
+    }
+
+A preflight result is "fresh" for a repo when the recorded HEAD sha
+equals the repo's current HEAD. If any repo's HEAD has moved since the
+recorded run, the preflight is stale (state machine treats it as
+"not run").
+"""
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from ..git import repo as git
+from ..workspace.workspace import Workspace
+
+
+def _state_file(workspace_root: Path) -> Path:
+    return workspace_root / ".canopy" / "state" / "preflight.json"
+
+
+def read_state(workspace_root: Path) -> dict[str, Any]:
+    """Return ``{<feature>: {passed, ran_at, head_sha_per_repo, ...}}``."""
+    path = _state_file(workspace_root)
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def record_result(
+    workspace_root: Path,
+    feature: str,
+    *,
+    passed: bool,
+    head_sha_per_repo: dict[str, str],
+    summary: str = "",
+) -> None:
+    """Persist a preflight outcome for a feature."""
+    path = _state_file(workspace_root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    state = read_state(workspace_root)
+    state[feature] = {
+        "passed": passed,
+        "ran_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "head_sha_per_repo": dict(head_sha_per_repo),
+        "summary": summary,
+    }
+    tmp = path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(state, indent=2))
+    tmp.replace(path)
+
+
+def is_fresh(
+    workspace: Workspace,
+    feature: str,
+    repo_branches: dict[str, str],
+) -> tuple[bool, dict[str, Any] | None]:
+    """True if the recorded preflight is still valid for the current HEAD per repo.
+
+    Returns ``(fresh, entry)``:
+      - fresh=True only when the entry exists AND each repo's recorded
+        sha equals current HEAD sha for the expected branch.
+      - entry is the recorded dict (None if no entry).
+    """
+    state = read_state(workspace.config.root)
+    entry = state.get(feature)
+    if not entry:
+        return False, None
+
+    recorded = entry.get("head_sha_per_repo") or {}
+    for repo_name, branch in repo_branches.items():
+        try:
+            state_obj = workspace.get_repo(repo_name)
+        except KeyError:
+            return False, entry
+        current = git.sha_of(state_obj.abs_path, branch)
+        if not current or recorded.get(repo_name) != current:
+            return False, entry
+    return True, entry

canopy/actions/push.py

@@ -0,0 +1,199 @@
+"""push — feature-scoped multi-repo push.
+
+Pushes the feature's branch in each in-scope repo to ``origin``. Like
+``commit``, defaults to the canonical feature when no ``--feature`` is
+given. ``--dry-run`` enumerates what would happen without firing pushes.
+
+Pre-flight (raises ``BlockerError`` before any push fires):
+  - ``no_canonical_feature`` — no active feature and no explicit one.
+  - ``empty_feature`` — feature has no associated repos.
+  - ``no_upstream`` — at least one in-scope repo lacks a configured
+    upstream and ``set_upstream`` was not passed. The fix-action
+    carries the same call arguments + ``set_upstream=True`` so the
+    agent can retry mechanically.
+
+Per-repo recipe::
+
+    1. read upstream + unpushed_count for the feature branch
+    2. branch ahead of upstream → `git push` → ok / rejected / failed
+    3. branch up-to-date → status: "up_to_date"
+    4. branch lacks upstream + set_upstream → push --set-upstream
+    5. rejected (non-fast-forward) without force_with_lease → status:
+       "rejected" + reason; do NOT auto-force.
+"""
+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 .aliases import repos_for_feature, resolve_feature
+from .errors import BlockerError, FixAction
+from .feature_state import resolve_repo_paths
+
+
+def _resolve_feature_name(
+    workspace: Workspace, feature: str | None,
+) -> str:
+    if feature:
+        return resolve_feature(workspace, feature)
+    state = slots_mod.read_state(workspace)
+    if state is None or state.canonical is None:
+        raise BlockerError(
+            code="no_canonical_feature",
+            what="no active feature; pass --feature or run `canopy switch <name>` first",
+            fix_actions=[
+                FixAction(action="switch", args={}, safe=False,
+                          preview="canopy switch <feature> sets the canonical slot"),
+            ],
+        )
+    return state.canonical.feature
+
+
+def _check_upstream(
+    repo_paths: dict[str, Path],
+    repo_branches: dict[str, str],
+    set_upstream: bool,
+    feature_name: str,
+) -> None:
+    """Raise no_upstream BlockerError if any repo lacks upstream + set_upstream not given."""
+    if set_upstream:
+        return
+    missing: dict[str, str] = {}
+    for repo_name, branch in repo_branches.items():
+        path = repo_paths.get(repo_name)
+        if path is None:
+            continue
+        if not git.has_upstream(path, branch):
+            missing[repo_name] = branch
+    if not missing:
+        return
+    raise BlockerError(
+        code="no_upstream",
+        what=(
+            f"{len(missing)} repo(s) have no upstream for the feature branch — "
+            "rerun with --set-upstream to publish"
+        ),
+        details={"per_repo": missing},
+        fix_actions=[
+            FixAction(
+                action="push",
+                args={"feature": feature_name, "set_upstream": True},
+                safe=False,
+                preview="canopy push --set-upstream publishes the branches",
+            ),
+        ],
+    )
+
+
+def _push_one(
+    repo_path: Path,
+    branch: str,
+    *,
+    set_upstream: bool,
+    force_with_lease: bool,
+    dry_run: bool,
+) -> dict[str, Any]:
+    """Push one repo. Returns a per-repo result dict."""
+    has_up = git.has_upstream(repo_path, branch)
+
+    # Up-to-date short-circuit only meaningful when upstream exists.
+    if has_up and not set_upstream:
+        unpushed = git.unpushed_count(repo_path, branch)
+        if unpushed == 0:
+            ref = git.upstream_ref(repo_path, branch)
+            return {
+                "status": "up_to_date",
+                "ref": ref,
+                "pushed_count": 0,
+            }
+
+    if dry_run:
+        # dry-run still calls git push --dry-run; trust the primitive.
+        return git.push(
+            repo_path,
+            branch=branch,
+            set_upstream=set_upstream and not has_up,
+            force_with_lease=force_with_lease,
+            dry_run=True,
+        )
+
+    return git.push(
+        repo_path,
+        branch=branch,
+        set_upstream=set_upstream and not has_up,
+        force_with_lease=force_with_lease,
+    )
+
+
+def push(
+    workspace: Workspace,
+    *,
+    feature: str | None = None,
+    repos: list[str] | None = None,
+    set_upstream: bool = False,
+    force_with_lease: bool = False,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Push the feature branch across every repo in the lane.
+
+    Args:
+        workspace: the workspace.
+        feature: feature alias. If None, falls back to the canonical
+            feature in ``slots.json``.
+        repos: optional filter — only push these repos within the
+            feature scope.
+        set_upstream: pass ``--set-upstream`` for repos that lack an
+            upstream; without this, missing-upstream raises a
+            ``BlockerError(code='no_upstream')`` pre-flight.
+        force_with_lease: pass ``--force-with-lease`` so non-fast-forward
+            pushes succeed when the local upstream cache matches the
+            remote (preserves "did anyone push behind my back?" check).
+        dry_run: enumerate what would happen without firing pushes.
+
+    Returns ``{feature, results: {<repo>: {...}}}``. Per-repo dict shape::
+
+        {status, pushed_count?, ref?, set_upstream?, reason?, dry_run?}
+
+    where ``status`` is one of
+    ``ok | up_to_date | rejected | failed``.
+    """
+    feature_name = _resolve_feature_name(workspace, feature)
+    repo_branches = repos_for_feature(workspace, feature_name)
+    if not repo_branches:
+        raise BlockerError(
+            code="empty_feature",
+            what=f"feature '{feature_name}' has no associated repos",
+        )
+
+    if repos:
+        repo_branches = {
+            r: b for r, b in repo_branches.items() if r in set(repos)
+        }
+        if not repo_branches:
+            raise BlockerError(
+                code="repos_filter_empty",
+                what=f"none of {sorted(repos)} are in feature '{feature_name}'",
+            )
+
+    repo_paths, _has_wt = resolve_repo_paths(workspace, feature_name, repo_branches)
+
+    _check_upstream(repo_paths, repo_branches, set_upstream, feature_name)
+
+    results: dict[str, dict[str, Any]] = {}
+    for repo_name, branch in repo_branches.items():
+        path = repo_paths.get(repo_name)
+        if path is None:
+            results[repo_name] = {"status": "failed", "reason": "repo path unresolved"}
+            continue
+        results[repo_name] = _push_one(
+            path,
+            branch,
+            set_upstream=set_upstream,
+            force_with_lease=force_with_lease,
+            dry_run=dry_run,
+        )
+
+    return {"feature": feature_name, "results": results}