taskops-cli 0.2.0__py3-none-any.whl

taskops/engine/wire.py

@@ -0,0 +1,92 @@
+"""The EPHEMERAL channel: things a watcher wants to see, that nobody should store.
+
+Same shape as the event bus and deliberately a different object. `BUS` carries
+`Event`s, and everything downstream of it — the cursor read, the export, the commit —
+treats what it sees as a fact worth keeping. A narration delta is not that: it is
+one of thousands of prose fragments per report, useful for the two minutes somebody
+is watching the model write and worthless afterwards.
+
+Publishing it here rather than there is what keeps `events.jsonl` readable as a diff.
+The FILE is the durable copy; this is the window.
+
+In-process only, like the bus, and for once that is not a limitation: the digest runs
+inside the studio's own `ThreadingHTTPServer`, so the thread that publishes and the
+thread parked in the live feed are the same process by construction.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Callable, Generic, TypeVar
+
+from ..contracts import WireMessage
+
+__all__ = ["Broadcast", "WIRE", "is_wire"]
+
+T = TypeVar("T")
+
+
+class Broadcast(Generic[T]):
+    """Publish/subscribe over a list, with a lock and no queue.
+
+    Synchronous dispatch: a listener runs on the publisher's thread, which keeps a
+    dropped message impossible for in-process subscribers and puts the cost of a slow
+    listener where it can be seen. Every listener here does one thing — hand the item
+    to its own outbound queue — which is the shape this requires.
+
+    `subscribe` returns the way to UNDO itself rather than exposing a `remove`: a
+    caller cannot hold a subscription it has no handle to, and a websocket that closes
+    cannot forget which listener was its own.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._listeners: list[Callable[[T], None]] = []
+
+    def subscribe(self, listener: Callable[[T], None]) -> Callable[[], None]:
+        with self._lock:
+            self._listeners.append(listener)
+
+        def cancel() -> None:
+            with self._lock:
+                if listener in self._listeners:
+                    self._listeners.remove(listener)
+
+        return cancel
+
+    def publish(self, item: T) -> None:
+        """Hand it to every listener. One that raises does not stop the rest.
+
+        A subscriber is a UI connection, and a browser that vanished mid-write must not
+        be able to abort the work that was publishing to it.
+        """
+        with self._lock:
+            listeners = tuple(self._listeners)
+        for listener in listeners:
+            try:
+                listener(item)
+            except Exception:                    # noqa: BLE001 — a UI must not break a write
+                continue
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._listeners)
+
+
+WIRE: Broadcast[WireMessage] = Broadcast()
+"""The process-wide ephemeral channel. A module-level singleton for the same reason
+`BUS` is: threading it through every use case to serve one optional subscriber, which
+is always the same object — whatever is streaming to browsers."""
+
+
+def is_wire(item: object) -> bool:
+    """Whether a thing off the feed is an ephemeral frame rather than an `Event`.
+
+    Structural, because both are plain dicts on the wire and the feed yields them down
+    one channel. `label` and `text` together are what an `Event` never has — it carries
+    `id`, `task` and `body` — so this cannot mistake one for the other.
+
+    It lives in the engine rather than in `contracts`, where the types are, because
+    layer 1 holds no logic at all; transports reach it through `usecases`.
+    """
+    return isinstance(item, dict) and "label" in item and "text" in item

taskops/engine/worker.py

