@zumino/cli 2.1.0

package/src/items.js

@@ -0,0 +1,86 @@
+import { api, resolveWorkspace } from "./client.js";
+import { requireProject } from "./config.js";
+import { CliError } from "./errors.js";
+import { pick } from "./output.js";
+
+/*
+ * Turning what a person typed into a path the API answers.
+ *
+ * A code (`ONS-14`) is a **lookup, not an address** — `docs/decisions/0004`. So
+ * every command that takes one resolves it once at
+ * `GET /workspaces/{workspace}/items/{code}` and then uses the `path` that read
+ * hands back. Nothing here builds an item path out of a kind and a number by
+ * hand: doing so would put the kind→segment mapping in a second place, and the
+ * first place is a registry the server holds.
+ */
+
+/**
+ * Resolve `ONS-14`, or a bare number in the current project.
+ *
+ * @param {any} ctx
+ * @param {string} ref  a code, `#14`, or `14`
+ * @param {{kind?: "task"|"request"|"epic"}} [opts] kind for the bare-number form
+ */
+export async function resolveItem(ctx, ref, opts = {}) {
+  const workspace = await resolveWorkspace(ctx);
+  const bare = String(ref).replace(/^#/, "");
+
+  // A number in the current project, with the kind either stated by the caller
+  // or carried by a letter. `E6` is the form `zumino epic create` prints, and it
+  // resolved to nothing until now: an epic's real code is `ACME-E6`, so `E6`
+  // went to the code lookup and 404'd — the identifier the CLI handed back could
+  // not be fed to the next command. `docs/decisions/0004` addresses an item by
+  // kind and number, and that is what this is.
+  const local = /^([Ee])?(\d+)$/.exec(bare);
+  if (local) {
+    const project = requireProject(ctx);
+    const kind = local[1] ? "epic" : (opts.kind ?? "task");
+    if (opts.kind && kind !== opts.kind) {
+      throw new CliError(`${bare} names an ${kind}, not a ${opts.kind}.`, {
+        hint: `Use: zumino ${kind} … ${bare}`,
+      });
+    }
+    const number = local[2];
+    const segment = { task: "tasks", request: "requests", epic: "epics" }[kind];
+    const path = `/workspaces/${workspace}/projects/${project}/${segment}/${number}`;
+    return { path, number: Number(number), kind, project, workspace };
+  }
+
+  const item = pick(
+    await api(ctx, "GET", `/workspaces/${workspace}/items/${encodeURIComponent(bare)}`),
+    "item",
+  );
+  if (!item?.path) {
+    throw new CliError(`Could not resolve "${ref}".`, {
+      hint: "Codes look like ONS-14 or ONS-E3. A bare number, or E<n> for an epic, needs --project.",
+    });
+  }
+  // A code resolves to whatever kind the server says it is, and `done` is a
+  // valid status on more than one of them — so without this, `zumino task
+  // status ONS-E3 done` would close an *epic* through the task subcommand. The
+  // per-kind split exists precisely so a write names what it is writing to.
+  if (opts.kind && item.kind !== opts.kind) {
+    const article = (k) => (/^[aeiou]/.test(k) ? "an" : "a");
+    throw new CliError(
+      `${bare} is ${article(item.kind)} ${item.kind}, not ${article(opts.kind)} ${opts.kind}.`,
+      {
+        hint: `Use: zumino ${item.kind} … ${bare}`,
+      },
+    );
+  }
+
+  return {
+    path: item.path,
+    number: item.number,
+    kind: item.kind,
+    project: item.project?.slug,
+    workspace,
+    item,
+  };
+}
+
+/** The project path every per-kind write hangs off. */
+export async function projectPath(ctx) {
+  const workspace = await resolveWorkspace(ctx);
+  return `/workspaces/${workspace}/projects/${requireProject(ctx)}`;
+}

package/src/main.js

@@ -0,0 +1,163 @@
+import { parseArgs } from "node:util";
+
+import { CliError, EXIT_FAILURE } from "./errors.js";
+import { VERSION } from "./client.js";
+import { bold, dim, note, out } from "./output.js";
+
+import * as auth from "./commands/auth.js";
+import * as queue from "./commands/queue.js";
+import * as context from "./commands/context.js";
+import * as find from "./commands/find.js";
+import * as task from "./commands/task.js";
+import * as request from "./commands/request.js";
+import * as epic from "./commands/epic.js";
+import * as raw from "./commands/api.js";
+import * as init from "./commands/init.js";
+import * as skill from "./commands/skill.js";
+import * as selfUpdate from "./commands/self-update.js";
+
+/*
+ * Argument parsing and dispatch.
+ *
+ * The command shape is `DOMAIN.md`'s rule, not a style choice: **generic reads
+ * span every kind, and every write names its kind.** `queue`, `context` and
+ * `find` are top-level because they answer across kinds; everything that writes
+ * is `task …`, `request …` or `epic …`, so a fourth kind adds a noun rather
+ * than widening a flat verb list every script has already learned.
+ */
+
+const OPTIONS = {
+  // global
+  json: { type: "boolean" },
+  host: { type: "string" },
+  token: { type: "string" },
+  project: { type: "string" },
+  workspace: { type: "string" },
+  account: { type: "string" },
+  help: { type: "boolean", short: "h" },
+  version: { type: "boolean" },
+  limit: { type: "string" },
+  // reads
+  "needs-input": { type: "boolean" },
+  kind: { type: "string" },
+  status: { type: "string" },
+  state: { type: "string" },
+  activity: { type: "boolean" },
+  // writes
+  title: { type: "string" },
+  description: { type: "string" },
+  assignee: { type: "string" },
+  epic: { type: "string" },
+  plan: { type: "string" },
+  acceptance: { type: "string" },
+  url: { type: "string" },
+  body: { type: "string" },
+  to: { type: "string" },
+  // housekeeping
+  dir: { type: "string" },
+  check: { type: "boolean" },
+  yes: { type: "boolean", short: "y" },
+};
+
+const COMMANDS = {
+  queue: queue.run,
+  context: context.run,
+  find: find.run,
+  task: task.run,
+  request: request.run,
+  epic: epic.run,
+  api: raw.run,
+  auth: auth.run,
+  init: init.run,
+  skill: skill.run,
+  "self-update": selfUpdate.run,
+};
+
+const USAGE = `${bold("zumino")} — drive Zumino from a terminal, a script, or an agent.
+
+${bold("Reads")} (across every kind of item)
+  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 request|task|epic] [--state open|closed]
+
+${bold("Writes")} (each names its 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 TEXT | --acceptance TEXT
+  zumino task comment <CODE> <text>
+  zumino task link <CODE> <blocks|blocked-by|related|answers> <CODE>
+  zumino task ref <CODE> --url URL [--title T]
+  zumino request answer <CODE|#N> <text>
+  zumino request promote <CODE|#N> --to <work-project>
+  zumino request status <CODE|#N> <status>
+  zumino request note <CODE|#N> <text>
+  zumino request comment <CODE|#N> <text>
+  zumino epic create --title T
+  zumino epic status <CODE> <status>
+
+${bold("Everything else")}
+  zumino api <METHOD> <PATH> [--body JSON]   any endpoint, including new ones
+  zumino auth login | status | list | logout
+  zumino init                                 write .zumino.json for this repo
+  zumino skill install [--dir D] [--check]    install the agent skill, globally
+  zumino self-update
+
+${bold("Context")} is resolved in this order, and ${dim("zumino auth status")} says which won:
+  --token/--account → ZUMINO_TOKEN → .zumino.json → repo map → sole account
+
+${bold("Flags")}  --json  --project P  --workspace W  --host URL  --account NAME
+${bold("Env")}    ZUMINO_TOKEN  ZUMINO_URL  ZUMINO_PROJECT  ZUMINO_WORKSPACE
+        ZUMINO_ACCOUNT  ZUMINO_NO_UPDATE_CHECK
+${bold("Exit")}   0 ok · 1 failed · 2 nothing resolved · 3 CLI too old`;
+
+/** @param {string[]} argv */
+export async function main(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options: OPTIONS,
+      allowPositionals: true,
+      strict: true,
+    });
+  } catch (err) {
+    note(`zumino: ${err.message}`);
+    note("Try: zumino --help");
+    return EXIT_FAILURE;
+  }
+
+  const { values: flags, positionals } = parsed;
+
+  if (flags.version) {
+    out(VERSION);
+    return 0;
+  }
+  const [name, ...rest] = positionals;
+  if (!name || name === "help" || (flags.help && !name)) {
+    out(USAGE);
+    return 0;
+  }
+
+  const run = COMMANDS[name];
+  if (!run) {
+    note(`zumino: unknown command "${name}".`);
+    note("Try: zumino --help");
+    return EXIT_FAILURE;
+  }
+
+  try {
+    return (await run(rest, flags)) ?? 0;
+  } catch (err) {
+    if (err instanceof CliError) {
+      note(`zumino: ${err.message}`);
+      // The hint is the actionable half, and it is why failures are phrased as
+      // imperatives with an exact command: an agent reads this on stderr and
+      // runs it, which is the whole mechanism by which drift gets fixed.
+      if (err.hint) note(`        ${err.hint}`);
+      return err.exitCode;
+    }
+    note(`zumino: ${err?.message ?? String(err)}`);
+    return EXIT_FAILURE;
+  }
+}

