canopy-cli 3.1.0__py3-none-any.whl

canopy/actions/slots.py

@@ -0,0 +1,221 @@
+"""Slot state — single source of truth for canopy's canonical + warm features.
+
+State file: .canopy/state/slots.json (atomic temp+rename writes).
+
+Schema::
+
+    {
+      "version": 1,
+      "slot_count": 2,
+      "canonical": {feature, activated_at, per_repo_paths},
+      "previous_canonical": str | null,
+      "slots": {"worktree-1": {feature, occupied_at}, ...},
+      "last_touched": {feature: iso, ...},
+      "in_flight": {feature_being_promoted, previously_canonical,
+                     started_at, per_repo_completed, failed_repo,
+                     error_what} | null
+    }
+
+Validation on read: a missing canonical path clears ``canonical`` only —
+the slots/last_touched maps are independent of the canonical pointer and
+must NOT be discarded when the canonical entry is stale. Catastrophic
+cases (file missing, JSON unparseable, top-level not a dict) still
+return None.
+
+Missing slot dirs → silently drop from the returned state.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from ..workspace.workspace import Workspace
+
+
+SLOTS_DIR = ".canopy/worktrees"
+
+
+@dataclass
+class CanonicalEntry:
+    feature: str
+    activated_at: str
+    per_repo_paths: dict[str, str]
+
+
+@dataclass
+class SlotEntry:
+    feature: str
+    occupied_at: str
+
+
+@dataclass
+class SlotState:
+    slot_count: int = 2
+    canonical: CanonicalEntry | None = None
+    previous_canonical: str | None = None
+    slots: dict[str, SlotEntry] = field(default_factory=dict)
+    last_touched: dict[str, str] = field(default_factory=dict)
+    in_flight: dict | None = None
+
+    def to_dict(self) -> dict:
+        d: dict[str, Any] = {
+            "version": 1,
+            "slot_count": self.slot_count,
+            "previous_canonical": self.previous_canonical,
+            "slots": {
+                sid: {"feature": e.feature, "occupied_at": e.occupied_at}
+                for sid, e in self.slots.items()
+            },
+            "last_touched": dict(self.last_touched),
+            "in_flight": dict(self.in_flight) if self.in_flight else None,
+        }
+        if self.canonical is not None:
+            d["canonical"] = {
+                "feature": self.canonical.feature,
+                "activated_at": self.canonical.activated_at,
+                "per_repo_paths": dict(self.canonical.per_repo_paths),
+            }
+        else:
+            d["canonical"] = None
+        return d
+
+
+def _state_path(workspace: Workspace) -> Path:
+    return workspace.config.root / ".canopy" / "state" / "slots.json"
+
+
+def _slots_root(workspace: Workspace) -> Path:
+    return workspace.config.root / SLOTS_DIR
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def read_state(workspace: Workspace) -> SlotState | None:
+    path = _state_path(workspace)
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(data, dict):
+        return None
+
+    # Canonical staleness check — stale canonical is NOT fatal to the
+    # rest of the state. Slots and last_touched are independent of the
+    # canonical pointer; clear canonical only and preserve the rest.
+    canonical_raw = data.get("canonical")
+    canonical: CanonicalEntry | None = None
+    if isinstance(canonical_raw, dict) and canonical_raw.get("feature"):
+        per_repo = canonical_raw.get("per_repo_paths") or {}
+        if not isinstance(per_repo, dict):
+            # Malformed canonical block — treat as no canonical, keep rest.
+            canonical = None
+        else:
+            stale = any(not Path(p).exists() for p in per_repo.values())
+            if stale:
+                canonical = None
+            else:
+                canonical = CanonicalEntry(
+                    feature=canonical_raw["feature"],
+                    activated_at=canonical_raw.get("activated_at", ""),
+                    per_repo_paths=dict(per_repo),
+                )
+
+    slots_raw = data.get("slots") or {}
+    slots_root = _slots_root(workspace)
+    slots_out: dict[str, SlotEntry] = {}
+    for sid, entry in slots_raw.items():
+        if not isinstance(entry, dict):
+            continue
+        # Drop slots whose dir is gone (stale on filesystem)
+        if not (slots_root / sid).exists():
+            continue
+        slots_out[sid] = SlotEntry(
+            feature=entry.get("feature", ""),
+            occupied_at=entry.get("occupied_at", ""),
+        )
+
+    in_flight_raw = data.get("in_flight")
+    in_flight = (
+        dict(in_flight_raw) if isinstance(in_flight_raw, dict) else None
+    )
+
+    return SlotState(
+        slot_count=int(data.get("slot_count", 2)),
+        canonical=canonical,
+        previous_canonical=data.get("previous_canonical"),
+        slots=slots_out,
+        last_touched={
+            str(k): str(v) for k, v in (data.get("last_touched") or {}).items()
+        },
+        in_flight=in_flight,
+    )
+
+
+def write_state(workspace: Workspace, state: SlotState) -> None:
+    path = _state_path(workspace)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(state.to_dict(), indent=2))
+    tmp.replace(path)
+
+
+def slot_worktree_path(workspace: Workspace, slot_id: str, repo: str) -> Path:
+    """Filesystem location of a slot's repo subdir."""
+    return _slots_root(workspace) / slot_id / repo
+
+
+def slot_for_feature(workspace: Workspace, feature: str) -> str | None:
+    """Return the slot id currently holding ``feature``, or None."""
+    state = read_state(workspace)
+    if state is None:
+        return None
+    for sid, entry in state.slots.items():
+        if entry.feature == feature:
+            return sid
+    return None
+
+
+def feature_for_slot(workspace: Workspace, slot_id: str) -> str | None:
+    """Return the feature currently in ``slot_id``, or None."""
+    state = read_state(workspace)
+    if state is None or slot_id not in state.slots:
+        return None
+    return state.slots[slot_id].feature
+
+
+def allocate_slot(state: SlotState) -> str | None:
+    """Return the lowest-index free slot id, or None if all are full."""
+    occupied = set(state.slots.keys())
+    for i in range(1, state.slot_count + 1):
+        sid = f"worktree-{i}"
+        if sid not in occupied:
+            return sid
+    return None
+
+
+def lru_evictee(
+    state: SlotState, *, exclude: set[str] | None = None,
+) -> str | None:
+    """Pick the LRU-coldest occupant feature from the warm slots.
+
+    Returns None when no eligible candidate. Sorting is deterministic:
+    (last_touched ASC, feature name ASC) — features with no timestamp
+    sort as oldest.
+    """
+    exclude = exclude or set()
+    candidates = [
+        e.feature for e in state.slots.values() if e.feature not in exclude
+    ]
+    if not candidates:
+        return None
+    return sorted(
+        candidates,
+        key=lambda f: (state.last_touched.get(f, ""), f),
+    )[0]