@@ -0,0 +1,115 @@
+"""What to launch for one card, and what to tell it. The piece that makes a fleet real.
+
+Everything else in taskops coordinates agents somebody else started. This starts them — the difference
+between "a hundred agents could work in parallel" and a human opening a hundred terminals.
+
+The mechanics of getting a process running live in `_process`; what is decided here is the command,
+the tools it may use, the identity it runs as, and the prompt.
+
+**`$TASKOPS_ROOT` is the load-bearing line.** A worker runs in a `git worktree`, which has no
+`.taskops/` of its own — so without it a worker would resolve a fresh empty project inside its own
+directory and coordinate with nobody. One board, N working trees.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..contracts import Task
+from ._briefs import brief_for, prompt_for
+from ._process import make_worktree, spawn
+from .identity import ENV_ACTOR
+from .scheduler import branch_for
+
+__all__ = ["Launched", "launch", "prepare", "worktree_for", "brief_for", "prompt_for",
+           "WORKERS_DIR", "TREES_DIR", "TOOLS", "DROPPED_ENV"]
+
+DROPPED_ENV = ("ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_BASE_URL")
+"""API credentials the worker does NOT inherit. The money rule, stated as a constant.
+
+The `claude` CLI prefers an exported key over the logged-in subscription, so a developer who has
+one in their shell was silently billing every dispatched worker per token — while the plan they
+already pay for sat unused. A background agent nobody is watching must not be able to spend money
+the caller did not choose to spend, and the subscription login is the default everybody expects.
+
+`ANTHROPIC_BASE_URL` goes with them: pointing a worker at a proxy or a gateway is the same class of
+surprise, decided by whoever exported a variable years ago rather than by whoever typed the command.
+`taskops run --use-api-key` is the way to ask for the other mode, out loud."""
+
+WORKERS_DIR = ".taskops/workers"
+"""Where a worker's log goes. Under `.taskops/` so one gitignore rule covers it."""
+
+TREES_DIR = ".taskops/trees"
+"""Where the worktrees go. INSIDE the repository but gitignored, which is deliberate: next to the
+project they are easy to find and easy to delete, and somewhere under /tmp an interrupted worker's
+uncommitted work disappears on the next reboot."""
+
+TOOLS = ("Read", "Write", "Edit", "Bash", "Glob", "Grep", "TodoWrite", "mcp__taskops")
+"""What a dispatched worker may use. An ALLOWlist, so a new tool is unavailable until somebody adds
+it here — the right direction for a process nobody is watching.
+
+`mcp__taskops` is the whole point: a worker that cannot call taskops cannot claim, comment or close.
+No `WebFetch` and no `WebSearch` — a background agent reaching the network is a decision for whoever
+dispatches it, not a default.
+"""
+
+
+class Launched:
+    """A worker that was started, and where to look at it."""
+
+    def __init__(self, *, actor: str, task: str, pid: int, tree: Path, log: Path,
+                 branch: str, brief: str = "") -> None:
+        self.actor = actor
+        self.task = task
+        self.pid = pid
+        """0 when no process was started — the default, where the caller spawns a sub-agent."""
+
+        self.tree = tree
+        self.log = log
+        self.branch = branch
+        self.brief = brief
+        """The prompt to hand a sub-agent, verbatim. Empty for a spawned worker, which got it as an
+        argument instead."""
+
+
+def worktree_for(root: Path, task: Task) -> Path:
+    return root / TREES_DIR / task["id"]
+
+
+def prepare(root: Path, task: Task, *, actor: str) -> Launched:
+    """Make the worktree and write the brief. Starts NO process.
+
+    The default half of dispatch: the caller passes `.brief` to its own sub-agent tool, so the worker
+    runs on the session's existing subscription rather than opening a new billed one.
+    """
+    tree = worktree_for(root, task)
+    make_worktree(root, tree, branch_for(task))
+    return Launched(actor=actor, task=task["id"], pid=0, tree=tree, log=Path(""),
+                    branch=branch_for(task), brief=brief_for(root, task, actor, tree))
+
+
+def launch(root: Path, task: Task, *, actor: str, model: str = "",
+           use_api_key: bool = False) -> Launched:
+    """Start a headless Claude Code on its own worktree. Returns immediately.
+
+    A worktree that cannot be made is NOT fatal — a repository with no commits has no HEAD to branch
+    from — and the worker runs in the main checkout instead. That is fine for one worker and wrong for
+    several, which is why `dispatch` is the thing that decides whether to allow it.
+
+    `use_api_key` keeps `DROPPED_ENV` in the child's environment: the worker then bills per token
+    instead of using the subscription. Default OFF, and no MCP tool can turn it on.
+    """
+    tree = worktree_for(root, task)
+    branch = branch_for(task)
+    usable = make_worktree(root, tree, branch)
+    log = root / WORKERS_DIR / f"{task['id']}.log"
+    command = ["claude", "-p", prompt_for(task, actor),
+               "--permission-mode", "acceptEdits",
+               "--allowedTools", ",".join(TOOLS)]
+    if model:
+        command += ["--model", model]
+    pid = spawn(command, cwd=tree if usable else root, log=log,
+                env={"TASKOPS_ROOT": str(root), ENV_ACTOR: actor},
+                drop=() if use_api_key else DROPPED_ENV)
+    return Launched(actor=actor, task=task["id"], pid=pid, tree=tree, log=log,
+                    branch=branch, brief="")

