@zumino/cli 2.1.0

package/src/commands/task.js

@@ -0,0 +1,223 @@
+import { api } from "../client.js";
+import { resolveContext } from "../config.js";
+import { CliError } from "../errors.js";
+import { codeOf, givenFlag, json, out, pick, positiveInt, safeText } from "../output.js";
+import { projectPath, resolveItem } from "../items.js";
+
+/*
+ * Everything that writes a task.
+ *
+ * Per-kind because `DOMAIN.md` says writes are per-kind: each has its own Zod
+ * schema and its own rate-limit bucket, so a run filing twenty-five tasks is
+ * never the reason naming the epic they belong to is refused.
+ */
+
+const SUB = { create, status, assign, spec, comment, link, ref, attention, show };
+
+export async function run(args, flags) {
+  const [sub, ...rest] = args;
+  const fn = SUB[sub];
+  if (!fn) {
+    throw new CliError(`zumino task: 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("A task needs a title.", {
+      hint: 'zumino task create --title "…"',
+    });
+  }
+  const base = await projectPath(ctx);
+  const body = { title };
+  // `!== undefined`, not truthiness: `--description ""` is an instruction to
+  // leave it blank, and dropping it silently left whatever was there.
+  if (givenFlag(flags.description) !== undefined) body.description = flags.description;
+  if (givenFlag(flags.status) !== undefined) body.status = flags.status;
+  // An **epic** reference in this project, and nothing else.
+  //
+  // `epicNumber` is project-local, so a key prefix cannot express a foreign
+  // epic — its only effect was to let one through silently: `OPS-E14` targeted
+  // epic 14 *here*. And stripping leading letters off anything turned the task
+  // code `ONS-14` into epic 14, which is legal because task and epic numbers are
+  // separate namespaces, so the task was created under the wrong parent and
+  // reported success. Accept `E3` or `3`; refuse everything else and say why.
+  if (givenFlag(flags.epic) !== undefined) {
+    const raw = String(flags.epic).trim();
+    const m = /^[Ee]?(\d+)$/.exec(raw);
+    if (!m) {
+      throw new CliError(`--epic "${raw}" is not an epic in this project.`, {
+        hint:
+          "Write E3 or 3. A task code like ONS-14 is not an epic, and an epic in " +
+          "another project cannot be a parent — move the task instead.",
+      });
+    }
+    body.epicNumber = positiveInt(m[1], "epic");
+  }
+
+  const res = pick(await api(ctx, "POST", `${base}/tasks`, { body }), "task");
+  if (flags.json) return json(res), 0;
+  out(`${codeOf(res)}  ${safeText(res.title)}`);
+  return 0;
+}
+
+async function status(args, flags) {
+  const [ref, value] = args;
+  if (!ref || !value) {
+    throw new CliError("zumino task status <CODE> <status>", {
+      hint: "Statuses are tokens: backlog, shaping, todo, in_progress, done, wont_do.",
+    });
+  }
+  const ctx = resolveContext(flags);
+  const { path } = await resolveItem(ctx, ref, { kind: "task" });
+  const res = pick(await api(ctx, "PATCH", path, { body: { status: value } }), "task");
+  if (flags.json) return json(res), 0;
+  out(`${codeOf(res)}  ${res.status}`);
+  return 0;
+}
+
+async function assign(args, flags) {
+  const [ref, who] = args;
+  if (!ref || !who) {
+    throw new CliError("zumino task assign <CODE> <userId|->", {
+      hint: "`-` clears the assignee. An assignee is always a person, even when an agent does the work.",
+    });
+  }
+  // An email is the natural guess and the server cannot say so: it looks the
+  // value up as a user id and refuses with "not a member of this workspace",
+  // which reads as "that person has no access" rather than "that is the wrong
+  // kind of value". Caught here, where the difference is still visible.
+  if (who !== "-" && /@/.test(who)) {
+    throw new CliError(`"${who}" looks like an email; assign takes a user id.`, {
+      hint: "Find one on an item you can read: zumino task show <CODE> --json | jq -r '.assignee.id'",
+    });
+  }
+
+  const ctx = resolveContext(flags);
+  const { path } = await resolveItem(ctx, ref, { kind: "task" });
+  const res = pick(
+    await api(ctx, "PATCH", path, { body: { assigneeId: who === "-" ? null : who } }),
+    "task",
+  );
+  if (flags.json) return json(res), 0;
+  out(`${codeOf(res)}  ${safeText(res.assignee?.name) || "unassigned"}`);
+  return 0;
+}
+
+/**
+ * The two spec sections are written one at a time, and that is deliberate:
+ * an agent redrafting the plan must not be able to touch the criteria it will
+ * be judged against.
+ */
+async function spec(args, flags) {
+  const [ref] = args;
+  const section = flags.plan !== undefined ? "plan" : flags.acceptance !== undefined ? "acceptance" : null;
+  if (!ref || !section) {
+    throw new CliError("zumino task spec <CODE> --plan TEXT | --acceptance TEXT", {
+      hint: "One section per call, on purpose.",
+    });
+  }
+  if (flags.plan !== undefined && flags.acceptance !== undefined) {
+    throw new CliError("Write one section at a time.", {
+      hint: "The plan and the criteria are written separately so redrafting one cannot touch the other.",
+    });
+  }
+  const ctx = resolveContext(flags);
+  const { path } = await resolveItem(ctx, ref, { kind: "task" });
+  const body = section === "plan" ? flags.plan : flags.acceptance;
+  const res = pick(
+    await api(ctx, "PUT", `${path}/spec/${section}`, { body: { body: body === "" ? null : body } }),
+    "task",
+  );
+  if (flags.json) return json(res), 0;
+  out(`${ref}  ${section} written`);
+  return 0;
+}
+
+async function comment(args, flags) {
+  const [ref, ...text] = args;
+  const bodyText = flags.body ?? text.join(" ").trim();
+  if (!ref || !bodyText) throw new CliError("zumino task comment <CODE> <text>");
+  const ctx = resolveContext(flags);
+  const { path } = await resolveItem(ctx, ref, { kind: "task" });
+  const res = pick(await api(ctx, "POST", `${path}/comments`, { body: { body: bodyText } }), "comment");
+  if (flags.json) return json(res), 0;
+  out(`${ref}  commented`);
+  return 0;
+}
+
+const LINK_TYPES = { blocks: "blocks", "blocked-by": "blockedBy", blockedby: "blockedBy", related: "related", answers: "answers" };
+
+async function link(args, flags) {
+  const [ref, kind, other] = args;
+  const type = LINK_TYPES[String(kind ?? "").toLowerCase()];
+  if (!ref || !type || !other) {
+    throw new CliError("zumino task link <CODE> <blocks|blocked-by|related|answers> <CODE|project#N>", {
+      hint: "`answers` says this work exists because of a request, and takes project#N.",
+    });
+  }
+  const ctx = resolveContext(flags);
+  const { path } = await resolveItem(ctx, ref, { kind: "task" });
+  // A far end written `project#42` is a request; anything else is a task. The
+  // API takes them under different keys because only a request can be answered.
+  const body = other.includes("#") && !/^#?\d+$/.test(other)
+    ? { type, request: other }
+    : { type, task: other };
+  const res = pick(await api(ctx, "POST", `${path}/links`, { body }), "task");
+  if (flags.json) return json(res), 0;
+  out(`${ref}  ${type}  ${other}`);
+  return 0;
+}
+
+async function ref(args, flags) {
+  const [itemRef] = args;
+  const url = flags.url ?? args[1];
+  if (!itemRef || !url) {
+    throw new CliError("zumino task ref <CODE> --url URL [--title T]", {
+      hint: "A ref is the pull request that answers the task — a URL and a title, nothing more.",
+    });
+  }
+  const ctx = resolveContext(flags);
+  const { path } = await resolveItem(ctx, itemRef, { kind: "task" });
+  const body = { url };
+  if (givenFlag(flags.title) !== undefined) body.title = flags.title;
+  const res = pick(await api(ctx, "POST", `${path}/refs`, { body }), "ref");
+  if (flags.json) return json(res), 0;
+  out(`${itemRef}  ${url}`);
+  return 0;
+}
+
+async function attention(args, flags) {
+  const [itemRef, ...text] = args;
+  if (!itemRef) throw new CliError("zumino task attention <CODE> [reason|-]");
+  const ctx = resolveContext(flags);
+  const { path } = await resolveItem(ctx, itemRef, { kind: "task" });
+  const reason = text.join(" ").trim();
+  const res = pick(
+    await api(ctx, "POST", `${path}/attention`, {
+      body: { reason: !reason || reason === "-" ? null : reason },
+    }),
+    "task",
+  );
+  if (flags.json) return json(res), 0;
+  out(`${itemRef}  ${reason && reason !== "-" ? "needs input" : "cleared"}`);
+  return 0;
+}
+
+async function show(args, flags) {
+  const [itemRef] = args;
+  if (!itemRef) throw new CliError("zumino task show <CODE>");
+  const ctx = resolveContext(flags);
+  const { path } = await resolveItem(ctx, itemRef, { kind: "task" });
+  const res = pick(await api(ctx, "GET", path), "task");
+  if (flags.json) return json(res), 0;
+  out(`${codeOf(res)}  ${safeText(res.title)}`);
+  out(`status ${res.status}   priority ${res.priority ?? "-"}   assignee ${safeText(res.assignee?.name) || "-"}`);
+  if (res.description) out(`\n${safeText(res.description)}`);
+  return 0;
+}

package/src/config.js

@@ -0,0 +1,373 @@
+import { execFileSync } from "node:child_process";
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, parse as parsePath, resolve } from "node:path";
+
+import { CliError, EXIT_UNRESOLVED } from "./errors.js";
+import { safeText } from "./output.js";
+
+/**
+ * A slug that is safe to interpolate into a request path.
+ *
+ * `workspace` and `project` can come from a committed `.zumino.json`, and they
+ * are interpolated into every workspace-scoped path. Unvalidated, a value like
+ * `x/../../workspaces/acme/projects/feedback/requests/99?ignored=` is resolved
+ * by `new URL()` — dot segments collapse and `?` starts a query — so the fixed
+ * suffix the command appended became query text and the write landed on a
+ * different item, while the CLI printed the identifier the user asked for.
+ *
+ * The API's own slugs are lowercase alphanumeric with hyphens, and a key is the
+ * uppercase project prefix, so anything outside that is refused rather than
+ * escaped: encoding would make a hostile value merely fail, and saying why is
+ * more useful than a 404.
+ */
+const SAFE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export function requireSafeSegment(value, what, origin) {
+  if (value === null || value === undefined) return value;
+  const v = String(value);
+  if (!SAFE_SEGMENT.test(v)) {
+    throw new CliError(
+      // The value is the reason this threw — it contains bytes outside the
+      // grammar — so it is exactly what must not reach a terminal live.
+      `${what} "${safeText(v)}" is not a valid slug.`,
+      {
+        exitCode: EXIT_UNRESOLVED,
+        hint: origin
+          ? `It came from ${safeText(origin)}. A slug is letters, digits, dots, dashes and underscores.`
+          : "A slug is letters, digits, dots, dashes and underscores.",
+      },
+    );
+  }
+  return v;
+}
+
+/*
+ * Where an account, a host and a project come from.
+ *
+ * The rule and the reasoning are `docs/decisions/0006-an-identity-is-discovered-
+ * not-current.md`, and the short version is the thing this file must not grow:
+ * **there is no stored current account and no `switch` command.** One person
+ * holds several accounts across several hosts, and two agents run in two
+ * checkouts at once — a single mutable "active" pointer in the home directory
+ * would let either of them silently change the other's identity, and a tracker
+ * write landing as the wrong person against the wrong host looks exactly like
+ * success.
+ *
+ * So resolution reads only two things: the process's own environment, and the
+ * directory it is standing in. Neither is shared between concurrent agents.
+ */
+
+/** ~/.config/zumino/config.json, honouring XDG_CONFIG_HOME. */
+export function configPath() {
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(base, "zumino", "config.json");
+}
+
+/** @returns {{accounts: Record<string, any>, repos: Record<string, any>}} */
+export function readConfig() {
+  try {
+    const raw = JSON.parse(readFileSync(configPath(), "utf8"));
+    return { accounts: raw.accounts ?? {}, repos: raw.repos ?? {} };
+  } catch {
+    // A missing or unreadable config is not an error here: the environment or a
+    // `.zumino.json` may still answer, and rung 6 is where refusal happens.
+    return { accounts: {}, repos: {} };
+  }
+}
+
+/** @param {{accounts: Record<string, any>, repos: Record<string, any>}} cfg */
+export function writeConfig(cfg) {
+  const p = configPath();
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 });
+  // `writeFileSync`'s mode applies only when it creates the file, so an existing
+  // one keeps whatever permissions it had. This holds 0600 on every write.
+  chmodSync(p, 0o600);
+}
+
+/**
+ * The nearest `.zumino.json`, walking up from `cwd`.
+ *
+ * Committed, and carries no secret — host and project are facts about the work
+ * and true for everyone who clones. Which *account* a given person uses for this
+ * repository is a fact about their laptop and lives in the home config instead.
+ */
+export function readRepoFile(cwd = process.cwd()) {
+  let dir = resolve(cwd);
+  const { root } = parsePath(dir);
+  for (;;) {
+    try {
+      const raw = JSON.parse(readFileSync(join(dir, ".zumino.json"), "utf8"));
+      return { ...raw, path: join(dir, ".zumino.json") };
+    } catch {
+      /* keep walking */
+    }
+    if (dir === root) return null;
+    dir = dirname(dir);
+  }
+}
+
+/**
+ * How this checkout is named in the home config's repo map.
+ *
+ * The remote URL first, because it survives a directory rename and distinguishes
+ * two clones of different projects that happen to share a basename. The basename
+ * is the fallback for a checkout with no remote — a fresh `git init`, or a
+ * worktree of something never pushed — because refusing those would make the map
+ * useless in exactly the case a new project starts from.
+ */
+export function repoKeys(cwd = process.cwd()) {
+  const keys = [];
+  try {
+    const url = execFileSync("git", ["remote", "get-url", "origin"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (url) keys.push(url);
+  } catch {
+    /* not a repo, or no origin */
+  }
+  try {
+    const top = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (top) keys.push(parsePath(top).base);
+  } catch {
+    keys.push(parsePath(resolve(cwd)).base);
+  }
+  return keys;
+}
+
+/**
+ * Resolve host, token and project, and say which rung answered.
+ *
+ * The chain is fixed and each rung is narrower than the one below it, so the
+ * most specific statement of intent always wins:
+ *
+ *   1. explicit flags                  the caller said so on this command
+ *   2. ZUMINO_TOKEN / ZUMINO_URL       this process, and no other
+ *   3. .zumino.json                    this checkout, for everyone who clones
+ *   4. the home config's repo map      this checkout, for this person
+ *   5. the only account there is       unambiguous by arithmetic
+ *   6. refuse                          never guess
+ *
+ * `source` is not diagnostics. `zumino auth status` prints it, and it is what
+ * makes "who am I about to write as" a question with a visible answer.
+ *
+ * @param {{token?: string, host?: string, project?: string, account?: string}} flags
+ * @param {string} [cwd]
+ */
+export function resolveContext(flags = {}, cwd = process.cwd()) {
+  // Every credential source is checked for an explicit-but-empty value, not
+  // just the two flags. Automation that exports `ZUMINO_TOKEN=''` because a
+  // secret did not populate would otherwise skip that rung on truthiness and
+  // run the mutation as the stored personal account — the same failure the flag
+  // rungs were fixed for, one source over.
+  for (const name of ["ZUMINO_TOKEN", "ZUMINO_ACCOUNT", "ZUMINO_URL"]) {
+    const v = process.env[name];
+    if (v !== undefined && !v.trim()) {
+      throw new CliError(`${name} is set but empty.`, {
+        exitCode: EXIT_UNRESOLVED,
+        hint: "Unset it, or give it a value — refusing to fall back while it names a credential.",
+      });
+    }
+  }
+
+  const cfg = readConfig();
+  const repoFile = readRepoFile(cwd);
+
+  // Project is resolved independently of identity: a flag beats the environment
+  // beats the checkout's own file. Many commands do not need one at all.
+  const project =
+    flags.project ?? process.env.ZUMINO_PROJECT ?? repoFile?.project ?? null;
+  // Every write path names its workspace (`DOMAIN.md` — the segment is a
+  // confirmation, not just an address), so it is resolved the same way. It may
+  // stay null: `client.js` looks it up from the project when it has to, and
+  // `zumino init` pins it so that lookup happens once rather than every command.
+  const workspace =
+    flags.workspace ?? process.env.ZUMINO_WORKSPACE ?? repoFile?.workspace ?? null;
+
+  // `!== undefined`, not truthiness. `--token "$BOT_TOKEN"` with the variable
+  // unset used to skip this rung silently and fall through to the stored
+  // personal account — so a script that named a credential explicitly ran its
+  // mutation as somebody else. An explicit empty value is an error, not an
+  // absence.
+  if (flags.token !== undefined) {
+    if (!String(flags.token).trim()) {
+      throw new CliError("--token was given but is empty.", {
+        exitCode: EXIT_UNRESOLVED,
+        hint: "Refusing to fall back to a stored account when a credential was named explicitly.",
+      });
+    }
+    return mk("flag (--token)", flags.host ?? process.env.ZUMINO_URL, flags.token, project, workspace, repoFile);
+  }
+
+  if (flags.account !== undefined) {
+    if (!String(flags.account).trim()) {
+      throw new CliError("--account was given but is empty.", {
+        exitCode: EXIT_UNRESOLVED,
+        hint: "Refusing to fall back to another account when one was named explicitly.",
+      });
+    }
+    const acct = cfg.accounts[flags.account];
+    if (!acct) {
+      throw new CliError(`No account named "${flags.account}".`, {
+        exitCode: EXIT_UNRESOLVED,
+        hint: `Known accounts: ${Object.keys(cfg.accounts).join(", ") || "none"}. Add one with: zumino auth login`,
+      });
+    }
+    return mk(`account "${flags.account}" (--account)`, flags.host ?? process.env.ZUMINO_URL ?? acct.host, acct.token, project, workspace, repoFile, flags.account);
+  }
+
+  if (process.env.ZUMINO_TOKEN) {
+    const host = flags.host ?? process.env.ZUMINO_URL;
+    return mk("environment (ZUMINO_TOKEN)", host, process.env.ZUMINO_TOKEN, project, workspace, repoFile);
+  }
+
+  if (process.env.ZUMINO_ACCOUNT) {
+    const name = process.env.ZUMINO_ACCOUNT;
+    const acct = cfg.accounts[name];
+    if (!acct) {
+      throw new CliError(`ZUMINO_ACCOUNT names "${name}", which is not configured.`, {
+        exitCode: EXIT_UNRESOLVED,
+        hint: `Known accounts: ${Object.keys(cfg.accounts).join(", ") || "none"}.`,
+      });
+    }
+    return mk(`account "${name}" (ZUMINO_ACCOUNT)`, flags.host ?? process.env.ZUMINO_URL ?? acct.host, acct.token, project, workspace, repoFile, name);
+  }
+
+  // There is deliberately no rung here that lets `.zumino.json` name an account.
+  //
+  // It had one, and it contradicted `docs/decisions/0006`: a committed file
+  // states what to work on, and which *credential* is used here is a fact about
+  // this laptop that lives in the home config's repo map below. Binding the
+  // token to its own account's host stopped a repo exfiltrating it, but a repo
+  // could still *select* a more privileged identity by guessing an account name
+  // — so writes from a checkout you did not author were recorded as that user.
+  //
+  // Nothing is lost: the repo map at the next rung gives an agent in a checkout
+  // the same "no environment needed" resolution, keyed by the checkout's own
+  // remote, from a file only its owner can write.
+
+  for (const key of repoKeys(cwd)) {
+    const mapped = cfg.repos[key];
+    if (!mapped) continue;
+    const acct = cfg.accounts[mapped.account];
+    if (!acct) continue;
+    return mk(
+      `account "${mapped.account}" (repo map: ${key})`,
+      flags.host ?? process.env.ZUMINO_URL ?? acct.host,
+      acct.token,
+      project ?? mapped.project ?? null,
+      workspace ?? mapped.workspace ?? null,
+      repoFile,
+      mapped.account,
+    );
+  }
+
+  const names = Object.keys(cfg.accounts);
+  if (names.length === 1) {
+    const acct = cfg.accounts[names[0]];
+    return mk(
+      `the only account ("${names[0]}")`,
+      flags.host ?? process.env.ZUMINO_URL ?? acct.host,
+      acct.token,
+      project,
+      workspace,
+      repoFile,
+      names[0],
+    );
+  }
+
+  throw new CliError(
+    names.length
+      ? "Several accounts are configured and nothing here says which to use."
+      : "No Zumino account is configured.",
+    {
+      exitCode: EXIT_UNRESOLVED,
+      hint: names.length
+        ? `Pass --account <${names.join("|")}>, set ZUMINO_ACCOUNT, or map this repo: zumino init`
+        : "Run: zumino auth login",
+    },
+  );
+}
+
+const trimHost = (h) => String(h).replace(/\/+$/, "");
+
+/**
+ * Bind a credential to a host, and refuse to let a repository redirect it.
+ *
+ * **`.zumino.json` is committed and carries no secret — but `host` decides
+ * where the secret is *sent*.** A checkout is found by walking up from the
+ * working directory, so any ancestor answers, and the CLI's own documented
+ * workflow is an agent running inside a repository it did not write. If a repo
+ * file could name the host, cloning a hostile one and running any command would
+ * post a `zumino_live_…` token — which authenticates as its owner across every
+ * workspace they belong to — to whatever origin that file chose, before
+ * anything is validated.
+ *
+ * So the credential's own host wins, always, and a repo file may only *agree*
+ * with it. A repo file naming a different host is a hard refusal rather than a
+ * silent redirect, and a repo file that is the sole source of a host is refused
+ * too: something the caller controls — `--host`, `ZUMINO_URL`, or the account
+ * the token came from — has to say where a credential may go.
+ *
+ * @returns {{host: string, token: string, project: string|null, workspace: string|null, source: string}}
+ */
+function mk(source, credentialHost, token, project, workspace = null, repoFile = null, accountName = null) {
+  const repoHost = repoFile?.host ? trimHost(repoFile.host) : null;
+  const host = credentialHost ? trimHost(credentialHost) : null;
+
+  if (host && repoHost && host !== repoHost) {
+    throw new CliError(
+      `${safeText(repoFile.path)} names host ${safeText(repoHost)}, but this credential belongs to ${host}.`,
+      {
+        exitCode: EXIT_UNRESOLVED,
+        hint:
+          "Refusing to send a token to a host the repository chose. " +
+          `If ${safeText(repoHost)} is right, use an account for it or pass --host ${safeText(repoHost)}.`,
+      },
+    );
+  }
+
+  if (!host) {
+    throw new CliError(
+      repoHost
+        ? `${safeText(repoFile.path)} names a host, but nothing says which credential may be sent there.`
+        : "No Zumino host is configured.",
+      {
+        exitCode: EXIT_UNRESOLVED,
+        hint: repoHost
+          ? `Run: zumino auth login ${safeText(repoHost)}   (or set ZUMINO_URL / pass --host)`
+          : "Set ZUMINO_URL, pass --host, or run: zumino init",
+      },
+    );
+  }
+
+  const ws = typeof workspace === "string" ? workspace : (workspace?.slug ?? null);
+  const origin = repoFile?.path ?? "the environment or a flag";
+  return {
+    source,
+    account: accountName,
+    host,
+    token,
+    project: requireSafeSegment(project, "project", origin),
+    workspace: requireSafeSegment(ws, "workspace", origin),
+  };
+}
+
+/**
+ * The project a command needs, or a refusal that says how to supply one.
+ * @param {{project: string|null}} ctx
+ */
+export function requireProject(ctx) {
+  if (ctx.project) return ctx.project;
+  throw new CliError("No project. This command needs one.", {
+    exitCode: EXIT_UNRESOLVED,
+    hint: "Pass --project <slug>, set ZUMINO_PROJECT, or run: zumino init",
+  });
+}

package/src/errors.js

@@ -0,0 +1,47 @@
+/*
+ * What the CLI exits with, and why each code is its own.
+ *
+ * A wrapper — a git hook, a CI step, an agent's shell — branches on the number.
+ * Parsing the message instead is what we are trying to spare them, so the codes
+ * are part of the contract and are documented in `README.md`.
+ */
+
+/** Ordinary failure: the server refused, the arguments were wrong. */
+export const EXIT_FAILURE = 1;
+/** Nothing resolved an account, host or project. Fix the configuration. */
+export const EXIT_UNRESOLVED = 2;
+/** This CLI is older than the server allows. Run `zumino self-update`. */
+export const EXIT_TOO_OLD = 3;
+
+export class CliError extends Error {
+  /**
+   * @param {string} message
+   * @param {{exitCode?: number, hint?: string, key?: string}} [opts]
+   */
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = opts.exitCode ?? EXIT_FAILURE;
+    /** A second line telling the caller what to *do*. Agents act on these. */
+    this.hint = opts.hint;
+    /** The server's stable `errors.*` key, when the failure came from the API. */
+    this.key = opts.key;
+  }
+}
+
+/**
+ * The server says this CLI is too old to be answered.
+ *
+ * Deliberately fatal rather than a warning. The whole point of the handshake is
+ * that a client which no longer matches the shapes it was built against must not
+ * produce a *plausible* answer — silently wrong output from a stale client is
+ * the failure this exists to prevent.
+ *
+ * @param {string} ours @param {string} min @param {string} host
+ */
+export function tooOld(ours, min, host) {
+  return new CliError(
+    `CLI ${ours} is too old for ${host}, which requires >= ${min}.`,
+    { exitCode: EXIT_TOO_OLD, hint: "Run: zumino self-update" },
+  );
+}