@zumino/cli 2.1.0 → 2.2.0

package/README.md

@@ -21,34 +21,73 @@ stale client is told on the call it was already making, and an incompatible one
 refuses to run rather than returning a plausible answer built on shapes the
 server no longer sends.
 
-## Commands
+## Finding your way
+
+The command list is not written down twice. `cli/src/spec.js` declares every
+command, every flag and every value a flag accepts; the help pages, the argument
+validation and the machine-readable dump are all generated from it.
+
+```bash
+zumino                       # every command, grouped, one line each
+zumino help task list        # one command in full: flags, accepted values, examples
+zumino commands              # every command as a flat list, for grepping
+zumino commands --json       # the whole surface, for a program to read
+```
+
+`zumino commands --json` is the one to reach for from a script or an agent. It
+carries the vocabularies, so `--status in_review` is never discovered by having
+`--status review` refused:
+
+```bash
+zumino commands --json | jq -r '.values.taskStatus[]'
+zumino commands --json | jq -r '.commands[] | select(.path|startswith("task")) | .usage'
+```
+
+## The shape of it
+
+**Generic reads span every kind; 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.
 
 ```
-zumino queue [--needs-input] [--limit N]      what to work on next
-zumino context <CODE> [--activity]            the whole brief for one task
-zumino find <query> [--kind k]                one read across every kind
-
-zumino task create --title T [--description D] [--epic N]
-zumino task status <CODE> <status>
-zumino task assign <CODE> <userId|->
-zumino task spec <CODE> --plan T | --acceptance T
-zumino task comment <CODE> <text>
-zumino task link <CODE> <blocks|blocked-by|related|answers> <CODE|project#N>
-zumino task ref <CODE> --url URL [--title T]
-zumino task attention <CODE> [reason|-]
-zumino task show <CODE>
-
-zumino request create|answer|status|note|comment|show
-zumino request promote <CODE|#N> --to <work-project>
-zumino epic    create|status|list|show      # address as E6 or ACME-E6
-
-zumino api <METHOD> <PATH> [--body JSON]
-zumino auth login | status | list | logout
-zumino init
-zumino skill install [--dir D] [--check]
-zumino self-update
+orient      workspace list · project list · project show · project tags · auth status
+read        queue · context <CODE> · find
+one kind    task    list show events create edit status assign spec comment link ref attention tag untag
+            request list show events create edit answer status note comment promote tag untag
+            epic    list show create edit status
+else        api · auth · init · skill install · self-update · commands · help
 ```
 
+## Filters
+
+Every list command carries the filters its endpoint performs, and **only** those.
+Nothing here narrows a list locally: a client-side filter reads exactly like a
+server-side one and is wrong invisibly, because it filters the page it was handed
+rather than the project.
+
+```bash
+zumino task list --status todo,in_progress --priority high --assignee me
+zumino task list --epic E3 --sort manual            # the order the board draws
+zumino task list --status done --limit 100 --offset 100
+zumino request list --status open --sort top --limit 10
+zumino find "rate limit" --kind task,epic --state open
+zumino task events ACME-14 --field status           # how has this moved
+```
+
+Three consequences of that rule worth knowing:
+
+- **A flag a command does not accept is an error**, not a no-op. `zumino find
+  --priority high` says so and names the command that does filter by priority.
+  Every value is checked against the real vocabulary before the call is made.
+- **`--status` is repeatable** (`--status todo --status done`) or
+  comma-separated; both produce one query parameter.
+- **A paged answer says it is paged**, and names the flag that fetches the rest —
+  `1–50 of 312 — next page: --offset 50`. A table that stops at fifty rows and
+  says nothing is how a duplicate gets filed.
+
+`--assignee me` resolves against the token's owner, so no `jq` is needed to find
+your own user id.
+
 `--json` prints the raw response instead of a table, on every command that
 returns API data. The housekeeping commands — `auth login`/`logout`, `init`,
 `skill install`, `self-update` — report progress in prose and ignore it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zumino/cli",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Drive Zumino from a terminal, a script, or an agent.",
   "license": "MIT",
   "type": "module",

