@zumino/cli 2.1.0 → 2.2.0

package/src/flags.js

@@ -0,0 +1,257 @@
+import { CliError } from "./errors.js";
+import { flagsFor, valuesOf } from "./spec.js";
+
+/*
+ * What the caller typed: checked against the spec, then coerced.
+ *
+ * `parseArgs` lexes every flag the CLI has, because it runs before the command
+ * is known. That is the whole reason this file exists: without it, `zumino find
+ * --priority high` parses perfectly, reaches the handler, is never read, and
+ * prints an unfiltered list that looks exactly like a filtered one. A flag the
+ * command in hand does not accept is a *refusal*, and so is a value outside the
+ * set the API will act on.
+ *
+ * Both checks read `spec.js`, which is also what the help pages are rendered
+ * from — so a flag cannot be documented and unvalidated, or validated and
+ * undocumented.
+ */
+
+/**
+ * Refuse a flag this command does not take, or a value it cannot mean.
+ *
+ * @param {any} leaf  the spec entry for the command being run
+ * @param {Record<string, any>} flags  `parseArgs` values
+ * @param {string} path  how the command is written, for the message
+ */
+export function validateFlags(leaf, flags, path) {
+  const allowed = flagsFor(leaf);
+
+  for (const name of Object.keys(flags)) {
+    // `--version` and `--help` are answered before dispatch, on every command.
+    if (name === "version" || name === "help") continue;
+
+    // A flag that exists elsewhere in the CLI and is a plausible mistake here
+    // gets the explanation rather than the list. Declared per command, because
+    // what makes `--status` wrong on `find` is a property of that read.
+    const reject = leaf?.rejects?.[name];
+    if (reject) throw new CliError(reject.message, { hint: reject.hint });
+
+    const flag = allowed[name];
+    if (!flag) {
+      const offered = Object.entries(allowed)
+        .filter(([, f]) => !f.global)
+        .map(([n]) => `--${n}`);
+      throw new CliError(`${path} has no --${name}.`, {
+        hint: offered.length
+          ? `It takes: ${offered.join(" ")}. See: zumino help ${path}`
+          : `It takes no flags of its own. See: zumino help ${path}`,
+      });
+    }
+
+    // Checked here as well as where it is read, so `--limit 0` is refused
+    // before a project is resolved and a token is spent on a call that cannot
+    // succeed. The coercion at the call site is what produces the number.
+    if (flag.numeric === "positive") positiveInt(flags[name], name);
+    if (flag.numeric === "nonNegative") nonNegativeInt(flags[name], name);
+
+    // `--assignee someone@example.com` is a wrong *kind* of value, which is this
+    // layer's question — and answering it here means the message arrives before
+    // "No Zumino account is configured", which is what a caller sees first
+    // otherwise and is the less useful of the two.
+    if (flag.shape === "user") {
+      for (const given of listValues(flags, name) ?? []) {
+        assertUserRef(given, { flag: `--${name}`, allowClear: Boolean(flag.clearable) });
+      }
+    }
+
+    /*
+     * `--status ""` and `--status=` are *given* and carry nothing.
+     *
+     * Left alone they are the original defect in miniature: the value list comes
+     * out empty, no filter is sent, and the answer is an unfiltered list at exit
+     * 0. An empty value is only ever an instruction where the field can be
+     * cleared — `--size ""` on a patch — and never on a filter or a closed
+     * vocabulary.
+     */
+    if ((valuesOf(flag) || flag.shape) && !flag.clearable) {
+      const given = listValues(flags, name);
+      if (given && given.length === 0) {
+        throw new CliError(`--${name} was given no value.`, {
+          hint: `See: zumino help ${path}`,
+        });
+      }
+    }
+
+    const values = valuesOf(flag);
+    if (!values) continue;
+    for (const given of listValues(flags, name) ?? []) {
+      // A clearable field accepts `-` as "set this back to nothing", which is
+      // the same spelling `zumino task assign … -` uses.
+      if (flag.clearable && (given === "-" || given === "")) continue;
+      if (!values.includes(given)) {
+        throw new CliError(`--${name} takes ${values.join(", ")} — not "${given}".`, {
+          hint: `See: zumino help ${path}`,
+        });
+      }
+    }
+  }
+}
+
+/**
+ * Every value of a repeatable flag, flattened.
+ *
+ * `--status todo --status shaping` and `--status todo,shaping` are the same
+ * thing, because the API accepts both spellings of the same filter. Empty
+ * segments are dropped, so a trailing comma is not a value the server would
+ * silently ignore.
+ *
+ * @returns {string[]|undefined} `undefined` when the flag was not given
+ */
+export function listValues(flags, name) {
+  const raw = flags[name];
+  if (raw === undefined) return undefined;
+  const all = (Array.isArray(raw) ? raw : [raw])
+    .flatMap((v) => String(v).split(","))
+    .map((v) => v.trim())
+    .filter((v) => v.length > 0);
+  return all;
+}
+
+/**
+ * The single value of a flag that is repeatable in the parser but not here.
+ *
+ * `--status` is a list on `task list` and one value on `task create`. Without
+ * this, the second `--status` would silently win — the same
+ * quietly-dropped-input failure this file exists to stop, one layer down.
+ *
+ * @returns {string|undefined}
+ */
+export function oneValue(flags, name) {
+  const raw = flags[name];
+  if (raw === undefined) return undefined;
+  if (!Array.isArray(raw)) return String(raw);
+  if (raw.length > 1) {
+    throw new CliError(`--${name} takes one value here, and was given ${raw.length}.`);
+  }
+  return raw.length ? String(raw[0]) : undefined;
+}
+
+/**
+ * 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) {
+  return boundedInt(value, flag, 1);
+}
+
+/** Same, for `--offset`, where zero is the first page rather than an error. */
+export function nonNegativeInt(value, flag) {
+  return boundedInt(value, flag, 0);
+}
+
+function boundedInt(value, flag, min) {
+  if (value === undefined || value === null || value === "") return undefined;
+  const raw = Array.isArray(value) ? value[value.length - 1] : value;
+  const n = Number(String(raw).trim());
+  if (!Number.isInteger(n) || n < min) {
+    throw new CliError(
+      `--${flag} takes a whole number${min === 1 ? " of 1 or more" : " of 0 or more"}, not "${raw}".`,
+    );
+  }
+  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) {
+  if (value === undefined) return undefined;
+  return Array.isArray(value) ? String(value[value.length - 1]) : String(value);
+}
+
+/**
+ * The shape of a value that names a person, checked without asking the server.
+ *
+ * The API takes a **user id** everywhere a person is named, which is right and
+ * also unusable by hand — so the two values somebody actually has are both wrong,
+ * and each is wrong misleadingly:
+ *
+ *  - an **email** is looked up as an id and refused with "not a member of this
+ *    workspace", which reads as "that person has no access" rather than "that is
+ *    the wrong kind of value";
+ *  - **`me`** is the one a script wants most and nothing accepted.
+ *
+ * This is the pure half: it classifies what was typed and refuses an email. It
+ * runs in `validateFlags` and, for `zumino task assign`, before the context is
+ * resolved at all — the shape of an argument is wrong whether or not a credential
+ * exists, and "No Zumino account is configured" is the less useful of the two
+ * answers. `resolveUser` in `users.js` is the half that makes the call.
+ *
+ * @param {string} value  a user id, `me`, or `-`/`none`
+ * @param {{flag: string, allowClear?: boolean}} opts
+ * @returns {{kind: "clear"|"me"|"id", id?: string}}
+ */
+export function assertUserRef(value, { flag, allowClear = false }) {
+  const v = String(value ?? "").trim();
+
+  if (v === "-" || v === "" || v === "none") {
+    if (allowClear) return { kind: "clear" };
+    throw new CliError(`--${flag} needs a person: a user id, or "me".`, {
+      hint: "A filter cannot ask for nobody — the API has no unassigned filter.",
+    });
+  }
+  if (v === "me") return { kind: "me" };
+  if (/@/.test(v)) {
+    throw new CliError(`"${v}" looks like an email; ${flag} takes a user id.`, {
+      hint:
+        "Find one on an item you can read: " +
+        "zumino task show <CODE> --json | jq -r '.assignee.id'",
+    });
+  }
+  return { kind: "id", id: v };
+}
+
+/**
+ * The comma-joined form the API's repeatable filters take.
+ *
+ * `?status=todo,shaping` rather than `?status=todo&status=shaping`: the server
+ * accepts either, and one parameter keeps the URL a person can read in a log.
+ */
+export function csv(flags, name) {
+  const all = listValues(flags, name);
+  return all?.length ? all.join(",") : undefined;
+}
+
+/**
+ * The free text a list command searches for, given either way.
+ *
+ * `zumino find "rate limit"` and `zumino find --query "rate limit"` are the same
+ * call. Giving both is refused rather than resolved by precedence: one of the
+ * two was going to be dropped, and a search that quietly answers a different
+ * question than the one asked is the failure this whole module is about.
+ *
+ * @param {string[]} args  positionals left after the subcommand
+ * @param {Record<string, any>} flags
+ */
+export function searchText(args, flags) {
+  const positional = args.join(" ").trim();
+  const flagged = oneValue(flags, "query")?.trim();
+  if (positional && flagged !== undefined && flagged !== positional) {
+    throw new CliError("Give the search text once — as an argument or as --query, not both.");
+  }
+  return (flagged ?? positional) || undefined;
+}