canopy/actions/stash.py

@@ -0,0 +1,230 @@
+"""Feature-aware stash tagging.
+
+Wraps the existing per-repo stash primitives so a stash saved in a
+feature context carries a structured prefix in its message. The prefix
+shape — ``[canopy <feature> @ <iso_ts>] <user_message>`` — is readable
+in ``git stash list`` output and easy to parse back.
+
+Untagged stashes still work end-to-end. ``list_grouped`` groups stashes
+by feature using the tag; entries without the prefix go in
+``untagged``.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any
+
+from ..git import multi as git_multi
+from ..git import repo as git
+from ..workspace.workspace import Workspace
+from .aliases import resolve_feature
+from .errors import BlockerError, FailedError, FixAction
+
+
+# Git stash auto-prefixes the stored message with "On <branch>: " (or
+# "WIP on <branch>: ..." when no -m given). Match the canopy tag anywhere
+# after that optional prefix; user message is whatever follows the ``]``.
+_TAG = re.compile(r"\[canopy (\S+) @ (\S+)\] ?(.*)$", re.DOTALL)
+
+
+@dataclass(frozen=True)
+class StashEntry:
+    repo: str
+    index: int
+    ref: str            # 'stash@{N}'
+    message: str        # raw message as git stored it
+    feature: str | None # parsed from tag, None if untagged
+    ts: str | None      # parsed from tag
+    user_message: str   # message text after the tag, OR raw if untagged
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "repo": self.repo,
+            "index": self.index,
+            "ref": self.ref,
+            "message": self.message,
+            "feature": self.feature,
+            "ts": self.ts,
+            "user_message": self.user_message,
+        }
+
+
+def _format_tag(feature: str, message: str) -> str:
+    ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    msg = message.strip()
+    return f"[canopy {feature} @ {ts}]" + (f" {msg}" if msg else "")
+
+
+def parse_message(raw: str) -> tuple[str | None, str | None, str]:
+    """Extract ``(feature, ts, user_message)`` from a stored stash message.
+
+    Returns ``(None, None, raw)`` if the message isn't a canopy tag.
+    """
+    m = _TAG.search(raw)
+    if not m:
+        return None, None, raw
+    return m.group(1), m.group(2), m.group(3)
+
+
+def _parse_entry(repo: str, raw: dict) -> StashEntry:
+    feature, ts, user_message = parse_message(raw.get("message", ""))
+    return StashEntry(
+        repo=repo,
+        index=raw.get("index", 0),
+        ref=raw.get("ref", f"stash@{{{raw.get('index', 0)}}}"),
+        message=raw.get("message", ""),
+        feature=feature,
+        ts=ts,
+        user_message=user_message,
+    )
+
+
+def save_for_feature(
+    workspace: Workspace,
+    feature: str,
+    message: str,
+    repos: list[str] | None = None,
+) -> dict[str, Any]:
+    """Stash dirty changes in feature.repos with a feature-tagged message.
+
+    ``repos`` overrides which repos to stash (default: all repos in the
+    feature lane). Repos not in the feature lane are silently skipped
+    when expanding from the lane; if ``repos`` is passed explicitly,
+    unknown names raise.
+    """
+    feature_name = resolve_feature(workspace, feature)
+    target_repos = _select_repos(workspace, feature_name, repos)
+    tagged_message = _format_tag(feature_name, message)
+
+    raw = git_multi.stash_save_all(
+        workspace, tagged_message, target_repos, include_untracked=True,
+    )
+    return {
+        "feature": feature_name,
+        "message": tagged_message,
+        "repos": raw,  # {repo: "stashed" | "clean" | error_str}
+    }
+
+
+def list_grouped(
+    workspace: Workspace, feature: str | None = None,
+) -> dict[str, Any]:
+    """List stashes across repos, grouped by feature tag.
+
+    If ``feature`` is passed, returns only entries matching that feature
+    (in ``by_feature[<feature>]``). Otherwise groups all tagged entries
+    by feature; unmatched go to ``untagged``.
+    """
+    target_feature = resolve_feature(workspace, feature) if feature else None
+    raw_per_repo = git_multi.stash_list_all(workspace)
+
+    by_feature: dict[str, list[dict]] = {}
+    untagged: list[dict] = []
+
+    for repo_name, entries in raw_per_repo.items():
+        for raw in entries:
+            entry = _parse_entry(repo_name, raw)
+            if entry.feature is None:
+                if target_feature is not None:
+                    continue  # feature filter applied — skip untagged
+                untagged.append(entry.to_dict())
+                continue
+            if target_feature is not None and entry.feature != target_feature:
+                continue
+            by_feature.setdefault(entry.feature, []).append(entry.to_dict())
+
+    return {"by_feature": by_feature, "untagged": untagged}
+
+
+def pop_feature(
+    workspace: Workspace,
+    feature: str,
+    repos: list[str] | None = None,
+) -> dict[str, Any]:
+    """Pop the most recent tagged stash for a feature in each target repo.
+
+    Returns per-repo ``{status: 'popped' | 'no_match' | 'failed', ref, message}``.
+    Raises ``BlockerError`` if no matching stash exists in any target repo.
+    """
+    feature_name = resolve_feature(workspace, feature)
+    target_repos = _select_repos(workspace, feature_name, repos)
+
+    raw_per_repo = git_multi.stash_list_all(workspace)
+    results: dict[str, dict] = {}
+    any_popped = False
+
+    for repo_name in target_repos:
+        entries_raw = raw_per_repo.get(repo_name, [])
+        # Most recent matching = lowest index where feature matches.
+        match: StashEntry | None = None
+        for raw in entries_raw:
+            parsed = _parse_entry(repo_name, raw)
+            if parsed.feature == feature_name:
+                if match is None or parsed.index < match.index:
+                    match = parsed
+        if match is None:
+            results[repo_name] = {"status": "no_match"}
+            continue
+        try:
+            state = workspace.get_repo(repo_name)
+            git.stash_pop(state.abs_path, match.index)
+            results[repo_name] = {
+                "status": "popped",
+                "ref": match.ref,
+                "message": match.user_message,
+                "ts": match.ts,
+            }
+            any_popped = True
+        except git.GitError as e:
+            results[repo_name] = {
+                "status": "failed",
+                "ref": match.ref,
+                "error": str(e),
+            }
+
+    if not any_popped:
+        raise BlockerError(
+            code="no_tagged_stash",
+            what=f"no stash tagged with feature '{feature_name}' in any target repo",
+            expected={"feature": feature_name, "target_repos": list(target_repos)},
+            actual={"per_repo": results},
+            fix_actions=[
+                FixAction(action="stash list", args={"feature": feature_name},
+                          safe=True, preview="see what tagged stashes exist"),
+            ],
+        )
+
+    return {"feature": feature_name, "repos": results}
+
+
+def _select_repos(
+    workspace: Workspace,
+    feature_name: str,
+    requested: list[str] | None,
+) -> list[str]:
+    """Pick the repo set for a stash op.
+
+    If ``requested`` is given, validate names. Otherwise default to the
+    feature lane's ``repos`` (from features.json) or all workspace repos
+    when the feature is implicit / has no explicit lane.
+    """
+    all_names = {r.config.name for r in workspace.repos}
+
+    if requested is not None:
+        unknown = [r for r in requested if r not in 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)
+
+    from ..features.coordinator import FeatureCoordinator
+    features = FeatureCoordinator(workspace)._load_features()
+    feature_data = features.get(feature_name) or {}
+    declared = feature_data.get("repos") or sorted(all_names)
+    return [r for r in declared if r in all_names]