@fnndsc/brasa 0.56.3 → 0.57.0

package/dist/builtins/fs/transferJobs.d.ts

@@ -0,0 +1,64 @@
+/** The session variable that says how many files move at once when a line does not. */
+export declare const TRANSFER_JOBS_VARIABLE: string;
+/**
+ * `-j N` / `--jobs N`: how many files move at once.
+ *
+ * @example
+ * ```ts
+ * const GRAMMAR = { options: { jobs: TRANSFER_JOBS_OPTION } } as const satisfies CommandGrammar;
+ * ```
+ */
+export declare const TRANSFER_JOBS_OPTION: {
+    readonly short: "j";
+    readonly long: "jobs";
+    readonly summary: `Move N files at once, 1 to ${number} (1 is one at a time); without it $TRANSFER_JOBS, else ${number}`;
+    readonly value: {
+        readonly name: "N";
+        readonly kind: "int";
+        readonly min: 1;
+        readonly max: number;
+    };
+};
+/**
+ * How many files a transfer moves at once, or why the session's variable
+ * cannot say.
+ *
+ * @example
+ * ```ts
+ * const jobs: TransferJobs = { jobs: 8 };
+ * ```
+ */
+export type TransferJobs = {
+    readonly jobs: number;
+} | {
+    readonly refused: string;
+};
+/**
+ * The number of files a transfer moves at once: the line's `-j`, else the
+ * session's `TRANSFER_JOBS`, else the pool's default.
+ *
+ * @param given - The line's `-j`, already checked by the parser; undefined when the line gives none.
+ * @returns The number, or a plain line refusing the variable's value.
+ *
+ * @example
+ * ```ts
+ * transferJobs_resolve(4);         // { jobs: 4 }
+ * transferJobs_resolve(undefined); // { jobs: 8 }, or $TRANSFER_JOBS
+ * ```
+ */
+export declare function transferJobs_resolve(given: number | undefined): TransferJobs;
+/**
+ * The lines under a transfer's summary that name each file that failed
+ * after its retry, and say how many a cancel left.
+ *
+ * @param failedPaths - The files that failed, as the transfer names them.
+ * @param cancelledCount - How many files a cancel left unmoved.
+ * @param verb - What the transfer does to a file (`downloaded`, `uploaded`).
+ * @returns The lines, each ending in a newline; empty when nothing failed or was left.
+ *
+ * @example
+ * ```ts
+ * transferLeftovers_render(['/home/me/uploads/a.dcm'], 0, 'downloaded'); // '  failed: /home/me/uploads/a.dcm\n'
+ * ```
+ */
+export declare function transferLeftovers_render(failedPaths: readonly string[], cancelledCount: number, verb: string): string;

package/dist/builtins/fs/transferJobs.js

