@zumino/cli 2.1.0

package/src/commands/auth.js

@@ -0,0 +1,345 @@
+import { createInterface } from "node:readline/promises";
+
+import { api, VERSION } from "../client.js";
+import { configPath, readConfig, resolveContext, writeConfig } from "../config.js";
+import { CliError } from "../errors.js";
+import { bold, dim, json, note, out, table, safeText } from "../output.js";
+
+/*
+ * Credentials, and the one thing this command cannot do.
+ *
+ * **It cannot mint a token.** `DOMAIN.md` puts credentials under governance: a
+ * token authenticates *as its owner*, so a token that could mint tokens turns a
+ * leak into permanent access that revoking the leaked one does not undo. A
+ * person creates one in a browser they are signed in to; this reads it, checks
+ * it, and remembers where it belongs.
+ */
+
+/**
+ * The prompts `auth login` needs, and who is allowed to see the answers.
+ *
+ * The token is a long-lived credential that authenticates as its owner across
+ * every workspace they belong to, and the prompt is the promoted path — README,
+ * `/docs/api` and the generated installer all end by telling a new user to paste
+ * one here. Echoed, it lands in scrollback, tmux buffers, `script` recordings
+ * and shared sessions. The account name, by contrast, *should* echo.
+ *
+ * So the two cases are split by where the echo comes from:
+ *
+ *  - **a TTY** echoes in the terminal driver, which no library flag reaches. Raw
+ *    mode turns it off, so the secret is read that way and the name gets an
+ *    ordinary interface afterwards. An earlier attempt overrode
+ *    `rl._writeToOutput`, which does not exist on a `node:readline/promises`
+ *    interface — that is the callback API's alias — so it created a property
+ *    nothing called and echoed the token behind a docstring claiming otherwise.
+ *  - **a pipe** has nothing echoing it, so one `terminal: false` interface reads
+ *    both lines and writes nothing back. It has to be *one*: iterating stdin
+ *    directly consumed the whole buffer and left a later interface hanging.
+ */
+function prompter() {
+  const stdin = process.stdin;
+  let lines = null;
+  let next = 0;
+
+  // Piped input is read once, whole, and served line by line. Going through a
+  // readline interface per prompt did not survive both answers arriving in one
+  // chunk — the stream ended, the interface closed, and the second question
+  // threw `readline was closed`. Iterating stdin per prompt was worse: the first
+  // read consumed the buffer and left the second hanging.
+  async function pipedLines() {
+    if (lines) return lines;
+    let data = "";
+    for await (const chunk of stdin) data += chunk.toString("utf8");
+    lines = data.split(/\r?\n/);
+    return lines;
+  }
+
+  const nextPiped = async (promptText) => {
+    process.stderr.write(promptText + "\n");
+    return (await pipedLines())[next++] ?? "";
+  };
+
+  return {
+    /** The token. Never echoed. */
+    secret: (promptText) =>
+      stdin.isTTY ? readRaw(promptText) : nextPiped(promptText),
+
+    /** The account name, which should echo on a terminal. */
+    async line(promptText) {
+      if (!stdin.isTTY) return nextPiped(promptText);
+      const rl = createInterface({ input: stdin, output: process.stderr });
+      try {
+        return await rl.question(promptText);
+      } finally {
+        rl.close();
+      }
+    },
+
+    close() {},
+  };
+}
+
+/**
+ * Read one line from a TTY with the driver's echo turned off.
+ *
+ * **Event listeners, not `for await`.** Node's async iterator destroys the
+ * stream when the loop is left early, and `destroyOnReturn` defaults to true —
+ * so reading the token with `for await … break` destroyed `process.stdin`, and
+ * the account-name prompt built over it afterwards never resolved. The token was
+ * verified against the server and then thrown away with no error, on the exact
+ * path the installer and the docs page promote.
+ *
+ * The stream is a parameter so this is testable without a pty; `login` passes
+ * `process.stdin`.
+ */
+function readRaw(promptText, stdin = process.stdin) {
+  process.stderr.write(promptText);
+  const wasRaw = stdin.isRaw;
+  if (stdin.isTTY) stdin.setRawMode(true);
+  stdin.resume();
+
+  return new Promise((resolve, reject) => {
+    let input = "";
+
+    // `rest` is put back only after the listeners are gone — unshifting while
+    // still subscribed re-delivers it to this same handler, which appended the
+    // next answer onto the token.
+    const done = (fn, value, rest) => {
+      stdin.removeListener("data", onData);
+      stdin.removeListener("error", onError);
+      if (stdin.isTTY) stdin.setRawMode(wasRaw);
+      stdin.pause();
+      if (rest) stdin.unshift(Buffer.from(rest, "utf8"));
+      process.stderr.write("\n");
+      fn(value);
+    };
+
+    const onError = (err) => done(reject, err);
+
+    const onData = (chunk) => {
+      const text = chunk.toString("utf8");
+      for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (ch === "\r" || ch === "\n") {
+          // Whatever followed the newline belongs to the next prompt. A terminal
+          // or a pty can deliver both answers in one chunk, and dropping the
+          // remainder left the next prompt waiting for input already read and
+          // discarded — which hung `auth login` just as surely as destroying the
+          // stream did.
+          return done(resolve, input, text.slice(i + 1).replace(/^\n/, ""));
+        }
+        // Raw mode delivers no signal, so Ctrl-C is honoured here or the prompt
+        // cannot be escaped.
+        if (ch === "\u0003") return done(reject, new CliError("Cancelled."));
+        if (ch === "\u007F" || ch === "\b") {
+          input = input.slice(0, -1);
+          continue;
+        }
+        if (ch >= " ") input += ch;
+      }
+    };
+
+    stdin.on("data", onData);
+    stdin.on("error", onError);
+  });
+}
+
+export const __testables = { readRaw };
+
+const SUB = { login, status, list, logout };
+
+export async function run(args, flags) {
+  const [sub = "status", ...rest] = args;
+  const fn = SUB[sub];
+  if (!fn) {
+    throw new CliError(`zumino auth: unknown subcommand "${sub}".`, {
+      hint: `One of: ${Object.keys(SUB).join(", ")}`,
+    });
+  }
+  return fn(rest, flags);
+}
+
+async function login(args, flags) {
+  // `ZUMINO_URL` belongs here too: it is read on all six rungs in config.js, the
+  // README documents it as the host origin, and `/install.sh` — generated per
+  // instance — tells every self-hosted user to run the bare `zumino auth login`.
+  // Without it, following those instructions sent a live token issued by a
+  // self-hosted instance to zumino.cc before anything was validated.
+  const host = (
+    flags.host ??
+    args[0] ??
+    process.env.ZUMINO_URL ??
+    "https://zumino.cc"
+  ).replace(/\/+$/, "");
+
+  // The readline interface is created *after* the token is read, not before.
+  // Both consume stdin, and an interface attached while `askSecret` iterates the
+  // same stream aborts it — the secret prompt failed outright with ABORT_ERR.
+  // So: token first, by whatever means, then a prompt for the name only if no
+  // flag answered it.
+  const ask = prompter();
+
+  try {
+    if (!flags.token) {
+      note(`\nCreate a personal access token at:\n  ${bold(`${host}/app/account`)}\n`);
+    }
+    const token = (flags.token ?? (await ask.secret("Paste it here: "))).trim();
+    if (!token) throw new CliError("No token given.");
+
+    // Verify before storing. A token that does not work is worse in a config
+    // file than absent: the failure surfaces later, somewhere else.
+    const me = await api({ host, token }, "GET", "/me");
+    // Sanitised here because it reaches four sinks: the note below, the config
+    // file (where JSON escapes it and JSON.parse restores it live on every later
+    // `auth list`), that list's table — whose widths count escape bytes as
+    // columns — and the collision hint. `status()` already did this; these did
+    // not.
+    const who = safeText(me?.user?.email ?? me?.user?.name) || "?";
+    const suggested =
+      flags.account ?? new URL(host).hostname.split(".")[0].replace(/[^a-z0-9-]/gi, "") ?? "default";
+    let name = flags.account;
+    if (!name) {
+      // Both prompts are skipped when the flag that answers them is present, so
+      // `--token … --account …` completes with no terminal at all.
+      name = (await ask.line(`Name for this account [${suggested}]: `)).trim() || suggested;
+    }
+
+    const cfg = readConfig();
+
+    // The suggested name is the host's first label, so `zumino.cc` and
+    // `zumino.customer.example` both suggest `zumino`. Overwriting silently
+    // discarded the first credential while every repo mapping kept pointing at
+    // that name — and on one host the redirect guard sees no mismatch, so those
+    // repositories then wrote as the second identity. That is the identity
+    // switch this design exists to prevent, arriving through the back door.
+    const existing = cfg.accounts[name];
+    if (existing && !flags.yes) {
+      throw new CliError(`An account named "${name}" already exists.`, {
+        hint:
+          `It points at ${safeText(existing.host)}${existing.user ? ` as ${safeText(existing.user)}` : ""}. ` +
+          `Choose another name with --account, or pass --yes to replace it ` +
+          `(every repo mapped to "${name}" would then use the new credential).`,
+      });
+    }
+
+    cfg.accounts[name] = { host, token, user: who, readOnly: me?.token?.readOnly ?? false };
+    writeConfig(cfg);
+
+    note(`\nStored account ${bold(name)} in ${configPath()} (0600).`);
+    note(`Signed in as ${who}${me?.token?.readOnly ? " (read-only)" : ""}.`);
+    note(
+      dim(
+        `\nNothing is "current" — that is deliberate, so two agents cannot change\n` +
+          `each other's identity. Tie this repo to the account with: zumino init`,
+      ),
+    );
+    return 0;
+  } finally {
+    ask.close();
+  }
+}
+
+/**
+ * Which rung of the resolution chain answered, and who that makes you.
+ *
+ * The `source` line is the point of this command. "Which account am I about to
+ * write as" has to be a question with a visible answer, or the absence of a
+ * stored current account just moves the confusion somewhere else.
+ */
+async function status(args, flags) {
+  const ctx = resolveContext(flags);
+  let me = null;
+  try {
+    me = await api(ctx, "GET", "/me");
+  } catch (err) {
+    // `err.exitCode`, not a literal 1. The exit codes are the contract a hook or
+    // an agent branches on, and `auth status` is the first command the skill
+    // tells every session to run — so flattening a 3 here meant the one call an
+    // automated wrapper makes to check its footing was the one that misreported
+    // it, while every other command on the same machine exited 3 correctly.
+    const code = err.exitCode ?? 1;
+    if (flags.json) {
+      json({ ...redact(ctx), ok: false, error: err.message, hint: err.hint, exitCode: code });
+      return code;
+    }
+    out(`token:   ${ctx.source}`);
+    out(`host:    ${ctx.host}`);
+    note(`\nzumino: ${err.message}`);
+    if (err.hint) note(`        ${err.hint}`);
+    return code;
+  }
+
+  if (flags.json) {
+    json({ ...redact(ctx), ok: true, user: me?.user, token: me?.token, cli: VERSION });
+    return 0;
+  }
+  // `readOnly` is checked up front and printed here rather than being
+  // discovered through a 403 halfway through a run of writes.
+  const readOnly = me?.token?.readOnly ? "  (read-only)" : "";
+  out(`token:     ${ctx.source}${readOnly}`);
+  out(`host:      ${ctx.host}`);
+  out(`acting as: ${safeText(me?.user?.email ?? me?.user?.name) || "?"}`);
+  if (ctx.workspace) out(`workspace: ${ctx.workspace}`);
+  if (ctx.project) out(`project:   ${ctx.project}`);
+  out(dim(`cli:       ${VERSION}`));
+  return 0;
+}
+
+function redact(ctx) {
+  return { source: ctx.source, host: ctx.host, project: ctx.project, workspace: ctx.workspace };
+}
+
+async function list(args, flags) {
+  const cfg = readConfig();
+  const names = Object.keys(cfg.accounts);
+  if (flags.json) {
+    json({
+      accounts: Object.fromEntries(
+        names.map((n) => [n, { host: cfg.accounts[n].host, user: cfg.accounts[n].user }]),
+      ),
+      repos: cfg.repos,
+    });
+    return 0;
+  }
+  if (names.length === 0) {
+    out("No accounts configured.");
+    note(dim("  Add one with: zumino auth login"));
+    return 0;
+  }
+  table(
+    names.map((n) => [n, safeText(cfg.accounts[n].host), safeText(cfg.accounts[n].user)]),
+    { head: ["ACCOUNT", "HOST", "USER"] },
+  );
+  const repos = Object.entries(cfg.repos ?? {});
+  if (repos.length) {
+    out("");
+    table(repos.map(([k, v]) => [safeText(k), safeText(v.account), safeText(v.project)]), {
+      head: ["REPO", "ACCOUNT", "PROJECT"],
+    });
+  }
+  return 0;
+}
+
+async function logout(args, flags) {
+  const name = args[0] ?? flags.account;
+  if (!name) {
+    throw new CliError("Which account? zumino auth logout <name>", {
+      hint: "List them with: zumino auth list",
+    });
+  }
+  const cfg = readConfig();
+  if (!cfg.accounts[name]) throw new CliError(`No account named "${name}".`);
+  delete cfg.accounts[name];
+  for (const [repo, m] of Object.entries(cfg.repos)) {
+    if (m.account === name) delete cfg.repos[repo];
+  }
+  writeConfig(cfg);
+  out(`Removed ${name}.`);
+  note(
+    dim(
+      "  The token still exists on the server — this only forgot it here.\n" +
+        "  Revoke it at /app/account.",
+    ),
+  );
+  return 0;
+}

