taskops-cli 0.2.0__py3-none-any.whl

taskops/transports/cli/commands/dispatch.py

@@ -0,0 +1,43 @@
+"""Preparing worker agents, one per card — the flags and the call `taskops run` is built on.
+
+`taskops dispatch` was hidden once `taskops run` took over the half of this that starts
+processes, and it is gone now: an orchestrator dispatches over MCP (`taskops_dispatch`), and
+the person who wants processes types `run`. What stays is this module, because `run`'s flags
+are declared here — a second copy of that parser would drift the first time either grew an
+option.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from ....render import render_dispatch
+from ....usecases import dispatch as launch_workers
+from ._shared import add_target, repo_of
+
+__all__ = ["add_dispatch_args", "dispatch_with"]
+
+
+def add_dispatch_args(parser: argparse.ArgumentParser) -> None:
+    """Every flag a dispatch takes except `--spawn` — which is the one thing that tells the
+    two commands apart, and so is declared by each of them."""
+    add_target(parser)
+    parser.add_argument("tasks", nargs="*", help="task ids (default: the best ready ones)")
+    parser.add_argument("--count", type=int, default=0, help="how many to launch (default 3)")
+    parser.add_argument("--prefix", default="", help="worker name prefix (default 'w')")
+    parser.add_argument("--model", default="", help="model for the workers")
+    parser.add_argument("--dry-run", action="store_true", dest="dry_run",
+                        help="show what would launch, change nothing")
+    parser.add_argument("--actor", default="", help="who is dispatching")
+
+
+def dispatch_with(args: argparse.Namespace, *, spawn: bool) -> str:
+    """The one call both commands make. `spawn` is the only thing either of them decides.
+
+    `--use-api-key` is read with `getattr` because only `run` declares it; `dispatch` keeps the
+    flag set it always had rather than growing one that its own help would have to explain."""
+    return render_dispatch(launch_workers(
+        repo_of(args), tasks=tuple(str(t) for t in args.tasks), count=int(args.count),
+        actor=str(args.actor), prefix=str(args.prefix), model=str(args.model),
+        dry_run=bool(args.dry_run), spawn=spawn,
+        use_api_key=bool(getattr(args, "use_api_key", False))))

taskops/transports/cli/commands/init.py

@@ -0,0 +1,48 @@
+"""`taskops init` — make a repository coordinated, and say what actually happened."""
+
+from __future__ import annotations
+
+import argparse
+
+from ....usecases import InitReport
+from ....usecases import init as setup
+from ._shared import add_target, repo_of
+
+__all__ = ["register"]
+
+
+def register(sub: "argparse._SubParsersAction[argparse.ArgumentParser]") -> None:
+    parser = sub.add_parser("init", help="create .taskops/ and install the git hooks")
+    add_target(parser)
+    parser.add_argument("--no-hooks", action="store_true", dest="no_hooks",
+                        help="skip the git hooks (the MCP tools work without them)")
+    parser.set_defaults(run=run)
+
+
+def run(args: argparse.Namespace) -> str:
+    report = setup(repo_of(args), install_git_hooks=not args.no_hooks)
+    return _describe(report)
+
+
+def _describe(report: InitReport) -> str:
+    """Report the SKIPPED hooks too. An init that quietly installed two of three would
+    leave a project whose commits are only sometimes recorded, which is worse than none.
+
+    And say that re-running is the REPAIR. Hooks live in `.git/hooks`, which is untracked, so
+    a fresh clone has none — and a repository set up before the wiring moved to
+    `taskops.transports.hooks` has hook lines naming a command that no longer exists. Every
+    hook line ends in `|| true`, so that failure is completely silent; the only thing a person
+    can act on is knowing that `taskops init` again fixes it.
+    """
+    lines = [f"{'created' if report.created else 'already a'} taskops project at "
+             f"{report.root}"]
+    if report.adopted:
+        lines.append(f"adopted {report.adopted} change(s) from the committed log")
+    if report.hooks:
+        lines.append(f"hooks installed: {', '.join(report.hooks)}")
+    for skipped in report.skipped:
+        lines.append(f"hook skipped — {skipped}")
+    lines.append("")
+    lines.append("Register the MCP server with:")
+    lines.append("  claude mcp add taskops -- python3 -m taskops.transports.mcp")
+    return "\n".join(lines)

taskops/transports/cli/commands/log.py

@@ -0,0 +1,22 @@
+"""Read what the agent said while working on a card — reached as `taskops tasks log`.
+
+The top-level `taskops log` was one of the agent's, and the agent reads a card over MCP. The
+function is untouched: `tasks log` points straight at it.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from ....render import render_log
+from ....usecases import session_log
+from ._shared import repo_of
+
+__all__ = ["run"]
+
+
+def run(args: argparse.Namespace) -> str:
+    from ....usecases.log import MAX_ENTRIES
+
+    return render_log(session_log(repo_of(args), str(args.task),
+                                  limit=int(args.limit) or MAX_ENTRIES))

