@appchy/jarvis 0.1.37 → 0.1.39

package/harness/harness/branches.py

@@ -0,0 +1,408 @@
+"""The board on other branches — read-only, and answered from this clone.
+
+An agent blocked on something cannot tell whether the work it needs is finished
+somewhere else, not started, or being done right now by somebody else. The answer
+is already on disk: every machine has the whole repo, so another branch's board is
+`git show <ref>:work/…` and costs no network at all.
+
+**Reading is all this does.** A take, an update or a completion happens on the
+branch you have checked out and nowhere else — asking to act elsewhere is refused
+saying so, rather than quietly writing to a ref you are not on. Reading any branch
+and writing your own is the whole of the arrangement: a branch's board describes
+that branch's world and merges when the branch does.
+
+Three things are deliberately NOT here. The map refuses for another branch — it is
+a built artifact per checkout, and answering would mean building one, which is a
+manual step even for the branch you are on; a half-answer joining one branch's
+items to another branch's code would quietly mislead. Nothing warns that somebody
+else's PR touches your files: that needs a definition of "overlaps" and is its own
+piece of work. And nothing here talks to another agent — seeing why you are blocked
+is this; being told is the notices feature.
+"""
+
+import json
+import re
+import subprocess
+import time
+from pathlib import Path
+
+from harness import git
+from harness.tree import BUCKETS
+
+
+#: How long a PR lookup is believed. A sweep over twenty items must not become
+#: twenty API calls, and a PR's state does not change on a timescale that makes a
+#: few minutes wrong. `--refresh` is the answer when it does.
+PR_TTL = 300
+_PR_CACHE = "work-prs.json"
+
+#: `versions/<version>/<epic>/<bucket>/<name>/task.md`, or the backlog's shorter
+#: form. The bucket IS the status, so a path answers where an item stands without
+#: reading a byte of it — which is what makes reading a whole branch cheap.
+_ITEM = re.compile(r"^work/(versions|backlog)/.+/task\.md$")
+
+
+def items_at(repo, ref: str) -> list:
+    """Every item on `ref`, from that ref's tree alone.
+
+    No checkout, no stash, no touching the working tree: `ls-tree` reads the object
+    store, so this is safe to run with uncommitted changes sitting in front of you.
+    """
+    code, out, _ = git._git(repo, "ls-tree", "-r", "--name-only", ref, "--", "work/")
+    if code != 0:
+        return []
+    found = []
+    for path in out.splitlines():
+        path = path.strip()
+        if not _ITEM.match(path):
+            continue
+        parts = path.split("/")
+        backlog = parts[1] == "backlog"
+        bucket = "queue" if backlog else (parts[-3] if len(parts) >= 3 else "")
+        found.append({
+            "name": parts[-2],
+            "status": bucket if bucket in BUCKETS else "queue",
+            "epic": parts[2] if backlog else (parts[3] if len(parts) > 3 else ""),
+            "version": "backlog" if backlog else parts[2],
+            "path": path,
+        })
+    return sorted(found, key=lambda i: i["name"])
+
+
+def brief_at(repo, ref: str, path: str) -> str:
+    """One brief's text as `ref` has it. Empty when that ref does not carry it."""
+    code, out, _ = git._git(repo, "show", f"{ref}:{path}")
+    return out if code == 0 else ""
+
+
+def branches_of(repo, name: str) -> list:
+    """Every branch carrying work on `name`, newest commit first.
+
+    Read from the COMMITS rather than from the trees, because a branch that has the
+    file and has never touched it is not where the work is happening. The trailers
+    slice 1 started writing are what make this answerable at all.
+    """
+    code, out, _ = git._git(
+        repo, "log", "--all", "--format=%H%x1f%aI%x1f%an", "-E",
+        f"--grep=^{git.ITEM}: {re.escape(name)}$", timeout=60)
+    if code != 0 or not out.strip():
+        return []
+
+    seen = {}
+    for line in out.splitlines():
+        parts = line.split("\x1f")
+        if len(parts) < 3:
+            continue
+        sha, when, who = parts[0], parts[1], parts[2]
+        for branch in _containing(repo, sha):
+            prior = seen.get(branch)
+            if not prior or when > prior["when"]:
+                seen[branch] = {"branch": branch, "when": when, "by": who, "sha": sha[:12]}
+    return sorted(seen.values(), key=lambda b: b["when"], reverse=True)
+
+
+def _containing(repo, sha: str) -> list:
+    """Branches holding a commit, remote-tracking refs folded onto what they track.
+
+    `origin/x` and `x` are one branch that happens to exist in two places, and
+    listing both reads as two people working it — the exact confusion this command
+    is here to clear up. Folded by REMOTE NAME rather than by splitting on the
+    first slash, because `claude/fix-something` is a branch with a slash in it and
+    is nobody's remote.
+    """
+    code, out, _ = git._git(repo, "branch", "--all", "--format=%(refname:short)",
+                            "--contains", sha)
+    if code != 0:
+        return []
+    remotes = [r for r in git._git(repo, "remote")[1].split() if r]
+    names = []
+    for line in out.splitlines():
+        line = line.strip()
+        if not line or "HEAD ->" in line:
+            continue
+        if line.startswith("remotes/"):
+            line = line[len("remotes/"):]
+        for remote in remotes:
+            if line.startswith(f"{remote}/"):
+                line = line[len(remote) + 1:]
+                break
+        if line and line not in names:
+            names.append(line)
+    return names
+
+
+def current(repo) -> str:
+    """The branch this clone has checked out, or "" on a detached HEAD."""
+    return git._git(repo, "branch", "--show-current")[1].strip()
+
+
+def refs_state(repo) -> dict:
+    """Which refs this clone can answer from, and how old they are.
+
+    Offline is a normal state, not a failure — the whole point is that another
+    branch's board is already here. What is NOT honest is presenting a ref fetched
+    a week ago as current, so this reports when the origin was last actually
+    REACHED, which `git.py` records as an outcome rather than reading a timestamp
+    that a failed fetch also updates.
+    """
+    _, _, synced = git._last_probe(repo)
+    # A SPACE, not `%x1f`: `for-each-ref` does not expand hex escapes the way
+    # `log --format` does — it emits the literal text `%x1f`, so every ref came
+    # back with the separator glued into its name and matched nothing. A space is
+    # safe here because git forbids one in a ref name, and the strict date carries
+    # none either.
+    code, out, _ = git._git(repo, "for-each-ref",
+                            "--format=%(refname:short) %(committerdate:iso8601-strict)",
+                            "refs/heads", "refs/remotes")
+    refs = []
+    if code == 0:
+        for line in out.splitlines():
+            name, _, when = line.strip().partition(" ")
+            if name and "HEAD" not in name:
+                refs.append({"ref": name, "when": when.strip()})
+    refs.sort(key=lambda r: r["when"], reverse=True)
+    return {"refs": refs, "synced": synced, "current": current(repo)}
+
+
+# =============================================================================
+# Pull requests
+# =============================================================================
+
+
+def pr_for(repo, branch: str, refresh: bool = False) -> dict:
+    """The PR a branch is being reviewed in, or {} when there is none to find.
+
+    **Cached, because a sweep over twenty items would otherwise be twenty API
+    calls.** This is the only real network call in the whole arrangement;
+    everything else above is local git against objects already on disk.
+
+    Uses `gh`, which is how a developer machine already talks to GitHub, and says
+    nothing rather than guessing when it is absent or logged out. An absent `gh` is
+    the same answer as an unreachable origin: this clone cannot tell you, which is
+    a true statement, unlike "there is no PR".
+    """
+    cache = _pr_cache(repo)
+    hit = cache.get(branch)
+    if hit and not refresh and (time.time() - hit.get("at", 0)) < PR_TTL:
+        return hit.get("pr")
+
+    pr = _ask_gh(repo, branch)
+    # A failure is not cached. "I could not ask" is a fact about this moment, and
+    # remembering it for five minutes would turn one flaky call into five minutes
+    # of pretending not to know.
+    if pr is not None:
+        cache[branch] = {"at": time.time(), "pr": pr}
+        _write_pr_cache(repo, cache)
+    return pr
+
+
+def _ask_gh(repo, branch: str):
+    """`{}` when the branch has no PR, `None` when this clone could not ask.
+
+    Two different answers that a single empty value would flatten into one: "there
+    is no PR" is a fact about the branch, and "gh is not installed here" is a fact
+    about this machine. Saying the first when you mean the second is the same lie a
+    stale board tells.
+    """
+    try:
+        p = subprocess.run(
+            ["gh", "pr", "list", "--head", branch, "--state", "all", "--limit", "1",
+             "--json", "number,title,state,url,isDraft"],
+            cwd=str(repo), capture_output=True, text=True, timeout=15)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if p.returncode != 0:
+        return None
+    try:
+        rows = json.loads(p.stdout or "[]")
+    except ValueError:
+        return None
+    if not rows:
+        return {}
+    row = rows[0]
+    return {"number": row.get("number"), "title": row.get("title", ""),
+            "state": str(row.get("state", "")).lower(),
+            "draft": bool(row.get("isDraft")), "url": row.get("url", "")}
+
+
+def branch_of_pr(repo, number: str) -> str:
+    """The branch a PR is on, so a PR resolves back to the items being done on it."""
+    try:
+        p = subprocess.run(["gh", "pr", "view", str(number), "--json", "headRefName"],
+                           cwd=str(repo), capture_output=True, text=True, timeout=15)
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    if p.returncode != 0:
+        return ""
+    try:
+        return str(json.loads(p.stdout or "{}").get("headRefName") or "")
+    except ValueError:
+        return ""
+
+
+def _pr_cache_path(repo):
+    d = git._git(repo, "rev-parse", "--git-dir")[1].strip()
+    return (Path(repo) / d / _PR_CACHE) if d else None
+
+
+def _pr_cache(repo) -> dict:
+    p = _pr_cache_path(repo)
+    try:
+        return json.loads(p.read_text())
+    except (OSError, ValueError, AttributeError):
+        return {}
+
+
+def _write_pr_cache(repo, cache: dict) -> None:
+    p = _pr_cache_path(repo)
+    try:
+        p.write_text(json.dumps(cache))
+    except (OSError, AttributeError, TypeError):
+        pass
+
+
+# =============================================================================
+# Commands
+# =============================================================================
+
+
+def _repo():
+    from .tree import die, locate_work_root
+    root = locate_work_root()[0]
+    if root is None:
+        die("no work/ tree found — there is no board here to read")
+    repo = root.parent
+    if not git.is_repo(repo):
+        die(f"{repo} is not a git repository — a board on another branch needs one")
+    return repo
+
+
+def cmd_find(args) -> int:
+    """Where a piece of work is being done, in either direction.
+
+    An item resolves to the branches carrying it and the PR each is in; a branch or
+    a PR resolves back to the items on it. One command for both because it is one
+    question — *where is this happening* — and splitting it by which end you happen
+    to be holding would mean remembering two.
+    """
+    repo = _repo()
+    target = str(args["target"]).strip()
+    refresh = bool(args.get("refresh"))
+    state = refs_state(repo)
+
+    # A PR number first: `#123` says so outright, and a bare number cannot be an
+    # item name, which the harness requires to be kebab-case.
+    number = target[1:] if target.startswith("#") else target
+    if number.isdigit():
+        branch = branch_of_pr(repo, number)
+        if not branch:
+            print(f"  #{number}  cannot tell — `gh` is not answering here")
+            _say_refs(state)
+            return 0
+        print(f"  #{number}  branch {branch}")
+        _say_items(repo, branch)
+        _say_refs(state)
+        return 0
+
+    known = {r["ref"] for r in state["refs"]}
+    if target in known:
+        print(f"  {target}  branch")
+        pr = pr_for(repo, target, refresh)
+        print(f"        pr      {_pr_line(pr)}")
+        _say_items(repo, target)
+        _say_refs(state)
+        return 0
+
+    found = branches_of(repo, target)
+    if not found:
+        # Not knowing WHERE is different from not knowing OF, and the two want
+        # different next steps from whoever hit this.
+        # One tree read per ref, not two: this walks every ref the clone has, and
+        # a board of a hundred items across forty refs is slow enough already
+        # without asking each one the same question twice.
+        anywhere = [b["ref"] for b in state["refs"]
+                    if any(i["name"] == target for i in items_at(repo, b["ref"]))]
+        if anywhere:
+            print(f"  {target}  on {', '.join(anywhere[:5])}, "
+                  f"but no commit here has touched it")
+        else:
+            print(f"  {target}  nothing on any ref this clone has names it")
+        _say_refs(state)
+        return 0
+
+    print(f"  {target}")
+    here = current(repo)
+    for entry in found:
+        mine = "  ← you are here" if entry["branch"] == here else ""
+        print(f"        branch  {entry['branch']}{mine}")
+        print(f"                last touched {entry['when'][:10]} by {entry['by']} ({entry['sha']})")
+        print(f"                pr      {_pr_line(pr_for(repo, entry['branch'], refresh))}")
+    _say_refs(state)
+    return 0
+
+
+def _pr_line(pr) -> str:
+    if pr is None:
+        return "cannot tell — `gh` is not answering on this machine"
+    if not pr:
+        return "no pull request for this branch"
+    draft = " · draft" if pr.get("draft") else ""
+    return f"#{pr.get('number')} {pr.get('state')}{draft} — {pr.get('title', '')}"
+
+
+def _say_items(repo, ref: str) -> None:
+    items = items_at(repo, ref)
+    if not items:
+        print("        items   none on that ref")
+        return
+    moving = [i for i in items if i["status"] != "complete"]
+    print(f"        items   {len(items)} on that ref, {len(moving)} still moving")
+    for item in moving[:12]:
+        print(f"                {item['status']:<12} {item['name']}")
+    if len(moving) > 12:
+        print(f"                … and {len(moving) - 12} more")
+
+
+def _say_refs(state: dict) -> None:
+    """What answered, and how old it is. An offline clone gives a real answer from
+    the refs it has; what it must never do is pass them off as current."""
+    synced = state.get("synced") or "never"
+    print(f"        refs    {len(state['refs'])} on this clone · origin last reached {synced}")
+
+
+def cmd_at(args) -> int:
+    """The board as another branch has it.
+
+    Printed on its own rather than merged into the current branch's, because two
+    branches are ALLOWED to disagree — a branch's board describes that branch's
+    world. Merging them would hide exactly the difference somebody ran this to see.
+    """
+    repo = _repo()
+    ref = str(args["ref"]).strip()
+    state = refs_state(repo)
+    known = {r["ref"] for r in state["refs"]}
+    if ref not in known:
+        from .tree import die
+        die(f"this clone has no ref called '{ref}'. It answers from what it already "
+            f"has — {len(state['refs'])} ref(s), origin last reached "
+            f"{state.get('synced') or 'never'}. `git fetch` first if you expect a "
+            f"newer one, or `jarvis work find` to see where work is happening.")
+
+    items = items_at(repo, ref)
+    if not items:
+        print(f"  {ref}  no work/ tree on that ref")
+        _say_refs(state)
+        return 0
+
+    here = " (this is the branch you are on)" if ref == state.get("current") else ""
+    print(f"  BOARD as {ref} has it{here} — {len(items)} item(s), read-only")
+    for bucket in BUCKETS:
+        rows = [i for i in items if i["status"] == bucket]
+        if not rows:
+            continue
+        print(f"\n  {bucket.upper()}  ({len(rows)})")
+        for item in rows:
+            print(f"      {item['name']:<44} {item['epic']}")
+    print()
+    _say_refs(state)
+    return 0