#!/usr/bin/env python3 """unblock.py: command-line companion for Unblock boards (DAG todo lists stored as JSON). It reads and writes the same file the web app links to, and computes the same numbers: task state, % unblocked, what to do next, and the critical path. python3 unblock.py init # start .github/unblock.json in this repository python3 unblock.py view # open the board in the browser; edits save to the file python3 unblock.py # summary python3 unblock.py next # ready tasks, most unblocking first python3 unblock.py show auth-api # one task: readiness, blockers, links python3 unblock.py tree # the whole board as an indented tree python3 unblock.py report # computed report as JSON (for agents) python3 unblock.py set auth-api done # change status python3 unblock.py edit auth-api --assignee sam --notes "- [ ] rate limits" python3 unblock.py point auth-api --note "Starting this" # highlight tasks in the open viewer python3 unblock.py diff main feature # what a branch does to the plan (also: diff main...feature, diff HEAD) python3 unblock.py init --ci # add a GitHub Action that comments that diff on every pull request python3 unblock.py mcp # MCP server (stdio) with the board as an MCP App python3 unblock.py add "Write docs" --parent launch --depends-on onboarding,dashboard python3 unblock.py link docs auth-api # docs now waits on auth-api python3 unblock.py unlink docs auth-api python3 unblock.py rm docs # delete (a group needs --ungroup or --recursive) python3 unblock.py validate Without -f it uses $UNBLOCK_FILE, or else the first of .github/unblock.json, unblock.json, board.json that exists (the same files the web viewer at unblock.esh.sh/gh// looks for). Only the standard library is used. """ import argparse import contextlib import datetime import hashlib import http.server import io import json import math import os import random import re import secrets import shlex import shutil import signal import stat import string import subprocess import sys import tempfile import textwrap import threading import time import traceback import urllib.error import urllib.parse import urllib.request import webbrowser FORMAT = "unblock/v1" BOARD_PATHS = (".github/unblock.json", "unblock.json", "board.json") STATUSES = ("todo", "doing", "done") KNOWN = ("id", "title", "status", "parent", "dependsOn", "estimate", "assignee", "tags", "notes") TOP_KNOWN = ("format", "title", "updatedAt", "view", "tasks") APP_URL = "https://unblock.esh.sh/" APP_PAGE = APP_URL + "app" SCHEMA_URL = APP_URL + "schema.json" # boards name it in "$schema", so editors check and autocomplete them # the app itself; the site's root is the landing page __version__ = "0.2.0" # packaging/build.py stamps the wheel and the npm package with it class BoardError(Exception): pass # ---------------------------------------------------------------- format def normalize(raw): """Validate raw JSON data. Returns (board, warnings); raises BoardError listing every problem.""" errors, warnings = [], [] if not isinstance(raw, dict): raise BoardError('Expected a JSON object with a "tasks" array.') if not isinstance(raw.get("tasks"), list): raise BoardError('The board needs a "tasks" array.') tasks, seen = [], set() for i, t in enumerate(raw["tasks"]): if not isinstance(t, dict): errors.append("tasks[%d] is not an object." % i) continue tid = t.get("id") tid = str(tid).strip() if isinstance(tid, (str, int)) and not isinstance(tid, bool) else "" if not tid: errors.append('tasks[%d] has no "id".' % i) continue if tid in seen: errors.append('The id "%s" is used twice.' % tid) continue seen.add(tid) status = "todo" if t.get("status") is None else str(t.get("status")) if status not in STATUSES: warnings.append('"%s" had status "%s"; treated as "todo".' % (tid, status)) status = "todo" task = {"id": tid, "title": str(t.get("title") or tid), "status": status} if t.get("parent") not in (None, ""): task["parent"] = str(t["parent"]) deps = t.get("dependsOn") if deps is not None and not isinstance(deps, list): errors.append('"%s": "dependsOn" must be a list of ids.' % tid) task["dependsOn"] = list(dict.fromkeys(str(d) for d in (deps if isinstance(deps, list) else []))) if t.get("estimate") not in (None, ""): try: e = float(t["estimate"]) if e < 0: raise ValueError task["estimate"] = int(e) if e.is_integer() else e except (TypeError, ValueError): warnings.append('"%s" has an estimate that is not a number >= 0; ignored.' % tid) if t.get("assignee"): task["assignee"] = str(t["assignee"]) if isinstance(t.get("tags"), list) and t["tags"]: task["tags"] = [str(x) for x in t["tags"]] if t.get("notes"): task["notes"] = str(t["notes"]) for k, v in t.items(): if k not in KNOWN: task[k] = v tasks.append(task) if errors: raise BoardError("\n".join(errors)) by_id = {t["id"]: t for t in tasks} for t in tasks: p = t.get("parent") if p == t["id"]: errors.append('"%s" is its own parent.' % t["id"]) elif p and p not in by_id: errors.append('"%s" has parent "%s", which does not exist.' % (t["id"], p)) for t in tasks: chain, p = {t["id"]}, t.get("parent") while p and p in by_id: if p in chain: errors.append('Parents form a loop around "%s".' % t["id"]) break chain.add(p) p = by_id[p].get("parent") for t in tasks: for d in t["dependsOn"]: if d == t["id"]: errors.append('"%s" depends on itself.' % t["id"]) elif d not in by_id: errors.append('"%s" depends on "%s", which does not exist.' % (t["id"], d)) if errors: raise BoardError("\n".join(dict.fromkeys(errors))) view = raw.get("view") if isinstance(raw.get("view"), dict) else {} collapsed = [str(x) for x in view.get("collapsed", []) if str(x) in by_id] if isinstance(view.get("collapsed"), list) else [] board = {"format": FORMAT, "title": str(raw.get("title") or "Untitled board"), "updatedAt": str(raw["updatedAt"]) if raw.get("updatedAt") else None, "view": {"collapsed": collapsed}, "tasks": tasks, "_extra": {k: v for k, v in raw.items() if k not in TOP_KNOWN}} m = Model(board) for t in tasks: for d in t["dependsOn"]: if d in m.ancestors(t["id"]): errors.append('"%s" depends on "%s", the group it sits in. A task can\'t wait on its own group.' % (t["id"], d)) elif t["id"] in m.ancestors(d): errors.append('Group "%s" depends on "%s", one of its own subtasks.' % (t["id"], d)) if not errors: cyc = m.find_cycle() if cyc: errors.append("Dependency loop: %s. Each one waits on the one before it; remove one link to break the loop." % " -> ".join('"%s"' % x for x in cyc)) if errors: raise BoardError("\n".join(errors)) return board, warnings def clean_task(t, is_group): o = {"id": t["id"], "title": t["title"]} if not is_group: o["status"] = t.get("status", "todo") if t.get("parent"): o["parent"] = t["parent"] o["dependsOn"] = t.get("dependsOn", []) if t.get("estimate") is not None: o["estimate"] = t["estimate"] for k in ("assignee", "tags", "notes"): if t.get(k): o[k] = t[k] for k, v in t.items(): if k not in KNOWN and not k.startswith("_"): o[k] = v return o def export_board(board): parents = {t["parent"] for t in board["tasks"] if t.get("parent")} out = {"$schema": board["_extra"]["$schema"]} if "$schema" in board.get("_extra", {}) else {} out.update({"format": FORMAT, "title": board["title"]}) # no updatedAt: rewriting it made every two branches conflict, and git records it anyway out.update(board.get("_extra", {})) out["view"] = {"collapsed": [c for c in board["view"].get("collapsed", []) if c in parents]} out["tasks"] = [clean_task(t, t["id"] in parents) for t in board["tasks"]] return out def pretty(v, ind=""): """Same layout as the web app: lists of plain values stay on one line.""" nx = ind + " " if isinstance(v, list): if not v: return "[]" if all(x is None or not isinstance(x, (dict, list)) for x in v): return "[" + ", ".join(json.dumps(x, ensure_ascii=False) for x in v) + "]" return "[\n" + ",\n".join(nx + pretty(x, nx) for x in v) + "\n" + ind + "]" if isinstance(v, dict): if not v: return "{}" return "{\n" + ",\n".join(nx + json.dumps(k, ensure_ascii=False) + ": " + pretty(x, nx) for k, x in v.items()) + "\n" + ind + "}" return json.dumps(v, ensure_ascii=False) def now_iso(): return datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z") def pct(done, total, done_n, total_n): if not total > 0: if not total_n: return 100 done, total = done_n, total_n p = int(round(done / total * 100 + 1e-9)) if p == 100 and done < total: p = 99 if p == 0 and done > 0: p = 1 return p # ---------------------------------------------------------------- model class Model(object): """Leaf tasks are the units of work. Depending on a group means depending on all of its leaves, and a group's own dependsOn is inherited by every leaf inside it.""" def __init__(self, board): self.board = board self.tasks = board["tasks"] self.by_id = {t["id"]: t for t in self.tasks} self.kids, self.roots = {}, [] for t in self.tasks: p = t.get("parent") if p and p in self.by_id: self.kids.setdefault(p, []).append(t["id"]) else: self.roots.append(t["id"]) self._anc, self._leaves, self._metrics = {}, {}, {} self.leaf_ids = [t["id"] for t in self.tasks if not self.is_group(t["id"])] self.pre = {l: [] for l in self.leaf_ids} self.post = {l: [] for l in self.leaf_ids} for l in self.leaf_ids: for src in [l] + self.ancestors(l): for d in self.by_id[src].get("dependsOn", []): if d not in self.by_id: continue for dl in self.leaves(d): if dl != l and dl not in self.pre[l]: self.pre[l].append(dl) self.post[dl].append(l) indeg = {l: len(self.pre[l]) for l in self.leaf_ids} topo = [l for l in self.leaf_ids if not indeg[l]] i = 0 while i < len(topo): for w in self.post[topo[i]]: indeg[w] -= 1 if not indeg[w]: topo.append(w) i += 1 if len(topo) < len(self.leaf_ids): s = set(topo) topo += [l for l in self.leaf_ids if l not in s] self.topo = topo self.topo_idx = {l: i for i, l in enumerate(topo)} self.up, self.down = {}, {} for l in topo: s = set() for p in self.pre[l]: s.add(p) s |= self.up.get(p, set()) self.up[l] = s for l in reversed(topo): s = set() for c in self.post[l]: s.add(c) s |= self.down.get(c, set()) self.down[l] = s self.state = {} for l in self.leaf_ids: st = self.by_id[l].get("status", "todo") if st in ("done", "doing"): self.state[l] = st else: self.state[l] = "ready" if all(self.is_done(p) for p in self.pre[l]) else "blocked" self.dist, self.via = {}, {} for l in topo: if self.is_done(l): self.dist[l] = 0 continue best, bp = 0, None for p in self.pre[l]: if self.is_done(p): continue d = self.dist.get(p, 0) if d > best or (bp is None and d == best and d > 0): best, bp = d, p self.dist[l] = best + self.weight(l) self.via[l] = bp end, end_d = None, 0 for l in topo: if not self.is_done(l) and self.dist[l] > end_d: end, end_d = l, self.dist[l] self.crit = self.chain_to(end) if end else [] self.crit_pts = end_d def is_group(self, tid): return tid in self.kids def is_done(self, l): return self.by_id[l].get("status") == "done" def weight(self, tid): e = self.by_id[tid].get("estimate") return 1 if e is None else e def ancestors(self, tid): if tid not in self._anc: out, guard, p = [], {tid}, self.by_id.get(tid, {}).get("parent") while p and p in self.by_id and p not in guard: guard.add(p) out.append(p) p = self.by_id[p].get("parent") self._anc[tid] = out return self._anc[tid] def leaves(self, tid): if tid not in self._leaves: self._leaves[tid] = [] if self.is_group(tid): self._leaves[tid] = [x for k in self.kids[tid] for x in self.leaves(k)] else: self._leaves[tid] = [tid] return self._leaves[tid] def chain_to(self, l): c = [] while l: c.insert(0, l) l = self.via.get(l) return c def impact(self, l): return sum(1 for d in self.down[l] if not self.is_done(d)) def find_cycle(self): color = {} for s in self.leaf_ids: if color.get(s): continue stack, it = [s], [[s, list(self.post[s]), 0]] color[s] = 1 while it: top = it[-1] if top[2] < len(top[1]): w = top[1][top[2]] top[2] += 1 c = color.get(w, 0) if c == 1: return stack[stack.index(w):] + [w] if not c: color[w] = 1 stack.append(w) it.append([w, list(self.post[w]), 0]) else: color[top[0]] = 2 stack.pop() it.pop() return None def metrics(self, tid): if tid in self._metrics: return self._metrics[tid] W = self.leaves(tid) Ws = set(W) P = set() for w in W: P |= {u for u in self.up[w] if u not in Ws} pd = pt = pdn = 0 waiting, frontier = [], [] for u in sorted(P, key=lambda x: self.topo_idx[x]): wt = self.weight(u) pt += wt if self.is_done(u): pd += wt pdn += 1 else: waiting.append(u) if self.state[u] in ("ready", "doing"): frontier.append(u) frontier.sort(key=lambda x: (-self.impact(x), self.topo_idx[x])) wd = wt_ = wdn = 0 counts = {"done": 0, "doing": 0, "ready": 0, "blocked": 0} for w in W: x = self.weight(w) wt_ += x counts[self.state[w]] += 1 if self.is_done(w): wd += x wdn += 1 D = set() for w in W: D |= {d for d in self.down[w] if d not in Ws} if not self.is_group(tid): state = self.state[tid] elif counts["done"] == len(W): state = "done" elif counts["doing"] or counts["done"]: state = "doing" elif counts["ready"]: state = "ready" else: state = "blocked" r = {"state": state, "counts": counts, "waiting": waiting, "frontier": frontier, "impact": sum(1 for d in D if not self.is_done(d)), "prereqCount": len(P), "prereqDone": pdn, "prereqW": pt, "prereqDoneW": pd, "unblocked": pct(pd, pt, pdn, len(P)), "progress": pct(wd, wt_, wdn, len(W)), "workW": wt_, "workDoneW": wd, "leaves": W} self._metrics[tid] = r return r def dep_error(self, t, d): """Why task t can't wait on d, or None if it can.""" if t == d: return "A task can't wait on itself." if t not in self.by_id or d not in self.by_id: return "Unknown task id: %s" % (t if t not in self.by_id else d) if d in self.ancestors(t): return '"%s" sits inside "%s", so it can\'t wait on it.' % (t, d) if t in self.ancestors(d): return '"%s" sits inside "%s", so the group can\'t wait on it.' % (d, t) if d in self.by_id[t].get("dependsOn", []): return '"%s" already waits on "%s".' % (t, d) lt = self.leaves(t) for ld in self.leaves(d): if any(x in self.up[ld] for x in lt): return 'That would make a loop: "%s" already waits on "%s".' % (d, t) return None def checklist(notes): """Progress of Markdown task-list items ("- [ ]" / "- [x]") in a description.""" if not notes: return None items = re.findall(r"^\s*[-*+]\s+\[([ xX])\]", str(notes), re.M) return {"done": sum(1 for x in items if x in "xX"), "total": len(items)} if items else None def build_report(board): m = Model(board) c = {"ready": 0, "doing": 0, "blocked": 0, "done": 0} tw = dw = 0 for l in m.leaf_ids: c[m.state[l]] += 1 tw += m.weight(l) if m.state[l] == "done": dw += m.weight(l) tasks = {} for t in m.tasks: x = m.metrics(t["id"]) tasks[t["id"]] = {"title": t["title"], "kind": "group" if m.is_group(t["id"]) else "task", "state": x["state"], "unblockedPct": x["unblocked"], "progressPct": x["progress"], "upstream": {"total": x["prereqCount"], "done": x["prereqDone"]}, "doNext": x["frontier"], "waitingOn": x["waiting"], "unblocksOpen": x["impact"]} ck = checklist(t.get("notes")) if ck: tasks[t["id"]]["checklist"] = ck ready = sorted([l for l in m.leaf_ids if m.state[l] == "ready"], key=lambda l: (-m.impact(l), m.topo_idx[l])) return {"format": "unblock-report/v1", "title": board["title"], "boardUpdatedAt": board.get("updatedAt"), "summary": {"tasks": len(m.leaf_ids), "groups": len(m.tasks) - len(m.leaf_ids), "ready": c["ready"], "doing": c["doing"], "blocked": c["blocked"], "done": c["done"], "progressPct": pct(dw, tw, c["done"], len(m.leaf_ids)), "pointsDone": dw, "pointsTotal": tw}, "next": [{"id": l, "title": m.by_id[l]["title"], "unblocksOpen": m.impact(l), "estimate": m.weight(l)} for l in ready], "criticalPath": {"points": m.crit_pts, "tasks": m.crit}, "tasks": tasks} # ---------------------------------------------------------------- io def load(path): try: with open(path, encoding="utf-8") as f: raw = json.load(f) except FileNotFoundError: raise BoardError("No board at %s. Create .github/unblock.json (the app can save one: JSON > Save to file), or pass -f." % path) except json.JSONDecodeError as e: raise BoardError("%s is not valid JSON: %s" % (path, e)) board, warnings = normalize(raw) for w in warnings: print("warning: " + w, file=sys.stderr) return board def write_file(path, text): """Write text to path, atomically and never through a symlink. A repository can commit links (say .github/unblock.json.tmp -> ~/.zshenv, or README.md -> ~/.bashrc), so the text goes to a new temporary file that then replaces path itself: a link is replaced, its target is never touched.""" d = os.path.dirname(os.path.abspath(path)) fd, tmp = tempfile.mkstemp(dir=d, prefix="." + os.path.basename(path) + ".", suffix=".tmp") # O_EXCL: never an existing file try: with os.fdopen(fd, "w", encoding="utf-8", newline="") as f: # LF on Windows too, or every save rewrites each line f.write(text) try: st = os.lstat(path) mode = stat.S_IMODE(st.st_mode) if stat.S_ISREG(st.st_mode) else 0o644 except FileNotFoundError: mode = 0o644 os.chmod(tmp, mode) os.replace(tmp, path) except BaseException: try: os.remove(tmp) except OSError: pass raise UNDO_KEEP = 20 UNDO_LABEL = None # what the next save is called in `unblock undo --list`; the command line by default def save(path, board): exported = export_board(board) normalize(json.loads(json.dumps(exported))) # never write a board the app would refuse text = pretty(exported) + "\n" old = None if os.path.isfile(path): with open(path, encoding="utf-8") as f: old = f.read() write_file(path, text) if old is not None and old != text: remember_undo(path, old, text) def _undo_file(path): return os.path.join(os.path.dirname(_claims_file(path)), "undo.json") def _sha(text): return hashlib.sha256(text.encode("utf-8")).hexdigest() def remember_undo(path, before, after): """Keep the board as it was before a save, so `unblock undo` can put it back (the last UNDO_KEEP, per board).""" try: f = _undo_file(path) os.makedirs(os.path.dirname(f), exist_ok=True) try: with open(f, encoding="utf-8") as fh: data = json.load(fh) except (OSError, ValueError): data = {} key = _board_key(path) label = UNDO_LABEL or " ".join(["unblock"] + sys.argv[1:4]) data[key] = ((data.get(key) or []) + [{"at": int(time.time()), "what": label[:120], "before": before, "after": _sha(after)}])[-UNDO_KEEP:] write_file(f, json.dumps(data)) except (OSError, BoardError, ValueError): pass # undo is a convenience: never let it fail a save def _ago(ts): s = max(0, int(time.time() - ts)) return "%ds ago" % s if s < 90 else "%dm ago" % (s // 60) if s < 5400 else "%dh ago" % (s // 3600) if s < 129600 else "%dd ago" % (s // 86400) def cmd_undo(args): """`unblock undo`: put the board back as it was before the last save by unblock (the CLI or the MCP server).""" path = args.file f = _undo_file(path) try: with open(f, encoding="utf-8") as fh: data = json.load(fh) except (OSError, ValueError): data = {} key = _board_key(path) stack = data.get(key) or [] if args.list: if not stack: print("Nothing to undo.") for e in reversed(stack): print("%-9s %s" % (_ago(e["at"]), e["what"])) return 0 if not stack: raise BoardError("Nothing to undo: unblock keeps the board from before each of its own saves, and there are none yet.") last = stack[-1] with open(path, encoding="utf-8") as fh: cur = fh.read() if _sha(cur) != last["after"]: raise BoardError("The board changed since `%s` (%s), outside unblock: undoing would lose that change too. Use git for it (git diff %s)." % (last["what"], _ago(last["at"]), path)) board, _ = normalize(json.loads(last["before"])) pct = build_report(load(path))["summary"]["progressPct"] write_file(path, last["before"]) data[key] = stack[:-1] write_file(f, json.dumps(data)) r = build_report(board)["summary"] print("undid %s (%s)" % (last["what"], _ago(last["at"]))) print(signature(r["progressPct"], pct, ["%d of %d tasks done" % (r["done"], r["tasks"])])) return 0 def new_id(board, title): base = re.sub(r"-+", "-", re.sub(r"[\s_]+", "-", re.sub(r"[^\w\s-]", "", title.lower()).strip()))[:32] taken = {t["id"] for t in board["tasks"]} if base and base not in taken: return base while True: cand = (base + "-" if base else "t-") + "".join(random.choice(string.ascii_lowercase + string.digits) for _ in range(4)) if cand not in taken: return cand def need(m, tid): if tid not in m.by_id: close = [t for t in m.by_id if tid.lower() in t.lower() or tid.lower() in m.by_id[t]["title"].lower()] hint = (" Did you mean: " + ", ".join(close[:5]) + "?") if close else "" raise BoardError('No task with id "%s".%s' % (tid, hint)) return m.by_id[tid] # ---------------------------------------------------------------- output helpers MARK = {"done": "[x]", "doing": "[~]", "ready": "[ ]", "blocked": "[.]"} def fmt_num(n): return str(int(n)) if float(n).is_integer() else "%.1f" % n def bar(counts, width=24): total = sum(counts.values()) or 1 out = "" for k, ch in (("done", "#"), ("doing", "~"), ("ready", "o"), ("blocked", ".")): out += ch * int(round(counts[k] / total * width)) return (out + "." * width)[:width] def line(m, l, extra=""): t = m.by_id[l] grp = m.by_id[m.ancestors(l)[0]]["title"] if m.ancestors(l) else "" bits = [b for b in (grp, "@" + t["assignee"] if t.get("assignee") else "", extra) if b] return "%s %-24s %s%s" % (MARK[m.metrics(l)["state"]], l, t["title"], (" (" + " · ".join(bits) + ")") if bits else "") # ---------------------------------------------------------------- commands def cmd_summary(board, args): m = Model(board) r = build_report(board)["summary"] print("%s\n" % board["title"]) c = {k: r[k] for k in ("done", "doing", "ready", "blocked")} print(" %s %d%% done (%d of %d tasks, %s of %s pt)" % (bar(c), r["progressPct"], r["done"], r["tasks"], fmt_num(r["pointsDone"]), fmt_num(r["pointsTotal"]))) print(" %d ready · %d doing · %d blocked · %d done\n" % (r["ready"], r["doing"], r["blocked"], r["done"])) doing = [l for l in m.topo if m.state[l] == "doing"] if doing: print("In progress") for l in doing: print(" " + line(m, l)) print() ready = sorted([l for l in m.leaf_ids if m.state[l] == "ready"], key=lambda l: (-m.impact(l), m.topo_idx[l])) if ready: print("Ready to start (most unblocking first)") for l in ready[:8]: print(" " + line(m, l, "unblocks %d" % m.impact(l) if m.impact(l) else "")) if len(ready) > 8: print(" ... and %d more (see: next)" % (len(ready) - 8)) print() if m.crit: print("Critical path: %s pt of open work in %d step%s" % (fmt_num(m.crit_pts), len(m.crit), "" if len(m.crit) == 1 else "s")) print(" " + " -> ".join(m.crit)) def in_scope(m, tid, scope): return not scope or scope in m.ancestors(tid) def check_scope(m, scope): if scope and (scope not in m.by_id or not m.is_group(scope)): raise BoardError('"%s" is not a group.' % scope) def waves(board, held=None, me=None): """Open tasks in sets that can run in parallel: set 1 is ready now, each later set only waits on earlier ones. Tasks other agents hold count as in progress.""" m = Model(board) held = held or {} open_ = [l for l in m.topo if m.state[l] != "done"] busy = {l for l in open_ if m.state[l] == "doing" or (l in held and held[l]["by"] != me)} level, out = {}, [] for l in open_: # topological order: every open task after the ones it waits on if l in busy: continue ups = [u for u in m.pre[l] if m.state[u] != "done"] level[l] = 1 + max([1 if u in busy else level.get(u, 0) for u in ups] or [0]) # work in progress fills the first set for l, lv in level.items(): while len(out) < lv: out.append([]) out[lv - 1].append(l) return [sorted(w, key=lambda l: (-m.impact(l), m.topo_idx[l])) for w in out] def cmd_next(board, args): rep = build_report(board) m0 = Model(board) check_scope(m0, args.within) held = active_claims(args.file) if getattr(args, "file", None) else {} me = default_holder(args.file) if held else None if getattr(args, "waves", False): ws = waves(board, held, me) if args.json: print(pretty([[{"id": l, "title": m0.by_id[l]["title"]} for l in w] for w in ws])) return if not ws: print("Nothing open.") for i, w in enumerate(ws[: args.limit or len(ws)]): print("%s (%d task%s%s)" % ("Now" if i == 0 else "Then, set %d" % (i + 1), len(w), "" if len(w) == 1 else "s", ", in parallel" if len(w) > 1 else "")) for l in w: print(" " + line(m0, l)) return items = [it for it in rep["next"] if in_scope(m0, it["id"], args.within) and (it["id"] not in held or held[it["id"]]["by"] == me)] items = items[: args.limit] if args.limit else items if args.json: print(pretty(items)) return others = sorted(k for k, v in held.items() if v["by"] != me) if others: print("(skipping %d claimed by other agents: %s)" % (len(others), ", ".join(others))) m = Model(board) if not items: print("Nothing is ready. " + ("Everything is done." if rep["summary"]["done"] == rep["summary"]["tasks"] else "Finish the tasks in progress first.")) for it in items: print(line(m, it["id"], "unblocks %d" % it["unblocksOpen"] if it["unblocksOpen"] else "")) # ---------------------------------------------------------------- claims: two agents never take the same task # A claim is a lease on a task: who holds it and until when. Claims live in the repository's shared git folder # (`git rev-parse --git-common-dir`), so every worktree on this machine sees them, even before branches merge; outside # git they live in the cache folder. Claiming also marks the task doing in the board, which is what people see. def _lease(text): mo = re.match(r"^\s*(\d+(?:\.\d+)?)\s*([smhd]?)\s*$", str(text or "2h")) if not mo: raise BoardError('A lease looks like 30m, 2h or 1d, not "%s".' % text) return float(mo.group(1)) * {"s": 1, "m": 60, "h": 3600, "d": 86400, "": 3600}[mo.group(2)] def _claims_file(path): d = os.path.dirname(os.path.abspath(path)) try: r = subprocess.run(["git", "rev-parse", "--git-common-dir"], cwd=d, capture_output=True, text=True) except OSError: # no git on this machine: as outside a repository r = None if r is not None and r.returncode == 0 and r.stdout.strip(): return os.path.join(os.path.abspath(os.path.join(d, r.stdout.strip())), "unblock", "claims.json") return os.path.join(cache_dir(), "claims", hashlib.sha1(os.path.realpath(path).encode("utf-8")).hexdigest()[:16] + ".json") def _board_key(path): """The board's path inside its repository, so every worktree names it the same way. Outside git, its full path: boards outside git share one folder for claims, points and undo, and two garden.unblock.json must not mix.""" top = _git_top(os.path.dirname(os.path.abspath(path))) if not top: return os.path.realpath(path).replace(os.sep, "/") return os.path.relpath(os.path.realpath(path), top).replace(os.sep, "/") ACTIVITY_KEEP, ACTIVITY_FRESH, ACTIVITY_DROP = 5, 1800, 4 * 3600 # entries per task; faded after 30 min; gone after 4 h ACTIVE_SHOWN = 3 # busy tasks opened per group in a folded picture; the rest are counted def _activity_file(path): """What agents said they're doing, next to the claims: on this machine, never in the repository or in Jira.""" return _claims_file(path)[:-len(".json")] + "-activity.json" def _when(v): """Epoch seconds from seconds or ISO 8601 (2026-10-06T12:00:00Z); None if neither.""" if isinstance(v, (int, float)) and not isinstance(v, bool): return float(v) try: d = datetime.datetime.fromisoformat(str(v).strip().replace("Z", "+00:00")) return (d if d.tzinfo else d.replace(tzinfo=datetime.timezone.utc)).timestamp() except ValueError: return None def say(path, entries): """Add (id, text, agent, at) entries to the board's activity: the last ACTIVITY_KEEP per task, none older than ACTIVITY_DROP. ponytail: read-modify-write without a lock; two says in the same instant can lose one.""" f, key, now = _activity_file(path), _board_key(path), time.time() try: with open(f, encoding="utf-8") as fh: data = json.load(fh) except (OSError, ValueError): data = {} b = data.setdefault(key, {}) if isinstance(data, dict) else {} for tid, text, agent, at in entries: b.setdefault(tid, []).append({"text": str(text)[:200], "agent": str(agent or "agent")[:40], "at": at or now}) for tid in list(b): b[tid] = [e for e in b[tid] if now - e.get("at", 0) < ACTIVITY_DROP][-ACTIVITY_KEEP:] if not b[tid]: del b[tid] os.makedirs(os.path.dirname(f), exist_ok=True) write_file(f, json.dumps(data)) def activity(path): """{task id: its latest entry, with "age" in seconds}, for entries younger than ACTIVITY_DROP.""" try: with open(_activity_file(path), encoding="utf-8") as fh: b = json.load(fh).get(_board_key(path)) or {} except (OSError, ValueError, AttributeError): return {} now = time.time() return {k: dict(v[-1], age=now - v[-1]["at"]) for k, v in b.items() if v and now - v[-1].get("at", 0) < ACTIVITY_DROP} def activity_text(e): return "%s · %s · %s" % (e["agent"], e["text"], _ago(e["at"])) def cmd_say(board, args): """`unblock say "what I'm doing"`: a line on the task for the board's pictures and viewer, on this machine only. `--from file.json` takes {id: {text, at, agent}} from an orchestrator, every agent at once.""" m = Model(board) if args.src: with (sys.stdin if args.src == "-" else open(args.src, encoding="utf-8")) as fh: raw = json.load(fh) entries = [(k, v.get("text"), v.get("agent") or args.agent, _when(v.get("at")) if v.get("at") is not None else None) for k, v in (raw.items() if isinstance(raw, dict) else []) if isinstance(v, dict) and v.get("text")] elif args.id and args.text: entries = [(args.id, args.text, args.agent, None)] else: raise BoardError('Say what: unblock say "what you\'re doing", or unblock say --from activity.json') unknown = [e[0] for e in entries if e[0] not in m.by_id] entries = [e for e in entries if e[0] in m.by_id] if unknown: print("note: no task %s on this board; skipped" % ", ".join(unknown[:10]), file=sys.stderr) say(args.file, entries) print("said on %d task%s" % (len(entries), "" if len(entries) == 1 else "s")) def default_holder(path): if os.environ.get("UNBLOCK_AGENT"): return os.environ["UNBLOCK_AGENT"] d = os.path.dirname(os.path.abspath(path)) r = subprocess.run(["git", "rev-parse", "--show-toplevel"], cwd=d, capture_output=True, text=True) where = os.path.basename(r.stdout.strip()) if r.returncode == 0 else os.path.basename(d) import getpass import socket try: who = getpass.getuser() except Exception: who = "agent" return "%s@%s:%s" % (who, socket.gethostname().split(".")[0], where) @contextlib.contextmanager def _claims(path): """Read and write the claims file under a lock; yields (claims for this board, now).""" f = _claims_file(path) os.makedirs(os.path.dirname(f), exist_ok=True) lock = f + ".lock" end = time.time() + 5 while True: try: fd = os.open(lock, os.O_CREAT | os.O_EXCL | os.O_WRONLY) os.close(fd) break except FileExistsError: try: if time.time() - os.path.getmtime(lock) > 30: # left behind by a process that died os.remove(lock) continue except OSError: continue if time.time() > end: raise BoardError("The claims file is locked (%s). Try again." % lock) time.sleep(0.05) try: try: with open(f, encoding="utf-8") as fh: data = json.load(fh) except (OSError, ValueError): data = {} now = time.time() key = _board_key(path) mine = {k: v for k, v in (data.get(key) or {}).items() if v.get("until", 0) > now} # expired leases free the task before = json.dumps(data.get(key) or {}, sort_keys=True) yield mine, now if json.dumps(mine, sort_keys=True) != before: # only on a change: readers (a status line, a pane) watch this file data[key] = mine write_file(f, json.dumps({k: v for k, v in data.items() if v}, indent=1)) finally: try: os.remove(lock) except OSError: pass def active_claims(path): try: with _claims(path) as (c, now): return dict(c) except BoardError: return {} def _until(ts): return time.strftime("%H:%M", time.localtime(ts)) + ("" if ts - time.time() < 86400 else time.strftime(" on %b %d", time.localtime(ts))) def task_from_checkout(m, path): """The task this checkout is for, by its branch (claude/, copilot/, unblock/, or just ) or the worktree's folder name; None when neither names an open task.""" d = os.path.dirname(os.path.abspath(path)) names = [] try: names.append(git(["rev-parse", "--abbrev-ref", "HEAD"], cwd=d).strip()) names.append(os.path.basename(git(["rev-parse", "--show-toplevel"], cwd=d).strip())) except BoardError: pass for n in names: for cand in (n, n.rsplit("/", 1)[-1]): if cand in m.by_id and not m.is_group(cand) and m.by_id[cand].get("status") != "done": return cand return None def cmd_claim(board, args): m = Model(board) if not args.id: # from the branch or worktree it's run in args.id = task_from_checkout(m, args.file) if not args.id: raise BoardError("Say which task: unblock claim . (Without one it claims the task the branch or worktree is named after, such as claude/, and this one names none.)") t = need(m, args.id) if m.is_group(args.id): raise BoardError('"%s" is a group. Claim one of its tasks.' % args.id) if t.get("status") == "done": raise BoardError('"%s" is already done.' % args.id) holder = args.holder or default_holder(args.file) with _claims(args.file) as (c, now): cur = c.get(args.id) if cur and cur["by"] != holder and not args.force: raise BoardError('"%s" is claimed by %s until %s. Pick another task, or pass --force to take it over.' % (args.id, cur["by"], _until(cur["until"]))) renew = bool(cur and cur["by"] == holder) c[args.id] = {"by": holder, "until": now + _lease(args.lease), "since": (cur or {}).get("since", now) if renew else now} if os.environ.get("CLAUDECODE"): # Claude Code sets this in its shell, so the board can say which agent holds it c[args.id]["agent"] = "claude" c[args.id].update({k: cur[k] for k in ("session", "state", "seen") if renew and k in cur}) until = c[args.id]["until"] state = m.metrics(args.id)["state"] if t.get("status") != "doing": t["status"] = "doing" save(args.file, board) print("%s %s as %s until %s; it's doing now" % ("renewed" if renew else "claimed", args.id, holder, _until(until))) if state == "blocked": print("note: %d upstream tasks are still open" % len(m.metrics(args.id)["waiting"])) def release_claim(path, tid, holder=None, force=False): with _claims(path) as (c, now): cur = c.get(tid) if not cur: return None if holder and cur["by"] != holder and not force: raise BoardError('"%s" is claimed by %s, not by you. Pass --force to release it anyway.' % (tid, cur["by"])) del c[tid] return cur def cmd_release(board, args): need(Model(board), args.id) cur = release_claim(args.file, args.id, args.holder or default_holder(args.file), args.force) print(("released %s (was %s's)" % (args.id, cur["by"])) if cur else "%s isn't claimed" % args.id) def cmd_claims(board, args): c = active_claims(args.file) if args.json: print(pretty([{"id": k, "by": v["by"], "until": datetime.datetime.fromtimestamp(v["until"], datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")} for k, v in sorted(c.items())])) return if not c: print("No tasks are claimed.") m = Model(board) for k, v in sorted(c.items()): print("%-24s %s (%s, until %s)" % (k, m.by_id[k]["title"] if k in m.by_id else "(not on this board)", v["by"], _until(v["until"]))) def task_durations(path, limit=60): """How long finished tasks took, from the board file's git history: {id: seconds from the first commit where it was doing to the first where it was done}. Tasks never seen doing don't count.""" try: versions = board_versions(path, limit) except BoardError: return {} start, out = {}, {} for v in versions: try: ts = datetime.datetime.fromisoformat(v["date"]).timestamp() except (ValueError, TypeError): continue for t in (v["board"] or {}).get("tasks", []): st, tid = t.get("status"), t.get("id") if st == "doing": start.setdefault(tid, ts) elif st == "done" and tid in start and tid not in out: out[tid] = ts - start[tid] return out def _took(seconds): h = seconds / 3600 return "under an hour" if h < 1 else "about %d hour%s" % (round(h), "" if round(h) == 1 else "s") if h < 36 else "about %d days" % round(h / 24) def estimate_line(m, tid, durations): """`Tasks in took about 2 days from start to done (median of 5)`, or None without enough history.""" med = lambda xs: sorted(xs)[len(xs) // 2] parent = m.by_id[tid].get("parent") peers = [d for k, d in durations.items() if k in m.by_id and k != tid and parent and m.by_id[k].get("parent") == parent] if len(peers) >= 2: return 'Tasks in "%s" took %s from start to done (median of %d)' % (m.by_id[parent]["title"], _took(med(peers)), len(peers)) every = [d for k, d in durations.items() if k != tid] if len(every) >= 3: return "Tasks on this board took %s from start to done (median of %d)" % (_took(med(every)), len(every)) return None def cmd_show(board, args): m = Model(board) t = need(m, args.id) x = m.metrics(args.id) if args.json: print(pretty(build_report(board)["tasks"][args.id])) return kind = "group of %d tasks" % len(x["leaves"]) if m.is_group(args.id) else "task" path = " > ".join(m.by_id[a]["title"] for a in reversed(m.ancestors(args.id))) print("%s (%s, %s)%s" % (t["title"], args.id, kind, ("\n in " + path) if path else "")) print(" state: %s" % x["state"]) if x["prereqCount"]: print(" %d%% unblocked: %d of %d upstream tasks done, %s of %s pt" % (x["unblocked"], x["prereqDone"], x["prereqCount"], fmt_num(x["prereqDoneW"]), fmt_num(x["prereqW"]))) else: print(" nothing upstream") if m.is_group(args.id): print(" progress: %d%% %s" % (x["progress"], bar(x["counts"], 16))) if x["frontier"]: print("\n Do next to unblock it:") for l in x["frontier"]: print(" " + line(m, l, "unblocks %d" % m.impact(l) if m.impact(l) else "")) if t.get("dependsOn"): print("\n Waits on:") for d in t["dependsOn"]: print(" %s %s %s" % (MARK[m.metrics(d)["state"]], d, m.by_id[d]["title"])) for a in m.ancestors(args.id): if m.by_id[a].get("dependsOn"): print(" (via group %s: %s)" % (a, ", ".join(m.by_id[a]["dependsOn"]))) dependents = [o["id"] for o in m.tasks if args.id in o.get("dependsOn", [])] if dependents: print("\n Unblocks:") for d in dependents: print(" %s %s %s" % (MARK[m.metrics(d)["state"]], d, m.by_id[d]["title"])) ck = checklist(t.get("notes")) if ck: print("\n Checklist: %d of %d done" % (ck["done"], ck["total"])) where = getattr(args, "file", None) # the MCP server runs show without one if not m.is_group(args.id) and x["state"] != "done" and where and os.path.isfile(where): est = estimate_line(m, args.id, task_durations(where)) if est: print("\n " + est) if t.get("notes"): print("\n Description:\n" + "\n".join(" " + line for line in t["notes"].splitlines())) def cmd_tree(board, args): m = Model(board) check_scope(m, args.within) print(board["title"] + (" > " + " > ".join(m.by_id[a]["title"] for a in list(reversed(m.ancestors(args.within))) + [args.within]) if args.within else "")) def walk(ids, ind): for tid in ids: x = m.metrics(tid) if m.is_group(tid): ub = "" if x["unblocked"] == 100 else ", %d%% unblocked" % x["unblocked"] print("%s%s %d/%d done%s [%s]" % (ind, m.by_id[tid]["title"], x["counts"]["done"], len(x["leaves"]), ub, tid)) walk(m.kids[tid], ind + " ") else: ub = " %d%% unblocked" % x["unblocked"] if x["state"] == "blocked" else "" print("%s%s %s%s [%s]" % (ind, MARK[x["state"]], m.by_id[tid]["title"], ub, tid)) walk(m.kids[args.within] if args.within else m.roots, " ") def cmd_report(board, args): print(pretty(build_report(board))) def cmd_validate(board, args): m = Model(board) links = sum(len(t["dependsOn"]) for t in board["tasks"]) print("OK: %d tasks, %d groups, %d links, no loops." % (len(m.leaf_ids), len(m.tasks) - len(m.leaf_ids), links)) def cmd_set(board, args): m = Model(board) t = need(m, args.id) if m.is_group(args.id): raise BoardError('"%s" is a group; its status comes from its subtasks.' % args.id) before = {l for l in m.leaf_ids if m.state[l] == "ready"} pct_before = build_report(board)["summary"]["progressPct"] was = m.state[args.id] t["status"] = args.status if getattr(args, "note", None): t["notes"] = add_note(t.get("notes"), args.note, args.status) save(args.file, board) if args.status != "doing": # finished or put back: the task is free again try: release_claim(args.file, args.id, force=True) except BoardError: pass m2 = Model(board) print("%s: %s -> %s" % (args.id, was, args.status)) if args.status == "doing" and was == "blocked": print("note: started while %d upstream tasks are still open" % len(m.metrics(args.id)["waiting"])) print_moment(board, m2, before, pct_before) def signature(pct, before=None, parts=()): """Unblock's one line for where the plan stands, the same in the CLI, the status line, MCP results and the plugin's band: ▸ Unblock ▰▰▰▰▰▰▰▰▱▱ 81% → 82% · 15 ready. `before` adds how progress moved.""" filled = int(pct / 10 + 0.5) head = "▸ Unblock %s %s" % ("▰" * filled + "▱" * (10 - filled), "%d%% → %d%%" % (before, pct) if before is not None and before != pct else "%d%%" % pct) return " · ".join([head] + [p for p in parts if p]) def print_moment(board, m2, before, pct_before): """What a status change did, in two short lines an agent can pass on: what's ready now, and the plan's progress.""" now = [l for l in m2.leaf_ids if m2.state[l] == "ready" and l not in before] if now: print("now ready: " + ", ".join(now)) r = build_report(board)["summary"] if r["progressPct"] != pct_before: print(signature(r["progressPct"], pct_before, ["%d of %d tasks done" % (r["done"], r["tasks"])])) def add_note(notes, note, status=None): """Append a dated one-line note (what was decided, what was learned) to a task's description.""" stamp = time.strftime("%Y-%m-%d") line = "%s%s: %s" % ("Done " if status == "done" else "", stamp, note.strip()) return (notes.rstrip() + "\n\n" if (notes or "").strip() else "") + line def cmd_edit(board, args): """Change a task's fields. An empty string clears assignee, tags, notes, estimate, or (for parent) moves it to the top level.""" m = Model(board) t = need(m, args.id) changed = [] if args.status is not None: if m.is_group(args.id): raise BoardError('"%s" is a group; its status comes from its subtasks.' % args.id) if args.status not in STATUSES: raise BoardError("status must be one of %s" % ", ".join(STATUSES)) before = {l for l in m.leaf_ids if m.state[l] == "ready"} pct_before = build_report(board)["summary"]["progressPct"] if args.title is not None: if not args.title.strip(): raise BoardError("The title can't be empty.") t["title"] = args.title.strip() changed.append("title") if args.status is not None and args.status != t.get("status"): t["status"] = args.status changed.append("status -> " + args.status) if getattr(args, "note", None): t["notes"] = add_note(t.get("notes") if args.notes is None else args.notes, args.note, args.status) changed.append("note") elif args.notes is not None: if args.notes: t["notes"] = args.notes else: t.pop("notes", None) changed.append("description") if args.estimate is not None: if args.estimate in ("", None): t.pop("estimate", None) else: try: e = float(args.estimate) except ValueError: raise BoardError("estimate must be a number") if e < 0: raise BoardError("estimate can't be negative") t["estimate"] = int(e) if e.is_integer() else e changed.append("estimate") if args.assignee is not None: if args.assignee.strip(): t["assignee"] = args.assignee.strip().lstrip("@") else: t.pop("assignee", None) changed.append("assignee") if getattr(args, "issue", None) is not None: if args.issue.strip(): t["issue"] = issue_ref(args.issue) else: t.pop("issue", None) changed.append("issue") if getattr(args, "ref", None) is not None: if args.ref.strip(): if not parse_ref(args.ref): raise BoardError('A ref is written owner/repo, owner/repo#task, owner/repo:path/board.json#task, ../path/board.json#task, or other.unblock.json#task for a plan beside this one.') t["ref"] = args.ref.strip() else: t.pop("ref", None) changed.append("ref") if args.tags is not None: tags = args.tags if isinstance(args.tags, list) else args.tags.split(",") tags = [x.strip() for x in tags if x and x.strip()] if tags: t["tags"] = tags else: t.pop("tags", None) changed.append("tags") if args.parent is not None: par = args.parent.strip() if par: need(m, par) if par == args.id or args.id in m.ancestors(par): raise BoardError('"%s" can\'t go inside itself.' % args.id) t["parent"] = par else: t.pop("parent", None) changed.append("parent") if not changed: print("nothing to change") return try: normalize(json.loads(json.dumps(export_board(board)))) except BoardError as e: raise BoardError("Not changed. %s" % e) save(args.file, board) if args.status is not None and args.status != "doing": try: release_claim(args.file, args.id, force=True) except BoardError: pass m2 = Model(board) print("%s: %s" % (args.id, ", ".join(changed))) print_moment(board, m2, before, pct_before) def cmd_add(board, args): m = Model(board) if args.parent: need(m, args.parent) deps = [d.strip() for d in (args.depends_on or "").split(",") if d.strip()] for d in deps: need(m, d) tid = args.id or new_id(board, args.title) if tid in m.by_id: raise BoardError('The id "%s" is already used.' % tid) t = {"id": tid, "title": args.title, "status": args.status, "dependsOn": deps} if args.parent: t["parent"] = args.parent if args.estimate is not None: t["estimate"] = int(args.estimate) if float(args.estimate).is_integer() else args.estimate if args.assignee: t["assignee"] = args.assignee if getattr(args, "issue", None): t["issue"] = issue_ref(args.issue) if getattr(args, "ref", None): if not parse_ref(args.ref): raise BoardError('A ref is written owner/repo, owner/repo#task, owner/repo:path/board.json#task, ../path/board.json#task, or other.unblock.json#task for a plan beside this one.') t["ref"] = args.ref.strip() if args.tags: t["tags"] = [x.strip() for x in args.tags.split(",") if x.strip()] if args.notes: t["notes"] = args.notes # keep JSON order following the tree: insert after the parent's last descendant at = len(board["tasks"]) if args.parent: idx = [i for i, x in enumerate(board["tasks"]) if x["id"] == args.parent or args.parent in m.ancestors(x["id"])] at = max(idx) + 1 board["tasks"].insert(at, t) try: normalize(json.loads(json.dumps(export_board(board)))) except BoardError as e: raise BoardError("Not added. %s" % e) save(args.file, board) x = Model(board).metrics(tid) print("added %s (%s, %d%% unblocked)" % (tid, x["state"], x["unblocked"])) def cmd_link(board, args): m = Model(board) need(m, args.task) need(m, args.prereq) err = m.dep_error(args.task, args.prereq) if err: raise BoardError(err) m.by_id[args.task]["dependsOn"].append(args.prereq) save(args.file, board) print("%s now waits on %s" % (args.task, args.prereq)) def cmd_unlink(board, args): m = Model(board) t = need(m, args.task) if args.prereq not in t["dependsOn"]: raise BoardError('"%s" does not wait on "%s" directly.' % (args.task, args.prereq)) t["dependsOn"].remove(args.prereq) save(args.file, board) print("%s no longer waits on %s" % (args.task, args.prereq)) def cmd_rm(board, args): m = Model(board) t = need(m, args.id) if m.is_group(args.id): if args.ungroup: kids = [x for x in board["tasks"] if x.get("parent") == args.id] kid_ids = [k["id"] for k in kids] for k in kids: if t.get("parent"): k["parent"] = t["parent"] else: k.pop("parent", None) k["dependsOn"] = list(dict.fromkeys(k["dependsOn"] + t["dependsOn"])) for x in board["tasks"]: if args.id in x["dependsOn"]: x["dependsOn"] = list(dict.fromkeys([d for d in x["dependsOn"] if d != args.id] + kid_ids)) board["tasks"] = [x for x in board["tasks"] if x["id"] != args.id] save(args.file, board) print("removed group %s; kept %d tasks" % (args.id, len(kids))) return if not args.recursive: raise BoardError('"%s" is a group. Pass --ungroup to keep its tasks, or --recursive to delete them too.' % args.id) gone = {args.id} | {x["id"] for x in board["tasks"] if args.id in m.ancestors(x["id"])} board["tasks"] = [x for x in board["tasks"] if x["id"] not in gone] for x in board["tasks"]: x["dependsOn"] = [d for d in x["dependsOn"] if d not in gone] save(args.file, board) print("deleted %d task%s" % (len(gone), "" if len(gone) == 1 else "s")) # ---------------------------------------------------------------- which plan: one rule for the CLI, the MCP server, the # plugin and the viewer. A plan is any JSON file with "format": "unblock/v1"; a folder can keep several (garden.unblock.json, # launch.unblock.json), and git is optional. In order: the file named (-f, the MCP tools' board argument), $UNBLOCK_FILE, # the folder's choice (`unblock use`, kept in .unblock/settings.json, looked up from here to the top of the repository), # the usual names (.github/unblock.json, unblock.json, board.json), and the only *.unblock.json. Several plans and no # choice is a question for the person, never a guess. .unblock/ is personal state: it's never committed. PLAN_SUFFIX = ".unblock.json" UNBLOCK_DIR = ".unblock" NO_WALK = {".git", "node_modules", ".venv", "venv", "__pycache__", "dist", "build", UNBLOCK_DIR} def plans_here(folder): """The plans kept right in `folder`: the usual names first, then *.unblock.json by name.""" out = [os.path.join(folder, p) for p in BOARD_PATHS if os.path.isfile(os.path.join(folder, p))] try: names = sorted(n for n in os.listdir(folder) if n.endswith(PLAN_SUFFIX) and os.path.isfile(os.path.join(folder, n))) except OSError: names = [] return out + [os.path.join(folder, n) for n in names if os.path.join(folder, n) not in out] def plans_below(folder, depth=2): """The plans in `folder` and its subfolders, `depth` levels down (not into .git, node_modules and the like).""" out, level = [], [folder] for d in range(depth + 1): nxt = [] for f in level: out += [p for p in plans_here(f) if p not in out] if d < depth: try: nxt += [os.path.join(f, n) for n in sorted(os.listdir(f)) if os.path.isdir(os.path.join(f, n)) and n not in NO_WALK and not (n.startswith(".") and n != ".github")] except OSError: pass level = nxt return out def plan_name(path): """What a plan is called in lists and in `unblock use `: garden for garden.unblock.json, else the file's name.""" base = os.path.basename(path) if base.endswith(PLAN_SUFFIX): return base[:-len(PLAN_SUFFIX)] if path.replace(os.sep, "/").endswith(".github/unblock.json") or base == "unblock.json": return os.path.basename(plan_folder(path)) or "unblock" return os.path.splitext(base)[0] def plan_folder(path): """The folder a plan belongs to: the repository's for .github/unblock.json, else the file's own.""" d = os.path.dirname(os.path.abspath(path)) return os.path.dirname(d) if path.replace(os.sep, "/").endswith(".github/unblock.json") else d def _settings_file(folder): return os.path.join(folder, UNBLOCK_DIR, "settings.json") def read_settings(folder): try: with open(_settings_file(folder), encoding="utf-8") as f: data = json.load(f) return data if isinstance(data, dict) else {} except (OSError, ValueError): return {} def _git_top(folder): """The top of the git repository `folder` is in; None outside one, or where there's no git at all.""" try: r = subprocess.run(["git", "rev-parse", "--show-toplevel"], cwd=folder, capture_output=True, text=True) except OSError: return None return os.path.realpath(r.stdout.strip()) if r.returncode == 0 and r.stdout.strip() else None def _up_from(start): """`start` and, inside a git repository, the folders above it up to the repository's top. Outside one, only `start`: a parent folder there may be anything, and a write must never land in someone else's plan.""" d = os.path.abspath(start) top = _git_top(d) while True: yield d if not top or os.path.realpath(d) == top: return up = os.path.dirname(d) if up == d: return d = up def _shown(path): """A path as people read it: relative to here when it's below here.""" rel = os.path.relpath(path) return path if rel.startswith("..") else rel def resolve_plan(ref, base="."): """The plan a name or path means, as the MCP tools' board argument and `unblock use` read it: a file, a folder (its plan by the rule, without looking above it), or a plan's name (garden: garden.unblock.json, plans/garden.unblock.json, or a plan of that name below here). None when there's no such plan.""" raw = os.path.expanduser(str(ref).strip()) p = raw if os.path.isabs(raw) else os.path.join(os.path.abspath(base), raw) if os.path.isfile(p): return os.path.normpath(p) if os.path.isdir(p): c = choose_plan(p, walk=False) return c["file"] if c["file"] and os.path.isfile(c["file"]) else None if not re.match(r"^[\w.-]+$", raw): return None for cand in (p + PLAN_SUFFIX, os.path.join(os.path.abspath(base), "plans", raw + PLAN_SUFFIX)): if os.path.isfile(cand): return os.path.normpath(cand) named = [q for q in plans_below(os.path.abspath(base)) if plan_name(q) == raw] return os.path.normpath(named[0]) if len(named) == 1 else None def choose_plan(start=".", explicit=None, walk=True): """{"file", "why", "problem", "settings"}: the plan to use from `start`, by the rule above. "file" is None when the rule can't decide (several plans, no choice), and "problem" says what to do; a "file" that doesn't exist yet is where `init` would make one.""" if explicit: return {"file": explicit, "why": "named", "problem": None, "settings": None} if os.environ.get("UNBLOCK_FILE"): return {"file": os.environ["UNBLOCK_FILE"], "why": "UNBLOCK_FILE", "problem": None, "settings": None} for d in (_up_from(start) if walk else [os.path.abspath(start)]): board = read_settings(d).get("board") if board: f = os.path.normpath(board if os.path.isabs(board) else os.path.join(d, board)) problem = None if os.path.isfile(f) else "This folder uses %s (unblock use), and it isn't there. Pick another with `unblock use `, or `unblock use --clear`." % _shown(f) return {"file": _shown(f), "why": "chosen with unblock use", "problem": problem, "settings": d} here = plans_here(d) named = [p for p in here if not p.endswith(PLAN_SUFFIX)] if named: return {"file": _shown(named[0]), "why": "found", "problem": None, "settings": None} if len(here) == 1: return {"file": _shown(here[0]), "why": "the only plan here", "problem": None, "settings": None} if len(here) > 1: return {"file": None, "why": "several", "settings": None, "problem": "%s keeps %d plans (%s). Pick one: `unblock use ` remembers it for this folder, or pass -f ." % (_shown(d) if d != os.path.abspath(".") else "This folder", len(here), ", ".join(plan_name(p) for p in here))} return {"file": _shown(os.path.join(os.path.abspath(start), BOARD_PATHS[0])), "why": "none yet", "problem": None, "settings": None} def is_board_file(path): """Whether `path` is an Unblock board (a .json file that loads as one): only boards are ever opened by name.""" if not path.endswith(".json") or not os.path.isfile(path) or os.path.getsize(path) > 20 * 1024 * 1024: return False try: load(path) return True except (BoardError, OSError, ValueError): return False def find_board(): """The plan to use here (see choose_plan), or where `init` would make one.""" return choose_plan()["file"] or BOARD_PATHS[0] def ignore_local_state(folder): """Keep .unblock/ out of version control without touching shared files: git's own exclude list (never committed), and a word about Perforce, whose ignore file is the team's. Returns what it did, for the message.""" try: r = subprocess.run(["git", "rev-parse", "--git-dir"], cwd=folder, capture_output=True, text=True) except OSError: r = None if r is not None and r.returncode == 0: if subprocess.run(["git", "check-ignore", "-q", os.path.join(UNBLOCK_DIR, "settings.json")], cwd=folder).returncode != 0: ex = os.path.join(os.path.abspath(os.path.join(folder, r.stdout.strip())), "info", "exclude") os.makedirs(os.path.dirname(ex), exist_ok=True) with open(ex, "a", encoding="utf-8") as f: f.write("\n# unblock's per-folder state (which plan you're on)\n/%s/\n" % UNBLOCK_DIR) return "kept out of git (.git/info/exclude)" return None if os.environ.get("P4CONFIG") or os.environ.get("P4CLIENT") or os.environ.get("P4IGNORE"): return "in a Perforce workspace, add %s/ to your P4IGNORE file so it isn't submitted" % UNBLOCK_DIR return None def _plan_line(path, current=None): try: r = build_report(load(path))["summary"] stats = "%3d%% · %d ready%s" % (r["progressPct"], r["ready"], " · %d doing" % r["doing"] if r["doing"] else "") title = load(path)["title"] except (BoardError, OSError, ValueError): stats, title = "not a valid board", "" mark = "▸" if current and os.path.realpath(path) == os.path.realpath(current) else " " return "%s %-16s %-26s %s" % (mark, plan_name(path), stats, _shown(path) + (" (%s)" % title if title else "")) def plan_info(path, current=None): try: b = load(path) r = build_report(b)["summary"] info = {"title": b["title"], "progressPct": r["progressPct"], "ready": r["ready"], "doing": r["doing"], "tasks": r["tasks"]} except (BoardError, OSError, ValueError) as e: info = {"error": str(e)[:200]} return dict({"file": os.path.abspath(path), "name": plan_name(path), "current": bool(current) and os.path.realpath(path) == os.path.realpath(current)}, **info) def cmd_where(args): """`unblock where`: which plan unblock uses here and why; --json for tools (the plugin and the viewer ask this).""" if args.target: f = resolve_plan(args.target) c = {"file": f, "why": "named", "problem": None if f else "No plan at %s." % args.target, "settings": None} else: c = choose_plan(".", os.environ.get("UNBLOCK_FILE")) f = c["file"] exists = bool(f) and os.path.isfile(f) folder = plan_folder(f) if exists else os.path.abspath(".") siblings = plans_here(folder) + [p for p in plans_here(os.path.join(folder, "plans")) if os.path.isdir(os.path.join(folder, "plans"))] out = {"board": os.path.abspath(f) if f else None, "exists": exists, "why": c["why"], "problem": c["problem"], "claims": _claims_file(f) if exists else None, "point": _point_file(f) if exists else None, "key": _board_key(f) if exists else None, "plans": [plan_info(p, f) for p in siblings]} if args.json: print(json.dumps(out, indent=2)) return 0 if not f: raise BoardError(c["problem"]) print("%s (%s)%s" % (_shown(f), c["why"], "" if exists else ": not created yet; `unblock init` makes it")) if c["problem"]: print(c["problem"]) if len(siblings) > 1: print("Plans here: " + ", ".join(plan_name(p) for p in siblings)) return 0 def cmd_list(args): """`unblock list`: the plans in this folder and below, with progress; the one in use is marked.""" found = plans_below(os.path.abspath("."), args.depth) c = choose_plan(".", os.environ.get("UNBLOCK_FILE")) if args.json: print(json.dumps([plan_info(p, c["file"]) for p in found], indent=2)) return 0 if not found: print("No plans here. Start one: `unblock new ` (or `unblock init` for the repository's .github/unblock.json).") return 0 for p in found: print(_plan_line(p, c["file"])) if c["problem"]: print(c["problem"]) elif len(found) > 1: print("Switch with `unblock use `.") return 0 def cmd_use(args): """`unblock use `: remember which plan this folder works on (in .unblock/settings.json, never committed).""" folder = next((d for d in _up_from(".") if os.path.isfile(_settings_file(d))), os.path.abspath(".")) if args.clear: try: os.remove(_settings_file(folder)) print("forgot the plan for %s; unblock finds it by the usual names again" % _shown(folder)) except OSError: print("no plan was chosen here") return 0 if not args.plan: raise BoardError("Which plan? `unblock list` shows them; `unblock use ` picks one.") f = resolve_plan(args.plan) if not f: raise BoardError("No plan called %s here. `unblock list` shows the plans; `unblock new %s` starts one." % (args.plan, args.plan if re.match(r"^[\w.-]+$", args.plan) else "")) if not is_board_file(f): raise BoardError("%s isn't an Unblock board." % _shown(f)) data = read_settings(folder) data["board"] = os.path.relpath(f, folder).replace(os.sep, "/") os.makedirs(os.path.join(folder, UNBLOCK_DIR), exist_ok=True) write_file(_settings_file(folder), json.dumps(data, indent=2) + "\n") note = ignore_local_state(folder) print("using %s (%s) here%s" % (plan_name(f), _shown(f), "; .unblock/ " + note if note else "")) return 0 def cmd_new(args): """`unblock new `: start another plan in this folder, .unblock.json, and use it.""" if not re.match(r"^[\w][\w.-]*$", args.name) or args.name.endswith(".json"): raise BoardError("A plan's name is letters, digits, dots, dashes and underscores (garden, q3-launch), not %s." % args.name) path = os.path.join(args.dir or ".", args.name + PLAN_SUFFIX) if os.path.exists(path): raise BoardError("%s already exists. `unblock use %s` switches to it." % (_shown(path), args.name)) if args.dir: os.makedirs(args.dir, exist_ok=True) board, _ = normalize({"format": "unblock/v1", "title": args.title or args.name.replace("-", " ").replace("_", " ").capitalize(), "tasks": []}) save(path, board) print("created %s" % _shown(path)) if not args.no_use: a = argparse.Namespace(plan=path, clear=False) cmd_use(a) return 0 def path_hint(): """What to do when there's no `unblock` command here: AGENTS.md, the hooks, the status line and the side pane all run it by name, and fail quietly without it. None when there is one.""" if shutil.which("unblock"): return None me = os.path.realpath(os.path.abspath(sys.argv[0] or __file__)) if os.path.basename(me) != "unblock" or os.sep + "uv" + os.sep in me: # unblock.py from a clone, or uvx's throwaway copy how = "Install it as a command: mkdir -p ~/.local/bin && curl -fsSL https://unblock.esh.sh/unblock.py -o ~/.local/bin/unblock && chmod +x ~/.local/bin/unblock" where = os.path.expanduser("~/.local/bin") else: how, where = "", os.path.dirname(me) rc = {"zsh": "~/.zshrc", "bash": "~/.bashrc"}.get(os.path.basename(os.environ.get("SHELL", ""))) home = os.path.expanduser("~") shown = "$HOME" + where[len(home):] if where.startswith(home + os.sep) else where lines = ["note: there's no `unblock` command on your PATH, so agents, the hooks, the status line and the side pane can't run it."] if how: lines.append(how) lines.append(("Put it on your PATH: echo 'export PATH=\"%s:$PATH\"' >> %s" % (shown, rc)) if rc else "Add %s to your PATH" % where) lines[-1] += ", then open a new terminal." return "\n".join(lines) def cmd_init(args): """Create a board for this repository. Doesn't need an existing board.""" path = args.file if args.file_given else BOARD_PATHS[0] existing = next((p for p in ([path] + list(BOARD_PATHS)) if os.path.exists(p)), None) if args.git: setup_git_merge(existing or path) if args.agents: setup_agents(existing or path) hp, added = setup_claude_hooks(".") print(("added Claude Code hooks to %s (%s): the board shows what each session is doing" % (hp, ", ".join(added))) if added else "%s already has the Unblock hooks" % hp) lp, made = setup_launch_pane(".") print(("added the live board to %s: in Claude Code's desktop app, open it in the browser pane beside the chat (it's the \"unblock\" entry)" % lp) if made else "%s already has the board's pane" % lp) sp, how = setup_status_line(".") print({"added": "added the Unblock status line to %s: progress, ready, needs you, and this session's task (shown by Claude Code in the terminal)" % sp, "ours": "%s already shows the Unblock status line" % sp, "theirs": "%s already has a status line, so it was left alone. To use Unblock's: \"statusLine\": {\"type\": \"command\", \"command\": \"unblock statusline\"}" % sp}[how]) hint = path_hint() if hint: print(hint) if (args.git or args.agents) and existing and not args.ci: return if args.ci and not _git_top("."): print("note: --ci adds a GitHub workflow (a comment on each pull request, tasks done when it merges): it does something once this folder is a git repository on GitHub. Everything else works without git.", file=sys.stderr) if args.ci: wf = os.path.join(".github", "workflows", "unblock.yml") pin = ci_pin() runs = ("It runs unblock %s, checked against its sha256." % pin[0]) if pin else \ "It downloads the latest unblock on each run: no release to pin was found (run `unblock init --ci` again later to pin one)." if os.path.exists(wf) and not args.force: with open(wf, encoding="utf-8") as f: text = f.read() if "Written by `unblock init --ci`" not in text or not GET_STEP.search(text): raise BoardError("%s already exists. Pass --force to replace it." % wf) if not pin: print("%s is left as it is: no release to pin was found" % wf) else: # ours: move it to the release, and keep any other edits new = GET_STEP.sub(lambda m: get_step(pin), text) if new != text: write_file(wf, new) print(("%s now runs unblock %s, checked against its sha256" if new != text else "%s already runs unblock %s") % (wf, pin[0])) else: os.makedirs(os.path.dirname(wf), exist_ok=True) write_file(wf, GET_STEP.sub(lambda m: get_step(pin), CI_WORKFLOW)) print("created %s: every pull request gets a comment with what it changes in the plan. %s" % (wf, runs)) if os.path.exists(path) or any(os.path.exists(p) for p in BOARD_PATHS): return if os.path.exists(path) and not args.force: raise BoardError("%s already exists. Pass --force to replace it." % path) name = os.path.basename(os.path.abspath(".")) tasks = [] source = None if getattr(args, "draft", False): raw = draft_board(".", args.title or "%s roadmap" % name) tasks, source = raw["tasks"], raw["source"] elif args.example: tasks = [ {"id": "setup", "title": "Set up the project", "status": "done", "dependsOn": []}, {"id": "first-feature", "title": "Build the first feature", "status": "doing", "dependsOn": ["setup"]}, {"id": "docs", "title": "Write the README", "status": "todo", "dependsOn": ["setup"]}, {"id": "ship", "title": "Ship it", "status": "todo", "dependsOn": ["first-feature", "docs"]}, ] board, _ = normalize({"$schema": SCHEMA_URL, "format": FORMAT, "title": args.title or "%s roadmap" % name, "tasks": tasks, **({"view": raw["view"]} if source else {})}) d = os.path.dirname(path) if d: os.makedirs(d, exist_ok=True) save(path, board) print("created %s" % path) if source: groups = {t.get("parent") for t in tasks} - {None} n = len([t for t in tasks if t["id"] not in groups]) print("drafted %d task%s%s from %s. Nothing is linked yet: link what waits on what (unblock link a b), group, and mark what's done" % ( n, "" if n == 1 else "s", " and %d group%s" % (len(groups), "" if len(groups) == 1 else "s") if groups else "", source) if tasks else "found nothing to draft from (no checklists, TODO comments or other tool's plan): the board is empty") print("next: add tasks (unblock add \"Title\" --depends-on id,id), check with unblock validate, and see it with unblock view") def file_mtime(path): """When the file last changed, as ISO 8601 UTC (boards no longer store their own time).""" try: return datetime.datetime.fromtimestamp(os.path.getmtime(path), datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.000Z") except OSError: return None def cache_dir(): return os.path.join(os.environ.get("XDG_CACHE_HOME") or os.path.expanduser("~/.cache"), "unblock") def app_html(marker="unblock-boot"): # a page that reads its settings as JSON (its CSP blocks the old inline script) """The web app: index.html next to this script, else a copy downloaded from unblock.esh.sh (cached for a day).""" here = os.path.join(os.path.dirname(os.path.abspath(__file__)), "index.html") if os.path.isfile(here): with open(here, encoding="utf-8") as f: html = f.read() if marker in html: return html cdir = cache_dir() cache = os.path.join(cdir, "index.html") fresh = os.path.isfile(cache) and time.time() - os.path.getmtime(cache) < 86400 if fresh: with open(cache, encoding="utf-8") as f: fresh = marker in f.read() if not fresh: try: req = urllib.request.Request(APP_PAGE, headers={"User-Agent": "unblock-cli/1 (+https://unblock.esh.sh)"}) # the default Python agent is blocked by the CDN with urllib.request.urlopen(req, timeout=20) as r: html = r.read().decode("utf-8") if marker not in html: raise BoardError("the app at %s is too old for this version of unblock" % APP_PAGE) os.makedirs(cdir, exist_ok=True) with open(cache, "w", encoding="utf-8") as f: f.write(html) except Exception as e: if not os.path.isfile(cache): raise BoardError("Couldn't download the app from %s (%s). Put index.html next to unblock.py to work offline." % (APP_PAGE, e)) with open(cache, encoding="utf-8") as f: return f.read() def viewer_file(path): """Where a running `unblock view` leaves its port and token, so `unblock point` can find it.""" return os.path.join(cache_dir(), "viewers", hashlib.sha1(os.path.abspath(path).encode("utf-8")).hexdigest()[:16] + ".json") def find_viewer(path): """The running viewer for this board file, or None.""" try: with open(viewer_file(path), encoding="utf-8") as f: v = json.load(f) req = urllib.request.Request("http://127.0.0.1:%d/api/whoami" % v["port"], headers={"X-Unblock-Token": v["token"]}) with urllib.request.urlopen(req, timeout=1.5) as r: me = json.loads(r.read().decode("utf-8")) if os.path.abspath(path) in [me.get("path")] + (me.get("plans") or []): # this board, or one it can switch to return v except Exception: pass return None def _point_file(path): return os.path.join(os.path.dirname(_claims_file(path)), "point.json") def remember_point(path, ids, note="", frm=""): """Keep the latest point beside the claims, for what can't be sent one (the Claude Code plugin's pane reads it).""" try: f = _point_file(path) os.makedirs(os.path.dirname(f), exist_ok=True) try: with open(f, encoding="utf-8") as fh: data = json.load(fh) except (OSError, ValueError): data = {} data[_board_key(path)] = {"ids": ids, "note": note[:300], "from": frm, "at": int(time.time())} write_file(f, json.dumps(data)) except (OSError, BoardError): pass def send_point(path, ids, note="", frm=""): """Show a point in the open viewer, and keep it for the plugin's pane. Returns the viewer's URL, or None when no viewer is running for this board.""" remember_point(path, ids, note, frm) v = find_viewer(path) if not v: return None # "plan": a viewer showing another plan in the same folder switches to this one first body = json.dumps({"ids": ids, "note": note, "from": frm, "plan": os.path.abspath(path)}).encode("utf-8") req = urllib.request.Request("http://127.0.0.1:%d/api/point" % v["port"], data=body, method="POST", headers={"Content-Type": "application/json", "X-Unblock-Token": v["token"]}) try: with urllib.request.urlopen(req, timeout=2): return v["url"] except Exception: return None def point_hash(ids, note="", frm=""): q = [("point", ",".join(ids))] + ([("note", note)] if note else []) + ([("from", frm)] if frm else []) return "#" + urllib.parse.urlencode(q, quote_via=urllib.parse.quote) def github_board_url(path): """https://unblock.esh.sh/gh/owner/repo when the board is in a GitHub repo at a place the viewer looks, else None.""" d = os.path.dirname(os.path.abspath(path)) try: top = subprocess.run(["git", "-C", d, "rev-parse", "--show-toplevel"], capture_output=True, text=True, timeout=3).stdout.strip() origin = subprocess.run(["git", "-C", d, "remote", "get-url", "origin"], capture_output=True, text=True, timeout=3).stdout.strip() except Exception: return None mo = re.match(r"^(?:git@github\.com:|ssh://git@github\.com/|https://(?:[^@/]+@)?github\.com/)([\w.-]+)/([\w.-]+?)(?:\.git)?/?$", origin) if not top or not mo or os.path.relpath(os.path.realpath(path), os.path.realpath(top)).replace(os.sep, "/") not in BOARD_PATHS: return None return "%sgh/%s/%s" % (APP_URL, mo.group(1), mo.group(2)) def resolve_ids(m, ids): """Task ids (or exact titles) -> ids, with hints for anything unknown.""" out = [] for raw in ids: tid = str(raw).strip() if not tid: continue if tid not in m.by_id: hit = [t["id"] for t in m.tasks if t["title"].lower() == tid.lower()] if hit: tid = hit[0] need(m, tid) if tid not in out: out.append(tid) if not out: raise BoardError("Say which tasks to point at.") return out def cmd_point(board, args): m = Model(board) ids = resolve_ids(m, [x for part in args.ids for x in part.split(",")]) url = send_point(args.file, ids, args.note or "", args.frm) names = ", ".join("%s (%s)" % (i, m.by_id[i]["title"]) for i in ids) if url: print("Pointing at %s in the open viewer: %s" % (names, url)) else: print("No `unblock view` is running for %s; the Unblock pane in Claude Code shows it, if you use the plugin." % os.path.relpath(args.file)) print("Or start a viewer that opens on these tasks: unblock view --point %s%s" % (",".join(ids), (" --note %s" % json.dumps(args.note)) if args.note else "")) gh = github_board_url(args.file) if gh: print("Link for the pushed board: %s%s" % (gh, point_hash(ids, args.note or ""))) def cmd_view(board, args): """Serve the app on 127.0.0.1 against the board file: browser edits are saved to it, disk changes show up live.""" path = os.path.abspath(args.file) rel = os.path.relpath(path) token = secrets.token_urlsafe(24) lock = threading.Lock() point = {"seq": 0} root = os.path.abspath(".") cfg = {"api": "/api/board", "token": token, "path": rel, "root": root, "name": os.path.basename(root), "repo": repo_of(path)} jroot = getattr(args, "jira_root", None) if jroot: # the board is Jira's: the page is read-only, and saves and agent starts are refused here too (an older page doesn't know) cfg["readOnly"] = "Jira" if args.diff: # compare mode: the live file against a git ref ("main", or "main..." for where this branch split off) ref, label = args.diff, args.diff if ref.endswith("..."): ref = git(["merge-base", ref[:-3] or "HEAD", "HEAD"], cwd=os.path.dirname(path)).strip() base = board_at(ref, path) cfg["compare"] = {"base": export_board(base or empty_board(board["title"])), "label": label} cur = {"path": path, "rel": rel} html = app_html() plans_root = plan_folder(path) # the plan's own folder (the repository's, for .github/unblock.json), even with -f def folder_plans(): """The plans this viewer can switch between: the ones in its plan's folder, and below.""" return [p for p in plans_below(plans_root) if is_board_file(p)] def page(): # per request: the page boots on the plan shown now, with the folder's other plans for its picker c = dict(cfg, path=cur["rel"], plans=[dict(plan_info(p, cur["path"]), file=os.path.relpath(p)) for p in folder_plans()]) return html.replace("", '\n' % json.dumps({"local": c}).replace(" 5: live["agents"], live["agents_at"] = claude_agents(root), now if now - live["reviews_at"] > 60 and not live["busy"]: live["busy"] = True threading.Thread(target=refresh_reviews, daemon=True).start() try: agents = agents_by_task(live["agents"], claims, load(cur["path"])) except BoardError: agents = {} agents.update(codex_agents(claims)) for k, v in activity(cur["path"]).items(): # `unblock say`: what each agent is up to, as the page's "last said" a = agents.setdefault(k, {"agent": v["agent"].lower(), "state": "working" if v["age"] <= ACTIVITY_FRESH else "quiet"}) a["said"] = "%s (%s)" % (v["text"], _ago(v["at"])) if any(v.get("started") == "copilot" for v in claims.values()): # GitHub's API: at most every 30 seconds if now - live.get("copilot_at", 0) > 30: live["copilot"], live["copilot_at"] = copilot_agents(claims, github_token()), now agents.update({k: v for k, v in live.get("copilot", {}).items() if k in claims}) return {"claims": claims, "agents": agents, "reviews": live["reviews"], "now": now} class Handler(http.server.BaseHTTPRequestHandler): server_version = "unblock" def log_message(self, *a): pass def host_ok(self): # refuse other hostnames (DNS rebinding) host = (self.headers.get("Host") or "").rsplit(":", 1)[0] return host in ("127.0.0.1", "localhost", "[::1]") def send(self, code, body=b"", ctype="application/json; charset=utf-8", headers=None): self.send_response(code) self.send_header("Content-Type", ctype) self.send_header("Cache-Control", "no-store") self.send_header("X-Frame-Options", "DENY") # no other site may frame the board and click Start or Save self.send_header("Content-Security-Policy", "frame-ancestors 'none'") self.send_header("Content-Length", str(len(body))) for k, v in (headers or {}).items(): self.send_header(k, v) self.end_headers() if body: self.wfile.write(body) def do_GET(self): if not self.host_ok(): return self.send(403, b"forbidden", "text/plain") route = self.path.split("?")[0] if route in ("/", "/index.html"): return self.send(200, page(), "text/html; charset=utf-8") if route == "/api/plans": return self.send(200, json.dumps({"path": cur["rel"], "plans": [dict(plan_info(p, cur["path"]), file=os.path.relpath(p)) for p in folder_plans()]}).encode()) if route == "/api/board": try: with open(cur["path"], "rb") as f: data = f.read() except OSError: return self.send(404, json.dumps({"errors": ["%s is missing" % cur["rel"]]}).encode()) tag = etag_of(data) mod = {"ETag": tag, "X-Unblock-Modified": file_mtime(cur["path"]), "X-Unblock-Path": urllib.parse.quote(cur["rel"])} if self.headers.get("If-None-Match") == tag: return self.send(304, headers=mod) return self.send(200, data, headers=mod) if route == "/api/claims": return self.send(200, json.dumps(live_state()).encode()) if route == "/api/start-plan": try: plan = start_plan(load(cur["path"]), cur["path"], max(1, min(int((re.search(r"[?&]max=(\d+)", self.path) or [0, 3])[1]), 10))) except BoardError as e: return self.send(400, json.dumps({"errors": [str(e)]}).encode()) plan.update(can={"claude": bool(claude_exe()), "codex": bool(codex_exe()), "copilot": bool(repo_of(cur["path"]) and github_token())}, reviews=len(live["reviews"])) return self.send(200, json.dumps(plan).encode()) if route == "/api/history": try: return self.send(200, json.dumps({"versions": board_versions(cur["path"])}).encode()) except Exception as e: # not a git repository, or git missing return self.send(200, json.dumps({"versions": [], "error": str(e)[:200]}).encode()) if route == "/api/point": p = dict(point, age=round(time.time() - point.get("at", 0))) if point["seq"] else {"seq": 0} p.pop("at", None) p["path"] = cur["rel"] # the page reloads when the viewer moved to another plan return self.send(200, json.dumps(p).encode()) if route == "/api/whoami": if self.headers.get("X-Unblock-Token") != token: return self.send(403, b"forbidden", "text/plain") return self.send(200, json.dumps({"path": os.path.abspath(cur["path"]), "plans": [os.path.abspath(p) for p in folder_plans()]}).encode()) if route == "/favicon.ico": return self.send(204) return self.send(404, b"not found", "text/plain") def do_POST(self): if not self.host_ok() or self.headers.get("X-Unblock-Token") != token: return self.send(403, b"forbidden", "text/plain") route = self.path.split("?")[0] if route not in ("/api/point", "/api/start", "/api/stop", "/api/use"): return self.send(404, b"not found", "text/plain") if jroot and route != "/api/point": return self.send(403, b'{"errors":["This board is read from Jira: start work there."]}') try: body = json.loads(self.rfile.read(min(int(self.headers.get("Content-Length") or 0), 65536)).decode("utf-8")) ids = [str(x) for x in body.get("ids") or []][:50] except (ValueError, AttributeError): return self.send(400, b'{"errors":["bad request"]}') if route == "/api/use" or (route == "/api/point" and body.get("plan")): # the picker, or a point at another plan here want = os.path.realpath(os.path.abspath(str(body.get("file") or body.get("plan") or ""))) hit = next((p for p in folder_plans() if os.path.realpath(p) == want), None) # only this folder's plans if not hit: if route == "/api/use": return self.send(400, json.dumps({"errors": ["That isn't one of the plans here."]}).encode()) elif os.path.realpath(cur["path"]) != want: with lock: switch(hit, remember=route == "/api/use") if route == "/api/use": return self.send(200, json.dumps({"path": cur["rel"]}).encode()) if route == "/api/start": # the play button: the page confirmed these tasks; the cap still holds here cap = max(1, min(int(body.get("max") or 3), 10)) if not ids or len(ids) > cap: return self.send(400, json.dumps({"errors": ["Pick between 1 and %d tasks." % cap]}).encode()) with lock: try: res = start_agents(load(cur["path"]), cur["path"], ids, str(body.get("agent") or "claude")) except BoardError as e: return self.send(400, json.dumps({"errors": [str(e)]}).encode()) live["agents_at"] = 0 return self.send(200, json.dumps({"results": res}).encode()) if route == "/api/stop": with lock: res = stop_agents(cur["path"], ids or None) live["agents_at"] = 0 return self.send(200, json.dumps({"results": res}).encode()) with lock: point.update(seq=point["seq"] + 1, ids=ids, note=str(body.get("note") or "")[:600], at=time.time()) point["from"] = str(body.get("from") or "")[:40] return self.send(200, json.dumps({"seq": point["seq"]}).encode()) def do_PUT(self): if not self.host_ok() or self.headers.get("X-Unblock-Token") != token: return self.send(403, b"forbidden", "text/plain") if self.path.split("?")[0] != "/api/board": return self.send(404, b"not found", "text/plain") if jroot: return self.send(403, b'{"errors":["This board is read from Jira: change it there."]}') size = int(self.headers.get("Content-Length") or 0) if size > 20 * 1024 * 1024: return self.send(413, b"too large", "text/plain") body = self.rfile.read(size) meant = self.headers.get("X-Unblock-Path") if meant and urllib.parse.unquote(meant) != cur["rel"]: # the page was on another plan: never save it into this one return self.send(409, json.dumps({"moved": cur["rel"]}).encode()) with lock: try: with open(cur["path"], "rb") as f: current = f.read() except OSError: current = b"" if self.headers.get("If-Match") != etag_of(current): # someone else changed the file since the page read it return self.send(409, json.dumps({"etag": etag_of(current), "text": current.decode("utf-8", "replace")}).encode()) try: new_board, _ = normalize(json.loads(body.decode("utf-8"))) except (ValueError, BoardError) as e: return self.send(400, json.dumps({"errors": str(e).split("\n")}).encode()) text = pretty(export_board(new_board)) + "\n" write_file(cur["path"], text) print(" %s saved %s" % (time.strftime("%H:%M:%S"), cur["rel"])) return self.send(200, json.dumps({"etag": etag_of(text.encode("utf-8")), "text": text}).encode()) server = None for port in range(args.port, args.port + 20): try: server = http.server.ThreadingHTTPServer(("127.0.0.1", port), Handler) break except OSError: if getattr(args, "exact_port", False): # the side pane points at this port: never move to another one raise BoardError("Port %d is in use. Is unblock view already running for this board?" % args.port) continue if not server: raise BoardError("No free port between %d and %d." % (args.port, args.port + 19)) url = "http://127.0.0.1:%d/" % server.server_address[1] regs = [] def register(): """Tell `unblock point` where this viewer is, under every plan it can show: a point at a sibling plan switches it.""" for r in regs: try: os.remove(r) except OSError: pass regs[:] = [] for p in {os.path.abspath(cur["path"])} | {os.path.abspath(x) for x in folder_plans()}: r = viewer_file(p) try: os.makedirs(os.path.dirname(r), exist_ok=True) fd = os.open(r, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600) # holds the token: only this user may read it with os.fdopen(fd, "w") as f: json.dump({"port": server.server_address[1], "token": token, "url": url, "path": os.path.abspath(cur["path"]), "pid": os.getpid()}, f) regs.append(r) except OSError: pass def switch(to, remember): cur["path"], cur["rel"] = to, os.path.relpath(to) point.update(seq=point["seq"] + 1, ids=[], note="", at=time.time()) if remember: # like `unblock use`: the folder works on this plan from now on try: folder = next((d for d in _up_from(plans_root) if os.path.isfile(_settings_file(d))), plans_root) data = read_settings(folder) data["board"] = os.path.relpath(to, folder).replace(os.sep, "/") os.makedirs(os.path.join(folder, UNBLOCK_DIR), exist_ok=True) write_file(_settings_file(folder), json.dumps(data, indent=2) + "\n") ignore_local_state(folder) except (OSError, BoardError): pass register() print(" %s now showing %s" % (time.strftime("%H:%M:%S"), cur["rel"])) register() print("Showing %s at %s" % (cur["rel"], url)) if jroot: def keep_fresh(): # the page reloads the file when it changes while True: time.sleep(JIRA_FRESH) try: jira_refresh(jroot, quiet=True) except Exception: # ponytail: offline or a revoked token shows as a board that stops changing; `unblock jira check` says why pass threading.Thread(target=keep_fresh, daemon=True).start() print("Read from Jira and refreshed every %d seconds; change tickets in Jira." % JIRA_FRESH) else: print("Edits in the browser are saved to the file, and changes to the file show up in the browser within a second.") print("Press Ctrl+C to stop.") sys.stdout.flush() try: signal.signal(signal.SIGTERM, lambda *a: sys.exit(0)) # `kill` also cleans up (open_viewer runs it in the background) except (ValueError, AttributeError): pass if not args.no_open: ids = resolve_ids(Model(board), args.point.split(",")) if args.point else [] webbrowser.open(url + (point_hash(ids, args.note or "") if ids else "")) try: server.serve_forever() except KeyboardInterrupt: print("\nStopped.") finally: server.server_close() for r in regs: try: os.remove(r) except OSError: pass # ---------------------------------------------------------------- diff: what a change does to the plan def git(args, cwd=None, binary=False): r = subprocess.run(["git"] + list(args), cwd=cwd, capture_output=True) if r.returncode: raise BoardError(r.stderr.decode("utf-8", "replace").strip() or "git %s failed" % args[0]) return r.stdout if binary else r.stdout.decode("utf-8") def parse_board_text(text, label): try: raw = json.loads(text) except ValueError as e: raise BoardError("%s is not valid JSON: %s" % (label, e)) try: board, _ = normalize(raw) except BoardError as e: raise BoardError("%s has problems:\n%s" % (label, e)) return board def board_at(ref, path): """The board file as it is at a git ref, or None if the file doesn't exist there.""" d = os.path.dirname(os.path.abspath(path)) while not os.path.isdir(d): d = os.path.dirname(d) top = git(["rev-parse", "--show-toplevel"], cwd=d).strip() rel = os.path.relpath(os.path.realpath(path), os.path.realpath(top)).replace(os.sep, "/") # realpath: /tmp and /var are symlinks on macOS if subprocess.run(["git", "rev-parse", "--verify", "--quiet", ref + "^{commit}"], cwd=top, capture_output=True).returncode: raise BoardError('Unknown git ref "%s".' % ref) r = subprocess.run(["git", "show", "%s:%s" % (ref, rel)], cwd=top, capture_output=True) if r.returncode: return None return parse_board_text(r.stdout.decode("utf-8"), "%s at %s" % (rel, ref)) def empty_board(title="Unblock board"): return normalize({"format": FORMAT, "title": title, "tasks": []})[0] def board_side(spec, path): """(board or None, label) for a diff side: a git ref, a .json file, or None for the file on disk.""" if spec is None: if not os.path.isfile(path): return None, "working copy" with open(path, encoding="utf-8") as f: return parse_board_text(f.read(), os.path.relpath(path)), "working copy" if spec.lower().endswith(".json") and os.path.isfile(spec): with open(spec, encoding="utf-8") as f: return parse_board_text(f.read(), spec), spec return board_at(spec, path), spec def board_diff(a, b, base_label="base", head_label="head"): """Everything that differs between two boards, and what it does to the plan: which tasks get done, become ready or blocked, how % unblocked and progress move, and the critical path.""" ma, mb = Model(a), Model(b) ia, ib = ma.by_id, mb.by_id info = lambda m, tid: {"id": tid, "title": m.by_id[tid]["title"], "kind": "group" if m.is_group(tid) else "task", "state": m.metrics(tid)["state"], "parent": m.by_id[tid].get("parent")} added = [info(mb, t["id"]) for t in b["tasks"] if t["id"] not in ia] removed = [info(ma, t["id"]) for t in a["tasks"] if t["id"] not in ib] changed = [] for t in b["tasks"]: o = ia.get(t["id"]) if not o: continue tid, ch = t["id"], {} leaf = not ma.is_group(tid) and not mb.is_group(tid) for k in ("title", "parent", "estimate", "assignee") + (("status",) if leaf else ()): if o.get(k) != t.get(k): ch[k] = [o.get(k), t.get(k)] if sorted(o.get("tags") or []) != sorted(t.get("tags") or []): ch["tags"] = [o.get("tags") or [], t.get("tags") or []] plus = [d for d in t["dependsOn"] if d not in o["dependsOn"]] minus = [d for d in o["dependsOn"] if d not in t["dependsOn"]] if plus or minus: ch["dependsOn"] = {"added": plus, "removed": minus} if (o.get("notes") or "") != (t.get("notes") or ""): ca, cb = checklist(o.get("notes")), checklist(t.get("notes")) ch["notes"] = {"checklist": [ca, cb]} if (ca or cb) and ca != cb else True if ch: changed.append(dict(info(mb, tid), changes=ch)) both = [l for l in mb.leaf_ids if l in ia and not ma.is_group(l)] st = lambda m, l: m.metrics(l)["state"] completed = [info(mb, l) for l in both if st(mb, l) == "done" and st(ma, l) != "done"] reopened = [info(mb, l) for l in both if st(ma, l) == "done" and st(mb, l) != "done"] now_ready = [dict(info(mb, l), was=st(ma, l), wasUnblockedPct=ma.metrics(l)["unblocked"]) for l in both if st(mb, l) == "ready" and st(ma, l) == "blocked"] now_blocked = [dict(info(mb, l), was=st(ma, l), unblockedPct=mb.metrics(l)["unblocked"]) for l in both if st(mb, l) == "blocked" and st(ma, l) in ("ready", "doing")] moved = sorted([{"id": l, "title": ib[l]["title"], "from": ma.metrics(l)["unblocked"], "to": mb.metrics(l)["unblocked"]} for l in both if st(mb, l) != "done" and ma.metrics(l)["unblocked"] != mb.metrics(l)["unblocked"]], key=lambda x: (-(x["to"] - x["from"]), x["id"])) groups = [{"id": g, "title": ib[g]["title"], "from": ma.metrics(g)["progress"], "to": mb.metrics(g)["progress"]} for g in ib if g in ia and mb.is_group(g) and ma.is_group(g) and ma.metrics(g)["progress"] != mb.metrics(g)["progress"]] ra, rb = build_report(a)["summary"], build_report(b)["summary"] side = lambda board, r, m, label: {"label": label, "title": board["title"], "progressPct": r["progressPct"], "done": r["done"], "tasks": r["tasks"], "ready": r["ready"], "blocked": r["blocked"], "pointsDone": r["pointsDone"], "pointsTotal": r["pointsTotal"], "criticalPath": {"points": m.crit_pts, "tasks": m.crit}} d = {"format": "unblock-diff/v1", "base": side(a, ra, ma, base_label), "head": side(b, rb, mb, head_label), "added": added, "removed": removed, "changed": changed, "effects": {"completed": completed, "reopened": reopened, "nowReady": now_ready, "nowBlocked": now_blocked, "unblockedPct": moved, "groupProgress": groups}} d["hasChanges"] = bool(added or removed or changed or a["title"] != b["title"]) d["warnings"] = plan_warnings(b, only={x["id"] for x in completed} | {x["id"] for x in added}, added=[x["id"] for x in added]) return d def diff_focus(d, limit=None): """The ids that matter most in a diff, most important first.""" e, out = d["effects"], [] for group in (e["completed"], e["nowReady"], e["nowBlocked"], e["reopened"], d["added"], d["changed"], d["removed"], e["unblockedPct"]): for x in group: if x["id"] not in out: out.append(x["id"]) return out[:limit] if limit else out def _q(v): return '"%s"' % v if isinstance(v, str) else "none" if v is None else fmt_num(v) if isinstance(v, (int, float)) else str(v) def md_text(v): """Board text in Markdown, shown as written: a title can't add links, images, HTML, headings or @mentions to a pull request comment (a pull request can change the board, so its text is the author's).""" v = re.sub(r"\s+", " ", str(v)) return re.sub(r"([\\`*_\[\]()<>#!|~])", r"\\\1", v).replace("@", "@\u2060") def fence_for(v): return "`" * max(3, max([len(x) for x in re.findall(r"`+", str(v))] or [0]) + 1) def md_code(v): """Inline code that a backtick in the text can't close early.""" v = re.sub(r"\s+", " ", str(v)) fence = "`" * (max([len(x) for x in re.findall(r"`+", v)] or [0]) + 1) return fence + (" %s " % v if v.startswith("`") or v.endswith("`") else v) + fence def change_phrases(c, code=lambda x: x, text=lambda x: x): """Readable phrases for one changed task.""" ch, out = c["changes"], [] if "status" in ch: out.append("status %s → %s" % tuple(x or "todo" for x in ch["status"])) if "title" in ch: out.append("renamed from %s" % text(_q(ch["title"][0]))) if "dependsOn" in ch: if ch["dependsOn"]["added"]: out.append("now waits on " + ", ".join(code(x) for x in ch["dependsOn"]["added"])) if ch["dependsOn"]["removed"]: out.append("no longer waits on " + ", ".join(code(x) for x in ch["dependsOn"]["removed"])) if "parent" in ch: out.append("moved to " + (code(ch["parent"][1]) if ch["parent"][1] else "the top level")) if "estimate" in ch: out.append("estimate %s → %s" % tuple(fmt_num(x) if x is not None else "1" for x in ch["estimate"])) if "assignee" in ch: out.append(("assigned to %s" % text("@" + ch["assignee"][1])) if ch["assignee"][1] else "unassigned") if "tags" in ch: out.append("tags: " + (text(", ".join(ch["tags"][1])) or "none")) if "notes" in ch: ck = ch["notes"]["checklist"] if isinstance(ch["notes"], dict) else None out.append("checklist %s → %s" % tuple(("%d/%d" % (x["done"], x["total"])) if x else "none" for x in ck) if ck else "description edited") return out def diff_text(d): b, h, e = d["base"], d["head"], d["effects"] lines = ["%s: %s → %s" % (h["title"], b["label"], h["label"])] if not d["hasChanges"]: return lines[0] + "\n\nNo changes to the board." lines.append(" %d%% → %d%% done (%d → %d of %d tasks done)" % (b["progressPct"], h["progressPct"], b["done"], h["done"], h["tasks"])) if b["title"] != h["title"]: lines.append(" board renamed from %s" % _q(b["title"])) def section(title, items, fmt): if items: lines.append("\n%s (%d)" % (title, len(items))) lines.extend(" " + fmt(x) for x in items) row = lambda mark, x, extra="": "%s %-24s %s%s" % (mark, x["id"], x["title"], (" (" + extra + ")") if extra else "") section("Completed", e["completed"], lambda x: row("[x]", x)) section("Now ready", e["nowReady"], lambda x: row("[ ]", x, "was blocked, %d%% unblocked" % x["wasUnblockedPct"])) section("Now blocked", e["nowBlocked"], lambda x: row("[.]", x, "was %s, now %d%% unblocked" % (x["was"], x["unblockedPct"]))) section("Reopened", e["reopened"], lambda x: row("[~]", x, x["state"])) section("Worth a look", d.get("warnings") or [], lambda x: "! " + x["text"]) section("Added", d["added"], lambda x: row("+", x, ", ".join(filter(None, [x["kind"] if x["kind"] == "group" else x["state"], ("in " + x["parent"]) if x["parent"] else ""])))) section("Removed", d["removed"], lambda x: row("-", x)) section("Changed", d["changed"], lambda x: row("~", x, "; ".join(change_phrases(x)))) section("% unblocked", e["unblockedPct"][:12], lambda x: "%-28s %d%% → %d%%" % (x["id"], x["from"], x["to"])) if len(e["unblockedPct"]) > 12: lines.append(" ... and %d more" % (len(e["unblockedPct"]) - 12)) ca, cb = b["criticalPath"], h["criticalPath"] if ca["tasks"] != cb["tasks"]: lines.append("\nCritical path: %s pt in %d steps → %s pt in %d steps" % (fmt_num(ca["points"]), len(ca["tasks"]), fmt_num(cb["points"]), len(cb["tasks"]))) return "\n".join(lines) # colors from the app, readable on GitHub's light and dark themes MERMAID_CLASSES = { "done": "fill:#DAF1E7,stroke:#0F8A62,color:#0A6A4B", "ready": "fill:#FDE8DE,stroke:#E84E12,color:#B03A0A", "doing": "fill:#E1E9FD,stroke:#2563EB,color:#1C4DBD", "blocked": "fill:#E7EBEF,stroke:#96A0AD,color:#586473", "removed": "fill:#FBE4E2,stroke:#C4362B,color:#C4362B,stroke-dasharray:4 3", "context": "fill:transparent,stroke:#96A0AD,color:#7F8B9A,stroke-dasharray:2 2", } def diff_mermaid(d, a, b, limit=24, context=10): """A Mermaid flowchart of the tasks a change touches, plus their direct neighbours for context.""" ma, mb = Model(a), Model(b) focus = diff_focus(d, limit) if not focus: return "" status = {} e = d["effects"] for x in e["completed"]: status[x["id"]] = "done ✓" for x in e["nowReady"]: status.setdefault(x["id"], "blocked → ready") for x in e["nowBlocked"]: status.setdefault(x["id"], "%s → blocked" % x["was"]) for x in e["reopened"]: status.setdefault(x["id"], "done → %s" % x["state"]) for x in d["added"]: status.setdefault(x["id"], "new · " + (x["kind"] if x["kind"] == "group" else x["state"])) for x in d["removed"]: status.setdefault(x["id"], "removed") for x in e["unblockedPct"]: status.setdefault(x["id"], "%d%% → %d%% unblocked" % (x["from"], x["to"])) nodes, max_nodes = list(focus), len(focus) + context edges_b = {(dep, t["id"]) for t in b["tasks"] for dep in t["dependsOn"]} edges_a = {(dep, t["id"]) for t in a["tasks"] for dep in t["dependsOn"]} edges = [] for (x, y) in sorted(edges_b | edges_a): if x not in nodes and y not in nodes: continue for n in (x, y): if n not in nodes and len(nodes) < max_nodes: nodes.append(n) if x in nodes and y in nodes: edges.append((x, y, "added" if (x, y) not in edges_a else "removed" if (x, y) not in edges_b else "same")) key = {n: "n%d" % i for i, n in enumerate(nodes)} esc = lambda t: t.replace('"', "#quot;").replace("<", "#lt;").replace(">", "#gt;").replace("`", "'") out = ["flowchart LR"] for n in nodes: m = mb if n in mb.by_id else ma title = m.by_id[n]["title"] title = title if len(title) <= 42 else title[:41].rstrip() + "…" st = m.metrics(n)["state"] sub = status.get(n) or (("group · %d%%" % m.metrics(n)["progress"]) if m.is_group(n) else st) label = "%s
%s" % (esc(title), esc(sub)) o, c = ("[[", "]]") if m.is_group(n) else ("(", ")") out.append(' %s%s"%s"%s' % (key[n], o, label, c)) styles = [] for i, (x, y, kind) in enumerate(edges): out.append(" %s %s %s" % (key[x], "==>" if kind == "added" else "-.->" if kind == "removed" else "-->", key[y])) if kind == "added": styles.append(" linkStyle %d stroke:#0F8A62,stroke-width:2.5px" % i) elif kind == "removed": styles.append(" linkStyle %d stroke:#C4362B" % i) out += styles for k, v in MERMAID_CLASSES.items(): out.append(" classDef %s %s" % (k, v)) for n in nodes: cls = "removed" if n not in mb.by_id else "context" if n not in focus else mb.metrics(n)["state"] out.append(" class %s %s" % (key[n], cls)) if n in {x["id"] for x in d["added"]}: out.append(" style %s stroke-width:3px" % key[n]) return "\n".join(out) DIFF_MARKER = "" # ---------------------------------------------------------------- the plan in the README: a badge and a Mermaid graph def board_mermaid(board, limit=40): """A Mermaid flowchart of the whole plan. Big plans show their groups folded, deeper first, to stay near `limit` boxes; a link between tasks inside folded groups is drawn between the groups.""" m = Model(board) depth = {t["id"]: len(m.ancestors(t["id"])) for t in m.tasks} cut = max(depth.values() or [0]) while cut > 0 and sum(1 for d in depth.values() if d <= cut) > limit: cut -= 1 shown = [t["id"] for t in m.tasks if depth[t["id"]] <= cut] rep_of = lambda i: next((a for a in reversed(m.ancestors(i)) if depth[a] == cut), None) if depth[i] > cut else i folded = {i for i in shown if m.is_group(i) and depth[i] == cut and cut < max(depth.values())} key = {n: "n%d" % i for i, n in enumerate(shown)} esc = lambda t: t.replace('"', "#quot;").replace("<", "#lt;").replace(">", "#gt;").replace("`", "'") out = ["flowchart LR"] def node(n, pad): t = m.by_id[n] title = t["title"] if len(t["title"]) <= 42 else t["title"][:41].rstrip() + "…" x = m.metrics(n) sub = ("%d%% done" % x["progress"]) if m.is_group(n) else x["state"] o, c = ("[[", "]]") if m.is_group(n) else ("(", ")") out.append('%s%s%s"%s
%s"%s' % (pad, key[n], o, esc(title), esc(sub), c)) def place(parent, pad): for n in shown: if m.by_id[n].get("parent") != parent: continue if m.is_group(n) and n not in folded: out.append('%ssubgraph %s ["%s"]' % (pad, key[n] + "g", esc(m.by_id[n]["title"]))) place(n, pad + " ") out.append(pad + "end") else: node(n, pad) place(None, " ") seen = [] for t in m.tasks: for d in t["dependsOn"]: x, y = rep_of(d), rep_of(t["id"]) if x and y and x != y and (x, y) not in seen and x in key and y in key: seen.append((x, y)) def reach(x, y, skip): # is y reachable from x without the edge `skip`? todo, got = [x], {x} while todo: u = todo.pop() for e in seen: if e != skip and e[0] == u and e[1] not in got: if e[1] == y: return True got.add(e[1]) todo.append(e[1]) return False for e in list(seen): # a link another path already implies adds nothing to the picture if reach(e[0], e[1], e): seen.remove(e) boxed = lambda n: key[n] + ("g" if m.is_group(n) and n not in folded else "") out += [" %s --> %s" % (boxed(x), boxed(y)) for x, y in seen] for k, v in MERMAID_CLASSES.items(): if k in ("done", "ready", "doing", "blocked"): out.append(" classDef %s %s" % (k, v)) for n in shown: if not (m.is_group(n) and n not in folded): out.append(" class %s %s" % (key[n], m.metrics(n)["state"])) return "\n".join(out) def badge_svg(board): """A README badge in the usual two-part style: "plan | 54% · 3 ready".""" r = build_report(board)["summary"] right = "%d%% done" % r["progressPct"] + (" · %d ready" % r["ready"] if r["ready"] else "") + (" · %d doing" % r["doing"] if r["doing"] else "") w = lambda t: int(len(t) * 6.3 + 12) # Verdana 11px, near enough for these characters lw, rw = w("plan"), w(right) color = "#0F8A62" if r["progressPct"] == 100 else "#E84E12" if r["ready"] else "#2563EB" if r["doing"] else "#586473" return ('plan: {r}' '' '' '' '' 'planplan' '{r}{r}\n' ).format(t=lw + rw, lw=lw, rw=rw, col=color, lx=lw / 2, rx=lw + rw / 2, r=right) README_START, README_END = "", "" # The markers count only on lines of their own: a README that mentions them in a sentence keeps that sentence. README_BLOCK = re.compile(r"(?ms)^%s[ \t]*$.*?^%s[ \t]*$" % (re.escape(README_START), re.escape(README_END))) BADGE_PATH = ".github/unblock-badge.svg" def readme_block(board, path, badge_rel): url = github_board_url(path) r = build_report(board)["summary"] img = "![Plan: %d%% done](%s)" % (r["progressPct"], badge_rel) lines = [README_START, "", "[%s](%s)" % (img, url) if url else img, "", "%d of %d tasks done, %d ready to start%s." % (r["done"], r["tasks"], r["ready"], ", %d in progress" % r["doing"] if r["doing"] else ""), "", "```mermaid", board_mermaid(board), "```", ""] if url: lines += ["Kept up to date by [Unblock](https://unblock.esh.sh). [Open the live board](%s)." % url, ""] return "\n".join(lines + [README_END]) def update_readme(board, path, readme, add=False): """Refresh the plan block in the README (between the markers), and the badge next to the board. Returns the files that changed; with add, puts the block at the end of a README that has none.""" if not os.path.isfile(readme) and not add: raise BoardError("There's no %s." % readme) text = "" if os.path.isfile(readme): with open(readme, encoding="utf-8") as f: text = f.read() badge = os.path.join(os.path.dirname(os.path.abspath(path)), os.path.basename(BADGE_PATH)) rel = os.path.relpath(badge, os.path.dirname(os.path.abspath(readme))).replace(os.sep, "/") block = readme_block(board, path, rel) m = README_BLOCK.search(text) if m: new = text[:m.start()] + block + text[m.end():] elif add: new = (text.rstrip("\n") + "\n\n" if text.strip() else "# %s\n\n" % board["title"]) + "## Plan\n\n" + block + "\n" else: return None changed = [] if new != text: write_file(readme, new) changed.append(readme) svg = badge_svg(board) old = open(badge, encoding="utf-8").read() if os.path.isfile(badge) else None if old != svg: write_file(badge, svg) changed.append(badge) return changed def cmd_readme(board, args): changed = update_readme(board, args.file, args.readme, add=args.add) if changed is None: raise BoardError("%s has no plan block. Run `unblock readme --add` to add one, or put %s and %s, each on a line of its own, where it should go." % (args.readme, README_START, README_END)) print("updated %s" % ", ".join(os.path.relpath(c) for c in changed) if changed else "%s is up to date" % args.readme) if args.check and changed: return 1 def cmd_mermaid(board, args): print(board_mermaid(board, args.limit)) def diff_markdown(d, a, b, link=None, footer="", image=None): h, bs, e = d["head"], d["base"], d["effects"] code, t = md_code, md_text out = [DIFF_MARKER, "### Unblock: what this changes in the plan"] if not d["hasChanges"]: out.append("No changes to **%s**." % t(h["title"])) if footer: out.append("\n%s" % footer) return "\n".join(out) counts = [("completes", len(e["completed"])), ("unblocks", len(e["nowReady"])), ("blocks", len(e["nowBlocked"])), ("reopens", len(e["reopened"])), ("adds", len(d["added"])), ("removes", len(d["removed"])), ("changes", len(d["changed"]))] arrow = "%d%% → %d%% done" % (bs["progressPct"], h["progressPct"]) if bs["progressPct"] != h["progressPct"] else "%d%% done" % h["progressPct"] out.append("**%s** · %s · %s" % (t(h["title"]), arrow, " · ".join("%s **%d**" % (w, n) for w, n in counts if n))) if d.get("doneOnMerge"): out.append("\nMerging marks %s done, from `done:` lines in this pull request." % ", ".join(code(i) for i in d["doneOnMerge"])) if image: # the picture from unblock.esh.sh, in the reader's theme; it links to a page with the same picture alt = "%s: %s" % (h["title"], ", ".join("%s %d" % (w, n) for w, n in counts if n)) out += ["", '%s' % (image["page"], image["svgDark"], alt.replace('"', "'"), image["svg"])] else: graph = diff_mermaid(d, a, b) if graph: out += ["", "```mermaid", graph, "```"] def lst(title, items, fmt): if items: out.append("\n**%s**" % title) out.extend("- " + fmt(x) for x in items[:15]) if len(items) > 15: out.append("- …and %d more" % (len(items) - 15)) lst("Completed", e["completed"], lambda x: "%s %s" % (t(x["title"]), code(x["id"]))) lst("Now ready to start", e["nowReady"], lambda x: "%s %s (was %d%% unblocked)" % (t(x["title"]), code(x["id"]), x["wasUnblockedPct"])) lst("Now blocked", e["nowBlocked"], lambda x: "%s %s (was %s, now %d%% unblocked)" % (t(x["title"]), code(x["id"]), x["was"], x["unblockedPct"])) lst("Reopened", e["reopened"], lambda x: "%s %s" % (t(x["title"]), code(x["id"]))) lst("Worth a look", d.get("warnings") or [], lambda x: "".join(code(part) if part in x["ids"] else t(part) for part in re.split(r"\b(%s)\b" % "|".join(re.escape(i) for i in x["ids"]), x["text"]) if part) if x["ids"] else t(x["text"])) details = [] for x in d["added"]: details.append("- ➕ %s %s: %s%s" % (t(x["title"]), code(x["id"]), x["kind"] if x["kind"] == "group" else x["state"], (" in " + code(x["parent"])) if x["parent"] else "")) for x in d["removed"]: details.append("- ➖ ~~%s~~ %s" % (t(x["title"]), code(x["id"]))) for x in d["changed"]: details.append("- ✏️ %s %s: %s" % (t(x["title"]), code(x["id"]), "; ".join(change_phrases(x, code, t)))) for x in e["unblockedPct"][:20]: details.append("- %s %s: %d%% → %d%% unblocked" % (t(x["title"]), code(x["id"]), x["from"], x["to"])) ca, cb = bs["criticalPath"], h["criticalPath"] if ca["tasks"] != cb["tasks"]: details.append("- Critical path: %s pt in %d steps → %s pt in %d steps" % (fmt_num(ca["points"]), len(ca["tasks"]), fmt_num(cb["points"]), len(cb["tasks"]))) if details: out += ["", "
Every change (%d)" % len(details), ""] + details + ["", "
"] if link: out.append("\n[Open the board with these tasks highlighted](%s)" % link) if footer: out.append("\n%s" % footer) return "\n".join(out) # ---------------------------------------------------------------- agent setup: the AGENTS.md lines and `unblock prime` AGENT_START, AGENT_END = "", "" def agent_block(rel): return """%s ## The plan: %s This project's plan is an Unblock board: tasks, what each waits on, and their status. Keep it current as you work; the user reads it as a graph and doesn't update it themselves. - At the start of a session, run `unblock prime`: progress, what's in flight, and what to pick up next. - Before starting a task, `unblock claim ` (other agents skip it). When it's finished and verified, `unblock set done --note "what you decided"`, or put `done: ` in the commit. - Found more work? `unblock add "Title" --depends-on ` rather than doing it silently. Blocked? Add the missing task and link it. - To show the user what you mean: `unblock point --note "..."`. - Ask before deleting tasks you didn't create. Everything else: https://unblock.esh.sh/skill.md %s """ % (AGENT_START, rel, AGENT_END) def write_agent_block(path, block): """Put the block into a file, replacing an earlier one; returns what happened.""" text = "" if os.path.exists(path): with open(path, encoding="utf-8") as f: text = f.read() if AGENT_START in text and AGENT_END in text: new = text[:text.index(AGENT_START)] + block.strip() + text[text.index(AGENT_END) + len(AGENT_END):] verb = "updated" if new != text else "already up to date:" else: new = (text.rstrip() + "\n\n" if text.strip() else "") + block.strip() + "\n" verb = "added the Unblock lines to" if text else "created" if new != text: write_file(path, new) return verb def setup_agents(path): rel = os.path.relpath(os.path.abspath(path)).replace(os.sep, "/") print("%s AGENTS.md" % write_agent_block("AGENTS.md", agent_block(rel))) if os.path.exists("CLAUDE.md"): print("%s CLAUDE.md" % write_agent_block("CLAUDE.md", agent_block(rel))) else: # Claude Code reads CLAUDE.md, and follows @-imports write_file("CLAUDE.md", "@AGENTS.md\n") print("created CLAUDE.md (it imports AGENTS.md)") for line in ignore_for_team("."): print(line) def ignore_for_team(folder): """`init --agents`: .unblock/ (each person's choice of plan, Jira settings) into the project's ignore files, so nobody commits or submits it: .gitignore in a git repository, the P4IGNORE file in a Perforce workspace.""" out = [] files = [] if _git_top(folder): files.append(".gitignore") if os.environ.get("P4IGNORE"): files.append(os.environ["P4IGNORE"].split(os.pathsep)[0]) for name in files: f = os.path.join(folder, name) try: with open(f, encoding="utf-8") as fh: text = fh.read() except OSError: text = "" if re.search(r"(?m)^/?\.unblock/?\s*$", text): continue write_file(f, text + ("" if not text or text.endswith("\n") else "\n") + "# each person's Unblock state: which plan they're on (unblock use)\n.unblock/\n") out.append("added .unblock/ to %s" % name) if not files and (os.environ.get("P4CONFIG") or os.environ.get("P4CLIENT")): out.append("note: in a Perforce workspace, add .unblock/ to your P4IGNORE file so it isn't submitted") return out def cmd_now(board, args): """One answer to "what should I do now?".""" m = Model(board) held = active_claims(args.file) me = default_holder(args.file) mine = [k for k, v in held.items() if v["by"] == me and k in m.by_id and m.by_id[k].get("status") != "done"] if mine: t = m.by_id[mine[0]] print("Keep going with %s (%s): you claimed it." % (t["title"], mine[0])) return nxt = [it for it in build_report(board)["next"] if it["id"] not in held] if not nxt: doing = [l for l in m.topo if m.state[l] == "doing"] print(("Nothing new is ready. Finish what's in progress first: %s" % ", ".join(doing)) if doing else ("Everything is done." if m.leaf_ids else "The board is empty.")) return it = nxt[0] t = m.by_id[it["id"]] why = "everything it waits on is done" + (", and it unblocks %d task%s" % (it["unblocksOpen"], "" if it["unblocksOpen"] == 1 else "s") if it["unblocksOpen"] else "") print("Do this now: %s (%s)\n Why: %s." % (t["title"], it["id"], why)) if (t.get("notes") or "").strip(): print("\n" + "\n".join(" " + x for x in t["notes"].strip().splitlines()[:12])) print("\nStart with: unblock claim %s" % it["id"]) def cmd_prime(board, args): """What an agent needs at the start of a session, in a few lines.""" m = Model(board) rep_ = build_report(board) r = rep_["summary"] rel = os.path.relpath(args.file).replace(os.sep, "/") held = active_claims(args.file) me = default_holder(args.file) print("Unblock plan: %s (%s): %d%% done, %d ready, %d doing, %d blocked" % (board["title"], rel, r["progressPct"], r["ready"], r["doing"], r["blocked"])) if os.path.isfile(args.file): others = [p for p in plans_here(plan_folder(args.file)) if os.path.realpath(p) != os.path.realpath(args.file) and (p.endswith(PLAN_SUFFIX) or p.replace(os.sep, "/").endswith(".github/unblock.json"))] # plans kept on purpose if others: print("Other plans here: %s (switch with `unblock use `, or pass -f )" % ", ".join(plan_name(p) for p in others)) doing = [l for l in m.topo if m.state[l] == "doing"] if doing: print("\nIn progress") since = doing_since(args.file, doing) if os.path.isfile(args.file) else {} for l in doing: c = held.get(l) days = int((time.time() - since[l]) / 86400) if l in since else 0 bits = ["claimed by %s until %s" % ("you" if c["by"] == me else c["by"], _until(c["until"]))] if c else [] if days >= 3: # stale: say so, so it gets finished or put back bits.append("in progress for %d days" % days + ("" if c else "; nobody holds it: pick it up, or put it back with `unblock set %s todo`" % l)) print(" " + line(m, l, "; ".join(bits))) nxt = [it for it in rep_["next"] if it["id"] not in held or held[it["id"]]["by"] == me][: args.limit] if nxt: print("\nPick up next (most unblocking first%s)" % (", others' claims skipped" if any(v["by"] != me for v in held.values()) else "")) for it in nxt: print(" " + line(m, it["id"], "unblocks %d" % it["unblocksOpen"] if it["unblocksOpen"] else "")) mine = [k for k, v in held.items() if v["by"] == me and k in m.by_id] for k in mine: notes = (m.by_id[k].get("notes") or "").strip() if notes: print("\nYour claimed task %s: %s\n%s" % (k, m.by_id[k]["title"], "\n".join(" " + x for x in notes.splitlines()[:12]))) ws = plan_warnings(board) if ws: print("\nWorth a look") for w in ws[:5]: print(" - " + w["text"]) print("\nThe loop: `unblock claim `, do the work, then `unblock set done --note \'what you decided\'` (or `done: ` in the commit)." " New work: `unblock add`. Show the user: `unblock point --note`.") # ---------------------------------------------------------------- plan warnings: mistakes worth a look, never a gate def doing_since(path, ids, depth=60): """For tasks that are doing now: when they became doing, from the board file's git history (None if unknown).""" try: d = os.path.dirname(os.path.abspath(path)) top = git(["rev-parse", "--show-toplevel"], cwd=d).strip() if git(["rev-parse", "--is-shallow-repository"], cwd=top).strip() == "true": return {} rel = os.path.relpath(os.path.realpath(path), os.path.realpath(top)).replace(os.sep, "/") log = git(["log", "-n", str(depth), "--format=%H %ct", "--", rel], cwd=top).split("\n") except BoardError: return {} since, still = {}, set(ids) for entry in log: if not entry.strip() or not still: break sha, ts = entry.split() try: b = board_at(sha, path) except BoardError: break st = {t["id"]: t.get("status") for t in (b or {}).get("tasks", [])} for tid in list(still): if st.get(tid) == "doing": since[tid] = int(ts) # doing at this commit: it has been doing at least since here else: still.discard(tid) # not doing yet at this commit: the one after it is where it started return since def plan_warnings(board, only=None, added=None, path=None, stale_days=7): """What's worth a look in a board. `only` limits the done-while-blocked check to these ids, and `added` names the tasks new in a change (the description check applies to those). Returns [{"kind", "ids", "text"}].""" m = Model(board) out = [] early = [] for l in m.leaf_ids: if m.by_id[l].get("status") == "done" and (only is None or l in only): open_up = [u for u in m.pre[l] if m.state[u] != "done"] if open_up: early.append((l, open_up)) for l, ups in early: out.append({"kind": "doneWhileBlocked", "ids": [l] + ups, "text": "%s is done, but it waits on %s, which %s" % (l, ", ".join(ups[:3]) + (" and %d more" % (len(ups) - 3) if len(ups) > 3 else ""), "isn't" if len(ups) == 1 else "aren't")}) if path: doing = [l for l in m.leaf_ids if m.by_id[l].get("status") == "doing"] for tid, ts in sorted(doing_since(path, doing).items()): days = (time.time() - ts) / 86400 if days >= stale_days: out.append({"kind": "stuckDoing", "ids": [tid], "text": "%s has been doing for %d days" % (tid, days)}) bare = [x for x in (added or []) if x in m.by_id and not m.is_group(x) and m.by_id[x].get("status") != "done" and not (m.by_id[x].get("notes") or "").strip()] if bare: out.append({"kind": "noDescription", "ids": bare, "text": "%s %s no description, so an agent starting %s has only the title to go on" % (", ".join(bare[:5]) + (" and %d more" % (len(bare) - 5) if len(bare) > 5 else ""), "has" if len(bare) == 1 else "have", "it" if len(bare) == 1 else "them")}) return out def cmd_lint(board, args): ws = plan_warnings(board, path=os.path.abspath(args.file), stale_days=args.days) m = Model(board) bare = [l for l in m.leaf_ids if m.by_id[l].get("status") != "done" and not (m.by_id[l].get("notes") or "").strip()] if args.json: print(pretty(ws)) elif not ws: print("Nothing to flag." + (" (%d open tasks have no description)" % len(bare) if bare else "")) else: for w in ws: print("- " + w["text"]) if bare: print("(%d open tasks have no description)" % len(bare)) return 1 if ws and args.strict else 0 # ---------------------------------------------------------------- snapshot images: a diff drawn as an SVG in the app's style # `diff_snapshot` keeps only what the picture needs (the affected tasks, their neighbours, titles and states), and # `snapshot_svg` draws it. The server at unblock.esh.sh stores snapshots and renders them with the same code, so it never # has to accept SVG from anyone. SNAP_FORMAT = "unblock-snapshot/v1" SNAP_TAGS = ("completed", "nowReady", "nowBlocked", "reopened", "added", "removed", "started", "changed", "moved", "focus", "needsYou", "pointed", "context") SNAP_STATES = ("ready", "doing", "blocked", "done") SNAP_COUNTS = ("completed", "nowReady", "nowBlocked", "reopened", "added", "removed", "changed") def diff_snapshot(d, a, b, limit=16, context=8, source=None): ma, mb = Model(a), Model(b) e = d["effects"] tag = {} for key, items in (("completed", e["completed"]), ("nowReady", e["nowReady"]), ("nowBlocked", e["nowBlocked"]), ("reopened", e["reopened"]), ("added", d["added"]), ("removed", d["removed"]), ("changed", d["changed"]), ("moved", e["unblockedPct"])): for x in items: tag.setdefault(x["id"], key) for c in d["changed"]: if tag.get(c["id"]) == "changed" and (c["changes"].get("status") or [None, None])[1] == "doing": tag[c["id"]] = "started" edits = {c["id"]: change_phrases(c)[:3] for c in d["changed"]} focus = diff_focus(d, limit) nodes, cap = list(focus), len(focus) + context edges_b = {(dep, t["id"]) for t in b["tasks"] for dep in t["dependsOn"]} edges_a = {(dep, t["id"]) for t in a["tasks"] for dep in t["dependsOn"]} pairs = [] for (x, y) in sorted(edges_b | edges_a): if x not in nodes and y not in nodes: continue for n in (x, y): if n not in nodes and len(nodes) < cap: nodes.append(n) if x in nodes and y in nodes: pairs.append((x, y, "added" if (x, y) not in edges_a else "removed" if (x, y) not in edges_b else "same")) out = [] for n in nodes: m = mb if n in mb.by_id else ma x = m.metrics(n) t = m.by_id[n] o = {"id": n[:80], "title": t["title"][:160], "kind": "group" if m.is_group(n) else "task", "state": x["state"], "tag": tag.get(n, "context") if n in focus else "context"} if n in ma.by_id and n in mb.by_id and ma.metrics(n)["state"] != x["state"]: o["was"] = ma.metrics(n)["state"] if m.is_group(n): o["progress"] = x["progress"] else: o["estimate"] = m.weight(n) if x["state"] != "done": o["pct"] = x["unblocked"] if n in ma.by_id and n in mb.by_id and not ma.is_group(n) and ma.metrics(n)["unblocked"] != x["unblocked"]: o["wasPct"] = ma.metrics(n)["unblocked"] if t.get("parent") and t["parent"] in m.by_id: o["group"] = m.by_id[t["parent"]]["title"][:60] if n in edits: o["edits"] = [s[:90] for s in edits[n]] out.append(o) idx = {n: i for i, n in enumerate(nodes)} counts = {"completed": len(e["completed"]), "nowReady": len(e["nowReady"]), "nowBlocked": len(e["nowBlocked"]), "reopened": len(e["reopened"]), "added": len(d["added"]), "removed": len(d["removed"]), "changed": len(d["changed"])} side = lambda s: {"label": s["label"][:80], "progressPct": s["progressPct"], "done": s["done"], "tasks": s["tasks"]} return {"format": SNAP_FORMAT, "title": d["head"]["title"][:120], "base": side(d["base"]), "head": side(d["head"]), "counts": counts, "hidden": max(0, len(diff_focus(d)) - len(focus)), "nodes": out, "edges": [{"from": idx[x], "to": idx[y], "kind": k} for x, y, k in pairs], "source": source or {}} def landed(board, m): """(ids, label): done tasks tagged with one of the board's "landed" statuses (In Review, waiting for CI), and what to call them. ([], None) on boards without any. A task past done (a stage) isn't landed any more.""" names = board.get("_extra", {}).get("landed") or [] tags, v = {x.lower() for x in names}, {l for _, ids in stages(board, m) for l in ids} ids = [l for l in m.leaf_ids if tags and m.state[l] == "done" and l not in v and tags & {x.lower() for x in m.by_id[l].get("tags") or []}] return ids, " / ".join(x.lower() for x in names) or None def stages(board, m): """[(name, ids)], shallowest first: the board's own stages beyond done (named by whoever set it up: 'verified', 'shipped', ...), each with the done tasks whose furthest stage it is.""" return [(n, [l for l in m.leaf_ids if m.state[l] == "done" and m.by_id[l].get("stage") == n]) for n in board.get("_extra", {}).get("stages") or []] def progress_line(board, m, sm): """(["63% done"], landed %, [[stage, %], ...]), or "12% verified + 29% done + 22% in review" when part of the done work reached a stage beyond done or has only landed.""" ids, label = landed(board, m) share = lambda xs: pct(sum(m.weight(l) for l in xs), sm["pointsTotal"], len(xs), sm["tasks"]) if xs else 0 lp, sp = share(ids), [[n, share(xs)] for n, xs in stages(board, m)] if not (lp or any(p for _, p in sp)): return ["%d%% done" % sm["progressPct"]], 0, [] parts = ["%d%% %s" % (p, n) for n, p in reversed(sp) if p] + ["%d%% done" % max(0, sm["progressPct"] - lp - sum(p for _, p in sp))] + (["%d%% %s" % (lp, label)] if lp else []) return [" + ".join(parts)], lp, sp def momentum(board, m, since): """{group: {kind: n}} and the totals under "", for tasks that got somewhere within `since` (7d, 24h, 2w): a stage (its name), landed, done or started. Each task counts once, by the furthest it got. None without a window.""" mo = re.match(r"^(\d+)\s*([hdw])$", (since or "").strip()) if not mo: if since: raise BoardError("--since takes a time like 24h, 7d or 2w.") return None cut = (datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(seconds=int(mo.group(1)) * {"h": 3600, "d": 86400, "w": 604800}[mo.group(2)])).strftime("%Y-%m-%dT%H:%M:%SZ") lids = set(landed(board, m)[0]) out = {"": {}} for l in m.leaf_ids: t = m.by_id[l] if t.get("stage") and m.state[l] == "done" and (t.get("stageSince") or "") >= cut: kind = t["stage"] elif (t.get("stateSince") or "") >= cut and m.state[l] in ("done", "doing"): kind = "landed" if l in lids else "done" if m.state[l] == "done" else "started" else: continue for g in ("", t.get("parent") or "-"): out.setdefault(g, {})[kind] = out.get(g, {}).get(kind, 0) + 1 return out def landings(board, m, since): """({group: [n per slice]}, slices): tasks that reached done (landed and later stages included) in each slice of the window, oldest first. A day per slice for windows of days or weeks (at most 14), else 8 slices. None without a window.""" mo = re.match(r"^(\d+)\s*([hdw])$", (since or "").strip()) if not mo: return None secs = int(mo.group(1)) * {"h": 3600, "d": 86400, "w": 604800}[mo.group(2)] n = min(14, secs // 86400) if mo.group(2) != "h" and secs >= 2 * 86400 else 8 now = time.time() out = {} for l in m.leaf_ids: t = _when(m.by_id[l].get("stateSince")) if m.state[l] == "done" and m.by_id[l].get("stateSince") else None if t is not None and 0 <= now - t < secs: g = m.by_id[l].get("parent") or "-" out.setdefault(g, [0] * n)[min(n - 1, int((t - (now - secs)) * n // secs))] += 1 return out, n def _svg_spark(counts, x, y, C): """Landings per slice as small bars, 14 px tall: is the group speeding up?""" top, out = max(counts) or 1, [] for i, c in enumerate(counts): h = 1.5 if not c else max(3, 14 * c / top) out.append('' % (x + i * 6, y + 14 - h, h, C["done"] if c else C["ringTrack"])) return "".join(out) def window(text, what="--since"): """Seconds in 24h, 7d or 2w.""" mo = re.match(r"^(\d+)\s*([hdw])$", (text or "").strip()) if not mo: raise BoardError("%s takes a time like 24h, 7d or 2w." % what) return int(mo.group(1)) * {"h": 3600, "d": 86400, "w": 604800}[mo.group(2)] def span(secs): return "%d min" % max(1, secs // 60) if secs < 3600 else "%.0f h" % (secs / 3600) if secs < 86400 else "%.1f d" % (secs / 86400) def lead_times(board, m, since=None): """[(leg, median s, p90 s, n, previous median s or None)] and {group: median s of the first leg}: how long tasks took from start to done (or to landed), and on to each stage, for tasks that finished the leg within `since` (all of them without it). With `since`, the median of the window before too: faster or slower.""" label = landed(board, m)[1] or "done" win, now = (window(since) if since else None), time.time() def legs(lo, hi): out = {} for l in m.leaf_ids: if m.state[l] != "done": continue t = m.by_id[l] a, b = (_when(t["startedAt"]) if t.get("startedAt") else None), (_when(t["stateSince"]) if t.get("stateSince") else None) if a and b and b >= a and (lo is None or lo <= b < hi): out.setdefault("start→" + label, []).append((b - a, t.get("parent") or "")) c = _when(t["stageSince"]) if t.get("stage") and t.get("stageSince") else None if b and c and c >= b and (lo is None or lo <= c < hi): out.setdefault("%s→%s" % (label, t["stage"]), []).append((c - b, t.get("parent") or "")) return out cur, prev = legs(now - win, now + 1) if win else legs(None, None), legs(now - 2 * win, now - win) if win else {} import statistics med = lambda xs: statistics.median(xs) if xs else None p90 = lambda xs: sorted(xs)[max(0, math.ceil(0.9 * len(xs)) - 1)] # nearest rank order = ["start→" + label] + ["%s→%s" % (label, n) for n, _ in stages(board, m)] rows = [(k, med([d for d, _ in cur[k]]), p90([d for d, _ in cur[k]]), len(cur[k]), med([d for d, _ in prev.get(k, [])])) for k in order if cur.get(k)] first = cur.get(order[0]) or [] groups = {g: med([d for d, h in first if h == g]) for g in {h for _, h in first}} return rows, groups def lead_text(rows): out = [] for k, md, p90, n, was in rows: trend = "" if was is None else ", faster than %s" % span(was) if md < was * 0.9 else ", slower than %s" % span(was) if md > was * 1.1 else ", as before" out.append("%s %s (p90 %s%s)" % (k, span(md), span(p90), trend)) return out def quiet(board, m, said=None, after=None): """{id: seconds since its last sign of life} for tasks in progress that have been quiet longer than `after`: no edit in the tracker (seen), no state change (stateSince), nothing said (`unblock say`). Tasks with none of these are left out: their board can't tell.""" if not after: return {} now, out = time.time(), {} for l in m.leaf_ids: if m.state[l] != "doing": continue t = m.by_id[l] last = max([x for x in (_when(t.get("seen")) if t.get("seen") else None, _when(t.get("stateSince")) if t.get("stateSince") else None, (said or {}).get(l, {}).get("at")) if x] or [0]) if last and now - last > after: out[l] = now - last return out def momentum_text(mo, label, g="", names=()): c = (mo or {}).get(g) or {} order = [(n, n) for n in reversed(list(names))] + [("landed", label or "landed"), ("done", "done"), ("started", "started")] return ["+%d %s" % (c[k], w) for k, w in order if c.get(k)] def now_snapshot(board, claims=None, limit=8, context=8, point=None, since=None, said=None, stale=None): """The board as it stands, as a snapshot to draw: what's waiting on you, what's in progress and the ready tasks that unblock the most (in focus), with what they unblock beside them, faded. snapshot_svg draws it.""" m, r = Model(board), build_report(board) claims = claims or {} qt = quiet(board, m, said, window(stale, "--stale") if stale else None) needs = [k for k, v in claims.items() if v.get("state") == "needs-you" and k in m.by_id and not m.is_group(k) and m.state[k] != "done"] doing = [l for l in m.leaf_ids if m.state[l] == "doing"] pointed = [i for i in ((point or {}).get("ids") or []) if i in m.by_id][:limit] open_ = [l for l in m.leaf_ids if m.state[l] != "done"] linked = {d for t in board["tasks"] for d in t.get("dependsOn", [])} | {t["id"] for t in board["tasks"] if t.get("dependsOn")} if any(m.by_id[l].get("parent") for l in open_) and 2 * sum(l not in linked for l in open_) > len(open_): return groups_snapshot(board, m, r, open_, limit, pointed, point, since, said, stale) # most tasks unlinked (a real tracker): a column of cards says nothing, epics do every = list(dict.fromkeys(pointed + needs + doing + [x["id"] for x in r["next"]])) focus = every[:max(limit, len(pointed))] nodes, cap = list(focus), len(focus) + context for t in board["tasks"]: # what they unblock: the tasks that name them if len(nodes) >= cap: break if t["id"] not in nodes and t.get("status") != "done" and any(d in focus for d in t.get("dependsOn", [])): nodes.append(t["id"]) pairs = [(d, t["id"]) for t in board["tasks"] for d in t.get("dependsOn", []) if d in nodes and t["id"] in nodes] out = [] for n in nodes: x, t = m.metrics(n), m.by_id[n] o = {"id": n[:80], "title": t["title"][:160], "kind": "group" if m.is_group(n) else "task", "state": x["state"], "tag": "pointed" if n in pointed else "needsYou" if n in needs else "focus" if n in focus else "context"} if m.is_group(n): o["progress"] = x["progress"] else: o["estimate"] = m.weight(n) if x["state"] != "done": o["pct"] = x["unblocked"] if t.get("parent") and t["parent"] in m.by_id: o["group"] = m.by_id[t["parent"]]["title"][:60] if n in (said or {}): o["activity"], o["stale"] = activity_text(said[n]), said[n]["age"] > ACTIVITY_FRESH if n in qt: o["quiet"] = span(qt[n]) out.append(o) idx = {n: i for i, n in enumerate(nodes)} sm = r["summary"] head, lp, sp = progress_line(board, m, sm) side = {"label": "", "progressPct": sm["progressPct"], "done": sm["done"], "tasks": sm["tasks"], "landedPct": lp, "stagePcts": sp} line = head + ["%d ready" % sm["ready"]] + (["%d doing" % sm["doing"]] if sm["doing"] else []) + \ (["%d waiting on you" % len(needs)] if needs else []) mo = momentum(board, m, since) if mo is not None: line.append("last %s: %s" % (since.strip(), ", ".join(momentum_text(mo, landed(board, m)[1], "", [n for n, _ in sp])) or "no change")) line += lead_text(lead_times(board, m, since)[0]) more = len(every) - len(focus) hidden = [m.state[i] for i in every[len(focus):]] # in progress and ready alike: say which parts = ["%d in progress" % hidden.count("doing")] if "doing" in hidden else [] parts += ["%d ready" % (len(hidden) - hidden.count("doing"))] if len(hidden) > hidden.count("doing") else [] snap = {"format": SNAP_FORMAT, "title": board["title"][:120], "base": side, "head": side, "counts": {}, "hidden": more, "nodes": out, "edges": [{"from": idx[a], "to": idx[b], "kind": "same"} for a, b in pairs], "source": {}, "line": " · ".join(line), "caption": "now", "more": "+%s not shown" % " and ".join(parts), "quiet": quiet_list(m, qt)} if pointed: # the agent's note, drawn as a callout on the first task it points at snap["point"] = {"note": ((point or {}).get("note") or "").strip()[:400] or "Look at these", "from": ((point or {}).get("from") or "Agent")[:40]} return snap def quiet_list(m, qt, most=10): """The quietest tasks in progress, for graph: [{id, title, for}].""" return [{"id": l, "title": m.by_id[l]["title"][:120], "for": span(qt[l])} for l in sorted(qt, key=lambda l: -qt[l])[:most]] def groups_snapshot(board, m, r, open_, limit=8, pointed=(), point=None, since=None, said=None, stale=None): """now_snapshot for a board whose tasks are mostly unlinked: one card per group (an epic) with its open tasks counted inside, busiest first, and an edge where a task in one waits on a task in another. Pointed tasks (what the agents are on) are drawn ringed beside their group, so the overview and the focus share one picture.""" by = {} home = lambda l: m.by_id[l].get("parent") or "" for l in open_: by.setdefault(home(l), []).append(l) said = {k: v for k, v in (said or {}).items() if k in m.by_id and not m.is_group(k)} qt = quiet(board, m, said, window(stale, "--stale") if stale else None) busy = [k for k, v in said.items() if v["age"] <= ACTIVITY_FRESH and k not in pointed] # the swarm at work opens its groups too pointed = [p for p in pointed if not m.is_group(p)][:24] asked = set(pointed) per = {} for k in sorted(busy, key=lambda k: said[k]["age"]): # the freshest few per group: the overview stays scannable at 40 agents per.setdefault(home(k), []).append(k) pointed = (pointed + [k for ks in per.values() for k in ks[:ACTIVE_SHOWN]])[:24] for p in pointed: by.setdefault(home(p), []) rank = lambda g: (-any(home(p) == g for p in pointed), -sum(m.state[l] == "doing" for l in by[g]), -sum(m.state[l] == "ready" for l in by[g]), -len(by[g])) shown = sorted(by, key=rank)[:max(limit, len({home(p) for p in pointed}))] nodes, loose = [], [l for l in m.leaf_ids if not m.by_id[l].get("parent")] lids, label = landed(board, m) st = stages(board, m) final = st[-1][0] if st else None waiting = list(open_) + [l for l in m.leaf_ids if final and m.state[l] == "done" and m.by_id[l].get("stage") != final] # short of the last stage, still waiting mo = momentum(board, m, since) spark = landings(board, m, since) lt = lead_times(board, m, since) for g in shown: states = [m.state[l] for l in by[g]] counts = ["%d %s" % (states.count(k), w) for k, w in (("doing", "doing"), ("ready", "ready"), ("blocked", "blocked")) if k in states] nl = sum(1 for l in lids if (m.by_id[l].get("parent") or "") == g) counts += ["%d %s" % (nl, label)] if nl else [] counts += ["%d %s" % (len([l for l in ids if home(l) == g]), n) for n, ids in reversed(st) if any(home(l) == g for l in ids)] nw = sum(1 for l in waiting if home(l) == g and m.by_id[l].get("waitsOutside")) counts += ["%d wait outside" % nw] if nw else [] nq = sum(1 for l in qt if home(l) == g) counts += ["%d stale" % nq] if nq else [] counts += ["⏱ %s" % span(lt[1][g])] if lt[1].get(g) else [] # its median start to done: where the time goes counts = momentum_text(mo, label, g or "-", [n for n, _ in st]) + counts # what moved first: percentages move slowly, these don't live = sum(1 for k, v in said.items() if v["age"] <= ACTIVITY_FRESH and home(k) == g) hidden = live - sum(1 for p in pointed if p not in asked and home(p) == g) counts = (["● %d active%s" % (live, " (%d not shown)" % hidden if hidden > 0 and g in {home(p) for p in pointed} else "")] if live else []) + counts extra = {"spark": spark[0].get(g or "-") or [0] * spark[1]} if spark else {} nodes.append(dict(extra, **{"id": (g or "-")[:80], "title": (m.by_id[g]["title"] if g else "Not in a group")[:160], "kind": "group", "tag": "focus", "state": "doing" if "doing" in states else "ready" if "ready" in states else "blocked", "group": " · ".join(counts), "progress": m.metrics(g)["progress"] if g else 100 * sum(m.state[l] == "done" for l in loose) // max(1, len(loose))})) idx = {g: i for i, g in enumerate(shown)} ins = set(open_) edges = {(idx[home(d)], idx[home(l)]) for l in open_ for d in m.by_id[l].get("dependsOn", []) if d in ins and home(d) in idx and home(l) in idx and home(d) != home(l)} member = [] for p in pointed: x = m.metrics(p) nodes.append({"id": p[:80], "title": m.by_id[p]["title"][:160], "kind": "task", "state": x["state"], "tag": "pointed" if p in asked else "focus", "estimate": m.weight(p)}) if x["state"] != "done": nodes[-1]["pct"] = x["unblocked"] if p in said: nodes[-1]["activity"], nodes[-1]["stale"] = activity_text(said[p]), said[p]["age"] > ACTIVITY_FRESH if p in qt: nodes[-1]["quiet"] = span(qt[p]) member.append((idx[home(p)], len(nodes) - 1)) sm, more = r["summary"], len(by) - len(shown) far = {} for l in waiting: for w in m.by_id[l].get("waitsOutside") or []: far.setdefault(w["key"], dict(w, blocks=[]))["blocks"].append(l if m.state[l] != "done" else "%s (to be %s)" % (l, final)) outside = sorted(far.values(), key=lambda w: -len(w["blocks"]))[:8] head, lp, sp = progress_line(board, m, sm) side = {"label": "", "progressPct": sm["progressPct"], "done": sm["done"], "tasks": sm["tasks"], "landedPct": lp, "stagePcts": sp} line = head + ["%d ready" % sm["ready"]] + (["%d doing" % sm["doing"]] if sm["doing"] else []) if mo is not None: line.append("last %s: %s" % (since.strip(), ", ".join(momentum_text(mo, label, "", [n for n, _ in st])) or "no change")) line += lead_text(lt[0]) return {"format": SNAP_FORMAT, "title": board["title"][:120], "base": side, "head": side, "counts": {}, "hidden": more, "nodes": nodes, "edges": [{"from": a, "to": b, "kind": "same"} for a, b in sorted(edges)] + [{"from": a, "to": b, "kind": "member"} for a, b in member], "source": {}, "line": " · ".join(line), "caption": "now, by group", "more": "+%d more groups not shown" % more, "wide": True, "outside": outside, "quiet": quiet_list(m, qt), **({"point": {"note": ((point or {}).get("note") or "").strip()[:400] or "Look at these", "from": ((point or {}).get("from") or "Agent")[:40]}} if asked else {})} def combine_themes(light, dark, ids=("dots", "sh")): """One SVG holding a light and a dark drawing, shown by the viewer's color scheme.""" for a in ids: dark = dark.replace('id="%s"' % a, 'id="%s-d"' % a).replace("url(#%s)" % a, "url(#%s-d)" % a) open_tag = light.split(">", 1)[0] + ">" body = lambda svg, cls: '%s' % (cls, svg.split(">", 1)[1].rsplit("", 1)[0]) style = "" return open_tag + style + body(light, "t-light") + body(dark, "t-dark") + "" # ---------------------------------------------------------------- all plans at once: a folder's plans side by side def plans_overview(folder, depth=2): """Every plan in `folder` (and below) as {name, file, title, summary, next, links}: what `next --all` and `svg --all` show. `links` are the other plans this one's tasks point at with a local ref.""" files = [p for p in plans_below(folder, depth) if is_board_file(p)] real = {os.path.realpath(p): i for i, p in enumerate(files)} out = [] for p in files: b = load(p) rep = build_report(b) held = active_claims(p) me = default_holder(p) if held else None nxt = [it for it in rep["next"] if it["id"] not in held or held[it["id"]]["by"] == me] links = set() for t in b["tasks"]: r = parse_ref(t.get("ref")) if r and r["file"]: f = r["file"] if os.path.isabs(r["file"]) else os.path.join(os.path.dirname(os.path.abspath(p)), r["file"]) if os.path.isdir(f): f = next((os.path.join(f, x) for x in BOARD_PATHS if os.path.isfile(os.path.join(f, x))), f) j = real.get(os.path.realpath(f)) if j is not None and files[j] != p: links.add(j) out.append({"name": plan_name(p), "file": p, "title": b["title"], "summary": rep["summary"], "next": nxt, "links": sorted(links)}) return out def cmd_svg_all(args): """`unblock svg --all`: the folder's plans as cards, light and dark in one SVG (or one theme).""" plans = plans_overview(os.path.abspath(".")) if not plans: raise BoardError("No plans here to draw. Start one: `unblock new `.") corner = 0 if (args.flush or args.fluid) else 14 svg = combine_themes(plans_svg(plans, "light", corner), plans_svg(plans, "dark", corner)) if args.theme == "auto" else plans_svg(plans, args.theme, corner) if args.fluid: svg = re.sub(r'^]*?) width="\d+" height="\d+"', r'`.") return 0 if not items: print("Nothing is ready in %s." % ", ".join(pl["name"] for pl in plans)) w = max(len(pl["name"]) for pl in plans) for it in items: print("%-*s [ ] %-24s %s%s" % (w, it["plan"], it["id"], it["title"], " (unblocks %d)" % it["unblocksOpen"] if it["unblocksOpen"] else "")) return 0 def plans_svg(plans, theme="light", corner=14): """A folder's plans as cards: title, progress, what's ready, the next task; an arrow where one plan's tasks point at another's.""" C = SVG_THEMES["dark" if theme == "dark" else "light"] W, H, GX, GY, M, HEAD = 300, 122, 46, 34, 24, 70 cols = max(1, min(3, len(plans))) rows = (len(plans) + cols - 1) // cols width = M * 2 + cols * W + (cols - 1) * GX height = M + HEAD + rows * H + (rows - 1) * GY + M + 18 pos = [(M + (i % cols) * (W + GX), M + HEAD + (i // cols) * (H + GY)) for i in range(len(plans))] done = sum(pl["summary"]["done"] for pl in plans) tasks = sum(pl["summary"]["tasks"] for pl in plans) P = ['' % (width, height, width, height, _xml("%d plans: %s" % (len(plans), ", ".join("%s %d%%" % (pl["name"], pl["summary"]["progressPct"]) for pl in plans))))] P.append('' % C["grid"]) P.append('' % C["shadow"]) P.append('' % (SVG_FONT, SVG_MONO)) P.append('' % (width, height, corner, C["paper"], width, height, corner)) P.append('%d plans here' % (M, M + 16, C["ink"], len(plans))) P.append('%s' % (M, M + 37, C["ink2"], _xml("%d of %d tasks done across them · %d ready" % (done, tasks, sum(pl["summary"]["ready"] for pl in plans))))) for i, pl in enumerate(plans): # links first, under the cards: neighbours side by side join edge to edge; others for j in pl["links"]: # arc over the cards between them (above a row, or between rows) (x1, y1), (x2, y2) = pos[i], pos[j] if y1 == y2 and abs(i - j) == 1: a, b = ((x1 + W, y1 + H / 2), (x2, y2 + H / 2)) if x2 > x1 else ((x1, y1 + H / 2), (x2 + W, y2 + H / 2)) d = "M%.1f,%.1fL%.1f,%.1f" % (a + b) elif y1 == y2: a, b = (x1 + W / 2, y1), (x2 + W / 2, y2) d = "M%.1f,%.1fC%.1f,%.1f %.1f,%.1f %.1f,%.1f" % (a[0], a[1], a[0], a[1] - 30, b[0], b[1] - 30, b[0], b[1]) else: a, b = (x1 + W / 2, y1 + H) if y2 > y1 else (x1 + W / 2, y1), (x2 + W / 2, y2) if y2 > y1 else (x2 + W / 2, y2 + H) k = GY / 2 if y2 > y1 else -GY / 2 d = "M%.1f,%.1fC%.1f,%.1f %.1f,%.1f %.1f,%.1f" % (a[0], a[1], a[0], a[1] + k, b[0], b[1] - k, b[0], b[1]) P.append('' % (d, C["edgeOpen"], b[0], b[1], C["edgeOpen"])) for (x, y), pl in zip(pos, plans): sm = pl["summary"] P.append('' % (x, y, W, H, C["surface"], C["line"])) P.append('%s' % (C["ink"], _xml(_clip(pl["title"], W - 90, 14, True)))) P.append('%s' % (W - 16, C["ink3"], _xml(_clip(pl["name"], 70, 11)))) bw = W - 32 P.append('' % (bw, C["ringTrack"])) if sm["progressPct"]: P.append('' % (bw * sm["progressPct"] / 100, C["done"])) stats = "%d%% done · %d ready%s%s" % (sm["progressPct"], sm["ready"], " · %d doing" % sm["doing"] if sm["doing"] else "", " · %d blocked" % sm["blocked"] if sm["blocked"] else "") P.append('%s' % (C["ink2"], _xml(stats))) nx = pl["next"][0] if pl["next"] else None label = ("Next: " + nx["title"]) if nx else ("All done" if sm["done"] == sm["tasks"] and sm["tasks"] else "Nothing ready") P.append('%s' % (C["accentDeep"] if nx else C["ink3"], _xml(_clip(label, W - 32, 12.5, True)))) if nx and nx["unblocksOpen"]: P.append('unblocks %d' % (C["ink3"], nx["unblocksOpen"])) P.append('') P.append('unblock.esh.sh' % (width - M - 92, height - 14, C["ink3"])) P.append('') return "\n".join(P) def both_themes_svg(snap, corner=14): """One SVG holding the light and the dark drawing, shown by the viewer's color scheme.""" return combine_themes(snapshot_svg(snap, "light", corner), snapshot_svg(snap, "dark", corner)) GRAPH_MARK = {"done": "✓", "doing": "◐", "ready": "○", "blocked": "◌"} def graph_text(snap, width=72): """A snapshot as text for any chat or terminal: each task in focus, and under it what it unblocks.""" nodes = snap["nodes"] kids, members = {}, {} for e in snap["edges"]: (members if e["kind"] == "member" else kids).setdefault(e["from"], []).append(e["to"]) inside = {k for v in members.values() for k in v} clip = lambda t, n: t if len(t) <= n else t[:max(1, n - 1)].rstrip() + "…" def row(n, indent): mark = "◎" if n["tag"] == "pointed" else "◆" if n["tag"] == "needsYou" else GRAPH_MARK.get(n["state"], "○") what = "waiting on you" if n["tag"] == "needsYou" else ("group · %d%%" % n.get("progress", 0) + (" · " + n["group"] if n.get("group") else "")) if n["kind"] == "group" else \ n["state"] + (" · %d%%" % n["pct"] if n["state"] == "blocked" and "pct" in n else "") head = indent + mark + " " room = max(12, width - len(head) - len(what) - 2) return head + clip(n["title"], room).ljust(room) + " " + what out = [snap["title"] + " · " + (snap.get("line") or _summary_line(snap)), ""] if snap.get("point"): out[1:1] = textwrap.wrap("◎ " + snap["point"]["note"], width, subsequent_indent=" ") shown = set() for i, n in enumerate(nodes): if n["tag"] == "context" or i in inside: continue out.append(row(n, "")) out += [" ↳ " + clip(n["activity"], width - 8)] if n.get("activity") else [] for k in members.get(i, []): # what the agents are on, in its group out.append(row(nodes[k], " ")) out += [" ↳ " + clip(nodes[k]["activity"], width - 10)] if nodes[k].get("activity") else [] under = [k for k in kids.get(i, []) if nodes[k]["tag"] == "context"] for j, k in enumerate(under): branch = "└─▶ " if j == len(under) - 1 else "├─▶ " out.append(row(nodes[k], " " + branch) if k not in shown else " " + branch + clip(nodes[k]["title"], width - 8) + " (above)") shown.add(k) if snap.get("quiet"): out += ["", "Quiet (in progress, no sign of life):"] + [" ◌ %s %s · %s" % (q["id"], clip(q["title"], width - 24 - len(q["id"])), q["for"]) for q in snap["quiet"]] if snap.get("outside"): out += ["", "Waiting outside this scope:"] + [" ⧗ %s %s · %s → blocks %s" % (w["key"], clip(w["title"], 40), ", ".join(x for x in (w.get("status"), w.get("assignee")) if x) or "open", ", ".join(w["blocks"][:4])) for w in snap["outside"]] if snap.get("hidden"): out += ["", snap.get("more") or "+%d more" % snap["hidden"]] return "\n".join(out) def _point_arg(args): ids = [x for part in (getattr(args, "point", None) or []) for x in part.split(",") if x] return {"ids": ids, "note": getattr(args, "note", None) or ""} if ids else None def cmd_graph(board, args): """`unblock graph`: the board as it stands, as text: waiting on you, in progress and ready, and what they unblock.""" claims = active_claims(args.file) if os.path.isfile(args.file) else {} print(graph_text(now_snapshot(board, claims, limit=args.limit, point=_point_arg(args), since=args.since, said=activity(args.file), stale=args.stale or None), args.width)) RESVG_HELP = ("PNG needs resvg, a small self-contained SVG renderer: https://github.com/linebender/resvg/releases " "(or brew install resvg, scoop install resvg, cargo install resvg). Or set UNBLOCK_RESVG to where it is.") def write_png(svg, out, zoom=2): """The SVG as a PNG, drawn by resvg (one small binary per platform, found on PATH or at $UNBLOCK_RESVG).""" exe = os.environ.get("UNBLOCK_RESVG") or shutil.which("resvg") if not exe: raise BoardError(RESVG_HELP) fd, tmp = tempfile.mkstemp(suffix=".svg") try: with os.fdopen(fd, "w", encoding="utf-8") as f: f.write(svg) r = subprocess.run([exe, "--zoom", str(zoom), "--sans-serif-family", "Arial", tmp, os.path.abspath(out)], capture_output=True, text=True, timeout=120) except OSError as e: raise BoardError("Couldn't run %s (%s). %s" % (exe, e, RESVG_HELP)) finally: try: os.remove(tmp) except OSError: pass if r.returncode or not os.path.isfile(out): raise BoardError("resvg couldn't draw it: %s" % (r.stderr.strip() or "exit %d" % r.returncode)) def cmd_svg(board, args): """`unblock svg`: the board as it stands, as a picture: what's in progress, what's ready, what they unblock.""" claims = active_claims(args.file) if os.path.isfile(args.file) else {} snap = now_snapshot(board, claims, limit=args.limit, point=_point_arg(args), since=args.since, said=activity(args.file), stale=args.stale or None) if args.png: # resvg ignores prefers-color-scheme: a PNG gets one theme, light unless asked write_png(snapshot_svg(snap, "dark" if args.theme == "dark" else "light", 0 if args.flush else 14), args.png, args.zoom) print("wrote %s" % args.png) return corner = 0 if args.flush or args.fluid else 14 svg = snapshot_svg(snap, args.theme, corner) if args.theme in ("light", "dark") else both_themes_svg(snap, corner) if args.fluid: # as wide as whatever shows it, the height following: drop the fixed size, keep the viewBox svg = re.sub(r'^(]*?) width="\d+" height="\d+"', r'\1 width="100%"', svg, count=1) if args.out: write_file(args.out, svg) print("wrote %s" % args.out) else: sys.stdout.write(svg + "\n") def clean_snapshot(raw): """Check a snapshot from outside and return a clean copy (raises ValueError). Everything drawn comes from here.""" if not isinstance(raw, dict) or raw.get("format") != SNAP_FORMAT: raise ValueError("not an %s document" % SNAP_FORMAT) txt = lambda v, n: str(v)[:n] if isinstance(v, (str, int, float)) and not isinstance(v, bool) else "" num = lambda v, lo, hi: max(lo, min(hi, int(v))) if isinstance(v, (int, float)) and not isinstance(v, bool) else lo nodes_in, edges_in = raw.get("nodes"), raw.get("edges") if not isinstance(nodes_in, list) or not isinstance(edges_in, list) or len(nodes_in) > 60 or len(edges_in) > 400: raise ValueError("nodes and edges must be lists (at most 60 nodes and 400 edges)") nodes = [] for o in nodes_in: if not isinstance(o, dict): raise ValueError("every node must be an object") n = {"id": txt(o.get("id"), 80), "title": txt(o.get("title"), 160) or "Untitled", "kind": "group" if o.get("kind") == "group" else "task", "state": o.get("state") if o.get("state") in SNAP_STATES else "ready", "tag": o.get("tag") if o.get("tag") in SNAP_TAGS else "context"} if o.get("was") in SNAP_STATES: n["was"] = o["was"] for k in ("pct", "wasPct", "progress"): if isinstance(o.get(k), (int, float)) and not isinstance(o.get(k), bool): n[k] = num(o[k], 0, 100) if isinstance(o.get("estimate"), (int, float)) and not isinstance(o.get("estimate"), bool): n["estimate"] = max(0, min(9999, float(o["estimate"]))) if o.get("group"): n["group"] = txt(o["group"], 60) if o.get("activity"): n["activity"], n["stale"] = txt(o["activity"], 160), bool(o.get("stale")) if o.get("quiet"): n["quiet"] = txt(o["quiet"], 20) if isinstance(o.get("spark"), list): n["spark"] = [num(c, 0, 10 ** 6) for c in o["spark"][:14]] if isinstance(o.get("edits"), list): n["edits"] = [txt(s, 90) for s in o["edits"][:3]] nodes.append(n) outside = [{"key": txt(w.get("key"), 40), "title": txt(w.get("title"), 120), "status": txt(w.get("status"), 40), "assignee": txt(w.get("assignee"), 60), "blocks": [txt(b, 80) for b in (w.get("blocks") or [])[:20]]} for w in (raw.get("outside") or [])[:8] if isinstance(w, dict)] if isinstance(raw.get("outside"), list) else [] edges = [] for ed in edges_in: if not isinstance(ed, dict): raise ValueError("every edge must be an object") f, t = ed.get("from"), ed.get("to") if not (isinstance(f, int) and isinstance(t, int) and 0 <= f < len(nodes) and 0 <= t < len(nodes) and f != t): raise ValueError("edges must link two different nodes by index") edges.append({"from": f, "to": t, "kind": ed.get("kind") if ed.get("kind") in ("same", "added", "removed", "member") else "same"}) side = lambda s: {"label": txt((s or {}).get("label"), 80), "progressPct": num((s or {}).get("progressPct"), 0, 100), "done": num((s or {}).get("done"), 0, 10 ** 6), "tasks": num((s or {}).get("tasks"), 0, 10 ** 6), "landedPct": num((s or {}).get("landedPct"), 0, 100), "stagePcts": [[txt(x[0], 40), num(x[1], 0, 100)] for x in ((s or {}).get("stagePcts") or [])[:4] if isinstance(x, list) and len(x) == 2]} src = raw.get("source") if isinstance(raw.get("source"), dict) else {} source = {k: txt(src.get(k), 200) for k in ("repo", "base", "head", "sha", "boardPath") if src.get(k)} if isinstance(src.get("pr"), int) and not isinstance(src.get("pr"), bool): source["pr"] = src["pr"] counts = {k: num((raw.get("counts") or {}).get(k), 0, 10 ** 6) for k in SNAP_COUNTS} return {"format": SNAP_FORMAT, "title": txt(raw.get("title"), 120) or "Unblock board", "base": side(raw.get("base")), "head": side(raw.get("head")), "counts": counts, "hidden": num(raw.get("hidden"), 0, 10 ** 6), "nodes": nodes, "edges": edges, "source": source, "wide": raw.get("wide") is True, "outside": outside} SVG_THEMES = { "light": {"paper": "#EDF0F3", "grid": "#C6CED8", "surface": "#FFFFFF", "ink": "#131A23", "ink2": "#4F5B6B", "ink3": "#7F8B9A", "line": "#D6DCE4", "accent": "#E84E12", "accentSoft": "#FDE8DE", "accentLine": "#F2B597", "accentDeep": "#B03A0A", "doing": "#2563EB", "doingSoft": "#E1E9FD", "doingDeep": "#1C4DBD", "done": "#0F8A62", "doneSoft": "#DAF1E7", "doneDeep": "#0A6A4B", "blocked": "#96A0AD", "blockedSoft": "#E7EBEF", "blockedDeep": "#586473", "danger": "#C4362B", "dangerSoft": "#FBE4E2", "edgeOpen": "#6B7786", "edgeSat": "#9CCBB7", "ringTrack": "#E1E6EC", "shadow": "rgba(19,26,35,.10)", "blockFill": "rgba(19,26,35,.028)", "blockLine": "#CCD4DE", "blockHead": "rgba(19,26,35,.035)", "amber": "#A86B12"}, "dark": {"paper": "#0C1015", "grid": "#222B35", "surface": "#151B22", "ink": "#E6EBF0", "ink2": "#A3AEBB", "ink3": "#6E7987", "line": "#29323D", "accent": "#FF6B35", "accentSoft": "#3A1C10", "accentLine": "#7A3618", "accentDeep": "#FFA47F", "doing": "#6E9DFF", "doingSoft": "#15223E", "doingDeep": "#AAC5FF", "done": "#35C592", "doneSoft": "#0F291F", "doneDeep": "#80E0BD", "blocked": "#6E7987", "blockedSoft": "#1E252D", "blockedDeep": "#A3AEBB", "danger": "#FF6B5E", "dangerSoft": "#3A1714", "edgeOpen": "#808C9A", "edgeSat": "#2D6A54", "ringTrack": "#27303A", "shadow": "rgba(0,0,0,.45)", "blockFill": "rgba(255,255,255,.02)", "blockLine": "#2B343F", "blockHead": "rgba(255,255,255,.025)", "amber": "#D9A441"}, } SVG_FONT = "'Hanken Grotesk',-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif" SVG_MONO = "'JetBrains Mono',ui-monospace,'SF Mono',Menlo,Consolas,monospace" def _xml(s): return str(s).replace("&", "&").replace("<", "<").replace(">", ">").replace('"', """) def _text_w(s, size, bold=False): """Rough width of text in a typical sans-serif (images can't load web fonts, so the viewer's system font draws it).""" w = 0.0 for ch in s: if ch in "iljI.,:;'|!()[]{} ": w += 0.28 elif ch in "ftr-\"`": w += 0.36 elif ch in "mwMW@%": w += 0.86 elif ch.isupper() or ch in "#&": w += 0.66 elif ch.isdigit(): w += 0.56 elif ord(ch) > 0x2000: w += 0.9 else: w += 0.53 return w * size * (1.06 if bold else 1.0) def _clip(s, width, size, bold=False): if _text_w(s, size, bold) <= width: return s while s and _text_w(s + "…", size, bold) > width: s = s[:-1] return s.rstrip() + "…" def _wrap(s, width, size, bold=False, lines=2): words, out, cur = s.split(), [], "" for i, w in enumerate(words): trial = (cur + " " + w).strip() if _text_w(trial, size, bold) <= width or not cur: cur = trial else: out.append(cur) cur = w if len(out) == lines - 1: cur = " ".join([w] + words[i + 1:]) break out.append(cur) return [_clip(x, width, size, bold) for x in out[:lines]] def card_facts(board, subtitle=None, date=None): """What the progress card shows, worked out once so the app and the CLI draw the same card.""" r = build_report(board) m, sm = Model(board), r["summary"] groups = sm["groups"] return {"title": board["title"], "subtitle": subtitle or "%d tasks%s" % (sm["tasks"], " in %d groups" % groups if groups else ""), "progressPct": sm["progressPct"], "done": sm["done"], "doing": sm["doing"], "ready": sm["ready"], "blocked": sm["blocked"], "tasks": sm["tasks"], "next": [x["title"] for x in r["next"][:3]], "inProgress": [m.by_id[l]["title"] for l in m.leaf_ids if m.state[l] == "doing"][:3], "date": date or datetime.date.today().isoformat()} def _rnd(x): return int(math.floor(x + 0.5)) def progress_card_svg(f, theme="light"): """A 1200x630 card of a board's progress, for sharing (the size link previews use).""" C = SVG_THEMES["dark" if theme == "dark" else "light"] W, H, M = 1200, 630, 72 P = ['' % (W, H, W, H, _xml("%s: %d%% done" % (f["title"], f["progressPct"])))] P.append('' % C["grid"]) P.append('' % (SVG_FONT, SVG_MONO)) P.append('' % (W, H, C["paper"], W, H)) # the mark and name, top left P.append('' % (M, M - 16, C["ink"], C["done"], C["done"], C["accent"])) P.append('Unblock' % (M + 42, M + 7, C["ink"])) P.append('%s' % (W - M, M + 6, C["ink3"], _xml(f["date"]))) # the title and what it is lines = _wrap(f["title"], 640, 50, True, 2) y = 200 if len(lines) > 1 else 222 for i, ln in enumerate(lines): P.append('%s' % (M, y + i * 60, C["ink"], _xml(ln))) y += (len(lines) - 1) * 60 + 46 P.append('%s' % (M, y, C["ink2"], _xml(_clip(f["subtitle"], 640, 24)))) # the ring: done, then doing cx, cy, r, sw = 940, 262, 132, 28 circ = 2 * math.pi * r P.append('' % (cx, cy, r, C["ringTrack"], sw)) total = max(f["tasks"], 1) doing = _rnd(circ * f["doing"] / total) done = _rnd(circ * f["progressPct"] / 100) if doing and done < _rnd(circ): P.append('' % (cx, cy, r, C["doing"], sw, min(doing, _rnd(circ) - done), _rnd(circ), -done, cx, cy)) if done: P.append('' % (cx, cy, r, C["done"], sw, done, _rnd(circ), "butt" if done >= _rnd(circ) else "round", cx, cy)) P.append('%d%%' % (cx, cy + 20, C["ink"], f["progressPct"])) P.append('done' % (cx, cy + 56, C["ink2"])) # the four counts x = M for key, label, col in (("done", "done", "done"), ("doing", "in progress", "doing"), ("ready", "ready to start", "accent"), ("blocked", "waiting", "blocked")): text = "%d %s" % (f[key], label) w = _rnd(_text_w(text, 20, True)) + 50 P.append('%s' % (x, 356, w, C["surface"], C["line"], x + 22, 378, C[col], x + 36, 385, C["ink"], _xml(text))) x += w + 12 # what's next rows = [("In progress", t, "doing") for t in f["inProgress"][:2]] + [("Next up", t, "accent") for t in f["next"]] y = 470 for label, t, col in rows[:3]: P.append('%s' % (M, y, C[col], label.upper())) P.append('%s' % (M + 150, y, C["ink"], _xml(_clip(t, W - 2 * M - 150, 22)))) y += 40 if not rows: P.append('%s' % (M, y, C["ink2"], "Everything is done." if f["tasks"] and f["done"] == f["tasks"] else "Nothing is ready yet.")) P.append('unblock.esh.sh' % (W - M, H - 40, C["ink3"])) P.append("") return "\n".join(P) + "\n" def cmd_card(board, args): url = github_board_url(args.file) svg = progress_card_svg(card_facts(board, subtitle=url.split("/gh/", 1)[1] if url else None), "dark" if args.dark else "light") with open(args.out, "w", encoding="utf-8") as f: f.write(svg) print("wrote %s" % args.out) def _layered(n, edges): """Layers, order and dummy points for a small DAG, in the spirit of the app's layout: longest-path layers, dummies for long links, barycentre ordering and aligned rows.""" succ = [[] for _ in range(n)] for f, t in edges: succ[f].append(t) # links that would close a loop (a removed link plus an added one can) are drawn but don't shape the layers color, back = [0] * n, set() for s in range(n): if color[s]: continue stack = [(s, iter(succ[s]))] color[s] = 1 while stack: u, it = stack[-1] v = next(it, None) if v is None: color[u] = 2 stack.pop() elif color[v] == 1: back.add((u, v)) elif not color[v]: color[v] = 1 stack.append((v, iter(succ[v]))) fwd = [(f, t) for f, t in edges if (f, t) not in back] layer = [0] * n for _ in range(n): changed = False for f, t in fwd: if layer[t] < layer[f] + 1: layer[t] = layer[f] + 1 changed = True if not changed: break # pull sources right next to what they unblock has_in = {t for f, t in fwd} for u in range(n): outs = [layer[t] for f, t in fwd if f == u] if outs and u not in has_in: layer[u] = min(outs) - 1 L = max(layer) + 1 if n else 0 verts = [{"layer": layer[i], "real": i} for i in range(n)] chains = {} up, down = {}, {} for f, t in fwd: prev, chain = f, [] for l in range(layer[f] + 1, layer[t]): verts.append({"layer": l, "real": None}) v = len(verts) - 1 chain.append(v) down.setdefault(prev, []).append(v) up.setdefault(v, []).append(prev) prev = v down.setdefault(prev, []).append(t) up.setdefault(t, []).append(prev) chains[(f, t)] = chain rows = [[v for v in range(len(verts)) if verts[v]["layer"] == l] for l in range(L)] pos = {} for r in rows: for i, v in enumerate(r): pos[v] = i for it in range(8): rng = range(1, L) if it % 2 == 0 else range(L - 2, -1, -1) for l in rng: nb = up if it % 2 == 0 else down def bary(v): ps = [pos[u] for u in nb.get(v, [])] return sum(ps) / len(ps) if ps else pos[v] rows[l].sort(key=lambda v: (bary(v), pos[v])) for i, v in enumerate(rows[l]): pos[v] = i return verts, rows, up, down, chains, back def _svg_open_groups(snap, C, corner): """A folded board with pointed tasks: one column, where each group holding pointed tasks is drawn open, as the app draws an expanded group (a bordered region, its header with progress and counts, its pointed tasks inside), and the other groups stay folded cards. Links between groups aren't drawn here: this view is for boards that have few.""" nodes, edges = snap["nodes"], snap["edges"] members = {} for e in edges: if e["kind"] == "member": members.setdefault(e["from"], []).append(e["to"]) inside = {k for v in members.values() for k in v} W, H, GY, M, PAD, TOP = 380, 64, 18, 24, 14, 58 parts = (snap.get("line") or _summary_line(snap)).split(" · ") # the summary wraps between its parts: room for the widest one is enough width = int(max(560, W + 2 * PAD + 2 * M, min(max(_text_w(snap["title"], 16, True) + 250, max(_text_w(p, 12.5) for p in parts) + 224) + 2 * M, 1100))) ox, oy = (width - W - 2 * PAD) / 2, M + _head_room(snap, width, M) body, cur = [], 0 if snap.get("point"): # the agent's note, above what it points at pt = snap["point"] lines = _wrap(pt["note"], W + 2 * PAD - 28, 12.5, False, 3) h = 30 + 17 * len(lines) body.append('' '%s' % (ox, oy, W + 2 * PAD, h, C["surface"], C["accent"], C["accent"], C["accent"], _xml(pt["from"].upper()))) body += ['%s' % (40 + 17 * i, C["ink"], _xml(l)) for i, l in enumerate(lines)] body.append('') cur += h + GY for i, n in enumerate(nodes): if i in inside: continue if i not in members: body.append(_svg_card(n, ox + PAD, oy + cur, W, H, C)) cur += H + GY continue ks = members[i] h = TOP + len(ks) * (H + GY) - GY + PAD x0, y0, bw = ox, oy + cur, W + 2 * PAD body.append('' % (x0, y0)) body.append('' % (bw, h, C["blockFill"], C["blockLine"])) body.append('' % (TOP - 12, bw - 16, bw - 1, TOP - 12, C["blockHead"])) body.append('' % (TOP - 12, bw - 1, TOP - 12, C["blockLine"])) body.append('' '' % (C["ink2"], C["ink2"])) room = bw - 36 - 84 - (6 * len(n["spark"]) + 16 if n.get("spark") else 0) # the title stops short of the sparkline and the bar body.append('%s' % (C["ink"], _xml(_clip(n["title"], room, 13, True)))) pc = n.get("progress", 0) if n.get("spark"): body.append(_svg_spark(n["spark"], bw - 92 - 6 * len(n["spark"]), 6, C)) body.append('' % (bw - 80, C["ringTrack"])) if pc: body.append('' % (bw - 80, 64 * pc / 100, C["done"])) stats = " · ".join(["%d%%" % pc] + ([n["group"]] if n.get("group") else [])) body.append('%s' % (C["ink3"], _xml(_clip(stats, bw - 52, 11)))) body.append('') for j, k in enumerate(ks): body.append(_svg_card(nodes[k], x0 + PAD, y0 + TOP + j * (H + GY), W, H, C)) cur += h + GY if snap.get("outside"): # what the scope waits on elsewhere: outlined, like the app's cards for other boards body.append('WAITING OUTSIDE THIS SCOPE' % (ox + PAD, oy + cur + 12, C["ink3"])) cur += 24 for w in snap["outside"]: body.append('' % (ox + PAD, oy + cur, W, C["blockedDeep"])) body.append('%s' % (C["ink2"], _xml(_clip("%s %s" % (w["key"], w["title"]), W - 28, 12.5, True)))) sub = " · ".join(x for x in (w.get("status"), w.get("assignee"), "blocks " + ", ".join(w["blocks"][:4]) + (" +%d" % (len(w["blocks"]) - 4) if len(w["blocks"]) > 4 else "")) if x) body.append('%s' % (C["ink3"], _xml(_clip(sub, W - 28, 11)))) cur += 48 + 10 cur += GY - 10 height = int(oy + max(cur - GY, H) + 44) P = ['' % (width, height, width, height, _xml(snap["title"] + ": " + (snap.get("line") or _summary_line(snap)))), '' % C["grid"], '' % C["shadow"], '' % (SVG_FONT, SVG_MONO), '' % (width, height, corner, C["paper"], width, height, corner), _svg_header(snap, C, width, M)] + body + [_svg_footer(snap, C, width, height, M), ""] return "\n".join(P) def snapshot_svg(snap, theme="light", corner=14): """Draw a (clean) snapshot as a standalone SVG. corner=0 for square edges, to fill a frame.""" C = SVG_THEMES["dark" if theme == "dark" else "light"] nodes, edges = snap["nodes"], snap["edges"] if snap.get("wide") or any(e["kind"] == "member" for e in edges): return _svg_open_groups(snap, C, corner) W, H, GX, GY, M = 380 if snap.get("wide") else 222, 64, 58, 18, 24 # group cards carry their counts verts, rows, up, down, chains, back = _layered(len(nodes), [(e["from"], e["to"]) for e in edges]) hv = lambda v: H if verts[v]["real"] is not None else 8 y = {} for r in rows: cur = 0 for v in r: y[v] = cur cur += hv(v) + GY center = lambda v: y[v] + hv(v) / 2 for it in range(10): rng = range(len(rows)) if it % 2 == 0 else range(len(rows) - 1, -1, -1) for l in rng: r = rows[l] want = [] for v in r: nb = up.get(v, []) + down.get(v, []) want.append(sum(center(u) for u in nb) / len(nb) - hv(v) / 2 if nb else y[v]) f = list(want) for i in range(1, len(r)): f[i] = max(f[i], f[i - 1] + hv(r[i - 1]) + GY) bk = list(want) for i in range(len(r) - 2, -1, -1): bk[i] = min(bk[i], bk[i + 1] - hv(r[i]) - GY) avg = [(p + q) / 2 for p, q in zip(f, bk)] for i in range(1, len(r)): avg[i] = max(avg[i], avg[i - 1] + hv(r[i - 1]) + GY) for v, val in zip(r, avg): y[v] = val top = min(y.values()) if y else 0 for v in y: y[v] -= top # squeeze out the bands no card reaches, so a picture is no taller than its cards need shift, reach = {}, None for v in sorted(y, key=lambda v: y[v]): gap = 0 if reach is None else y[v] - reach shift_now = (shift[prev] if reach is not None else 0) + max(0, gap - GY) shift[v] = shift_now reach = max(reach if reach is not None else y[v], y[v] + hv(v)) prev = v for v in y: y[v] -= shift[v] x = lambda v: verts[v]["layer"] * (W + GX) cw = len(rows) * (W + GX) - GX if rows else W ch = max([y[v] + hv(v) for v in y] or [H]) title_w = max(_text_w(snap["title"], 16, True), _text_w(snap.get("line") or _summary_line(snap), 12.5)) + 40 width = int(max(cw + 2 * M, min(title_w + 2 * M, 1100), 560)) ox = M + (width - 2 * M - cw) / 2 oy = M + _head_room(snap, width, M) pop = _svg_point_pop(snap, verts, y, x, W, H, width, M, oy) if snap.get("point") else None if pop: # the callout sits between the header and the cards oy += pop["room"] height = int(oy + ch + 44) P = [] P.append('' % (width, height, width, height, _xml(snap["title"] + ": " + (snap.get("line") or _summary_line(snap))))) P.append('' % C["grid"]) P.append('' % C["shadow"]) P.append('') P.append('' % (SVG_FONT, SVG_MONO)) P.append('' % (width, height, corner, C["paper"], width, height, corner)) P.append(_svg_header(snap, C, width, M)) # links first, under the cards for e in edges: f, t = e["from"], e["to"] pts = [(ox + x(f) + W, oy + center(f))] for v in chains.get((f, t), []): pts += [(ox + x(v), oy + center(v)), (ox + x(v) + W, oy + center(v))] pts.append((ox + x(t), oy + center(t))) d = "M%.1f,%.1f" % pts[0] for i in range(1, len(pts)): (x0, y0), (x1, y1) = pts[i - 1], pts[i] if i % 2 == 0 and len(pts) > 2 and i < len(pts) - 1 or abs(y1 - y0) < 0.5: d += "L%.1f,%.1f" % (x1, y1) else: k = max(24.0, abs(x1 - x0) * 0.5) d += "C%.1f,%.1f %.1f,%.1f %.1f,%.1f" % (x0 + k, y0, x1 - k, y1, x1, y1) src = nodes[f] col, sw, extra = (C["edgeSat"] if src["state"] == "done" else C["edgeOpen"]), 1.6, "" if e["kind"] == "added": col, sw, extra = C["done"], 2.4, " " elif e["kind"] == "removed": col, extra = C["danger"], ' stroke-dasharray="5 4" opacity=".8"' if e["kind"] == "member": # a task in its group, not a wait P.append('' % (d, C["edgeOpen"])) continue faded = nodes[f]["tag"] == "context" and nodes[t]["tag"] == "context" ex, ey = pts[-1] op = ' opacity=".45"' if faded and not extra else "" P.append('' % (d, col, sw, extra.strip() and extra, op, ex, ey, col, op)) for v, vert in enumerate(verts): if vert["real"] is not None: P.append(_svg_card(dict(nodes[vert["real"]], attached=True) if pop else nodes[vert["real"]], ox + x(v), oy + y[v], W, H, C)) if pop: P.append(pop["draw"](C, ox, oy)) P.append(_svg_footer(snap, C, width, height, M)) P.append("") return "\n".join(P) def _svg_point_pop(snap, verts, y, x, W, H, width, M, top): """The agent's note as a callout, like the board's: a bubble above the cards, its arrow on the first task pointed at when nothing sits above that task in its column (lower down, a dashed line leads to it). Pointed tasks are ringed.""" real = [v for v, vt in enumerate(verts) if vt["real"] is not None] hits = [v for v in real if snap["nodes"][verts[v]["real"]]["tag"] == "pointed"] if not hits: return None v = min(hits, key=lambda v: (y[v], verts[v]["layer"])) leads = all(y[u] >= y[v] for u in real if verts[u]["layer"] == verts[v]["layer"]) pt = snap["point"] bw_max = min(width - 2 * M, 440) lines = _wrap(pt["note"], bw_max - 28, 13, False, lines=4) bw = max(max(_text_w(ln, 13) for ln in lines), _text_w(pt["from"].upper(), 10.5, True) + 16) + 28 bw = min(bw_max, max(bw, 180)) bh = 36 + 18 * len(lines) room = bh + 18 def draw(C, ox, oy): cx = ox + x(v) + W / 2 x0 = max(M, min(cx - bw / 2, width - M - bw)) x1, y0 = x0 + bw, top - 6 y1, r = y0 + bh, 12 ax = max(x0 + r + 10, min(cx, x1 - r - 10)) notch = "H%.1fL%.1f,%.1fL%.1f,%.1f" % (ax + 8, ax, y1 + 8, ax - 8, y1) if leads else "" d = "M%.1f,%.1fH%.1fA%d,%d 0 0 1 %.1f,%.1fV%.1fA%d,%d 0 0 1 %.1f,%.1f%sH%.1fA%d,%d 0 0 1 %.1f,%.1fV%.1fA%d,%d 0 0 1 %.1f,%.1fZ" % ( x0 + r, y0, x1 - r, r, r, x1, y0 + r, y1 - r, r, r, x1 - r, y1, notch, x0 + r, r, r, x0, y1 - r, y0 + r, r, r, x0 + r, y0) out = [''] if leads and y[v] > 4: # the task sits lower in its column: lead the eye down to it out.append('' % (ax, y1 + 8, oy + y[v] - 8, C["accent"])) out.append('' % (d, C["surface"], C["accent"])) out.append('' % (x0 + 17, y0 + 17, C["accent"])) out.append('%s' % (x0 + 27, y0 + 21, C["accent"], _xml(pt["from"].upper()))) for i, ln in enumerate(lines): out.append('%s' % (x0 + 14, y0 + 42 + 18 * i, C["ink"], _xml(ln))) out.append('') return "\n".join(out) return {"v": v, "leads": leads, "room": room, "draw": draw} def _summary_line(snap): b, h, c = snap["base"], snap["head"], snap["counts"] arrow = "%d%% → %d%% done" % (b["progressPct"], h["progressPct"]) if b["progressPct"] != h["progressPct"] else "%d%% done" % h["progressPct"] words = [("completes", "completed"), ("unblocks", "nowReady"), ("blocks", "nowBlocked"), ("reopens", "reopened"), ("adds", "added"), ("removes", "removed"), ("edits", "changed")] return " · ".join([arrow] + ["%s %d" % (w, c[k]) for w, k in words if c.get(k)]) def _header_lines(snap, width, M, most=5): """The summary under the title, broken between its parts into lines that fit beside the progress bar: momentum and lead times come last, so they get lines of their own rather than being clipped.""" room, lines = width - 2 * M - 216, [""] for p in (snap.get("line") or _summary_line(snap)).split(" · "): lines[-1:] = [lines[-1] + " · " + p] if lines[-1] and (_text_w(lines[-1] + " · " + p, 12.5) <= room or len(lines) == most) else ([p] if not lines[-1] else [lines[-1], p]) return lines def _head_room(snap, width, M): """How far below the top the cards start: room for the title and as many summary lines as there are.""" return 78 + 16 * max(0, len(_header_lines(snap, width, M)) - 2) def _svg_header(snap, C, width, M): b, h = snap["base"], snap["head"] out = ['%s' % (M, M + 16, C["ink"], _xml(_clip(snap["title"], width - 2 * M - 250, 16, True)))] room, lines = width - 2 * M - 216, _header_lines(snap, width, M) for i, ln in enumerate(lines): out.append('%s' % (M, M + 37 + 16 * i, C["ink2"], _xml(_clip(ln, room, 12.5)))) # progress: the base's share, then what this change adds bw, bx, by = 200, width - M - 200, M + 30 out.append('' % (bx, by, bw, C["ringTrack"])) lo, hi = min(b["progressPct"], h["progressPct"]), max(b["progressPct"], h["progressPct"]) lp, st = ((h.get("landedPct") or 0), (h.get("stagePcts") or [])) if lo == hi else (0, []) sp = sum(p for _, p in st) if lp or sp: # the stages beyond done (deepest darkest), then done, then landed and waiting to be certified (lightest) light, mid = (C["edgeSat"], C["done"]) if sp else (C["done"], C["doneDeep"]) segs = [(lo, light if lp else mid, 1), (lo - lp, mid, 1)] for i, (_, p) in enumerate(st): segs.append((sum(q for _, q in st[i:]), C["doneDeep"], 0.45 + 0.55 * (i + 1) / len(st))) for w, col, op in segs: if w > 0: out.append('' % (bx, by, bw * w / 100, col, "" if op >= 1 else ' opacity="%.2f"' % op)) lo = hi = 0 if lo: out.append('' % (bx, by, bw * lo / 100, C["doneDeep"] if h["progressPct"] >= b["progressPct"] else C["done"])) if hi > lo: out.append('' % (bx + bw * lo / 100, by, bw * (hi - lo) / 100, C["done"] if h["progressPct"] > b["progressPct"] else C["danger"])) labels = snap["caption"] if snap.get("caption") else "%s → %s" % (b["label"] or "base", h["label"] or "head") out.append('%s' % (width - M, M + 16, C["ink3"], _xml(_clip(labels, 240, 11)))) return "\n".join(out) def _svg_footer(snap, C, width, height, M): out = [] if snap.get("hidden"): out.append('%s' % (M, height - 18, C["ink3"], _xml(snap.get("more") or "+%d more changes not shown" % snap["hidden"]))) bx = width - M - 118 out.append('' % (bx, height - 29, C["ink"], C["done"], C["done"], C["accent"])) out.append('unblock.esh.sh' % (bx + 20, height - 18, C["ink3"])) return "\n".join(out) SNAP_CHIP = {"completed": ("DONE", "done"), "nowReady": ("NOW READY", "accent"), "nowBlocked": ("NOW BLOCKED", "blockedDeep"), "reopened": ("REOPENED", "doing"), "started": ("STARTED", "doing"), "added": ("NEW", "done"), "removed": ("REMOVED", "danger"), "changed": ("EDITED", "ink3"), "needsYou": ("WAITING ON YOU", "accent"), "pointed": ("◎ HERE", "accent")} def _svg_tick(state, C): if state == "done": return '' % (C["done"], C["surface"]) if state == "doing": return '' % (C["doing"], C["doing"]) if state == "blocked": return '' % C["blocked"] return '' % C["ink"] def _svg_card(n, x, y, W, H, C): tag, st, grp = n["tag"], n["state"], n["kind"] == "group" out = ['' % (x, y, ' opacity=".5"' if tag == "context" else ' opacity=".82"' if tag == "removed" else "")] stroke, sw, dash = C["line"], 1, "" if tag in ("nowReady", "pointed"): out.append('' % (W + 8, H + 8, C["accentSoft"], 7 if tag == "pointed" else 5)) stroke, sw = C["accent"], 2.5 if tag == "pointed" else 2 elif tag in ("added", "completed"): stroke, sw = C["done"], 2 if tag == "added" else 1.5 elif tag == "nowBlocked": stroke, sw = C["blockedDeep"], 1.5 elif tag == "reopened": stroke, sw = C["doing"], 1.5 elif tag == "removed": stroke, sw, dash = C["danger"], 1.5, ' stroke-dasharray="5 4"' if grp: for off in (6, 3): out.append('' % (off, off, W, H, C["surface"], C["line"])) out.append('' % (W, H, C["surface"], stroke, sw, dash)) ring = "pct" in n and st == "blocked" and not grp tx, tw = 36, W - 36 - (50 if ring else 14) lines = _wrap(n["title"], tw, 13, True) ty = [22, 38] if len(lines) == 2 else [27] out.append('%s' % (H / 2 if len(lines) == 1 else 30, _svg_tick(st, C) if not grp else '' % (C["ink2"], C["ink2"]))) for i, ln in enumerate(lines): out.append('%s' % (tx, ty[i], C["ink"] if tag != "removed" else C["ink2"], ' text-decoration="line-through"' if tag == "removed" else "", _xml(ln))) # meta row: state pill, points, group my = 54 if len(lines) == 2 else 45 label = ("GROUP · %d%%" % n.get("progress", 0)) if grp else st.upper() pill_fg, pill_bg = {"done": ("doneDeep", "doneSoft"), "doing": ("doingDeep", "doingSoft"), "blocked": ("blockedDeep", "blockedSoft"), "ready": ("accentDeep", "accentSoft")}[st if not grp else "blocked"] pw = _text_w(label, 9.5, True) + 12 out.append('%s' % (tx, my - 11, pw, C[pill_bg], tx + 6, my, C[pill_fg], _xml(label))) meta = [] if not grp and n.get("estimate") is not None: meta.append("%s pt" % fmt_num(n["estimate"])) if "wasPct" in n: meta.append("was %d%%" % n["wasPct"]) if n.get("group"): meta.append(n["group"]) if n.get("activity"): # what its agent said it's doing, faded once it's half an hour old meta = [n["activity"]] elif n.get("quiet"): # in progress, and nothing heard from it for a while meta = ["no sign of life for %s" % n["quiet"]] if meta: mx = tx + pw + 7 col = C["doing"] if n.get("activity") and not n.get("stale") else C["amber"] if n.get("quiet") and not n.get("activity") else C["ink3"] out.append('%s' % (mx, my, col, _xml(_clip(" · ".join(meta), W - mx - (50 if ring else 12), 11)))) if ring: r, circ = 14.5, 2 * 3.14159265 * 14.5 cx, cy = W - 28, H / 2 out.append('' % (cx, cy, r, C["ringTrack"])) if "wasPct" in n: out.append('' % (r, C["accentLine"], circ * n["wasPct"] / 100, circ)) out.append('' % (r, C["accent"], max(0.01, circ * n["pct"] / 100 - 1.5), circ)) out.append('%d%%' % (C["ink"], n["pct"])) if grp and n.get("spark"): out.append(_svg_spark(n["spark"], W - 14 - 6 * len(n["spark"]), 12, C)) chip = SNAP_CHIP.get(tag) if not (n.get("attached") and tag == "pointed") else None # the callout and the ring say it if chip: text, col = chip cwid = _text_w(text, 9, True) + 14 out.append('%s' % (W - 12 - cwid, cwid, C[col], cwid / 2, C["surface"], text)) out.append('%s' % _xml(n["title"] + ("\n" + "; ".join(n["edits"]) if n.get("edits") else ""))) return "".join(out) def digest_base(path, since): """(board or None, label, commits): the board as it was `since` ago (7d, 12h, 2w) or at a git ref.""" d = os.path.dirname(os.path.abspath(path)) top = git(["rev-parse", "--show-toplevel"], cwd=d).strip() rel = os.path.relpath(os.path.realpath(path), os.path.realpath(top)).replace(os.sep, "/") mo = re.match(r"^(\d+)\s*([hdw])$", since.strip()) if mo: n, unit = int(mo.group(1)), mo.group(2) before = int(time.time() - n * {"h": 3600, "d": 86400, "w": 604800}[unit]) ref = git(["log", "-1", "--before=@%d" % before, "--format=%H", "--", rel], cwd=top).strip() label = "%d %s ago" % (n, {"h": "hour", "d": "day", "w": "week"}[unit] + ("" if n == 1 else "s")) else: ref, label = since.strip(), since.strip() # a ref, never an option: "--output=…" would make git write a file if ref.startswith("-") or subprocess.run(["git", "rev-parse", "--verify", "--quiet", ref + "^{commit}"], cwd=top, capture_output=True).returncode: raise BoardError('Unknown git ref "%s". Use a ref, or a time like 7d, 12h or 2w.' % ref) rng = (ref + "..HEAD") if ref else "HEAD" commits = int(git(["rev-list", "--count", rng, "--", rel], cwd=top).strip() or 0) return (board_at(ref, path) if ref else None), label, commits def digest_text(d, board, commits, markdown=False): e, b, h = d["effects"], d["base"], d["head"] code = (lambda x: "`%s`" % x) if markdown else (lambda x: x) out = [] if not b["tasks"]: head = "Since %s: %d%% done now" % (b["label"], h["progressPct"]) elif b["progressPct"] != h["progressPct"]: head = "Since %s: %d%% → %d%% done" % (b["label"], b["progressPct"], h["progressPct"]) else: head = "Since %s: still %d%% done" % (b["label"], h["progressPct"]) out.append(("**%s**" % head if markdown else head) + ", %d commit%s touched the plan." % (commits, "" if commits == 1 else "s")) if not d["hasChanges"]: out.append("Nothing changed in the plan.") def part(title, items): if items: names = ", ".join("%s %s" % (x["title"], "(%s)" % code(x["id"])) for x in items[:8]) + (" and %d more" % (len(items) - 8) if len(items) > 8 else "") out.append("%s (%d): %s" % (("**%s**" % title) if markdown else title, len(items), names)) part("Finished", e["completed"]) part("Now ready", e["nowReady"]) part("New", d["added"]) part("Now blocked", e["nowBlocked"]) part("Reopened", e["reopened"]) part("Removed", d["removed"]) nxt = build_report(board)["next"] if nxt: out.append("Next up: %s (%s)%s." % (nxt[0]["title"], code(nxt[0]["id"]), ", unblocks %d" % nxt[0]["unblocksOpen"] if nxt[0]["unblocksOpen"] else "")) for w in d.get("warnings") or []: out.append("Worth a look: " + w["text"]) return ("\n\n" if markdown else "\n").join(out) def cmd_digest(board, args): """What changed in the plan since a while ago, from the board file's git history.""" path = os.path.abspath(args.file) a, label, commits = digest_base(path, args.since) d = board_diff(a or empty_board(board["title"]), board, label if a else "the board was started", "now") d["warnings"] = [w for w in d["warnings"] if w["kind"] != "noDescription"] # that one is for pull requests if args.json: print(pretty(dict(d, commits=commits))) else: print(digest_text(d, board, commits, markdown=args.markdown)) ISSUE_RE = re.compile(r"^(?:https://github\.com/)?(?:([\w.-]+/[\w.-]+)(?:#|/issues/))?#?(\d+)$") def issue_ref(text): """Tidy what someone typed for a task's issue: "owner/repo#12", a GitHub issue URL, "#12" or "12".""" m = ISSUE_RE.match(str(text).strip()) if not m: raise BoardError('An issue is written owner/repo#123, or #123 for this repository (got "%s").' % text) return ("%s#%s" % (m.group(1), m.group(2))) if m.group(1) else "#%s" % m.group(2) def issue_target(ref, repo): """(owner/repo, number) for a task's issue, or None; "#12" is in `repo`.""" m = ISSUE_RE.match(str(ref or "").strip()) if not m or not (m.group(1) or repo): return None if m.group(1) and any(seg in (".", "..") for seg in m.group(1).split("/")): return None return m.group(1) or repo, int(m.group(2)) def repo_of(path): url = github_board_url(path) return url.split("/gh/", 1)[1] if url else None def sync_issues(board, repo, get): """Tasks whose issue was closed as completed become done. Returns (ids marked done, notes for the user). `get(repo, number)` returns the issue from GitHub's REST API, or None.""" m = Model(board) done, notes = [], [] for t in board["tasks"]: if not t.get("issue") or m.is_group(t["id"]): continue tgt = issue_target(t["issue"], repo) if not tgt: notes.append("%s: can't tell which repository \"%s\" is in; write it owner/repo#N." % (t["id"], t["issue"])) continue i = get(*tgt) if not i: notes.append("%s: %s#%d isn't there, or this token can't read it." % (t["id"], tgt[0], tgt[1])) continue closed, planned = i.get("state") == "closed", i.get("state_reason") != "not_planned" if closed and planned and t["status"] != "done": t["status"] = "done" done.append(t["id"]) elif closed and not planned and t["status"] != "done": notes.append("%s: %s#%d was closed as not planned. Remove the task, or unlink the issue." % (t["id"], tgt[0], tgt[1])) elif not closed and t["status"] == "done": notes.append("%s is done, but %s#%d is still open." % (t["id"], tgt[0], tgt[1])) return done, notes def github_get(token=None): """get(repo, number): one issue from the REST API, or None when it isn't there.""" api = (os.environ.get("GITHUB_API_URL") or "https://api.github.com").rstrip("/") def get(repo, n): url = "%s/repos/%s/issues/%d" % (api, repo, n) try: if token: return gh_request("GET", url, token) req = urllib.request.Request(url, headers={"Accept": "application/vnd.github+json", "User-Agent": "unblock"}) return json.loads(urllib.request.urlopen(req, timeout=20).read().decode("utf-8")) except urllib.error.HTTPError as e: if e.code in (404, 410): return None raise return get REF_RE = re.compile(r"^(?:(?P\.{1,2}/[^#]*|/[^#]+|[\w.-]+\.json)|(?P\w[\w.-]*/[\w.-]+)(?::(?P[^#]+))?)(?:#(?P[^#\s]+))?$") def parse_ref(ref): """A task's `ref`: another board, or one task in it. "owner/repo", "owner/repo#task", "owner/repo:path/board.json#task", or a local file: "../api/.github/unblock.json#task", or a plan beside this one, "garden.unblock.json#task". Returns a dict, or None.""" m = REF_RE.match(str(ref or "").strip()) if not m: return None r = {"repo": m.group("repo"), "path": m.group("path"), "file": m.group("file"), "id": m.group("id")} for part in (r["repo"], r["path"]): # "o/r:../../../user" would aim GitHub API calls somewhere else if part and (part.startswith("/") or any(seg in ("", ".", "..") for seg in part.split("/"))): return None return r def fetch_ref_board(r, base_dir, token=None, inside=False): """The board a ref points at, normalized, or None when it can't be read. inside=True keeps file refs within base_dir (the workflow runs other people's boards).""" if r["file"]: p = r["file"] if os.path.isabs(r["file"]) else os.path.join(base_dir, r["file"]) if os.path.isdir(p): p = next((os.path.join(p, x) for x in BOARD_PATHS if os.path.isfile(os.path.join(p, x))), p) real, root = os.path.realpath(p), os.path.realpath(base_dir) if not os.path.isfile(real) or os.path.getsize(real) > 20 * 1024 * 1024 or (inside and os.path.commonpath([real, root]) != root): return None # not /dev/zero, not a huge file, and in the workflow nothing outside the repository try: return load(p) except (BoardError, OSError): return None api = (os.environ.get("GITHUB_API_URL") or "https://api.github.com").rstrip("/") raw_host = os.environ.get("UNBLOCK_RAW_URL", "https://raw.githubusercontent.com").rstrip("/") for path in ([r["path"]] if r["path"] else list(BOARD_PATHS)): try: if token: req = urllib.request.Request("%s/repos/%s/contents/%s" % (api, r["repo"], urllib.parse.quote(path)), headers={"Authorization": "Bearer " + token, "Accept": "application/vnd.github.raw", "User-Agent": "unblock"}) else: req = urllib.request.Request("%s/%s/HEAD/%s" % (raw_host, r["repo"], path), headers={"User-Agent": "unblock"}) text = urllib.request.urlopen(req, timeout=20).read().decode("utf-8") return parse_board_text(text, "%s:%s" % (r["repo"], path)) except urllib.error.HTTPError as e: if e.code != 404: return None except (BoardError, OSError, ValueError): return None return None def ref_state(b, tid): """(state, progress %, title) of a task in another board, or of the whole board when tid is None.""" m = Model(b) if tid is None: r = build_report(b)["summary"] state = "done" if r["tasks"] and r["done"] == r["tasks"] else "doing" if r["doing"] or r["done"] else "todo" return state, r["progressPct"], b["title"] if tid not in m.by_id: return None x = m.metrics(tid) return x["state"], x["progress"], m.by_id[tid]["title"] def sync_refs(board, base_dir, fetch): """Tasks that point at another board (ref) follow it: done when it's done, doing once work there started. Returns (changes as (id, old, new), notes). `fetch(parsed_ref)` returns that board or None.""" m = Model(board) changes, notes, cache = [], [], {} for t in board["tasks"]: if not t.get("ref") or m.is_group(t["id"]): continue r = parse_ref(t["ref"]) if not r: notes.append('%s: can\'t read ref "%s"; write owner/repo, owner/repo#task or ../path/board.json#task.' % (t["id"], t["ref"])) continue key = (r["repo"], r["path"], r["file"]) if key not in cache: cache[key] = fetch(r) b = cache[key] if b is None: notes.append("%s: couldn't read the board %s points at." % (t["id"], t["ref"])) continue st = ref_state(b, r["id"]) if not st: notes.append("%s: there's no task %s in %s." % (t["id"], r["id"], r["repo"] or r["file"])) continue new = "done" if st[0] == "done" else "doing" if st[0] == "doing" or st[1] > 0 else None if new and t["status"] != new and not (new == "doing" and t["status"] == "done"): changes.append((t["id"], t["status"], new)) t["status"] = new return changes, notes def cmd_sync(board, args): """Tasks linked elsewhere follow it: closed issues mark them done, and tasks pointing at another board (ref) take its state.""" repo = args.repo or repo_of(args.file) has_issues, has_refs = any(t.get("issue") for t in board["tasks"]), any(t.get("ref") for t in board["tasks"]) if not has_issues and not has_refs: print("No task links to an issue or another board. Link one with: unblock edit --issue owner/repo#123, or --ref owner/repo#task") return token = github_token() done, notes, changes = [], [], [] if has_issues: done, notes = sync_issues(board, repo, github_get(token)) if has_refs: root = project_of(os.path.abspath(args.file)) # relative refs start from the project, not .github/ changes, more = sync_refs(board, root, lambda r: fetch_ref_board(r, root, token)) notes += more if (done or changes) and not args.dry_run: save(args.file, board) for n in notes: print("note: " + n) verb = "Would mark" if args.dry_run else "Marked" if done: print("%s done (their issues were closed): %s" % (verb, ", ".join(done))) for tid, old, new in changes: print("%s %s %s (it follows the board it points at; was %s)" % (verb, tid, new, old)) if not done and not changes: print("Nothing to change: linked issues and boards match the tasks.") def export_issues(board, ids, repo, board_repo, post, get, link=None): """Create a GitHub issue for each chosen task (a group brings the open tasks inside it), then make groups' tasks their sub-issues and links blocked-by, among the exported tasks and tasks already linked to issues in `repo`. Writes `issue` back on each task. `post(path, body)` and `get(path)` talk to the REST API under /repos/. Returns the (task id, issue number) pairs created.""" m = Model(board) chosen = [] for i in ids: inside = [t["id"] for t in board["tasks"] if i in m.ancestors(t["id"]) and (m.is_group(t["id"]) or t["status"] != "done")] # finished work stays out for x in [i] + inside: if x not in chosen: chosen.append(x) chosen = [x for x in chosen if not m.by_id[x].get("issue")] ref = lambda n: "#%d" % n if repo == board_repo else "%s#%d" % (repo, n) made, info = [], {} # task id -> {number, id} for tid in chosen: t = m.by_id[tid] body = (t.get("notes") or "").strip() extra = [] if t.get("tags"): extra.append("Tags: " + ", ".join(t["tags"])) if t.get("estimate") is not None: extra.append("Estimate: %s pt" % fmt_num(t["estimate"])) extra.append("From the Unblock plan%s: task `%s`." % (" ([open it](%s))" % link if link else "", tid)) i = post("/issues", {"title": t["title"], "body": (body + "\n\n" if body else "") + "\n".join("%s" % x for x in extra)}) info[tid] = {"number": i["number"], "id": i["id"]} t["issue"] = ref(i["number"]) made.append((tid, i["number"])) # issues that already existed, for links to them for t in board["tasks"]: tg = issue_target(t.get("issue"), board_repo or repo) if t["id"] not in info and tg and tg[0] == repo: info[t["id"]] = {"number": tg[1], "id": None} def iid(tid): if info[tid]["id"] is None: got = get("/issues/%d" % info[tid]["number"]) info[tid]["id"] = got["id"] if got else False return info[tid]["id"] for tid, n in made: t = m.by_id[tid] if t.get("parent") in info and info[t["parent"]]["number"] and m.is_group(t["parent"]): if iid(tid): post("/issues/%d/sub_issues" % info[t["parent"]]["number"], {"sub_issue_id": iid(tid)}) for d in t["dependsOn"]: if d in info and iid(d): post("/issues/%d/dependencies/blocked_by" % n, {"issue_id": iid(d)}) return made def cmd_export_issues(board, args): """Create GitHub issues for chosen tasks, so GitHub's agents can be assigned to them.""" m = Model(board) ids = resolve_ids(m, args.ids) board_repo = repo_of(args.file) repo = args.repo or board_repo if not repo: raise BoardError("Say which repository: unblock export-issues --repo owner/repo") if args.dry_run: titles = {} def post(path, body): if path == "/issues": k = len(titles) + 1 titles[k] = body["title"] print("would create: %s" % body["title"]) return {"number": k, "id": k} n = int(path.split("/")[2]) other = titles.get(body.get("sub_issue_id") or body.get("issue_id"), "an existing issue") print(" %s: %s" % (titles.get(n, "#%d" % n), "sub-issue " + other if "sub_issues" in path else "blocked by " + other)) made = export_issues(json.loads(json.dumps(board)), ids, repo, board_repo, post, lambda p: {"id": 0}) print("%d issue%s in %s (dry run: nothing created)" % (len(made), "" if len(made) == 1 else "s", repo)) return token = github_token() if not token: raise BoardError("Creating issues needs a GitHub token that can write issues: set GITHUB_TOKEN, or sign in with `gh auth login`.") api = (os.environ.get("GITHUB_API_URL") or "https://api.github.com").rstrip("/") + "/repos/" + repo def get(path): try: return gh_request("GET", api + path, token) except urllib.error.HTTPError: return None made = export_issues(board, ids, repo, board_repo, lambda path, body: gh_request("POST", api + path, token, body), get, github_board_url(args.file)) save(args.file, board) for tid, n in made: print("%s -> %s#%d" % (tid, repo, n)) print("created %d issue%s in %s; the tasks now link to them" % (len(made), "" if len(made) == 1 else "s", repo) if made else "Nothing to create: those tasks already have issues.") # ---------------------------------------------------------------- live state: what each agent is doing # Claude Code hook events -> the state they mean for the tasks that session holds HOOK_STATE = {"SessionStart": "working", "UserPromptSubmit": "working", "PostToolUse": "working", "SubagentStop": "working", "Notification": "needs-you", "Stop": "needs-you", "SessionEnd": "stopped"} LIVE_STATES = ("working", "needs-you", "stopped") HOOK_EVENTS = ("SessionStart", "UserPromptSubmit", "Notification", "Stop", "SessionEnd") HOOK_CMD = "command -v unblock >/dev/null 2>&1 && unblock heartbeat --hook || true" def heartbeat(path, holder, state="working", session=None, agent=None, ids=None): """Record that an agent is alive and what it's doing, on the claims it holds (or on `ids`). A heartbeat also renews the lease, so a working agent never loses its claim. Returns the task ids it touched.""" touched = [] with _claims(path) as (c, now): for k, v in c.items(): mine = (k in ids) if ids else (v.get("by") == holder or (session and v.get("session") == session)) if not mine: continue v.update(seen=now, state=state) if session: v["session"] = session if agent: v["agent"] = agent if state != "stopped": v["until"] = max(v["until"], now + 7200) touched.append(k) return touched def cmd_heartbeat(args): """`unblock heartbeat`: for hooks and agents. With --hook it reads a Claude Code hook's JSON from stdin and never prints or fails, since its output would reach the session.""" hook = {} try: if args.hook and not sys.stdin.isatty(): raw = sys.stdin.read() hook = json.loads(raw) if raw.strip() else {} path = args.file if hook.get("cwd") and not args.file_given and os.path.isdir(hook["cwd"]): os.chdir(hook["cwd"]) path = find_board() if not os.path.isfile(path): return 0 state = args.state or HOOK_STATE.get(hook.get("hook_event_name"), "working") agent = args.agent or ("claude" if args.hook else None) touched = heartbeat(path, args.holder or default_holder(path), state, args.session or hook.get("session_id"), agent, args.ids or None) if not args.hook: print("%s: %s" % (state, ", ".join(touched)) if touched else "No claims to update. Claim a task first: unblock claim ") except Exception as e: if not args.hook: raise BoardError(str(e)) return 0 STATUS_CMD = "command -v unblock >/dev/null 2>&1 && unblock statusline || true" def status_line(board, claims, session=None, holder=None, color=True): """One line for an editor's status bar: progress, what's ready, who needs you, and the task this session holds.""" m = Model(board) r = build_report(board)["summary"] open_claims = {k: v for k, v in claims.items() if k in m.by_id and m.by_id[k].get("status") != "done"} needs = sorted(k for k, v in open_claims.items() if v.get("state") == "needs-you") mine = [k for k, v in open_claims.items() if (session and v.get("session") == session) or (holder and v.get("by") == holder)] dim = (lambda t: "\033[2m%s\033[0m" % t) if color else (lambda t: t) hot = (lambda t: "\033[38;5;208m%s\033[0m" % t) if color else (lambda t: t) parts = ["%d ready" % r["ready"]] if r["doing"]: parts.append("%d doing" % r["doing"]) if needs: parts.append(hot("%d need%s you" % (len(needs), "s" if len(needs) == 1 else ""))) if mine: parts.append("on %s" % mine[0]) return signature(r["progressPct"]) + dim(" · ") + dim(" · ").join(parts) def cmd_statusline(args): """`unblock statusline`: Claude Code's status line runs this with the session's details as JSON on stdin. Never fails and prints nothing when there's no board, so it can stay in settings everywhere.""" try: info = {} if not sys.stdin.isatty(): raw = sys.stdin.read() info = json.loads(raw) if raw.strip() else {} where = (info.get("workspace") or {}).get("current_dir") or info.get("cwd") path = args.file if where and not args.file_given and os.path.isdir(where): os.chdir(where) path = find_board() if not os.path.isfile(path): return 0 print(status_line(load(path), active_claims(path), info.get("session_id"), default_holder(path), color=not os.environ.get("NO_COLOR") and not args.plain)) except Exception: pass return 0 def setup_status_line(root="."): """Claude Code's status line runs `unblock statusline`, unless the project already has a status line of its own.""" p = os.path.join(root, ".claude", "settings.json") data = {} if os.path.isfile(p): with open(p, encoding="utf-8") as f: try: data = json.load(f) except ValueError: raise BoardError("%s isn't valid JSON, so the status line wasn't added." % p) cur = data.get("statusLine") if cur: return p, "ours" if "unblock statusline" in json.dumps(cur) else "theirs" data["statusLine"] = {"type": "command", "command": STATUS_CMD, "padding": 0} os.makedirs(os.path.dirname(p), exist_ok=True) write_file(p, json.dumps(data, indent=2) + "\n") return p, "added" def pane_port(root): """A port of this project's own for the side pane, so two projects' panes never show each other's board.""" return 7100 + int(hashlib.sha1(os.path.realpath(root).encode("utf-8")).hexdigest(), 16) % 800 def setup_launch_pane(root="."): """An `unblock` entry in .claude/launch.json, so Claude Code's browser pane can show the live board beside the chat.""" p = os.path.join(root, ".claude", "launch.json") data = {"version": "0.0.1", "configurations": []} if os.path.isfile(p): with open(p, encoding="utf-8") as f: try: data = json.load(f) except ValueError: raise BoardError("%s isn't valid JSON, so the board's pane wasn't added." % p) confs = data.setdefault("configurations", []) if any(c.get("name") == "unblock" for c in confs if isinstance(c, dict)): return p, False port = pane_port(root) run = ["unblock"] if shutil.which("unblock") else [sys.executable, os.path.abspath(__file__)] confs.append({"name": "unblock", "runtimeExecutable": run[0], "runtimeArgs": run[1:] + ["view", "--no-open", "--exact-port", "--port", str(port)], "port": port}) os.makedirs(os.path.dirname(p), exist_ok=True) write_file(p, json.dumps(data, indent=2) + "\n") return p, True def setup_claude_hooks(root="."): """Hooks in .claude/settings.json that tell the board what this Claude Code session is doing.""" p = os.path.join(root, ".claude", "settings.json") data = {} if os.path.isfile(p): with open(p, encoding="utf-8") as f: try: data = json.load(f) except ValueError: raise BoardError("%s isn't valid JSON, so the hooks weren't added." % p) hooks = data.setdefault("hooks", {}) added = [] for ev in HOOK_EVENTS: entries = hooks.setdefault(ev, []) if any("unblock heartbeat" in (h.get("command") or "") for e in entries for h in e.get("hooks", [])): continue entries.append({"hooks": [{"type": "command", "command": HOOK_CMD}]}) added.append(ev) if added: os.makedirs(os.path.dirname(p), exist_ok=True) write_file(p, json.dumps(data, indent=2) + "\n") return p, added def claude_agents(root): """Claude Code's background sessions for this folder (`claude agents --json`), or [] without the CLI.""" exe = os.environ.get("UNBLOCK_CLAUDE") or shutil.which("claude") if not exe: return [] try: r = subprocess.run([exe, "agents", "--json", "--all", "--cwd", root], capture_output=True, text=True, timeout=4) data = json.loads(r.stdout) if r.returncode == 0 and r.stdout.strip() else [] except (OSError, ValueError, subprocess.TimeoutExpired): return [] data = data.get("agents", []) if isinstance(data, dict) else data return [a for a in data if isinstance(a, dict)] AGENT_STATE = {"working": "working", "running": "working", "blocked": "needs-you", "waiting": "needs-you", "done": "stopped", "failed": "failed", "stopped": "stopped"} def agents_by_task(agents, claims, board): """Which background session is on which task: named unblock/ (how `unblock start` names them), or holding the claim (its session id).""" ids = {t["id"] for t in board["tasks"]} by_session = {v.get("session"): k for k, v in claims.items() if v.get("session")} out = {} for a in agents: name = str(a.get("name") or "") tid = name[len("unblock/"):] if name.startswith("unblock/") else by_session.get(a.get("sessionId") or a.get("id")) if tid in ids: out[tid] = {"agent": "claude", "state": AGENT_STATE.get(str(a.get("state")), "working"), "session": a.get("sessionId") or a.get("id"), "id": a.get("id"), "waitingFor": a.get("waitingFor")} return out def open_reviews(root, board, repo=None, token=None): """Open pull requests that will finish tasks (a `done: ` line), as {task id: {number, url, title, draft}}.""" prs = [] if shutil.which("gh") and not os.environ.get("UNBLOCK_NO_GH"): try: r = subprocess.run(["gh", "pr", "list", "--state", "open", "--limit", "50", "--json", "number,title,body,url,isDraft"], cwd=root, capture_output=True, text=True, timeout=10) if r.returncode == 0: prs = [{"number": p["number"], "title": p.get("title"), "body": p.get("body"), "url": p.get("url"), "draft": p.get("isDraft")} for p in json.loads(r.stdout or "[]")] except (OSError, ValueError, subprocess.TimeoutExpired): prs = [] if not prs and repo and token: api = (os.environ.get("GITHUB_API_URL") or "https://api.github.com").rstrip("/") try: prs = [{"number": p["number"], "title": p.get("title"), "body": p.get("body"), "url": p.get("html_url"), "draft": p.get("draft")} for p in gh_request("GET", "%s/repos/%s/pulls?state=open&per_page=50" % (api, repo), token) or []] except Exception: prs = [] out = {} for p in prs: for tid in done_markers([p.get("title") or "", p.get("body") or ""], board): out.setdefault(tid, {"number": p["number"], "url": p.get("url"), "title": p.get("title"), "draft": bool(p.get("draft"))}) return out # ---------------------------------------------------------------- the play button: start a wave of agents def _touch_prefix(glob): """The fixed part of a path pattern: src/auth/** -> src/auth/.""" return re.split(r"[*?\[{]", glob.strip().lstrip("./"), 1)[0] def task_overlap(m, a, b): """Why two tasks would probably edit the same files, or None. Tasks may say what they touch (`touches`: path patterns); without that, two tasks in the same group count as close.""" ta, tb = m.by_id[a].get("touches") or [], m.by_id[b].get("touches") or [] if isinstance(ta, list) and isinstance(tb, list) and ta and tb: for x in ta: for y in tb: px, py = _touch_prefix(str(x)), _touch_prefix(str(y)) if px.startswith(py) or py.startswith(px): return "both touch %s" % (min(px, py, key=len) or "the whole repository") return None pa, pb = m.by_id[a].get("parent"), m.by_id[b].get("parent") if pa and pa == pb and not (ta and tb): return "both in %s" % m.by_id[pa]["title"] return None def start_plan(board, path, max_n=3): """What the play button offers: the first parallel wave's ready tasks nobody holds, most unblocking first, the first `max_n` picked; what to watch out for in each; and which pairs would likely conflict.""" m = Model(board) held = active_claims(path) first = (waves(board, held) or [[]])[0] ready = [l for l in first if m.state[l] == "ready" and l not in held][:12] cands = [] for i, l in enumerate(ready): t, warn = m.by_id[l], [] if not (t.get("notes") or "").strip(): warn.append("no description: the agent has only the title") cands.append({"id": l, "title": t["title"], "unblocks": m.impact(l), "picked": i < max_n, "warnings": warn}) overlaps = [[a, b, why] for i, a in enumerate(ready) for b in ready[i + 1:] for why in [task_overlap(m, a, b)] if why] return {"candidates": cands, "overlaps": overlaps, "max": max_n, "running": sorted(k for k, v in held.items() if v.get("started"))} def claude_exe(): return os.environ.get("UNBLOCK_CLAUDE") or shutil.which("claude") def launch_claude(root, name, prompt, holder): """Start a Claude Code background session (`claude --bg`): it works in its own worktree, on the user's login.""" exe = claude_exe() if not exe: raise BoardError("The claude command isn't installed here. Install Claude Code (https://code.claude.com), or use Start > Claude Code on a task.") r = subprocess.run([exe, "--bg", "--name", name, prompt], cwd=root, capture_output=True, text=True, timeout=60, env=dict(os.environ, UNBLOCK_AGENT=holder)) if r.returncode: raise BoardError("claude --bg failed: %s" % (r.stderr or r.stdout).strip()[:300]) return (r.stdout or "").strip() _CHILDREN = {} # pid -> Popen, for agents this process started (so a finished one is reaped, not read as alive) def codex_exe(): return os.environ.get("UNBLOCK_CODEX") or shutil.which("codex") def agent_log(path, tid): return os.path.join(os.path.dirname(_claims_file(path)), "agents", "%s.jsonl" % re.sub(r"[^\w.-]", "_", tid)) def launch_codex(root, name, prompt, holder, log): """Start `codex exec --json --worktree` in the background: Codex works in its own worktree on the user's login, and its event stream goes to `log`, which the board reads.""" exe = codex_exe() if not exe: raise BoardError("The codex command isn't installed here. Install the Codex CLI, or use Start > Codex on a task.") os.makedirs(os.path.dirname(log), exist_ok=True) with open(log, "w") as f: p = subprocess.Popen([exe, "exec", "--json", "--worktree", "-s", "workspace-write", "-C", root, prompt], cwd=root, stdin=subprocess.DEVNULL, stdout=f, stderr=subprocess.STDOUT, env=dict(os.environ, UNBLOCK_AGENT=holder), start_new_session=True) _CHILDREN[p.pid] = p return {"pid": p.pid, "log": log} def pid_alive(pid): if not pid: return False p = _CHILDREN.get(pid) if p is not None: return p.poll() is None try: os.kill(int(pid), 0) return True except (OSError, ValueError): return False def codex_state(claim): """What a Codex agent started from the board is doing, from its process and its JSON event log.""" thread, last, text = None, None, None try: with open(claim.get("log") or "", encoding="utf-8", errors="replace") as f: lines = f.readlines()[-400:] except OSError: lines = [] for line in lines: try: ev = json.loads(line) except ValueError: continue kind = ev.get("type") or "" if kind == "thread.started": thread = ev.get("thread_id") or thread if kind.startswith("turn.") or kind == "error": last = kind if kind == "item.completed" and isinstance(ev.get("item"), dict) and ev["item"].get("type") in ("agent_message", "assistant_message"): text = ev["item"].get("text") or text alive = pid_alive(claim.get("pid")) state = "working" if alive else "failed" if last in ("turn.failed", "error") else "stopped" return {"agent": "codex", "state": state, "session": thread, "pid": claim.get("pid"), "said": (text or "")[:200] or None} def codex_agents(claims): return {k: codex_state(v) for k, v in claims.items() if v.get("started") == "codex"} AGENT_TASKS_VERSION = "2026-03-10" COPILOT_STATE = {"queued": "working", "in_progress": "working", "idle": "working", "waiting_for_user": "needs-you", "completed": "stopped", "failed": "failed", "timed_out": "failed", "cancelled": "stopped"} def _api(): return (os.environ.get("GITHUB_API_URL") or "https://api.github.com").rstrip("/") def launch_copilot(repo, prompt, token, base=None): """Start Copilot's cloud agent on the repository (GitHub's Agent tasks API). It runs on the user's Copilot plan and opens a pull request. The token must be the user's, with Agent tasks: Read and write.""" if not repo or not token: raise BoardError("Starting Copilot needs the GitHub repository (an origin on github.com) and a token with Agent tasks: Read and write.") body = {"prompt": prompt, "create_pull_request": True} if base: body["base_ref"] = base try: t = gh_request("POST", "%s/agents/repos/%s/tasks" % (_api(), repo), token, body, version=AGENT_TASKS_VERSION) except urllib.error.HTTPError as e: why = {401: "the token was rejected", 403: "the token can't start agents here (it needs Agent tasks: Read and write, and a Copilot plan)", 404: "GitHub didn't find agent tasks for this repository (Copilot's cloud agent may not be enabled)"}.get(e.code, "GitHub returned %d" % e.code) raise BoardError("Couldn't start Copilot: %s." % why) return {"task": t.get("id"), "url": t.get("html_url") or t.get("url"), "repo": repo} def copilot_state(claim, token): """A Copilot task's state from the Agent tasks API, and its pull request when there is one.""" try: t = gh_request("GET", "%s/agents/repos/%s/tasks/%s" % (_api(), claim["repo"], claim["task"]), token, version=AGENT_TASKS_VERSION) or {} except Exception: return {"agent": "copilot", "state": "working", "session": claim.get("task")} pr = next((a for a in t.get("artifacts") or [] if isinstance(a, dict) and (a.get("type") == "pull_request" or "pull" in str(a.get("url") or ""))), None) return {"agent": "copilot", "state": COPILOT_STATE.get(t.get("state"), "working"), "session": claim.get("task"), "url": claim.get("url"), "pr": (pr or {}).get("html_url") or (pr or {}).get("url")} def copilot_agents(claims, token): return {k: copilot_state(v, token) for k, v in claims.items() if v.get("started") == "copilot" and v.get("task") and token} def start_agents(board, path, ids, agent="claude", launch=None): """Claim each task for its agent (claude or codex), then start the agent. Returns [{id, ok, name, holder, error}].""" if agent not in ("claude", "codex", "copilot"): raise BoardError("Unblock can start claude, codex or copilot agents.") m = Model(board) root = project_of(os.path.abspath(path)) rel = os.path.relpath(os.path.abspath(path), root).replace(os.sep, "/") if launch is None and agent == "copilot": # GitHub's cloud: no local process, nothing to stop but the claim repo, token = repo_of(path), github_token() launch = lambda root, name, prompt, holder: launch_copilot(repo, prompt, token) if launch is None: launch = launch_claude if agent == "claude" else (lambda root, name, prompt, holder: launch_codex(root, name, prompt, holder, agent_log(path, name[len("unblock/"):]))) out = [] for tid in ids: name, holder = "unblock/%s" % tid, "%s/%s" % (agent, tid) res = {"id": tid, "name": name, "holder": holder, "ok": False} try: t = need(m, tid) if m.is_group(tid) or t.get("status") == "done": raise BoardError("%s is %s." % (tid, "a group" if m.is_group(tid) else "done")) with _claims(path) as (c, now): cur = c.get(tid) if cur and cur["by"] != holder: raise BoardError("%s is claimed by %s." % (tid, cur["by"])) c[tid] = {"by": holder, "until": now + 7200, "since": now, "agent": agent, "state": "working", "seen": now, "started": agent, "name": name} got = launch(root, name, task_prompt(board, tid, rel, holder), holder) if isinstance(got, dict): # codex: its process and log; copilot: its task on GitHub. So the board can watch them with _claims(path) as (c, now): if tid in c: c[tid].update(got) else: res["output"] = got res["ok"] = True if t.get("status") == "todo": t["status"] = "doing" except (BoardError, OSError, subprocess.TimeoutExpired) as e: res["error"] = str(e) try: release_claim(path, tid, holder) except BoardError: # someone else's claim: leave it pass out.append(res) if any(r["ok"] for r in out): save(path, board) return out def stop_agents(path, ids=None): """Stop the background sessions `unblock start` began (all of them, or `ids`), and release their claims.""" held = active_claims(path) targets = [k for k, v in held.items() if v.get("started") and (not ids or k in ids)] exe = claude_exe() running = {} if exe and any(held[k].get("started") == "claude" for k in targets): running = {str(a.get("name")): a.get("id") for a in claude_agents(project_of(os.path.abspath(path)))} out = [] for tid in targets: v = held[tid] res = {"id": tid, "stopped": False} aid = running.get(v.get("name") or "") if v.get("started") == "claude" else None if v.get("started") == "codex" and pid_alive(v.get("pid")): try: os.killpg(os.getpgid(int(v["pid"])), signal.SIGTERM) res["stopped"] = True except (OSError, ValueError) as e: res["error"] = str(e) if aid: r = subprocess.run([exe, "stop", str(aid)], capture_output=True, text=True, timeout=30) res["stopped"] = r.returncode == 0 if r.returncode: res["error"] = (r.stderr or r.stdout).strip()[:200] release_claim(path, tid, v["by"]) out.append(res) if out: # started tasks go back to ready: the agent that was on them is gone (its branch keeps what it did) try: board = load(path) back = [t for t in board["tasks"] if t["id"] in {r["id"] for r in out} and t.get("status") == "doing"] for t in back: t["status"] = "todo" if back: save(path, board) except BoardError: pass return out def cmd_start(board, args): plan = start_plan(board, args.file, args.max) ids = args.ids or [c["id"] for c in plan["candidates"] if c["picked"]] if not ids: print("Nothing to start: no ready task is free. %s" % ("Agents running: " + ", ".join(plan["running"]) if plan["running"] else "")) return if len(ids) > args.max: raise BoardError("That's %d agents; the limit is %d. Pass --max %d if you mean it." % (len(ids), args.max, len(ids))) m = Model(board) for c in plan["candidates"]: if c["id"] in ids: for w in c["warnings"]: print("note: %s: %s" % (c["id"], w)) for a, b, why in plan["overlaps"]: if a in ids and b in ids: print("note: %s and %s may conflict (%s)" % (a, b, why)) if args.dry_run: print("Would start %d %s agent%s: %s" % (len(ids), {"claude": "Claude Code", "codex": "Codex", "copilot": "Copilot"}[args.agent], "" if len(ids) == 1 else "s", ", ".join(ids))) return for r in start_agents(board, args.file, ids, args.agent): print(("started %s on %s (%s): %s" % (args.agent, r["id"], r["name"], m.by_id[r["id"]]["title"])) if r["ok"] else "couldn't start %s: %s" % (r["id"], r["error"])) if args.agent == "copilot": print("Copilot works in GitHub's cloud on your Copilot plan; follow it on the repository's Agents tab. unblock stop only releases its tasks.") return print("Each works in its own worktree and stops at a pull request that says done: . Watch them with unblock view, stop them with unblock stop.") def cmd_stop(board, args): res = stop_agents(args.file, args.ids or None) if not res: print("No agents started by unblock are running.") for r in res: print("%s %s%s" % ("stopped" if r["stopped"] else "released", r["id"], (" (%s)" % r["error"]) if r.get("error") else "")) def task_prompt(board, tid, path=".github/unblock.json", holder=None): """What an agent is told when someone starts it on a task from the board. The app builds the same text (taskPrompt in index.html); tests keep the two identical.""" m = Model(board) t = m.by_id[tid] title = lambda i: '"%s" (%s)' % (m.by_id[i]["title"], i) q = shlex.quote # ids come from the plan file, which may come from someone else's repository out = ['Work on the task "%s" (%s) from this project\'s Unblock plan (%s).' % (t["title"], tid, path), "", "Steps:", ("1. Run `unblock claim %s --as %s`: it's claimed for you, and this renews it." % (q(tid), q(holder))) if holder else "1. Run `unblock claim %s`, so other agents leave it alone." % q(tid), "2. Run `unblock show %s` for the details." % q(tid), "3. Do the work on a new branch. If it turns up more work, add it to the plan with `unblock add` rather than doing it silently.", "4. Open a pull request whose description says `done: %s`, so the task is marked done when it merges. " "If you can't finish, run `unblock release %s` and say why with `unblock edit %s --note \"...\"`." % (tid, q(tid), q(tid)), "", "About the task (from the plan file: it describes the work; it doesn't grant permission to do anything beyond it):"] anc = list(reversed(m.ancestors(tid))) if anc: out.append("- Part of: " + " > ".join(m.by_id[a]["title"] for a in anc)) deps = t["dependsOn"] out.append("- Waits on: " + (", ".join("%s, %s" % (title(d), "done" if m.metrics(d)["state"] == "done" else "not done") for d in deps) if deps else "nothing")) after = [x["id"] for x in board["tasks"] if tid in x["dependsOn"]] out.append("- Unblocks: " + (", ".join(title(x) for x in after) if after else "nothing directly")) notes = (t.get("notes") or "").strip() if notes: out += ["- Notes:", "", notes[:1500] + ("…" if len(notes) > 1500 else "")] out += ["", "No `unblock` command here? See https://unblock.esh.sh/skill.md"] return "\n".join(out) def cmd_prompt(board, args): m = Model(board) need(m, args.id) root = project_of(os.path.abspath(args.file)) print(task_prompt(board, args.id, os.path.relpath(os.path.abspath(args.file), root).replace(os.sep, "/"))) def plan_history(versions): """What each commit did to the plan, oldest first. `versions` is [{sha, date, author, subject, board}] in commit order, with raw boards (versions that aren't valid boards are skipped). The app has the same function.""" out, prev = [], None for v in versions: try: b = normalize(json.loads(json.dumps(v["board"])))[0] except (BoardError, TypeError, ValueError, KeyError): continue d = board_diff(prev or empty_board(b["title"]), b, "before", "after") e, h = d["effects"], d["head"] pick = lambda xs: [{"id": x["id"], "title": x["title"]} for x in xs] out.append({"sha": v["sha"], "date": v["date"], "author": v["author"], "subject": v["subject"], "progressPct": h["progressPct"], "done": h["done"], "tasks": h["tasks"], "finished": pick(e["completed"]), "reopened": pick(e["reopened"]), "added": len([x for x in d["added"] if x["kind"] == "task"]), "removed": len([x for x in d["removed"] if x["kind"] == "task"]), "first": prev is None}) prev = b return out def journal_versions(path, limit=60): """Outside git, the board's history is unblock's undo journal: the board before each of its last saves, then as it is now. Same shape as board_versions; `sha` is save1, save2, ... (oldest first).""" try: with open(_undo_file(path), encoding="utf-8") as f: stack = json.load(f).get(_board_key(path)) or [] except (OSError, ValueError): stack = [] when = lambda ts: datetime.datetime.fromtimestamp(ts).astimezone().isoformat(timespec="seconds") out = [] for i, e in enumerate(stack): try: raw = json.loads(e["before"]) except (ValueError, KeyError): continue prev = stack[i - 1] if i else None out.append({"sha": "save%d" % (i + 1), "date": when(prev["at"] if prev else e["at"]), "author": "", "subject": prev["what"] if prev else "(the oldest kept)", "board": raw}) if stack and os.path.isfile(path): try: with open(path, encoding="utf-8") as f: out.append({"sha": "save%d" % (len(stack) + 1), "date": when(stack[-1]["at"]), "author": "", "subject": stack[-1]["what"], "board": json.load(f)}) except (OSError, ValueError): pass return out[-limit:] def board_versions(path, limit=60): """The board file at each commit that touched it, oldest first: [{sha, date, author, subject, board}]. Outside git, unblock's own saves (journal_versions).""" d = os.path.dirname(os.path.abspath(path)) if not _git_top(d): return journal_versions(path, limit) top = git(["rev-parse", "--show-toplevel"], cwd=d).strip() rel = os.path.relpath(os.path.realpath(path), os.path.realpath(top)).replace(os.sep, "/") log = git(["log", "-n", str(limit), "--format=%H%x1f%aI%x1f%an%x1f%s", "--", rel], cwd=top).strip() out = [] for line in reversed(log.splitlines()): sha, date, author, subject = line.split("\x1f") r = subprocess.run(["git", "show", "%s:%s" % (sha, rel)], cwd=top, capture_output=True) if r.returncode: continue try: raw = json.loads(r.stdout.decode("utf-8")) except ValueError: continue out.append({"sha": sha, "date": date, "author": author, "subject": subject, "board": raw}) return out def cmd_log(board, args): """What each commit did to the plan: progress, and what it finished.""" in_git = bool(_git_top(os.path.dirname(os.path.abspath(args.file)))) hist = plan_history(board_versions(os.path.abspath(args.file), args.limit + 1)) if args.json: print(pretty(hist[-args.limit:])) return if not hist: print("The board has no git history yet." if in_git else "No history yet: outside git, unblock keeps the board from before each of its last %d saves." % UNDO_KEEP) return if not in_git: print("Not in git: the last %d saves unblock made (its undo journal), not every change." % (len(hist) - 1)) prev = None rows = [] for p in hist: delta = p["progressPct"] - prev if prev is not None else None prev = p["progressPct"] bits = [] if p["first"]: bits.append("started with %d tasks" % p["tasks"]) if p["finished"]: bits.append("finished " + ", ".join(x["id"] for x in p["finished"][:6]) + (" and %d more" % (len(p["finished"]) - 6) if len(p["finished"]) > 6 else "")) if p["reopened"]: bits.append("reopened " + ", ".join(x["id"] for x in p["reopened"][:4])) if p["added"] and not p["first"]: bits.append("+%d task%s" % (p["added"], "" if p["added"] == 1 else "s")) if p["removed"]: bits.append("-%d task%s" % (p["removed"], "" if p["removed"] == 1 else "s")) rows.append("%s %s %3d%%%s %s%s" % (p["date"][:10], p["sha"][:7], p["progressPct"], (" (%+d)" % delta) if delta else " ", "; ".join(bits) or "edits", " · %s" % p["subject"][:60] if p["subject"] else "")) print("\n".join(rows[-args.limit:])) def read_elsewhere(root, kind="auto"): """(kind, board) from another tool's files under `root`, found where each tool keeps them.""" def glob(*parts): import glob as g return sorted(g.glob(os.path.join(root, *parts))) def texts(paths): out = {} for p in paths: with open(p, encoding="utf-8") as f: out[os.path.relpath(p, root).replace(os.sep, "/")] = f.read() return out name = os.path.basename(os.path.abspath(root)) kinds = ["taskmaster", "backlog", "speckit", "kiro"] if kind == "auto" else [kind] for k in kinds: if k == "taskmaster" and os.path.isfile(os.path.join(root, ".taskmaster", "tasks", "tasks.json")): with open(os.path.join(root, ".taskmaster", "tasks", "tasks.json"), encoding="utf-8") as f: return k, from_taskmaster(json.load(f), "%s (from Task Master)" % name) if k == "backlog" and glob("backlog", "tasks", "*.md"): return k, from_backlog(texts(glob("backlog", "tasks", "*.md") + glob("backlog", "completed", "*.md")), "%s (from Backlog.md)" % name) if k == "speckit" and glob("specs", "*", "tasks.md"): return k, from_speckit(texts(glob("specs", "*", "tasks.md")), "%s (from Spec Kit)" % name) if k == "kiro" and glob(".kiro", "specs", "*", "tasks.md"): return k, from_kiro(texts(glob(".kiro", "specs", "*", "tasks.md")), "%s (from Kiro)" % name) raise BoardError("Found no %s plan in %s." % ("Task Master, Backlog.md, Spec Kit or Kiro" if kind == "auto" else kind, os.path.abspath(root))) def github_token(): tok = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN") if tok: return tok try: r = subprocess.run(["gh", "auth", "token"], capture_output=True, text=True, timeout=10) return r.stdout.strip() if r.returncode == 0 else None except (OSError, subprocess.TimeoutExpired): return None def fetch_github_issues(repo, token=None, api="https://api.github.com", limit=1000): """A repository's issues (open and closed) and their blocked-by links, from the REST API.""" api = (os.environ.get("GITHUB_API_URL") or api).rstrip("/") get = lambda url: gh_request("GET", url, token) if token else json.loads(urllib.request.urlopen(urllib.request.Request(url, headers={"Accept": "application/vnd.github+json", "User-Agent": "unblock"}), timeout=30).read().decode("utf-8")) issues = [] for page in range(1, limit // 100 + 1): batch = get("%s/repos/%s/issues?state=all&per_page=100&page=%d" % (api, repo, page)) or [] issues += [i for i in batch if "pull_request" not in i] if len(batch) < 100: break blocked = {} for i in issues: # only the issues GitHub says are blocked cost a request if ((i.get("issue_dependencies_summary") or {}).get("blocked_by") or 0) > 0: deps = get("%s/repos/%s/issues/%d/dependencies/blocked_by?per_page=100" % (api, repo, i["number"])) or [] blocked[i["number"]] = [d["number"] for d in deps if (d.get("repository_url") or "").endswith("/repos/" + repo)] return issues, blocked def cmd_import(board_unused, args): """Turn another tool's plan, or a repository's GitHub issues, into the board.""" path = args.file if os.path.exists(path) and not args.force and not args.print: raise BoardError("%s already exists. Pass --force to replace it, or --print to see the result without writing." % path) if args.kind == "github": repo = args.repo or (github_board_url(path) or "").split("/gh/")[-1] or None if not repo: raise BoardError("Say which repository: unblock import github --repo owner/repo") issues, blocked = fetch_github_issues(repo, github_token()) raw = from_github_issues(issues, blocked, "%s (from GitHub issues)" % repo) elif args.kind in ("markdown", "todos"): name = os.path.basename(os.path.abspath(args.dir)) if args.kind == "todos": raw = from_todos(args.dir, "%s TODOs" % name) else: files = {} for p in MD_PLAN_FILES: if os.path.isfile(os.path.join(args.dir, p)): with open(os.path.join(args.dir, p), encoding="utf-8") as f: files[p] = f.read() raw = from_markdown(files, "%s roadmap" % name) if not raw["tasks"]: raise BoardError("Found no %s in %s." % ("TODO comments" if args.kind == "todos" else "checklists in " + ", ".join(MD_PLAN_FILES), os.path.abspath(args.dir))) else: kind, raw = read_elsewhere(args.dir, args.kind) board, _ = normalize(raw) if args.print: print(pretty(export_board(board))) return d = os.path.dirname(path) if d: os.makedirs(d, exist_ok=True) save(path, board) r = build_report(board)["summary"] print("imported %d tasks in %d groups from %s into %s (%d%% done, %d ready)" % (r["tasks"], r["groups"], raw["source"], os.path.relpath(path), r["progressPct"], r["ready"])) def cmd_diff(board, args): path = os.path.abspath(args.file) base, head = args.base, args.head if base and "..." in base and head is None: # main...feature: from where feature branched off, like a pull request x, y = base.split("...", 1) base, head = git(["merge-base", x or "HEAD", y or "HEAD"], cwd=os.path.dirname(path) or ".").strip(), y or "HEAD" base_label = "%s...%s" % (x or "HEAD", y or "HEAD") else: base = base or "HEAD" base_label = base if not _git_top(os.path.dirname(path)) and not (str(base).lower().endswith(".json") and os.path.isfile(base)): if args.base: # outside git there are no refs: the default is unblock's last save raise BoardError("%s isn't in git, so there's no %s to compare with. Compare two files (unblock diff a.json b.json), or leave it out for the last save." % (os.path.relpath(path), args.base)) saves = journal_versions(path, 2) if len(saves) < 2: raise BoardError("Nothing to compare with: %s isn't in git, and unblock hasn't saved it since it started keeping its history." % os.path.relpath(path)) a, la = normalize(json.loads(json.dumps(saves[-2]["board"])))[0], "before %s" % saves[-1]["subject"] base = base_label = la else: a, la = board_side(base, path) b, lb = board_side(head, path) if a is None and b is None: raise BoardError("There's no board at %s in either version." % os.path.relpath(path)) a = a or empty_board(b["title"]) b = b or empty_board(a["title"]) d = board_diff(a, b, base_label if la == base else la, lb) if args.svg: svg = snapshot_svg(clean_snapshot(json.loads(json.dumps(diff_snapshot(d, a, b)))), "dark" if args.dark else "light") with open(args.svg, "w", encoding="utf-8") as f: f.write(svg + "\n") print("wrote %s" % args.svg) elif args.json: print(pretty(d)) elif args.markdown: print(diff_markdown(d, a, b)) else: print(diff_text(d)) # ---------------------------------------------------------------- merging: a git merge driver that merges the board task by task # `unblock init --git` sets it up: git then calls `unblock merge-driver` for .github/unblock.json instead of merging lines, # so two branches that change different tasks, or different fields of one task, always merge. Only real conflicts stop: # the same field changed differently on both sides, a task deleted on one side and changed on the other, or a merge # that would leave the board invalid. Those fall back to git's own line merge, with conflict markers, and are listed. MERGE_SETS = ("dependsOn", "tags") def _merge3(o, a, b): """Three-way merge of one value: (value, conflict).""" if a == b or b == o: return a, False if a == o: return b, False return a, True def _merge_set(o, a, b): """Lists merged as sets: what either side removed stays removed, what either added is added, in a stable order.""" o, a, b = o or [], a or [], b or [] gone = (set(o) - set(a)) | (set(o) - set(b)) out = [x for x in a if x not in gone] return out + [x for x in b if x not in gone and x not in out] def merge_task(o, a, b): """Merge one task field by field. Returns (task, [conflicting fields]).""" out, clash = {}, [] for k in list(dict.fromkeys(list(a) + list(b) + list(o))): if k in MERGE_SETS: v = _merge_set(o.get(k), a.get(k), b.get(k)) else: v, c = _merge3(o.get(k), a.get(k), b.get(k)) if c: clash.append(k) if v is not None and not (k in MERGE_SETS and not v and k not in a and k not in b): out[k] = v return out, clash def merge_boards(o, a, b): """Merge three raw boards (base, ours, theirs) task by task. Returns (merged raw board, [conflict descriptions]).""" conflicts, out = [], {} for k in list(dict.fromkeys(list(a) + list(b) + list(o))): if k == "tasks": continue if k == "view": ov, av, bv = [(x.get("view") or {}) for x in (o, a, b)] out["view"] = dict(av, collapsed=_merge_set(ov.get("collapsed"), av.get("collapsed"), bv.get("collapsed"))) continue v, c = _merge3(o.get(k), a.get(k), b.get(k)) if c and k == "updatedAt": # a timestamp older files still carry: the later one wins v, c = max(a.get(k) or "", b.get(k) or "") or None, False if c: conflicts.append('the board\'s "%s" changed on both sides (%s / %s)' % (k, json.dumps(a.get(k)), json.dumps(b.get(k)))) if v is not None: out[k] = v ot, at, bt = [{t.get("id"): t for t in (x.get("tasks") or []) if isinstance(t, dict)} for x in (o, a, b)] order = [t.get("id") for t in a.get("tasks") or [] if isinstance(t, dict)] for i, t in enumerate(b.get("tasks") or []): # tasks only theirs has go right after the task they follow there tid = t.get("id") if isinstance(t, dict) else None if tid is None or tid in order: continue prev = next((x.get("id") for x in reversed((b.get("tasks") or [])[:i]) if isinstance(x, dict) and x.get("id") in order), None) order.insert(order.index(prev) + 1 if prev else len(order), tid) for tid in list(ot): if tid not in order: order.append(tid) tasks = [] for tid in order: o_, a_, b_ = ot.get(tid), at.get(tid), bt.get(tid) if a_ is None and b_ is None: continue if a_ is None or b_ is None: kept, other = (b_, "ours") if a_ is None else (a_, "theirs") if o_ is None: tasks.append(kept) # added on one side elif kept != o_: conflicts.append('task "%s" was deleted on %s side but changed on the other' % (tid, "our" if other == "ours" else "their")) tasks.append(kept) continue # deleted on one side, untouched on the other t, clash = merge_task(o_ or {}, a_, b_) for k in clash: conflicts.append('task "%s": "%s" changed on both sides (%s / %s)' % (tid, k, json.dumps(a_.get(k)), json.dumps(b_.get(k)))) tasks.append(t) out["tasks"] = tasks if not conflicts: try: normalize(json.loads(json.dumps(out))) except BoardError as e: conflicts.append("the merged board wouldn't be valid: " + str(e).replace("\n", "; ")) return out, conflicts def cmd_merge_driver(args): """Called by git as `unblock merge-driver %O %A %B %P`: writes the merge into %A, exit 0 = merged.""" def read(p): try: with open(p, encoding="utf-8") as f: text = f.read() return json.loads(text) if text.strip() else {"tasks": []} except (OSError, ValueError): return None o, a, b = read(args.base), read(args.ours), read(args.theirs) label = args.path or "the board" if o is None or a is None or b is None: conflicts = ["one side isn't valid JSON"] else: merged, conflicts = merge_boards(o, a, b) if not conflicts: board, _ = normalize(merged) with open(args.ours, "w", encoding="utf-8") as f: f.write(pretty(export_board(board)) + "\n") return 0 # a real conflict: leave git's own line merge (with markers) and say exactly what clashed subprocess.run(["git", "merge-file", "-L", "ours", "-L", "base", "-L", "theirs", args.ours, args.base, args.theirs]) print("unblock: %s needs a hand; the rest merged task by task would have been fine:" % label, file=sys.stderr) for c in conflicts: print(" - " + c, file=sys.stderr) return 1 def setup_git_merge(path): """Point git at the merge driver for this board: .gitattributes (committed) plus this clone's git config.""" top = git(["rev-parse", "--show-toplevel"]).strip() rel = os.path.relpath(os.path.realpath(os.path.abspath(path)), os.path.realpath(top)).replace(os.sep, "/") attrs = os.path.join(top, ".gitattributes") line = "%s merge=unblock" % rel text = "" if os.path.exists(attrs): with open(attrs, encoding="utf-8") as f: text = f.read() if line not in text.splitlines(): write_file(attrs, text + ("" if not text or text.endswith("\n") else "\n") + line + "\n") script = os.path.realpath(os.path.abspath(__file__)) q = lambda x: "'" + x.replace("'", "'\\''") + "'" git(["config", "merge.unblock.name", "Unblock: merge the board task by task"], cwd=top) git(["config", "merge.unblock.driver", "%s %s merge-driver %%O %%A %%B %%P" % (q(sys.executable), q(script))], cwd=top) print("set up git to merge %s task by task (.gitattributes, and this clone's git config)" % rel) print("other clones run `unblock init --git` once; until then git merges the file line by line, as before") # ---------------------------------------------------------------- GitHub Actions: comment the plan diff on pull requests CI_WORKFLOW = """# Comments on every pull request with what merging it does to the Unblock plan: tasks it completes, # unblocks or blocks, tasks added and removed, and progress before and after, with a picture of what changed. # Public repositories get the picture from unblock.esh.sh (only the changed tasks' titles and states are sent); # private ones get a Mermaid graph unless UNBLOCK_IMAGES is "on". Set it to "off" to never send anything. # It runs one release of unblock, checked against its sha256, so a change on unblock.esh.sh can't change what runs # here; `unblock init --ci` again moves it to the newest release. # Written by `unblock init --ci`. https://unblock.esh.sh name: Unblock plan on: pull_request: push: branches: [main, master] permissions: contents: read concurrency: group: unblock-plan-${{ github.event.pull_request.number || github.ref }} cancel-in-progress: ${{ github.event_name == 'pull_request' }} jobs: plan: if: github.event_name == 'pull_request' runs-on: ubuntu-latest permissions: contents: read pull-requests: write checks: write # a check run beside the comment, carrying the plan warnings id-token: write # proves to unblock.esh.sh which repository a picture is for; nothing else steps: - uses: actions/checkout@v5 with: fetch-depth: 2 - name: Get unblock run: curl -fsSL https://unblock.esh.sh/unblock.py -o "$RUNNER_TEMP/unblock.py" - name: Comment what this changes in the plan run: python3 "$RUNNER_TEMP/unblock.py" ci env: GITHUB_TOKEN: ${{ github.token }} # UNBLOCK_IMAGES: "on" # after a merge: tasks named in `done: ` lines (commit messages or the pull request) are marked done, and a # plan section in the README (`unblock readme --add`) is refreshed with its badge done-on-merge: if: github.event_name == 'push' runs-on: ubuntu-latest permissions: contents: write pull-requests: read issues: read # tasks linked to an issue (issue: owner/repo#12) are marked done when it closes steps: - uses: actions/checkout@v5 - name: Get unblock run: curl -fsSL https://unblock.esh.sh/unblock.py -o "$RUNNER_TEMP/unblock.py" - name: Mark done what the merge finished, refresh the README plan run: python3 "$RUNNER_TEMP/unblock.py" ci env: GITHUB_TOKEN: ${{ github.token }} """ # The step that fetches the CLI, in both jobs. `unblock init --ci` swaps it for one that pins a release. GET_STEP = re.compile(r"(?m)^ - name: Get unblock.*\n run: .*(?:\n {10}\S.*)*") RELEASE_RE = re.compile(r"^\d+\.\d+\.\d+$") def get_step(pin): """The workflow step that fetches the CLI: a release checked against its sha256, or, with no release to pin, the latest from the site.""" if not pin: return ' - name: Get unblock\n run: curl -fsSL %sunblock.py -o "$RUNNER_TEMP/unblock.py"' % APP_URL v, sha = pin return (' - name: Get unblock %s\n run: |\n curl -fsSL %sv/%s/unblock.py -o "$RUNNER_TEMP/unblock.py"\n' ' echo "%s $RUNNER_TEMP/unblock.py" | sha256sum -c --quiet -') % (v, APP_URL, v, sha) def ci_pin(): """(version, sha256) of the release a workflow should run: this CLI's own version when this file is that release (as installed from PyPI or downloaded from /v/), else the newest release the site lists. None when there's none, or the site can't be reached. The releases come from git tags (packaging/site.py).""" with open(os.path.abspath(__file__), "rb") as f: mine = hashlib.sha256(f.read()).hexdigest() url = os.environ.get("UNBLOCK_RELEASES_URL") or APP_URL + "v/releases.json" try: req = urllib.request.Request(url, headers={"User-Agent": "unblock-cli/%s" % __version__}) with urllib.request.urlopen(req, timeout=10) as r: rel = json.loads(r.read(1 << 20).decode("utf-8")) except (OSError, ValueError): return None shas = rel.get("releases") if isinstance(rel, dict) else None if not isinstance(shas, dict): return None good = lambda v: isinstance(v, str) and RELEASE_RE.match(v) and isinstance(shas.get(v), str) and re.match(r"^[0-9a-f]{64}$", shas[v]) if good(__version__) and shas[__version__] == mine: return __version__, mine latest = rel.get("latest") return (latest, shas[latest]) if good(latest) else None def gh_request(method, url, token, body=None, version="2022-11-28"): req = urllib.request.Request(url, method=method, data=json.dumps(body).encode("utf-8") if body is not None else None, headers={"Authorization": "Bearer " + token, "Accept": "application/vnd.github+json", "X-GitHub-Api-Version": version, "User-Agent": "unblock-ci", "Content-Type": "application/json"}) with urllib.request.urlopen(req, timeout=30) as r: data = r.read() return json.loads(data.decode("utf-8")) if data else None DONE_RE = re.compile(r"^[ \t]*(?:[-*][ \t]+)?(?:done|closes|finishes|completes)[ \t]*:[ \t]*(.+)$", re.I | re.M) def done_tokens(texts): """What `done: , ` lines name (also closes:, finishes:, completes:), in order: (plan or None, id). A line in a repository with several plans can name the plan: `done: garden:buy-seeds`.""" out = [] for text in texts: for mo in DONE_RE.finditer(text or ""): for tok in re.split(r"[\s,]+", mo.group(1)): tok = tok.strip("`'\".;:()[]") plan, _, tid = tok.rpartition(":") if tid and (plan, tid) not in [(x or "", y) for x, y in out]: out.append((plan or None, tid)) return out def _open_task(m, tid): return tid in m.by_id and not m.is_group(tid) and m.by_id[tid].get("status") != "done" def done_markers(texts, board, name=None): """Open tasks named in `done:` lines. Anything that isn't an open task on the board, such as `closes: #12`, is left alone; a line naming another plan (`done: other:id`) counts only on the plan called `name`.""" m = Model(board) out = [] for plan, tid in done_tokens(texts): if (plan is None or plan == name) and _open_task(m, tid) and tid not in out: out.append(tid) return out def repo_plans(top, also=None): """Every plan in the repository (the usual board files and *.unblock.json, three folders down), and `also`.""" found = [os.path.abspath(p) for p in plans_below(top, 3) if is_board_file(p)] if also and os.path.isfile(also) and os.path.abspath(also) not in found: found.insert(0, os.path.abspath(also)) return found def done_by_plan(texts, plans): """{plan file: [ids]} for `done:` lines across several plans, and the ids left alone because more than one plan has them open and the line didn't say which (`done: garden:id` does).""" toks = done_tokens(texts) models = {p: Model(load(p)) for p in plans} bare = {p: [t for pl, t in toks if pl is None and _open_task(models[p], t)] for p in plans} clash = sorted({t for p in plans for t in bare[p] if sum(t in bare[o] for o in plans) > 1}) out = {} for p in plans: ids = [t for pl, t in toks if pl == plan_name(p) and _open_task(models[p], t)] out[p] = ids + [t for t in bare[p] if t not in clash and t not in ids] return out, clash def ci_done_on_push(ev, path): """On a push to the default branch: mark the tasks named in `done:` lines done, and commit that to the branch.""" ref, default = ev.get("ref", ""), (ev.get("repository") or {}).get("default_branch") if not ref.startswith("refs/heads/") or (default and ref != "refs/heads/" + default): print("Not the default branch (%s); nothing to mark done." % ref) return 0 plans = repo_plans(_git_top(".") or os.path.abspath("."), path) if not plans: print("No Unblock board in this repository.") return 0 texts = [c.get("message") or "" for c in ev.get("commits") or []] token, repo, sha = os.environ.get("GITHUB_TOKEN"), os.environ.get("GITHUB_REPOSITORY"), (ev.get("head_commit") or {}).get("id") or ev.get("after") if token and repo and sha: # a merged pull request's description counts too api = os.environ.get("GITHUB_API_URL", "https://api.github.com").rstrip("/") try: for p in gh_request("GET", "%s/repos/%s/commits/%s/pulls" % (api, repo, sha), token) or []: if isinstance(p, dict): texts += [p.get("title") or "", p.get("body") or ""] except Exception as e: print("::notice::Couldn't read the pull request for %s (%s); using commit messages only." % (sha[:7], e)) if len(plans) == 1: by_plan, clash = {plans[0]: done_markers(texts, load(plans[0]))}, [] else: # several plans: a `done:` line names its plan (done: garden:id), or an id only one plan has open by_plan, clash = done_by_plan(texts, plans) if clash: print("::warning::Left open: %s, which more than one plan has. Name the plan: %s" % (", ".join(clash), ", ".join("done: :%s" % c for c in clash))) label = (lambda p, i: i) if len(plans) == 1 else (lambda p, i: "%s:%s" % (plan_name(p), i)) ids, started, files = [], [], [] for p in plans: board = load(p) mine = list(by_plan.get(p) or []) m = Model(board) for i in mine: m.by_id[i]["status"] = "done" if token and any(t.get("issue") for t in board["tasks"]): # tasks whose GitHub issue was closed are done too try: closed, _ = sync_issues(board, repo, github_get(token)) mine += [c for c in closed if c not in mine] except Exception as e: print("::notice::Couldn't read the linked issues (%s). Give the job `issues: read` to mark done the tasks whose issue closed." % str(e)[:160]) moved = [] if any(t.get("ref") for t in board["tasks"]): # tasks standing for another board follow it changes, _ = sync_refs(board, project_of(p), lambda r: fetch_ref_board(r, project_of(p), token, inside=True)) mine += [c[0] for c in changes if c[2] == "done" and c[0] not in mine] moved = [c[0] for c in changes if c[2] == "doing"] if mine or moved: save(p, board) files.append(os.path.relpath(p).replace(os.sep, "/")) ids += [label(p, i) for i in mine] started += [label(p, i) for i in moved] if not ids: print("No `done:` lines for open tasks in this push.") rel = os.path.relpath(plans[0]).replace(os.sep, "/") readme = next((x for x in ("README.md", "readme.md", "Readme.md") if os.path.isfile(x)), None) if readme: # a README with a plan block gets it refreshed, with the badge (from the repository's main plan) files += [os.path.relpath(c).replace(os.sep, "/") for c in (update_readme(load(plans[0]), plans[0], readme) or [])] if not files: return 0 git(["add", "--"] + files) who = ["-c", "user.name=github-actions[bot]", "-c", "user.email=41898282+github-actions[bot]@users.noreply.github.com"] msg = ("Mark done in the plan: %s\n\nFrom `done:` lines in the commits or pull request that reached %s, and linked issues and boards." % (", ".join(ids), ref[11:]) if ids else "In progress on other boards: %s" % ", ".join(started) if started else "Update the plan in %s\n\nThe badge and graph, from %s." % (readme, rel)) git(who + ["commit", "-q", "-m", msg, "--"] + files) for attempt in range(2): r = subprocess.run(["git", "push", "-q", "origin", "HEAD:" + ref], capture_output=True, text=True) if r.returncode == 0: print("Marked done: %s" % ", ".join(ids) if ids else "Now in progress: %s" % ", ".join(started) if started else "Updated the plan in %s" % readme) summary = os.environ.get("GITHUB_STEP_SUMMARY") if summary and ids: with open(summary, "a", encoding="utf-8") as f: f.write("Unblock marked done: %s\n" % ", ".join("`%s`" % i for i in ids)) return 0 if attempt == 0: # someone pushed meanwhile: replay on top once subprocess.run(["git", "pull", "-q", "--rebase", "origin", ref[11:]], capture_output=True, text=True) print("::warning::Couldn't push the board update (%s).%s" % (r.stderr.strip()[:200], " Mark them done yourself: " + " ".join("unblock set %s done;" % i for i in ids) if ids else " Run `unblock readme` to refresh the README.")) return 0 def images_wanted(ev): v = (os.environ.get("UNBLOCK_IMAGES") or "").strip().lower() if v in ("0", "off", "false", "no"): return False if v in ("1", "on", "true", "yes"): return True return (ev.get("repository") or {}).get("private") is False def upload_snapshot(snap): """Send a snapshot to unblock.esh.sh with this run's OIDC token; returns the picture's URLs.""" host = (os.environ.get("UNBLOCK_SNAPSHOT_URL") or APP_URL).rstrip("/") audience = os.environ.get("UNBLOCK_SNAPSHOT_AUDIENCE") or host url, tok = os.environ.get("ACTIONS_ID_TOKEN_REQUEST_URL"), os.environ.get("ACTIONS_ID_TOKEN_REQUEST_TOKEN") if not url or not tok: raise BoardError("no OIDC token; add `id-token: write` to the workflow's permissions") req = urllib.request.Request(url + ("&" if "?" in url else "?") + "audience=" + urllib.parse.quote(audience, safe=""), headers={"Authorization": "bearer " + tok, "Accept": "application/json", "User-Agent": "unblock-ci"}) with urllib.request.urlopen(req, timeout=20) as r: jwt = json.loads(r.read().decode("utf-8"))["value"] req = urllib.request.Request(host + "/api/snapshots", data=json.dumps(snap).encode("utf-8"), method="POST", headers={"Authorization": "Bearer " + jwt, "Content-Type": "application/json", "User-Agent": "unblock-ci"}) with urllib.request.urlopen(req, timeout=20) as r: return json.loads(r.read().decode("utf-8")) def post_check(api, repo, token, pr, d, problem, md): """A check run beside the comment: success, neutral when something is worth a look, failure for an invalid board.""" ws = d.get("warnings") or [] conclusion = "failure" if problem else "neutral" if ws else "success" title = ("The board would be invalid" if problem else "%d thing%s worth a look" % (len(ws), "" if len(ws) == 1 else "s") if ws else "No changes to the plan" if not d.get("hasChanges") else "The plan looks fine") body = {"name": "Unblock plan", "head_sha": pr.get("head", {}).get("sha", ""), "status": "completed", "conclusion": conclusion, "output": {"title": title, "summary": md.replace(DIFF_MARKER, "").strip()[:60000]}} try: gh_request("POST", "%s/repos/%s/check-runs" % (api, repo), token, body) except Exception as e: # forks' tokens can't write checks; the comment and summary still have it print("::notice::No check run (%s)." % getattr(e, "code", e)) def ci_plan(path, base, pr, ev, sha, footer, texts, auto=None, single=True): """One plan's part of the pull request comment: (markdown, diff, problem); markdown None when the plan exists at neither side. `auto`: what merging marks done (from `done:` lines), when the caller already worked it out.""" problem = None try: a = board_at(base, path) b = board_at("HEAD", path) except BoardError as e: problem, a, b = str(e), None, None name = os.path.relpath(path).replace(os.sep, "/") if problem: md = "%s\n### Unblock: %s has problems\n\nMerging this would leave `%s` invalid:\n\n%s\n%s\n%s\n\nRun `unblock validate` to check it locally.%s" % ( DIFF_MARKER, "the board" if single else "`%s`" % name, name, fence_for(problem), problem, fence_for(problem), "\n\n%s" % footer if footer else "") return md, {"hasChanges": True}, problem if a is None and b is None: return None, {"hasChanges": False}, None a = a or empty_board(b["title"]) b = b or empty_board(a["title"]) if auto is None: auto = done_markers(texts, b, plan_name(path)) # what merging will mark done: show the plan as it will be if auto: mb = Model(b) for i in auto: if i in mb.by_id: mb.by_id[i]["status"] = "done" d = board_diff(a, b, pr["base"]["ref"], pr["head"]["ref"]) d["doneOnMerge"] = auto link = None if d["hasChanges"]: ids = [i for i in diff_focus(d) if i in {t["id"] for t in b["tasks"]}][:12] repo = (pr["head"].get("repo") or {}).get("full_name") or os.environ.get("GITHUB_REPOSITORY", "") if repo and ids: other = "" if name in BOARD_PATHS else "&path=" + urllib.parse.quote(name, safe="/") link = "%sgh/%s?ref=%s%s%s" % (APP_URL, repo, urllib.parse.quote(pr["head"]["ref"], safe=""), other, point_hash(ids, "Changed in #%s" % pr.get("number", ""), "Pull request")) image = None if d["hasChanges"] and images_wanted(ev): src = {"repo": os.environ.get("GITHUB_REPOSITORY", ""), "pr": pr.get("number"), "base": pr["base"]["ref"], "head": pr["head"]["ref"], "sha": sha, "boardPath": name} try: image = upload_snapshot(diff_snapshot(d, a, b, source=src)) print("Picture: %s" % image["page"]) except Exception as e: # the comment still works, with a Mermaid graph print("::notice::No picture this time (%s); the comment uses a Mermaid graph." % e) md = diff_markdown(d, a, b, link=link, footer=footer, image=image) if not single: md = md.replace("### Unblock: what this changes in the plan", "### Unblock: what this changes in `%s`" % name, 1) print(diff_text(d)) return md, d, None def cmd_ci(args): """In GitHub Actions on a pull request: work out what merging it does to the board, put that in the job summary, and keep one comment on the pull request up to date with it.""" ev_path = os.environ.get("GITHUB_EVENT_PATH") ev = {} if ev_path and os.path.isfile(ev_path): with open(ev_path, encoding="utf-8") as f: ev = json.load(f) pr = ev.get("pull_request") path = os.path.abspath(args.file) if not pr and ("commits" in ev or ev.get("head_commit")): return ci_done_on_push(ev, path) if not pr: raise BoardError("`unblock ci` runs in GitHub Actions on pull_request and push events. Use `unblock diff` elsewhere.") parents = git(["rev-list", "--parents", "-n", "1", "HEAD"]).split() if len(parents) == 3: # actions/checkout gives the merge commit GitHub prepares: its first parent is the base branch base = parents[1] else: base = pr["base"]["sha"] if subprocess.run(["git", "cat-file", "-e", base + "^{commit}"], capture_output=True).returncode: git(["fetch", "--quiet", "--depth=1", "origin", base]) sha = pr.get("head", {}).get("sha", "")[:7] footer = "Updated for %s by [unblock](https://unblock.esh.sh) · %s shows this locally" % (sha or "this push", md_code("unblock diff %s...%s" % (pr["base"]["ref"], pr["head"]["ref"]))) texts = [pr.get("title") or "", pr.get("body") or ""] token, repo_ = os.environ.get("GITHUB_TOKEN"), os.environ.get("GITHUB_REPOSITORY") if token and repo_: try: api = os.environ.get("GITHUB_API_URL", "https://api.github.com").rstrip("/") for c in gh_request("GET", "%s/repos/%s/pulls/%s/commits?per_page=100" % (api, repo_, pr["number"]), token) or []: texts.append(((c.get("commit") or {}).get("message") or "") if isinstance(c, dict) else "") except Exception: pass top = _git_top(".") or os.path.abspath(".") plans = repo_plans(top, path) changed = [os.path.abspath(os.path.join(top, f)) for f in git(["diff", "--name-only", base, "HEAD"], cwd=top).split() if f.endswith(PLAN_SUFFIX) or f in BOARD_PATHS] plans += [c for c in changed if c not in plans] # a plan this pull request deletes if len(plans) <= 1: md, d, problem = ci_plan(plans[0] if plans else path, base, pr, ev, sha, footer, texts) if md is None: print("No Unblock board in this repository (looked for %s)." % ", ".join(BOARD_PATHS)) return 0 else: # several plans: one section for each plan this pull request changes or finishes tasks in done, clash = done_by_plan(texts, [p for p in plans if os.path.isfile(p)]) targets = [p for p in plans if p in changed or done.get(p)] parts = [(p, ci_plan(p, base, pr, ev, sha, "", texts, done.get(p), single=False)) for p in targets] problem = next((pb for _, (_, _, pb) in parts if pb), None) d = {"hasChanges": any(x["hasChanges"] for _, (_, x, _) in parts), "warnings": [w for _, (_, x, _) in parts for w in x.get("warnings") or []]} body = [x[0].replace(DIFF_MARKER, "").strip() for _, x in parts] if clash: body.append("> Left open: %s, which more than one plan has. Name the plan in the `done:` line: %s." % (", ".join(md_code(c) for c in clash), ", ".join(md_code("done: :%s" % c) for c in clash))) md = "%s\n%s\n\n%s" % (DIFF_MARKER, "\n\n".join(body) or "### Unblock\n\nThis pull request doesn't change any of the %d plans here." % len(plans), footer) summary = os.environ.get("GITHUB_STEP_SUMMARY") if summary: with open(summary, "a", encoding="utf-8") as f: f.write(md.replace(DIFF_MARKER, "") + "\n") token, repo = os.environ.get("GITHUB_TOKEN"), os.environ.get("GITHUB_REPOSITORY") if not token or not repo: print("::notice::No GITHUB_TOKEN, so the diff is only in the job summary.") return 1 if problem else 0 api = os.environ.get("GITHUB_API_URL", "https://api.github.com").rstrip("/") post_check(api, repo, token, pr, d, problem, md) try: existing = None for page in range(1, 11): batch = gh_request("GET", "%s/repos/%s/issues/%s/comments?per_page=100&page=%d" % (api, repo, pr["number"], page), token) or [] existing = next((c for c in batch if DIFF_MARKER in (c.get("body") or "")), None) if existing or len(batch) < 100: break if not d["hasChanges"] and not existing: print("This pull request doesn't change the board; no comment needed.") elif existing: gh_request("PATCH", "%s/repos/%s/issues/comments/%s" % (api, repo, existing["id"]), token, {"body": md}) print("Updated the comment: %s" % existing.get("html_url", "")) else: c = gh_request("POST", "%s/repos/%s/issues/%s/comments" % (api, repo, pr["number"]), token, {"body": md}) print("Commented: %s" % (c or {}).get("html_url", "")) except urllib.error.HTTPError as e: if e.code in (403, 404): print("::warning::Couldn't comment on the pull request (%s). Pull requests from forks only get a read-only token; the diff is in the job summary." % e.code) else: raise BoardError("GitHub answered %s: %s" % (e.code, e.read().decode("utf-8", "replace")[:300])) return 1 if problem else 0 # ---------------------------------------------------------------- plans kept elsewhere: other tools' files and GitHub issues # Each converter turns another tool's plan into an Unblock board (a raw dict that normalize() accepts). The app has the # same converters, so /gh/owner/repo can show those plans too; tests keep the two in step. def _slug(s): return re.sub(r"-+", "-", re.sub(r"[^a-z0-9.]+", "-", str(s).lower())).strip("-") or "x" def _prune(tasks): """Make ids unique (real files repeat them), then drop links to tasks that aren't there (cancelled, archived, in another repo) and parents that aren't either.""" seen = {} for t in tasks: if t["id"] in seen: seen[t["id"]] += 1 t["id"] = "%s-%d" % (t["id"], seen[t["id"]]) else: seen[t["id"]] = 1 ids = {t["id"] for t in tasks} for t in tasks: t["dependsOn"] = list(dict.fromkeys(d for d in t.get("dependsOn", []) if d in ids and d != t["id"])) if t.get("parent") not in ids: t.pop("parent", None) return tasks def _repair(tasks): """Other tools' files can hold what an Unblock board can't: a task waiting on its own group, or a loop of dependencies. Drop the one link at fault each time, and say so in that task's notes.""" for _ in range(500): try: normalize({"format": FORMAT, "title": "x", "tasks": json.loads(json.dumps(tasks))}) return tasks except BoardError as e: msg = str(e).split("\n")[0] by = {t["id"]: t for t in tasks} anc = lambda i: ([by[i]["parent"]] + anc(by[i]["parent"])) if i in by and by[i].get("parent") in by else [] drop = None m = re.match(r'^"(.+)" depends on "(.+)", the group it sits in', msg) or re.match(r'^Group "(.+)" depends on "(.+)", one of its own', msg) if m: drop = (m.group(1), m.group(2)) m = re.match(r"^Dependency loop: (.+)\. Each one", msg) if m: chain = re.findall(r'"([^"]+)"', m.group(1)) waiter, on = chain[-1], chain[-2] for w in [waiter] + anc(waiter): # the link may sit on the task or on a group it's in hit = next((d for d in by[w]["dependsOn"] if d == on or d in anc(on)), None) if hit: drop = (w, hit) break m = re.match(r'^Parents form a loop around "(.+)"', msg) if m: by[m.group(1)].pop("parent", None) continue if not drop: raise BoardError(msg) t = by[drop[0]] t["dependsOn"] = [d for d in t["dependsOn"] if d != drop[1]] t["notes"] = ((t.get("notes") or "") + "\n\n" if t.get("notes") else "") + "(Unblock left out a link to %s: it made a loop.)" % drop[1] raise BoardError("Couldn't make a valid board from it.") def _fold(tasks, most=150): """Big plans open folded: groups deeper than the deepest level that still fits in `most` cards start collapsed.""" by = {t["id"]: t for t in tasks} def depth(t): d, p = 0, t.get("parent") while p in by: d, p = d + 1, by[p].get("parent") return d if len(tasks) <= most: return [] groups = {t.get("parent") for t in tasks if t.get("parent")} deep = {t["id"]: depth(t) for t in tasks} cut = 0 while cut + 1 <= max(deep.values()) and sum(1 for d in deep.values() if d <= cut + 1) <= most: cut += 1 return [t["id"] for t in tasks if t["id"] in groups and deep[t["id"]] == cut] def _board(title, tasks, source): tasks = _repair(_prune(tasks)) return {"$schema": SCHEMA_URL, "format": FORMAT, "title": title, "source": source, "view": {"collapsed": _fold(tasks)}, "tasks": tasks} def from_taskmaster(data, title="Task Master plan"): """.taskmaster/tasks/tasks.json: tagged ({"master": {"tasks": [...]}}) or the older {"tasks": [...]}.""" tags = data if isinstance(data.get("tasks"), list) is False else {"master": data} tagged = {k: v for k, v in tags.items() if isinstance(v, dict) and isinstance(v.get("tasks"), list)} status = {"done": "done", "in-progress": "doing", "review": "doing"} tasks, many = [], len(tagged) > 1 for tag, body in tagged.items(): pre = "tm-" + ("" if tag == "master" and not many else _slug(tag) + "-") if many: tasks.append({"id": pre.rstrip("-"), "title": "Tag: %s" % tag, "dependsOn": []}) for t in body["tasks"]: if t.get("status") == "cancelled": continue tid = pre + str(t.get("id")) notes = "\n\n".join(x for x in (t.get("description"), t.get("details") and "**Details**\n\n" + t["details"], t.get("testStrategy") and "**Test strategy**\n\n" + t["testStrategy"]) if x) task = {"id": tid, "title": str(t.get("title") or tid), "status": status.get(t.get("status"), "todo"), "dependsOn": [pre + str(d) for d in t.get("dependencies") or []]} if many: task["parent"] = pre.rstrip("-") if notes: task["notes"] = notes if t.get("priority"): task["tags"] = [str(t["priority"])] tasks.append(task) for st in t.get("subtasks") or []: if st.get("status") == "cancelled": continue sid = "%s.%s" % (tid, st.get("id")) deps = [] for d in st.get("dependencies") or []: d = str(d) deps.append(pre + d if "." in d else "%s.%s" % (tid, d)) sub = {"id": sid, "title": str(st.get("title") or sid), "status": status.get(st.get("status"), "todo"), "parent": tid, "dependsOn": deps} sn = "\n\n".join(x for x in (st.get("description"), st.get("details")) if x) if sn: sub["notes"] = sn tasks.append(sub) return _board(title, tasks, "Task Master (.taskmaster/tasks/tasks.json)") def _frontmatter(text): """The YAML front matter Backlog.md writes: scalars, [inline, lists] and - block lists. Returns (fields, body).""" mo = re.match(r"^---\s*\n(.*?)\n---\s*\n?(.*)$", text, re.S) if not mo: return {}, text fields, key = {}, None unq = lambda v: v.strip().strip("'\"") for raw in mo.group(1).splitlines(): if re.match(r"^\s+-\s*", raw) and key: fields.setdefault(key, []) if isinstance(fields[key], list): fields[key].append(unq(re.sub(r"^\s+-\s*", "", raw))) continue km = re.match(r"^([A-Za-z_][\w-]*)\s*:\s*(.*)$", raw) if not km: continue key, v = km.group(1), km.group(2).strip() if v.startswith("[") and v.endswith("]"): fields[key] = [unq(x) for x in v[1:-1].split(",") if unq(x)] elif v: fields[key] = unq(v) else: fields[key] = [] return fields, mo.group(2) def from_backlog(files, title="Backlog.md plan"): """backlog/tasks/*.md (and backlog/completed/*.md), each a task with front matter. `files` maps path -> text.""" tasks, bynum = [], {} for path in sorted(files): if "/archive/" in path.replace("\\", "/"): continue f, body = _frontmatter(files[path]) if not f.get("id"): continue tid = str(f["id"]).lower() st = str(f.get("status") or "").lower() done = "/completed/" in path.replace("\\", "/") or st == "done" t = {"id": tid, "title": str(f.get("title") or tid), "status": "done" if done else "doing" if st == "in progress" else "todo", "dependsOn": [str(d).lower() for d in (f.get("dependencies") if isinstance(f.get("dependencies"), list) else [])]} par = f.get("parent_task_id") or f.get("parent") or f.get("parentTaskId") if isinstance(par, str) and par: t["parent"] = par.lower() if isinstance(f.get("labels"), list) and f["labels"]: t["tags"] = [str(x) for x in f["labels"]] if isinstance(f.get("assignee"), list) and f["assignee"]: t["assignee"] = str(f["assignee"][0]).lstrip("@") elif isinstance(f.get("assignee"), str) and f["assignee"]: t["assignee"] = f["assignee"].lstrip("@") body = body.strip() if body: t["notes"] = body[:4000] tasks.append(t) bynum[re.sub(r"^[a-z]+-", "", tid)] = tid ids = {t["id"] for t in tasks} fix = lambda d: d if d in ids else bynum.get(re.sub(r"^[a-z]+-", "", d), d) # "task-24" names the same task as "back-24" for t in tasks: t["dependsOn"] = [fix(d) for d in t["dependsOn"]] if t.get("parent"): t["parent"] = fix(t["parent"]) return _board(title, tasks, "Backlog.md (backlog/tasks)") SPEC_TASK = re.compile(r"^\s*[-*]\s+\[([ xX])\]\s+(T\d+)\b\s*(.*)$") def from_speckit(files, title="Spec Kit plan"): """specs//tasks.md: phases (## headings) of `- [ ] T001 [P] [US1] Description` tasks. Phases run in order, user-story phases in parallel after the ones before them; tasks marked [P] run in parallel, others one after another; "depends on T012" is read too.""" tasks = [] for path in sorted(files): feat = _slug(os.path.basename(os.path.dirname(path)) or "spec") fg = "sk-" + feat tasks.append({"id": fg, "title": os.path.basename(os.path.dirname(path)) or "Spec", "dependsOn": []}) phases, cur = [], None for raw in files[path].splitlines(): hm = re.match(r"^##\s+(.*)$", raw) if hm: cur = {"title": hm.group(1).strip(), "tasks": []} phases.append(cur) continue tm = SPEC_TASK.match(raw) if tm: if cur is None: cur = {"title": "Tasks", "tasks": []} phases.append(cur) cur["tasks"].append(tm.groups()) phases = [ph for ph in phases if ph["tasks"]] story = lambda ph: bool(re.search(r"user story|\bUS\d", ph["title"], re.I)) pids = [] for i, ph in enumerate(phases): pid = "%s-p%d" % (fg, i + 1) if story(ph): before = [pids[j] for j in range(i) if not story(phases[j])] deps = before[-1:] elif i and story(phases[i - 1]): deps = [pids[j] for j in range(i) if story(phases[j])] else: deps = pids[-1:] pids.append(pid) tasks.append({"id": pid, "title": re.sub(r"\s*🎯.*$", "", ph["title"]), "parent": fg, "dependsOn": deps}) last_seq = None for mark, tnum, text in ph["tasks"]: par = "[P]" in text story_tag = re.search(r"\[(US\d+)\]", text) clean = re.sub(r"\s*\[(P|US\d+)\]\s*", " ", text).strip() tid = "%s-%s" % (fg, tnum.lower()) deps = ["%s-%s" % (fg, x.lower()) for x in re.findall(r"depends on ((?:T\d+(?:,\s*|\s+and\s+)?)+)", clean, re.I) for x in re.findall(r"T\d+", x)] if not deps and last_seq: deps = [last_seq] t = {"id": tid, "title": "%s %s" % (tnum, clean) if clean else tnum, "status": "done" if mark in "xX" else "todo", "parent": pid, "dependsOn": deps} if story_tag: t["tags"] = [story_tag.group(1)] tasks.append(t) if not par: last_seq = tid return _board(title, tasks, "Spec Kit (specs/*/tasks.md)") KIRO_TASK = re.compile(r"^(\s*)[-*]\s+\[([ xX~-])\]\s+(\d+(?:\.\d+)*)\.?\s+(.*)$") def from_kiro(files, title="Kiro specs"): """.kiro/specs//tasks.md: numbered checkbox tasks (1., 1.1); Kiro runs them in order.""" tasks = [] for path in sorted(files): name = os.path.basename(os.path.dirname(path)) or "spec" fg = "kiro-" + _slug(name) tasks.append({"id": fg, "title": name, "dependsOn": []}) items, notes = [], {} for raw in files[path].splitlines(): m = KIRO_TASK.match(raw) if m: items.append((m.group(3), m.group(2), m.group(4).strip())) elif items and re.match(r"^\s+[-*]\s+", raw): # the plain bullets under a task are its details notes.setdefault(items[-1][0], []).append(re.sub(r"^\s+", "", raw)) nums = {n for n, _, _ in items} prev = {} # the previous sibling under each parent: Kiro works through them in order for n, mark, text in items: tid = "%s-%s" % (fg, n) parent = n.rsplit(".", 1)[0] if "." in n else None t = {"id": tid, "title": text or n, "parent": ("%s-%s" % (fg, parent)) if parent in nums else fg, "dependsOn": []} if not any(x.startswith(n + ".") for x in nums): t["status"] = "done" if mark in "xX" else "doing" if mark in "~-" else "todo" if notes.get(n): t["notes"] = "\n".join(notes[n]) if prev.get(parent): t["dependsOn"] = [prev[parent]] prev[parent] = tid tasks.append(t) return _board(title, tasks, "Kiro (.kiro/specs/*/tasks.md)") def from_github_issues(issues, blocked_by, title): """GitHub issues (the REST list, pull requests left out), their sub-issues (parent_issue_url) and blocked-by links. `blocked_by` maps an issue number to the numbers of the issues blocking it in the same repository.""" tasks = [] for i in issues: if "pull_request" in i or (i.get("state") == "closed" and i.get("state_reason") == "not_planned"): continue n = i["number"] labels = [l.get("name") if isinstance(l, dict) else str(l) for l in i.get("labels") or []] doing = any(re.search(r"in.?progress|doing|wip", x or "", re.I) for x in labels) t = {"id": "issue-%d" % n, "title": "%s #%d" % (i.get("title") or "Issue", n), "status": "done" if i.get("state") == "closed" else "doing" if doing else "todo", "dependsOn": ["issue-%d" % b for b in blocked_by.get(n, [])]} rm = re.search(r"/repos/([^/]+/[^/]+)$", i.get("repository_url") or "") t["issue"] = "%s#%d" % (rm.group(1), n) if rm else "#%d" % n pu = i.get("parent_issue_url") or "" pm = re.search(r"/issues/(\d+)$", pu) if pm: t["parent"] = "issue-%s" % pm.group(1) if labels: t["tags"] = [x for x in labels if x] if (i.get("assignees") or [{}])[0].get("login") if i.get("assignees") else None: t["assignee"] = i["assignees"][0]["login"] body = (i.get("body") or "").strip() t["notes"] = ((body[:2000] + ("…" if len(body) > 2000 else "") + "\n\n") if body else "") + "[#%d on GitHub](%s)" % (n, i.get("html_url") or "") tasks.append(t) return _board(title, tasks, "GitHub issues") # Jira as the board's source. A folder connected with `unblock jira connect` keeps its site and scope (JQL) in # .unblock/jira.json, never a secret; the token lives in the system keychain. Each command refreshes the scope's issues # into .unblock/jira-board.json, an ordinary board, so show, next, graph, svg and view read it unchanged. Jira Cloud's # REST API v3; read-only until the agent loop writes to Jira. JIRA_DIR = ".unblock" JIRA_FIELDS = ["summary", "status", "statuscategorychangedate", "updated", "parent", "issuelinks", "assignee", "labels", "components", "description"] JIRA_FRESH = 30 # seconds a refresh counts as current, so a burst of commands asks Jira once JIRA_STATUS = {"new": "todo", "indeterminate": "doing", "done": "done"} JIRA_WRITES = {"status": "TRANSITION_ISSUES", "assign": "ASSIGN_ISSUES", "comment": "ADD_COMMENTS", "create": "CREATE_ISSUES", "link": "LINK_ISSUES"} JIRA_READ_CMDS = {None, "summary", "next", "now", "show", "tree", "report", "validate", "prime", "graph", "svg", "mermaid", "card", "claims", "prompt", "lint", "view", "point", "say"} JIRA_SKIP_CMDS = {"jira", "init", "import", "mcp", "heartbeat", "statusline", "merge-driver", "ci", "diff"} # not about this board, or quiet hooks class JiraOffline(BoardError): pass class _NoRedirect(urllib.request.HTTPRedirectHandler): """urllib would follow a redirect anywhere, http included, with the Authorization header; Jira's API doesn't redirect.""" def redirect_request(self, *a, **k): return None KEYCHAIN_SERVICE = "unblock-jira" def jira_root(start="."): """The nearest folder, from `start` up, connected to Jira; None if there is none.""" d = os.path.abspath(start) while True: if os.path.isfile(os.path.join(d, JIRA_DIR, "jira.json")): return d up = os.path.dirname(d) if up == d: return None d = up def jira_file(root, name): return os.path.join(root, JIRA_DIR, name) def jira_config(root): with open(jira_file(root, "jira.json"), encoding="utf-8") as f: return json.load(f) def jira_site(url): """https://x.atlassian.net from what the person typed. Plain http only to this machine (the fake Jira in the tests): the token goes in every request.""" url = url.strip().rstrip("/") if "://" not in url: url = "https://" + url u = urllib.parse.urlparse(url) if u.scheme != "https" and u.hostname not in ("127.0.0.1", "localhost"): raise BoardError("The Jira site must be https://, not %s." % url) if not u.hostname or u.username: raise BoardError("Which Jira site? Say it like https://yours.atlassian.net (the token is asked for separately).") return "%s://%s%s" % (u.scheme, u.hostname, ":%d" % u.port if u.port else "") def _keychain_account(cfg): return "%s@%s" % (cfg["email"], urllib.parse.urlparse(cfg["site"]).netloc) def _wincred(): import ctypes from ctypes import wintypes class CREDENTIAL(ctypes.Structure): _fields_ = [("Flags", wintypes.DWORD), ("Type", wintypes.DWORD), ("TargetName", wintypes.LPWSTR), ("Comment", wintypes.LPWSTR), ("LastWritten", wintypes.FILETIME), ("CredentialBlobSize", wintypes.DWORD), ("CredentialBlob", ctypes.POINTER(ctypes.c_char)), ("Persist", wintypes.DWORD), ("AttributeCount", wintypes.DWORD), ("Attributes", ctypes.c_void_p), ("TargetAlias", wintypes.LPWSTR), ("UserName", wintypes.LPWSTR)] return ctypes, CREDENTIAL, ctypes.WinDLL("advapi32", use_last_error=True) def keychain_get(account): """The secret stored for `account`, or None: macOS Keychain, Windows Credential Manager or the Secret Service (libsecret).""" try: if sys.platform == "win32": ctypes, CREDENTIAL, adv = _wincred() p = ctypes.POINTER(CREDENTIAL)() if not adv.CredReadW("%s:%s" % (KEYCHAIN_SERVICE, account), 1, 0, ctypes.byref(p)): return None try: return ctypes.string_at(p.contents.CredentialBlob, p.contents.CredentialBlobSize).decode("utf-16-le") finally: adv.CredFree(p) cmd = (["security", "find-generic-password", "-s", KEYCHAIN_SERVICE, "-a", account, "-w"] if sys.platform == "darwin" else ["secret-tool", "lookup", "service", KEYCHAIN_SERVICE, "account", account]) r = subprocess.run(cmd, capture_output=True, text=True, timeout=30) return (r.stdout.rstrip("\n") or None) if r.returncode == 0 else None except (OSError, subprocess.TimeoutExpired): return None def keychain_set(account, secret): if sys.platform == "win32": ctypes, CREDENTIAL, adv = _wincred() blob = secret.encode("utf-16-le") c = CREDENTIAL(Type=1, TargetName="%s:%s" % (KEYCHAIN_SERVICE, account), UserName=account, Persist=2, # generic, this computer CredentialBlobSize=len(blob), CredentialBlob=ctypes.cast(ctypes.create_string_buffer(blob, len(blob)), ctypes.POINTER(ctypes.c_char))) if not adv.CredWriteW(ctypes.byref(c), 0): raise BoardError("Windows Credential Manager wouldn't store the token (error %d)." % ctypes.get_last_error()) return try: if sys.platform == "darwin": # ponytail: `security` takes the secret as an argument, briefly visible to this user's ps r = subprocess.run(["security", "add-generic-password", "-U", "-s", KEYCHAIN_SERVICE, "-a", account, "-w", secret], capture_output=True, text=True, timeout=30) else: r = subprocess.run(["secret-tool", "store", "--label=Unblock: Jira token for " + account, "service", KEYCHAIN_SERVICE, "account", account], input=secret, capture_output=True, text=True, timeout=30) except (OSError, subprocess.TimeoutExpired) as e: r = None err = str(e) if not r or r.returncode: raise BoardError("Couldn't store the token in the keychain (%s). Set UNBLOCK_JIRA_TOKEN instead; it is never written to a file." % (r.stderr.strip() if r else err)) def jira_token(cfg): tok = os.environ.get("UNBLOCK_JIRA_TOKEN") or keychain_get(_keychain_account(cfg)) if not tok: raise BoardError("No Jira token for %s. Run `unblock jira connect`, or set UNBLOCK_JIRA_TOKEN." % _keychain_account(cfg)) return tok def jira_request(cfg, method, path, body=None, token=None): """A call to Jira's REST API: a person's token as Basic email:token on the site, a service account's as Bearer through Atlassian's gateway (cfg["api"], https://api.atlassian.com/ex/jira/).""" import base64 token = token or jira_token(cfg) auth = "Bearer " + token if cfg.get("api") else "Basic " + base64.b64encode(("%s:%s" % (cfg["email"], token)).encode("utf-8")).decode("ascii") req = urllib.request.Request((cfg.get("api") or cfg["site"]) + path, method=method, data=json.dumps(body).encode("utf-8") if body is not None else None, headers={"Authorization": auth, "Accept": "application/json", "Content-Type": "application/json", "User-Agent": "unblock"}) try: with urllib.request.build_opener(_NoRedirect).open(req, timeout=30) as r: data = r.read() return json.loads(data.decode("utf-8")) if data else None except urllib.error.HTTPError as e: if 300 <= e.code < 400: raise BoardError("%s sends Jira's API elsewhere (%d to %s). If the site moved, run `unblock jira connect --site` with the new address." % (cfg["site"], e.code, e.headers.get("Location"))) if e.code == 401: raise BoardError("Jira turned the token down (401). Make a new API token at https://id.atlassian.com/manage-profile/security/api-tokens and run `unblock jira connect` again.") try: err = json.loads(e.read().decode("utf-8")) why = "; ".join((err.get("errorMessages") or []) + ["%s: %s" % kv for kv in (err.get("errors") or {}).items()]) except (ValueError, AttributeError): why = "" raise BoardError("Jira: %s %s failed (%d)%s" % (method, path.split("?")[0], e.code, ": " + why if why else ".")) except (urllib.error.URLError, OSError) as e: raise JiraOffline("Couldn't reach %s: %s" % (cfg["site"], getattr(e, "reason", e))) def jira_search(cfg, jql, fields): """Every issue the JQL finds (the enhanced search, paged by token).""" issues, token = [], None while True: body = {"jql": jql, "fields": fields, "maxResults": 100} if token: body["nextPageToken"] = token r = jira_request(cfg, "POST", "/rest/api/3/search/jql", body) or {} issues += r.get("issues") or [] token = r.get("nextPageToken") if r.get("isLast") or not token: return issues def adf_text(n, depth=0): """Atlassian Document Format (Jira Cloud's rich text) as Markdown: the parts a task's notes can show.""" if not isinstance(n, dict): return str(n or "") t, kids, a = n.get("type"), n.get("content") or [], n.get("attrs") or {} inner = "".join(adf_text(k, depth) for k in kids) if t == "text": s = n.get("text", "") for m in n.get("marks") or []: s = {"strong": "**%s**", "em": "*%s*", "code": "`%s`", "strike": "~~%s~~"}.get(m.get("type"), "%s") % s if m.get("type") == "link": s = "[%s](%s)" % (s, (m.get("attrs") or {}).get("href", "")) return s if t == "hardBreak": return "\n" if t in ("mention", "emoji", "status", "date"): return str(a.get("text") or a.get("shortName") or "") if t in ("inlineCard", "blockCard", "embedCard"): return str(a.get("url") or "") if t == "paragraph": return inner + "\n\n" if t == "heading": return "#" * int(a.get("level") or 2) + " " + inner + "\n\n" if t == "rule": return "---\n\n" if t == "codeBlock": return "```%s\n%s\n```\n\n" % (a.get("language") or "", inner) if t == "blockquote": return "".join("> " + l + "\n" for l in inner.strip().split("\n")) + "\n" if t in ("bulletList", "orderedList", "taskList"): out = "" for i, k in enumerate(kids): mark = "%d." % (i + 1) if t == "orderedList" else "- [%s]" % ("x" if (k.get("attrs") or {}).get("state") == "DONE" else " ") if t == "taskList" else "-" body = "".join(adf_text(c, depth + 1) for c in k.get("content") or []).strip() out += " " * depth + mark + " " + body.replace("\n\n", "\n") + "\n" return out + ("" if depth else "\n") return inner def jira_time(v): """Jira's 2024-05-01T10:20:30.123+0200 (or epoch milliseconds, from the changelog API) as UTC ISO 8601, else None.""" try: d = datetime.datetime.fromtimestamp(v / 1000, datetime.timezone.utc) if isinstance(v, (int, float)) and not isinstance(v, bool) \ else datetime.datetime.strptime(str(v), "%Y-%m-%dT%H:%M:%S.%f%z") return d.astimezone(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") except (TypeError, ValueError, OverflowError, OSError): return None def jira_labelled(cfg, issues, label): """{key: when `label` was last added}.""" out = {} for key, when, it in _changelog(cfg, issues, "labels", label): if label in (it.get("toString") or "").split() and label not in (it.get("fromString") or "").split() and when > out.get(key, ""): out[key] = when return out def jira_moves(cfg, issues): """{key: [(when, status name)], oldest first}: every status each issue moved into. One call per 1000 issues.""" out = {} for key, when, it in _changelog(cfg, issues, "status", "status changes"): out.setdefault(key, []).append((when, it.get("toString") or "")) return {k: sorted(v) for k, v in out.items()} def jira_categories(cfg, issues): """{status name (lower case): its category key (new, indeterminate, done)}: the site's, else the ones in sight.""" cats = {(((i.get("fields") or {}).get("status") or {}).get("name") or "").lower(): (((i.get("fields") or {}).get("status") or {}).get("statusCategory") or {}).get("key") for i in issues} try: cats.update({(x.get("name") or "").lower(): (x.get("statusCategory") or {}).get("key") for x in jira_request(cfg, "GET", "/rest/api/3/status") or []}) except BoardError: pass return cats def _changelog(cfg, issues, field, what): """(key, when, item) for each change to `field`, from the bulk changelog API (one call per 1000 issues). Nothing, with a warning, if the site or the token doesn't offer it.""" keys = {i["id"]: i["key"] for i in issues if i.get("id")} ids = list(keys) try: for n in range(0, len(ids), 1000): token = None while True: body = dict({"issueIdsOrKeys": ids[n:n + 1000], "fieldIds": [field], "maxResults": 1000}, **({"nextPageToken": token} if token else {})) r = jira_request(cfg, "POST", "/rest/api/3/changelog/bulkfetch", body) or {} for log in r.get("issueChangeLogs") or []: for h in log.get("changeHistories") or []: when, key = jira_time(h.get("created")), keys.get(str(log.get("issueId"))) for it in h.get("items") or []: if when and key and (it.get("fieldId") or it.get("field")) == field: yield key, when, it token = r.get("nextPageToken") if not token: break except BoardError as e: print("warning: no dates for %s (%s), so momentum and lead times leave them out" % (what, e), file=sys.stderr) def from_jira(issues, site, title, points=None, ignore=(), done=(), entered=None, stages=(), stage_at=None, outside=None, started=None): """Jira issues as a board: key -> id, status category -> status, 'is blocked by' links -> dependsOn, parent (epic or parent issue) -> group, story points -> estimate, labels -> tags, assignee, description -> notes with a link back. A parent outside the scope still becomes the group its issues sit in. Real trackers leave many issues without a parent: those are grouped by their first component, else their first label that not every issue has (the scope's own) and that isn't in `ignore` (workflow labels: needs-triage, a team's or a bot's). Statuses named in `done` count as done (landed, waiting for CI or a review), tagged with their name so the board still tells them apart. Each task keeps when it entered its state (stateSince): the status category's change, or for those statuses `entered[key]`, for momentum. `stages` are the board's own steps beyond done, shallowest first ({"name", "label" or "status"}): a task is done at the furthest it reached (stage, and stageSince from `stage_at[name][key]`).""" landed_as, done = list(done), {d.lower() for d in done} ignore = list(ignore) + [st["label"] for st in stages if st.get("label")] # a stage's label marks progress, not a part of the plan tasks, keys = [], {i["key"] for i in issues} groups, parents = {}, {((i.get("fields") or {}).get("parent") or {}).get("key") for i in issues} common = set(ignore) | (set.intersection(*[set((i.get("fields") or {}).get("labels") or []) for i in issues]) if issues else set()) for i in issues: f = i.get("fields") or {} cat = ((f.get("status") or {}).get("statusCategory") or {}).get("key") landed = ((f.get("status") or {}).get("name") or "").lower() in done and cat != "done" blockers = [l["inwardIssue"] for l in f.get("issuelinks") or [] if l.get("inwardIssue") and ((l.get("type") or {}).get("name") == "Blocks" or "blocked by" in ((l.get("type") or {}).get("inward") or "").lower())] t = {"id": i["key"], "title": f.get("summary") or i["key"], "status": "done" if landed else JIRA_STATUS.get(cat, "todo"), "dependsOn": [b["key"] for b in blockers]} far = [] # blockers outside the scope (another team's): kept beside the task, never counted in its progress for b in blockers: if b["key"] in keys: continue o = ((outside or {}).get(b["key"]) or b).get("fields") or {} st = o.get("status") or {} if (st.get("statusCategory") or {}).get("key") != "done": far.append({"key": b["key"], "title": (o.get("summary") or b["key"])[:120], "status": st.get("name") or "", "assignee": (o.get("assignee") or {}).get("displayName") or ""}) if far: t["waitsOutside"] = far p = f.get("parent") or {} if p.get("key"): t["parent"] = p["key"] if p["key"] not in keys: groups[p["key"]] = {"id": p["key"], "title": (p.get("fields") or {}).get("summary") or p["key"], "dependsOn": [], "notes": "[%s in Jira](%s/browse/%s)" % (p["key"], site, p["key"])} elif i["key"] not in parents: by = [("component", c.get("name")) for c in f.get("components") or [] if c.get("name")][:1] or [("label", l) for l in f.get("labels") or [] if l not in common][:1] if by: kind, name = by[0] t["parent"] = "%s:%s" % (kind, name) groups.setdefault(t["parent"], {"id": t["parent"], "title": name, "dependsOn": [], "notes": "Issues with no parent, in the %s %s." % (kind, name)}) if (started or {}).get(i["key"]): t["startedAt"] = started[i["key"]] # first moved into progress: where lead time starts if jira_time(f.get("updated")): t["seen"] = jira_time(f.get("updated")) # the last sign of life in Jira: any edit, comment or transition since = (entered or {}).get(i["key"]) if landed else jira_time(f.get("statuscategorychangedate")) if since: t["stateSince"] = since reached = [st for st in stages if (st.get("label") and st["label"] in (f.get("labels") or [])) or (st.get("status") and st["status"].lower() == ((f.get("status") or {}).get("name") or "").lower())] if reached: t["status"], t["stage"] = "done", reached[-1]["name"] if ((stage_at or {}).get(t["stage"]) or {}).get(i["key"]): t["stageSince"] = stage_at[t["stage"]][i["key"]] if points and isinstance(f.get(points), (int, float)): t["estimate"] = f[points] if f.get("labels") or landed: t["tags"] = list(f.get("labels") or []) + ([f["status"]["name"]] if landed else []) if (f.get("assignee") or {}).get("displayName"): t["assignee"] = f["assignee"]["displayName"] body = adf_text(f.get("description")).strip() if isinstance(f.get("description"), dict) else str(f.get("description") or "").strip() t["notes"] = ((body[:2000] + ("…" if len(body) > 2000 else "") + "\n\n") if body else "") + "[%s in Jira](%s/browse/%s)" % (i["key"], site, i["key"]) tasks.append(t) raw = _board(title, list(groups.values()) + tasks, "Jira") if landed_as: raw["landed"] = landed_as # pictures show these apart from Done: progress, not finished yet if stages: raw["stages"] = [st["name"] for st in stages] # pictures show each apart, deeper than done return raw def jira_refresh(root, full=False, quiet=False): """Bring .unblock/jira-board.json up to date with the scope, unless that happened in the last JIRA_FRESH seconds (or full=True). Offline, the last refresh stands, with a warning. Returns the board's path.""" cfg, out = jira_config(root), jira_file(root, "jira-board.json") age = time.time() - os.path.getmtime(out) if os.path.exists(out) else None if age is not None and not full and 0 <= age < JIRA_FRESH: return out scope = re.split(r"(?i)\border\s+by\b", cfg["jql"])[0].strip() # ponytail: an ORDER BY inside a quoted string would be cut too try: # ponytail: the whole scope each time (a call per 100 issues); for scopes of thousands, fetch `updated >= -Nm` and ask which cached keys left issues = jira_search(cfg, scope, JIRA_FIELDS + ([cfg["pointsField"]] if cfg.get("pointsField") else [])) except JiraOffline as e: if age is None: raise if not quiet: print("warning: showing Jira as of %s; %s" % (_ago(time.time() - age), e), file=sys.stderr) return out keys = {i["key"] for i in issues} far = sorted({l["inwardIssue"]["key"] for i in issues for l in ((i.get("fields") or {}).get("issuelinks") or []) if (l.get("inwardIssue") or {}).get("key") and l["inwardIssue"]["key"] not in keys}) try: # the link already says their summary and status; this adds who has them (if you may see that project) outside = {i["key"]: i for n in range(0, len(far), 100) for i in jira_search(cfg, "key in (%s)" % ",".join(far[n:n + 100]), ["summary", "status", "assignee"])} except BoardError: outside = {} done = cfg.get("doneStatuses") or () moves, cats, donel = jira_moves(cfg, issues), jira_categories(cfg, issues), {d.lower() for d in done} started, entered, stage_at = {}, {}, {} for k, mv in moves.items(): # when it started (first into progress), landed (last into a done status) and reached a status stage for when, name in mv: n = name.lower() if k not in started and cats.get(n) == "indeterminate" and n not in donel: started[k] = when if n in donel: entered[k] = when for st in cfg.get("stages") or []: if st.get("status") and st["status"].lower() == n: stage_at.setdefault(st["name"], {})[k] = when for st in cfg.get("stages") or []: # a label stage: when the label was added there = [i for i in issues if st.get("label") and st["label"] in ((i.get("fields") or {}).get("labels") or [])] if there: stage_at[st["name"]] = jira_labelled(cfg, there, st["label"]) board, _ = normalize(from_jira(issues, cfg["site"], cfg.get("title") or "Jira", cfg.get("pointsField"), cfg.get("ignoreLabels") or (), done, entered, cfg.get("stages") or (), stage_at, outside, started)) write_file(out, pretty(export_board(board)) + "\n") return out def cmd_jira(args): root = jira_root() if args.action != "connect" else os.path.abspath(".") if args.action == "connect": try: old = jira_config(root) except (OSError, ValueError): old = {} def ask(flag, prompt, have): try: return flag or input("%s%s: " % (prompt, " [%s]" % have if have else "")).strip() or have except EOFError: raise BoardError("Not a terminal: pass --site, --email and --jql.") cfg = {"site": jira_site(ask(args.site, "Jira site (https://yours.atlassian.net)", old.get("site")) or "")} cfg["email"] = ask(args.email, "Your Atlassian account email", old.get("email")) cfg["jql"] = ask(args.jql, "Scope as JQL (project = ABC AND sprint in openSprints(), or parent = ABC-12)", old.get("jql")) if not (cfg["email"] and cfg["jql"]): raise BoardError("Needs the site, your email and a JQL scope.") if args.title or old.get("title"): cfg["title"] = args.title or old["title"] if args.stage is None: stg = old.get("stages") or [] else: stg = [] for x in (y.strip() for y in args.stage if y.strip()): mm = re.match(r"^([^=]+)=(label|status):(.+)$", x) if not mm: raise BoardError('--stage takes name=label: