@fnndsc/brasa 0.56.1 → 0.56.3

package/dist/builtins/games/chrislab.js

@@ -11,6 +11,8 @@ import { surface_get } from '../../core/surface.js';
 import { uptime_words } from './lab.js';
 import { BRAIN } from './cowsay.js';
 import { envelope_ok, envelope_error } from '@fnndsc/menu';
+import { command_declare } from '../../core/commandDeclaration.js';
+import { declaredCommand_run } from '../../core/commandParse.js';
 /** Round trips `ping` makes when not told. */
 export const PING_COUNT = 3;
 /** The most round trips `ping` makes however asked. */
@@ -61,21 +63,76 @@ export function ping_summary(samples) {
     }
     return out;
 }
-/** `ping [-c N]`: round trips to CUBE. */
-export async function builtin_ping(args, fetchFn = (url, init) => fetch(url, init)) {
-    let count = PING_COUNT;
-    for (let i = 0; i < args.length; i++) {
-        if (args[i] === '-c') {
-            const n = Number(args[i + 1]);
-            if (!Number.isInteger(n) || n < 1)
-                return envelope_error('', undefined, 'ping: -c wants a positive whole number\n');
-            count = Math.min(n, PING_MAX);
-            i++;
-        }
-        else if (args[i] !== 'cube') {
-            return envelope_error('', undefined, `ping: only CUBE is pinged from here (ping [-c N] [cube]); '${args[i]}' is not that\n`);
-        }
-    }
+/** What a `ping` line may hold: how many round trips, and the one place it pings. */
+const PING_GRAMMAR = {
+    operands: [{ name: 'target', kind: 'enum', values: ['cube'], optional: true, summary: 'What to ping: only cube' }],
+    options: {
+        count: { short: 'c', summary: `Round trips to make (default ${PING_COUNT}, at most ${PING_MAX})`, value: { name: 'N', kind: 'int', min: 1 } },
+    },
+};
+/** The fetch `ping` uses unless handed another. */
+const defaultFetch = (url, init) => fetch(url, init);
+/**
+ * Declares `ping` over a fetch (a test hands in its own).
+ *
+ * @param fetchFn - The fetch the command round-trips with.
+ * @returns The declaration.
+ *
+ * @example
+ * ```ts
+ * const command = pingCommand_make(fakeFetch);
+ * ```
+ */
+export function pingCommand_make(fetchFn) {
+    return command_declare({
+        name: 'ping',
+        grammar: PING_GRAMMAR,
+        help: {
+            summary: 'Round trips to CUBE, timed',
+            description: "Makes N (3) HTTP round trips to the CUBE this session talks to and times each, then sums up as ping does — and adds the average of this session's own calls to CUBE so far. Only CUBE is pinged from here: a hosted session is not a probe for the network it sits on.",
+            examples: ['ping', 'ping -c 10'],
+        },
+        handler: async (args) => ping_command(args.options.count, fetchFn),
+    });
+}
+/**
+ * `ping [-c N] [cube]`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [pingCommand] });
+ * ```
+ */
+export const pingCommand = pingCommand_make(defaultFetch);
+/**
+ * `ping` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `ping`.
+ * @param fetchFn - The fetch to use.
+ * @returns The round trips, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_ping(['-c', '2']);
+ * ```
+ */
+export async function builtin_ping(args, fetchFn = defaultFetch) {
+    return declaredCommand_run(fetchFn === defaultFetch ? pingCommand : pingCommand_make(fetchFn), args);
+}
+/**
+ * Round-trips to the session's CUBE and sums up.
+ *
+ * @param asked - How many round trips were asked for; absent for the default.
+ * @param fetchFn - The fetch to use.
+ * @returns The samples and their summary, or a refusal when not connected.
+ *
+ * @example
+ * ```ts
+ * await ping_command(3, fetch);
+ * ```
+ */
+export async function ping_command(asked, fetchFn) {
+    const count = Math.min(asked ?? PING_COUNT, PING_MAX);
     const url = await chrisContext.ChRISURL_get();
     if (url === null)
         return envelope_error('', undefined, 'ping: not connected to a CUBE\n');
@@ -87,8 +144,51 @@ export async function builtin_ping(args, fetchFn = (url, init) => fetch(url, ini
     const recent = ledger.total > 0 ? `\nthis session's own calls: ${ledger.total} to CUBE, ${(ledger.ms / ledger.total).toFixed(0)} ms each on average` : '';
     return envelope_ok(`${lines.join('\n')}\n--- cube ping statistics ---\n${ping_summary(samples)}${recent}\n`, { kind: 'games.ping', data: { url, samples } });
 }
-/** `chrisfetch`: the brain beside the session's facts, neofetch style. */
-export async function builtin_chrisfetch(_args) {
+/** `chrisfetch` takes nothing. */
+const CHRISFETCH_GRAMMAR = {};
+/**
+ * `chrisfetch`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [chrisfetchCommand] });
+ * ```
+ */
+export const chrisfetchCommand = command_declare({
+    name: 'chrisfetch',
+    grammar: CHRISFETCH_GRAMMAR,
+    help: {
+        summary: "The brain beside the session's facts, neofetch style",
+        description: "Who you are and where, feeds by scope, jobs run and the failure rate, the index's state, the surfaces attached, the uptime — beside the ChRIS brain. All from what the session already holds: no extra calls.",
+        examples: ['chrisfetch', 'chrisfetch | lolcat'],
+    },
+    handler: async () => chrisfetch_run(),
+});
+/**
+ * `chrisfetch` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `chrisfetch`: none.
+ * @returns The brain beside the facts, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_chrisfetch([]);
+ * ```
+ */
+export async function builtin_chrisfetch(args) {
+    return declaredCommand_run(chrisfetchCommand, args);
+}
+/**
+ * The brain beside the session's facts, neofetch style.
+ *
+ * @returns The brain and the facts.
+ *
+ * @example
+ * ```ts
+ * await chrisfetch_run();
+ * ```
+ */
+export async function chrisfetch_run() {
     const user = (await chrisContext.ChRISuser_get()) ?? '?';
     const url = await chrisContext.ChRISURL_get();
     const host = url === null ? '(not connected)' : url.replace(/^https?:\/\//, '').replace(/\/api\/v1\/?$/, '');

package/dist/builtins/games/chrislab.js.map

@@ -1 +1 @@
-{"version":3,"file":"chrislab.js","sourceRoot":"","sources":["../../../src/builtins/games/chrislab.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"chrislab.js","sourceRoot":"","sources":["../../../src/builtins/games/chrislab.ts"],"names":[],"mappings":"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"}

package/dist/builtins/games/cowsay.d.ts

@@ -20,7 +20,98 @@ export declare function bubble_draw(lines: string[], thought: boolean): string[]
  * @param width - Wrap width.
  */
 export declare function cowsay_render(text: string, thought?: boolean, width?: number): string;
-/** `cowsay [-W N] [text]` */
+/**
+ * `cowsay [-W N] [text]`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [cowsayCommand] });
+ * ```
+ */
+export declare const cowsayCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "text";
+        readonly kind: "word";
+        readonly optional: true;
+        readonly repeat: true;
+        readonly summary: "What to say (default: what is piped in)";
+    }];
+    readonly options: {
+        readonly width: {
+            readonly short: "W";
+            readonly summary: "Wrap the bubble at N columns (8 or more)";
+            readonly value: {
+                readonly name: "N";
+                readonly kind: "int";
+                readonly min: 8;
+            };
+        };
+    };
+}>;
+/**
+ * `cowthink [-W N] [text]`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [cowthinkCommand] });
+ * ```
+ */
+export declare const cowthinkCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "text";
+        readonly kind: "word";
+        readonly optional: true;
+        readonly repeat: true;
+        readonly summary: "What to say (default: what is piped in)";
+    }];
+    readonly options: {
+        readonly width: {
+            readonly short: "W";
+            readonly summary: "Wrap the bubble at N columns (8 or more)";
+            readonly value: {
+                readonly name: "N";
+                readonly kind: "int";
+                readonly min: 8;
+            };
+        };
+    };
+}>;
+/**
+ * Draws the brain saying or thinking the piped text, else the words.
+ *
+ * @param name - The command's name, for its refusal.
+ * @param words - The words given.
+ * @param thought - Thought bubble rather than speech.
+ * @param width - The wrap width asked for, or undefined for the default.
+ * @returns The picture, or a refusal when there is nothing to say.
+ *
+ * @example
+ * ```ts
+ * await cow_run('cowsay', ['moo'], false, 20);
+ * ```
+ */
+export declare function cow_run(name: string, words: ReadonlyArray<string>, thought: boolean, width: number | undefined): Promise<CommandEnvelope>;
+/**
+ * `cowsay` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `cowsay`.
+ * @returns The picture, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_cowsay(['-W', '20', 'moo']);
+ * ```
+ */
 export declare function builtin_cowsay(args: string[]): Promise<CommandEnvelope>;
-/** `cowthink [-W N] [text]` */
+/**
+ * `cowthink` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `cowthink`.
+ * @returns The picture, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_cowthink(['hmm']);
+ * ```
+ */
 export declare function builtin_cowthink(args: string[]): Promise<CommandEnvelope>;

package/dist/builtins/games/cowsay.js

@@ -10,6 +10,8 @@
  */
 import { text_input } from './stdin.js';
 import { envelope_ok, envelope_error } from '@fnndsc/menu';
+import { command_declare } from '../../core/commandDeclaration.js';
+import { declaredCommand_run } from '../../core/commandParse.js';
 /** The brain, as ASCII has long drawn it. */
 export const BRAIN = [
     '        _---~~(~~-_.',
@@ -85,43 +87,100 @@ export function cowsay_render(text, thought = false, width = COWSAY_WIDTH) {
     const trail = thought ? ['        o', '         o'] : ['        \\', '         \\'];
     return [...bubble_draw(lines, thought), ...trail, ...BRAIN].join('\n') + '\n';
 }
-/** Parses `-W N` out of the arguments; the rest is the text. */
-function cowsayArgs_parse(args) {
-    let width = COWSAY_WIDTH;
-    const words = [];
-    for (let i = 0; i < args.length; i++) {
-        if (args[i] === '-W') {
-            const n = Number(args[i + 1]);
-            if (!Number.isInteger(n) || n < 8)
-                return { refusal: 'cowsay: -W wants a width of 8 or more' };
-            width = n;
-            i++;
-        }
-        else if (args[i]?.startsWith('-') && (args[i]?.length ?? 0) > 1) {
-            return { refusal: `cowsay: unknown flag '${args[i]}' (only -W N)` };
-        }
-        else {
-            words.push(args[i]);
-        }
-    }
-    return { width, words };
-}
-async function cow_run(args, thought, name) {
-    const parsed = cowsayArgs_parse(args);
-    if ('refusal' in parsed)
-        return envelope_error('', undefined, `${parsed.refusal}\n`);
-    const text = text_input(parsed.words);
+/** The words a cow says: what is piped in, else these. */
+const COW_TEXT = { name: 'text', kind: 'word', optional: true, repeat: true, summary: 'What to say (default: what is piped in)' };
+/** What a `cowsay` or `cowthink` line may hold. */
+const COW_GRAMMAR = {
+    operands: [COW_TEXT],
+    options: {
+        width: { short: 'W', summary: 'Wrap the bubble at N columns (8 or more)', value: { name: 'N', kind: 'int', min: 8 } },
+    },
+};
+/**
+ * `cowsay [-W N] [text]`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [cowsayCommand] });
+ * ```
+ */
+export const cowsayCommand = command_declare({
+    name: 'cowsay',
+    grammar: COW_GRAMMAR,
+    help: {
+        summary: 'The ChRIS brain says it — fortune | cowsay',
+        description: 'The classic, with the ChRIS brain for a cow: a speech bubble over the mascot. Says what is piped in, else the words given; -W N wraps at N columns (40 by default).',
+        examples: ['fortune | cowsay', 'cowsay hello, world', 'motd | cowsay -W 60'],
+    },
+    holds: [],
+    handler: async (args) => cow_run('cowsay', args.operands.text, false, args.options.width),
+});
+/**
+ * `cowthink [-W N] [text]`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [cowthinkCommand] });
+ * ```
+ */
+export const cowthinkCommand = command_declare({
+    name: 'cowthink',
+    grammar: COW_GRAMMAR,
+    help: {
+        summary: 'The ChRIS brain thinks it',
+        description: 'cowsay with a thought bubble.',
+        examples: ['fortune | cowthink'],
+    },
+    holds: [],
+    handler: async (args) => cow_run('cowthink', args.operands.text, true, args.options.width),
+});
+/**
+ * Draws the brain saying or thinking the piped text, else the words.
+ *
+ * @param name - The command's name, for its refusal.
+ * @param words - The words given.
+ * @param thought - Thought bubble rather than speech.
+ * @param width - The wrap width asked for, or undefined for the default.
+ * @returns The picture, or a refusal when there is nothing to say.
+ *
+ * @example
+ * ```ts
+ * await cow_run('cowsay', ['moo'], false, 20);
+ * ```
+ */
+export async function cow_run(name, words, thought, width) {
+    const text = text_input(words);
     if (text === null)
         return envelope_error('', undefined, `${name}: nothing to say (pipe text in, or give it: fortune | ${name})\n`);
     const said = text.replace(/\n$/, '');
-    return envelope_ok(cowsay_render(said, thought, parsed.width), { kind: 'games.cowsay', data: { text: said, thought } });
+    return envelope_ok(cowsay_render(said, thought, width ?? COWSAY_WIDTH), { kind: 'games.cowsay', data: { text: said, thought } });
 }
-/** `cowsay [-W N] [text]` */
+/**
+ * `cowsay` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `cowsay`.
+ * @returns The picture, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_cowsay(['-W', '20', 'moo']);
+ * ```
+ */
 export async function builtin_cowsay(args) {
-    return cow_run(args, false, 'cowsay');
+    return declaredCommand_run(cowsayCommand, args);
 }
-/** `cowthink [-W N] [text]` */
+/**
+ * `cowthink` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `cowthink`.
+ * @returns The picture, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_cowthink(['hmm']);
+ * ```
+ */
 export async function builtin_cowthink(args) {
-    return cow_run(args, true, 'cowthink');
+    return declaredCommand_run(cowthinkCommand, args);
 }
 //# sourceMappingURL=cowsay.js.map

package/dist/builtins/games/cowsay.js.map

@@ -1 +1 @@
-{"version":3,"file":"cowsay.js","sourceRoot":"","sources":["../../../src/builtins/games/cowsay.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cowsay.js","sourceRoot":"","sources":["../../../src/builtins/games/cowsay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAmB,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC5E,OAAO,EAAE,eAAe,EAA8C,MAAM,kCAAkC,CAAC;AAC/G,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE,6CAA6C;AAC7C,MAAM,CAAC,MAAM,KAAK,GAA0B;IAC1C,sBAAsB;IACtB,uBAAuB;IACvB,0BAA0B;IAC1B,2BAA2B;IAC3B,2BAA2B;IAC3B,4BAA4B;IAC5B,2BAA2B;IAC3B,0BAA0B;IAC1B,yBAAyB;IACzB,wBAAwB;CACzB,CAAC;AAEF,uCAAuC;AACvC,MAAM,CAAC,MAAM,YAAY,GAAW,EAAE,CAAC;AAEvC,+DAA+D;AAC/D,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,KAAa;IACnD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,MAAM,KAAK,GAAa,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAS,EAAW,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC5F,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAAC,SAAS;QAAC,CAAC;QACnD,IAAI,IAAI,GAAW,EAAE,CAAC;QACtB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;gBAAE,IAAI,GAAG,IAAI,CAAC;iBAC9B,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,IAAI,KAAK;gBAAE,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;iBAC/D,CAAC;gBAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAAC,IAAI,GAAG,IAAI,CAAC;YAAC,CAAC;QACvC,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAe,EAAE,OAAgB;IAC3D,MAAM,KAAK,GAAW,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IACjF,MAAM,GAAG,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACxD,MAAM,GAAG,GAAW,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC;IAChD,MAAM,MAAM,GAAW,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC;IACnD,IAAI,OAAO;QAAE,OAAO,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAS,EAAU,EAAE,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;IACxF,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,GAAG,EAAE,KAAK,GAAG,CAAC,KAAK,CAAC,CAAC,CAAW,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC/E,OAAO;QACL,GAAG;QACH,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAS,EAAE,CAAS,EAAU,EAAE;YAC5C,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,GAAqB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YAClH,OAAO,GAAG,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC;QACtC,CAAC,CAAC;QACF,MAAM;KACP,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,UAAmB,KAAK,EAAE,QAAgB,YAAY;IAChG,MAAM,KAAK,GAAa,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAa,OAAO,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;IAC9F,OAAO,CAAC,GAAG,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,GAAG,KAAK,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAChF,CAAC;AAED,0DAA0D;AAC1D,MAAM,QAAQ,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,yCAAyC,EAAW,CAAC;AAE3I,mDAAmD;AACnD,MAAM,WAAW,GAAG;IAClB,QAAQ,EAAE,CAAC,QAAQ,CAAC;IACpB,OAAO,EAAE;QACP,KAAK,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,0CAA0C,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE;KACtH;CACgC,CAAC;AAEpC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;IAC3C,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,WAAW;IACpB,IAAI,EAAE;QACJ,OAAO,EAAE,4CAA4C;QACrD,WAAW,EAAE,qKAAqK;QAClL,QAAQ,EAAE,CAAC,kBAAkB,EAAE,qBAAqB,EAAE,qBAAqB,CAAC;KAC7E;IACD,KAAK,EAAE,EAAE;IACT,OAAO,EAAE,KAAK,EAAE,IAA0C,EAA4B,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;CAC1J,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,eAAe,CAAC;IAC7C,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,WAAW;IACpB,IAAI,EAAE;QACJ,OAAO,EAAE,2BAA2B;QACpC,WAAW,EAAE,+BAA+B;QAC5C,QAAQ,EAAE,CAAC,oBAAoB,CAAC;KACjC;IACD,KAAK,EAAE,EAAE;IACT,OAAO,EAAE,KAAK,EAAE,IAA0C,EAA4B,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;CAC3J,CAAC,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAY,EAAE,KAA4B,EAAE,OAAgB,EAAE,KAAyB;IACnH,MAAM,IAAI,GAAkB,UAAU,CAAC,KAAK,CAAC,CAAC;IAC9C,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,cAAc,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,IAAI,yDAAyD,IAAI,KAAK,CAAC,CAAC;IACnI,MAAM,IAAI,GAAW,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC7C,OAAO,WAAW,CAAC,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,YAAY,CAAC,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;AACnI,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAc;IACjD,OAAO,mBAAmB,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAc;IACnD,OAAO,mBAAmB,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;AACpD,CAAC"}

package/dist/builtins/games/figlet.d.ts

@@ -9,7 +9,75 @@ export declare const FACE_ROWS: number;
  * @returns The five rows (more for several lines).
  */
 export declare function figlet_render(text: string, ink?: string): string[];
-/** `figlet [text]`: big letters, solid. */
+/**
+ * `figlet [text]`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [figletCommand] });
+ * ```
+ */
+export declare const figletCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "text";
+        readonly kind: "word";
+        readonly optional: true;
+        readonly repeat: true;
+        readonly summary: "The words to set (default: what is piped in)";
+    }];
+}>;
+/**
+ * `banner [text]`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [bannerCommand] });
+ * ```
+ */
+export declare const bannerCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "text";
+        readonly kind: "word";
+        readonly optional: true;
+        readonly repeat: true;
+        readonly summary: "The words to set (default: what is piped in)";
+    }];
+}>;
+/**
+ * Sets the piped text, else the words, in big letters.
+ *
+ * @param name - The command's name, for its refusal.
+ * @param words - The words given.
+ * @param ink - The character to draw with.
+ * @returns The big letters, or a refusal when there is nothing to set.
+ *
+ * @example
+ * ```ts
+ * await big_run('banner', ['hi'], '#');
+ * ```
+ */
+export declare function big_run(name: string, words: ReadonlyArray<string>, ink: string): Promise<CommandEnvelope>;
+/**
+ * `figlet` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `figlet`.
+ * @returns The big letters, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_figlet(['LCARS']);
+ * ```
+ */
 export declare function builtin_figlet(args: string[]): Promise<CommandEnvelope>;
