@fnndsc/brasa 0.56.2 → 0.56.4

package/dist/builtins/fs/xattr.js

@@ -2,16 +2,42 @@
  * @file `setfattr` and `getfattr` — a feed's tags.
  *
  * CUBE's freeform tags on a feed are, in POSIX terms, the values of one
- * extended attribute, `tag`. The capability lives in the kernel
- * (`feedTags_list`, `feedTag_add`, `feedTag_remove`); this is its shell face.
+ * extended attribute, `tag`. Each command is declared in one record: the
+ * attribute's name is one of the words it answers to, the feeds are path
+ * operands that glob. The capability lives in the kernel (`feedTags_list`,
+ * `feedTag_add`, `feedTag_remove`); this is its shell face.
+ *
+ * Key components:
+ * - setfattrCommand, getfattrCommand: the declarations.
+ * - builtin_setfattr, builtin_getfattr: each declaration run over words already split.
+ *
+ * Typical usage:
+ * ```ts
+ * await builtin_setfattr(['-n', 'tag', '-v', 'urgent', 'feed_12']);
+ * ```
+ *
+ * Dependencies: cumin's tag calls; the target and dump words (`xattr.args.ts`).
  *
  * @module
  */
+import chalk from 'chalk';
 import { feedTags_list, feedTag_add, feedTag_remove } from '@fnndsc/cumin';
-import { getfattrArgs_parse, setfattrArgs_parse, xattrTarget_resolve, xattr_render, } from './xattr.args.js';
+import { xattrTarget_resolve, xattr_render } from './xattr.args.js';
 import { error_stripDebugPrefix } from '../utils.js';
 import { errorStack } from '@fnndsc/fond';
 import { envelope_ok, envelope_error } from '@fnndsc/menu';
+import { command_declare } from '../../core/commandDeclaration.js';
+import { declaredCommand_run } from '../../core/commandParse.js';
+import { commandUsage_render } from '../../core/commandUsage.js';
+import { exitCode_set } from '../../core/handlerRun.js';
+/** The feeds a line names, as both commands take them. */
+const FEEDS_OPERAND = {
+    name: 'path',
+    kind: 'cfsPath',
+    repeat: true,
+    glob: true,
+    summary: 'The feeds: an id, feed_N, any path through /feeds/, or /proc/jobs/feed_N',
+};
 /**
  * A refusal, on a line of its own.
  *
@@ -31,19 +57,24 @@ function error_said(fallback) {
     const error = errorStack.stack_pop();
     return error?.message ?? fallback;
 }
+/** What a `getfattr` line may hold. */
+const GETFATTR_GRAMMAR = {
+    operands: [FEEDS_OPERAND],
+    options: {
+        name: { short: 'n', long: 'name', summary: 'The attribute to read (only tag exists)', value: { name: 'name', kind: 'enum', values: ['tag', 'user.tag'] } },
+        dump: { short: 'd', long: 'dump', summary: 'Dump every attribute (the default)' },
+    },
+};
 /**
  * Reads the tags a feed wears, in `getfattr`'s dump shape.
  *
- * @param args - Raw argument tokens.
+ * @param args - The line, parsed.
  * @returns An envelope carrying the rendered blocks and a model of them.
  */