taskops/render/__init__.py

@@ -0,0 +1,40 @@
+"""Layer 4 — a contract in, a string out. No I/O, ever.
+
+`tests/architecture` enforces the purity: nothing here may import storage, engine,
+usecases, sqlite3 or subprocess. That is what lets one renderer serve the CLI, the MCP
+reply and the web UI's markdown export, and it is why a rendering bug is reproducible from
+a literal dict.
+
+Split by AUDIENCE rather than by data type — the board (state), results (what an action
+did), reports (a time window), task and inbox (what an agent reads to work), session (what
+a hook injects). Each one answers a different question, so each one orders its output
+differently.
+"""
+
+from __future__ import annotations
+
+from .ansi import Ink
+from .board import render_board
+from .day import render_day
+from .dispatch import render_dispatch
+from .inbox import render_inbox
+from .log import render_log
+from .recover import render_recover
+from .report import NARRATION, PENDING, is_pending, narrated, render_report
+from .reports import render_fleet, render_standup
+from .results import (
+    render_edit,
+    render_next,
+    render_plan,
+    render_search,
+    render_update,
+)
+from .session import render_brief, render_verdict
+from .task import render_claim, render_view
+from .tasklist import render_tasklist
+
+__all__ = ["render_view", "render_claim", "render_inbox", "render_board",
+           "render_standup", "render_fleet", "render_plan", "render_next",
+           "render_update", "render_search", "render_edit", "render_dispatch", "render_brief",
+           "render_verdict", "render_recover", "render_log", "render_day",
+           "render_tasklist", "render_report", "narrated", "is_pending", "NARRATION", "PENDING", "Ink"]

taskops/render/_closed_days.py

@@ -0,0 +1,64 @@
+"""The `## Cerrado` section — flat for one day, grouped BY DAY for anything wider.
+
+Split from `day` because the grouping is the only thing a month-long report changes, and the
+module that decides the ORDER of a dossier should not grow a second concern the day somebody
+asks for a quarter.
+
+A hundred cards under one heading is a wall nobody scrolls. Under a heading per day, newest
+first, the same hundred cards answer "what happened the week of the 22nd" by eye — which is
+the question a range report exists for.
+"""
+
+from __future__ import annotations
+
+import time
+
+from ..contracts import ClosedCard, Event, PeriodReport
+from ._dossier import card_block
+from ._verbatim import Detail
+
+__all__ = ["closed_section"]
+
+
+def closed_section(day: PeriodReport, detail: Detail = "brief") -> list[str]:
+    """The heading, the cards, and — when the cap cut some — how many are missing."""
+    one_day = day["from_date"] == day["to_date"]
+    if not day["closed"]:
+        nothing = "Nothing closed on this day." if one_day else "Nothing closed in this window."
+        return ["## Cerrado", "", nothing, *_dropped(day), ""]
+    count = len(day["closed"])
+    body = (_flat(day["closed"], day["conversations"], detail) if one_day
+            else _by_day(day["closed"], day["conversations"], detail))
+    return [f"## Cerrado ({count})", "", body, *_dropped(day), ""]
+
+
+def _dropped(day: PeriodReport) -> list[str]:
+    """Never a silent truncation. The same rule the activity view follows: a report that shows
+    200 of 400 cards without saying so is worse than one that shows none, because the reader
+    has no way to know the number they are about to quote is short."""
+    if not day["dropped"]:
+        return []
+    return ["", f"_{day['dropped']} more card(s) closed in this window and are not shown — "
+                f"narrow the range to read them._"]
+
+
+def _flat(cards: list[ClosedCard], said: list[Event], detail: Detail) -> str:
+    """One day: no day headings. A `## 2026-07-28` under a `# 2026-07-28` title is noise, and
+    it is what keeps a single day's report byte-identical to what it always was."""
+    return "\n\n".join("\n".join(card_block(card, said, detail)) for card in cards)
+
+
+def _by_day(cards: list[ClosedCard], said: list[Event], detail: Detail) -> str:
+    """Newest day first, with its own count. The cards inside a day keep the log's order —
+    oldest close first — so a day still reads the way the day happened."""
+    days: dict[str, list[ClosedCard]] = {}
+    for card in cards:
+        days.setdefault(_date_of(card["done_ts"]), []).append(card)
+    return "\n\n".join(f"### {date} ({len(group)})\n\n" + _flat(group, said, detail)
+                       for date, group in sorted(days.items(), reverse=True))
+
+
+def _date_of(ts: float) -> str:
+    """The LOCAL date a close landed on — the same calendar the window was cut on, so a card
+    closed at 23:50 heads the day its reader worked, not the next one in UTC."""
+    return time.strftime("%Y-%m-%d", time.localtime(ts))

