taskops-cli 0.2.0__py3-none-any.whl

taskops/engine/gitio.py

@@ -0,0 +1,108 @@
+"""Reading git, and the two conventions that bind a commit to a task.
+
+```
+branch:          tk/<task-id>/<slug>
+commit trailer:  Task: tk-4f2a9c
+```
+
+Both, not either. The branch is what a human sees in `git branch` and what the guard
+can check BEFORE a commit exists; the trailer is what survives a squash, a rebase and
+a cherry-pick onto main, where the branch name is gone. A system with only the branch
+loses every association the moment the branch is deleted — which is the normal end of
+a branch's life.
+
+Every function here degrades rather than raises. This code runs inside git hooks and
+in repositories that are sometimes not repositories at all, and a coordination tool
+that breaks `git commit` because it could not parse something is worse than one that
+records nothing.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+
+from .._ids import TASK_PREFIX
+
+__all__ = ["TRAILER", "task_of_branch", "task_of_message", "add_trailer",
+           "current_branch", "head_sha", "commit_message", "changed_files"]
+
+TRAILER = "Task"
+
+_BRANCH = re.compile(rf"^tk/({re.escape(TASK_PREFIX)}[0-9a-f]+)/")
+_TRAILER_LINE = re.compile(rf"^{TRAILER}:\s*({re.escape(TASK_PREFIX)}[0-9a-f]+)\s*$",
+                           re.MULTILINE | re.IGNORECASE)
+
+
+def task_of_branch(branch: str) -> str:
+    """The task a branch belongs to, or "". Anchored, so `feat/tk-1/x` is not a match:
+    a near-miss must read as unbound rather than bind to the wrong task."""
+    found = _BRANCH.match(branch.strip())
+    return found.group(1) if found else ""
+
+
+def task_of_message(message: str) -> str:
+    """The task a commit message names in its trailer, or ""."""
+    found = _TRAILER_LINE.search(message)
+    return found.group(1) if found else ""
+
+
+def add_trailer(message: str, task_id: str) -> str:
+    """Append `Task: <id>` unless the message already carries one.
+
+    Idempotent, because the guard runs on every commit and an agent that wrote the
+    trailer by hand should not get two. A trailer for a DIFFERENT task is left
+    alone — the guard rejects that case rather than silently rewriting what the
+    author said.
+    """
+    if task_of_message(message):
+        return message
+    body = message.rstrip("\n")
+    separator = "\n\n" if "\n" not in body else "\n"
+    return f"{body}{separator}{TRAILER}: {task_id}\n"
+
+
+def current_branch(root: Path) -> str:
+    """The checked-out branch, or "" if there is not one.
+
+    `symbolic-ref` and NOT `rev-parse --abbrev-ref`, for two reasons that both bit:
+
+    - On a repository with no commits yet, HEAD is unborn and `rev-parse` FAILS — so the
+      branch read as "" and the guard told an agent that `tk/tk-ea4f26/…`, which it was
+      standing on, "is not a task branch". Found by hand-driving the CLI in a fresh repo,
+      because every test had made an initial commit first.
+    - On a detached HEAD, `rev-parse --abbrev-ref` returns the literal string "HEAD", which
+      is indistinguishable from a branch actually named HEAD. `symbolic-ref` fails instead,
+      and failing is the honest answer: there is no branch.
+    """
+    return _git(root, "symbolic-ref", "--short", "HEAD")
+
+
+def head_sha(root: Path) -> str:
+    return _git(root, "rev-parse", "HEAD")
+
+
+def commit_message(root: Path, sha: str = "HEAD") -> str:
+    return _git(root, "log", "-1", "--format=%B", sha)
+
+
+def changed_files(root: Path, sha: str = "HEAD") -> list[str]:
+    """Paths a commit touched. Empty for the very first commit, which has no parent
+    to diff against — reported as nothing rather than as a failure."""
+    out = _git(root, "diff-tree", "--no-commit-id", "--name-only", "-r", sha)
+    return [line for line in out.splitlines() if line]
+
+
+def _git(root: Path, *args: str) -> str:
+    """One git command's stdout, or "" for any failure at all.
+
+    Never raises, for the reason in the module docstring. `check=False` plus a
+    timeout: a hook that hangs on a git subprocess hangs the developer's commit.
+    """
+    try:
+        done = subprocess.run(["git", *args], cwd=root, capture_output=True,
+                              text=True, timeout=10, check=False)
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    return done.stdout.strip() if done.returncode == 0 else ""

taskops/engine/gitstate.py

@@ -0,0 +1,96 @@
+"""Reading how far a branch is from its remote. Cheap, batched, and never raising.
+
+The question a board has to answer is "can anybody else see this work yet", and git already knows.
+One `for-each-ref` returns every local branch with its upstream and its ahead/behind counts, which
+is why this is one subprocess for a whole board rather than one per card.
+
+Same rule as the rest of `gitio`: every function degrades to a useless-but-honest answer instead of
+raising. This runs inside a board refresh and inside hooks, and a coordination tool that breaks
+because a branch was deleted mid-read is worse than one that reports `exists: False`.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+
+from ..contracts import BranchState
+
+__all__ = ["branch_states", "branch_state", "unknown", "porcelain"]
+
+_TRACK = re.compile(r"ahead (\d+)|behind (\d+)")
+_SEP = "\x1f"          # unit separator: cannot appear in a ref name, unlike anything printable
+
+
+def unknown(branch: str) -> BranchState:
+    """The answer for a branch this repository does not have.
+
+    Its own constructor because the honest empty value is easy to get wrong: `exists=False` with
+    `pushed=False` reads as "unpushed work", and the truth is "no idea, not here".
+    """
+    return BranchState(branch=branch, upstream="", ahead=0, behind=0, pushed=False,
+                       exists=False)
+
+
+def branch_states(root: Path) -> dict[str, BranchState]:
+    """Every local branch, keyed by name. ONE subprocess for a whole board."""
+    fields = f"%(refname:short){_SEP}%(upstream:short){_SEP}%(upstream:track)"
+    out = _git(root, "for-each-ref", f"--format={fields}", "refs/heads")
+    states: dict[str, BranchState] = {}
+    for line in out.splitlines():
+        parts = line.split(_SEP)
+        if len(parts) != 3 or not parts[0]:
+            continue
+        states[parts[0]] = _state(parts[0], parts[1], parts[2])
+    return states
+
+
+def branch_state(root: Path, branch: str) -> BranchState:
+    """One branch. Convenience over `branch_states` for a single-task read."""
+    if not branch:
+        return unknown(branch)
+    return branch_states(root).get(branch, unknown(branch))
+
+
+def _state(branch: str, upstream: str, track: str) -> BranchState:
+    """`[ahead 3, behind 1]` -> the numbers.
+
+    A branch with no upstream reports `ahead=0`, and that is NOT "nothing to push": git has nothing
+    to compare against, so the count is unknown while the work is definitely unpushed. `pushed`
+    therefore requires an upstream, which is what keeps a never-pushed branch from reading as clean.
+    """
+    ahead, behind = 0, 0
+    for match in _TRACK.finditer(track):
+        if match.group(1):
+            ahead = int(match.group(1))
+        elif match.group(2):
+            behind = int(match.group(2))
+    return BranchState(branch=branch, upstream=upstream, ahead=ahead, behind=behind,
+                       pushed=bool(upstream) and ahead == 0, exists=True)
+
+
+def porcelain(tree: Path) -> list[str]:
+    """The paths `git status` reports as changed or untracked in `tree`, or [] if there is no tree.
+
+    Used by recovery to find what a dead worker never committed. Untracked files count — that is
+    usually exactly what a killed agent leaves, since it writes before it commits.
+    """
+    if not tree.is_dir():
+        return []
+    out = _git(tree, "status", "--porcelain")
+    return [line[3:].strip() for line in out.splitlines() if len(line) > 3]
+
+
+def _git(root: Path, *args: str) -> str:
+    """One git command's stdout, or "" for any failure.
+
+    Never raises, for the reason in the module docstring. `check=False` plus a timeout, because a
+    board refresh must not hang on a repository whose index is locked by somebody's rebase.
+    """
+    try:
+        done = subprocess.run(["git", *args], cwd=root, capture_output=True, text=True,
+                              timeout=10, check=False)
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    return done.stdout.strip() if done.returncode == 0 else ""

