@fnndsc/brasa 0.56.2 → 0.56.4

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

@@ -1,8 +1,40 @@
 import { type CommandEnvelope } from '@fnndsc/menu';
 /**
- * Uploads a local file or directory to ChRIS.
+ * `upload [-j N] <source> <destination>`: the declaration.
  *
- * @param args - [localPath, remotePath]
- * @returns An envelope carrying the upload summary.
+ * @example
+ * ```ts
+ * commands_register({ declarations: [uploadCommand] }, 'backend');
+ * ```
+ */
+export declare const uploadCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "source";
+        readonly kind: "hostPath";
+        readonly summary: "What to upload from this machine's disk: a file, a folder, or a wildcard chili matches there";
+    }, {
+        readonly name: "destination";
+        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.
+ *
+ * @param args - The words after `upload`.
+ * @returns The upload summary, or the refusal of a bad line.
  */
 export declare function builtin_upload(args: string[]): Promise<CommandEnvelope>;

package/dist/builtins/fs/upload.js

@@ -1,18 +1,43 @@
 /**
- * @file Builtin upload command.
- * Uploads files to ChRIS.
+ * @file `upload`: files, folders or the matches of a wildcard on this
+ * machine's disk, into ChRIS, with progress.
+ *
+ * The destination is where the store keeps it (`storePath_resolve`): an
+ * upload into a link lands in the folder the link points at.
+ *
+ * Declared in one record (`uploadCommand`): a host path operand, then one
+ * CFS path. The host path is never globbed by the line: chili matches a
+ * wildcard in it against the engine's disk.
+ *
+ * Key components:
+ * - uploadCommand: the declaration.
+ * - builtin_upload: the declaration run over words already split.
+ *
+ * Typical usage:
+ * ```ts
+ * await builtin_upload(['~/data/file.csv', '/home/user/uploads/']);
+ * ```
+ *
+ * Dependencies: chili's transfer, cumin's listing cache, the session's surface.
+ *
+ * @module
  */
 import chalk from 'chalk';
-import { path_resolve } from '../utils.js';
+import { path_resolve, storePath_resolve } from '../utils.js';
 import { files_uploadWithProgress as chefs_upload_cmd, bytes_format } from '@fnndsc/chili/commands/fs/upload.js';
 import { listCache_get } from '@fnndsc/cumin';
 import { sink_get } from '../../core/sink.js';
-import { shellArguments_pathnameExpansion } from '../../lib/parser.js';
 import { surface_get } from '../../core/surface.js';
 import { repl_confirm } from '../../core/question.js';
+import { command_declare } from '../../core/commandDeclaration.js';
+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 = /[*?[]/;
 /**
  * Asks the issuing surface to confirm replacement of an existing CFS target.
  *
@@ -27,18 +52,59 @@ async function uploadConfirmation_request(message) {
         throw new Error('Operation cancelled by user.');
     }
 }
+/** What an `upload` line may hold: one place on this machine, then one ChRIS path. */
+const UPLOAD_GRAMMAR = {
+    operands: [
+        { 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 [-j N] <source> <destination>`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [uploadCommand] }, 'backend');
+ * ```
+ */
+export const uploadCommand = command_declare({
+    name: 'upload',
+    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. 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, args.options.jobs),
+});
+/**
+ * `upload` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `upload`.
+ * @returns The upload summary, or the refusal of a bad line.
+ */
+export async function builtin_upload(args) {
+    return declaredCommand_run(uploadCommand, args);
+}
 /**
  * Uploads a local file or directory to ChRIS.
  *
- * @param args - [localPath, remotePath]
+ * @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.
  */
-export async function builtin_upload(args) {
-    if (args.length < 2) {
-        return envelope_ok(`${chalk.red('Usage: upload <local_path> <remote_path>')}\n`);
-    }
-    const localPath = args[0];
-    const remotePath = args[1];
+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
@@ -47,11 +113,23 @@ export async function builtin_upload(args) {
         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 localGlob = shellArguments_pathnameExpansion(args, 0);
-    const targetRemote = await path_resolve(remotePath);
+    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);
+    // Where the store keeps the destination: a link's target, not the link.
+    const targetRemote = await storePath_resolve(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();
@@ -70,6 +148,7 @@ export async function builtin_upload(args) {
             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.
@@ -85,8 +164,14 @@ export async function builtin_upload(args) {
         if (summary.transferredCount > 0) {
             const listCache = listCache_get();
             listCache.cache_invalidateTree(summary.actualTargetPath);
-            // Also invalidate parent to refresh its listing
+            // The destination's own listing, by both its names: where the store
+            // keeps it, and the path it was reached by.
             listCache.cache_invalidate(targetRemote);
+            listCache.cache_invalidate(await path_resolve(remotePath));
+        }
+        if (summary.failedCount > 0 || summary.cancelledCount > 0) {
+            exitCode_set(1);
+            return envelope_error(rendered, undefined, '');
         }
         return envelope_ok(rendered);
     }

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/xattr.args.d.ts

@@ -1,44 +1,18 @@
 /** The one attribute a feed carries. */
 export declare const XATTR_TAG: string;
-/** How `setfattr` is spelled. */
-export declare const SETFATTR_USAGE: string;
-/** How `getfattr` is spelled. */
-export declare const GETFATTR_USAGE: string;
-/** A parsed `setfattr` invocation. */
-export interface SetfattrArgs {
-    /** Set a value (`-n`), or remove (`-x`). */
-    mode: 'set' | 'remove';
-    /** The value to set or remove; null removes every value (`-x` alone). */
-    value: string | null;
-    paths: string[];
-    error: string | null;
-}
-/** A parsed `getfattr` invocation. */
-export interface GetfattrArgs {
-    paths: string[];
-    error: string | null;
-}
-/**
- * Reads a `setfattr` invocation. Unknown flags and attributes are refused by name.
- *
- * @param args - The tokens after the verb.
- * @returns The parsed invocation, its error set when it is wrong.
- */
-export declare function setfattrArgs_parse(args: ReadonlyArray<string>): SetfattrArgs;
-/**
- * Reads a `getfattr` invocation. `-n tag` is accepted (it is the only
- * attribute); `-d` (dump all) reads the same.
- *
- * @param args - The tokens after the verb.
- * @returns The parsed invocation, its error set when it is wrong.
- */
-export declare function getfattrArgs_parse(args: ReadonlyArray<string>): GetfattrArgs;
+/** The names that attribute answers to: `tag`, and `user.tag` as Linux namespaces it. */
+export declare const XATTR_NAMES: readonly ['tag', 'user.tag'];
 /**
  * The feed a path names: an id, a `feed_N`, a path through `/feeds/` as
  * setfacl reads it, or the projection `/proc/jobs/feed_N`.
  *
  * @param target - The path as typed.
  * @returns The feed id, or null.
+ *
+ * @example
+ * ```ts
+ * xattrTarget_resolve('/proc/jobs/feed_12'); // 12
+ * ```
  */
 export declare function xattrTarget_resolve(target: string): number | null;
 /**
@@ -48,5 +22,10 @@ export declare function xattrTarget_resolve(target: string): number | null;
  * @param path - The path as named.
  * @param tags - The tag names.
  * @returns The block.
+ *
+ * @example
+ * ```ts
+ * xattr_render('feed_12', ['urgent']); // '# file: feed_12\ntag="urgent"'
+ * ```
  */
 export declare function xattr_render(path: string, tags: ReadonlyArray<string>): string;

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

@@ -1,117 +1,34 @@
 /**
- * @file Shared `setfattr` / `getfattr` command-line grammar.
+ * @file The words of a feed's tags: the one attribute, the targets a feed
+ * is named by, and `getfattr`'s dump.
  *
  * A feed's tags are, in POSIX terms, an extended attribute: `setfattr -n
  * tag -v urgent feed_12` hangs one, `getfattr feed_12` reads them. One
  * attribute exists, `tag` (also spelled `user.tag`), and it holds many
  * values — CUBE's tags on the feed.
  *
- * Dependency-free, as `acl.args.ts` is: the engine graph cannot be loaded
- * under jest, so a grammar inside the builtin is a grammar nothing tests.
+ * The line itself is parsed against each command's declaration
+ * (`xattr.ts`). Dependency-free, as `acl.args.ts` is, so these are tested
+ * without the engine.
  *
  * @module
  */
 import { aclTarget_resolve } from './acl.args.js';
 /** The one attribute a feed carries. */
 export const XATTR_TAG = 'tag';
-/** How `setfattr` is spelled. */
-export const SETFATTR_USAGE = 'setfattr: usage: setfattr -n tag -v <value> <path>... | setfattr -x tag [-v <value>] <path>...';
-/** How `getfattr` is spelled. */
-export const GETFATTR_USAGE = 'getfattr: usage: getfattr [-n tag] <path>...';
-/**
- * Whether an attribute name is the one a feed carries.
- *
- * @param name - The name as typed.
- * @returns True for `tag` and `user.tag`.
- */
-function name_isTag(name) {
-    return name === XATTR_TAG || name === `user.${XATTR_TAG}`;
-}
-/**
- * Reads a `setfattr` invocation. Unknown flags and attributes are refused by name.
- *
- * @param args - The tokens after the verb.
- * @returns The parsed invocation, its error set when it is wrong.
- */
-export function setfattrArgs_parse(args) {
-    let mode = null;
-    let name = null;
-    let value = null;
-    const paths = [];
-    const fail = (error) => ({ mode: 'set', value: null, paths: [], error });
-    for (let i = 0; i < args.length; i += 1) {
-        const token = args[i] ?? '';
-        if (token === '-n' || token === '--name' || token === '-x' || token === '--remove') {
-            const given = args[i + 1];
-            if (given === undefined)
-                return fail(`setfattr: option '${token}' requires an argument\n${SETFATTR_USAGE}`);
-            mode = token === '-n' || token === '--name' ? 'set' : 'remove';
-            name = given;
-            i += 1;
-        }
-        else if (token === '-v' || token === '--value') {
-            const given = args[i + 1];
-            if (given === undefined)
-                return fail(`setfattr: option '${token}' requires an argument\n${SETFATTR_USAGE}`);
-            value = given;
-            i += 1;
-        }
-        else if (token.startsWith('-')) {
-            return fail(`setfattr: invalid option -- '${token.replace(/^-+/, '')}'\n${SETFATTR_USAGE}`);
-        }
-        else {
-            paths.push(token);
-        }
-    }
-    if (mode === null || name === null)
-        return fail(SETFATTR_USAGE);
-    if (!name_isTag(name))
-        return fail(`setfattr: ${name}: Operation not supported (a feed carries one attribute, tag)`);
-    if (mode === 'set' && (value === null || value.trim() === ''))
-        return fail(`setfattr: -n ${name} needs -v <value>\n${SETFATTR_USAGE}`);
-    if (paths.length === 0)
-        return fail(SETFATTR_USAGE);
-    return { mode, value: value === null ? null : value.trim(), paths, error: null };
-}
-/**
- * Reads a `getfattr` invocation. `-n tag` is accepted (it is the only
- * attribute); `-d` (dump all) reads the same.
- *
- * @param args - The tokens after the verb.
- * @returns The parsed invocation, its error set when it is wrong.
- */
-export function getfattrArgs_parse(args) {
-    const paths = [];
-    for (let i = 0; i < args.length; i += 1) {
-        const token = args[i] ?? '';
-        if (token === '-n' || token === '--name') {
-            const given = args[i + 1];
-            if (given === undefined)
-                return { paths: [], error: `getfattr: option '${token}' requires an argument\n${GETFATTR_USAGE}` };
-            if (!name_isTag(given))
-                return { paths: [], error: `getfattr: ${given}: No such attribute (a feed carries one attribute, tag)` };
-            i += 1;
-        }
-        else if (token === '-d' || token === '--dump') {
-            continue;
-        }
-        else if (token.startsWith('-')) {
-            return { paths: [], error: `getfattr: invalid option -- '${token.replace(/^-+/, '')}'\n${GETFATTR_USAGE}` };
-        }
-        else {
-            paths.push(token);
-        }
-    }
-    if (paths.length === 0)
-        return { paths: [], error: GETFATTR_USAGE };
-    return { paths, error: null };
-}
+/** The names that attribute answers to: `tag`, and `user.tag` as Linux namespaces it. */
+export const XATTR_NAMES = ['tag', 'user.tag'];
 /**
  * The feed a path names: an id, a `feed_N`, a path through `/feeds/` as
  * setfacl reads it, or the projection `/proc/jobs/feed_N`.
  *
  * @param target - The path as typed.
  * @returns The feed id, or null.
+ *
+ * @example
+ * ```ts
+ * xattrTarget_resolve('/proc/jobs/feed_12'); // 12
+ * ```
  */
 export function xattrTarget_resolve(target) {
     const held = aclTarget_resolve(target);
@@ -127,6 +44,11 @@ export function xattrTarget_resolve(target) {
  * @param path - The path as named.
  * @param tags - The tag names.
  * @returns The block.
+ *
+ * @example
+ * ```ts
+ * xattr_render('feed_12', ['urgent']); // '# file: feed_12\ntag="urgent"'
+ * ```
  */
 export function xattr_render(path, tags) {
     return [`# file: ${path}`, ...tags.map((tag) => `${XATTR_TAG}="${tag.replace(/"/g, '\\"')}"`)].join('\n');

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

@@ -1 +1 @@
-{"version":3,"file":"xattr.args.js","sourceRoot":"","sources":["../../../src/builtins/fs/xattr.args.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"xattr.args.js","sourceRoot":"","sources":["../../../src/builtins/fs/xattr.args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElD,wCAAwC;AACxC,MAAM,CAAC,MAAM,SAAS,GAAW,KAAK,CAAC;AAEvC,yFAAyF;AACzF,MAAM,CAAC,MAAM,WAAW,GAAiC,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;AAE7E;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,MAAM,IAAI,GAAkB,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACtD,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,SAAS,GAA4B,MAAM,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;IACtF,OAAO,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,IAA2B;IACpE,OAAO,CAAC,WAAW,IAAI,EAAE,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAW,EAAU,EAAE,CAAC,GAAG,SAAS,KAAK,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC5H,CAAC"}

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

@@ -1,17 +1,107 @@
 import { CommandEnvelope } from '@fnndsc/menu';
 /**
- * Reads the tags a feed wears, in `getfattr`'s dump shape.
+ * `getfattr [-d] [-n tag] <path>…`: the declaration.
  *
- * @param args - Raw argument tokens.
- * @returns An envelope carrying the rendered blocks and a model of them.
+ * @example
+ * ```ts
+ * commands_register({ declarations: [getfattrCommand] }, 'backend');
+ * ```
+ */
+export declare const getfattrCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "path";
+        readonly kind: "cfsPath";
+        readonly repeat: true;
+        readonly glob: true;
+        readonly summary: "The feeds: an id, feed_N, any path through /feeds/, or /proc/jobs/feed_N";
+    }];
+    readonly options: {
+        readonly name: {
+            readonly short: "n";
+            readonly long: "name";
+            readonly summary: "The attribute to read (only tag exists)";
+            readonly value: {
+                readonly name: "name";
+                readonly kind: "enum";
+                readonly values: readonly ["tag", "user.tag"];
+            };
+        };
+        readonly dump: {
+            readonly short: "d";
+            readonly long: "dump";
+            readonly summary: "Dump every attribute (the default)";
+        };
+    };
+}>;
+/**
+ * `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 declare function builtin_getfattr(args: string[]): Promise<CommandEnvelope>;
 /**
- * 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.
+ * `setfattr -n tag -v <value> <path>… | -x tag [-v <value>] <path>…`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [setfattrCommand] }, 'backend');
+ * ```
+ */
+export declare const setfattrCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "path";
+        readonly kind: "cfsPath";
+        readonly repeat: true;
+        readonly glob: true;
+        readonly summary: "The feeds: an id, feed_N, any path through /feeds/, or /proc/jobs/feed_N";
+    }];
+    readonly options: {
+        readonly name: {
+            readonly short: "n";
+            readonly long: "name";
+            readonly summary: "The attribute to set (only tag exists)";
+            readonly value: {
+                readonly name: "name";
+                readonly kind: "enum";
+                readonly values: readonly ["tag", "user.tag"];
+            };
+        };
+        readonly value: {
+            readonly short: "v";
+            readonly long: "value";
+            readonly summary: "The tag";
+            readonly value: {
+                readonly name: "value";
+                readonly kind: "word";
+            };
+        };
+        readonly remove: {
+            readonly short: "x";
+            readonly long: "remove";
+            readonly summary: "Remove the tag given by -v, or every tag without -v";
+            readonly value: {
+                readonly name: "name";
+                readonly kind: "enum";
+                readonly values: readonly ["tag", "user.tag"];
+            };
+        };
+    };
+}>;
+/**
+ * `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.
  *
- * @param args - Raw argument tokens.
- * @returns An envelope, empty on success.
+ * @example
+ * ```ts
+ * await builtin_setfattr(['-x', 'tag', 'feed_12']);
+ * ```
  */
 export declare function builtin_setfattr(args: string[]): Promise<CommandEnvelope>;