taskops/render/_dossier.py

@@ -0,0 +1,68 @@
+"""One closed card, as the day's dossier prints it.
+
+Split from `day` for the same reason `_sections` is split from `task`: that module decides the
+ORDER of the report — which is its whole design, since a reader stops early — and this one
+decides the CONTENT of the block that keeps growing.
+
+TWO DENSITIES, ONE RENDERER. `detail="brief"` is what a terminal has always printed; `"full"`
+is what `--write` puts on disk, and it adds the card's spec, every comment whole, and every
+file of every commit. A second renderer for the file would drift from this one within a week,
+and then a committed report and a printed one would disagree about what happened.
+"""
+
+from __future__ import annotations
+
+from ..contracts import ClosedCard, CommitStat, Event
+from ._text import STATUS_MARK, span, truncate
+from ._verbatim import Detail, said_block, spec_block
+
+__all__ = ["card_block"]
+
+BRIEF_FILES = 4
+"""Files named per commit in the terminal. `full` names them all: a written report is where
+somebody looks up which files a card touched, and `+9 more` is exactly the answer they came
+for being withheld."""
+
+
+def card_block(card: ClosedCard, conversations: list[Event],
+               detail: Detail = "brief") -> list[str]:
+    """The card, who closed it, how long it was held, what it shipped, and what was said.
+
+    The duration is claim -> done and is printed even when it is minutes, because a card
+    closed four minutes after being claimed is the single most useful thing this report can
+    surface: it is either a trivial fix or an agent that closed something it never did.
+    """
+    task = card["task"]
+    held = span(max(0.0, card["done_ts"] - card["claimed_ts"]))
+    mine = [e for e in conversations if e["task"] == task["id"]]
+    lines = [f"{STATUS_MARK['done']} **{task['id']}** — {truncate(task['title'], 70)}",
+             f"  {card['actor']} · held {held} · "
+             f"{len(card['commits'])} commit(s){_weight(card['commits'])}"]
+    lines += spec_block(task, detail)
+    lines += [f"  {line}" for commit in card["commits"] for line in _commit(commit, detail)]
+    return lines + said_block(mine, detail)
+
+
+def _weight(commits: list[CommitStat]) -> str:
+    """The card's total diff, or "" when git had nothing to say.
+
+    Suppressed rather than printed as `+0 -0`: zeros here mean "git could not answer", and a
+    card that really did ship nothing is already visible as zero commits.
+    """
+    adds = sum(c["additions"] for c in commits)
+    dels = sum(c["deletions"] for c in commits)
+    return f" · +{adds} -{dels}" if adds or dels else ""
+
+
+def _commit(commit: CommitStat, detail: Detail) -> list[str]:
+    """Sha, subject, size, then the files — the same shape `_sections.commits_section` uses,
+    so a commit reads identically on a card and in a day's report."""
+    head = (f"`{commit['sha'][:12]}` {commit['subject'] or '(no subject)'} "
+            f"(+{commit['additions']} -{commit['deletions']})")
+    files = commit["files"]
+    if not files:
+        return [head]
+    if detail == "full":
+        return [head, "  " + ", ".join(files)]
+    extra = "" if len(files) <= BRIEF_FILES else f" +{len(files) - BRIEF_FILES} more"
+    return [head, f"  {', '.join(files[:BRIEF_FILES])}{extra}"]

