@fnndsc/brasa 0.56.2 → 0.56.4

package/dist/builtins/games/lab.js

@@ -13,6 +13,8 @@ import chalk from 'chalk';
 import { surface_get } from '../../core/surface.js';
 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';
 /** A span of seconds in words: `2d 3h 04m`, `17m 05s`. */
 export function uptime_words(seconds) {
     const s = Math.floor(seconds);
@@ -26,8 +28,53 @@ export function uptime_words(seconds) {
         return `${hours}h ${String(minutes).padStart(2, '0')}m`;
     return `${minutes}m ${String(secs).padStart(2, '0')}s`;
 }
-/** `who`: the surfaces attached to this session. */
-export async function builtin_who(_args) {
+/** `who` takes nothing. */
+const WHO_GRAMMAR = {};
+/**
+ * `who`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [whoCommand] });
+ * ```
+ */
+export const whoCommand = command_declare({
+    name: 'who',
+    grammar: WHO_GRAMMAR,
+    help: {
+        summary: 'Who is attached to this session',
+        description: "Lists the surfaces on this session — each terminal and browser, by the host's name for it — marking the one you are at. A local shell answers for itself alone.",
+        posix: { group: 'System', differs: 'the surfaces on this session (each terminal and browser), not logged-in users' },
+        examples: ['who'],
+    },
+    holds: [],
+    handler: async () => who_run(),
+});
+/**
+ * `who` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `who`: none.
+ * @returns The surfaces, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_who([]);
+ * ```
+ */
+export async function builtin_who(args) {
+    return declaredCommand_run(whoCommand, args);
+}
+/**
+ * Lists the surfaces attached to this session.
+ *
+ * @returns The surfaces.
+ *
+ * @example
+ * ```ts
+ * await who_run();
+ * ```
+ */
+export async function who_run() {
     const peers = surface_get().peers?.() ?? null;
     const user = (await backendInstalled_get()?.session.user_get()) ?? '?';
     if (peers === null) {
@@ -38,8 +85,53 @@ export async function builtin_who(_args) {
     const lines = peers.map((p) => `${user.padEnd(16)} ${p.kind.padEnd(8)} ${p.id}${p.you ? chalk.gray('  (you)') : ''}${p.asking !== undefined ? chalk.yellow(`  ? ${p.asking.trim()}`) : ''}`);
     return envelope_ok(`${lines.join('\n')}\n`, { kind: 'games.who', data: { user, peers } });
 }
-/** `uptime`: how long this process has been up, and who is here. */
-export async function builtin_uptime(_args) {
+/** `uptime` takes nothing. */
+const UPTIME_GRAMMAR = {};
+/**
+ * `uptime`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [uptimeCommand] });
+ * ```
+ */
+export const uptimeCommand = command_declare({
+    name: 'uptime',
+    grammar: UPTIME_GRAMMAR,
+    help: {
+        summary: "How long this session's process has been up",
+        description: 'The time, how long the process serving this session has run, how many surfaces are attached, since when, and its pid.',
+        posix: { group: 'System', differs: "how long this session's process has run, not this machine" },
+        examples: ['uptime'],
+    },
+    holds: [],
+    handler: async () => uptime_run(),
+});
+/**
+ * `uptime` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `uptime`: none.
+ * @returns The uptime, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_uptime([]);
+ * ```
+ */
+export async function builtin_uptime(args) {
+    return declaredCommand_run(uptimeCommand, args);
+}
+/**
+ * Says how long this process has been up, and who is here.
+ *
+ * @returns The uptime.
+ *
+ * @example
+ * ```ts
+ * await uptime_run();
+ * ```
+ */
+export async function uptime_run() {
     const seconds = process.uptime();
     const peers = surface_get().peers?.() ?? null;
     const since = new Date(Date.now() - seconds * 1000);
@@ -48,9 +140,55 @@ export async function builtin_uptime(_args) {
     const line = ` ${now}  up ${uptime_words(seconds)}${who}  (since ${since.toISOString().replace('T', ' ').slice(0, 19)}Z, pid ${process.pid})`;
     return envelope_ok(`${line}\n`, { kind: 'games.uptime', data: { seconds, since: since.toISOString(), pid: process.pid, surfaces: peers?.length ?? null } });
 }
-/** `say [text]`: a surface with a voice speaks it; the console prints it. */
+/** What `say` takes: the words to speak, unless something is piped in. */
+const SAY_GRAMMAR = {
+    operands: [{ name: 'text', kind: 'word', optional: true, repeat: true, summary: 'What to say (default: what is piped in)' }],
+};
+/**
+ * `say [text]`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [sayCommand] });
+ * ```
+ */
+export const sayCommand = command_declare({
+    name: 'say',
+    grammar: SAY_GRAMMAR,
+    help: {
+        summary: 'A surface with a voice speaks it',
+        description: "Hands words to the surface: a browser speaks them (ARGUS, through the page's speech), a terminal prints them. Reads what is piped in, else the words given.",
+        examples: ['say analysis complete', 'fortune | say'],
+    },
+    handler: async (args) => say_run(args.operands.text),
+});
+/**
+ * `say` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `say`.
+ * @returns The words said, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_say(['hello', 'there']);
+ * ```
+ */
 export async function builtin_say(args) {
-    const text = text_input(args);
+    return declaredCommand_run(sayCommand, args);
+}
+/**
+ * Says words: what was piped in, else the words given.
+ *
+ * @param words - The operand words.
+ * @returns The words as said, or a refusal when there are none.
+ *
+ * @example
+ * ```ts
+ * await say_run(['hello']);
+ * ```
+ */
+export async function say_run(words) {
+    const text = text_input(words);
     if (text === null)
         return envelope_error('', undefined, 'say: nothing to say (say hello, or fortune | say)\n');
     const said = text.replace(/\n$/, '').replace(/\s+/g, ' ').trim();

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

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

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

@@ -12,5 +12,65 @@ export declare function rainbow_rgb(position: number, spread: number): [number,
  * @returns The text with a colour per character; plain spaces stay plain.
  */
 export declare function lolcat_paint(text: string, spread?: number, phase?: number): string;
-/** `lolcat [-p SPREAD] [-S PHASE] [text]` */
+/**
+ * `lolcat [-p SPREAD] [-S PHASE] [text]`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [lolcatCommand] });
+ * ```
+ */
+export declare const lolcatCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "text";
+        readonly kind: "word";
+        readonly optional: true;
+        readonly repeat: true;
+        readonly summary: "The text to paint (default: what is piped in)";
+    }];
+    readonly options: {
+        readonly spread: {
+            readonly short: "p";
+            readonly summary: "Characters per rainbow cycle (1 or more)";
+            readonly value: {
+                readonly name: "SPREAD";
+                readonly kind: "number";
+                readonly min: 1;
+            };
+        };
+        readonly phase: {
+            readonly short: "S";
+            readonly summary: "Where the rainbow starts";
+            readonly value: {
+                readonly name: "PHASE";
+                readonly kind: "number";
+            };
+        };
+    };
+}>;
+/**
+ * `lolcat` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `lolcat`.
+ * @returns The painted text, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_lolcat(['-p', '12', 'hello']);
+ * ```
+ */
 export declare function builtin_lolcat(args: string[]): Promise<CommandEnvelope>;
+/**
+ * Paints the piped text, else the words, in a rainbow.
+ *
+ * @param words - The words given.
+ * @param spread - Characters per cycle, or undefined for the default.
+ * @param phase - Where the rainbow starts, or undefined for a random start.
+ * @returns The painted text, or a refusal when there is nothing to paint.
+ *
+ * @example
+ * ```ts
+ * await lolcat_run(['hello'], 12, 0);
+ * ```
+ */
+export declare function lolcat_run(words: ReadonlyArray<string>, spread: number | undefined, phase: number | undefined): Promise<CommandEnvelope>;

package/dist/builtins/games/lolcat.js

@@ -11,6 +11,8 @@
 import chalk from 'chalk';
 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';
 /** 24-bit colour whatever the host thinks of its terminal: every surface here renders it. */
 const paint = new chalk.Instance({ level: 3 });
 /** Characters per rainbow cycle when none is asked. */
@@ -38,34 +40,67 @@ export function lolcat_paint(text, spread = LOLCAT_SPREAD, phase = 0) {
         return paint.rgb(r, g, b)(c);
     }).join('')).join('\n');
 }
-/** `lolcat [-p SPREAD] [-S PHASE] [text]` */
+/** What a `lolcat` line may hold. */
+const LOLCAT_GRAMMAR = {
+    operands: [{ name: 'text', kind: 'word', optional: true, repeat: true, summary: 'The text to paint (default: what is piped in)' }],
+    options: {
+        spread: { short: 'p', summary: 'Characters per rainbow cycle (1 or more)', value: { name: 'SPREAD', kind: 'number', min: 1 } },
+        phase: { short: 'S', summary: 'Where the rainbow starts', value: { name: 'PHASE', kind: 'number' } },
+    },
+};
+/**
+ * `lolcat [-p SPREAD] [-S PHASE] [text]`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [lolcatCommand] });
+ * ```
+ */
+export const lolcatCommand = command_declare({
+    name: 'lolcat',
+    grammar: LOLCAT_GRAMMAR,
+    help: {
+        summary: 'Text in a rainbow',
+        description: 'Paints each character the next hue along a rainbow, drifting down the lines. -p sets how many characters one cycle spans (24), -S where it starts (random). Reads what is piped in, else the words given.',
+        examples: ['fortune | lolcat', 'figlet ARGUS | lolcat', 'motd | lolcat -p 12'],
+    },
+    holds: [],
+    handler: async (args) => lolcat_run(args.operands.text, args.options.spread, args.options.phase),
+});
+/**
+ * `lolcat` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `lolcat`.
+ * @returns The painted text, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_lolcat(['-p', '12', 'hello']);
+ * ```
+ */
 export async function builtin_lolcat(args) {
-    let spread = LOLCAT_SPREAD;
-    let phase = Math.floor(Math.random() * 256);
-    const words = [];
-    for (let i = 0; i < args.length; i++) {
-        const flag = args[i];
-        if (flag === '-p' || flag === '-S') {
-            const n = Number(args[i + 1]);
-            if (!Number.isFinite(n) || (flag === '-p' && n < 1))
-                return envelope_error('', undefined, `lolcat: ${flag} wants a number${flag === '-p' ? ' of 1 or more' : ''}\n`);
-            if (flag === '-p')
-                spread = n;
-            else
-                phase = n;
-            i++;
-        }
-        else if (flag.startsWith('-') && flag.length > 1) {
-            return envelope_error('', undefined, `lolcat: unknown flag '${flag}' (only -p SPREAD and -S PHASE)\n`);
-        }
-        else {
-            words.push(flag);
-        }
-    }
+    return declaredCommand_run(lolcatCommand, args);
+}
+/**
+ * Paints the piped text, else the words, in a rainbow.
+ *
+ * @param words - The words given.
+ * @param spread - Characters per cycle, or undefined for the default.
+ * @param phase - Where the rainbow starts, or undefined for a random start.
+ * @returns The painted text, or a refusal when there is nothing to paint.
+ *
+ * @example
+ * ```ts
+ * await lolcat_run(['hello'], 12, 0);
+ * ```
+ */
+export async function lolcat_run(words, spread, phase) {
+    const cycle = spread ?? LOLCAT_SPREAD;
+    const start = phase ?? Math.floor(Math.random() * 256);
     const text = text_input(words);
     if (text === null)
         return envelope_error('', undefined, 'lolcat: nothing to paint (pipe text in: fortune | lolcat)\n');
     const said = text.replace(/\n$/, '');
-    return envelope_ok(`${lolcat_paint(said, spread, phase)}\n`, { kind: 'games.lolcat', data: { text: said, spread, phase } });
+    return envelope_ok(`${lolcat_paint(said, cycle, start)}\n`, { kind: 'games.lolcat', data: { text: said, spread: cycle, phase: start } });
 }
 //# sourceMappingURL=lolcat.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"lolcat.js","sourceRoot":"","sources":["../../../src/builtins/games/lolcat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAmB,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE5E,6FAA6F;AAC7F,MAAM,KAAK,GAAgB,IAAI,KAAK,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;AAE5D,uDAAuD;AACvD,MAAM,CAAC,MAAM,aAAa,GAAW,EAAE,CAAC;AAExC,+CAA+C;AAC/C,MAAM,UAAU,WAAW,CAAC,QAAgB,EAAE,MAAc;IAC1D,MAAM,CAAC,GAAW,CAAC,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;IACpD,MAAM,OAAO,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC;IACvF,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,SAAiB,aAAa,EAAE,QAAgB,CAAC;IAC1F,MAAM,KAAK,GAAW,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;IAC1D,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAY,EAAE,GAAW,EAAU,EAAE,CACjE,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAS,EAAE,GAAW,EAAU,EAAE;QAC/C,IAAI,CAAC,KAAK,GAAG;YAAE,OAAO,CAAC,CAAC;QACxB,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAA6B,WAAW,CAAC,KAAK,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;QACvF,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CACZ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,6CAA6C;AAC7C,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAc;IACjD,IAAI,MAAM,GAAW,aAAa,CAAC;IACnC,IAAI,KAAK,GAAW,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC;IACpD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,IAAI,CAAC,GAAW,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7C,MAAM,IAAI,GAAW,IAAI,CAAC,CAAC,CAAW,CAAC;QACvC,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YACnC,MAAM,CAAC,GAAW,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACtC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;gBAAE,OAAO,cAAc,CAAC,EAAE,EAAE,SAAS,EAAE,WAAW,IAAI,kBAAkB,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;YACrK,IAAI,IAAI,KAAK,IAAI;gBAAE,MAAM,GAAG,CAAC,CAAC;;gBAAM,KAAK,GAAG,CAAC,CAAC;YAC9C,CAAC,EAAE,CAAC;QACN,CAAC;aAAM,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACnD,OAAO,cAAc,CAAC,EAAE,EAAE,SAAS,EAAE,yBAAyB,IAAI,mCAAmC,CAAC,CAAC;QACzG,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;IACD,MAAM,IAAI,GAAkB,UAAU,CAAC,KAAK,CAAC,CAAC;IAC9C,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,cAAc,CAAC,EAAE,EAAE,SAAS,EAAE,6DAA6D,CAAC,CAAC;IACvH,MAAM,IAAI,GAAW,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC7C,OAAO,WAAW,CAAC,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;AAC9H,CAAC"}
+{"version":3,"file":"lolcat.js","sourceRoot":"","sources":["../../../src/builtins/games/lolcat.ts"],"names":[],"mappings":"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"}

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

@@ -1,9 +1,44 @@
 import { CommandEnvelope } from '@fnndsc/menu';
+import type { ExpressionDeclaration } from '../../core/commandDeclaration.js';
 /** The International code. */
 export declare const MORSE: Readonly<Record<string, string>>;
 /** Text to code: letters a space apart, words a slash apart; an unknown character is dropped. */
 export declare function morse_encode(text: string): string;
 /** Code to text: a group the code does not know becomes `?`. */
 export declare function morse_decode(code: string): string;
-/** `morse [-d] [text]` */
+/**
+ * `morse [-d] [text]`: the declaration. Its words are Morse code as often as
+ * text, and code is dashes (`morse -d ... --- ...`), so it takes its words
+ * as they come and reads `-d` or `--decode` at the front itself.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [morseCommand] });
+ * ```
+ */
+export declare const morseCommand: ExpressionDeclaration;
+/**
+ * `morse` over words already split.
+ *
+ * @param args - The words after `morse`: `-d` or `--decode` first to read code, then the text or the code.
+ * @returns The code or the text, or a refusal when there is nothing to carry.
+ *
+ * @example
+ * ```ts
+ * await builtin_morse(['-d', '...', '---', '...']); // sos
+ * ```
+ */
 export declare function builtin_morse(args: string[]): Promise<CommandEnvelope>;
+/**
+ * Taps out the piped text, else the words, or reads code back.
+ *
+ * @param words - The words of the text or the code.
+ * @param decode - Read code into text rather than text into code.
+ * @returns The result, or a refusal when there is nothing to carry.
+ *
+ * @example
+ * ```ts
+ * await morse_run(['sos'], false); // ... --- ...
+ * ```
+ */
+export declare function morse_run(words: ReadonlyArray<string>, decode: boolean): Promise<CommandEnvelope>;

package/dist/builtins/games/morse.js

@@ -4,6 +4,7 @@
  * `morse hello` taps it out; `morse -d .... . .-.. .-.. ---` reads it. One
  * space between letters, a slash between words, as operators write it. The
  * typed model carries the code so a surface with a speaker can sound it.
+ * Declared in one record (`morseCommand`), its words taken as they come.
  *
  * @module
  */
@@ -27,10 +28,57 @@ export function morse_encode(text) {
 export function morse_decode(code) {
     return code.trim().split(/\s*\/\s*|\s{3,}/).map((word) => word.trim().split(/\s+/).filter((g) => g.length > 0).map((g) => MORSE_BACK[g] ?? '?').join('')).join(' ');
 }
-/** `morse [-d] [text]` */
+/**
+ * `morse [-d] [text]`: the declaration. Its words are Morse code as often as
+ * text, and code is dashes (`morse -d ... --- ...`), so it takes its words
+ * as they come and reads `-d` or `--decode` at the front itself.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [morseCommand] });
+ * ```
+ */
+export const morseCommand = {
+    name: 'morse',
+    grammar: 'expression',
+    help: {
+        usage: 'morse [-d] [text]',
+        summary: 'Text to Morse code and back',
+        description: 'Taps text out in International Morse — one space between letters, a slash between words — or, with -d (or --decode) as the first word, reads code back into text. Morse code is dashes, so its words are taken as they come, never as options. Reads what is piped in, else the words given.',
+        examples: ['morse sos', 'morse -d ... --- ...', 'fortune | morse'],
+    },
+    holds: [],
+    handler: (args) => builtin_morse(args),
+};
+/**
+ * `morse` over words already split.
+ *
+ * @param args - The words after `morse`: `-d` or `--decode` first to read code, then the text or the code.
+ * @returns The code or the text, or a refusal when there is nothing to carry.
+ *
+ * @example
+ * ```ts
+ * await builtin_morse(['-d', '...', '---', '...']); // sos
+ * ```
+ */
 export async function builtin_morse(args) {
     const decode = args[0] === '-d' || args[0] === '--decode';
-    const text = text_input(decode ? args.slice(1) : args);
+    return morse_run(decode ? args.slice(1) : args, decode);
+}
+/**
+ * Taps out the piped text, else the words, or reads code back.
+ *
+ * @param words - The words of the text or the code.
+ * @param decode - Read code into text rather than text into code.
+ * @returns The result, or a refusal when there is nothing to carry.
+ *
+ * @example
+ * ```ts
+ * await morse_run(['sos'], false); // ... --- ...
+ * ```
+ */
+export async function morse_run(words, decode) {
+    const text = text_input(words);
     if (text === null)
         return envelope_error('', undefined, 'morse: usage: morse <text>  |  morse -d <code>\n');
     const said = text.replace(/\n$/, '');

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

@@ -1 +1 @@
-{"version":3,"file":"morse.js","sourceRoot":"","sources":["../../../src/builtins/games/morse.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"morse.js","sourceRoot":"","sources":["../../../src/builtins/games/morse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAmB,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG5E,8BAA8B;AAC9B,MAAM,CAAC,MAAM,KAAK,GAAqC;IACrD,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM;IACnG,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG;IACjG,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM;IAC9D,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO;IAC1I,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ;IAClI,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ;CACtI,CAAC;AAEF,MAAM,UAAU,GAAqC,MAAM,CAAC,WAAW,CACrE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,CAAmB,EAAoB,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAClG,CAAC;AAEF,iGAAiG;AACjG,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,IAAY,EAAU,EAAE,CACzE,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAS,EAAU,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAS,EAAW,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAC5G,CAAC,MAAM,CAAC,CAAC,CAAS,EAAW,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC7D,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,GAAG,CAAC,CAAC,IAAY,EAAU,EAAE,CACvE,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAS,EAAW,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAS,EAAU,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAChI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAA0B;IACjD,IAAI,EAAE,OAAO;IACb,OAAO,EAAE,YAAY;IACrB,IAAI,EAAE;QACJ,KAAK,EAAE,mBAAmB;QAC1B,OAAO,EAAE,6BAA6B;QACtC,WAAW,EAAE,8RAA8R;QAC3S,QAAQ,EAAE,CAAC,WAAW,EAAE,sBAAsB,EAAE,iBAAiB,CAAC;KACnE;IACD,KAAK,EAAE,EAAE;IACT,OAAO,EAAE,CAAC,IAAc,EAA4B,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC;CAC3E,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAc;IAChD,MAAM,MAAM,GAAY,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,UAAU,CAAC;IACnE,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,KAA4B,EAAE,MAAe;IAC3E,MAAM,IAAI,GAAkB,UAAU,CAAC,KAAK,CAAC,CAAC;IAC9C,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,cAAc,CAAC,EAAE,EAAE,SAAS,EAAE,kDAAkD,CAAC,CAAC;IAC5G,MAAM,IAAI,GAAW,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC7C,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,KAAK,GAAW,YAAY,CAAC,IAAI,CAAC,CAAC;QACzC,OAAO,WAAW,CAAC,GAAG,KAAK,IAAI,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC3H,CAAC;IACD,MAAM,IAAI,GAAW,YAAY,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,cAAc,CAAC,EAAE,EAAE,SAAS,EAAE,6CAA6C,CAAC,CAAC;IACrG,OAAO,WAAW,CAAC,GAAG,IAAI,IAAI,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;AAC5G,CAAC"}