package/skill/SKILL.md

@@ -1,14 +1,27 @@
 ---
 name: zumino
-version: 2.1.0
+version: 2.2.0
 description: Read and modify Zumino projects from any directory with the `zumino` CLI. Two kinds of project — feedback projects (requests, votes, roadmap statuses, read publicly as a board) and work projects (tasks and epics, with a structured spec, an owner, and a readiness bar) — plus one generic read across every kind of item. Use whenever the user mentions Zumino, a product board, a public roadmap, requests or feedback, a project, a task, an epic, a backlog item, a spec, or asks to file/track/pick up a bug, feature request, idea, or piece of work.
 ---
 
 # Zumino — projects from the command line
 
-Everything is `zumino`, installed globally and working from any directory. Run
-`zumino --help` for the full surface; this file is the part `--help` cannot
-carry — **what the words mean, and what will go wrong if you assume.**
+Everything is `zumino`, installed globally and working from any directory.
+
+**The surface documents itself, so this file does not restate it.**
+
+```bash
+zumino                       # every command, grouped, one line each
+zumino help task list        # one command in full: flags, accepted values, examples
+zumino commands --json       # the whole surface, for a program to read
+```
+
+`zumino commands --json` is the one to use. It carries every command, every flag
+and — the part worth having — **every value each filter accepts**, under
+`.values`. Read it rather than guessing a status and reading a 400 back.
+
+This file is the part none of that can carry: **what the words mean, and what
+will go wrong if you assume.**
 
 If `zumino` is not installed: `npm i -g @zumino/cli`.
 
@@ -31,10 +44,16 @@ zumino api POST /workspaces/acme/projects/app/tasks --body '{"title":"…"}'
 
 ```bash
 zumino auth status     # who am I, against which host, from which source
+zumino project list    # what can I see, and which kind is each one
 zumino queue           # what can I pick up right now
 zumino context ONS-14  # the whole brief for one task, as markdown
 ```
 
+`zumino project list` is the orientation read, and its TYPE column decides which
+half of the CLI applies: a **feedback** project holds requests (`#42`,
+`zumino request …`), a **work** project holds tasks and epics (`ONS-14`,
+`zumino task …`). `zumino workspace list` is the same question one level up.
+
 `zumino context` is not a convenience. It assembles the epic, the description,
 the plan, the acceptance criteria, the blockers and the requests a task answers
 into one document. Six separate reads would let you lay them out yourself, and
@@ -42,7 +61,11 @@ that is exactly the failure: you would assemble a *plausible* brief instead of
 the real one.
 
 Add `--activity` when picking up work someone (or some earlier run) already
-touched — it appends what has been tried.
+touched — it appends what has been tried. `zumino task events ONS-14` is the same
+history in full, and `--field status` narrows it to how the task has moved.
+**Read it before picking a task up**: "what was tried and then reverted" is the
+one piece of context the brief cannot hold, and re-doing an abandoned approach is
+what it costs to skip.
 
 ## Read the domain model first
 
@@ -53,10 +76,17 @@ It is the one place the vocabulary is written down, and the registries in
 
 This file deliberately carries **no copy** of any status list or kind list. A
 second list is accurate the day it is written and wrong a release later, and you
-would have no way of telling which one you were reading. From outside the repo,
-`zumino api GET /openapi.json` enumerates every value the API accepts, and an
-invalid one is refused with a message naming what was expected. Ask rather than
-guess.
+would have no way of telling which one you were reading. From outside the repo:
+
+```bash
+zumino commands --json | jq '.values'              # every vocabulary
+zumino commands --json | jq -r '.values.taskStatus[]'
+zumino help task list                              # the same lists, on the page
+```
+
+The CLI refuses a value outside the real set before it sends anything, and names
+the set in the refusal — so a wrong guess costs a message rather than a write.
+Ask rather than guess.
 
 ## Three words mean something narrower here
 