@@ -0,0 +1,98 @@
+/**
+ * @file How many files a transfer moves at once: the `-j N` / `--jobs N`
+ * option `download`, `upload` and `berth anchor` share, and the session
+ * variable `TRANSFER_JOBS` that stands in when a line gives none.
+ *
+ * The option's bounds are the transfer pool's (cumin's
+ * `TRANSFER_JOBS_MAX`), so the parser refuses `-j 40` before anything moves,
+ * and the variable is checked by the same `int` kind, so the two refuse in
+ * the same words.
+ *
+ * Key components:
+ * - TRANSFER_JOBS_OPTION: the option, for a command's grammar.
+ * - TRANSFER_JOBS_VARIABLE: the session variable's name.
+ * - transferJobs_resolve: the line's number, else the variable's, else the default.
+ * - transferLeftovers_render: the lines naming what failed and what a cancel left.
+ *
+ * Typical usage:
+ * ```ts
+ * const jobs: TransferJobs = transferJobs_resolve(args.options.jobs);
+ * if ('refused' in jobs) return refusal(jobs.refused);
+ * ```
+ *
+ * Dependencies: cumin's transfer pool for the bounds; the session's variables.
+ *
+ * @module
+ */
+import chalk from 'chalk';
+import { TRANSFER_JOBS_DEFAULT, TRANSFER_JOBS_MAX } from '@fnndsc/cumin/transfer-pool';
+import { argumentWord_check } from '../../core/argumentKinds.js';
+import { TEXT_KIND, variable_get } from '../../core/variables.js';
+/** The session variable that says how many files move at once when a line does not. */
+export const TRANSFER_JOBS_VARIABLE = 'TRANSFER_JOBS';
+/**
+ * `-j N` / `--jobs N`: how many files move at once.
+ *
+ * @example
+ * ```ts
+ * const GRAMMAR = { options: { jobs: TRANSFER_JOBS_OPTION } } as const satisfies CommandGrammar;
+ * ```
+ */
+export const TRANSFER_JOBS_OPTION = {
+    short: 'j',
+    long: 'jobs',
+    summary: `Move N files at once, 1 to ${TRANSFER_JOBS_MAX} (1 is one at a time); without it $TRANSFER_JOBS, else ${TRANSFER_JOBS_DEFAULT}`,
+    value: { name: 'N', kind: 'int', min: 1, max: TRANSFER_JOBS_MAX },
+};
+/**
+ * The number of files a transfer moves at once: the line's `-j`, else the
+ * session's `TRANSFER_JOBS`, else the pool's default.
+ *
+ * @param given - The line's `-j`, already checked by the parser; undefined when the line gives none.
+ * @returns The number, or a plain line refusing the variable's value.
+ *
+ * @example
+ * ```ts
+ * transferJobs_resolve(4);         // { jobs: 4 }
+ * transferJobs_resolve(undefined); // { jobs: 8 }, or $TRANSFER_JOBS
+ * ```
+ */
+export function transferJobs_resolve(given) {
+    if (given !== undefined)
+        return { jobs: given };
+    const variable = variable_get(TRANSFER_JOBS_VARIABLE);
+    if (variable === undefined)
+        return { jobs: TRANSFER_JOBS_DEFAULT };
+    const range = `it says how many files move at once, a whole number from 1 to ${TRANSFER_JOBS_MAX}`;
+    if (variable.answer.kind !== TEXT_KIND || typeof variable.answer.data !== 'string') {
+        return { refused: `${TRANSFER_JOBS_VARIABLE} holds a ${variable.answer.kind}; ${range}` };
+    }
+    const text = variable.answer.data.trim();
+    const checked = argumentWord_check(TRANSFER_JOBS_OPTION.value, text);
+    if (!checked.ok)
+        return { refused: `${TRANSFER_JOBS_VARIABLE} is ${text === '' ? "''" : text}; ${range}` };
+    return { jobs: checked.value };
+}
+/**
+ * The lines under a transfer's summary that name each file that failed
+ * after its retry, and say how many a cancel left.
+ *
+ * @param failedPaths - The files that failed, as the transfer names them.
+ * @param cancelledCount - How many files a cancel left unmoved.
+ * @param verb - What the transfer does to a file (`downloaded`, `uploaded`).
+ * @returns The lines, each ending in a newline; empty when nothing failed or was left.
+ *
+ * @example
+ * ```ts
+ * transferLeftovers_render(['/home/me/uploads/a.dcm'], 0, 'downloaded'); // '  failed: /home/me/uploads/a.dcm\n'
+ * ```
+ */
+export function transferLeftovers_render(failedPaths, cancelledCount, verb) {
+    let rendered = '';
+    for (const failed of failedPaths)
+        rendered += `${chalk.red(`  failed: ${failed}`)}\n`;
+    if (cancelledCount > 0)
+        rendered += `${chalk.yellow(`  cancelled: ${cancelledCount} file(s) not ${verb}`)}\n`;
+    return rendered;
+}
+//# sourceMappingURL=transferJobs.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transferJobs.js","sourceRoot":"","sources":["../../../src/builtins/fs/transferJobs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAEvF,OAAO,EAAE,kBAAkB,EAAsB,MAAM,6BAA6B,CAAC;AAErF,OAAO,EAAE,SAAS,EAAE,YAAY,EAAiB,MAAM,yBAAyB,CAAC;AAEjF,uFAAuF;AACvF,MAAM,CAAC,MAAM,sBAAsB,GAAW,eAAe,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,KAAK,EAAE,GAAG;IACV,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,8BAA8B,iBAAiB,0DAA0D,qBAAqB,EAAE;IACzI,KAAK,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,iBAAiB,EAAE;CACjC,CAAC;AAanC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAyB;IAC5D,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAChD,MAAM,QAAQ,GAAyB,YAAY,CAAC,sBAAsB,CAAC,CAAC;IAC5E,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,qBAAqB,EAAE,CAAC;IACnE,MAAM,KAAK,GAAW,iEAAiE,iBAAiB,EAAE,CAAC;IAC3G,IAAI,QAAQ,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,QAAQ,CAAC,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACnF,OAAO,EAAE,OAAO,EAAE,GAAG,sBAAsB,YAAY,QAAQ,CAAC,MAAM,CAAC,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;IAC5F,CAAC;IACD,MAAM,IAAI,GAAW,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACjD,MAAM,OAAO,GAAkB,kBAAkB,CAAC,oBAAoB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACpF,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,EAAE,GAAG,sBAAsB,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;IAC3G,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,KAAe,EAAE,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,wBAAwB,CAAC,WAA8B,EAAE,cAAsB,EAAE,IAAY;IAC3G,IAAI,QAAQ,GAAW,EAAE,CAAC;IAC1B,KAAK,MAAM,MAAM,IAAI,WAAW;QAAE,QAAQ,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,aAAa,MAAM,EAAE,CAAC,IAAI,CAAC;IACtF,IAAI,cAAc,GAAG,CAAC;QAAE,QAAQ,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,gBAAgB,cAAc,gBAAgB,IAAI,EAAE,CAAC,IAAI,CAAC;IAC9G,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/builtins/fs/upload.d.ts

