@mason-data/cli 0.8.0 → 0.10.0

package/dist/src/cli/command.js

@@ -7,24 +7,185 @@
  *
  *   - `mason <name> --help` and `mason help <name>` print its usage and exit 0;
  *   - the usage starts `usage: mason <name>`, and shows at least one example (an indented `mason <name> …` line);
+ *   - it reads in the order a person needs it: the usage line, a short description, the examples, the flags (one
+ *     entry each); then the long prose, and a long --json shape last (`The --json answer: …`, its entry saying so);
  *   - every option the parser takes is in the usage, by its `--name` (and `-x` when it has one);
  *   - `mason --help` lists it with its summary;
  *   - a wrong option prints what is wrong, then the usage, and exits 2.
  */
 import { parseArgs } from "node:util";
 import { err as styleErr, out as styleOut, PLAIN, wrap } from "./style.js";
+import { closest } from "../lib/did-you-mean.js";
+/**
+ * A LINE THAT HOLDS A HOSTED SERVICE'S TEXT IS BROKEN BY THE CLI, NEVER BY THE TERMINAL, AT EVERY WIDTH (PR 481's
+ * class rounds: a value sized to the terminal's width made the terminal start a visual line at column 0 with a forged
+ * `Next` heading, a step or a row; then the same under 40 columns, where no style wraps). src/cli/hosted.ts makes every
+ * value one line with no run of spaces (`serviceText`); the style a command gives its output when that output holds
+ * such a value (`serviceStyle`) makes every renderer here break every line it writes, at the terminal's own width
+ * (`Style.columns`, read when the output is drawn, whatever it is), so no line ever reaches the terminal's edge:
+ *
+ *   - a line takes at most width - 1 columns (one column at width 1), a character outside ASCII counted as two;
+ *   - it breaks at a space where one is in reach, else within the word; the headline, a row's label and a step's
+ *     command are broken as any text is (`strictLines`, the last pass of every renderer: `strict`);
+ *   - every continuation starts at `continuationAt(width)`: CONTINUATION (4) wherever the width leaves 4 columns after
+ *     it, else 1 (3 to 8 columns), else 0 (1 or 2 columns, where one character is a line). The CLI's own lines start at
+ *     0 (a heading, a failure, a tip) or 2 (a row, a step), never at 1 or 4, so a continuation can never be taken for
+ *     one; at 1 or 2 columns nothing the CLI starts a line with fits in a line, so none can be forged either;
+ *   - a value's own column (a row's, a step's description) is kept while it leaves `MIN_ROOM` columns, else its lines
+ *     continue at continuationAt(width), never one character a line under an indent wider than the terminal.
+ *
+ * So what a person sees begin a line is always the CLI's own. A pipe, a file and `--json` are unwrapped as ever (no
+ * terminal width): what an agent parses never changes.
+ */
+export const CONTINUATION = 4;
+/** The fewest columns a value's own column must leave it before its lines continue there. */
+const MIN_ROOM = 12;
+export const serviceStyle = (s) => ({ ...s, untrusted: true });
+/** The columns a word takes, counted so a line never takes more than the terminal has: a character outside ASCII as two. */
+const columns = (w) => { let n = 0; for (const ch of w)
+    n += ch.codePointAt(0) <= 0x7e ? 1 : 2; return n; };
+/** Where a continuation starts on a terminal `width` columns wide (above). */
+export const continuationAt = (width) => lineLimit(width) - CONTINUATION >= 4 ? CONTINUATION : width >= 3 ? 1 : 0;
+/** The most columns one line may take on a terminal `width` wide: one short of its edge, never none. */
+const lineLimit = (width) => Math.max(1, width - 1);
+/** The terminal width a style that holds a service's text breaks at; null when it is no terminal (or holds none). */
+const strictWidth = (s) => s.untrusted ? s.columns ?? s.width : null;
+/** `text` broken at `width` as `serviceStyle` asks (above), its first line after `firstUsed` columns of prefix: every
+ *  line within the limit, a long word broken within, every line after the first at `indent` while that leaves MIN_ROOM,
+ *  else at continuationAt(width). */
+export function strictWrap(text, width, indent, firstUsed) {
+    const limit = lineLimit(width);
+    const cont = Math.max(indent, CONTINUATION) + MIN_ROOM <= limit ? Math.max(indent, CONTINUATION) : continuationAt(width);
+    const lines = [];
+    let line = "", taken = 0, used = firstUsed;
+    const room = () => Math.max(1, limit - used);
+    const breakLine = () => { lines.push(line); line = ""; taken = 0; used = cont; };
+    // a prefix that leaves no room: the text starts on the next line
+    if (limit - used < 1)
+        breakLine();
+    for (const word of text.split(" ")) {
+        if (word === "")
+            continue;
+        const wc = columns(word);
+        if (line && taken + 1 + wc <= room()) {
+            line += ` ${word}`;
+            taken += 1 + wc;
+            continue;
+        }
+        if (line)
+            breakLine();
+        if (wc <= room()) {
+            line = word;
+            taken = wc;
+            continue;
+        }
+        for (const ch of word) {
+            const cc = columns(ch);
+            if (taken + cc > room() && line)
+                breakLine();
+            line += ch;
+            taken += cc;
+        }
+    }
+    lines.push(line);
+    return lines.join(`\n${" ".repeat(cont)}`);
+}
+/** A colour code, which takes no column. */
+const SGR = /^\x1b\[[0-9;]*m/;
+/**
+ * THE LAST PASS OF EVERY RENDERER under serviceStyle: each line of `text` that would reach the terminal's edge broken
+ * (above) — at its last space in reach, else within a word — its continuations at continuationAt(width), its colour codes
+ * taking no column and never split. A line within the limit is left as it is.
+ */
+export function strictLines(text, width) {
+    const limit = lineLimit(width), cont = continuationAt(width);
+    const out = [];
+    for (const whole of text.split("\n")) {
+        const tokens = [];
+        for (let i = 0; i < whole.length;) {
+            const sgr = SGR.exec(whole.slice(i));
+            if (sgr) {
+                tokens.push({ t: sgr[0], w: 0 });
+                i += sgr[0].length;
+                continue;
+            }
+            const ch = String.fromCodePoint(whole.codePointAt(i));
+            tokens.push({ t: ch, w: columns(ch) });
+            i += ch.length;
+        }
+        if (tokens.reduce((n, k) => n + k.w, 0) <= limit) {
+            out.push(whole);
+            continue;
+        }
+        // the line's own indent, kept while it leaves room for a word, else the continuation's
+        let lead = 0;
+        while (tokens[lead]?.t === " ")
+            lead++;
+        const indent = (n) => Array.from({ length: n }, () => ({ t: " ", w: 1 }));
+        let line = indent(lead + MIN_ROOM <= limit ? lead : Math.min(lead, cont));
+        let taken = line.length, start = line.length;
+        // each token placed in turn; past the limit the line is broken at its last space past the indent, and what followed
+        // the space is placed again from there (so it is broken again if it must), else broken here, within the word
+        let placed = []; // the source index of each of line's tokens past its indent
+        for (let i = lead; i < tokens.length; i++) {
+            const k = tokens[i];
+            if (taken + k.w > limit && taken > start) {
+                let at = -1;
+                for (let j = placed.length - 1; j > 0; j--)
+                    if (tokens[placed[j]].t === " ") {
+                        at = j;
+                        break;
+                    }
+                const kept = at >= 0 ? line.slice(0, start + at) : line;
+                while (kept.length > start && kept[kept.length - 1].t === " ")
+                    kept.pop();
+                out.push(kept.map((x) => x.t).join(""));
+                if (at >= 0)
+                    i = placed[at]; // the loop's i++ places what followed the space
+                else
+                    i--; // this token begins the next line
+                line = indent(cont);
+                taken = cont;
+                start = cont;
+                placed = [];
+                continue;
+            }
+            if (k.t === " " && taken === start && start > 0)
+                continue; // no space at a continuation's start
+            line.push(k);
+            placed.push(i);
+            taken += k.w;
+        }
+        // a continuation with nothing after its indent (the line ended in spaces) is no line
+        if (taken > start || start === 0)
+            out.push(line.map((x) => x.t).join(""));
+    }
+    return out.join("\n");
+}
+/** A renderer's output, as serviceStyle asks it on a terminal (strictLines), else as it is. */
+export const strict = (text, s) => { const w = strictWidth(s); return w === null ? text : strictLines(text, w); };
+/** A renderer's wrap: the strict one for a style that holds a service's text on a terminal, else style.ts's. */
+const fit = (text, s, indent, firstUsed = indent) => {
+    const w = strictWidth(s);
+    return w === null ? wrap(text, s.width, indent, firstUsed) : strictWrap(text, w, indent, firstUsed);
+};
 const HELP = { help: { type: "boolean", short: "h" } };
 /**
  * A command line read by its spec: the values and positionals; or the exit code when it answered itself — 0 after
- * printing the usage for `--help`, 2 after saying what is wrong with the line, then the usage.
+ * printing the usage for `--help` (its spec as data for `--help --json`), 2 after saying what is wrong with the line,
+ * then the usage.
  */
 export function parseCommand(spec, argv) {
+    if (specAsked(spec, argv)) {
+        process.stdout.write(`${specAnswer(spec)}\n`);
+        return 0;
+    }
     let parsed;
     try {
         parsed = parseArgs({ args: argv, options: { ...spec.options, ...HELP }, allowPositionals: true });
     }
     catch (e) {
-        return failed(spec.name, { message: e.message, code: "usage", usage: spec.usage, next: [[`mason ${spec.name} --help`, "its usage, with every option"]] }, { json: wantsJson(argv, spec) });
+        return failed(spec.name, { ...parseProblem(spec, e), code: "usage", usage: synopsis(spec), next: [[`mason ${spec.name} --help`, "its usage, with every option"]] }, { json: wantsJson(argv, spec) });
     }
     if (parsed.values.help) {
         process.stdout.write(spec.usage);
@@ -32,6 +193,140 @@ export function parseCommand(spec, argv) {
     }
     return { values: parsed.values, positionals: parsed.positionals };
 }
+/** A LIST FLAG's value, one comma list however it was written (`multiple: true` in the spec): `--columns id,status`
+ *  and `--columns id --columns status` mean the same, `id,status`; undefined when it was not given. */
+export function listFlag(v) {
+    if (typeof v === "string")
+        return v;
+    return Array.isArray(v) ? v.filter((x) => typeof x === "string").join(",") : undefined;
+}
+/** A command that takes no argument, given one (`mason stop myproject` stopped this folder's project, not that one):
+ *  a wrong line, its usage's synopsis. Null when there is none. */
+export function noArguments(spec, positionals, json) {
+    if (!positionals.length)
+        return null;
+    return failed(spec.name, { message: `it takes no argument (${positionals.join(" ")}): a project is its folder`, code: "usage",
+        fix: `run it in the project's folder: cd <folder> && mason ${spec.name}, or mason -C <folder> ${spec.name}`, usage: synopsis(spec),
+        next: [[`mason ${spec.name} --help`, "its usage, with every option"]] }, { json });
+}
+/** Whether a line asks for the command's spec as data: `--help` (or `-h`) and `--json` on a line that parses — every
+ *  command, whether or not it takes --json itself (mason help, mason mcp): the spec is what an agent reads first. A line
+ *  that does not parse is no such question: parseCommand's own parse says what is wrong with it. */
+function specAsked(spec, argv) {
+    if (!argv.includes("--json") || !(argv.includes("--help") || argv.includes("-h")))
+        return false;
+    try {
+        const options = { ...spec.options, ...HELP, json: { type: "boolean" } };
+        const p = parseArgs({ args: [...argv], options, allowPositionals: true });
+        return p.values["help"] === true && p.values["json"] === true;
+    }
+    catch (e) {
+        // not swallowed: the same line goes on to parseCommand's own parse, which says this error in the CLI's words
+        if (!(e instanceof TypeError))
+            throw e;
+        return false;
+    }
+}
+/** The keys of a command's spec as data (`mason <name> --help --json`, `mason help <name> --json`). */
+export const SPEC_ANSWER_KEYS = ["command", "next"];
+/** What follows a command's spec as data. */
+export const SPEC_NEXT = [["mason help --json", "every command's spec, the guides and the failure codes"]];
+/** A command's spec as its --json answer: `{ command: <spec>, next }`. */
+export const specAnswer = (spec) => jsonText({ ...spec, json: SPEC_ANSWER_KEYS }, { command: specJson(spec) }, SPEC_NEXT);
+/**
+ * THE EXIT CODES, a closed set (`mason help agent` lists them, and each command's spec as data names those it can
+ * exit with): 124 only for a command TIMEOUT_COMMANDS names.
+ */
+export const EXIT_CODES = {
+    0: "done",
+    1: "failed, with the reason",
+    2: "the command line is wrong (without --json the usage follows)",
+    124: "ran out of time (nothing stopped)",
+};
+/** Whether a command can run out of time (exit 124): TIMEOUT_COMMANDS names it. */
+const timesOut = (name) => new RegExp(`\\bmason ${name}\\b`).test(TIMEOUT_COMMANDS);
+export function specJson(spec) {
+    const lines = spec.usage.split("\n");
+    const end = lines.findIndex((l) => l.trim() === "");
+    const forms = lines.slice(0, end < 0 ? lines.length : end).map((l) => l.replace(/^usage:\s*/, "").trim());
+    const options = Object.entries({ ...spec.options, ...HELP }).map(([name, d]) => {
+        // the placeholder the synopsis writes after it, else the first the usage does
+        const placeholder = new RegExp(`--${name}[ =]([^\\s\\[\\]]+)`);
+        const value = d.type === "string" ? (forms.map((f) => placeholder.exec(f)?.[1]).find((v) => v !== undefined) ?? placeholder.exec(spec.usage)?.[1] ?? null) : null;
+        return { name: `--${name}`, short: d.short ? `-${d.short}` : null, type: d.type, multiple: d.multiple === true, default: d.default ?? null, value };
+    });
+    const exitCodes = Object.entries(EXIT_CODES).filter(([code]) => code !== "124" || timesOut(spec.name)).map(([code, meaning]) => ({ code: Number(code), meaning }));
+    return { name: spec.name, summary: spec.summary, usage: spec.usage, forms: forms.map((f) => ({ synopsis: f, positionals: positionalsOf(f, spec.name) })), options,
+        json: spec.json ? [...spec.json] : null, needs: spec.needs ?? null, stdout: spec.stdout ?? null, exitCodes };
+}
+/** The words of a synopsis form that are no option: split at the spaces outside brackets, `mason <name>` and every
+ *  option dropped — a bracketed group that starts with `-` (`[--json]`, `[-n <lines>]`), and a bare option with its
+ *  value (`--ssh <user@server>`). */
+function positionalsOf(form, name) {
+    const words = [];
+    let word = "", depth = 0;
+    for (const ch of form) {
+        if (ch === "[" || ch === "<")
+            depth++;
+        if (ch === "]" || ch === ">")
+            depth = Math.max(0, depth - 1);
+        if (ch === " " && depth === 0) {
+            if (word)
+                words.push(word);
+            word = "";
+            continue;
+        }
+        word += ch;
+    }
+    if (word)
+        words.push(word);
+    const rest = words[0] === "mason" && words[1] === name ? words.slice(2) : words;
+    const out = [];
+    for (let i = 0; i < rest.length; i++) {
+        const w = rest[i];
+        // an option is a dash and a letter (`[--json]`, `-n`); a lone `-` (`mason init -`, stdin) is a positional
+        if (/^\[--?[A-Za-z]/.test(w))
+            continue;
+        if (/^--?[A-Za-z]/.test(w)) {
+            if (rest[i + 1]?.startsWith("<"))
+                i++;
+            continue;
+        }
+        out.push(w);
+    }
+    // an alternative whose other side was an option (`<org>/<name> | --replica <org>/<name>`) leaves no `|` behind
+    return out.filter((w, i) => w !== "|" || (i > 0 && i < out.length - 1));
+}
+/** A command's synopsis: its usage's first lines, up to the first blank one (`usage: mason <name> …` and its other
+ *  forms), then where the rest is. What a wrong line is answered with: the whole usage is for `--help` (94 lines for
+ *  `mason status`, and the mistake scrolled away above it). */
+export function synopsis(spec) {
+    const lines = spec.usage.split("\n");
+    const end = lines.findIndex((l) => l.trim() === "");
+    return `${lines.slice(0, end < 0 ? lines.length : end).join("\n")}\n\nmason ${spec.name} --help for more\n`;
+}
+/** What is wrong with a line the parser refused, in the CLI's words (never Node's, whose advice about `--` misleads):
+ *  an option it does not take, with the closest it does (`didYouMean` over the spec's options and `--help`); one that
+ *  needs a value and has none; one that takes none and was given one. */
+function parseProblem(spec, e) {
+    const options = { ...spec.options, ...HELP };
+    const names = Object.keys(options).map((n) => `--${n}`);
+    const shorts = Object.entries(options).flatMap(([n, d]) => d.short ? [[`-${d.short}`, `--${n}`]] : []);
+    const said = /'(-[^'\s,]*)/.exec(e.message)?.[1];
+    const flag = said === undefined ? undefined : said.startsWith("--") ? said.replace(/=.*$/, "") : said;
+    if (e.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION" && flag !== undefined) {
+        const near = closest(flag, [...names, ...shorts.map(([s]) => s)]);
+        return { message: `there is no option ${flag}${near !== null ? ` — did you mean \`${near}\`?` : ""}`,
+            fix: `its options are ${names.join(", ")}` };
+    }
+    if (e.code === "ERR_PARSE_ARGS_INVALID_OPTION_VALUE" && flag !== undefined) {
+        const long = shorts.find(([s]) => s === flag)?.[1] ?? flag;
+        const named = long === flag ? long : `${flag} (${long})`;
+        const takes = options[long.slice(2)]?.type === "string";
+        return takes ? { message: `${named} needs a value: ${flag} <value>` } : { message: `${named} takes no value: write ${flag} alone` };
+    }
+    return { message: e.message };
+}
 /** The column a step's `what` starts in, after the two-space indent: wide enough for `mason add orders --columns …`. */
 const NEXT_WIDTH = 44;
 /**
@@ -46,25 +341,30 @@ export function nextBlock(steps, s = styleOut()) {
         if (!what)
             return `  ${s.cyan(command)}`;
         const used = 2 + Math.max(command.length, NEXT_WIDTH) + 2;
-        return `  ${s.cyan(command.padEnd(NEXT_WIDTH))}  ${s.dim(wrap(what, s.width, 2 + NEXT_WIDTH + 2, used))}`;
+        // a terminal too narrow for the column under serviceStyle: what it does on the next line, at the continuation
+        const w = strictWidth(s);
+        if (w !== null && 2 + NEXT_WIDTH + 2 + MIN_ROOM > lineLimit(w))
+            return `  ${s.cyan(command)}\n${" ".repeat(continuationAt(w))}${s.dim(fit(what, s, continuationAt(w)))}`;
+        return `  ${s.cyan(command.padEnd(NEXT_WIDTH))}  ${s.dim(fit(what, s, 2 + NEXT_WIDTH + 2, used))}`;
     };
-    return ["", s.bold("Next:"), ...steps.map(step)].join("\n");
+    return strict(["", s.bold("Next:"), ...steps.map(step)].join("\n"), s);
 }
 export function reportText(r, s = styleOut()) {
-    const lines = [s.bold(r.headline)];
+    // a headline is a terminal's to wrap, unless it holds a service's text: then the CLI breaks it (above)
+    const lines = [s.bold(strictWidth(s) !== null ? fit(r.headline, s, CONTINUATION, 0) : r.headline)];
     const w = Math.max(0, ...(r.details ?? []).map(([label]) => label.length));
     for (const [label, value] of r.details ?? [])
-        lines.push(`  ${s.dim(label.padEnd(w))}   ${wrap(value, s.width, 2 + w + 3)}`);
-    return withEnd(lines.join("\n"), r, s);
+        lines.push(`  ${s.dim(label.padEnd(w))}   ${fit(value, s, 2 + w + 3)}`);
+    return strict(withEnd(lines.join("\n"), r, s), s);
 }
 /**
  * The end of a command's output, to print on its own (out(endText(…))): its tips, then what to run next, each part after
  * a blank line; "" when it has neither. withEnd puts it after text a command has not printed yet.
  */
 export function endText(r, s = styleOut()) {
-    const tips = r.tips?.length ? `\n${r.tips.map((t) => s.dim(`Tip: ${wrap(t, s.width, 5)}`)).join("\n")}` : "";
+    const tips = r.tips?.length ? `\n${r.tips.map((t) => s.dim(`Tip: ${fit(t, s, 5)}`)).join("\n")}` : "";
     const next = r.next?.length ? nextBlock(r.next, s) : "";
-    return tips && next ? `${tips}\n${next}` : tips || next;
+    return strict(tips && next ? `${tips}\n${next}` : tips || next, s);
 }
 export function withEnd(text, r, s = styleOut()) {
     const end = endText(r, s);
@@ -97,8 +397,11 @@ export function jsonText(spec, value, next = []) {
         throw new Error(`mason ${spec.name}: its json keys must end with next (every --json answer carries what to run next)`);
     return JSON.stringify({ ...value, next: nextJson(next) }, null, 2);
 }
+/** The commands that can run out of time, exit 124 (code `timeout`): the one list the codes and the agent's guide say. */
+export const TIMEOUT_COMMANDS = "mason wait, mason deploy, mason replica create, mason replica delete, mason login (its code expired), mason share and mason ui --ssh (no address or answer in time)";
 /**
- * THE CODES A FAILURE CARRIES, a closed set a program can branch on (`mason help agent` lists them).
+ * THE CODES A FAILURE CARRIES, a closed set a program can branch on (`mason help agent` lists them): `Failure.code` is
+ * one of them, so a code outside the set does not compile.
  */
 export const FAILURE_CODES = {
     usage: "the command line is wrong: a flag, an argument, a value (exit 2; the usage follows for a person)",
@@ -108,12 +411,16 @@ export const FAILURE_CODES = {
     bad_roles: "the project's roles file (mason/roles.yml) names something wrong: a table the sources file does not sync, a column the synced table lacks, a role with no table; the file, the key and the way out are said",
     not_running: "Mason is not running for the project (mason start)",
     unreachable: "Mason is running but does not answer (mason logs says why)",
+    not_answering: "Mason's process is alive and does not answer its commands, hung: mason stop ends it (its synced data stays)",
     not_found: "a name nothing has: a table, a column, a user",
     nothing_yet: "nothing to work on yet: no table added (the next steps say what adds one)",
     refused: "Mason refused what was asked, with the reason",
     failed: "the command tried and could not finish: the reason, and what to do",
-    timeout: "ran out of time — mason wait; nothing stopped (exit 124)",
+    timeout: `ran out of time — ${TIMEOUT_COMMANDS}; nothing stopped (exit 124)`,
 };
+/** A code another process sent (the run's refusal, the server's Mason over ssh) as one of ours: its own when it is in
+ *  the set, else `otherwise` — a code outside it never reaches a program that branches on the set. */
+export const failureCode = (code, otherwise) => typeof code === "string" && Object.hasOwn(FAILURE_CODES, code) ? code : otherwise;
 /** A failure thrown from deep in a command, for main.ts to print: the one way a failure leaves a command without a return code. */
 export class CommandFailed extends Error {
     failure;
@@ -127,17 +434,17 @@ export function failureText(cmd, f, s = styleErr()) {
     const head = cmd ? `mason ${cmd}:` : "mason:";
     // the checklist's marks: ✘ on a terminal (beside its ✔), ✗ in plain text (beside its ✓); a style that colours is one
     const mark = s.red("x") === "x" ? "✗" : "✘";
-    const lines = [`${s.red(mark)} ${s.red(head)} ${s.bold(wrap(f.message, s.width, 2, mark.length + 1 + head.length + 1))}`];
+    const lines = [`${s.red(mark)} ${s.red(head)} ${s.bold(fit(f.message, s, 2, (strictWidth(s) === null ? mark.length : columns(mark)) + 1 + head.length + 1))}`];
     const rows = [...(f.why ? [["why", f.why]] : []), ...(f.fix ? [["fix", f.fix]] : [])];
     // a value of several lines (a list of failures, an entry to paste) keeps its lines, each under the first
     for (const [label, value] of rows)
-        lines.push(`  ${s.dim(label)}   ${value.split("\n").map((l, i) => i ? `${" ".repeat(8)}${wrap(l, s.width, 8)}` : wrap(l, s.width, 8)).join("\n")}`);
+        lines.push(`  ${s.dim(label)}   ${value.split("\n").map((l, i) => i ? `${" ".repeat(8)}${fit(l, s, 8)}` : fit(l, s, 8)).join("\n")}`);
     let text = lines.join("\n");
     if (f.next?.length)
         text += `\n${nextBlock(f.next, s)}`;
     if (f.usage)
         text += `\n\n${f.usage.replace(/\n$/, "")}`;
-    return text;
+    return strict(text, s);
 }
 /** A failure's `error` as --json carries it: on its own (failureJson), or beside a command's own keys when it did part of
  *  its work (mason add: the tables added; mason wait: the tables' state). */
@@ -154,7 +461,7 @@ export function failureJson(f) {
  * data never has to read prose. tests/conventions.test.ts refuses a `mason <cmd>: …` written to stderr any other way.
  */
 export function failed(cmd, f, o) {
-    const n = asFailure(f);
+    const n = usageWayOut(cmd, asFailure(f));
     const io = o.io ?? STDIO;
     if (o.json)
         io.out(failureJson(n));
@@ -162,6 +469,21 @@ export function failed(cmd, f, o) {
         io.err(failureText(cmd, n, o.style ?? failureStyle(io)));
     return exitOf(n);
 }
+/**
+ * A WRONG COMMAND LINE ALWAYS SAYS WHERE ITS USAGE IS, whatever raised it (the parse, or a command's own check, many of
+ * which answered with `next: []`): its next steps end with `mason <cmd> --help` (`mason --help` for no command), and it
+ * carries a fix, its own, else the way to its usage. Decided here, where every failure is said, so a usage failure added
+ * later cannot leave it out.
+ */
+export function usageWayOut(cmd, f) {
+    if (f.code !== "usage")
+        return f;
+    const help = cmd ? `mason ${cmd} --help` : "mason --help";
+    // `mason help <cmd>` is the same page, so a failure that names it already says where the usage is
+    const said = (c) => c === help || (cmd !== "" && c === `mason help ${cmd}`);
+    const next = f.next?.some(([c]) => said(c)) ? f.next : [...(f.next ?? []), [help, cmd ? "its usage, with every option" : "every command"]];
+    return { ...f, next, fix: f.fix ?? (cmd ? `write the line as its usage says (mason ${cmd} --help)` : "name a command mason --help lists") };
+}
 /** The style a failure is drawn in: stderr's own when it goes to stderr, plain for an io a test or a caller supplied.
  *  By the STREAM, never by "was an io passed" (CLAUDE.md "Two readers, one interface"): mason init defaults its io to
  *  STDIO and passed it on, and every failure it drew was plain — no red head, no dim labels — on a terminal. */