package/src/help.js

@@ -0,0 +1,259 @@
+import {
+  COMMANDS,
+  FLAGS,
+  GLOBAL_FLAGS,
+  GROUPS,
+  command,
+  flagsFor,
+  leaves,
+  subcommand,
+  valuesOf,
+} from "./spec.js";
+import { bold, dim } from "./output.js";
+
+/*
+ * Every page the CLI prints about itself, rendered from `spec.js`.
+ *
+ * Nothing here is written twice. A flag appears on a help page because the
+ * command declares it, and the validator refuses it because the command does
+ * not — the same line of the same file answers both, which is the only way a
+ * `--help` page stays true after the tenth flag is added.
+ *
+ * Three audiences, three shapes, one source:
+ *
+ *  - `overview()` for somebody who typed `zumino` and wants to see the shape of
+ *    it — every command, grouped, one line each.
+ *  - `page()` for somebody who knows which command and needs the accepted
+ *    values — the thing a flat usage string cannot hold.
+ *  - `flat()` and `surface()` for a program. `surface()` is the declaration
+ *    itself, so an agent can discover the vocabularies (`values.taskStatus`)
+ *    rather than guessing them and reading a 400 back.
+ */
+
+const WIDTH = 78;
+
+/** Wrap prose to the terminal, indenting every line including the first. */
+function wrap(text, indent = "  ", width = WIDTH) {
+  const words = String(text).split(/\s+/).filter(Boolean);
+  const lines = [];
+  let line = "";
+  for (const word of words) {
+    if (line && (indent + line + " " + word).length > width) {
+      lines.push(indent + line);
+      line = word;
+    } else {
+      line = line ? `${line} ${word}` : word;
+    }
+  }
+  if (line) lines.push(indent + line);
+  return lines.join("\n");
+}
+
+const pad = (s, n) => s + " ".repeat(Math.max(1, n - s.length));
+
+/** `--status STATUS`, as it is written on a page. */
+function flagSyntax(name, flag) {
+  return flag.arg ? `--${name} ${flag.arg}` : `--${name}`;
+}
+
+/** The global flags, on one line, for the bottom of a command page. */
+function globalLine() {
+  return GLOBAL_FLAGS.filter((n) => n !== "help")
+    .map((n) => flagSyntax(n, FLAGS[n]))
+    .join("  ");
+}
+
+/** `zumino --help`: the whole surface, one line per command. */
+export function overview() {
+  const lines = [
+    `${bold("zumino")} — drive Zumino from a terminal, a script, or an agent.`,
+  ];
+
+  for (const [id, heading] of GROUPS) {
+    const group = COMMANDS.filter((c) => (c.group ?? "meta") === id);
+    if (group.length === 0) continue;
+    lines.push("", bold(heading));
+    for (const c of group) {
+      lines.push(`  ${pad(c.name, 14)}${c.summary}`);
+      if (c.subcommands) {
+        lines.push(dim(`  ${" ".repeat(14)}${c.subcommands.map((s) => s.name).join(" · ")}`));
+      }
+    }
+  }
+
+  lines.push(
+    "",
+    bold("One command in full"),
+    `  zumino help <command> [<subcommand>]   ${dim("e.g. zumino help task list")}`,
+    `  zumino commands [--json]              ${dim("every command at once, for a program")}`,
+    "",
+    bold("Context") +
+      ` is resolved in this order, and ${dim("zumino auth status")} says which won:`,
+    "  --token/--account → ZUMINO_TOKEN → .zumino.json → repo map → sole stored account",
+    "",
+    `${bold("Global flags")}  ${globalLine()}`,
+    `${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`,
+  );
+  return lines.join("\n");
+}
+
+/** The page for one group — its subcommands and what each is for. */
+function groupPage(group) {
+  const width = Math.max(...group.subcommands.map((s) => s.name.length)) + 2;
+  return [
+    `${bold(`zumino ${group.name}`)} — ${group.summary}`,
+    "",
+    ...group.subcommands.map((s) => `  ${pad(s.name, width)}${s.summary}`),
+    "",
+    dim(`  zumino help ${group.name} <subcommand>   for one in full`),
+  ].join("\n");
+}
+
+/**
+ * The page for one command: usage, arguments, every flag with the values it
+ * accepts, why it is shaped the way it is, and examples that run.
+ */
+function leafPage(leaf, path) {
+  const lines = [`${bold(`zumino ${path}`)} — ${leaf.summary}`];
+
+  lines.push("", bold("Usage"), `  ${leaf.usage ?? `zumino ${path}`}`);
+
+  if (leaf.args?.length) {
+    const width = Math.max(...leaf.args.map(([a]) => a.length)) + 2;
+    lines.push("", bold("Arguments"));
+    for (const [arg, help] of leaf.args) lines.push(`  ${pad(arg, width)}${help}`);
+  }
+
+  const own = Object.entries(flagsFor(leaf)).filter(([, f]) => !f.global);
+  if (own.length) {
+    const width = Math.max(...own.map(([n, f]) => flagSyntax(n, f).length)) + 2;
+    lines.push("", bold("Flags"));
+    for (const [name, flag] of own) {
+      lines.push(`  ${pad(flagSyntax(name, flag), width)}${flag.help ?? ""}`);
+      const values = valuesOf(flag);
+      if (values) {
+        const listed = flag.clearable ? [...values, "-"] : values;
+        lines.push(dim(`  ${" ".repeat(width)}${listed.join(" · ")}`));
+      }
+    }
+  }
+  lines.push("", dim(`  Global: ${globalLine()}`));
+
+  if (leaf.notes) lines.push("", bold("Notes"), wrap(leaf.notes));
+
+  if (leaf.examples?.length) {
+    lines.push("", bold("Examples"));
+    for (const ex of leaf.examples) lines.push(`  ${ex}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * The most specific page for what was typed.
+ *
+ * Returns `null` when the name is not a command, so the caller can say so with
+ * a suggestion rather than printing a page for something else.
+ *
+ * @param {string[]} words  e.g. `["task", "list"]`
+ */
+export function page(words) {
+  const [name, sub] = words;
+  if (!name) return overview();
+  const top = command(name);
+  if (!top) return null;
+  if (!top.subcommands) return leafPage(top, top.name);
+  if (!sub) return groupPage(top);
+  const leaf = subcommand(top, sub);
+  if (!leaf) return null;
+  return leafPage(leaf, `${top.name} ${sub}`);
+}
+
+/**
+ * What to suggest when a name is not a command.
+ *
+ * The plural is the guess people and agents actually make — `zumino projects`
+ * for `zumino project list` — so it is answered with the command rather than
+ * with the whole help page.
+ */
+export function suggest(name) {
+  const all = leaves();
+  const bare = String(name ?? "").toLowerCase();
+  const singular = bare.replace(/s$/, "");
+
+  if (bare === "whoami" || bare === "me") return "zumino auth status";
+  if (bare === "login" || bare === "logout") return `zumino auth ${bare}`;
+  if (bare === "ls" || bare === "list" || bare === "search") return "zumino find";
+  if (bare === "show" || bare === "get" || bare === "view") return "zumino task show <CODE>";
+
+  // A group whose list is what was probably meant: `projects` → `project list`.
+  const group = COMMANDS.find((c) => c.name === singular && c.subcommands);
+  if (group && subcommand(group, "list")) return `zumino ${group.name} list`;
+
+  const near = all.find((l) => l.path.startsWith(bare) || l.name === singular);
+  return near ? `zumino ${near.path}` : null;
+}
+
+/** `zumino commands`: every leaf, one line each, for grepping. */
+export function flat() {
+  const all = leaves();
+  const width = Math.max(...all.map((l) => l.path.length)) + 2;
+  return all.map((l) => `${pad(l.path, width)}${l.summary}`).join("\n");
+}
+
+/**
+ * `zumino commands --json`: the declaration itself.
+ *
+ * The shape a program should read before driving this CLI. `values` is the point
+ * of it — the accepted set of every enumerated filter, so a caller does not
+ * discover `in_review` by having `--status review` refused.
+ *
+ * @param {{version: string, values: Record<string, string[]>}} opts
+ */
+export function surface({ version, values }) {
+  return {
+    cli: version,
+    values,
+    global: GLOBAL_FLAGS.filter((n) => n !== "help").map((name) => ({
+      name,
+      arg: FLAGS[name].arg ?? null,
+      type: FLAGS[name].type,
+      help: FLAGS[name].help,
+    })),
+    env: [
+      "ZUMINO_TOKEN",
+      "ZUMINO_URL",
+      "ZUMINO_PROJECT",
+      "ZUMINO_WORKSPACE",
+      "ZUMINO_ACCOUNT",
+      "ZUMINO_NO_UPDATE_CHECK",
+    ],
+    exitCodes: {
+      0: "ok",
+      1: "failed",
+      2: "nothing resolved — no token, project or workspace",
+      3: "this CLI is too old for the server; run zumino self-update",
+    },
+    commands: leaves().map((leaf) => ({
+      path: leaf.path,
+      summary: leaf.summary,
+      usage: leaf.usage ?? `zumino ${leaf.path}`,
+      args: (leaf.args ?? []).map(([name, help]) => ({ name, help })),
+      flags: Object.entries(flagsFor(leaf))
+        .filter(([, f]) => !f.global)
+        .map(([name, f]) => ({
+          name,
+          arg: f.arg ?? null,
+          type: f.type,
+          repeatable: Boolean(f.multiple),
+          values: valuesOf(f),
+          clearable: Boolean(f.clearable),
+          help: f.help ?? null,
+        })),
+      notes: leaf.notes ?? null,
+      examples: leaf.examples ?? [],
+    })),
+  };
+}