taskops/transports/cli/commands/plan.py

@@ -0,0 +1,43 @@
+"""Create tasks from a JSON file or stdin — reached as `taskops tasks plan`.
+
+JSON rather than flags: a plan is a nested structure with dependencies in it, and every
+attempt to express one in shell arguments turns into a worse JSON. `-` reads stdin, which is
+what makes `... | taskops tasks plan -` work from a script.
+
+The top-level `taskops plan` was the agent's, and agents have `taskops_plan`. The subparser
+went; the function is still the only creator of a card, which is what keeps a hand-typed card
+carrying the same event body a planned one does.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, cast
+
+from ...._errors import BadRequest
+from ....render import render_plan
+from ....usecases import plan as create
+from ._shared import repo_of
+
+__all__ = ["run"]
+
+
+def run(args: argparse.Namespace) -> str:
+    return render_plan(create(repo_of(args), _entries(str(args.source)),
+                              actor=str(args.actor)))
+
+
+def _entries(source: str) -> list[dict[str, Any]]:
+    raw = sys.stdin.read() if source == "-" else open(source, encoding="utf-8").read()
+    try:
+        parsed: object = json.loads(raw)
+    except json.JSONDecodeError as bad:
+        raise BadRequest(f"{source} is not valid JSON: {bad}") from bad
+    if isinstance(parsed, dict):
+        parsed = [cast("object", parsed)]
+    if not isinstance(parsed, list):
+        raise BadRequest("expected a JSON array of {title, spec, after?} objects")
+    items = cast("list[object]", parsed)
+    return [cast("dict[str, Any]", item) for item in items if isinstance(item, dict)]

taskops/transports/cli/commands/pushpull.py

@@ -0,0 +1,53 @@
+"""`taskops push` and `taskops pull` — sync against the remote instead of through git.
+
+Two commands in one module because they are one summary: both print the same four numbers,
+and a second module would be a second place to keep that sentence honest.
+
+A conflicted report is printed on its OWN line, after the summary, and the exit code stays 0.
+Nothing was lost — the refusal is the point — so this is a decision waiting for a person, not
+a failure; making it exit non-zero would break the `push && git push` line everyone writes.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from ....usecases import Exchange
+from ....usecases import pull as receive
+from ....usecases import push as send
+from ._shared import add_target, repo_of
+
+__all__ = ["register"]
+
+
+def register(sub: "argparse._SubParsersAction[argparse.ArgumentParser]") -> None:
+    pushing = sub.add_parser("push", help="send this board to the remote, then take theirs")
+    add_target(pushing)
+    pushing.add_argument("--force", action="store_true",
+                         help="overwrite a report the server refused to replace "
+                              "(whatever narration is on the server is lost)")
+    pushing.set_defaults(run=run_push)
+    pulling = sub.add_parser("pull", help="take the remote's events and reports")
+    add_target(pulling)
+    pulling.set_defaults(run=run_pull)
+
+
+def run_push(args: argparse.Namespace) -> str:
+    return _summary("pushed", send(repo_of(args), force=bool(args.force)))
+
+
+def run_pull(args: argparse.Namespace) -> str:
+    return _summary("pulled", receive(repo_of(args)))
+
+
+def _summary(verb: str, done: Exchange) -> str:
+    """Events both ways, reports both ways, then every stand-off in full."""
+    swap = done.reports
+    parts = [f"{done.accepted} event(s) out", f"{done.events_in} in"]
+    if done.unblocked:
+        parts.append(f"{len(done.unblocked)} now ready")
+    if swap.uploaded or swap.downloaded:
+        parts.append(f"reports {len(swap.uploaded)} up, {len(swap.downloaded)} down")
+    lines = [f"{verb}: " + ", ".join(parts)]
+    lines += [f"  ! {clash}" for clash in swap.conflicts]
+    return "\n".join(lines)