@@ -89,12 +119,20 @@ finding worth reporting, not a reason to stop:
 # Committed but not yet shaped — the queue will not offer these.
 zumino find --state open --json | jq -r '.[] | select(.kind=="task") | .code'
 zumino task show ONS-14        # readiness is on the task
+```
 
-`find` takes `--state open|closed`, never `--status`: the read that spans every
-kind publishes no per-kind status (`docs/decisions/0003`). A status belongs to a
-kind, so ask that kind — `zumino task show`.
+Or ask the task endpoint directly, which has the statuses:
+
+```bash
+zumino task list --status todo,shaping        # committed
+zumino task list --status backlog --open      # not committed
 ```
 
+`find` takes `--state open|closed` and **never `--status`**: the read that spans
+every kind publishes no per-kind status (`docs/decisions/0003`). A status belongs
+to a kind, so ask that kind — `zumino task list` or `zumino request list`. The
+CLI says exactly that if you try, rather than answering an unfiltered list.
+
 Shape one of those and it appears in the queue by itself. **Do not invent a
 description or a criterion to make a task eligible** — that is laundering an
 unshaped task as a shaped one, and the whole point of the bar is that it cannot
@@ -131,6 +169,10 @@ zumino task create --title "…" --description "…" # if not
 zumino task ref ONS-14 --url <the PR you opened> # when you open one
 ```
 
+**Check the page count.** A list that is a slice of a bigger answer says so and
+names the flag that fetches the rest — `1–50 of 312 — next page: --offset 50`.
+"Nothing matches" from a read you capped at ten is how a duplicate gets filed.
+
 **Before finishing a piece of work, check the backlog.** A change that resolves,
 contradicts or partially implements something already filed should say so on
 that ticket rather than leaving it to be reconciled later.
@@ -210,8 +252,11 @@ cannot wait, stop and say which calls landed and which did not.
   `in_review` and say what you did.
 - If a task's readiness is below the bar, **raise attention rather than filling
   the gap with a plausible guess**: `zumino task attention ONS-14 "…"`.
-- If a project is ambiguous or missing, run `zumino api GET /projects` and ask —
-  do not guess.
+- If a project is ambiguous or missing, run `zumino project list` and ask — do
+  not guess.
+- **Change several fields in one call**: `zumino task edit ONS-14 --priority high
+  --size L` is one entry in the history and reads as one decision. Five calls
+  read as five.
 - An **assignee is always a person**, even when an agent does the work. There is
   no agent identity; a token acts as its owner, and that is who the history
   records.

package/src/commands/auth.js

