taskops-cli 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

taskops/__init__.py

@@ -1,39 +1,26 @@
-"""taskops — the coordination substrate Claude Code does not have.
+"""taskops — a shared work board for teams of coding agents.
 
-Persistent tasks with a dependency DAG, atomic claims that survive a crashed
-agent, every commit bound to the task that motivated it, and a live board a
-human can watch while a hundred agents work.
-
-The error types are exported eagerly because a caller has to be able to write
-`except taskops.LeaseHeld` before it has opened anything. Everything else stays
-behind its own module so that importing this package costs a dict lookup — the
-MCP host imports it to list tools long before it asks for any work.
+The public surface is deliberately tiny: open a board, call a verb, handle one
+error tree. Everything else (MCP tools, the HTTP server, the git hooks) is a
+transport built on top of exactly this.
 """
 
 from __future__ import annotations
 
 from ._errors import (
-    AlreadyWritten,
+    Refused,
+    NotFound,
     BadRequest,
-    GuardFailed,
-    IllegalTransition,
-    LeaseHeld,
-    NoLease,
-    NoSuchTask,
-    NotInitialized,
+    Unreachable,
     TaskopsError,
 )
 from ._version import __version__
 
 __all__ = [
-    "__version__",
     "TaskopsError",
-    "NotInitialized",
-    "NoSuchTask",
-    "IllegalTransition",
-    "LeaseHeld",
-    "NoLease",
-    "GuardFailed",
+    "Refused",
+    "NotFound",
+    "Unreachable",
     "BadRequest",
-    "AlreadyWritten",
+    "__version__",
 ]

taskops/_clock.py

@@ -1,32 +1,33 @@
-"""Layer 0 — the one place that asks what time it is.
+"""The only module that reads the clock.
 
-Leases expire, heartbeats renew and events are ordered, so "now" is load-bearing
-here rather than incidental. Routing it through one function is what lets a test
-of "the agent died and its lease lapsed" run in microseconds instead of waiting
-fifteen real minutes for the TTL.
+`tests/test_architecture.py` pins this: `time.time`, `datetime.now`,
+`time.monotonic`, `localtime` and `strftime` may not appear anywhere else
+(except `core/hours.py`, which does calendar arithmetic and says so). v1 let a
+stray `strftime` through and a report cut days in two timezones at once.
 
-`time.time()` and not `monotonic()`: these timestamps are compared ACROSS
-machines and survive a restart, which a monotonic clock cannot do. The cost is
-that a badly skewed clock skews a TTL — bounded, and visible in the studio,
-where a lease from the future is obvious.
+Tests freeze time through `set_now`; nothing else may.
 """
 
 from __future__ import annotations
 
 import time
 
-__all__ = ["now", "LEASE_TTL", "HEARTBEAT_GRACE"]
+_frozen: float | None = None
 
-LEASE_TTL = 900.0
-"""Seconds a claim survives without a heartbeat. Every taskops call an agent
-makes renews it, so this bounds how long a task stays stuck after a CRASH —
-not how long a legitimately slow task may run."""
 
-HEARTBEAT_GRACE = 60.0
-"""Extra seconds the studio waits before calling a session dead. A lease renews
-on tool calls, and an agent that spends two minutes thinking has not gone away."""
+def now() -> float:
+    """Wall-clock seconds. The single source of 'when'."""
+    return _frozen if _frozen is not None else time.time()
 
 
-def now() -> float:
-    """Wall-clock seconds since the epoch."""
-    return time.time()
+def datestamp(when: float) -> str:
+    """`YYYY-MM-DD`, local. Here and not at the call site for the reason above:
+    the archive a `board push` leaves behind is named after a day, and a day is
+    a calendar fact — the one kind of formatting this module exists to own."""
+    return time.strftime("%Y-%m-%d", time.localtime(when))
+
+
+def set_now(value: float | None) -> None:
+    """Freeze (or unfreeze) the clock. Tests only — never called by the package."""
+    global _frozen
+    _frozen = value

taskops/_errors.py