taskops/transports/cli/commands/recover.py

@@ -0,0 +1,30 @@
+"""`taskops recover` — hand back the cards of workers that died."""
+
+from __future__ import annotations
+
+import argparse
+
+from ....render import render_recover
+from ....usecases import recover as run_recovery
+from ._shared import add_target, repo_of
+
+__all__ = ["register"]
+
+
+def register(sub: "argparse._SubParsersAction[argparse.ArgumentParser]") -> None:
+    parser = sub.add_parser("recover", help="release cards held by workers that went silent")
+    add_target(parser)
+    parser.add_argument("--force", action="store_true",
+                        help="release even the workers still reporting")
+    parser.add_argument("--grace", type=float, default=0.0,
+                        help="seconds of silence to tolerate (default: the fleet's own grace)")
+    parser.add_argument("--actor", default="", help="who is recovering")
+    parser.set_defaults(run=run)
+
+
+def run(args: argparse.Namespace) -> str:
+    from ...._clock import HEARTBEAT_GRACE
+
+    return render_recover(run_recovery(
+        repo_of(args), actor=str(args.actor), force=bool(args.force),
+        grace=float(args.grace) or HEARTBEAT_GRACE))

taskops/transports/cli/commands/remote.py

@@ -0,0 +1,56 @@
+"""`taskops remote` — where this project syncs, and the token that proves who it is.
+
+With no subcommand it SHOWS, for the same reason `taskops tasks` lists: the thing you want
+nine times out of ten should not cost a second turn. What it shows never includes the token —
+it prints a length and nothing else, because the whole point of a terminal is that somebody
+may be looking at it, and this is the one value in the system that a screenshot leaks.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from ....usecases import add_remote, read_remote, remove_remote
+from ._shared import add_target, repo_of
+
+__all__ = ["register"]
+
+
+def register(sub: "argparse._SubParsersAction[argparse.ArgumentParser]") -> None:
+    parser = sub.add_parser("remote", help="show, set or drop the server this project syncs with")
+    add_target(parser)
+    parser.set_defaults(run=run_show, subcommand="")
+    inner = parser.add_subparsers(dest="subcommand", metavar="<subcommand>")
+    adding = inner.add_parser("add", help="register the one remote for this project")
+    adding.add_argument("url", help="the server's base URL, e.g. https://taskops.example.com")
+    adding.add_argument("--token", required=True, help="the bearer the server issued you")
+    add_target(adding, inherit=True)
+    adding.set_defaults(run=run_add)
+    dropping = inner.add_parser("remove", help="forget the remote and its token")
+    add_target(dropping, inherit=True)
+    dropping.set_defaults(run=run_remove)
+
+
+def run_show(args: argparse.Namespace) -> str:
+    found = read_remote(repo_of(args))
+    if found is None:
+        return ("no remote — this project syncs through git (`taskops sync`). Add one with "
+                "`taskops remote add <url> --token <token>`")
+    return (f"{found['url']}\n  token   {_masked(found['token'])}\n"
+            f"  cursor  seq {found['cursor']} of the server's log")
+
+
+def run_add(args: argparse.Namespace) -> str:
+    added = add_remote(repo_of(args), str(args.url), str(args.token))
+    return (f"remote set to {added['url']} — the token is in .taskops/remote.json (mode 0600, "
+            f"gitignored). `taskops push` to send this board up.")
+
+
+def run_remove(args: argparse.Namespace) -> str:
+    return f"remote {remove_remote(repo_of(args))} removed, token deleted"
+
+
+def _masked(token: str) -> str:
+    """Its LENGTH, never a prefix. A prefix is enough to recognise a token in a leaked log
+    and enough to confirm a guess, and it answers no question worth answering."""
+    return f"set ({len(token)} characters)" if token else "MISSING — the server will refuse"

taskops/transports/cli/commands/report.py

@@ -0,0 +1,82 @@
+"""`taskops report` — the generated views."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from ...._errors import BadRequest
+from ....render import render_board, render_day, render_fleet, render_standup
+from ....usecases import (
+    Selector,
+    board,
+    fleet,
+    period,
+    standup,
+    write_report,
+)
+from ._digest import stream_digest
+from ._shared import add_target, repo_of
+from ._window import selector
+
+__all__ = ["register", "DOSSIERS"]
+
+DOSSIERS = ("day", "range", "all")
+"""The kinds that cover a span of days and can therefore be written and narrated. `board` and
+`standup` cannot: one is a snapshot with no window, the other moves every time it is run."""
+
+
+def register(sub: "argparse._SubParsersAction[argparse.ArgumentParser]") -> None:
+    parser = sub.add_parser("report", help="board, standup, day, range, all, or fleet")
+    add_target(parser)
+    parser.add_argument("kind", nargs="?", default="board",
+                        choices=("board", "standup", "day", "range", "all", "fleet"))
+    parser.add_argument("--since", default="24h", help="standup window: 24h, 7d, 30m")
+    parser.add_argument("--date", default="today",
+                        help="which day the dossier covers: today, yesterday, YYYY-MM-DD")
+    parser.add_argument("--last", default="",
+                        help="range: how far back from --to, e.g. 7d, 2w, 1m")
+    parser.add_argument("--from", dest="from_date", default="",
+                        help="range: the first day, YYYY-MM-DD")
+    parser.add_argument("--to", default="",
+                        help="range: the last day (inclusive), YYYY-MM-DD; default today")
+    parser.add_argument("--actor", default="", help="restrict a standup to one actor")
+    parser.add_argument("--write", action="store_true",
+                        help="persist the dossier to .taskops/reports/<label>.md")
+    parser.add_argument("--force", action="store_true",
+                        help="with --write: regenerate a report that already exists")
+    parser.add_argument("--digest", action="store_true",
+                        help="write it, then have Claude narrate what it means "
+                             "(uses your logged-in subscription, never an API key)")
+    parser.add_argument("--model", default="",
+                        help="with --digest: the model to narrate with")
+    parser.set_defaults(run=run)
+
+
+def run(args: argparse.Namespace) -> str:
+    where = repo_of(args)
+    if args.kind not in DOSSIERS and (args.write or args.force or args.digest):
+        raise BadRequest("--write, --force and --digest only apply to `report day`, "
+                         "`report range` and `report all` — a board and a standup are "
+                         "regenerated on demand")
+    if args.kind == "standup":
+        return render_standup(standup(where, since=str(args.since), actor=str(args.actor)))
+    if args.kind in DOSSIERS:
+        return _dossier(args, where, selector(args))
+    if args.kind == "fleet":
+        return render_fleet(fleet(where))
+    return render_board(board(where))
+
+
+def _dossier(args: argparse.Namespace, where: Path, sel: Selector) -> str:
+    """Printed, or written and its PATH printed.
+
+    The path rather than the dossier: what the caller does next is read or commit that file,
+    and a command that dumps 300 lines it just saved makes the one useful line scroll away.
+    """
+    if args.digest:
+        return stream_digest(where, sel, kind=str(args.kind), model=str(args.model),
+                             force=bool(args.force))
+    if not args.write:
+        return render_day(period(where, sel))
+    return f"wrote {write_report(where, sel, force=bool(args.force))}"