taskops/render/_opened.py

@@ -0,0 +1,64 @@
+"""The `## Abierto` section — what this window PLANNED, and what it is waiting on.
+
+The section that did not exist. A window whose whole content was four specs and a dependency
+chain printed `0 closed · 0 in flight · 0 blocked` and three empty headings, because nothing
+rendered `backlog` or `ready`. Everything below is about making that window legible.
+
+The DAG is the point, not decoration. On a planning day the only questions worth answering are
+"which of these can somebody start right now" and "what is waiting on what", and a list of
+titles answers neither. So every card says either that it is ready, or exactly what it waits
+for — and, in the written rendering, what was ASKED, quoted whole.
+"""
+
+from __future__ import annotations
+
+from ..contracts import OpenedCard, PeriodReport, Task
+from ._text import STATUS_MARK, bullet, truncate
+from ._verbatim import Detail, spec_block
+
+__all__ = ["opened_section", "moving_section"]
+
+READY = "listo para empezar"
+"""What an empty `waiting_on` is printed as. Saying it OUT LOUD rather than leaving the line
+off: a card with no dependency line and a card whose dependencies nobody computed look
+identical, and "what can I pick up" is the question this section exists to answer."""
+
+
+def opened_section(day: PeriodReport, detail: Detail = "brief") -> list[str]:
+    """Cards created in this window, with their edges. Absent when the window created none."""
+    if not day["opened"]:
+        return []
+    blocks = ["\n".join(_card(card, detail)) for card in day["opened"]]
+    return [f"## Abierto ({len(blocks)})", "", "\n\n".join(blocks), ""]
+
+
+def _card(card: OpenedCard, detail: Detail) -> list[str]:
+    task = card["task"]
+    waits = f"  espera a: {', '.join(card['waiting_on'])}" if card["waiting_on"] else f"  {READY}"
+    lines = [f"{STATUS_MARK[task['status']]} **{task['id']}** — {truncate(task['title'], 70)}",
+             f"  {task['status']} · priority {task['priority']}{_tags(task)}", waits]
+    if card["blocking"]:
+        lines.append(f"  bloquea a: {', '.join(card['blocking'])}")
+    return lines + spec_block(task, detail)
+
+
+def _tags(task: Task) -> str:
+    """Labels and files, when there are any. The files are what an agent picking the card up
+    collides on, so they belong beside it rather than one `ask` away."""
+    parts = [", ".join(task["labels"]), ", ".join(task["files"])]
+    return "".join(f" · {part}" for part in parts if part)
+
+
+def moving_section(day: PeriodReport) -> list[str]:
+    """Every OPEN card the window touched and did not create, marked by status.
+
+    One section and not three, ordered blocked -> working -> unstarted: they are all "open,
+    not new", the glyph already says which, and the order puts the row that needs a human at
+    the top. `waiting` is the half that used to be dropped on the floor.
+    """
+    rows = day["blocked"] + day["in_flight"] + day["waiting"]
+    if not rows:
+        return []
+    return ["## Sigue abierto", "",
+            bullet([f"{STATUS_MARK[t['status']]} {t['id']} — {truncate(t['title'], 70)}"
+                    for t in rows]), ""]

taskops/render/_sections.py