package/src/output.js

@@ -0,0 +1,192 @@
+import { CliError } from "./errors.js";
+import { styleText } from "node:util";
+
+/*
+ * Everything the CLI prints, and the one rule that governs all of it:
+ *
+ * **stdout is the answer; stderr is everything else.** A caller pipes stdout
+ * into `jq`, so a version notice, a progress line or a warning written there
+ * would corrupt output that was otherwise machine-readable. There is no case in
+ * which a notice is worth breaking a pipe for.
+ */
+
+const colorEnabled = () =>
+  process.stdout.isTTY && !process.env.NO_COLOR && process.env.TERM !== "dumb";
+
+/** @param {string} s @param {Parameters<typeof styleText>[0]} style */
+function paint(s, style) {
+  return colorEnabled() ? styleText(style, s) : s;
+}
+
+export const dim = (s) => paint(s, "dim");
+export const bold = (s) => paint(s, "bold");
+export const amber = (s) => paint(s, "yellow");
+
+/*
+ * The writers do NOT sanitise, and that is deliberate — it was tried and it was
+ * wrong in both directions.
+ *
+ * `bold()` and `dim()` emit CSI sequences, and they run *before* the string
+ * reaches the sink, so a sanitising `out()` deleted the CLI's own styling:
+ * `--help` rendered plain and every dim hint disappeared. And `json()` goes
+ * through `out()` too, so it mutated the answer — `JSON.stringify` escapes C0 as
+ * `\uXXXX` but emits DEL and the C1 range raw, which the final rule then
+ * stripped from inside string literals, silently returning less than the API
+ * holds.
+ *
+ * The boundary is the untrusted **value**, not the assembled line. Everything
+ * read from a response or from a committed `.zumino.json` goes through
+ * `safeText` where it is interpolated — see the response fields in the command
+ * modules, and the refusal messages in `config.js` and `client.js`, which are
+ * the error path an earlier round found unguarded.
+ */
+
+/** A notice for a person, never part of the answer. Always stderr. */
+export function note(s) {
+  process.stderr.write(s + "\n");
+}
+
+/** The answer. Always stdout. */
+export function out(s) {
+  process.stdout.write(s + "\n");
+}
+
+export function json(value) {
+  out(JSON.stringify(value, null, 2));
+}
+
+/**
+ * A plain column table.
+ *
+ * Columns are padded to their widest cell, which is fine for the sizes a queue
+ * or a search answers with and avoids a dependency for the sake of box-drawing.
+ * `--json` exists for anything that wants to be parsed, so this is free to be
+ * for eyes only.
+ *
+ * @param {Array<Array<string>>} rows
+ * @param {{head?: string[]}} [opts]
+ */
+export function table(rows, opts = {}) {
+  const all = opts.head ? [opts.head, ...rows] : rows;
+  if (all.length === 0) return;
+  const widths = [];
+  for (const row of all) {
+    row.forEach((cell, i) => {
+      widths[i] = Math.max(widths[i] ?? 0, String(cell ?? "").length);
+    });
+  }
+  const render = (row) =>
+    row
+      .map((cell, i) =>
+        i === row.length - 1
+          ? String(cell ?? "")
+          : String(cell ?? "").padEnd(widths[i]),
+      )
+      .join("  ")
+      .trimEnd();
+  if (opts.head) out(dim(render(opts.head)));
+  for (const row of rows) out(render(row));
+}
+
+/**
+ * Strip terminal control sequences from text the server sent.
+ *
+ * Item titles and bodies are written by other people — on a public feedback
+ * project, by anyone who can reach it — and they land on a terminal when
+ * somebody runs `zumino find` or `zumino task show`. Left intact, an ESC in a
+ * title is *interpreted*: CSI can clear the screen or forge the rest of the
+ * listing, and OSC 52 can replace the reader's clipboard. `JSON.parse` restores
+ * whatever escaping the transport applied, so the bytes arrive live.
+ *
+ * Everything printed from a response goes through here. Tabs and newlines are
+ * kept — they are legitimate in a description and in the context brief — and
+ * every other C0/C1 control, plus complete ANSI sequences, is removed.
+ */
+export function safeText(value) {
+  return String(value ?? "")
+    // CSI / OSC / other escape sequences, taken whole so no orphan tail is left
+    .replace(/\u001B\[[0-?]*[ -/]*[@-~]/g, "")
+    .replace(/\u001B\][^\u0007\u001B]*(?:\u0007|\u001B\\)/g, "")
+    .replace(/\u001B[@-Z\\-_]/g, "")
+    // remaining C0 (keeping \t \n \r) and C1
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g, "");
+}
+
+/** Trim a title to keep a table one line per row on an ordinary terminal. */
+export function clip(s, n = 60) {
+  const t = safeText(s).replace(/\s+/g, " ").trim();
+  return t.length <= n ? t : t.slice(0, n - 1) + "…";
+}
+
+/**
+ * An item's code, under whichever word the endpoint published it.
+ *
+ * The API says `code` on the generic spine read and `ref` on every task shape,
+ * for the same string — `tasks/the-api-publishes-an-item-code-under-two-words.md`.
+ * `DOMAIN.md` settles the word as **code**, so the CLI reads past the drift and
+ * always prints one. This is the only place that knows both spellings.
+ */
+export function codeOf(item) {
+  return item?.code ?? item?.ref ?? "";
+}
+
+/**
+ * The object out of a response envelope.
+ *
+ * Every write on this API answers `{"task": {…}}`, `{"item": {…}}`,
+ * `{"comment": {…}}` and so on rather than the object alone — the envelope is
+ * what lets a response grow a second key without changing the shape of the
+ * first. The CLI unwraps at the edge so nothing downstream has to know which
+ * word a given endpoint chose, and falls back to the response itself so a bare
+ * body is not a crash.
+ */
+export function pick(res, key) {
+  return res?.[key] ?? res;
+}
+
+/**
+ * A workspace slug, however the endpoint published it.
+ *
+ * `GET /queue` sets `workspace` to a plain slug string; `GET /projects` sets it
+ * to a `{slug, name}` reference (`publicWorkspaceRefView`). Both feed paths that
+ * name their workspace, and interpolating the object yields
+ * `/workspaces/[object%20Object]/…`, which 404s — so every read of the field
+ * goes through here.
+ */
+export function workspaceSlug(value) {
+  return typeof value === "string" ? value : (value?.slug ?? null);
+}
+
+/**
+ * A flag that must be a positive integer, refused rather than coerced.
+ *
+ * `Number("foo")` is `NaN`, and `JSON.stringify({n: NaN})` is `{"n":null}` —
+ * which on `epicNumber` is the value that *detaches* the epic. So a typo in
+ * `--epic` silently did the opposite of what was asked. A bad `--limit` was
+ * milder (the server falls back to its default) but equally silent.
+ */
+export function positiveInt(value, flag) {
+  if (value === undefined || value === null || value === "") return undefined;
+  const n = Number(String(value).trim());
+  if (!Number.isInteger(n) || n < 1) {
+    throw new CliError(`--${flag} takes a positive whole number, not "${value}".`);
+  }
+  return n;
+}
+
+/**
+ * An explicitly-given flag value, where empty means "clear it", not "absent".
+ *
+ * `parseArgs` reports `--description ""` and `--description=` as `""`, which is
+ * falsy — so a truthiness gate dropped the flag and the field was left untouched
+ * instead of cleared. `config.js` already states the rule for credentials ("an
+ * explicit empty value is an error, not an absence"); this is the same
+ * distinction for fields where empty is a legitimate instruction rather than a
+ * mistake.
+ *
+ * Returns `undefined` when the flag was not given at all, so a caller can tell
+ * the three cases apart.
+ */
+export function givenFlag(value) {
+  return value === undefined ? undefined : String(value);
+}