@zumino/cli 2.1.0 → 2.2.0

package/src/spec.js

@@ -0,0 +1,1015 @@
+/*
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THE COMMAND SURFACE, DECLARED ONCE.
+ *
+ * Every command, every flag, every value a flag accepts. Five things read this
+ * file and nothing restates it:
+ *
+ *   1. `parseArgs` — its `options` map is derived from `FLAGS` (`parseOptions`).
+ *   2. validation — a flag not declared on the command is refused, and so is a
+ *      value outside the declared set (`flags.js`).
+ *   3. `--help` and `zumino help <command>` — rendered from here (`help.js`).
+ *   4. `zumino commands [--json]` — the whole surface, for an agent to read.
+ *   5. `test/cli-vocabulary.test.ts` in the app — holds `VALUES` against the
+ *      server's own `TASK_STATUSES`, `ENTRY_STATUSES`, `AUDIT_EVENT_KINDS` and
+ *      the rest, so a vocabulary that grows in the product cannot quietly stop
+ *      being offered here.
+ *
+ * **Why one table rather than help text beside each command.** The first
+ * version of this CLI documented its flags in a hand-written `USAGE` string and
+ * validated three of them. The result was the failure class this project
+ * already had a name for — a caller value the server silently drops — one flag
+ * at a time: `--status` on `find` went to the wire as a parameter the generic
+ * item read does not have, answered 200, and printed an unfiltered list as if
+ * it were a filtered one. Generated help cannot describe a flag the validator
+ * does not know about, and the validator cannot accept one the help does not
+ * list, because they are the same line of this file.
+ *
+ * **It imports nothing**, deliberately: the app's test suite imports it
+ * directly, and a `node:`-flavoured dependency here would drag the CLI's
+ * runtime into a vitest process that has no business loading it.
+ *
+ * ── The one rule about filters ──────────────────────────────────────────────
+ *
+ * **Every filter here is a filter the API performs.** Nothing in this CLI
+ * narrows a list locally. A client-side filter reads identically to a
+ * server-side one and is wrong in a way nobody can see: it filters the page it
+ * was handed, so `--limit 50` plus a local filter silently answers from the
+ * first fifty rows rather than from the project. Where the API has no filter,
+ * this file has no flag — see `epic list`, which is unpaginated and unfiltered
+ * on the server and therefore here too.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+
+/**
+ * The vocabularies the server owns, copied here so a value can be refused
+ * before it is sent rather than ignored after.
+ *
+ * A copy is a liability, so it is held in step mechanically:
+ * `test/cli-vocabulary.test.ts` fails when any list here disagrees with the
+ * constant it mirrors. Adding a status to the product is one line there and one
+ * line here, in the same pull request.
+ */
+export const VALUES = {
+  /** `src/lib/item-kind.ts` */
+  itemKind: ["request", "task", "epic"],
+  /** Derived from `closedAt` by the generic spine read — not a status. */
+  itemState: ["open", "closed"],
+  itemSort: ["updated", "new", "code"],
+
+  /** `TASK_STATUSES` in `src/lib/task-meta.ts` */
+  taskStatus: [
+    "backlog",
+    "todo",
+    "shaping",
+    "in_progress",
+    "in_review",
+    "done",
+    "wont_do",
+  ],
+  /** `TASK_TYPES` */
+  taskType: ["feature", "bug", "improvement", "refactor", "investigation", "chore"],
+  /** `TASK_PRIORITIES` */
+  taskPriority: ["critical", "high", "normal", "low"],
+  /** `TASK_SIZES` */
+  taskSize: ["S", "M", "L", "XL"],
+  /** `TASK_CLARITIES` */
+  taskClarity: ["well_defined", "needs_investigation", "exploratory"],
+  taskSort: ["priority", "new", "updated", "manual"],
+
+  /** `ENTRY_STATUSES` in `src/lib/entry-meta.ts` */
+  requestStatus: ["open", "planned", "in_progress", "done", "wont_do"],
+  /** `ENTRY_TYPES` */
+  requestType: ["feature", "bug", "improvement", "idea"],
+  requestSort: ["top", "new"],
+
+  /** `EPIC_STATUSES` in `src/lib/epic-meta.ts` */
+  epicStatus: ["open", "in_progress", "done", "wont_do"],
+
+  /** `AUDIT_EVENT_KINDS` in `src/lib/audit-event-meta.ts` */
+  eventKind: [
+    "created",
+    "field",
+    "status",
+    "spec",
+    "attention",
+    "tag",
+    "link",
+    "ref",
+    "attachment",
+    "detached",
+    "pin",
+    "response",
+    "promoted",
+  ],
+
+  /** The link vocabulary as a person says it, `task link` maps it to the API's. */
+  linkType: ["blocks", "blocked-by", "related", "answers"],
+
+  boolean: ["true", "false"],
+};
+
+/**
+ * Every flag the CLI understands, with the one-line help it is documented by.
+ *
+ * `type` is `parseArgs`'s. `multiple` means the flag may be repeated — and that
+ * `parseArgs` hands back an array, which is why a command that takes one value
+ * reads it through `oneValue()` rather than trusting the shape.
+ *
+ * A command overrides `help` and adds `values` where the accepted set depends on
+ * which list is being read: `--kind` is an item kind on `find` and an event kind
+ * on `task events`, and `--status` has three different vocabularies.
+ */
+export const FLAGS = {
+  // --- global ---------------------------------------------------------------
+  json: { type: "boolean", help: "print the API's own JSON instead of a table" },
+  host: { type: "string", arg: "URL", help: "the Zumino server to talk to" },
+  token: { type: "string", arg: "TOKEN", help: "a personal access token, used for this call only" },
+  account: { type: "string", arg: "NAME", help: "use a stored account by name" },
+  project: { type: "string", arg: "SLUG", help: "the project to act in" },
+  workspace: { type: "string", arg: "SLUG", help: "the workspace to act in" },
+  help: { type: "boolean", short: "h", help: "this page" },
+  version: { type: "boolean", help: "print the CLI version" },
+
+  // --- paging and search ----------------------------------------------------
+  limit: {
+    type: "string",
+    arg: "N",
+    numeric: "positive",
+    help: "how many rows to return (1–200, default 50)",
+  },
+  offset: {
+    type: "string",
+    arg: "N",
+    numeric: "nonNegative",
+    help: "skip N rows — page with it, not by raising --limit",
+  },
+  query: { type: "string", short: "q", arg: "TEXT", help: "match title and description" },
+  sort: { type: "string", arg: "ORDER", help: "the order rows come back in" },
+
+  // --- filters --------------------------------------------------------------
+  kind: { type: "string", arg: "KIND", multiple: true, help: "narrow by kind" },
+  state: { type: "string", arg: "STATE", help: "open or closed" },
+  status: { type: "string", arg: "STATUS", multiple: true, help: "narrow by status" },
+  type: { type: "string", arg: "TYPE", help: "narrow by type" },
+  priority: { type: "string", arg: "PRIORITY", help: "narrow by priority" },
+  assignee: { type: "string", arg: "USER", shape: "user", help: "a user id, or `me`" },
+  tag: { type: "string", arg: "TAG_ID", help: "a tag id — list them with: zumino project tags" },
+  epic: { type: "string", arg: "E<n>", help: "an epic in this project, or `none` for the ungrouped" },
+  "needs-input": { type: "boolean", help: "only what is waiting on a person" },
+  open: { type: "boolean", help: "hide closed rows" },
+  field: { type: "string", arg: "FIELD", help: "narrow to one field that moved, e.g. status" },
+  before: { type: "string", arg: "CURSOR", help: "the `nextBefore` from the previous page" },
+  activity: { type: "boolean", help: "fold the activity log into the brief" },
+
+  // --- item fields ----------------------------------------------------------
+  title: { type: "string", arg: "TEXT", help: "the title" },
+  description: { type: "string", arg: "TEXT", help: "markdown; empty clears it" },
+  size: { type: "string", arg: "SIZE", help: "rough size" },
+  clarity: { type: "string", arg: "CLARITY", help: "how well understood the work is" },
+  reviewer: {
+    type: "string",
+    arg: "USER",
+    shape: "user",
+    clearable: true,
+    help: "who reviews it — a user id, `me`, or `-` to clear",
+  },
+  pinned: { type: "string", arg: "BOOL", help: "pin the request to the top of the public board" },
+  plan: { type: "string", arg: "TEXT", help: "the plan — how this gets done" },
+  acceptance: { type: "string", arg: "TEXT", help: "the acceptance criteria — when it is done" },
+  url: { type: "string", arg: "URL", help: "the pull request, commit or issue" },
+  body: { type: "string", arg: "TEXT", help: "the text, when it is easier to pass as a flag" },
+  to: { type: "string", arg: "SLUG", help: "the work project the task is filed in" },
+
+  // --- housekeeping ---------------------------------------------------------
+  dir: { type: "string", arg: "PATH", help: "where to install the skill" },
+  check: { type: "boolean", help: "report whether the installed skill is current; write nothing" },
+  yes: { type: "boolean", short: "y", help: "do not ask" },
+};
+
+/**
+ * The flags every command takes, so no command declares them.
+ *
+ * They are how a call is addressed rather than what it does — which credential,
+ * which host, which project, and whether the answer is for a person or for
+ * `jq`. `zumino auth status` says which of them won.
+ */
+export const GLOBAL_FLAGS = [
+  "json",
+  "host",
+  "token",
+  "account",
+  "project",
+  "workspace",
+  "help",
+];
+
+/*
+ * ── The commands ────────────────────────────────────────────────────────────
+ *
+ * Shape is `DOMAIN.md`'s rule and not a style choice: **generic reads span
+ * every kind and are top-level; every write names its kind.** So `queue`,
+ * `context` and `find` are verbs at the root, and everything that touches one
+ * kind hangs off that kind's noun — which is also why a fourth kind would add a
+ * noun rather than widen a flat verb list every script has already learned.
+ *
+ * A noun's own list (`task list`, `request list`) sits under the noun for the
+ * same reason: it reads that kind's detail endpoint, with that kind's
+ * vocabulary, and publishes fields `find` deliberately does not have.
+ */
+
+/** @typedef {{name: string, summary: string, usage?: string, args?: Array<[string,string]>, flags?: Record<string, object>, rejects?: Record<string, {message: string, hint?: string}>, examples?: string[], notes?: string, group?: string, subcommands?: any[]}} Command */
+
+/** @type {Command[]} */
+export const COMMANDS = [
+  // --- orientation ----------------------------------------------------------
+  {
+    name: "workspace",
+    group: "orient",
+    summary: "the workspaces you belong to",
+    subcommands: [
+      {
+        name: "list",
+        summary: "every workspace the token's owner belongs to, and their role in each",
+        usage: "zumino workspace list",
+        notes:
+          "The bootstrap read. Every other path carries a workspace segment, so " +
+          "a fresh token cannot build a single URL until this one has answered. " +
+          "`role` comes with it because it is what predicts whether a " +
+          "moderator-only write will be refused.",
+        examples: [
+          "zumino workspace list",
+          "zumino workspace list --json | jq -r '.[].slug'",
+        ],
+      },
+    ],
+  },
+  {
+    name: "project",
+    group: "orient",
+    summary: "the projects you can reach, and what is in one",
+    subcommands: [
+      {
+        name: "list",
+        summary: "every project you can reach, with its workspace, type and size",
+        usage: "zumino project list [--workspace SLUG]",
+        notes:
+          "One of the two genuinely cross-workspace reads, so it is narrowed by " +
+          "`--workspace` rather than addressed under one. A feedback project has " +
+          "no key and holds requests; a work project has a key and holds tasks " +
+          "and epics — which is what decides whether `zumino task …` or " +
+          "`zumino request …` is the right half of the CLI.",
+        examples: [
+          "zumino project list",
+          "zumino project list --workspace acme",
+          "zumino project list --json | jq -r '.[] | select(.type==\"work\") | .slug'",
+        ],
+      },
+      {
+        name: "show",
+        summary: "one project, its type, its key and its counters",
+        usage: "zumino project show [<slug>]",
+        args: [["<slug>", "the project; defaults to the resolved --project"]],
+        examples: ["zumino project show acme-app", "zumino project show"],
+      },
+      {
+        name: "tags",
+        summary: "the project's tag palette — the ids `--tag` takes",
+        usage: "zumino project tags [<slug>]",
+        args: [["<slug>", "the project; defaults to the resolved --project"]],
+        notes:
+          "A tag is filtered by id, not by name, so this is the read that makes " +
+          "`--tag` usable at all.",
+        examples: [
+          "zumino project tags",
+          "zumino project tags --json | jq -r '.[] | select(.name==\"infra\") | .id'",
+        ],
+      },
+    ],
+  },
+
+  // --- reads across every kind ---------------------------------------------
+  {
+    name: "queue",
+    group: "read",
+    summary: "what to work on next, across every project you can reach",
+    usage: "zumino queue [--needs-input] [--limit N]",
+    flags: {
+      "needs-input": { help: "tasks waiting on you, instead of tasks you can pick up" },
+      limit: true,
+    },
+    notes:
+      "Availability is computed rather than read off a column: committed, " +
+      "shaped, and unblocked. So an empty answer is a finding — the specs are " +
+      "below the bar or their blockers are open — and this command says which " +
+      "rather than printing nothing.",
+    examples: [
+      "zumino queue",
+      "zumino queue --needs-input",
+      "zumino queue --workspace acme --limit 5",
+    ],
+  },
+  {
+    name: "context",
+    group: "read",
+    summary: "the whole brief for one task, as one markdown document",
+    usage: "zumino context <CODE> [--activity]",
+    args: [["<CODE>", "a task — `ACME-14`, or `14` with a project resolved"]],
+    flags: { activity: true },
+    notes:
+      "The epic, the description, the plan, the acceptance criteria, the " +
+      "blockers and the requests it answers, assembled by the server. Prefer it " +
+      "over six reads not to save round trips but because an agent that " +
+      "assembles its own brief assembles a plausible one rather than the real " +
+      "one. Readiness goes to stderr, so the document alone is what a pipe sees.",
+    examples: ["zumino context ACME-14", "zumino context ACME-14 --activity"],
+  },
+  {
+    name: "find",
+    group: "read",
+    summary: "one search across every kind of item",
+    usage: "zumino find [<text>] [filters]",
+    args: [["<text>", "matched against title and description; same as --query"]],
+    flags: {
+      kind: { values: "itemKind", help: "request, task or epic — repeatable, or comma-separated" },
+      state: { values: "itemState" },
+      assignee: true,
+      query: true,
+      sort: { values: "itemSort", help: "default: updated" },
+      offset: true,
+      limit: true,
+    },
+    rejects: {
+      status: {
+        message:
+          "find has no --status: the read that spans every kind publishes only open/closed.",
+        hint:
+          "Did you mean --state open? For a per-kind status, use that kind's own " +
+          "list: zumino task list --status in_progress.",
+      },
+      priority: {
+        message: "find has no --priority: priority belongs to tasks, not to every kind.",
+        hint: "Use: zumino task list --priority high",
+      },
+    },
+    notes:
+      "Scoped to a project when one is resolved, and to the whole workspace " +
+      "when not. It reads the spine shape, which deliberately publishes no " +
+      "per-kind status (docs/decisions/0003) — hence STATE rather than STATUS, " +
+      "and hence `task list` for anything a task alone has.",
+    examples: [
+      "zumino find \"rate limit\"",
+      "zumino find --kind task,epic --state open",
+      "zumino find --assignee me --sort new --limit 10",
+      "zumino find --json | jq -r '.[].code'",
+    ],
+  },
+
+  // --- work -----------------------------------------------------------------
+  {
+    name: "task",
+    group: "work",
+    summary: "the work layer of a work project — read it, file it, move it",
+    subcommands: [
+      {
+        name: "list",
+        summary: "the project's tasks, with every filter the board itself has",
+        usage: "zumino task list [<text>] [filters]",
+        args: [["<text>", "matched against title and description; same as --query"]],
+        flags: {
+          status: {
+            values: "taskStatus",
+            help: "repeatable, or comma-separated — e.g. --status todo,in_progress",
+          },
+          type: { values: "taskType" },
+          priority: { values: "taskPriority" },
+          assignee: true,
+          epic: true,
+          tag: true,
+          "needs-input": { help: "only tasks flagged as waiting on a person" },
+          open: true,
+          query: true,
+          sort: { values: "taskSort", help: "default: priority" },
+          offset: true,
+          limit: true,
+        },
+        notes:
+          "`--sort manual` is the stored order — what the board draws and what " +
+          "somebody dragged it into. It is the read half of hand-ordering, which " +
+          "was a write with no read until it was published here.",
+        examples: [
+          "zumino task list",
+          "zumino task list --status todo,in_progress --priority high",
+          "zumino task list --assignee me --open",
+          "zumino task list --epic E3 --sort manual",
+          "zumino task list --tag $(zumino project tags --json | jq -r '.[0].id')",
+          "zumino task list --status done --limit 100 --offset 100",
+        ],
+      },
+      {
+        name: "show",
+        summary: "one task: status, priority, assignee and description",
+        usage: "zumino task show <CODE>",
+        args: [["<CODE>", "`ACME-14`, or `14` with a project resolved"]],
+        examples: ["zumino task show ACME-14", "zumino task show 14 --json"],
+      },
+      {
+        name: "events",
+        summary: "what has been done to this task, newest first",
+        usage: "zumino task events <CODE> [--kind KIND] [--field FIELD]",
+        args: [["<CODE>", "the task"]],
+        flags: {
+          kind: { values: "eventKind", help: "one kind of change" },
+          field: { help: "one field that moved, e.g. status, priority, assigneeId" },
+          limit: true,
+          before: true,
+        },
+        notes:
+          "The counterpart to the comment thread: that records what people said, " +
+          "this records what anyone — person or agent — actually did. Read it " +
+          "before picking a task up: \"what was tried and then reverted\" is the " +
+          "context an executor otherwise has no way to recover, and re-doing an " +
+          "abandoned approach is the usual cost of not having it.",
+        examples: [
+          "zumino task events ACME-14",
+          "zumino task events ACME-14 --field status",
+          "zumino task events ACME-14 --kind spec --json",
+        ],
+      },
+      {
+        name: "create",
+        summary: "file a task",
+        usage: "zumino task create --title T [fields]",
+        args: [["<text>", "the title, if --title is not given"]],
+        flags: {
+          title: true,
+          description: {
+            help: "what this is, a couple of paragraphs — half the bar for the queue",
+          },
+          type: { values: "taskType" },
+          priority: { values: "taskPriority" },
+          status: { values: "taskStatus", help: "defaults to backlog" },
+          size: { values: "taskSize" },
+          clarity: { values: "taskClarity" },
+          assignee: { clearable: true, help: "a user id, or `me`" },
+          epic: { help: "an epic in this project — E3 or 3" },
+        },
+        notes:
+          "A title is the only requirement: capture has to be cheap or it does " +
+          "not happen. A description plus acceptance criteria is what puts the " +
+          "task in `zumino queue` — write them with `zumino task spec`.",
+        examples: [
+          "zumino task create --title \"Retry the webhook\"",
+          "zumino task create --title \"Fix the 429\" --type bug --priority high --epic E3",
+        ],
+      },
+      {
+        name: "edit",
+        summary: "change any field on a task, in one call",
+        usage: "zumino task edit <CODE> [fields]",
+        args: [["<CODE>", "the task"]],
+        flags: {
+          title: true,
+          description: true,
+          type: { values: "taskType" },
+          status: { values: "taskStatus" },
+          priority: { values: "taskPriority" },
+          size: { values: "taskSize", clearable: true, help: "rough size, or `-` to clear" },
+          clarity: { values: "taskClarity", clearable: true, help: "or `-` to clear" },
+          assignee: { clearable: true, help: "a user id, `me`, or `-` to clear" },
+          reviewer: true,
+          epic: { help: "E3 or 3, or `none` to detach" },
+        },
+        notes:
+          "One PATCH, so three fields are one audit group and render as one " +
+          "sentence in the history. Only what is named is sent: a flag left out " +
+          "is untouched, and an empty value clears a field that is allowed to be " +
+          "empty. `zumino task status` and `zumino task assign` stay because they " +
+          "are the two an agent does constantly and they want to be three words.",
+        examples: [
+          "zumino task edit ACME-14 --priority critical --status in_progress",
+          "zumino task edit ACME-14 --size L --clarity needs_investigation",
+          "zumino task edit ACME-14 --epic none",
+        ],
+      },
+      {
+        name: "status",
+        summary: "move a task",
+        usage: "zumino task status <CODE> <status>",
+        args: [["<CODE>", "the task"], ["<status>", VALUES.taskStatus.join(" · ")]],
+        examples: ["zumino task status ACME-14 in_progress", "zumino task status ACME-14 done"],
+      },
+      {
+        name: "assign",
+        summary: "set or clear the assignee",
+        usage: "zumino task assign <CODE> <userId|me|->",
+        args: [
+          ["<CODE>", "the task"],
+          ["<userId|me|->", "a user id, `me`, or `-` to clear"],
+        ],
+        notes:
+          "An assignee is always a person, even when an agent does the work. " +
+          "There is no delegation object and no executor registry: an agent reads " +
+          "the queue, pulls the brief, and writes back through the endpoints a " +
+          "person uses.",
+        examples: ["zumino task assign ACME-14 me", "zumino task assign ACME-14 -"],
+      },
+      {
+        name: "spec",
+        summary: "write the plan, or the acceptance criteria",
+        usage: "zumino task spec <CODE> --plan TEXT | --acceptance TEXT",
+        args: [["<CODE>", "the task"]],
+        flags: { plan: true, acceptance: true },
+        notes:
+          "One section per call, on purpose: an agent redrafting the plan must " +
+          "not be able to touch the criteria it will be judged against. An empty " +
+          "value clears the section.",
+        examples: [
+          "zumino task spec ACME-14 --plan \"$(cat plan.md)\"",
+          "zumino task spec ACME-14 --acceptance \"429 answers carry Retry-After\"",
+        ],
+      },
+      {
+        name: "comment",
+        summary: "say something on a task",
+        usage: "zumino task comment <CODE> <text>",
+        args: [["<CODE>", "the task"], ["<text>", "the comment"]],
+        flags: { body: true },
+        examples: ["zumino task comment ACME-14 \"Blocked on the migration\""],
+      },
+      {
+        name: "link",
+        summary: "relate two items",
+        usage: "zumino task link <CODE> <blocks|blocked-by|related|answers> <CODE|project#N>",
+        args: [
+          ["<CODE>", "the task the link is described from"],
+          ["<type>", VALUES.linkType.join(" · ")],
+          ["<CODE|project#N>", "the far end — `answers` takes a request, written project#N"],
+        ],
+        notes:
+          "`blocks` and `blocked-by` are the same stored row read from either " +
+          "end. `answers` says this work exists because of a request — the " +
+          "request is not consumed and does not change kind (docs/decisions/0002).",
+        examples: [
+          "zumino task link ACME-14 blocked-by ACME-9",
+          "zumino task link ACME-14 answers acme-board#42",
+        ],
+      },
+      {
+        name: "ref",
+        summary: "attach the pull request that answers the task",
+        usage: "zumino task ref <CODE> --url URL [--title T]",
+        args: [["<CODE>", "the task"]],
+        flags: { url: true, title: { help: "what to call it" } },
+        examples: ["zumino task ref ACME-14 --url https://github.com/acme/app/pull/99"],
+      },
+      {
+        name: "attention",
+        summary: "flag a task as waiting on a person, or clear the flag",
+        usage: "zumino task attention <CODE> [reason|-]",
+        args: [["<CODE>", "the task"], ["[reason|-]", "why it is stuck; `-` or nothing clears it"]],
+        notes: "What `zumino queue --needs-input` answers with.",
+        examples: [
+          "zumino task attention ACME-14 \"Which bucket should this charge?\"",
+          "zumino task attention ACME-14 -",
+        ],
+      },
+      {
+        name: "tag",
+        summary: "put a tag on a task",
+        usage: "zumino task tag <CODE> <tagId>",
+        args: [["<CODE>", "the task"], ["<tagId>", "from: zumino project tags"]],
+        examples: ["zumino task tag ACME-14 tag_abc123"],
+      },
+      {
+        name: "untag",
+        summary: "take a tag off a task",
+        usage: "zumino task untag <CODE> <tagId>",
+        args: [["<CODE>", "the task"], ["<tagId>", "from: zumino project tags"]],
+        examples: ["zumino task untag ACME-14 tag_abc123"],
+      },
+    ],
+  },
+  {
+    name: "request",
+    group: "work",
+    summary: "what people asked for, on a feedback project",
+    subcommands: [
+      {
+        name: "list",
+        summary: "the project's requests, filtered",
+        usage: "zumino request list [<text>] [filters]",
+        args: [["<text>", "matched against title and description; same as --query"]],
+        flags: {
+          status: {
+            values: "requestStatus",
+            help: "repeatable, or comma-separated — e.g. --status open,planned",
+          },
+          type: { values: "requestType" },
+          tag: true,
+          query: true,
+          sort: { values: "requestSort", help: "default: top, which is most voted" },
+          offset: true,
+          limit: true,
+        },
+        examples: [
+          "zumino request list",
+          "zumino request list --status open --sort top --limit 10",
+          "zumino request list \"dark mode\" --json",
+        ],
+      },
+      {
+        name: "show",
+        summary: "one request: status, votes and the words as written",
+        usage: "zumino request show <#N|CODE>",
+        args: [["<#N|CODE>", "`#42` on a feedback project, which has no key"]],
+        examples: ["zumino request show 42"],
+      },
+      {
+        name: "events",
+        summary: "the request's history — moderator-only",
+        usage: "zumino request events <#N|CODE> [--kind KIND] [--field FIELD]",
+        args: [["<#N|CODE>", "the request"]],
+        flags: {
+          kind: { values: "eventKind", help: "one kind of change" },
+          field: true,
+          limit: true,
+          before: true,
+        },
+        notes:
+          "Answers 404 rather than 403 to anyone who does not moderate the " +
+          "project: the history carries actor names, both sides of the internal " +
+          "note, and every decision that was reverted.",
+        examples: ["zumino request events 42", "zumino request events 42 --kind response"],
+      },
+      {
+        name: "create",
+        summary: "file a request",
+        usage: "zumino request create --title T [--description D] [--type TYPE]",
+        args: [["<text>", "the title, if --title is not given"]],
+        flags: { title: true, description: true, type: { values: "requestType" } },
+        examples: ["zumino request create --title \"Dark mode\" --type idea"],
+      },
+      {
+        name: "edit",
+        summary: "change a request's words, type, status or pinning",
+        usage: "zumino request edit <#N|CODE> [fields]",
+        args: [["<#N|CODE>", "the request"]],
+        flags: {
+          title: true,
+          description: true,
+          type: { values: "requestType" },
+          status: { values: "requestStatus" },
+          pinned: { values: "boolean" },
+        },
+        notes:
+          "The words are the author's or a moderator's; the status and the " +
+          "pinning are a moderator's. Only what is named is sent.",
+        examples: [
+          "zumino request edit 42 --type bug",
+          "zumino request edit 42 --pinned true",
+        ],
+      },
+      {
+        name: "answer",
+        summary: "post a comment and mark it the official answer",
+        usage: "zumino request answer <#N|CODE> <text>",
+        args: [["<#N|CODE>", "the request"], ["<text>", "the answer"]],
+        flags: { body: true },
+        notes:
+          "Two calls, because the API models it as two things: at most one " +
+          "comment on a request may be official, so the answer is a comment that " +
+          "has been designated rather than a field. If the second call is " +
+          "refused, the failure says so and names the comment that was already " +
+          "posted — never re-run it, or a second comment lands on a public board.",
+        examples: ["zumino request answer 42 \"Shipping in 2.3 — tracked as ACME-51.\""],
+      },
+      {
+        name: "status",
+        summary: "decide a request",
+        usage: "zumino request status <#N|CODE> <status>",
+        args: [["<#N|CODE>", "the request"], ["<status>", VALUES.requestStatus.join(" · ")]],
+        notes: "Owner or admin only. `done` and `wont_do` close the item.",
+        examples: ["zumino request status 42 planned"],
+      },
+      {
+        name: "note",
+        summary: "write the team's internal note, which the public never sees",
+        usage: "zumino request note <#N|CODE> <text|->",
+        args: [["<#N|CODE>", "the request"], ["<text|->", "the note; `-` clears it"]],
+        examples: ["zumino request note 42 \"Third report this month.\""],
+      },
+      {
+        name: "comment",
+        summary: "comment on a request, without marking it the answer",
+        usage: "zumino request comment <#N|CODE> <text>",
+        args: [["<#N|CODE>", "the request"], ["<text>", "the comment"]],
+        flags: { body: true },
+        examples: ["zumino request comment 42 \"Which browser?\""],
+      },
+      {
+        name: "promote",
+        summary: "file work that answers a request",
+        usage: "zumino request promote <#N|CODE> --to <work-project>",
+        args: [["<#N|CODE>", "the request"]],
+        flags: { to: true },
+        notes:
+          "A request never becomes a task (docs/decisions/0002). This creates a " +
+          "task that answers it, and both go on living — which is why the " +
+          "destination is `--to` and not `--project`: `--project` names where the " +
+          "request lives.",
+        examples: ["zumino request promote 42 --to acme-app"],
+      },
+      {
+        name: "tag",
+        summary: "put a tag on a request",
+        usage: "zumino request tag <#N|CODE> <tagId>",
+        args: [["<#N|CODE>", "the request"], ["<tagId>", "from: zumino project tags"]],
+        examples: ["zumino request tag 42 tag_abc123"],
+      },
+      {
+        name: "untag",
+        summary: "take a tag off a request",
+        usage: "zumino request untag <#N|CODE> <tagId>",
+        args: [["<#N|CODE>", "the request"], ["<tagId>", "from: zumino project tags"]],
+        examples: ["zumino request untag 42 tag_abc123"],
+      },
+    ],
+  },
+  {
+    name: "epic",
+    group: "work",
+    summary: "the outcomes a project is organised around",
+    subcommands: [
+      {
+        name: "list",
+        summary: "every epic in the project, with progress",
+        usage: "zumino epic list",
+        notes:
+          "Unfiltered and unpaginated, because the endpoint is: epics are the " +
+          "handful of outcomes a project is organised around, not its inventory. " +
+          "A project with enough of them to need a page has stopped using them as " +
+          "groupings. Filter the tasks under one instead: `zumino task list " +
+          "--epic E3`.",
+        examples: ["zumino epic list", "zumino epic list --json"],
+      },
+      {
+        name: "show",
+        summary: "one epic and how far through it is",
+        usage: "zumino epic show <E<n>|CODE>",
+        args: [["<E<n>|CODE>", "`E3`, or `ACME-E3`"]],
+        examples: ["zumino epic show E3"],
+      },
+      {
+        name: "create",
+        summary: "name an outcome",
+        usage: "zumino epic create --title T [--description D]",
+        args: [["<text>", "the title, if --title is not given"]],
+        flags: {
+          title: true,
+          description: {
+            help: "the brief for the whole outcome — handed to whoever works any task under it",
+          },
+          status: { values: "epicStatus", help: "defaults to open" },
+          assignee: { clearable: true, help: "who owns the outcome — a user id or `me`" },
+        },
+        examples: ["zumino epic create --title \"Make the API boring\""],
+      },
+      {
+        name: "edit",
+        summary: "change an epic's title, brief, status or owner",
+        usage: "zumino epic edit <E<n>|CODE> [fields]",
+        args: [["<E<n>|CODE>", "the epic"]],
+        flags: {
+          title: true,
+          description: true,
+          status: { values: "epicStatus" },
+          assignee: { clearable: true, help: "a user id, `me`, or `-` to clear" },
+        },
+        notes:
+          "There is no delete: retire an epic with `wont_do`, which keeps the " +
+          "record of what was decided against.",
+        examples: ["zumino epic edit E3 --status in_progress"],
+      },
+      {
+        name: "status",
+        summary: "move an epic",
+        usage: "zumino epic status <E<n>|CODE> <status>",
+        args: [["<E<n>|CODE>", "the epic"], ["<status>", VALUES.epicStatus.join(" · ")]],
+        examples: ["zumino epic status E3 done"],
+      },
+    ],
+  },
+
+  // --- everything else ------------------------------------------------------
+  {
+    name: "api",
+    group: "meta",
+    summary: "call any endpoint, including ones newer than this CLI",
+    usage: "zumino api <METHOD> <PATH> [--body JSON]",
+    args: [
+      ["<METHOD>", "GET · POST · PATCH · PUT · DELETE · HEAD"],
+      ["<PATH>", "below /api/v1, e.g. /queue or /workspaces/acme/items/ACME-14"],
+    ],
+    flags: { body: { help: "the request body, as JSON" } },
+    notes:
+      "Not a fallback for a missing command; it is what keeps the verb layer " +
+      "small enough to be worth learning. It is also why the server's `CLI_MIN` " +
+      "moves only for a breaking change: an old CLI reaches a new endpoint the " +
+      "day it ships. `zumino api GET /openapi.json` enumerates everything.",
+    examples: [
+      "zumino api GET /openapi.json",
+      "zumino api POST /workspaces/acme/projects/acme-app/tasks/14/vote",
+      "zumino api PUT /workspaces/acme/projects/acme-app/tasks/14/position --body '{\"after\":9}'",
+    ],
+  },
+  {
+    name: "auth",
+    group: "meta",
+    summary: "tokens, accounts, and which one is being used",
+    subcommands: [
+      {
+        name: "login",
+        summary: "store a token under an account name",
+        usage: "zumino auth login [--host URL] [--token TOKEN] [--account NAME]",
+        flags: { token: true, account: { help: "what to call this account locally" }, host: true },
+        notes:
+          "Nothing becomes \"current\": there is no stored active account and no " +
+          "`switch`, so two agents in two checkouts cannot change each other's " +
+          "identity (docs/decisions/0006). Tie a repository to an account with " +
+          "`zumino init`.",
+        examples: [
+          "zumino auth login --host https://zumino.cc",
+          "echo $TOKEN | zumino auth login --host https://zumino.cc --account ci",
+        ],
+      },
+      {
+        name: "status",
+        summary: "who you are acting as, on which host, and why that credential won",
+        usage: "zumino auth status",
+        notes:
+          "The first call to make in a session, and the answer to \"whoami\". It " +
+          "reports the resolved host and project, whether the token is " +
+          "read-only — checked here rather than discovered through a 403 halfway " +
+          "through a run of writes — and exits 3 if this CLI is too old for the " +
+          "server.",
+        examples: ["zumino auth status", "zumino auth status --json"],
+      },
+      {
+        name: "list",
+        summary: "the accounts stored on this machine",
+        usage: "zumino auth list",
+        examples: ["zumino auth list"],
+      },
+      {
+        name: "logout",
+        summary: "forget a stored account",
+        usage: "zumino auth logout [--account NAME] [-y]",
+        flags: { account: true, yes: true },
+        examples: ["zumino auth logout --account ci"],
+      },
+    ],
+  },
+  {
+    name: "init",
+    group: "meta",
+    summary: "tie this repository to an account, a host and a project",
+    usage: "zumino init [-y]",
+    flags: { yes: true },
+    notes:
+      "Writes `.zumino.json`, which is the first thing the resolution chain " +
+      "reads. It names a host, a workspace and a project — never a credential " +
+      "and never an account, because a file in a repository must not be able to " +
+      "choose which identity a command runs as.",
+    examples: ["zumino init"],
+  },
+  {
+    name: "skill",
+    group: "meta",
+    summary: "the agent skill this package bundles",
+    // The only group with a default: `zumino skill` has meant `zumino skill
+    // install` since the first release, and there is nothing else to do with a
+    // bundled document.
+    defaultSub: "install",
+    subcommands: [
+      {
+        name: "install",
+        summary: "install the skill globally, outside any one checkout",
+        usage: "zumino skill install [--dir PATH] [--check]",
+        flags: { dir: true, check: true },
+        notes:
+          "Global rather than per-repository: one copy that every session picks " +
+          "up, instead of one per checkout to forget to update. `--check` writes " +
+          "nothing and exits 1 when the installed copy is behind, which is what a " +
+          "hook branches on.",
+        examples: ["zumino skill install", "zumino skill install --check"],
+      },
+    ],
+  },
+  {
+    name: "self-update",
+    group: "meta",
+    summary: "update this CLI to the newest published version",
+    usage: "zumino self-update",
+    notes:
+      "Every API response carries the minimum and the newest CLI version, so " +
+      "staleness is detected on a call that was being made anyway. Below the " +
+      "minimum the CLI refuses to run and exits 3; merely behind, it says so on " +
+      "stderr once a day per host.",
+    examples: ["zumino self-update"],
+  },
+  {
+    name: "commands",
+    group: "meta",
+    summary: "every command, in one flat list — or the whole surface as JSON",
+    usage: "zumino commands [--json]",
+    flags: { json: { help: "the full surface: flags, accepted values, examples" } },
+    notes:
+      "What to read first when driving this CLI from a program. `--json` is the " +
+      "same declaration the help pages and the argument validator are generated " +
+      "from, so it cannot describe a command that does not exist or miss one " +
+      "that does.",
+    examples: [
+      "zumino commands",
+      "zumino commands --json | jq -r '.commands[].name'",
+      "zumino commands --json | jq '.values.taskStatus'",
+    ],
+  },
+  {
+    name: "help",
+    group: "meta",
+    summary: "the page for one command — flags, accepted values, examples",
+    usage: "zumino help [<command> [<subcommand>]]",
+    args: [
+      ["<command>", "e.g. task"],
+      ["<subcommand>", "e.g. list"],
+    ],
+    notes: "`zumino <command> --help` is the same page.",
+    examples: ["zumino help", "zumino help task", "zumino help task list"],
+  },
+];
+
+/** Groups, in the order `--help` prints them. */
+export const GROUPS = [
+  ["orient", "Orient"],
+  ["read", "Read across every kind"],
+  ["work", "Read and change one kind"],
+  ["meta", "Everything else"],
+];
+
+/** Every top-level command, by name. */
+export function command(name) {
+  return COMMANDS.find((c) => c.name === name);
+}
+
+/** One subcommand of a group, by name. */
+export function subcommand(group, name) {
+  return group?.subcommands?.find((s) => s.name === name);
+}
+
+/** Every leaf command — a top-level verb, or a group's subcommand. */
+export function leaves() {
+  return COMMANDS.flatMap((c) =>
+    c.subcommands
+      ? c.subcommands.map((s) => ({ ...s, path: `${c.name} ${s.name}`, parent: c }))
+      : [{ ...c, path: c.name, parent: null }],
+  );
+}
+
+/** The flags a leaf accepts, global ones included, as `{name: merged}`. */
+export function flagsFor(leaf) {
+  /** @type {Record<string, any>} */
+  const all = {};
+  for (const name of GLOBAL_FLAGS) all[name] = { ...FLAGS[name], global: true };
+  for (const [name, override] of Object.entries(leaf?.flags ?? {})) {
+    const base = FLAGS[name];
+    all[name] = { ...base, ...(override === true ? {} : override), global: false };
+  }
+  return all;
+}
+
+/** The accepted values of a merged flag entry, or null when it takes free text. */
+export function valuesOf(flag) {
+  return flag?.values ? (VALUES[flag.values] ?? null) : null;
+}
+
+/**
+ * `parseArgs`'s `options` map, derived from `FLAGS`.
+ *
+ * Lexing is global on purpose — `parseArgs` runs before the command is known —
+ * so this is every flag the CLI has. Which of them the command in hand actually
+ * accepts is the next question, and `flags.js` answers it against the spec
+ * rather than leaving an unknown flag to be parsed and then ignored.
+ */
+export function parseOptions() {
+  /** @type {Record<string, {type: string, short?: string, multiple?: boolean}>} */
+  const options = {};
+  for (const [name, f] of Object.entries(FLAGS)) {
+    options[name] = {
+      type: f.type,
+      ...(f.short ? { short: f.short } : {}),
+      ...(f.multiple ? { multiple: true } : {}),
+    };
+  }
+  return options;
+}