@@ -0,0 +1,51 @@
+"""The sections a task view is built from: the thread and the commits.
+
+Split from `task` because that module decides the ORDER — which is its whole design, since an agent
+reads top-down and may stop early — and these decide the CONTENT of two blocks that keep growing.
+"""
+
+from __future__ import annotations
+
+from ..contracts import Event, TaskView
+from ._text import ago
+
+__all__ = ["thread_section", "commits_section"]
+
+
+def thread_section(thread: list[Event]) -> list[str]:
+    if not thread:
+        return []
+    lines = [f"**{e['actor']}** ({ago(e['ts'])}): {e['body'].get('text', '')}"
+             for e in thread]
+    return ["### Thread", "", "\n\n".join(lines), ""]
+
+
+def commits_section(view: TaskView) -> list[str]:
+    """Sha, subject, and the files each commit touched.
+
+    The subject is the point. This printed bare twelve-character hashes for a while, which made a
+    finished card look like it had recorded nothing — while the `commit` event underneath had carried
+    the subject and the file list the whole time. The data was recorded, stored and replicated, and
+    then dropped one layer before anybody could read it.
+
+    Short shas still: the full forty characters is noise nobody reads, and anybody following one up
+    pastes it into git, where twelve is unambiguous.
+    """
+    if not view["commits"]:
+        return []
+    lines: list[str] = []
+    for commit in view["commits"]:
+        lines.append(f"`{commit['sha'][:12]}` {commit['subject'] or '(no subject)'}")
+        if commit["files"]:
+            lines.append(f"  {_files(commit['files'])}")
+    return [f"### Commits ({len(view['commits'])})", "", "\n".join(lines), ""]
+
+
+def _files(files: list[str]) -> str:
+    """The paths, truncated by COUNT rather than by characters.
+
+    A commit that touched forty files would push the rest of the card off the screen, and the first
+    few plus a count is what a reader actually uses.
+    """
+    shown = ", ".join(files[:4])
+    return shown if len(files) <= 4 else f"{shown} +{len(files) - 4} more"

taskops/render/_tasklist.py

@@ -0,0 +1,72 @@
+"""The row, the cap and the summary of `taskops tasks`. Pure, like the rest of `render/`.
+
+Split out of `tasklist.py` for the file budget, and the seam is the honest one: that module
+decides WHICH cards a reader is asking for, this one decides what one of them looks like on
+a line and how a long list ends.
+"""
+
+from __future__ import annotations
+
+from .._types import OPEN_STATUSES
+from ..contracts import Board, Card
+from ._text import STATUS_MARK, ago, truncate
+
+__all__ = ["CAP", "lines", "capped", "summary"]
+
+CAP = 10
+"""How many rows of one group get printed before the rest become a count.
+
+Closed cards accumulate for the life of a project, so an uncapped list would be read only
+as far as the first screen anyway — and a reader who scrolls past forty finished cards to
+reach the summary stops opening the command. Ten is a screen; `+N more` says the rest are
+there, which is the part an empty tail would not.
+"""
+
+
+def lines(board: Board, statuses: frozenset[str], *, dated: bool = False) -> list[str]:
+    """One line per card in `statuses`, newest-updated first when `dated`.
+
+    Open cards keep the board's own order (priority, as the columns were built), because a
+    list you are about to pick from is ordered by what to do next. Closed cards have no next,
+    so they are ordered by when they stopped moving — which is what "what was worked on" asks.
+    """
+    cards = [(card, column["status"]) for column in board["columns"]
+             if column["status"] in statuses for card in column["cards"]]
+    if dated:
+        cards.sort(key=lambda pair: pair[0]["task"]["updated"], reverse=True)
+    return [_line(card, status, dated=dated) for card, status in cards]
+
+
+def _line(card: Card, status: str, *, dated: bool = False) -> str:
+    """`◐ tk-4f2a9c  claimed      Regroup the CLI              ← agent:berna/v21`
+
+    Padded rather than tabulated: a markdown table costs three characters of framing per
+    column and this view exists to be compact. The holder is suffixed with an arrow instead
+    of a column of its own, because most rows have none and a mostly-empty column is a
+    column of noise. A closed card has no holder and trades that suffix for its age, which
+    is the only thing left that distinguishes yesterday's work from last quarter's.
+    """
+    who = card["lease"]["actor"] if card["lease"] else ""
+    tail = f"  {ago(card['task']['updated'])}" if dated else (f"  ← {who}" if who else "")
+    return (f"{STATUS_MARK.get(status, '?')} {card['task']['id']}  {status:<12}"
+            f"{truncate(card['task']['title'], 52)}{tail}")
+
+
+def capped(rows: list[str]) -> list[str]:
+    """At most `CAP` rows, then a line saying how many were left out."""
+    if len(rows) <= CAP:
+        return list(rows)
+    return [*rows[:CAP], f"+{len(rows) - CAP} more"]
+
+
+def summary(board: Board, closed: int) -> str:
+    """`3 open, 1 ready` — and the closed count whenever closed cards are on screen.
+
+    The `ready` count is the one number that says whether adding another agent would help,
+    and a person reading their list is exactly the person deciding that. The closed count
+    appears only when closed rows do, so the line never describes something not shown.
+    """
+    count = sum(len(column["cards"]) for column in board["columns"]
+                if column["status"] in OPEN_STATUSES)
+    line = f"{count} open, {board['ready']} ready"
+    return f"{line}, {closed} closed" if closed else line