taskops/engine/history.py

@@ -0,0 +1,76 @@
+"""The log read as a HISTORY: what happened here, in order, and who did it.
+
+Its own module rather than a third projection in `activity.py`, because it answers a different
+question. That one is about the workers as they are right now — who holds what, is it alive — and
+this one is about the record they leave behind, which outlives every session that wrote it.
+
+Nothing is stored for it. Every fact it shows is already in `events.jsonl`, which is why it could be
+added without a migration and why it cannot drift from what actually happened.
+"""
+
+from __future__ import annotations
+
+from ..contracts import Activity, ActorRoll, Event
+from ..storage import Store
+from .activity import tasks_of
+
+__all__ = ["activity", "rolls", "MAX_EVENTS"]
+
+MAX_EVENTS = 600
+"""How much timeline one read returns. A window wide enough to be interesting on an old project is
+also wide enough to be tens of thousands of events, and nobody scrolls that — so it is bounded, and
+the answer SAYS it was bounded rather than quietly showing a slice as if it were everything."""
+
+
+def activity(store: Store, *, since: float, limit: int = MAX_EVENTS) -> Activity:
+    """The timeline, plus a roll-up per actor, from one pass over the same events.
+
+    One projection and not two: a per-actor summary computed over a different window than the
+    timeline beside it would summarise something the reader cannot see, and it would cost a second
+    scan of the same rows to be wrong.
+
+    The questions this answers — when did this card really move, who has ever touched this area,
+    what did that agent do while it held the lease — are answerable from the log and from nothing
+    else, because a task row keeps only where things landed.
+    """
+    # One extra row is the whole truncation check: asking for `limit + 1` and getting it means
+    # there was more, without a second COUNT over the same window.
+    found = store.events.newest_since(since, limit=limit + 1)
+    kept = found[-limit:] if len(found) > limit else found
+    return Activity(repo=str(store.root), since=since, events=list(reversed(kept)),
+                    titles={task["id"]: task["title"]
+                            for task in tasks_of(store, [e["task"] for e in kept])},
+                    actors=rolls(kept), kinds=sorted({e["kind"] for e in kept}),
+                    truncated=len(found) > limit)
+
+
+def rolls(events: list[Event]) -> list[ActorRoll]:
+    """Per actor, busiest first. Public because `day` needs the same roll-up over its own
+    window — two projections summarising actors two different ways is exactly how a board
+    starts disagreeing with itself about who did what.
+
+    Counted from the events rather than from leases, which is what makes an agent that finished an
+    hour ago still appear: the lease is gone, the work is not. That is the whole reason this replaced
+    a live fleet panel — "who is free" stopped being a question when agents became disposable.
+    """
+    seen: dict[str, list[Event]] = {}
+    for event in events:
+        seen.setdefault(event["actor"], []).append(event)
+    out = [_roll(actor, theirs) for actor, theirs in seen.items()]
+    return sorted(out, key=lambda roll: (-roll["tasks"], -roll["commits"], roll["actor"]))
+
+
+def _roll(actor: str, events: list[Event]) -> ActorRoll:
+    """Tasks, not events: an actor that commented forty times on one card has done less than one
+    that closed four, and counting events would rank them the other way round."""
+    stamps = [event["ts"] for event in events]
+    kinds = [event["kind"] for event in events]
+    return ActorRoll(actor=actor, tasks=len({event["task"] for event in events}),
+                     commits=kinds.count("commit"),
+                     comments=kinds.count("comment") + kinds.count("message"),
+                     # A close is its OWN kind — `update` writes `done` rather than `status` when
+                     # the target is done, precisely so it can be found without reading bodies.
+                     # This is the only place the fact lives: the task row shows the state, never
+                     # who moved it there.
+                     done=kinds.count("done"),
+                     first_seen=min(stamps), last_seen=max(stamps))