@@ -146,7 +146,7 @@ function readRaw(promptText, stdin = process.stdin) {
 
 export const __testables = { readRaw };
 
-const SUB = { login, status, list, logout };
+export const SUB = { login, status, list, logout };
 
 export async function run(args, flags) {
   const [sub = "status", ...rest] = args;

package/src/commands/commands.js

@@ -0,0 +1,26 @@
+import { VERSION } from "../client.js";
+import { json, out } from "../output.js";
+import { flat, surface } from "../help.js";
+import { VALUES } from "../spec.js";
+
+/**
+ * `zumino commands [--json]` — the whole surface, in one read.
+ *
+ * The command an agent runs first. Without it, discovering the CLI means
+ * paging through `--help` one command at a time and guessing which values a
+ * filter accepts; with `--json` it is a single object carrying every command,
+ * every flag, and — the part that matters — every enumerated value, so
+ * `--status review` is never sent to find out that the word is `in_review`.
+ *
+ * It reaches no network and needs no token: the surface is a property of the
+ * installed CLI, and the version handshake already says whether that CLI is
+ * current.
+ */
+export async function run(args, flags) {
+  if (flags.json) {
+    json(surface({ version: VERSION, values: VALUES }));
+    return 0;
+  }
+  out(flat());
+  return 0;
+}

package/src/commands/epic.js

@@ -1,8 +1,10 @@
 import { api } from "../client.js";
 import { resolveContext } from "../config.js";
 import { CliError } from "../errors.js";
-import { clip, json, out, pick, table, positiveInt, safeText, givenFlag } from "../output.js";
+import { clip, dim, json, out, pick, safeText, table } from "../output.js";
+import { givenFlag, oneValue } from "../flags.js";
 import { projectPath, resolveItem } from "../items.js";
+import { resolveUser } from "../users.js";
 
 /*
  * Epics group tasks, and are not tasks.
@@ -11,7 +13,7 @@ import { projectPath, resolveItem } from "../items.js";
  * so there is deliberately nothing here that nests an epic inside anything.
  */
 
-const SUB = { create, status, list, show };
+export const SUB = { list, show, create, edit, status };
 
 export async function run(args, flags) {
   const [sub, ...rest] = args;
@@ -24,38 +26,20 @@ export async function run(args, flags) {
   return fn(rest, flags);
 }
 
-async function create(args, flags) {
-  const ctx = resolveContext(flags);
-  const title = flags.title ?? args.join(" ").trim();
-  if (!title) throw new CliError("An epic needs a title.", { hint: 'zumino epic create --title "…"' });
-  const base = await projectPath(ctx);
-  const body = { title };
-  if (givenFlag(flags.description) !== undefined) body.description = flags.description;
-  const res = pick(await api(ctx, "POST", `${base}/epics`, { body }), "epic");
-  if (flags.json) return json(res), 0;
-  // An epic shape publishes neither `code` nor `ref` — just a number. `E<n>` is
-  // a real address (see `resolveItem`), so what is printed can be fed straight
-  // back to `zumino epic show`; the full `KEY-E<n>` form works too and is what
-  // `zumino find --kind epic` shows.
-  out(`E${res.number}  ${safeText(res.title)}`);
-  return 0;
-}
-
-async function status(args, flags) {
-  const [ref, value] = args;
-  if (!ref || !value) throw new CliError("zumino epic status <CODE|N> <open|closed>");
-  const ctx = resolveContext(flags);
-  const { path } = await resolveItem(ctx, ref, { kind: "epic" });
-  const res = pick(await api(ctx, "PATCH", path, { body: { status: value } }), "epic");
-  if (flags.json) return json(res), 0;
-  out(`${ref}  ${res.status}`);
-  return 0;
-}
-
+/**
+ * Every epic in the project.
+ *
+ * **No filters and no paging, because the endpoint has none** — epics are the
+ * handful of outcomes a project is organised around, not its inventory, and a
+ * project with enough of them to need a page has stopped using them as
+ * groupings. Narrowing them locally would be a filter that looks like the
+ * server's and is not, so the answer to "only the open ones" is `--json | jq`,
+ * and the answer to "what is under one" is `zumino task list --epic E3`.
+ */
 async function list(args, flags) {
   const ctx = resolveContext(flags);
   const base = await projectPath(ctx);
-  const res = await api(ctx, "GET", `${base}/epics`, { query: { limit: positiveInt(flags.limit, "limit") } });
+  const res = await api(ctx, "GET", `${base}/epics`);
   const epics = res?.epics ?? [];
   if (flags.json) return json(epics), 0;
   if (epics.length === 0) return out("No epics."), 0;
@@ -68,12 +52,13 @@ async function list(args, flags) {
     ]),
     { head: ["EPIC", "STATUS", "DONE", "TITLE"] },
   );
+  out(dim("\nThe work under one: zumino task list --epic E<n>"));
   return 0;
 }
 
 async function show(args, flags) {
   const [ref] = args;
-  if (!ref) throw new CliError("zumino epic show <CODE|N>");
+  if (!ref) throw new CliError("zumino epic show <E<n>|CODE>");
   const ctx = resolveContext(flags);
   const { path } = await resolveItem(ctx, ref, { kind: "epic" });
   const res = pick(await api(ctx, "GET", path), "epic");
@@ -83,3 +68,64 @@ async function show(args, flags) {
   if (res.description) out(`\n${safeText(res.description)}`);
   return 0;
 }
+
+/** The fields an epic write carries, for `create` and for `edit`. */
+async function fields(ctx, flags) {
+  /** @type {Record<string, any>} */
+  const body = {};
+  for (const name of ["title", "description"]) {
+    const v = givenFlag(flags[name]);
+    if (v !== undefined) body[name] = v;
+  }
+  const status = oneValue(flags, "status");
+  if (status !== undefined) body.status = status;
+  const assignee = oneValue(flags, "assignee");
+  if (assignee !== undefined) {
+    body.assigneeId = await resolveUser(ctx, assignee, { flag: "--assignee", allowClear: true });
+  }
+  return body;
+}
+
+async function create(args, flags) {
+  const ctx = resolveContext(flags);
+  const title = oneValue(flags, "title") ?? args.join(" ").trim();
+  if (!title) throw new CliError("An epic needs a title.", { hint: 'zumino epic create --title "…"' });
+  const base = await projectPath(ctx);
+  const body = { ...(await fields(ctx, flags)), title };
+  const res = pick(await api(ctx, "POST", `${base}/epics`, { body }), "epic");
+  if (flags.json) return json(res), 0;
+  // An epic shape publishes neither `code` nor `ref` — just a number. `E<n>` is
+  // a real address (see `resolveItem`), so what is printed can be fed straight
+  // back to `zumino epic show`; the full `KEY-E<n>` form works too and is what
+  // `zumino find --kind epic` shows.
+  out(`E${res.number}  ${safeText(res.title)}`);
+  return 0;
+}
+
+async function edit(args, flags) {
+  const [ref] = args;
+  if (!ref) throw new CliError("zumino epic edit <E<n>|CODE> [fields]");
+  const ctx = resolveContext(flags);
+  const body = await fields(ctx, flags);
+  if (Object.keys(body).length === 0) {
+    throw new CliError("Nothing to change.", {
+      hint: "Name at least one field. See: zumino help epic edit",
+    });
+  }
+  const { path } = await resolveItem(ctx, ref, { kind: "epic" });
+  const res = pick(await api(ctx, "PATCH", path, { body }), "epic");
+  if (flags.json) return json(res), 0;
+  out(`E${res.number}  ${Object.keys(body).join(", ")} written`);
+  return 0;
+}
+
+async function status(args, flags) {
+  const [ref, value] = args;
+  if (!ref || !value) throw new CliError("zumino epic status <E<n>|CODE> <open|in_progress|done|wont_do>");
+  const ctx = resolveContext(flags);
+  const { path } = await resolveItem(ctx, ref, { kind: "epic" });
+  const res = pick(await api(ctx, "PATCH", path, { body: { status: value } }), "epic");
+  if (flags.json) return json(res), 0;
+  out(`${ref}  ${res.status}`);
+  return 0;
+}

package/src/commands/find.js

@@ -1,60 +1,53 @@
-import { api } from "../client.js";
+import { api, resolveWorkspace } from "../client.js";
 import { resolveContext } from "../config.js";
-import { CliError } from "../errors.js";
-
-/** The kinds `GET …/items` recognises (`src/lib/item-kind.ts`). */
-const ITEM_KINDS = ["request", "task", "epic"];
-import { resolveWorkspace } from "../client.js";
-import { clip, codeOf, dim, json, out, table, positiveInt } from "../output.js";
+import { csv, nonNegativeInt, oneValue, positiveInt, searchText } from "../flags.js";
+import { clip, codeOf, dim, json, out, pageLine, table } from "../output.js";
+import { resolveUser } from "../users.js";
 
 /**
- * `zumino find <query>` — one read across every kind of item.
+ * `zumino find` — one read across every kind of item.
+ *
+ * Scoped to a project when one is resolved, and to the whole workspace when
+ * not. It reads the spine shape, which deliberately publishes no `status`
+ * (`docs/decisions/0003`) — so the STATE column says open or closed, and
+ * anything narrower is that kind's own list: `zumino task list --status
+ * in_progress`, `zumino request list --status planned`.
  *
- * Scoped to a project when one is resolved, and to the whole workspace when not.
- * It reads the spine shape, which deliberately publishes no `status`
- * (`docs/decisions/0003`) — so the STATE column says open or closed, and a
- * per-kind status needs the kind's own read.
+ * Every flag here is a filter the endpoint performs. `--status` and
+ * `--priority` are refused with the command that does do them, declared in
+ * `spec.js` — they were the two that used to reach the wire, be ignored, and
+ * answer 200 with an unfiltered list.
  */
 export async function run(args, flags) {
   const ctx = resolveContext(flags);
   const workspace = await resolveWorkspace({ ...ctx, project: ctx.project });
-  const q = args.join(" ").trim();
 
-  const path = ctx.project
-    ? `/workspaces/${workspace}/projects/${ctx.project}/items`
-    : `/workspaces/${workspace}/items`;
+  const q = searchText(args, flags);
+  // `!== undefined` rather than truthiness: `--assignee ""` is given and empty,
+  // and a falsy test would drop it and answer an unfiltered list.
+  const assignee =
+    flags.assignee !== undefined
+      ? await resolveUser(ctx, oneValue(flags, "assignee"), { flag: "--assignee" })
+      : undefined;
 
-  // `--state`, not `--status`. The generic spine read deliberately publishes no
-  // per-kind status (docs/decisions/0003) and understands only `open` and
-  // `closed`; anything else was silently dropped server-side and answered 200
-  // with an unfiltered list, so a wrong filter looked like a real result.
-  if (flags.status) {
-    throw new CliError(
-      `find has no --status: the read that spans every kind publishes only open/closed.`,
-      {
-        hint:
-          `Did you mean --state ${/^(open|closed)$/.test(flags.status) ? flags.status : "open"}? ` +
-          `For a per-kind status, use that kind's own read, e.g. zumino task show <CODE>.`,
-      },
-    );
-  }
-  if (flags.state && !/^(open|closed)$/.test(flags.state)) {
-    throw new CliError(`--state takes open or closed, not "${flags.state}".`);
-  }
-  // Validated here for the same reason `--status` is, one flag over: the server
-  // keeps only recognised kinds and turns an empty set into `false`, so a wrong
-  // value answers 200 with an empty page. The skill prescribes `zumino find` as
-  // the duplicate check before filing, and `--kind bug` or `--kind feature` are
-  // plausible mistakes — they are real task *types* in this product — so a
-  // confident "Nothing matches" is how an agent files a duplicate.
-  if (flags.kind && !ITEM_KINDS.includes(flags.kind)) {
-    throw new CliError(`--kind takes ${ITEM_KINDS.join(", ")}, not "${flags.kind}".`, {
-      hint: "bug and feature are task *types*, not kinds — filter those with zumino task show.",
-    });
-  }
-  const res = await api(ctx, "GET", path, {
-    query: { q: q || undefined, kind: flags.kind, state: flags.state, limit: positiveInt(flags.limit, "limit") },
-  });
+  const offset = nonNegativeInt(flags.offset, "offset");
+  const query = {
+    q,
+    kind: csv(flags, "kind"),
+    state: oneValue(flags, "state"),
+    assignee,
+    sort: oneValue(flags, "sort"),
+    offset,
+    limit: positiveInt(flags.limit, "limit"),
+  };
+
+  // The two scopes are written as two calls rather than one call against a
+  // computed path: `test/cli-routes.test.ts` reads these templates out of the
+  // source to hold them against the server's own routes, and a path assembled
+  // into a variable first is a path nothing checks.
+  const res = ctx.project
+    ? await api(ctx, "GET", `/workspaces/${workspace}/projects/${ctx.project}/items`, { query })
+    : await api(ctx, "GET", `/workspaces/${workspace}/items`, { query });
 
   const items = res?.items ?? [];
   if (flags.json) {
@@ -76,8 +69,6 @@ export async function run(args, flags) {
     ]),
     { head: ["CODE", "KIND", "STATE", "TITLE", "PROJECT"] },
   );
-  if (typeof res.total === "number" && res.total > items.length) {
-    out(dim(`\n${items.length} of ${res.total} — narrow with --kind, or raise --limit.`));
-  }
+  out(dim(`\n${pageLine(res, items.length, offset)}`));
   return 0;
 }