@arbiterforge/ca-pi 0.6.0

package/plugins/ca-pi/hooks/_standuplib.py

@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+# codeArbiter — standup hygiene parsers (sprint: session-hygiene, Feature 1).
+#
+# PURE functions only: no I/O, no subprocess, no os.environ. Each function takes
+# the OUTPUT STRING of a git command and returns structured data. The git calls
+# themselves happen elsewhere (a later task); keeping parsing pure makes every
+# branch unit-testable from fixture strings, and keeps this module compliant with
+# the stdlib-only / fail-loud hook posture.
+
+import os
+
+__all__ = [
+    "parse_porcelain",
+    "parse_ahead_behind",
+    "merged_branch_candidates",
+    "parse_worktrees",
+    "parse_stash_count",
+    "ff_pull_eligible",
+    "stale_worktree_candidates",
+    "any_actionable",
+]
+
+
+def parse_porcelain(text):
+    """Parse `git status --porcelain=v1` output into a summary.
+
+    Returns {"dirty": bool, "staged": int, "unstaged": int, "untracked": int}.
+
+    Each status line is `XY <path>` where X is the index (staged) column and Y is
+    the worktree (unstaged) column. A space means "no change" in that column.
+    Untracked files use the `??` code and are counted separately (not as
+    staged/unstaged). A file modified in both index and worktree (e.g. "MM")
+    counts toward BOTH staged and unstaged. Empty/whitespace input is clean.
+    """
+    staged = unstaged = untracked = 0
+    for raw in (text or "").splitlines():
+        if not raw.strip():
+            continue
+        code = raw[:2]
+        if code == "??":
+            untracked += 1
+            continue
+        x = code[0:1]
+        y = code[1:2]
+        if x and x != " " and x != "?":
+            staged += 1
+        if y and y != " " and y != "?":
+            unstaged += 1
+    dirty = (staged + unstaged + untracked) > 0
+    return {
+        "dirty": dirty,
+        "staged": staged,
+        "unstaged": unstaged,
+        "untracked": untracked,
+    }
+
+
+def parse_ahead_behind(text):
+    """Parse `git rev-list --left-right --count <upstream>...HEAD` output.
+
+    The single output line is `<behind>\\t<ahead>` (left side = upstream-only
+    commits = behind; right side = HEAD-only commits = ahead). Returns
+    (behind, ahead). Empty or malformed (wrong field count, non-numeric) → (0, 0).
+    """
+    line = (text or "").strip()
+    if not line:
+        return (0, 0)
+    parts = line.split()
+    if len(parts) != 2:
+        return (0, 0)
+    try:
+        behind = int(parts[0])
+        ahead = int(parts[1])
+    except ValueError:
+        return (0, 0)
+    return (behind, ahead)
+
+
+def merged_branch_candidates(branch_vv_text, current, default):
+    """Parse `git branch -vv` output for local branches safe to prune.
+
+    PRUNE RULE (single, deterministic): a branch is a candidate iff its line shows
+    its upstream is `gone` — i.e. it contains the `: gone]` marker that git prints
+    when the tracked remote branch no longer exists (typically because the PR was
+    merged and the remote branch deleted). The current branch (line begins with
+    `* `) and the `default` branch (e.g. "main") are NEVER candidates, regardless
+    of their upstream state. Order of first appearance is preserved.
+    """
+    candidates = []
+    for raw in (branch_vv_text or "").splitlines():
+        if not raw.strip():
+            continue
+        is_current = raw.startswith("* ")
+        # Strip the `* ` / leading spaces marker, then the branch name is token 0.
+        body = raw[2:] if is_current else raw.lstrip()
+        tokens = body.split()
+        if not tokens:
+            continue
+        name = tokens[0]
+        if ": gone]" not in raw:
+            continue
+        if is_current or name == current or name == default:
+            continue
+        candidates.append(name)
+    return candidates
+
+
+def _strip_trailing_sep(path):
+    """Drop a single trailing / or \\ so a repo_root with a trailing separator
+    still matches the worktree path git reports (which has none)."""
+    if path and path[-1] in ("/", "\\"):
+        return path[:-1]
+    return path
+
+
+def parse_worktrees(porcelain_text, repo_root):
+    """Parse `git worktree list --porcelain` output.
+
+    Returns a list of {"path": str, "branch": str|None, "is_main": bool}. Records
+    are separated by blank lines; each starts with a `worktree <path>` line and may
+    carry a `branch refs/heads/<name>` line (absent / `detached` => branch None).
+    The main worktree is the record whose path equals `repo_root` (trailing
+    separator tolerated). Parses faithfully; staleness/merge classification is a
+    later task's job.
+    """
+    root = _strip_trailing_sep(repo_root or "")
+    out = []
+    cur = None
+    for raw in (porcelain_text or "").splitlines():
+        line = raw.rstrip("\n")
+        if not line.strip():
+            if cur is not None:
+                out.append(cur)
+                cur = None
+            continue
+        if line.startswith("worktree "):
+            if cur is not None:
+                out.append(cur)
+            path = line[len("worktree "):].strip()
+            cur = {"path": path, "branch": None, "is_main": path == root}
+        elif line.startswith("branch ") and cur is not None:
+            ref = line[len("branch "):].strip()
+            cur["branch"] = ref[len("refs/heads/"):] if ref.startswith("refs/heads/") else ref
+        # HEAD / detached / bare / locked lines carry no fields we surface here.
+    if cur is not None:
+        out.append(cur)
+    return out
+
+
+def parse_stash_count(text):
+    """Count stashes from `git stash list` output (one stash per line). Empty → 0."""
+    return sum(1 for ln in (text or "").splitlines() if ln.strip())
+
+
+def ff_pull_eligible(porcelain_text, behind):
+    """SH-6: True iff a fast-forward pull should be OFFERED — the working tree is
+    CLEAN (no staged/unstaged/untracked changes per parse_porcelain) AND we are
+    behind (`behind > 0`). A dirty tree withholds the offer (a ff-pull on a dirty
+    tree is unsafe); behind == 0 means there is nothing to pull. PURE: porcelain
+    OUTPUT STRING + behind count in, bool out. This only IDENTIFIES eligibility;
+    it never pulls — the /ca:standup command acts on explicit user confirmation."""
+    if behind <= 0:
+        return False
+    return not parse_porcelain(porcelain_text)["dirty"]
+
+
+def stale_worktree_candidates(worktrees, gone_or_merged_branches, path_exists=os.path.exists):
+    """SD-B1: from parsed `worktrees` (parse_worktrees output) plus the set of
+    branch names that are gone/merged on the remote, return the NON-MAIN worktrees
+    that are STALE CANDIDATES. A worktree is stale iff its branch is in
+    `gone_or_merged_branches` OR its path no longer exists on disk. The main
+    worktree (is_main) is NEVER a candidate. Order of input is preserved.
+
+    `path_exists(path) -> bool` is injectable so the disk check is deterministic in
+    tests (pass a fake predicate); production defaults to os.path.exists. This is a
+    PURE classifier: it only IDENTIFIES candidates and removes/mutates nothing —
+    the /ca:standup command removes a worktree only on explicit per-item user
+    confirmation, which is why the broad (gone OR missing) candidate rule is safe."""
+    gone = gone_or_merged_branches or set()
+    out = []
+    for wt in worktrees or []:
+        if wt.get("is_main"):
+            continue
+        branch = wt.get("branch")
+        path = wt.get("path")
+        is_stale = (branch in gone) or (not path_exists(path))
+        if is_stale:
+            out.append(wt)
+    return out
+
+
+def any_actionable(summary):
+    """True if the assembled briefing summary has ANY actionable condition.
+
+    Drives the "emit an offer line only if actionable" behavior. Triggers: a dirty
+    tree, behind > 0, ahead/unpushed > 0, non-empty prune_candidates, non-empty
+    stale_worktrees, or stashes > 0. Missing keys default to falsy.
+    """
+    s = summary or {}
+    if s.get("dirty"):
+        return True
+    if (s.get("behind") or 0) > 0:
+        return True
+    if (s.get("ahead") or 0) > 0:
+        return True
+    if (s.get("unpushed") or 0) > 0:
+        return True
+    if s.get("prune_candidates"):
+        return True
+    if s.get("stale_worktrees"):
+        return True
+    if (s.get("stashes") or 0) > 0:
+        return True
+    return False