-export async function builtin_getfattr(args) {
-    const parsed = getfattrArgs_parse(args);
-    if (parsed.error !== null)
-        return refusal(parsed.error);
+async function getfattr_run(args) {
     const blocks = [];
     const model = [];
-    for (const path of parsed.paths) {
+    for (const path of args.operands.path) {
         const feedId = xattrTarget_resolve(path);
         if (feedId === null)
             return refusal(`getfattr: '${path}' does not name a feed`);
@@ -56,45 +87,153 @@ export async function builtin_getfattr(args) {
     }
     return envelope_ok(`${blocks.join('\n\n')}\n`, { kind: 'fs.xattr', data: model });
 }
+/**
+ * `getfattr [-d] [-n tag] <path>…`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [getfattrCommand] }, 'backend');
+ * ```
+ */
+export const getfattrCommand = command_declare({
+    name: 'getfattr',
+    grammar: GETFATTR_GRAMMAR,
+    help: {
+        summary: 'Show the tags a feed wears',
+        description: 'Show a feed\'s tags in getfattr\'s dump shape: a # file: line, then one tag="…" line per tag.',
+        category: 'Sharing',
+        posix: { group: 'Files', differs: 'a feed\'s tags, as extended attributes' },
+        examples: [
+            'getfattr feed_12',
+            'getfattr -n tag /home/me/feeds/feed_12',
+        ],
+    },
+    // Reading a feed's tags changes nothing of the session.
+    holds: [],
+    handler: getfattr_run,
+});
+/**
+ * `getfattr` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `getfattr`.
+ * @returns The tags, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_getfattr(['feed_12']);
+ * ```
+ */
+export async function builtin_getfattr(args) {
+    return declaredCommand_run(getfattrCommand, args);
+}
+/** What a `setfattr` line may hold. */
+const SETFATTR_GRAMMAR = {
+    operands: [FEEDS_OPERAND],
+    options: {
+        name: { short: 'n', long: 'name', summary: 'The attribute to set (only tag exists)', value: { name: 'name', kind: 'enum', values: ['tag', 'user.tag'] } },
+        value: { short: 'v', long: 'value', summary: 'The tag', value: { name: 'value', kind: 'word' } },
+        remove: { short: 'x', long: 'remove', summary: 'Remove the tag given by -v, or every tag without -v', value: { name: 'name', kind: 'enum', values: ['tag', 'user.tag'] } },
+    },
+};
+/**
+ * A refusal of a line that says neither what to set nor what to remove, or
+ * a set without its value, with the usage.
+ *
+ * @param reason - What is missing.
+ * @returns The error envelope.
+ */
+function setfattrLine_refuse(reason) {
+    exitCode_set(1);
+    return envelope_error('', undefined, `${chalk.red(`setfattr: ${reason}; usage: ${commandUsage_render(setfattrCommand)}`)}\n`);
+}
 /**
  * Hangs a tag on feeds (`-n tag -v <value>`), or takes one off (`-x tag -v
  * <value>`), or takes every tag off (`-x tag`, as setfattr removes the
  * whole attribute). Silent on success, as setfattr is; a refusal is named.
  *
- * @param args - Raw argument tokens.
+ * @param args - The line, parsed.
  * @returns An envelope, empty on success.
  */
-export async function builtin_setfattr(args) {
-    const parsed = setfattrArgs_parse(args);
-    if (parsed.error !== null)
-        return refusal(parsed.error);
+async function setfattr_run(args) {
+    const { name, remove } = args.options;
+    if (name !== undefined && remove !== undefined)
+        return setfattrLine_refuse('-n sets and -x removes; give one');
+    if (name === undefined && remove === undefined)
+        return setfattrLine_refuse('-n tag or -x tag is needed');
+    const mode = name !== undefined ? 'set' : 'remove';
+    const value = args.options.value === undefined ? null : args.options.value.trim();
+    if (mode === 'set' && (value === null || value === ''))
+        return setfattrLine_refuse(`-n ${name ?? 'tag'} needs -v <value>`);
     const changed = [];
-    for (const path of parsed.paths) {
+    for (const path of args.operands.path) {
         const feedId = xattrTarget_resolve(path);
         if (feedId === null)
             return refusal(`setfattr: '${path}' does not name a feed`);
         let names;
-        if (parsed.mode === 'remove' && parsed.value === null) {
+        if (mode === 'remove' && value === null) {
             const held = await feedTags_list(feedId);
             if (!held.ok)
                 return refusal(error_said(`setfattr: could not read the tags of feed ${feedId}`));
             names = held.value.map((tag) => tag.name);
         }
         else {
-            names = [parsed.value ?? ''];
+            names = [value ?? ''];
         }
-        for (const name of names) {
-            const done = parsed.mode === 'set' ? await feedTag_add(feedId, name) : await feedTag_remove(feedId, name);
+        for (const tagName of names) {
+            const done = mode === 'set' ? await feedTag_add(feedId, tagName) : await feedTag_remove(feedId, tagName);
             if (!done.ok) {
-                const said = error_stripDebugPrefix(error_said(`could not ${parsed.mode === 'set' ? 'add' : 'remove'} tag ${name}`));
+                const said = error_stripDebugPrefix(error_said(`could not ${mode === 'set' ? 'add' : 'remove'} tag ${tagName}`));
                 return refusal(`setfattr: ${path}: ${said}`);
             }
-            if (parsed.mode === 'remove' && parsed.value !== null && !done.value) {
-                return refusal(`setfattr: ${path}: tag="${name}": No such attribute value`);
+            if (mode === 'remove' && value !== null && !done.value) {
+                return refusal(`setfattr: ${path}: tag="${tagName}": No such attribute value`);
             }
-            changed.push({ feedId, tag: name, done: done.value });
+            changed.push({ feedId, tag: tagName, done: done.value });
         }
     }
-    return envelope_ok('', { kind: 'fs.xattr.changed', data: { mode: parsed.mode, changed } });
+    return envelope_ok('', { kind: 'fs.xattr.changed', data: { mode, changed } });
+}
+/**
+ * `setfattr -n tag -v <value> <path>… | -x tag [-v <value>] <path>…`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [setfattrCommand] }, 'backend');
+ * ```
+ */
+export const setfattrCommand = command_declare({
+    name: 'setfattr',
+    grammar: SETFATTR_GRAMMAR,
+    help: {
+        summary: 'Hang a tag on a feed, or take it off',
+        description: 'A feed\'s tags are the values of one extended attribute, tag (also user.tag): CUBE\'s '
+            + 'freeform labels. -n tag -v <value> hangs one of your tags (a folder under /proc/tags: '
+            + 'mkdir /proc/tags/<name> makes a tag, and naming one that does not exist is an error); '
+            + '-x tag -v <value> takes it off; -x tag alone takes every tag off, as '
+            + 'setfattr removes the whole attribute. A feed is named by id, by feed_N, by any path '
+            + 'through /feeds/, or by its projection /proc/jobs/feed_N. Silent on success.',
+        category: 'Sharing',
+        posix: { group: 'Files', differs: 'tags on a feed, as extended attributes' },
+        examples: [
+            'setfattr -n tag -v urgent feed_12',
+            'setfattr -n tag -v review feed_12 feed_13',
+            'setfattr -x tag -v urgent /proc/jobs/feed_12',
+        ],
+    },
+    handler: setfattr_run,
+});
+/**
+ * `setfattr` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `setfattr`.
+ * @returns An envelope, empty on success, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_setfattr(['-x', 'tag', 'feed_12']);
+ * ```
+ */
+export async function builtin_setfattr(args) {
+    return declaredCommand_run(setfattrCommand, args);
 }
 //# sourceMappingURL=xattr.js.map

package/dist/builtins/fs/xattr.js.map

@@ -1 +1 @@
-{"version":3,"file":"xattr.js","sourceRoot":"","sources":["../../../src/builtins/fs/xattr.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,cAAc,EAAgB,MAAM,eAAe,CAAC;AACzF,OAAO,EACL,kBAAkB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,YAAY,GAE1E,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,UAAU,EAAkC,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAmB,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE5E;;;;;GAKG;AACH,SAAS,OAAO,CAAC,OAAe;IAC9B,OAAO,cAAc,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;AACxC,CAAC;AAED;;;;;GAKG;AACH,SAAS,UAAU,CAAC,QAAgB;IAClC,MAAM,KAAK,GAA6B,UAAU,CAAC,SAAS,EAAE,CAAC;IAC/D,OAAO,KAAK,EAAE,OAAO,IAAI,QAAQ,CAAC;AACpC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAc;IACnD,MAAM,MAAM,GAAiB,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACtD,IAAI,MAAM,CAAC,KAAK,KAAK,IAAI;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACxD,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,KAAK,GAA4D,EAAE,CAAC;IAC1E,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAChC,MAAM,MAAM,GAAkB,mBAAmB,CAAC,IAAI,CAAC,CAAC;QACxD,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,OAAO,CAAC,cAAc,IAAI,wBAAwB,CAAC,CAAC;QAChF,MAAM,IAAI,GAAsB,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,CAAC,EAAE;YAAE,OAAO,OAAO,CAAC,UAAU,CAAC,6CAA6C,MAAM,EAAE,CAAC,CAAC,CAAC;QAChG,MAAM,IAAI,GAAa,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAY,EAAU,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1E,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QACtC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,WAAW,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AACpF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAc;IACnD,MAAM,MAAM,GAAiB,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACtD,IAAI,MAAM,CAAC,KAAK,KAAK,IAAI;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACxD,MAAM,OAAO,GAA0D,EAAE,CAAC;IAC1E,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAChC,MAAM,MAAM,GAAkB,mBAAmB,CAAC,IAAI,CAAC,CAAC;QACxD,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,OAAO,CAAC,cAAc,IAAI,wBAAwB,CAAC,CAAC;QAChF,IAAI,KAAe,CAAC;QACpB,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YACtD,MAAM,IAAI,GAAsB,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;YAC5D,IAAI,CAAC,IAAI,CAAC,EAAE;gBAAE,OAAO,OAAO,CAAC,UAAU,CAAC,6CAA6C,MAAM,EAAE,CAAC,CAAC,CAAC;YAChG,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAY,EAAU,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC7D,CAAC;aAAM,CAAC;YACN,KAAK,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;QAC/B,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,IAAI,GAAoB,MAAM,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,MAAM,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YAC3H,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;gBACb,MAAM,IAAI,GAAW,sBAAsB,CAAC,UAAU,CAAC,aAAa,MAAM,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAC;gBAC7H,OAAO,OAAO,CAAC,aAAa,IAAI,KAAK,IAAI,EAAE,CAAC,CAAC;YAC/C,CAAC;YACD,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,KAAK,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACrE,OAAO,OAAO,CAAC,aAAa,IAAI,UAAU,IAAI,4BAA4B,CAAC,CAAC;YAC9E,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IACD,OAAO,WAAW,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;AAC7F,CAAC"}
+{"version":3,"file":"xattr.js","sourceRoot":"","sources":["../../../src/builtins/fs/xattr.ts"],"names":[],"mappings":"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"}

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

@@ -9,13 +9,209 @@ export declare function magic_derive(bytes: Buffer, name?: string): string;
 export declare function hexdump_render(bytes: Buffer, base?: number): string;
 /** The printable runs of at least `min` characters in some bytes. */
 export declare function strings_find(bytes: Buffer, min?: number): string[];
-/** `file <path>...` */
+/**
+ * `file <path…>`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [fileCommand] }, 'backend');
+ * ```
+ */
+export declare const fileCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "path";
+        readonly kind: "cfsPath";
+        readonly repeat: true;
+        readonly glob: true;
+        readonly summary: "The ChRIS files to name; a wildcard matches paths";
+    }];
+}>;
+/**
+ * `file` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `file`.
+ * @returns What each file is, or the refusal of a bad line.
+ */
 export declare function builtin_file(args: string[]): Promise<CommandEnvelope>;
-/** `xxd [-s OFFSET] [-l LENGTH] <path>` */
+/**
+ * `xxd [-s OFFSET] [-l LENGTH] <path>`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [xxdCommand] });
+ * ```
+ */
+export declare const xxdCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "path";
+        readonly kind: "cfsPath";
+        readonly glob: true;
+        readonly summary: "The file";
+    }];
+    readonly options: {
+        readonly offset: {
+            readonly short: "s";
+            readonly summary: "Start at this byte (default 0)";
+            readonly value: {
+                readonly name: "OFFSET";
+                readonly kind: "int";
+                readonly min: 0;
+            };
+        };
+        readonly length: {
+            readonly short: "l";
+            readonly summary: `Show this many bytes (default ${number})`;
+            readonly value: {
+                readonly name: "LENGTH";
+                readonly kind: "int";
+                readonly min: 0;
+            };
+        };
+    };
+}>;
+/**
+ * `xxd` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `xxd`.
+ * @returns The dump, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_xxd(['-l', '16', 'a.txt']);
+ * ```
+ */
 export declare function builtin_xxd(args: string[]): Promise<CommandEnvelope>;
-/** `strings [-n MIN] [-l LIMIT] <path>` */
+/**
+ * Dumps a file's bytes in hex.
+ *
+ * @param path - The CFS path.
+ * @param start - Where to start; absent for the beginning.
+ * @param span - How many bytes to show; absent for the default.
+ * @returns The dump and how much it showed, or why the file cannot be read.
+ *
+ * @example
+ * ```ts
+ * await xxd_run('a.txt', 0, 16);
+ * ```
+ */
+export declare function xxd_run(path: string, start: number | undefined, span: number | undefined): Promise<CommandEnvelope>;
+/**
+ * `strings [-n MIN] [-l LIMIT] <path>`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [stringsCommand] });
+ * ```
+ */
+export declare const stringsCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "path";
+        readonly kind: "cfsPath";
+        readonly glob: true;
+        readonly summary: "The file";
+    }];
+    readonly options: {
+        readonly min: {
+            readonly short: "n";
+            readonly summary: "Shortest run to show (default 4)";
+            readonly value: {
+                readonly name: "MIN";
+                readonly kind: "int";
+                readonly min: 0;
+            };
+        };
+        readonly limit: {
+            readonly short: "l";
+            readonly summary: `Most runs to show (default ${number})`;
+            readonly value: {
+                readonly name: "LIMIT";
+                readonly kind: "int";
+                readonly min: 0;
+            };
+        };
+    };
+}>;
+/**
+ * `strings` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `strings`.
+ * @returns The runs, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_strings(['-n', '8', 'a.bin']);
+ * ```
+ */
 export declare function builtin_strings(args: string[]): Promise<CommandEnvelope>;