taskops/engine/identity.py

@@ -0,0 +1,84 @@
+"""Who is calling — resolved once, from the least surprising source available.
+
+An agent rarely knows its own name, and asking it to invent one produces a fleet of
+actors called `agent:claude/agent`. So the resolution order goes from most explicit
+to most inferable, and every step is something a human configured on purpose:
+
+1. what the caller passed (a fleet launcher naming its workers)
+2. `$TASKOPS_ACTOR` (the plugin exports it per session)
+3. the git identity, turned into `dev:<local-part>`
+
+The last one is why a developer who never configures anything still gets attributed
+work rather than an `unknown`. It is also why `git config user.email` being wrong
+shows up here: the actor on the board is the identity the commits will carry.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+from .._errors import BadRequest
+from ..contracts import Actor
+
+__all__ = ["parse", "resolve", "ENV_ACTOR", "ENV_SESSION"]
+
+ENV_ACTOR = "TASKOPS_ACTOR"
+ENV_SESSION = "TASKOPS_SESSION"
+
+_FALLBACK = "dev:unknown"
+
+
+def parse(actor_id: str) -> Actor:
+    """`agent:berna/one` -> its parts. Raises on a shape nothing can attribute.
+
+    Strict rather than lenient, unlike most readers in this package: an actor id is
+    a JOIN KEY — it addresses an inbox and appears in every event — so accepting a
+    malformed one creates a second identity for the same person that nobody notices
+    until half their work is filed under it.
+    """
+    kind, _, rest = actor_id.strip().partition(":")
+    if kind == "dev" and rest and "/" not in rest:
+        return Actor(id=f"dev:{rest}", kind="dev", dev=rest)
+    if kind == "agent" and "/" in rest:
+        dev, _, name = rest.partition("/")
+        if dev and name:
+            return Actor(id=f"agent:{dev}/{name}", kind="agent", dev=dev)
+    raise BadRequest(f"`{actor_id}` is not an actor id — use `dev:<name>` or "
+                     f"`agent:<dev>/<name>`")
+
+
+def resolve(root: Path, asked: str = "") -> Actor:
+    """The caller's identity: what it said, else the environment, else git."""
+    for candidate in (asked, os.environ.get(ENV_ACTOR, "")):
+        if candidate.strip():
+            return parse(candidate)
+    return parse(_from_git(root))
+
+
+def _from_git(root: Path) -> str:
+    """`dev:<local-part of user.email>`, or a named fallback.
+
+    Falling back rather than raising: a git identity is missing in a fresh
+    container and in a repository nobody configured, and refusing to work there
+    would make taskops unusable in exactly the throwaway environments agents run
+    in. The fallback is VISIBLE on the board, which is the nudge.
+    """
+    email = _git_config(root, "user.email")
+    local = email.partition("@")[0].strip()
+    return f"dev:{local}" if local else _FALLBACK
+
+
+def _git_config(root: Path, key: str) -> str:
+    """One git config value, or "" if git is absent, broken or silent.
+
+    Never raises: this is called during identity resolution, which happens on the
+    way into every single call. A missing git must degrade, not take the tool down.
+    """
+    try:
+        done = subprocess.run(["git", "config", "--get", key], cwd=root,
+                              capture_output=True, text=True, timeout=5, check=False)
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    return done.stdout.strip() if done.returncode == 0 else ""

