@zumino/cli 2.1.0

package/README.md

@@ -0,0 +1,108 @@
+# `@zumino/cli`
+
+Drive [Zumino](https://zumino.cc) from a terminal, a script, or an agent.
+
+```bash
+npm i -g @zumino/cli
+zumino auth login
+zumino init            # in a repo — ties it to a project
+zumino queue
+```
+
+## Why a CLI and not a library
+
+There is nothing to import. The API is the product, and this is a thin front-end
+over it — every endpoint stays reachable through `zumino api`, including ones
+added after you installed this.
+
+What the CLI adds that `curl` cannot is **a version handshake**. Every response
+carries the oldest CLI the server will answer and the newest one published, so a
+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
+
+```
+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
+```
+
+`--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.
+
+## Where context comes from
+
+Resolved in this order. `zumino auth status` says which rung answered.
+
+```
+1. --token / --account / --host / --project
+2. ZUMINO_TOKEN / ZUMINO_URL / ZUMINO_PROJECT / ZUMINO_WORKSPACE / ZUMINO_ACCOUNT
+3. .zumino.json in the repo        committed; host, workspace, project, no secret
+4. the repo map in ~/.config/zumino/config.json   which account you use here
+5. the only account configured
+6. refuse
+```
+
+**There is no "current account" and no `switch` command.** One person may hold
+several accounts on several hosts, and two agents may run in two checkouts at
+once — a single mutable pointer in the home directory would let either silently
+change the other's identity, and a tracker write landing as the wrong person
+looks exactly like success.
+
+## Exit codes
+
+| code | meaning |
+|---|---|
+| `0` | fine |
+| `1` | the call failed |
+| `2` | nothing resolved an account, host or project |
+| `3` | this CLI is too old for the server — run `zumino self-update` |
+
+## Environment
+
+| | |
+|---|---|
+| `ZUMINO_TOKEN` | a personal access token, `zumino_live_…` |
+| `ZUMINO_URL` | host origin, no trailing slash and no `/api` |
+| `ZUMINO_PROJECT` / `ZUMINO_WORKSPACE` | slugs |
+| `ZUMINO_ACCOUNT` | a name from `zumino auth list` |
+| `ZUMINO_NO_UPDATE_CHECK` | silences the "you are behind" notice. It cannot silence the refusal |
+
+Notices go to stderr and the answer goes to stdout, so `zumino queue --json \| jq`
+is always safe.
+
+## The agent skill
+
+```bash
+zumino skill install     # ~/.claude/skills/zumino/ — once, globally
+```
+
+Installed globally on purpose: a per-repo copy is N copies of one document, each
+aging separately with nothing to say which is current.
+
+## Requirements
+
+Node 24 or newer. No runtime dependencies.

package/bin/zumino.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from "../src/main.js";
+
+// The CLI owns its own exit code (see `src/errors.js`), so nothing here maps
+// a thrown value to a status — `main` has already decided, and rethrowing would
+// replace a deliberate 3 with node's 1.
+process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@zumino/cli",
+  "version": "2.1.0",
+  "description": "Drive Zumino from a terminal, a script, or an agent.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "zumino": "bin/zumino.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skill",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/skkap/zumino.git",
+    "directory": "cli"
+  },
+  "keywords": [
+    "zumino",
+    "issue-tracker",
+    "agents",
+    "cli"
+  ],
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: zumino
+version: 2.1.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.**
+
+If `zumino` is not installed: `npm i -g @zumino/cli`.
+
+## The command shape, in one line
+
+**Generic reads span every kind; every write names its kind.** `zumino queue`,
+`zumino context ONS-14` and `zumino find` answer across tasks, requests and
+epics. Anything that writes is `zumino task …`, `zumino request …` or
+`zumino epic …`. That is the API's own rule, and the CLI mirrors it so that a
+new kind of item adds a noun rather than changing what you already know.
+
+Anything not in the verb layer is still reachable:
+
+```bash
+zumino api GET /openapi.json          # every endpoint and every accepted value
+zumino api POST /workspaces/acme/projects/app/tasks --body '{"title":"…"}'
+```
+
+## Start here, every session
+
+```bash
+zumino auth status     # who am I, against which host, from which source
+zumino queue           # what can I pick up right now
+zumino context ONS-14  # the whole brief for one task, as markdown
+```
+
+`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
+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.
+
+## Read the domain model first
+
+**If you are in the Zumino repo, read `DOMAIN.md` before you write anything.**
+It is the one place the vocabulary is written down, and the registries in
+`src/lib` are what the server actually enforces, held in step by
+`test/domain-vocabulary.test.ts`.
+
+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.
+
+## Three words mean something narrower here
+
+Each of these will bite an agent specifically.
+
+| Word | Here | Not |
+|---|---|---|
+| **ref** | a **pull request** attached to a task — a URL and a title, nothing more. `zumino task ref ONS-14 --url …` attaches one | *not* the identifier of an item. That is a **code**. The API publishes the code under two spellings (`code` and `ref`) depending on which endpoint you asked; the CLI reads past that and always prints **code**. Say "code" to a person |
+| **key** | the **project key** — the permanent uppercase prefix a code is built from (`ONS`), unique per workspace, and **absent on a feedback project** | *not* the project's slug (the `--project` value), and *not* `publicSlug` (only the `/b/{slug}` page's address) |
+| **backlog** | a task **status**, and a **view** of a project | *not* "everything not yet done". `todo`, `shaping` and the rest are not in the backlog; they are committed work |
+
+Two consequences, because both look like bugs otherwise:
+
+- **A request on a feedback project has no code.** The project has no key, so
+  `#42` is the whole of its name. Do not synthesize one.
+- **Nothing in `backlog` is offered by `zumino queue`.**
+
+## `zumino queue` is computed, not a column
+
+The default mode answers with **available work**: a task that is `todo` or
+`shaping`, that meets the bar (a description **and** acceptance criteria), with
+no unfinished task blocking it. All three are computed. There is no status
+anyone drags a card into to publish work here.
+
+**An empty queue does not mean there is nothing to do.** It means every
+committed task is either below the bar or waiting on something. That is a
+finding worth reporting, not a reason to stop:
+
+```bash
+# 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`.
+```
+
+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
+be satisfied by filler.
+
+The bar does **not** require a plan. A task can legitimately arrive with no plan
+and expect you to work the approach out; the brief says so when that is the case.
+
+`--needs-input` is the other mode: tasks waiting on you.
+
+## Every repo knows its project
+
+A tracker only tells the truth if the work goes through it. The failure mode is
+not that people refuse to file tickets — it is that an agent doing an hour of
+real work in a repo has no reason to know a project exists, so the work happens
+and the board silently falls behind.
+
+**Two conventions close that.**
+
+**1. A repo declares its project.** `zumino init` writes `.zumino.json` at the
+repo root — host, workspace, project, no secret — and every `zumino` command in
+that checkout then needs no arguments. If you are in a repo with no
+`.zumino.json` and the user is tracking work in Zumino, offer to run it.
+
+**2. Real work finds or files a ticket.** Not every edit — a typo fix does not
+need one, and a rule that says otherwise gets ignored wholesale. But **work with
+a shape to it** starts by finding the existing ticket or creating one, and ends
+by closing it, commenting on it, or moving it. The threshold: if you would
+mention it in a standup, it needs a ticket.
+
+```bash
+zumino find "rate limit"                         # is this already filed?
+zumino task create --title "…" --description "…" # if not
+zumino task ref ONS-14 --url <the PR you opened> # when you open one
+```
+
+**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.
+
+## Addressing an epic
+
+`zumino epic create` prints `E6`. That is a real address in the current project —
+`zumino epic show E6` works — and so is the full code `ACME-E6`, which is what
+`zumino find --kind epic` shows. A bare `6` means *task* 6, because task and epic
+numbers are separate namespaces, so the letter is what tells them apart.
+
+## The three pieces of writing
+
+A task carries a `description` (what this is), `spec.plan` (the output of
+shaping) and `spec.acceptance` (when it is done). The two spec sections are
+written **one at a time**, and the CLI enforces it:
+
+```bash
+zumino task spec ONS-14 --plan "…"
+zumino task spec ONS-14 --acceptance "…"
+```
+
+That is not ceremony. An agent redrafting the plan must not be able to touch the
+criteria it will be judged against.
+
+## Linking work
+
+```bash
+zumino task link ONS-14 blocks ONS-9        # ONS-9 waits on ONS-14
+zumino task link ONS-14 blocked-by ONS-9    # the other direction
+zumino task link ONS-14 related ONS-3       # worth reading together, nothing waits
+zumino task link ONS-14 answers feedback#42 # this work exists because of that request
+```
+
+`answers` is the useful one and the odd one: the far end is a **request**, not a
+task, and it needs owner or admin on the request's project. A request is never
+*converted* into a task — promoting one creates a task that answers it, and both
+go on living:
+
+```bash
+zumino request promote 42 --project feedback --to app
+```
+
+`--project` is where the request lives, `--to` is where the task goes. They are
+two different projects, which is why they are two different flags.
+
+## Errors
+
+Failures carry a stable key and an English message; the CLI prints the message
+and, where there is one, a second line telling you what to do. Act on that line.
+
+**Exit codes are the contract**, so branch on them rather than parsing text:
+
+| code | meaning |
+|---|---|
+| `0` | fine |
+| `1` | the call failed — the message says why |
+| `2` | nothing resolved an account, host or project |
+| `3` | **this CLI is too old for the server** — run `zumino self-update` and retry |
+
+**A rate-limit refusal means wait and repeat that exact call — never skip it and
+never shorten it.** The message carries the exact number of seconds. A
+half-authored epic looks finished, which is worse than one not started. If you
+cannot wait, stop and say which calls landed and which did not.
+
+## Rules
+
+- **Never destroy anything.** There is no `zumino delete`, deliberately: an
+  item's history cascades with the row, so deletion is the one operation that
+  erases its own evidence. Retire work with `wont_do`.
+- **Never write text in the user's name without showing it first.** Requests and
+  comments on a public board are visible to everyone.
+- **Never overwrite a task's `description` or its `acceptance`** without being
+  asked. Those are the human's half: what the work is, and what it will be
+  judged against.
+- **Never mark a task `done`.** Acceptance is a person's call. Move it to
+  `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.
+- 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.
+- Titles are one line and specific. Descriptions carry repro steps, file paths
+  and links. Do not pad.
+
+## When something says you are out of date
+
+```
+zumino: CLI 2.0.0 is too old for https://zumino.cc, which requires >= 2.1.0.
+        Run: zumino self-update
+```
+
+Run it, then retry what you were doing. The CLI refuses rather than guessing
+because a client built against shapes the server no longer sends would produce a
+*plausible* answer, and a plausible answer is worse than none.
+
+If the CLI is newer than this skill, refresh it: `zumino skill install`.