package/plugins/ca-pi/hooks/_subagentslib.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+# codeArbiter — statusline subagent-rows helpers (extracted from statusline.py,
+# architecture-004).
+#
+# Owns resolving the current session's subagents directory, reading its recent
+# `.jsonl` transcripts (deduped per requestId, same rule as the Session/Today
+# rows), and labeling each subagent from its first user message. Carries no
+# rendering concern — the statusline turns the returned dicts into rows.
+#
+# Design principles (mirroring _ledgerlib.py):
+#   - Stdlib only; no third-party imports ever.
+#   - Zero side effects at import time.
+#   - Never raise on malformed input — every reader degrades to a safe blank.
+#
+# Public API:
+#   subagent_dir(data, root, sid) -> str|None
+#   read_subagents(sdir) -> (active, recent, shown, (tot_in, tot_out))
+#   sub_label(content) -> str
+#   display_model(model_id) -> str
+
+import json
+import os
+import re
+import time
+
+try:
+    import _colorlib
+    strip_control = _colorlib.strip_control
+except Exception:  # pragma: no cover — never let an import break the statusline
+    _colorlib = None
+
+    def strip_control(s):
+        return s if not isinstance(s, str) else re.sub(r"[\000-\037]", "", s)
+
+ACTIVE_WINDOW = 150       # secs: a subagent file touched this recently is "active"
+SHOW_WINDOW = 600         # secs: still display recently-finished subagents
+MAX_SUB_ROWS = 4
+MAX_SUB_FILES = 12        # hot-path bound: parse at most this many files / render
+MAX_SUB_LINES = 2500      # per-file line cap
+
+
+def display_model(model_id):
+    """Compact a host model ID while retaining its family and version."""
+    if not isinstance(model_id, str):
+        return "model:?"
+    name = strip_control(model_id).strip()
+    if not name:
+        return "model:?"
+    if name.startswith("claude-"):
+        name = name[len("claude-"):]
+    name = re.sub(r"-(?:\d{8}|\d{4}-\d{2}-\d{2})$", "", name)
+    return "model:" + name[:24]
+
+
+def num(x, default=0.0):
+    """Coerce any host value to float; tolerate strings, None, and containers."""
+    try:
+        return float(x)
+    except (TypeError, ValueError):
+        return default
+
+
+def get(d, *path, default=None):
+    cur = d
+    for k in path:
+        if not isinstance(cur, dict) or k not in cur or cur[k] is None:
+            return default
+        cur = cur[k]
+    return cur
+
+
+def subagent_dir(data, root, sid):
+    """Resolve the current session's subagents directory: prefer transcript_path
+    (authoritative), else derive the project slug from cwd + session id."""
+    tp = data.get("transcript_path") if isinstance(data, dict) else None
+    if tp:
+        base = os.path.dirname(tp)
+        sess = os.path.splitext(os.path.basename(tp))[0]
+        cand = os.path.join(base, sess, "subagents")
+        if os.path.isdir(cand):
+            return cand
+    if sid:
+        cwd = get(data, "workspace", "current_dir") or get(data, "cwd") or root
+        slug = re.sub(r"[^A-Za-z0-9]", "-", os.path.abspath(cwd))
+        cand = os.path.join(os.path.expanduser("~"), ".claude", "projects", slug, sid, "subagents")
+        if os.path.isdir(cand):
+            return cand
+    return None
+
+
+def read_subagents(sdir):
+    """Return (active, recent, shown[{label,inp,out,age,active}], (tot_in, tot_out)).
+    `active` = files touched within ACTIVE_WINDOW (a liveness proxy); `recent` =
+    all files within SHOW_WINDOW (active + recently finished).
+
+    ONE result shape on EVERY path (#413). The element types are stable — int,
+    int, list, (int|float, int|float) — so a caller may unpack four names
+    unconditionally. statusline.py does exactly that, OUTSIDE its safe()
+    wrapper, so an error branch returning a shorter tuple was a hard ValueError
+    that erased the entire subagent section on a routine directory race. An
+    unreadable/absent directory is an EMPTY result, not a different result."""
+    empty = (0, 0, [], (0, 0))
+    now = time.time()
+    files = []
+    try:
+        for nm in os.listdir(sdir):
+            if not nm.endswith(".jsonl"):
+                continue
+            fp = os.path.join(sdir, nm)
+            try:
+                st = os.stat(fp)
+            except OSError:
+                continue
+            if now - st.st_mtime <= SHOW_WINDOW:
+                files.append((st.st_mtime, st.st_size, fp, nm))
+    except OSError:
+        return empty
+    files.sort(reverse=True)   # most-recently-touched first
+
+    active = sum(1 for mtime, _, _, _ in files if now - mtime <= ACTIVE_WINDOW)
+    shown, tot_in, tot_out = [], 0, 0
+    for mtime, size, fp, nm in files[:MAX_SUB_FILES]:
+        if size > 16 * 1024 * 1024:
+            continue
+        reqs = {}
+        models = []
+        label = None
+        try:
+            with open(fp, encoding="utf-8", errors="replace") as f:
+                for i, ln in enumerate(f):
+                    if i > MAX_SUB_LINES:
+                        break
+                    ln = ln.strip()
+                    if not ln:
+                        continue
+                    try:
+                        d = json.loads(ln)
+                    except ValueError:
+                        continue
+                    if not isinstance(d, dict):
+                        # A transcript line may be ANY valid JSON value; only an
+                        # object carries an event. `[]`/`null`/`3`/`"s"` used to
+                        # reach .get() below inside a try that caught OSError
+                        # only, so one such line raised AttributeError out of
+                        # read_subagents and blanked every subagent row (#413).
+                        continue
+                    msg = d.get("message")
+                    if not isinstance(msg, dict):
+                        continue
+                    if label is None and msg.get("role") == "user":
+                        label = sub_label(msg.get("content"))
+                    if msg.get("role") == "assistant":
+                        raw_model = msg.get("model")
+                        if isinstance(raw_model, str) and raw_model.strip():
+                            raw_model = raw_model.strip()
+                            if raw_model not in models:
+                                models.append(raw_model)
+                    u = msg.get("usage")
+                    if isinstance(u, dict):
+                        # dedupe by requestId; fresh input only (cache reads excluded)
+                        # — same definition as the Session/Today rows.
+                        reqs[d.get("requestId") or msg.get("id") or i] = (
+                            num(u.get("input_tokens")) + num(u.get("cache_creation_input_tokens")),
+                            num(u.get("output_tokens")))
+        except Exception:  # noqa: BLE001 — #413: the error boundary is PER FILE
+            # One unreadable or structurally surprising transcript must cost
+            # only its own row, never the rest of the directory. Widened from
+            # OSError so a shape the reader has not anticipated degrades the
+            # same way malformed JSON already does (the module's standing
+            # "never raise on malformed input" contract) instead of escaping
+            # into the statusline and blanking every subagent row.
+            continue
+        inp = sum(v[0] for v in reqs.values())
+        out = sum(v[1] for v in reqs.values())
+        tot_in += inp
+        tot_out += out
+        if len(shown) < MAX_SUB_ROWS:
+            shown.append({"label": label or ("agent-" + re.sub(r"\.jsonl$", "", nm)[-6:]),
+                          "model": (display_model(models[0]) if len(models) == 1 else
+                                    ("model:mixed" if models else "model:?")),
+                          "inp": inp, "out": out, "age": now - mtime,
+                          "active": now - mtime <= ACTIVE_WINDOW})
+    return active, len(files), shown, (tot_in, tot_out)
+
+
+def sub_label(content):
+    """Derive a label from a subagent's first user message. A short, title-like
+    first line wins (a dispatcher may lead the prompt with one); otherwise flatten
+    and drop a boilerplate role-assignment preamble so the visible text carries
+    signal instead of "You are a...". Truncation to the row width is the render's
+    job (clip()), so this returns the full cleaned string up to a sane cap."""
+    text = ""
+    if isinstance(content, str):
+        text = content
+    elif isinstance(content, list):
+        for blk in content:
+            if isinstance(blk, dict) and blk.get("type") == "text":
+                text = blk.get("text", "")
+                break
+            if isinstance(blk, str):
+                text = blk
+                break
+    raw = strip_control(str(text))
+    # strip leading reminder/system blocks up front (multi-line safe), then a lone tag
+    raw = re.sub(r"^\s*(?:<([^>\s]+)[^>]*>.*?</\1>\s*)+", "", raw, flags=re.S)
+    raw = re.sub(r"^\s*<[^>]+>\s*", "", raw)
+    # a short, title-like first line wins (rewards a leading title line)
+    first = ""
+    for ln in raw.splitlines():
+        ln = ln.strip()
+        if ln:
+            first = ln
+            break
+    if 0 < len(first) <= 60 and not re.match(r"(?i)^(you are|act as|role\s*:)\b", first):
+        return first
+    # otherwise flatten and strip a leading role-assignment preamble (one or more sentences)
+    flat = re.sub(r"\s+", " ", raw).strip()
+    flat = re.sub(r"(?i)^(?:(?:you are|you're|act as|role\s*:)\b[^.]*\.\s*)+", "", flat)
+    return flat[:80].strip()