taskops/engine/log.py

@@ -0,0 +1,68 @@
+"""Recording that something happened. The one door into the event log.
+
+Every fact enters through `record`, which means three things happen together and
+cannot drift apart: the row is written, the id is derived from the content, and the
+live subscribers are told. A use case that wrote the table directly would be an
+event nobody sees on the board and nobody can replicate.
+
+Nothing here decides ANYTHING. `record` does not check a lease or a transition — by
+the time it is called, `machine` has already allowed the move. That separation is
+what lets the ingest path record a commit somebody made by hand outside any claim.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._clock import now
+from .._ids import event_id
+from .._types import EventKind
+from ..contracts import Event
+from ..storage import Store
+from .bus import BUS
+
+__all__ = ["record", "build"]
+
+
+def build(*, task: str, actor: str, kind: EventKind, body: dict[str, Any] | None = None,
+          ts: float | None = None) -> Event:
+    """An event with its id derived from its content.
+
+    Split from `record` so a caller can construct one without a database — which is
+    what the relay does when it forwards, and what the tests do when they need an
+    event whose id they can predict.
+    """
+    when = now() if ts is None else ts
+    payload = body or {}
+    return Event(id=event_id(task=task, actor=actor, kind=kind, body=payload, ts=when),
+                 task=task, actor=actor, kind=kind, body=payload, ts=when)
+
+
+def record(store: Store, *, task: str, actor: str, kind: EventKind,
+           body: dict[str, Any] | None = None, ts: float | None = None) -> Event:
+    """Write it, then announce it. Returns the event either way.
+
+    The event is returned even when it was already present, because the caller's
+    next step is usually to report what it recorded and a None here would make every
+    call site handle a case that is not an error.
+    """
+    event = build(task=task, actor=actor, kind=kind, body=body, ts=ts)
+    if store.events.append(event):
+        BUS.publish(event)
+    return event
+
+
+def relay(store: Store, event: Event) -> bool:
+    """Accept an event that came from elsewhere, verbatim. True if it was new.
+
+    The id is NOT recomputed. A foreign event's id is its identity, and rebuilding
+    it here would silently fork history the moment a newer taskops adds a body field
+    this version does not serialize identically.
+
+    That means a bad actor could forge an id, which is worth being explicit about:
+    the trust boundary is the git remote and the relay's token, not this function.
+    """
+    accepted = store.events.append(event, exported=True)
+    if accepted:
+        BUS.publish(event)
+    return accepted

taskops/engine/machine.py

@@ -0,0 +1,160 @@
+"""The state machine, and the ONLY place a status move is decided.
+
+Two tables and no `if status ==` anywhere else in the package — `tests/architecture`
+enforces the second half. A transition table plus one convenient status check
+somewhere is two state machines, and the convenient one is always the one that
+forgot the guard.
+
+Guards are pure functions of `Facts`, not of a database. That is what makes the
+rules testable from literals — "a claimed task cannot be closed without a commit"
+is three lines here, not a fixture with a repository in it — and it means the use
+case that ASSEMBLES the facts is the only thing that needs a store.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+from .._errors import GuardFailed, IllegalTransition
+from .._types import Status
+from ..contracts import Task
+
+__all__ = ["Facts", "TRANSITIONS", "check_move", "allowed_from"]
+
+
+@dataclass(frozen=True, slots=True)
+class Facts:
+    """Everything the guards are allowed to know. Assembled by `usecases.update`."""
+
+    task: Task
+    actor: str
+    has_live_lease: bool
+    commits: int
+    """Commits bound to this task — the evidence `done` demands."""
+
+    open_children: int
+    no_code: bool
+    """The caller's explicit declaration that this task produces no commit."""
+
+    justification: str
+    """The comment accompanying `no_code`. A claim with no reasoning is a bypass."""
+
+    unpushed: int
+    """Commits on this branch no remote has. Recorded on close, never blocking — see `_closing`."""
+
+
+Guard = Callable[[Facts], str | None]
+"""None means allowed; a string is the reason, written for the agent that is stuck."""
+
+
+def _needs_lease(facts: Facts) -> str | None:
+    if facts.has_live_lease:
+        return None
+    return (f"{facts.actor} holds no live lease on {facts.task['id']} — claim it "
+            f"with taskops_next before working on it")
+
+
+def _needs_evidence(facts: Facts) -> str | None:
+    """`done` requires a commit, or an argued exemption.
+
+    THE guard that makes the board trustworthy. Without it "done" means "an agent
+    said so", which is exactly the failure a human is trying to avoid by reading a
+    board instead of the diff. The exemption exists because research and decisions
+    are real work — but it has to be declared and reasoned, so that a review can
+    see which closures had no code and why.
+    """
+    if facts.commits > 0:
+        return None
+    if facts.no_code and facts.justification.strip():
+        return None
+    if facts.no_code:
+        return ("no_code needs a `comment` saying what was produced instead — "
+                "an unexplained exemption is indistinguishable from a shortcut")
+    # "on the task's branch" and not "the guard adds the trailer", which was the earlier wording:
+    # the trailer is only injected inside Claude Code, where a hook can rewrite the command. From a
+    # terminal the BRANCH is what binds the commit, so naming the branch is the advice that is true
+    # in both places.
+    return (f"{facts.task['id']} has no commit bound to it. Commit your work on the "
+            f"task's branch, or pass no_code with a comment if this task legitimately "
+            f"produced none")
+
+
+def _needs_children_closed(facts: Facts) -> str | None:
+    if facts.open_children == 0:
+        return None
+    return (f"{facts.task['id']} still has {facts.open_children} open subtask(s) — "
+            f"an epic is done when its children are")
+
+
+def _closing(facts: Facts) -> str | None:
+    """Both closing rules, in the order a caller can act on them.
+
+    Children first: being told to write a commit for an epic whose subtasks are
+    unfinished sends the agent to do the wrong work.
+
+    `unpushed` is deliberately NOT a rule here. It is recorded on the `done` event and shown on the
+    board instead, because pushing is not always the closer's job — a task can finish on a branch
+    somebody else lands — and a repository with no remote at all would otherwise be unable to close
+    anything, which is the most common way taskops is first tried.
+    """
+    return _needs_children_closed(facts) or _needs_evidence(facts)
+
+
+TRANSITIONS: dict[Status, dict[Status, Guard | None]] = {
+    "backlog": {"ready": None, "cancelled": None},
+    "ready": {"claimed": _needs_lease, "backlog": None, "cancelled": None},
+    "claimed": {"in_progress": _needs_lease, "review": _needs_lease, "done": _closing,
+                "ready": None, "blocked": _needs_lease, "cancelled": None},
+    "in_progress": {"review": _needs_lease, "done": _closing, "blocked": _needs_lease,
+                    "ready": None, "cancelled": None},
+    "blocked": {"ready": None, "backlog": None, "in_progress": _needs_lease,
+                "cancelled": None},
+    "review": {"done": _closing, "in_progress": _needs_lease, "blocked": None,
+               "cancelled": None},
+    "done": {},
+    "cancelled": {"backlog": None},
+}
+"""Who may go where.
+
+`claimed → done` exists, so `in_progress` is never MANDATORY. Requiring the
+intermediate step would add a call to the lifecycle of every task in the project in
+exchange for no information the commit does not already carry — and it is the GUARD,
+not the path taken to reach it, that protects the board. An agent that wants its work
+shown in flight sets `in_progress`; one that claimed, coded, committed and closed has
+done nothing wrong. (The missing arrow was found by the end-to-end test, which is the
+kind of bureaucracy only a full run reveals.)
+
+`done` is TERMINAL on purpose: reopening would make the log say a task was finished
+twice, and the honest record of "we shipped it and it was wrong" is a new task that
+references the old one.
+
+`→ ready` from a working status is the RELEASE path, and it is deliberately
+unguarded: an agent that is out of context or out of depth must always be able to
+hand work back, and a guard there would make the alternative — abandoning it until
+the lease lapses — the easier move.
+"""
+
+
+def allowed_from(status: Status) -> tuple[Status, ...]:
+    """Where a task in this status can go. Used in the error message, so a
+    rejected caller learns the shape of the machine instead of guessing."""
+    return tuple(TRANSITIONS.get(status, {}))
+
+
+def check_move(facts: Facts, new: Status) -> None:
+    """Raise unless this move is legal AND earned. Silent on success.
+
+    Two error types, because they are two different conversations: the arrow does
+    not exist (nothing to do about it), versus the arrow exists and the work is not
+    there yet (do the work).
+    """
+    old: Status = facts.task["status"]
+    outgoing = TRANSITIONS.get(old, {})
+    if new not in outgoing:
+        raise IllegalTransition.between(task=facts.task["id"], old=old, new=new,
+                                        allowed=allowed_from(old))
+    guard = outgoing[new]
+    refusal = guard(facts) if guard else None
+    if refusal:
+        raise GuardFailed(refusal)