package/src/client.js

@@ -0,0 +1,247 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+
+import { CliError, tooOld } from "./errors.js";
+import { note, safeText, workspaceSlug } from "./output.js";
+
+const require = createRequire(import.meta.url);
+export const VERSION = require("../package.json").version;
+
+/*
+ * One HTTP call, and the version handshake that rides on its reply.
+ *
+ * The handshake is the reason this CLI is worth having over `curl`. Every
+ * `/api/v1` response carries `X-Zumino-Cli-Min` and `X-Zumino-Cli-Latest`
+ * (`src/lib/cli-version.ts`), so staleness is detected on the call the caller
+ * was already making — no version endpoint, no extra round trip, and no way to
+ * be silently out of date.
+ *
+ * Two tiers, and the difference between them is the whole design:
+ *
+ *  - **below the minimum** — fatal, every time, uncached. The shapes this CLI
+ *    was built against are no longer what the server sends, so a plausible
+ *    answer is worse than no answer.
+ *  - **merely behind** — one line on stderr, at most once a day per host. An
+ *    agent making forty calls in a session must not read the same notice forty
+ *    times; that is context it pays for and cannot act on twice.
+ */
+
+/** @param {string} host */
+function noticeCachePath() {
+  const base = process.env.XDG_CACHE_HOME || join(homedir(), ".cache");
+  return join(base, "zumino", "update-notice.json");
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** True at most once per day per (host, version we would recommend). */
+function shouldNag(host, latest) {
+  if (process.env.ZUMINO_NO_UPDATE_CHECK) return false;
+  const key = `${host}@${latest}`;
+  const path = noticeCachePath();
+  let seen = {};
+  try {
+    seen = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    /* no cache yet */
+  }
+  if (typeof seen[key] === "number" && Date.now() - seen[key] < DAY_MS) return false;
+  try {
+    seen[key] = Date.now();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(seen));
+  } catch {
+    // A read-only or absent cache directory must not stop the command. The cost
+    // of failing to record is a repeated notice, which is noise, not breakage.
+  }
+  return true;
+}
+
+/**
+ * Enforce the floor, advise about the ceiling.
+ *
+ * `ZUMINO_NO_UPDATE_CHECK` silences the *advice* only. It deliberately cannot
+ * suppress the refusal: an environment variable that let a known-incompatible
+ * client keep running would defeat the one guarantee this handshake makes.
+ */
+export function evaluateVersion(ours, min, latest) {
+  if (min && cmp(ours, min) < 0) return { verdict: "refuse", min };
+  if (latest && cmp(ours, latest) < 0) return { verdict: "behind", latest };
+  return { verdict: "ok" };
+}
+
+function checkVersion(res, host) {
+  const { verdict, min, latest } = evaluateVersion(
+    VERSION,
+    res.headers.get("x-zumino-cli-min"),
+    res.headers.get("x-zumino-cli-latest"),
+  );
+  if (verdict === "refuse") throw tooOld(VERSION, min, host);
+  if (verdict === "behind" && shouldNag(host, latest)) {
+    note(
+      `zumino: CLI ${VERSION} is behind ${latest} on ${host}.\n` +
+        `        Update with: zumino self-update`,
+    );
+  }
+}
+
+function cmp(a, b) {
+  const pa = String(a).split(".").map(Number);
+  const pb = String(b).split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * Call the API.
+ *
+ * @param {{host: string, token: string}} ctx
+ * @param {string} method
+ * @param {string} path      below `/api/v1`, e.g. `/queue`
+ * @param {{query?: Record<string, any>, body?: any, raw?: boolean}} [opts]
+ */
+export async function api(ctx, method, path, opts = {}) {
+  const url = new URL(`${ctx.host}/api/v1${path}`);
+  for (const [k, v] of Object.entries(opts.query ?? {})) {
+    if (v !== undefined && v !== null && v !== "") url.searchParams.set(k, String(v));
+  }
+
+  let res;
+  try {
+    res = await fetch(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${ctx.token}`,
+        Accept: "application/json",
+        "X-Zumino-Cli": VERSION,
+        "User-Agent": `zumino-cli/${VERSION} node/${process.versions.node}`,
+        ...(opts.body === undefined ? {} : { "Content-Type": "application/json" }),
+      },
+      body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+    });
+  } catch (cause) {
+    throw new CliError(`Cannot reach ${ctx.host}: ${cause.message}`, {
+      hint: "Check ZUMINO_URL, or the host in .zumino.json.",
+    });
+  }
+
+  checkVersion(res, ctx.host);
+
+  // Two ways a reply legitimately carries nothing, and they have to be taken
+  // before the body guards below or those guards fire on every one of them.
+  //
+  // HEAD is the one that was missed: it carries no body *by definition*, Next
+  // auto-implements it from the GET handler, and it is reachable through
+  // `zumino api HEAD …`. Skipping only the empty-body check was not enough —
+  // the empty string then reached `JSON.parse` and failed the non-JSON guard
+  // instead, which is the same defect one line further down.
+  if (res.status === 204 || method === "HEAD") {
+    if (!res.ok) {
+      throw new CliError(`${ctx.host} answered ${res.status}.`, {
+        hint: res.status === 401 ? "Token rejected. Check it with: zumino auth status" : undefined,
+      });
+    }
+    return null;
+  }
+
+  const text = await res.text();
+
+  // No route on this API answers 200 with an empty body — the empty ones are
+  // 204, handled above. So a zero-length body is a truncated or intercepted
+  // reply, and letting it through as `null` reproduces the same confident-empty
+  // failure the non-JSON guard below exists to stop.
+  if (!text) {
+    throw new CliError(`${ctx.host} answered ${res.status} with an empty body.`, {
+      hint: "The reply was truncated or intercepted; nothing was read.",
+    });
+  }
+  let parsed = null;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    // A non-JSON body from a JSON API means something in front of the app
+    // answered — a proxy, an SSO or captive-portal page, a `ZUMINO_URL` one hop
+    // short of the app.
+    //
+    // **This throws whatever the status was.** It used to raise only on `!ok`,
+    // so a `200 text/html` fell through as `null` and every caller's
+    // `res?.tasks ?? []` turned it into a confident empty answer at exit 0:
+    // `zumino queue` said there was nothing to pick up, `zumino find` said
+    // nothing matched — which is what an agent reads before filing a duplicate —
+    // and `auth status` reported success against a host that authenticated
+    // nothing. That is exactly the plausible-answer failure this file's header
+    // says the design exists to prevent.
+    throw new CliError(`${ctx.host} answered ${res.status} with a non-JSON body.`, {
+      hint: "Is ZUMINO_URL pointing at the app rather than a proxy or a login page?",
+    });
+  }
+
+  if (!res.ok) {
+    const err = parsed?.error;
+    // `Retry-After` carries the exact wait (`src/lib/api-resource.ts`), so a
+    // caller sleeps the right amount rather than guessing or dropping the write.
+    const retry = res.headers.get("retry-after");
+    // The server's message is built from its own keys, but a Zod issue can echo
+    // a submitted value back, so it is treated as remote text like any other.
+    throw new CliError(safeText(err?.message) || `${method} ${path} failed (${res.status}).`, {
+      key: err?.key,
+      hint:
+        res.status === 429 && retry
+          ? `Rate limited. Retry after ${retry}s.`
+          : res.status === 401
+            ? "Token rejected. Check it with: zumino auth status"
+            : undefined,
+    });
+  }
+
+  return parsed;
+}
+
+/**
+ * The workspace a project lives in, looked up when nothing named one.
+ *
+ * `GET /projects` is one of the two deliberately cross-workspace reads, so this
+ * is a single call rather than a search. It is a fallback and says so: `zumino
+ * init` writes the workspace into `.zumino.json` precisely to make it stop
+ * happening on every command.
+ *
+ * @param {{host: string, token: string, workspace: string|null, project: string|null}} ctx
+ */
+export async function resolveWorkspace(ctx) {
+  // Normalised rather than returned as-is: a `.zumino.json` written by an older
+  // build can hold the object shape, and it would otherwise be interpolated
+  // into every path in that checkout.
+  const named = workspaceSlug(ctx.workspace);
+  if (named) return named;
+  if (!ctx.project) {
+    throw new CliError("No project, so no workspace to find.", {
+      hint: "Pass --project <slug>, or run: zumino init",
+    });
+  }
+  const { projects = [] } = (await api(ctx, "GET", "/projects")) ?? {};
+  const hits = projects.filter(
+    (p) => p.slug === ctx.project || p.key === ctx.project,
+  );
+  if (hits.length === 0) {
+    throw new CliError(`No project "${ctx.project}" in any workspace you can reach.`, {
+      hint: "List what you can see with: zumino api GET /projects",
+    });
+  }
+  if (hits.length > 1) {
+    // The slug is unique per workspace, not globally, so this is reachable and
+    // guessing would write to the wrong workspace — the exact failure the
+    // workspace segment exists to prevent.
+    throw new CliError(
+      `"${ctx.project}" exists in more than one workspace: ${hits
+        .map((h) => workspaceSlug(h.workspace))
+        .join(", ")}.`,
+      { hint: "Name one with --workspace <slug>." },
+    );
+  }
+  return workspaceSlug(hits[0].workspace);
+}

package/src/commands/api.js

@@ -0,0 +1,50 @@
+import { api } from "../client.js";
+import { resolveContext } from "../config.js";
+import { CliError } from "../errors.js";
+import { json } from "../output.js";
+
+/**
+ * `zumino api <METHOD> <PATH> [--body JSON]` — the escape hatch.
+ *
+ * It is not a fallback for a missing feature; it is what keeps the verb layer
+ * small enough to be worth learning. Every one of the API's endpoints is
+ * reachable here, including ones added after this CLI was installed — which is
+ * why `CLI_MIN` on the server moves only for a *breaking* change and not for a
+ * new endpoint. An old CLI can always reach a new path.
+ *
+ * `GET /openapi.json` enumerates everything, and an invalid value is refused
+ * with a message naming what was expected.
+ */
+export async function run(args, flags) {
+  const [rawMethod, path, ...rest] = args;
+  if (!rawMethod || !path) {
+    throw new CliError("zumino api <METHOD> <PATH> [--body JSON]", {
+      hint: "Paths are below /api/v1, e.g. /queue or /workspaces/acme/items/ONS-14",
+    });
+  }
+  const method = rawMethod.toUpperCase();
+  if (!/^(GET|POST|PATCH|PUT|DELETE|HEAD)$/.test(method)) {
+    throw new CliError(`"${rawMethod}" is not an HTTP method.`);
+  }
+  if (!path.startsWith("/")) {
+    throw new CliError(`Path must start with "/" — got "${path}".`, {
+      hint: "It is relative to /api/v1, so /queue rather than /api/v1/queue.",
+    });
+  }
+
+  const rawBody = flags.body ?? rest.join(" ").trim();
+  let body;
+  if (rawBody) {
+    try {
+      body = JSON.parse(rawBody);
+    } catch (err) {
+      throw new CliError(`--body is not valid JSON: ${err.message}`);
+    }
+  }
+
+  const ctx = resolveContext(flags);
+  const res = await api(ctx, method, path, { body });
+  if (res === null) return 0;
+  json(res);
+  return 0;
+}