@@ -1,160 +1,55 @@
-"""Structured errors: a small taxonomy every boundary maps ONCE.
-
-Errors are data, not strings — a stable machine `code` plus an `http_status` — so
-each transport translates the TYPE at one catch site instead of matching message
-text. Each subclass also inherits the builtin a caller would plausibly already be
-catching (the `json.JSONDecodeError(ValueError)` trick). Every message names what
-to DO: the reader is an agent mid-turn, and this is all it gets to act on.
+"""The one error tree.
+
+Every exception that escapes this package descends from `TaskopsError`. A
+foreign exception is converted at the boundary that raises it (`raise X from
+err`) — a caller never sees `sqlite3.OperationalError` or
+`json.JSONDecodeError`. Each class carries a stable `code` because that code
+crosses the wire in the RPC envelope, so the string lives here and nowhere
+else.
+
+`Refused` is the interesting one: a rule said no, and **its message contains
+the call that fixes it, verbatim**. That was the best habit of v1 and it is
+kept word for word.
 """
 
 from __future__ import annotations
 
-from pathlib import Path
-
-__all__ = [
-    "TaskopsError", "NotInitialized", "NoSuchTask", "IllegalTransition", "LeaseHeld", "NoLease",
-    "GuardFailed", "BadRequest", "AlreadyWritten", "AlreadyNarrating", "NarrationFailed",
-    "ReportConflict", "Unreachable",
-]
-
 
 class TaskopsError(Exception):
-    """Root. `except TaskopsError` catches everything the engine raises."""
+    """Root of everything this package raises."""
 
     code = "error"
-    http_status = 500
-
-
-class NotInitialized(TaskopsError, FileNotFoundError):
-    """No `.taskops/` at or above the given path."""
-
-    code = "not_initialized"
-    http_status = 404
-
-    @classmethod
-    def at(cls, path: str | Path) -> "NotInitialized":
-        return cls(f"no taskops project at or above {path} — run `taskops init` in the "
-                   f"repository root")
-
-
-class NoSuchTask(TaskopsError, KeyError):
-    """A task id nobody created — usually a hallucinated or a stale one."""
-
-    code = "no_such_task"
-    http_status = 404
-
-    @classmethod
-    def named(cls, task: str) -> "NoSuchTask":
-        return cls(f"no task {task} — list what exists with `taskops report board`")
-
-
-class IllegalTransition(TaskopsError, ValueError):
-    """A status move the machine does not allow."""
-
-    code = "illegal_transition"
-    http_status = 409
-
-    @classmethod
-    def between(
-        cls, *, task: str, old: str, new: str, allowed: tuple[str, ...]
-    ) -> "IllegalTransition":
-        legal = ", ".join(allowed) if allowed else "nothing — it is terminal"
-        return cls(f"{task} is {old} and cannot go to {new}; from {old} it can go to {legal}")
-
-
-class LeaseHeld(TaskopsError, RuntimeError):
-    """Somebody else is on it and their lease has not expired."""
 
-    code = "lease_held"
-    http_status = 409
 
-    @classmethod
-    def by(cls, *, task: str, actor: str, seconds: int) -> "LeaseHeld":
-        return cls(f"{task} is claimed by {actor} for another {seconds}s — "
-                   f"pick another task, or message them on it")
+class Refused(TaskopsError):
+    """A rule said no. The message must name the way out."""
 
+    code = "refused"
 
-class NoLease(TaskopsError, RuntimeError):
-    """Working on a task nobody claimed. Its own type, not a GuardFailed,
-    because it has ONE fix the agent can apply unaided — which the message is."""
 
-    code = "no_lease"
-    http_status = 409
+class NotFound(TaskopsError):
+    """A card, milestone, board or event that does not exist."""
 
-    @classmethod
-    def on(cls, *, task: str, actor: str) -> "NoLease":
-        return cls(f"{actor} holds no live lease on {task} — claim it with "
-                   f"taskops_next, or `taskops claim {task}`")
+    code = "not_found"
 
 
-class GuardFailed(TaskopsError, ValueError):
-    """A transition the machine allows but the project's rules refuse. Separate
-    from IllegalTransition: that one is "the arrow does not exist", this one is
-    "you have not earned it yet" — and only this one is fixable by doing work."""
+class Unreachable(TaskopsError):
+    """The remote board did not answer. Never silently degrades to local."""
 
-    code = "guard_failed"
-    http_status = 400
+    code = "unreachable"
 
 
-class BadRequest(TaskopsError, ValueError):
-    """An argument that cannot mean anything. Raised at the edges, not inside."""
+class BadRequest(TaskopsError):
+    """Malformed input: bad actor grammar, unknown verb, wrong argument shape."""
 
     code = "bad_request"
-    http_status = 400
-
-
-class AlreadyWritten(TaskopsError, FileExistsError):
-    """A generated file that exists and would be OVERWRITTEN. 409, never 500.
-
-    A written report is something somebody may have already read, cited, or narrated by
-    hand; silently regenerating it would rewrite history under them. Refusing and naming
-    `--force` leaves the choice with the person who knows whether the old one mattered.
-    """
-
-    code = "already_written"
-    http_status = 409
-
-
-class AlreadyNarrating(TaskopsError, RuntimeError):
-    """A narration of that report is already running IN THIS PROCESS. 409.
-
-    Two models writing the same file is not a slow path, it is corruption: both hold the
-    dossier they read at the start and each rewrites the whole file when it flushes, so
-    whichever finishes last silently erases the other. Refusing the second is the only
-    outcome that leaves a readable report — and the first one is still streaming, so the
-    person who clicked twice is already looking at what they asked for.
-    """
 
-    code = "already_narrating"
-    http_status = 409
 
+CODES: dict[str, type[TaskopsError]] = {
+    cls.code: cls for cls in (Refused, NotFound, Unreachable, BadRequest, TaskopsError)
+}
 
-class NarrationFailed(TaskopsError, RuntimeError):
-    """The `claude` CLI could not write the narration. 502: an upstream did not answer.
 