package/src/commands/context.js

@@ -0,0 +1,55 @@
+import { api } from "../client.js";
+import { resolveContext } from "../config.js";
+import { CliError } from "../errors.js";
+import { json, note, out, safeText } from "../output.js";
+import { resolveItem } from "../items.js";
+
+/**
+ * `zumino context <CODE>` — the whole brief in one call.
+ *
+ * The endpoint this wraps assembles the epic, the description, the plan, the
+ * acceptance criteria, the blockers and the requests it answers into one
+ * markdown document. The reason to prefer it over six reads is not round trips:
+ * it is that six reads leave the caller to lay them out, and an agent that
+ * assembles its own brief assembles a *plausible* one rather than the real one.
+ */
+export async function run(args, flags) {
+  const [ref] = args;
+  if (!ref) {
+    throw new CliError("Which task? zumino context <CODE>", {
+      hint: "Find one with: zumino queue",
+    });
+  }
+  const ctx = resolveContext(flags);
+  const { path, kind } = await resolveItem(ctx, ref, { kind: "task" });
+
+  if (kind !== "task") {
+    throw new CliError(`${ref} is a ${kind}, and only tasks carry a brief.`, {
+      hint: `Read it with: zumino api GET ${path}`,
+    });
+  }
+
+  const res = await api(ctx, "GET", `${path}/context`, {
+    query: { activity: flags.activity ? "true" : undefined },
+  });
+
+  if (flags.json) {
+    json(res);
+    return 0;
+  }
+
+  // The brief is destined for a prompt or a terminal; neither wants live
+  // escape sequences from somebody else's task description.
+  out(safeText(res.markdown));
+
+  // Readiness goes to stderr: the brief is the answer and belongs in the pipe,
+  // while "this spec is below the bar" is a note to whoever is reading.
+  const r = res.readiness;
+  if (r && !r.meetsBar) {
+    note(
+      `\nzumino: this spec is below the bar — missing ${r.missing.join(", ")}.\n` +
+        `        It will not appear in zumino queue until it is shaped.`,
+    );
+  }
+  return 0;
+}