@@ -1,6 +1,6 @@
 import { type CommandEnvelope } from '@fnndsc/menu';
 /**
- * `upload <source> <destination>`: the declaration.
+ * `upload [-j N] <source> <destination>`: the declaration.
  *
  * @example
  * ```ts
@@ -17,6 +17,19 @@ export declare const uploadCommand: import("../../core/commandDeclaration.js").C
         readonly kind: "cfsPath";
         readonly summary: "The ChRIS folder it goes into";
     }];
+    readonly options: {
+        readonly jobs: {
+            readonly short: "j";
+            readonly long: "jobs";
+            readonly summary: `Move N files at once, 1 to ${number} (1 is one at a time); without it $TRANSFER_JOBS, else ${number}`;
+            readonly value: {
+                readonly name: "N";
+                readonly kind: "int";
+                readonly min: 1;
+                readonly max: number;
+            };
+        };
+    };
 }>;
 /**
  * `upload` over words already split: the declaration's parse and handler.

package/dist/builtins/fs/upload.js

@@ -34,6 +34,8 @@ import { declaredCommand_run } from '../../core/commandParse.js';
 import { errorStack } from '@fnndsc/fond';
 import { envelope_ok, envelope_error } from '@fnndsc/menu';
 import { exitCode_set } from '../../core/handlerRun.js';
+import { commandCancellation_enable, commandCancellation_signalGet } from '../../core/cancellation.js';
+import { TRANSFER_JOBS_OPTION, transferJobs_resolve, transferLeftovers_render } from './transferJobs.js';
 /** The characters that make a host path a pattern chili matches against the disk. */
 const HOST_WILDCARD = /[*?[]/;
 /**
@@ -56,9 +58,12 @@ const UPLOAD_GRAMMAR = {
         { name: 'source', kind: 'hostPath', summary: "What to upload from this machine's disk: a file, a folder, or a wildcard chili matches there" },
         { name: 'destination', kind: 'cfsPath', summary: 'The ChRIS folder it goes into' },
     ],
+    options: {
+        jobs: TRANSFER_JOBS_OPTION,
+    },
 };
 /**
- * `upload <source> <destination>`: the declaration.
+ * `upload [-j N] <source> <destination>`: the declaration.
  *
  * @example
  * ```ts
@@ -70,16 +75,17 @@ export const uploadCommand = command_declare({
     grammar: UPLOAD_GRAMMAR,
     help: {
         summary: 'Upload local files, directories, or glob matches to ChRIS',
-        description: 'Upload local files, directories, or glob matches to ChRIS with progress tracking. A progress bar shows the file count and percentage complete, the estimated time remaining (ETA) and the data transferred; summary statistics follow the upload.',
+        description: 'Upload local files, directories, or glob matches to ChRIS with progress tracking. A progress bar shows the file count and percentage complete, the estimated time remaining (ETA) and the data transferred; summary statistics follow the upload. The files of a folder move 8 at a time (-j N, or the session variable TRANSFER_JOBS, says how many, 1 to 32); a file that fails is tried once more, the rest continue, and the summary names each that failed.',
         category: 'Files',
         examples: [
             'upload ~/data/file.csv /home/user/uploads/',
             'upload ~/Pictures/earthandmoon* .',
             'upload ./results/ ~/data/',
             'upload ~/experiment/data /home/user/projects/',
+            'upload -j 1 ./results/ ~/data/  # one at a time',
         ],
     },
-    handler: async (args) => upload_run(args.operands.source, args.operands.destination),
+    handler: async (args) => upload_run(args.operands.source, args.operands.destination, args.options.jobs),
 });
 /**
  * `upload` over words already split: the declaration's parse and handler.
@@ -95,9 +101,10 @@ export async function builtin_upload(args) {
  *
  * @param localPath - The host path, as typed: a wildcard in it is matched on the engine's disk.
  * @param remotePath - The ChRIS destination, as typed.
+ * @param jobsGiven - The line's `-j`; undefined when it gives none.
  * @returns An envelope carrying the upload summary.
  */
-async function upload_run(localPath, remotePath) {
+async function upload_run(localPath, remotePath, jobsGiven) {
     // The local path is read by the ENGINE: under a daemon that is the daemon
     // host's disk, which belongs to nobody attending the session unless the
     // operator declared it theirs (--host-control=files). Without that, refuse
@@ -106,6 +113,13 @@ async function upload_run(localPath, remotePath) {
         exitCode_set(1);
         return envelope_error('', undefined, `${chalk.red("upload: calypso's host disk is nobody's; start calypso with --host-control=files, or upload from a surface that can supply the bytes.")}\n`);
     }
+    const jobs = transferJobs_resolve(jobsGiven);
+    if ('refused' in jobs) {
+        exitCode_set(1);
+        return envelope_error('', undefined, `${chalk.red(`upload: ${jobs.refused}`)}\n`);
+    }
+    commandCancellation_enable();
+    const signal = commandCancellation_signalGet();
     // chili reads an exact path first and matches a pattern only when nothing
     // stands at it.
     const localGlob = HOST_WILDCARD.test(localPath);
@@ -114,6 +128,8 @@ async function upload_run(localPath, remotePath) {
     try {
         const summary = await chefs_upload_cmd(localPath, targetRemote, {
             expandLocalGlob: localGlob,
+            jobs: jobs.jobs,
+            ...(signal !== undefined ? { signal } : {}),
             confirm: uploadConfirmation_request,
             onNotice: (message, channel) => {
                 const sink = sink_get();
@@ -132,6 +148,7 @@ async function upload_run(localPath, remotePath) {
             rendered += `${chalk.yellow(`⚠ Uploaded ${summary.transferredCount} file(s), ${summary.failedCount} failed`)}\n`;
         }
         rendered += `${chalk.gray(`  Total: ${bytes_format(summary.transferSize)} in ${summary.duration.toFixed(1)}s (${bytes_format(summary.speed)}/s)`)}\n`;
+        rendered += transferLeftovers_render(summary.failedPaths, summary.cancelledCount, 'uploaded');
         // A file that landed under another name because its own was taken must
         // say so: the store has no overwrite, and an upload reported as plain
         // success leaves the operator believing they replaced something.
@@ -152,7 +169,7 @@ async function upload_run(localPath, remotePath) {
             listCache.cache_invalidate(targetRemote);
             listCache.cache_invalidate(await path_resolve(remotePath));
         }
-        if (summary.failedCount > 0) {
+        if (summary.failedCount > 0 || summary.cancelledCount > 0) {
             exitCode_set(1);
             return envelope_error(rendered, undefined, '');
         }

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

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

package/dist/builtins/fs/url.d.ts

@@ -1,4 +1,5 @@
 import { CommandEnvelope } from '@fnndsc/menu';
+import { type CommandDeclaration } from '../../core/commandDeclaration.js';
 /** The environment variable naming the door (porter) a link opens through. */
 export declare const URL_DOOR_ENV: string;
 /**
@@ -9,11 +10,35 @@ export declare const URL_DOOR_ENV: string;
  * @returns The link, or the bare fragment when there is no door.
  */
 export declare function url_compose(door: string, absolutePath: string): string;
+/** What a `url` line may hold. */
+declare const URL_GRAMMAR: {
+    readonly operands: readonly [{
+        readonly name: "path";
+        readonly kind: "cfsPath";
+        readonly optional: true;
+        readonly summary: "Where the link opens: a feed or a node lands in RUNS, anything else in FILES (default: where you stand)";
+    }];
+};
 /**
- * Prints a web address that opens ARGUS at a path (the cwd when none).
+ * `url [path]`: the declaration, its door read from the process's environment.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [urlCommand] });
+ * ```
+ */
+export declare const urlCommand: CommandDeclaration<typeof URL_GRAMMAR>;
+/**
+ * `url` over words already split.
  *
  * @param args - The path, optionally.
  * @param env - The environment the door is read from.
- * @returns An envelope carrying the link and its `fs.url` model.
+ * @returns An envelope carrying the link and its `fs.url` model, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_url(['.']);
+ * ```
  */
 export declare function builtin_url(args?: string[], env?: NodeJS.ProcessEnv): Promise<CommandEnvelope>;
+export {};

package/dist/builtins/fs/url.js

@@ -8,13 +8,16 @@
  * in FILES. The path is the session's resolved absolute path, so the link
  * names the same place for anyone the feed is shared with.
  *
+ * Declared in one record (`urlCommand`).
+ *
  * @module
  */
 import chalk from 'chalk';
-import { envelope_error, envelope_ok } from '@fnndsc/menu';
+import { envelope_ok } from '@fnndsc/menu';
 import { session } from '../../session/index.js';
 import { path_resolve } from '../utils.js';
-import { exitCode_set } from '../../core/handlerRun.js';
+import { command_declare } from '../../core/commandDeclaration.js';
+import { declaredCommand_run } from '../../core/commandParse.js';
 /** The environment variable naming the door (porter) a link opens through. */
 export const URL_DOOR_ENV = 'CHELL_DOOR';
 /**
@@ -30,20 +33,19 @@ export function url_compose(door, absolutePath) {
         return fragment;
     return `${door.replace(/\/+$/, '')}/${fragment}`;
 }
+/** What a `url` line may hold. */
+const URL_GRAMMAR = {
+    operands: [{ name: 'path', kind: 'cfsPath', optional: true, summary: 'Where the link opens: a feed or a node lands in RUNS, anything else in FILES (default: where you stand)' }],
+};
 /**
  * Prints a web address that opens ARGUS at a path (the cwd when none).
  *
- * @param args - The path, optionally.
+ * @param path - The path, if given.
  * @param env - The environment the door is read from.
  * @returns An envelope carrying the link and its `fs.url` model.
  */
-export async function builtin_url(args = [], env = process.env) {
-    const words = args.filter((word) => !word.startsWith('--'));
-    if (words.length > 1) {
-        exitCode_set(1);
-        return envelope_error('', undefined, `${chalk.red('Usage: url [path]')}\n`);
-    }
-    const absolute = words.length === 0 ? await session.getCWD() : await path_resolve(words[0]);
+async function url_answer(path, env) {
+    const absolute = path === undefined ? await session.getCWD() : await path_resolve(path);
     const door = (env[URL_DOOR_ENV] ?? '').trim();
     const link = url_compose(door, absolute);
     const rendered = door === ''
@@ -51,4 +53,52 @@ export async function builtin_url(args = [], env = process.env) {
         : `${link}\n`;
     return envelope_ok(rendered, { kind: 'fs.url', data: { path: absolute, url: link } });
 }
+/**
+ * The `url` declaration over one environment, the one its door is read from.
+ *
+ * @param env - The environment.
+ * @returns The declaration.
+ */
+function urlCommand_make(env) {
+    return command_declare({
+        name: 'url',
+        grammar: URL_GRAMMAR,
+        help: {
+            summary: 'Print a link (a web address) that opens ARGUS at a path, to send to a colleague',
+            description: `Print a web address that opens ARGUS at a path: a feed or a node lands in RUNS, anything else in FILES. The path is the session's resolved absolute path, so the link names the same place for anyone the feed is shared with. The door comes from ${URL_DOOR_ENV}; without it the fragment alone is printed, with a word on what to put in front.`,
+            category: 'Sharing',
+            examples: [
+                'url                                   # Where you stand',
+                'url /home/sandip.samal/feeds/feed_4389/pl-dicom_repack_639204',
+                'url .                                 # Paste it to a colleague the feed is shared with',
+            ],
+        },
+        holds: [],
+        handler: async (args) => url_answer(args.operands.path, env),
+    });
+}
+/**
+ * `url [path]`: the declaration, its door read from the process's environment.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [urlCommand] });
+ * ```
+ */
+export const urlCommand = urlCommand_make(process.env);
+/**
+ * `url` over words already split.
+ *
+ * @param args - The path, optionally.
+ * @param env - The environment the door is read from.
+ * @returns An envelope carrying the link and its `fs.url` model, or the refusal of a bad line.
+ *
+ * @example
+ * ```ts
+ * await builtin_url(['.']);
+ * ```
+ */
+export async function builtin_url(args = [], env = process.env) {
+    return declaredCommand_run(env === process.env ? urlCommand : urlCommand_make(env), args);
+}
 //# sourceMappingURL=url.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"url.js","sourceRoot":"","sources":["../../../src/builtins/fs/url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAmB,cAAc,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC5E,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAExD,8EAA8E;AAC9E,MAAM,CAAC,MAAM,YAAY,GAAW,YAAY,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,YAAoB;IAC5D,MAAM,QAAQ,GAAW,IAAI,SAAS,CAAC,YAAY,CAAC,EAAE,CAAC;IACvD,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,QAAQ,CAAC;IACjC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,QAAQ,EAAE,CAAC;AACnD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAAiB,EAAE,EAAE,MAAyB,OAAO,CAAC,GAAG;IACzF,MAAM,KAAK,GAAa,IAAI,CAAC,MAAM,CAAC,CAAC,IAAY,EAAW,EAAE,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;IACvF,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,YAAY,CAAC,CAAC,CAAC,CAAC;QAChB,OAAO,cAAc,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAC9E,CAAC;IACD,MAAM,QAAQ,GAAW,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,YAAY,CAAC,KAAK,CAAC,CAAC,CAAW,CAAC,CAAC;IAC9G,MAAM,IAAI,GAAW,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACtD,MAAM,IAAI,GAAW,WAAW,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACjD,MAAM,QAAQ,GAAW,IAAI,KAAK,EAAE;QAClC,CAAC,CAAC,GAAG,IAAI,KAAK,KAAK,CAAC,GAAG,CAAC,qCAAqC,YAAY,mFAAmF,IAAI,EAAE,CAAC,IAAI;QACvK,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC;IAChB,OAAO,WAAW,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;AACxF,CAAC"}
+{"version":3,"file":"url.js","sourceRoot":"","sources":["../../../src/builtins/fs/url.ts"],"names":[],"mappings":"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"}

package/dist/builtins/help.d.ts

@@ -1,12 +1,6 @@
 import { type HelpLookup } from './helpSections.js';
-import { type CommandHelp } from '../core/commandRegistry.js';
+import { type CommandDeclaration } from '../core/commandDeclaration.js';
 import type { CommandEnvelope } from '@fnndsc/menu';
-/**
- * Help-text registry keyed by builtin command name, for the commands not yet
- * declared in one record: a declared command's help is generated from its
- * declaration, and its entry leaves this table.
- */
-export declare const helpText: Record<string, CommandHelp>;
 /**
  * Displays help text for a command.
  *
@@ -36,16 +30,18 @@ export declare function commandHelp_get(command: string): string | undefined;
  * Renders contextual help for one registered pipeline executable.
  *
  * @param name - Pipeline executable name as exposed in `/bin`.
+ * @param declaration - Its declaration, made from its manifest, when CUBE gave one: the usage and every node option come from it.
  * @returns Pipeline-specific help text, terminated with a newline.
  */
-export declare function pipelineExecutableHelp_render(name: string): string;
+export declare function pipelineExecutableHelp_render(name: string, declaration?: CommandDeclaration): string;
 /**
  * Renders contextual help for one versioned plugin executable.
  *
  * @param name - Plugin executable name as exposed in `/bin`.
+ * @param declaration - Its declaration, made from CUBE's parameters, when CUBE gave one: the usage and every parameter come from it.
  * @returns Plugin-specific help text, terminated with a newline.
  */
-export declare function pluginExecutableHelp_render(name: string): string;
+export declare function pluginExecutableHelp_render(name: string, declaration?: CommandDeclaration): string;
 /**
  * Renders a command's help text as a string.
  *
@@ -90,7 +86,7 @@ export declare function args_checkHasHelpFlag(args: string[], command?: string):
  * commands_register({ declarations: [helpCommand] });
  * ```
  */
-export declare const helpCommand: import("../core/commandDeclaration.js").CommandDeclaration<{
+export declare const helpCommand: CommandDeclaration<{
     readonly operands: readonly [{
         readonly name: "topic";
         readonly kind: "word";