-    Its own type because the fix is never in taskops — the binary is missing, the session is
-    not logged in, or the model refused — and the message has to say which. Everything else
-    about the report still worked: the dossier is on disk either way, so this never costs the
-    facts, only the prose.
-    """
-
-    code = "narration_failed"
-    http_status = 502
-
-
-class ReportConflict(TaskopsError, FileExistsError):
-    """A DIFFERENT narration of one report, not a newer one — `ours`/`theirs` are the stamps."""
-
-    code = "report_conflict"
-    http_status = 409
-    ours = -1
-    theirs = -1
-
-
-class Unreachable(TaskopsError, ConnectionError):
-    """The server did not answer at all — no status, no body. 502, and never a reason to
-    write locally instead: that is how two machines end up holding one card. Its own type
-    so `usecases._routing` can catch exactly it and say which URL went quiet."""
-
-    code = "unreachable"
-    http_status = 502
+def from_code(code: str, message: str) -> TaskopsError:
+    """Rebuild an error carried over the wire. Unknown code → the root type."""
+    return CODES.get(code, TaskopsError)(message)

taskops/_ids.py

@@ -1,63 +1,71 @@
-"""Layer 0 — how a task and an event get their names.
+"""Identifiers.
 
-Two different jobs, and the difference is the whole design:
+Two shapes, both deliberate:
 
-**Task ids are RANDOM** (`tk-4f2a9c`). Many machines create tasks without
-talking to each other, so an id must be collision-free without coordination —
-which rules out a counter. Random also means unguessable, so a task id in a
-branch name leaks no ordering information about the project.
-
-**Event ids are the CONTENT, hashed.** The event log is replicated by `git pull`
-and by the relay, and the same event can arrive by both paths: with a content
-hash, importing it twice is a primary-key no-op instead of a duplicate comment
-in somebody's inbox. It also makes the log verifiable — an event whose id does
-not match its content was edited after the fact.
+* a card id is **random** (`tk-` + 6 hex). It is a name, not a hash: it must
+  stay stable while the card is edited, and it is what the git branch and the
+  commit trailer are made of.
+* an event id is the **sha256 of its canonical form, 32 hex**. Content-hash
+  ids are what make the log idempotent (`INSERT OR IGNORE` and replaying twice
+  is free). v1 truncated to 16 hex — 64 bits — and a collision there is a
+  silently dropped event, so 128 bits it is.
 """
 
 from __future__ import annotations
 
-import hashlib
-import json
 import secrets
-from typing import Any
-
-__all__ = ["new_task_id", "event_id", "slugify", "TASK_PREFIX"]
+from hashlib import sha256
 
 TASK_PREFIX = "tk-"
-_TASK_BYTES = 3  # 6 hex chars: 16.7M ids, and the whole id fits a branch name
-_EVENT_CHARS = 16
+MILESTONE_PREFIX = "ms-"
+EVENT_ID_LEN = 32
 
 
 def new_task_id() -> str:
-    """A fresh task id. Uniqueness is checked at INSERT, not assumed here."""
-    return TASK_PREFIX + secrets.token_hex(_TASK_BYTES)
-
-
-def event_id(*, task: str, actor: str, kind: str, body: dict[str, Any], ts: float) -> str:
-    """The id of an event, derived from everything the event says.
-
-    `sort_keys` and a fixed float format matter more than they look: two
-    machines must hash the same event to the same id, and Python's dict order
-    and `repr(float)` are not a contract across versions.
-    """
-    payload = json.dumps(
-        {"task": task, "actor": actor, "kind": kind, "body": body, "ts": f"{ts:.6f}"},
-        sort_keys=True,
-        separators=(",", ":"),
-        default=str,
+    """`tk-` + 6 random hex. Collision-checked by the caller's INSERT."""
+    return TASK_PREFIX + secrets.token_hex(3)
+
+
+def new_milestone_id() -> str:
+    return MILESTONE_PREFIX + secrets.token_hex(3)
+
+
+def is_task_id(value: str) -> bool:
+    return _is(value, TASK_PREFIX)
+
+
+def is_milestone_id(value: str) -> bool:
+    return _is(value, MILESTONE_PREFIX)
+
+
+def _is(value: str, prefix: str) -> bool:
+    body = value[len(prefix) :]
+    return (
+        value.startswith(prefix) and len(body) == 6 and all(c in "0123456789abcdef" for c in body)
     )
-    return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:_EVENT_CHARS]
 
 
-def slugify(text: str, *, limit: int = 32) -> str:
-    """A title -> the branch-safe half of `tk/<id>/<slug>`.
+def digest(canonical: str) -> str:
+    """sha256 of an already-canonical string, truncated to 128 bits."""
+    return sha256(canonical.encode("utf-8")).hexdigest()[:EVENT_ID_LEN]
+
+
+def new_token() -> str:
+    """A credential or invite secret. Only the sha256 of this is ever stored.
+
+    **Never starts with `-`.** `token_urlsafe` draws from `A-Za-z0-9_-`, so
+    roughly one token in 64 begins with a hyphen — and every one of those is a
+    token that cannot be passed to the CLI: `taskops join x --invite -Ab9…`
+    makes argparse read the secret as an option and refuse with *expected one
+    argument*. It fails for the user who was unlucky, on a value they cannot
+    influence, with a message about the flag rather than the value.
+
+    Fixed HERE, at the one place a secret is minted, rather than by quoting or
+    `--invite=` at each call site: the token also travels in URLs, briefs and
+    shell snippets nobody controls. Found by CI — the runner drew a leading
+    hyphen on the first run this suite ever had off this laptop.
 
-    Deliberately lossy and never parsed back: the id is what identifies the
-    task, so this only has to be readable in a `git branch` listing. Everything
-    git or a shell would treat as special becomes a dash.
-    """
-    kept = [c.lower() if c.isalnum() else "-" for c in text.strip()]
-    slug = "".join(kept).strip("-")
-    while "--" in slug:
-        slug = slug.replace("--", "-")
-    return slug[:limit].strip("-") or "task"
+    Rerolling (not stripping) keeps every token the full 24 bytes of entropy."""
+    while (token := secrets.token_urlsafe(24)).startswith("-"):
+        pass
+    return token

taskops/_json.py