taskops/transports/cli/commands/run_.py

@@ -0,0 +1,60 @@
+"""`taskops run` — the spawn path, under the name that says what it does.
+
+The capability existed as `dispatch --spawn`, which is how a flag hides a decision: a person
+scanning the help had no way to tell that one word turns a free preparation into N NEW billed
+Claude sessions. Same code, honest name, and the price stated BEFORE anything starts rather
+than on the invoice.
+
+`--yes` exists because a fleet script cannot answer a prompt. Everything else that reads a
+board is free; this is the one command that is not, so an unattended caller has to say so.
+
+`--use-api-key` is the other half of the same honesty. Workers do NOT inherit the Anthropic
+credentials (`engine.worker.DROPPED_ENV`), because an exported key silently outranks the
+subscription and turns every dispatched worker into a per-token invoice. This flag gives the
+capability back to whoever types it, which is the only person entitled to decide it. CLI only:
+no MCP tool can spend an API balance on the caller's behalf.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .dispatch import add_dispatch_args, dispatch_with
+
+__all__ = ["register", "WARNING"]
+
+WARNING = ("⚠ each worker is a NEW Claude session on your logged-in subscription, counting "
+           "against its limits — for free parallelism dispatch sub-agents from a session "
+           "(taskops_dispatch). Add --use-api-key to bill per token instead.")
+
+
+def register(sub: "argparse._SubParsersAction[argparse.ArgumentParser]") -> None:
+    parser = sub.add_parser("run",
+                            help="run cards with headless Claude workers (experimental, billed)")
+    add_dispatch_args(parser)
+    parser.add_argument("--yes", action="store_true",
+                        help="skip the confirmation (for unattended callers)")
+    parser.add_argument("--use-api-key", action="store_true", dest="use_api_key",
+                        help="let the workers see ANTHROPIC_API_KEY — they then BILL PER TOKEN "
+                             "instead of using your logged-in subscription")
+    parser.set_defaults(run=run)
+
+
+def run(args: argparse.Namespace) -> str:
+    """Warn, confirm, then spawn. A dry run is free, so it skips both."""
+    if not args.dry_run and not _confirmed(bool(args.yes)):
+        return "aborted — nothing started"
+    return dispatch_with(args, spawn=True)
+
+
+def _confirmed(yes: bool) -> bool:
+    """The warning goes to stderr so a piped render stays a render; the answer comes from
+    stdin, and no tty (a hook, a CI job) counts as "did not agree" rather than as yes."""
+    print(WARNING, file=sys.stderr)
+    if yes:
+        return True
+    try:
+        return input("start them? [y/N] ").strip().lower() in ("y", "yes")
+    except EOFError:
+        return False

taskops/transports/cli/commands/serve.py

@@ -0,0 +1,74 @@
+"""`taskops serve` — many projects' boards on one port, each behind its own token.
+
+`taskops ui` serves the repository you are standing in; this serves a DIRECTORY OF PROJECTS and
+is the thing meant to sit on a host. The difference that matters is not the routing — see
+`transports.http.projects` for that — it is the trust model: there is no ambient "it's only
+loopback" here, so every project has a secret and a project without one is not served.
+
+It runs no git hooks and no guard, and `serve init` creates the project with
+`install_git_hooks=False`: this is a store of boards, not a working tree. The code stays in git
+where it belongs; what centralises is the board, so that two agents racing for the same task
+compete inside ONE sqlite.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from ....transports.http import bound_port, mount, serve_route
+from ._serve_init import create
+
+__all__ = ["register"]
+
+DEFAULT_PORT = 2160
+DEFAULT_ROOT = "~/taskops-server"
+
+_HELP = "many projects' boards on one port, each behind a token"
+
+
+def register(sub: "argparse._SubParsersAction[argparse.ArgumentParser]") -> None:
+    parser = sub.add_parser("serve", help=_HELP)
+    _root(parser, inherit=False)
+    parser.add_argument("--host", default="127.0.0.1",
+                        help="bind address (default: loopback only)")
+    parser.add_argument("--port", type=int, default=DEFAULT_PORT)
+    parser.add_argument("--readonly", action="store_true",
+                        help="refuse every write, on every project")
+    parser.add_argument("--rate-limit", type=int, default=0, dest="rate_limit",
+                        help="requests per minute, 0 for none")
+    parser.set_defaults(run=run)
+    inner = parser.add_subparsers(dest="serve_command", metavar="<subcommand>")
+    created = inner.add_parser("init", help="create a project here and mint its token")
+    created.add_argument("project", help="its name and its URL segment: [a-z0-9-]")
+    _root(created, inherit=True)
+    created.set_defaults(run=run_init)
+
+
+def _root(parser: argparse.ArgumentParser, *, inherit: bool) -> None:
+    """`--root` on BOTH parsers, so `serve init x --root /srv` reads as naturally as
+    `serve --root /srv init x`. The subcommand's copy defaults to SUPPRESS, or argparse would
+    write its default over the value the parent already parsed."""
+    parser.add_argument("--root", default=argparse.SUPPRESS if inherit else DEFAULT_ROOT,
+                        help=f"the directory of projects (default: {DEFAULT_ROOT})")
+
+
+def run(args: argparse.Namespace) -> str:
+    """Blocks until interrupted. The banner goes to stderr, like `taskops ui`'s."""
+    root = Path(str(args.root)).expanduser().resolve()
+    route = mount(root, readonly=bool(args.readonly), rate_limit=int(args.rate_limit))
+    server = serve_route(str(args.host), int(args.port), route)
+    print(f"taskops serve → http://{args.host}:{bound_port(server)}/<project>/  ({root})"
+          + ("  [read-only]" if args.readonly else ""), file=sys.stderr)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("\nstopped", file=sys.stderr)
+    finally:
+        server.server_close()
+    return ""
+
+
+def run_init(args: argparse.Namespace) -> str:
+    return create(Path(str(args.root)).expanduser().resolve(), str(args.project))