taskops/render/_text.py

@@ -0,0 +1,74 @@
+"""Text primitives. Pure functions of strings — no I/O anywhere in `render/`.
+
+That purity is enforced (`tests/architecture`) and it is what lets the same renderer
+serve the CLI, the MCP reply and the web UI's markdown export: a rendering bug is
+reproducible from a literal dict with no database in sight.
+"""
+
+from __future__ import annotations
+
+from .._clock import now
+
+__all__ = ["ago", "span", "bullet", "table", "truncate", "STATUS_MARK"]
+
+STATUS_MARK = {"backlog": "·", "ready": "○", "claimed": "◐", "in_progress": "●",
+               "blocked": "✕", "review": "◆", "done": "✓", "cancelled": "—"}
+"""One glyph per status, so a board scans vertically without reading words.
+
+ASCII-ish and deliberately not emoji: this is read in a terminal by a human and in a
+context window by a model, and emoji cost several tokens each for the same information.
+"""
+
+
+def ago(ts: float, *, at: float | None = None) -> str:
+    """`1 800 000 042.0` -> "3m ago". Coarse on purpose.
+
+    Nobody acts differently on 187 versus 190 seconds, and a precise duration invites a
+    reader to compare two of them — which is a comparison between two clocks that may not
+    agree, since these timestamps come from different machines.
+    """
+    seconds = max(0.0, (now() if at is None else at) - ts)
+    return f"{span(seconds)} ago" if seconds >= 60.0 else "just now"
+
+
+def span(seconds: float) -> str:
+    """`5400.0` -> "1h". A DURATION, where `ago` is a distance from now.
+
+    The same coarseness and the same arithmetic, which is why `ago` is written in terms of
+    it: two rounding rules for two ways of printing the same number is how a card ends up
+    saying it took 2h beside a claim that says 3h ago.
+    """
+    for size, unit in ((86400.0, "d"), (3600.0, "h"), (60.0, "m")):
+        if seconds >= size:
+            return f"{int(seconds // size)}{unit}"
+    return "under a minute"
+
+
+def truncate(text: str, limit: int) -> str:
+    """One line, at most `limit` characters. Collapses newlines first.
+
+    A spec's first line is often a sentence that continues, and pasting the raw newline
+    into a table cell breaks the table for every row after it.
+    """
+    flat = " ".join(text.split())
+    return flat if len(flat) <= limit else flat[: limit - 1].rstrip() + "…"
+
+
+def bullet(lines: list[str], *, indent: int = 0) -> str:
+    prefix = " " * indent + "- "
+    return "\n".join(prefix + line for line in lines)
+
+
+def table(headers: list[str], rows: list[list[str]]) -> str:
+    """A markdown table, or "" for no rows.
+
+    Empty rather than a header with nothing under it: a reader shown an empty table has
+    to work out whether the query failed or the answer is genuinely nothing, and the
+    caller knows which and can say so in a sentence.
+    """
+    if not rows:
+        return ""
+    head = "| " + " | ".join(headers) + " |"
+    rule = "|" + "|".join("---" for _ in headers) + "|"
+    body = ["| " + " | ".join(cell for cell in row) + " |" for row in rows]
+    return "\n".join([head, rule, *body])