package/src/commands/epic.js

@@ -0,0 +1,85 @@
+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 { projectPath, resolveItem } from "../items.js";
+
+/*
+ * Epics group tasks, and are not tasks.
+ *
+ * Grouping is one level deep (`docs/decisions/0001`) and there are no sub-tasks,
+ * so there is deliberately nothing here that nests an epic inside anything.
+ */
+
+const SUB = { create, status, list, show };
+
+export async function run(args, flags) {
+  const [sub, ...rest] = args;
+  const fn = SUB[sub];
+  if (!fn) {
+    throw new CliError(`zumino epic: unknown subcommand "${sub ?? ""}".`, {
+      hint: `One of: ${Object.keys(SUB).join(", ")}`,
+    });
+  }
+  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;
+}
+
+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 epics = res?.epics ?? [];
+  if (flags.json) return json(epics), 0;
+  if (epics.length === 0) return out("No epics."), 0;
+  table(
+    epics.map((e) => [
+      `E${e.number}`,
+      e.status ?? "",
+      `${e.progress?.closed ?? 0}/${e.progress?.total ?? 0}`,
+      clip(e.title),
+    ]),
+    { head: ["EPIC", "STATUS", "DONE", "TITLE"] },
+  );
+  return 0;
+}
+
+async function show(args, flags) {
+  const [ref] = args;
+  if (!ref) throw new CliError("zumino epic show <CODE|N>");
+  const ctx = resolveContext(flags);
+  const { path } = await resolveItem(ctx, ref, { kind: "epic" });
+  const res = pick(await api(ctx, "GET", path), "epic");
+  if (flags.json) return json(res), 0;
+  out(`E${res.number}  ${safeText(res.title)}`);
+  out(`status ${res.status}   ${res.progress?.closed ?? 0}/${res.progress?.total ?? 0} done`);
+  if (res.description) out(`\n${safeText(res.description)}`);
+  return 0;
+}

package/src/commands/find.js

@@ -0,0 +1,83 @@
+import { api } 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";
+
+/**
+ * `zumino find <query>` — 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 a
+ * per-kind status needs the kind's own read.
+ */
+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`;
+
+  // `--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 items = res?.items ?? [];
+  if (flags.json) {
+    json(items);
+    return 0;
+  }
+  if (items.length === 0) {
+    out(q ? `Nothing matches "${q}".` : "No items.");
+    return 0;
+  }
+
+  table(
+    items.map((i) => [
+      codeOf(i) || `#${i.number}`,
+      i.kind ?? "",
+      i.state ?? "",
+      clip(i.title),
+      dim(i.project?.slug ?? ""),
+    ]),
+    { 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.`));
+  }
+  return 0;
+}