taskops/transports/cli/commands/sync.py

@@ -0,0 +1,22 @@
+"""`taskops sync` — reconcile with what git brought in. Called from post-merge."""
+
+from __future__ import annotations
+
+import argparse
+
+from ....usecases import sync as reconcile
+from ._shared import add_target, repo_of
+
+__all__ = ["register"]
+
+
+def register(sub: "argparse._SubParsersAction[argparse.ArgumentParser]") -> None:
+    parser = sub.add_parser("sync", help="import and export the committed event log")
+    add_target(parser)
+    parser.set_defaults(run=run)
+
+
+def run(args: argparse.Namespace) -> str:
+    report = reconcile(repo_of(args))
+    unblocked = (f", {len(report.unblocked)} now ready" if report.unblocked else "")
+    return (f"synced: {report.imported} event(s) in, {report.exported} out{unblocked}")

taskops/transports/cli/commands/tasks.py

@@ -0,0 +1,79 @@
+"""`taskops tasks` — everything a person does to the task list, under one name.
+
+Almost nothing here is new behaviour: the subcommands reach `run` functions that already
+existed, and the two exceptions (`list`, `add`) are thin over `usecases.board` and
+`usecases.plan`. The grouping is for the reader of `--help`, which had grown to nineteen
+commands mixing three audiences — a person's task list, an agent's claim/update protocol,
+and the git and session plumbing that only a hook ever types. A person had to know which
+was which before they could find the one command they wanted.
+
+`taskops tasks` with no subcommand lists, because the list is what you want nine times out
+of ten and a group name that prints usage is a name that costs a second turn.
+"""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from ...._errors import BadRequest
+from ...._types import STATUSES
+from ....render import render_edit, render_plan, render_tasklist
+from ....usecases import board
+from ....usecases import edit as rewrite
+from ....usecases import plan as create
+from ._shared import add_actor, add_target, repo_of
+from ._tasks_args import add_list_flags, add_subcommands
+
+__all__ = ["register"]
+
+
+def register(sub: "argparse._SubParsersAction[argparse.ArgumentParser]") -> None:
+    parser = sub.add_parser("tasks", help="list, read, create and close tasks")
+    add_target(parser)
+    add_actor(parser)
+    add_list_flags(parser)
+    parser.set_defaults(run=run_list, subcommand="")
+    add_subcommands(parser, listing=run_list, adding=run_add, editing=run_edit)
+
+
+def run_list(args: argparse.Namespace) -> str:
+    """The list, filtered by what was asked for.
+
+    `--status` is validated HERE and not by argparse `choices`, so the refusal reads like
+    every other one in the package — the name that was rejected, then the legal values —
+    rather than argparse's usage dump, which buries the answer under the whole grammar.
+    """
+    status = getattr(args, "status", None)
+    if status is not None and status not in STATUSES:
+        raise BadRequest(f"`{status}` is not a status — use one of {', '.join(STATUSES)}")
+    return render_tasklist(board(repo_of(args)),
+                           show_all=bool(getattr(args, "all", False)), status=status)
+
+
+def run_add(args: argparse.Namespace) -> str:
+    """One card through the batch door.
+
+    `plan` stays the only creator even for a single task, so a card typed at a terminal
+    carries exactly the event body a planned one does — a second insert path here is how the
+    log would start holding two shapes of `created`, one of which another machine cannot
+    replay. The flags are read into the same dict `plan` takes from JSON, so `_entry` keeps
+    owning what every field means.
+    """
+    entry: dict[str, Any] = {
+        "title": str(args.title), "spec": str(args.spec),
+        "labels": str(args.labels), "files": str(args.files),
+        "after": [part.strip() for part in str(args.after).split(",") if part.strip()]}
+    if args.priority is not None:
+        entry["priority"] = int(args.priority)
+    return render_plan(create(repo_of(args), [entry], actor=str(args.actor)))
+
+
+def run_edit(args: argparse.Namespace) -> str:
+    """Rewrite a card. `None` means "not passed" all the way down, which is why the flags
+    default to it rather than to "": an empty spec is a legitimate edit (somebody clearing a
+    brief that was wrong), and a default of "" could not tell that from silence."""
+    return render_edit(rewrite(
+        repo_of(args), str(args.task), title=args.title, spec=args.spec,
+        priority=None if args.priority is None else int(args.priority),
+        actor=str(args.actor)))