@zumino/cli 2.1.0 → 2.2.0

package/src/main.js

@@ -2,7 +2,10 @@ 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 { note, out } from "./output.js";
+import { command, parseOptions, subcommand } from "./spec.js";
+import { overview, page, suggest } from "./help.js";
+import { validateFlags } from "./flags.js";
 
 import * as auth from "./commands/auth.js";
 import * as queue from "./commands/queue.js";
@@ -11,54 +14,30 @@ 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 project from "./commands/project.js";
+import * as workspace from "./commands/workspace.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";
+import * as commands from "./commands/commands.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.
+ * **What a command is, and what flags it takes, is declared in `spec.js` and
+ * nowhere else.** This file looks the command up there, refuses a flag it does
+ * not accept, and hands the rest to the module below. The help pages are
+ * rendered from the same declaration, so there is no usage string here to fall
+ * out of step with what actually runs.
+ *
+ * The shape of the surface is `DOMAIN.md`'s rule rather than 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 touches one kind hangs off that kind's noun, so a fourth kind
+ * adds a noun rather than widening a flat verb list every script has 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,
@@ -66,58 +45,23 @@ const COMMANDS = {
   task: task.run,
   request: request.run,
   epic: epic.run,
+  project: project.run,
+  workspace: workspace.run,
   api: raw.run,
   auth: auth.run,
   init: init.run,
   skill: skill.run,
   "self-update": selfUpdate.run,
+  commands: commands.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,
+      options: parseOptions(),
       allowPositionals: true,
       strict: true,
     });
@@ -133,21 +77,57 @@ export async function main(argv) {
     out(VERSION);
     return 0;
   }
+
   const [name, ...rest] = positionals;
-  if (!name || name === "help" || (flags.help && !name)) {
-    out(USAGE);
+
+  // `zumino`, `zumino --help`, `zumino help`, `zumino help task list`.
+  if (!name || name === "help") {
+    const words = name === "help" ? rest : [];
+    const rendered = page(words);
+    if (rendered === null) return notACommand(words.join(" "));
+    out(rendered);
     return 0;
   }
 
-  const run = COMMANDS[name];
-  if (!run) {
-    note(`zumino: unknown command "${name}".`);
-    note("Try: zumino --help");
-    return EXIT_FAILURE;
+  const top = command(name);
+  if (!top) return notACommand(name);
+
+  // `zumino task --help` and `zumino task list --help` are the same pages as
+  // `zumino help …`, because an agent reaches for whichever it learned first.
+  if (flags.help) {
+    out(page([name, rest[0]]) ?? page([name]) ?? overview());
+    return 0;
+  }
+
+  /*
+   * A group needs a subcommand, and saying which ones exist is more useful than
+   * repeating that one is missing. The page goes to stdout because it is the
+   * answer to "what can this do"; the refusal goes to stderr and the exit code
+   * is a failure, because the command as typed did nothing.
+   */
+  let leaf = top;
+  let path = top.name;
+  if (top.subcommands) {
+    const sub = rest[0] ?? top.defaultSub;
+    const found = sub ? subcommand(top, sub) : null;
+    if (!found) {
+      note(
+        sub
+          ? `zumino: ${top.name} has no subcommand "${sub}".`
+          : `zumino: ${top.name} needs a subcommand.`,
+      );
+      out(page([top.name]));
+      return EXIT_FAILURE;
+    }
+    leaf = found;
+    path = `${top.name} ${sub}`;
   }
 
   try {
-    return (await run(rest, flags)) ?? 0;
+    // Before the command runs, not inside it: a flag this command does not take
+    // is a refusal, never a value that reaches the wire and is ignored there.
+    validateFlags(leaf, flags, path);
+    return (await COMMANDS[name](rest, flags)) ?? 0;
   } catch (err) {
     if (err instanceof CliError) {
       note(`zumino: ${err.message}`);
@@ -161,3 +141,10 @@ export async function main(argv) {
     return EXIT_FAILURE;
   }
 }
+
+function notACommand(name) {
+  note(`zumino: unknown command "${name}".`);
+  const guess = suggest(name);
+  note(guess ? `        Did you mean: ${guess}` : "        Try: zumino --help");
+  return EXIT_FAILURE;
+}

package/src/output.js

@@ -1,4 +1,3 @@
-import { CliError } from "./errors.js";
 import { styleText } from "node:util";
 
 /*
@@ -158,35 +157,24 @@ export function workspaceSlug(value) {
 }
 
 /**
- * A flag that must be a positive integer, refused rather than coerced.
+ * What the caller is looking at, and how to see the rest of it.
  *
- * `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.
+ * `total` on a paged read is the unpaginated match count, so a page that is a
+ * slice of a larger answer has to say so: a table that stops at fifty rows and
+ * says nothing reads as the whole result, which is exactly how an agent told to
+ * check for duplicates first decides there are none. The next page is named as
+ * the flag that fetches it, because the useful answer to "there is more" is the
+ * command.
  *
- * Returns `undefined` when the flag was not given at all, so a caller can tell
- * the three cases apart.
+ * @param {{total?: unknown}} res   the response envelope
+ * @param {number} shown            rows printed
+ * @param {number|undefined} offset the offset this page was read at
  */
-export function givenFlag(value) {
-  return value === undefined ? undefined : String(value);
+export function pageLine(res, shown, offset = 0) {
+  const total = typeof res?.total === "number" ? res.total : null;
+  const from = offset ?? 0;
+  if (total === null) return `${shown} shown.`;
+  const last = from + shown;
+  if (last >= total) return from === 0 ? `${shown} of ${total}.` : `${from + 1}–${last} of ${total}.`;
+  return `${from + 1}–${last} of ${total} — next page: --offset ${last}`;
 }