-/** `banner [text]`: big letters in `#`, as banner always drew them. */
+/**
+ * `banner` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `banner`.
+ * @returns The big letters, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_banner(['ChRIS']);
+ * ```
+ */
 export declare function builtin_banner(args: string[]): Promise<CommandEnvelope>;

package/dist/builtins/games/figlet.js

@@ -10,6 +10,8 @@
  */
 import { text_input } from './stdin.js';
 import { envelope_ok, envelope_error } from '@fnndsc/menu';
+import { command_declare } from '../../core/commandDeclaration.js';
+import { declaredCommand_run } from '../../core/commandParse.js';
 /** The face: each glyph five rows, `#` for ink. */
 const FACE = {
     A: [' ### ', '#   #', '#####', '#   #', '#   #'],
@@ -91,19 +93,94 @@ export function figlet_render(text, ink = '#') {
     rows.pop();
     return rows;
 }
-async function big_run(args, ink, name) {
-    const text = text_input(args);
+/** The words to set in big letters: what is piped in, else these. */
+const BIG_TEXT = { name: 'text', kind: 'word', optional: true, repeat: true, summary: 'The words to set (default: what is piped in)' };
+/** What a `figlet` or `banner` line may hold. */
+const BIG_GRAMMAR = { operands: [BIG_TEXT] };
+/**
+ * `figlet [text]`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [figletCommand] });
+ * ```
+ */
+export const figletCommand = command_declare({
+    name: 'figlet',
+    grammar: BIG_GRAMMAR,
+    help: {
+        summary: 'Big letters, solid',
+        description: 'Sets words in a five-row face of solid blocks. Letters, digits and the punctuation a title needs; lowercase is set as capitals. Reads what is piped in, else the words given.',
+        examples: ['figlet LCARS', 'date +%H:%M | figlet'],
+    },
+    holds: [],
+    handler: async (args) => big_run('figlet', args.operands.text, '█'),
+});
+/**
+ * `banner [text]`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [bannerCommand] });
+ * ```
+ */
+export const bannerCommand = command_declare({
+    name: 'banner',
+    grammar: BIG_GRAMMAR,
+    help: {
+        summary: 'Big letters in #, as banner drew them',
+        description: 'figlet in the face banner used: # for ink.',
+        examples: ['banner ChRIS'],
+    },
+    holds: [],
+    handler: async (args) => big_run('banner', args.operands.text, '#'),
+});
+/**
+ * Sets the piped text, else the words, in big letters.
+ *
+ * @param name - The command's name, for its refusal.
+ * @param words - The words given.
+ * @param ink - The character to draw with.
+ * @returns The big letters, or a refusal when there is nothing to set.
+ *
+ * @example
+ * ```ts
+ * await big_run('banner', ['hi'], '#');
+ * ```
+ */
+export async function big_run(name, words, ink) {
+    const text = text_input(words);
     if (text === null)
         return envelope_error('', undefined, `${name}: nothing to set (give words, or pipe them in)\n`);
     const said = text.replace(/\n$/, '');
     return envelope_ok(`${figlet_render(said, ink).join('\n')}\n`, { kind: 'games.figlet', data: { text: said, ink } });
 }
-/** `figlet [text]`: big letters, solid. */
+/**
+ * `figlet` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `figlet`.
+ * @returns The big letters, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_figlet(['LCARS']);
+ * ```
+ */
 export async function builtin_figlet(args) {
-    return big_run(args, '█', 'figlet');
+    return declaredCommand_run(figletCommand, args);
 }
-/** `banner [text]`: big letters in `#`, as banner always drew them. */
+/**
+ * `banner` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `banner`.
+ * @returns The big letters, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_banner(['ChRIS']);
+ * ```
+ */
 export async function builtin_banner(args) {
-    return big_run(args, '#', 'banner');
+    return declaredCommand_run(bannerCommand, args);
 }
 //# sourceMappingURL=figlet.js.map