@@ -0,0 +1,48 @@
+"""Foreign JSON becomes a typed mapping HERE, or it becomes nothing.
+
+Every boundary that reads JSON somebody else wrote — a config file, an HTTP
+envelope, an MCP argument object — goes through `as_object`. One place to be
+lenient, everywhere else typed. v1 spread this coercion over fifteen call
+sites and one of them read `claim="false"` as True.
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+
+def as_object(value: object) -> dict[str, Any]:
+    """A JSON object as `dict[str, Any]`. Anything else is an empty mapping."""
+    if not isinstance(value, dict):
+        return {}
+    return {str(k): v for k, v in cast("dict[Any, Any]", value).items()}
+
+
+def as_rows(value: object) -> list[dict[str, Any]]:
+    """A JSON array of objects. A non-object entry becomes an empty mapping."""
+    if not isinstance(value, list):
+        return []
+    return [as_object(x) for x in cast("list[object]", value)]
+
+
+def as_strings(value: object) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [x for x in cast("list[object]", value) if isinstance(x, str)]
+
+
+def text(value: object, default: str = "") -> str:
+    """A string field that may be missing or of the wrong type."""
+    return value if isinstance(value, str) else default
+
+
+def query(url: str) -> dict[str, str]:
+    """`…?token=abc&invite=xyz` → the parameters, without a urllib import at
+    every call site. Anything malformed is simply absent."""
+    _, _, tail = url.partition("?")
+    found: dict[str, str] = {}
+    for part in tail.split("&"):
+        key, sep, value = part.partition("=")
+        if sep and key:
+            found[key] = value
+    return found

taskops/_locate.py

@@ -0,0 +1,106 @@
+"""Where the board is, and what its config says. Nothing here opens one.
+
+Split out of `board.py` along the seam that file's own history names: v1 kept
+this as `storage/locate.py`, and the two questions really are separate — *which
+directory is this project's* is answered from the filesystem alone, while *how
+do I talk to its board* needs the stores, the verbs and the network.
+
+Two files make a project, and only `init`/`join` ever write them:
+
+    .taskops/board.json    {"url": …}   committed — the address travels with the code
+    .taskops/remote.json   {"token", "token_expires", "login"}   0600, gitignored —
+                           the secret never travels, and with a `login` block the
+                           token is a SESSION this machine re-mints (`session.py`)
+"""
+
+from __future__ import annotations
+
+import os
+import json
+from typing import Any
+from pathlib import Path
+
+from ._json import as_object
+
+DIR = ".taskops"
+
+# "A board lives here." Written by BOTH `init` and `join`, so it is the one
+# marker every project has and nothing else creates.
+ADDRESS = "board.json"
+
+
+def is_project(candidate: Path) -> bool:
+    """A directory is a project when `.taskops/board.json` is in it.
+
+    The FILE, not the directory, and the distinction is not pedantry: v1 kept
+    its sessions in `~/.taskops/`, so that directory exists on every machine
+    that ever ran it — and matching the directory alone made the HOME DIRECTORY
+    a project: `taskops init` in a fresh repo under it walked up, adopted HOME,
+    and wrote the board, both git hooks, `.mcp.json` and the Claude settings
+    there instead of in the repo. v1 hit and fixed this the same way
+    (`storage/locate.py`); v2 shipped the bare check and reproduced it.
+    """
+    return (candidate / DIR / ADDRESS).is_file()
+
+
+def find_root(start: Path) -> Path:
+    """The nearest project, else the git root, else `start`.
+
+    A project wins over `.git` deliberately: a worker's worktree lives at
+    `<repo>/.taskops/trees/tk-…` and has a `.git` file of its own. Answering
+    "the worktree" there would look for the credential in the wrong place and
+    silently fall back to a local board — one of v1's split-brain routes. The
+    walk finds `<repo>` anyway, because that is where the address file is.
+    """
+    here = start.resolve()
+    chain = [here, *here.parents]
+    for candidate in chain:
+        if is_project(candidate):
+            return candidate
+    for candidate in chain:
+        if (candidate / ".git").exists():
+            return candidate
+    return here
+
+
+def read_config(root: Path) -> dict[str, Any]:
+    """board.json (committed) merged with remote.json (secret). Missing is fine."""
+    out: dict[str, Any] = {}
+    for name in (ADDRESS, "remote.json"):
+        path = root / DIR / name
+        if not path.exists():
+            continue
+        try:
+            data: Any = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            continue  # a broken config means "not configured", never a crash on read
+        out.update(as_object(data))
+    return out
+
+
+def write_remote(root: Path, fields: dict[str, Any]) -> None:
+    """Merge `fields` into remote.json, keeping every other key it holds, 0600.
+
+    The WRITER of the secret half, beside its reader, because the shape of that
+    file is one fact: a session refresh (`session.remember`), the key that minted
+    it (`session.cache_login`) and the host and board this checkout operates
+    (`cli/remote.py`) each write ONE block and must not eat the others'.
+
+    `login` is therefore MERGED FIELD BY FIELD and never replaced whole. Three
+    writers own three fields of it — `remote add` the host, a sign-in the
+    principal and the key, `board create` the board's name — and a plain
+    top-level update would have the sign-in silently drop the recorded name, so
+    the bare `board push` after it would go back to guessing the directory."""
+    path = root / DIR / "remote.json"
+    body: dict[str, Any] = {}
+    if path.exists():
+        try:
+            body = as_object(json.loads(path.read_text(encoding="utf-8")))
+        except (OSError, ValueError):
+            body = {}
+    if "login" in fields:
+        fields = {**fields, "login": {**as_object(body.get("login")), **as_object(fields["login"])}}
+    body.update(fields)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(body, indent=2) + "\n", encoding="utf-8")
+    os.chmod(path, 0o600)

taskops/_version.py

@@ -1,7 +1,4 @@
-"""The single source of the version. `pyproject.toml` reads this attribute."""
-
 from __future__ import annotations
 
-__all__ = ["__version__"]
-
-__version__ = "0.2.0"
+__title__ = "taskops"
+__version__ = "0.3.0"  # single source of truth; pyproject reads it dynamically