-/** `sha256sum <path>...` */
+/**
+ * Lists the printable runs in a file.
+ *
+ * @param path - The CFS path.
+ * @param shortest - The shortest run to show; absent for 4.
+ * @param most - The most runs to show; absent for the default.
+ * @returns The runs and how many there were, or why the file cannot be read.
+ *
+ * @example
+ * ```ts
+ * await strings_run('a.bin', 8, 50);
+ * ```
+ */
+export declare function strings_run(path: string, shortest: number | undefined, most: number | undefined): Promise<CommandEnvelope>;
+/**
+ * `sha256sum <path>...`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [sha256sumCommand] });
+ * ```
+ */
+export declare const sha256sumCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "paths";
+        readonly kind: "cfsPath";
+        readonly glob: true;
+        readonly repeat: true;
+        readonly summary: "The files";
+    }];
+}>;
+/**
+ * `md5sum <path>...`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [md5sumCommand] });
+ * ```
+ */
+export declare const md5sumCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "paths";
+        readonly kind: "cfsPath";
+        readonly glob: true;
+        readonly repeat: true;
+        readonly summary: "The files";
+    }];
+}>;
+/**
+ * `sha256sum` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `sha256sum`.
+ * @returns The digests, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_sha256sum(['a.txt']);
+ * ```
+ */
 export declare function builtin_sha256sum(args: string[]): Promise<CommandEnvelope>;
-/** `md5sum <path>...` */
+/**
+ * `md5sum` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `md5sum`.
+ * @returns The digests, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_md5sum(['a.txt']);
+ * ```
+ */
 export declare function builtin_md5sum(args: string[]): Promise<CommandEnvelope>;