@fnndsc/brasa 0.56.1 → 0.56.3

package/dist/builtins/fs/configWrite.js

@@ -6,47 +6,98 @@
  * argus desktops, prompt choices — as files under `~/.config/...` on CFS.
  * Surfaces hold no upload credentials of their own, so the write travels
  * the session: content arrives base64-encoded, lands in a host temp file,
- * and rides the same upload path the edit-in-place flow already uses.
+ * and rides the same upload path the edit-in-place flow already uses. The
+ * document is written where the store keeps its path (`storePath_resolve`).
+ *
+ * Declared in one record (`configCommand`): one subcommand, `write`, with a
+ * CFS path and the content as a word.
+ *
+ * Key components:
+ * - configCommand: the declaration.
+ * - builtin_config: the declaration run over words already split.
+ *
+ * Typical usage:
+ * ```ts
+ * await builtin_config(['write', '~/.config/argus/desktops/quad.desk', 'dmlldyBmaWxlcwo=']);
+ * ```
+ *
+ * Dependencies: salsa's upload and chili's replace-in-place; the session's
+ * listing cache.
  *
  * @module
  */
 import { writeFileSync, unlinkSync, existsSync } from 'fs';
 import { tmpdir } from 'os';
-import { join } from 'path';
+import { join, posix } from 'path';
 import chalk from 'chalk';
 import { files_uploadPath } from '@fnndsc/salsa';
 import { file_replaceContent } from '@fnndsc/chili/commands/fs/edit.js';
-import { path_resolve } from '../utils.js';
+import { path_resolve, storePath_resolve } from '../utils.js';
+import { command_declare } from '../../core/commandDeclaration.js';
+import { declaredCommand_run } from '../../core/commandParse.js';
+import { listingCache_get } from '../../core/filesystem.js';
 import { envelope_error, envelope_ok } from '@fnndsc/menu';
 import { exitCode_set } from '../../core/handlerRun.js';
 /** A config document is a note, not a dataset. */
 const CONFIG_WRITE_LIMIT = 256 * 1024;
+/** What a `config` line may hold: `write`, a CFS path, and the document as base64. */
+const CONFIG_GRAMMAR = {
+    subcommands: {
+        write: {
+            summary: 'Write a configuration document',
+            operands: [
+                { name: 'path', kind: 'cfsPath', summary: 'Where the document goes in ChRIS' },
+                { name: 'content', kind: 'word', summary: 'The document, base64-encoded' },
+            ],
+        },
+    },
+};
+/**
+ * `config write <path> <content>`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [configCommand] }, 'backend');
+ * ```
+ */
+export const configCommand = command_declare({
+    name: 'config',
+    grammar: CONFIG_GRAMMAR,
+    help: {
+        summary: "Write a small configuration document into the user's CUBE home",
+        description: 'Write a small configuration document into the user\'s CUBE home (the durable layer: argus desktops, surface preferences). Reads travel the ordinary cat. Documents are notes, not datasets: 256KB limit.',
+        category: 'Files',
+        examples: [
+            'config write ~/.config/argus/desktops/quad.desk dmlldyBmaWxlcwo=   # a saved argus desktop',
+            'cat ~/.config/argus/desktops/quad.desk                             # reading one back',
+        ],
+    },
+    handler: async (args) => configWrite_run(args),
+});
+/**
+ * `config` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `config`.
+ * @returns The subcommand's envelope, or the refusal of a bad line.
+ */
+export async function builtin_config(args) {
+    return declaredCommand_run(configCommand, args);
+}
 /**
- * Handles `config write <path> <base64>`.
+ * Runs `config write <path> <base64>`.
  *
- * @param args - Full command args (`config`, `write`, path, base64).
+ * @param args - The line, parsed.
  * @returns An envelope reporting the written path.
  */
-export async function configWrite_handle(args) {
-    const rawPath = args[2];
-    const encoded = args[3];
-    if (rawPath === undefined || encoded === undefined) {
-        exitCode_set(1);
-        return envelope_error('', undefined, 'usage: config write <cfs-path> <base64-content>\n');
-    }
-    let content;
-    try {
-        content = Buffer.from(encoded, 'base64');
-    }
-    catch {
-        exitCode_set(1);
-        return envelope_error('', undefined, 'config write: the content is not valid base64.\n');
-    }
+async function configWrite_run(args) {
+    const rawPath = args.operands.path;
+    const content = Buffer.from(args.operands.content, 'base64');
     if (content.length > CONFIG_WRITE_LIMIT) {
         exitCode_set(1);
         return envelope_error('', undefined, 'config write: a config document is a note, not a dataset (256KB limit).\n');
     }
-    const remotePath = rawPath.startsWith('/') ? rawPath : await path_resolve(rawPath);
+    const shown = await path_resolve(rawPath);
+    const remotePath = await storePath_resolve(rawPath);
     const tmpPath = join(tmpdir(), `chell-config-${Date.now()}.tmp`);
     try {
         writeFileSync(tmpPath, content);
@@ -59,26 +110,16 @@ export async function configWrite_handle(args) {
         }
         if (!uploaded) {
             exitCode_set(1);
-            return envelope_error('', undefined, `config write: upload to ${remotePath} failed.\n`);
+            return envelope_error('', undefined, `config write: upload to ${shown} failed.\n`);
         }
-        return envelope_ok(`${chalk.green('[+]')} wrote ${remotePath} (${content.length} bytes)\n`);
+        // The folder's listing is stale by both its names.
+        listingCache_get().cache_invalidate?.(posix.dirname(remotePath));
+        listingCache_get().cache_invalidate?.(posix.dirname(shown));
+        return envelope_ok(`${chalk.green('[+]')} wrote ${shown} (${content.length} bytes)\n`);
     }
     finally {
         if (existsSync(tmpPath))
             unlinkSync(tmpPath);
     }
 }
-/**
- * Routes the `config` command family. `write` is its only member today;
- * reads travel the ordinary `cat`.
- *
- * @param args - Full command args.
- * @returns The subcommand's envelope.
- */
-export async function builtin_config(args) {
-    if (args[1] === 'write')
-        return configWrite_handle(args);
-    exitCode_set(1);
-    return envelope_error('', undefined, 'usage: config write <cfs-path> <base64-content>\n');
-}
 //# sourceMappingURL=configWrite.js.map

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

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

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

@@ -12,12 +12,47 @@ export interface CpModelData {
     failed: number;
 }
 /**
- * Copies a file or directory.
- * Supports multiple sources when destination is a directory.
+ * `cp [-rt] [--target-directory <dir>] <paths…>`: the declaration.
  *
- * @param args - [flags, src1, src2, ..., dest]
+ * @example
+ * ```ts
+ * commands_register({ declarations: [cpCommand] });
+ * ```
+ */
+export declare const cpCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "paths";
+        readonly kind: "cfsPath";
+        readonly repeat: true;
+        readonly glob: true;
+        readonly summary: "The sources, then the destination; a lone source asks where it goes";
+    }];
+    readonly options: {
+        readonly recursive: {
+            readonly short: "r";
+            readonly long: "recursive";
+            readonly summary: "Recursive copy (for directories)";
+        };
+        readonly askTarget: {
+            readonly short: "t";
+            readonly summary: "Every operand is a source; asks for the target directory, and the answer must be one";
+        };
+        readonly targetDirectory: {
+            readonly long: "target-directory";
+            readonly summary: "Every operand is a source; copy into this directory";
+            readonly value: {
+                readonly name: "dir";
+                readonly kind: "cfsPath";
+            };
+        };
+    };
+}>;
+/**
+ * `cp` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `cp`.
  * @returns An envelope whose rendered text reports progress and results and
- *   whose model carries per-source outcomes.
+ *   whose model carries per-source outcomes, or the refusal of a bad line.
  */
 export declare function builtin_cp(args: string[]): Promise<CommandEnvelope>;
 /** Typed invocation options for cp. */

package/dist/builtins/fs/cp.js

@@ -1,59 +1,77 @@
 /**
- * @file Builtin cp command.
- * Copies files or directories, reported as a command envelope.
+ * @file `cp`: copies files and folders within ChRIS's filesystem (CFS),
+ * reported as a command envelope.
+ *
+ * Declared in one record (`cpCommand`): the sources, then the destination,
+ * each a path that may be a wildcard; a lone source, or `-t`, asks where.
+ * Each path is acted on where the store keeps it (`storePath_resolve`): a
+ * source through a link is what the link points at, and a destination
+ * through a link lands in the link's target. What cp says names the paths
+ * as the session resolves them.
+ *
+ * Key components:
+ * - cpCommand: the declaration.
+ * - builtin_cp: the declaration run over words already split.
+ * - cp_run: the typed core behind both, and the typed API.
+ *
+ * Typical usage:
+ * ```ts
+ * await builtin_cp(['-r', 'data', 'backup/']);
+ * await cp_run({ sources: ['a.txt'], dest: 'b.txt' });
+ * ```
+ *
+ * Dependencies: the session's filesystem and listing cache, and the
+ * destination question.
+ *
+ * @module
  */
 import chalk from 'chalk';
 import path from 'path';
-import { commandArgs_process, optionsUnknown_refusal, path_resolve } from '../utils.js';
+import { path_resolve, storePath_resolve } from '../utils.js';
+import { command_declare } from '../../core/commandDeclaration.js';
+import { declaredCommand_run } from '../../core/commandParse.js';
 import { listingCache_get, vfsDispatcher_get } from '../../core/filesystem.js';
 import { destination_ask, destination_missing, operands_fix } from './destination.js';
 import { cp_render, vfsRefusal_text } from '@fnndsc/fond';
 import { pathEntry_find, entry_isFolder } from './entries.js';
 import { envelope_ok, envelope_error } from '@fnndsc/menu';
 import { exitCode_set } from '../../core/handlerRun.js';
+/** What a `cp` line may hold. */
+const CP_GRAMMAR = {
+    operands: [
+        { name: 'paths', kind: 'cfsPath', repeat: true, glob: true, summary: 'The sources, then the destination; a lone source asks where it goes' },
+    ],
+    options: {
+        recursive: { short: 'r', long: 'recursive', summary: 'Recursive copy (for directories)' },
+        askTarget: { short: 't', summary: 'Every operand is a source; asks for the target directory, and the answer must be one' },
+        targetDirectory: { long: 'target-directory', summary: 'Every operand is a source; copy into this directory', value: { name: 'dir', kind: 'cfsPath' } },
+    },
+};
 /**
- * Copies a file or directory.
- * Supports multiple sources when destination is a directory.
+ * Runs a parsed `cp` line: into a target directory given or asked for, to a
+ * destination asked for a lone source, or to the last operand.
  *
- * @param args - [flags, src1, src2, ..., dest]
- * @returns An envelope whose rendered text reports progress and results and
- *   whose model carries per-source outcomes.
+ * @param args - The typed line.
+ * @returns The copy's envelope, or the refusal of an abandoned question.
  */
-export async function builtin_cp(args) {
-    const parsed = commandArgs_process(args, { booleanLongOptions: ['recursive'] });
-    const refusal = optionsUnknown_refusal('cp', parsed, ['t', 'r', 'recursive']);
-    if (refusal !== null)
-        return envelope_error('', undefined, `${chalk.red(refusal)}\n`);
-    const pathArgs = parsed._;
-    // `-t <dir>` names the TARGET DIRECTORY, so every operand is a source —
-    // the shell's own answer to "several things, one destination". Given no
-    // value it is a question (an-absent-value-is-a-question), and the answer
-    // wants a directory: `cp a b` without it means rename a ONTO b, which
-    // is the right reading of that line and the wrong thing for a set.
-    const target = parsed.t;
-    if (target !== undefined && pathArgs.length > 0) {
-        if (typeof target === 'string' && target !== '') {
-            return cp_run({ sources: pathArgs, dest: target });
-        }
-        // The sources are fixed before the question: other commands run while it is open.
-        const sources = await operands_fix(pathArgs);
-        const chosen = await destination_ask({
-            verb: 'cp', commit: 'COPY HERE', sources, wantsDirectory: true,
-        });
-        if (chosen === '') {
-            exitCode_set(1);
-            return envelope_error('', undefined, `${chalk.red(destination_missing('cp'))}\n`);
-        }
-        return cp_run({ sources, dest: chosen });
-    }
-    const recursive = !!parsed['r'] || !!parsed['recursive'];
-    // One operand names what to copy and not where: a question, not a usage
-    // error. See `destination_ask`.
-    if (pathArgs.length === 1) {
+async function cp_handle(args) {
+    const paths = args.operands.paths;
+    const recursive = args.options.recursive;
+    // `--target-directory <dir>` names the TARGET DIRECTORY, so every operand
+    // is a source: the shell's own answer to "several things, one destination".
+    const target = args.options.targetDirectory;
+    if (target !== undefined)
+        return cp_run({ sources: paths, dest: target, recursive });
+    // `-t` alone is that line with the directory not said: a question
+    // (an-absent-value-is-a-question), and the answer wants a directory:
+    // `cp a b` without it means copy a ONTO b, the right reading of that line
+    // and the wrong thing for a set. One operand names what to copy and not
+    // where: a question too, not a usage error. See `destination_ask`.
+    if (args.options.askTarget || paths.length === 1) {
         // The sources are fixed before the question: other commands run while it is open.
-        const sources = await operands_fix(pathArgs);
+        const sources = await operands_fix(paths);
         const chosen = await destination_ask({
-            verb: 'cp', commit: 'COPY HERE', sources,
+            verb: 'cp', commit: 'COPY HERE', sources, ...(args.options.askTarget ? { wantsDirectory: true } : {}),
         });
         if (chosen === '') {
             exitCode_set(1);
@@ -61,12 +79,61 @@ export async function builtin_cp(args) {
         }
         return cp_run({ sources, dest: chosen, recursive });
     }
-    // Last arg is destination, all others are sources
-    return cp_run({
-        sources: pathArgs.slice(0, -1),
-        dest: pathArgs.length > 0 ? pathArgs[pathArgs.length - 1] : '',
-        recursive,
-    });
+    // The last operand is the destination, all others are sources.
+    return cp_run({ sources: paths.slice(0, -1), dest: paths[paths.length - 1] ?? '', recursive });
+}
+/**
+ * `cp [-rt] [--target-directory <dir>] <paths…>`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [cpCommand] });
+ * ```
+ */
+export const cpCommand = command_declare({
+    name: 'cp',
+    grammar: CP_GRAMMAR,
+    help: {
+        summary: 'Copy files or directories (supports wildcards and multiple sources)',
+        description: "Copies files or folders within ChRIS's filesystem: the last operand is the destination, and several sources want a folder there. Given only a source, the destination is asked for. A path through a link is the link's target: a copy into a linked folder lands in the folder it points at. PACS sources: a /net/pacs/queries/... source names query results, not stored files, and cp materializes the series: if its DICOMs are not yet in CUBE it fires a PACS retrieve and waits for them to land (the same engine as pull), then copies the landed files to the destination. A series already fully in CUBE is copied without a retrieve.",
+        category: 'Files',
+        posix: { group: 'Files', differs: 'copies within CFS; -r for folders' },
+        examples: [
+            'cp file.txt copy.txt              # Copy single file',
+            'cp -r dir1/ dir2/                 # Copy directory recursively',
+            'cp file1 file2 file3 dest/        # Copy multiple files',
+            'cp uploads/*.txt backup/          # Copy with wildcard',
+            'cp --target-directory backup/ a b # Copy several into one folder',
+            'cp -t a.txt b.txt                 # Ask which folder they go to',
+            'cp "file with spaces.txt" dest/   # Use quotes for spaces',
+            'cp -r /net/pacs/queries/AccessionNumber:123_qid:7/Study_1.2.3_Head/Series_1.2.3.4_AX_T2 results/',
+            '                                  # Retrieve-if-needed, then copy the series',
+        ],
+    },
+    handler: cp_handle,
+});
+/**
+ * `cp` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `cp`.
+ * @returns An envelope whose rendered text reports progress and results and
+ *   whose model carries per-source outcomes, or the refusal of a bad line.
+ */
+export async function builtin_cp(args) {
+    return declaredCommand_run(cpCommand, args);
+}
+/**
+ * Forgets the cached listings a write to a destination changes: beneath it
+ * (a recursive copy replaces them) and of its parent, by each name it has.
+ *
+ * @param listCache - The session's listing cache.
+ * @param names - The destination as the session names it and as the store keeps it.
+ */
+function destination_invalidate(listCache, names) {
+    for (const name of new Set(names)) {
+        listCache.cache_invalidateTree?.(name);
+        listCache.cache_invalidate?.(path.posix.dirname(name));
+    }
 }
 /**
  * Copies files or directories: the shared typed core behind the parsed
@@ -84,6 +151,8 @@ export async function cp_run(options) {
     }
     const recursive = options.recursive ?? false;
     const destPath = await path_resolve(dest);
+    // Written where the store keeps it: into a linked folder lands in the link's target.
+    const destStore = await storePath_resolve(destPath);
     const listCache = listingCache_get();
     let successCount = 0;
     let failCount = 0;
@@ -102,10 +171,11 @@ export async function cp_run(options) {
             }
             // Into a folder the destination names, the copy keeps its name.
             const dispatcher = vfsDispatcher_get();
-            const finalDest = entry_isFolder(await pathEntry_find(dispatcher, destPath)) && !dispatcher.path_isVirtual(destPath)
-                ? path.posix.join(destPath, path.posix.basename(srcPath))
-                : destPath;
-            const copied = await dispatcher.cp(srcPath, finalDest, { recursive });
+            const finalDest = entry_isFolder(await pathEntry_find(dispatcher, destStore)) && !dispatcher.path_isVirtual(destStore)
+                ? path.posix.join(destStore, path.posix.basename(srcPath))
+                : destStore;
+            // Copied from where the store keeps it (a /proc data path, a link); named as it was asked.
+            const copied = await dispatcher.cp(await storePath_resolve(srcPath), finalDest, { recursive });
             const success = copied.ok;
             if (sources.length === 1) {
                 rendered += `${cp_render(srcPath, destPath, success)}\n`;
@@ -131,11 +201,7 @@ export async function cp_run(options) {
             failCount++;
         }
     }
-    // Invalidate the destination subtree (a recursive copy replaces whatever
-    // listings were cached beneath it) and its parent.
-    listCache.cache_invalidateTree?.(destPath);
-    const destParent = path.posix.dirname(destPath);
-    listCache.cache_invalidate?.(destParent);
+    destination_invalidate(listCache, [destPath, destStore]);
     // Summary for multiple files
     if (sources.length > 1) {
         if (failCount === 0) {

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

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

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

@@ -1,9 +1,36 @@
 import { type CommandEnvelope } from '@fnndsc/menu';
 /**
- * Downloads a remote ChRIS file or directory to the local filesystem, or hands
- * it to the surface when the engine's disk is not the operator's.
+ * `download [-f] <source…> <destination>`: the declaration.
  *
- * @param args - [remotePathOrGlob, localPath] plus optional -f/--force to overwrite.
- * @returns An envelope carrying the download summary.
+ * @example
+ * ```ts
+ * commands_register({ declarations: [downloadCommand] }, 'backend');
+ * ```
+ */
+export declare const downloadCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "source";
+        readonly kind: "cfsPath";
+        readonly repeat: true;
+        readonly glob: true;
+        readonly summary: "What to download: a ChRIS file or folder; a wildcard matches paths";
+    }, {
+        readonly name: "destination";
+        readonly kind: "hostPath";
+        readonly summary: "Where it goes on this machine's disk; several sources go into one folder";
+    }];
+    readonly options: {
+        readonly force: {
+            readonly short: "f";
+            readonly long: "force";
+            readonly summary: "Overwrite local paths that exist";
+        };
+    };
+}>;
+/**
+ * `download` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `download`.
+ * @returns The download summary, or the refusal of a bad line.
  */
 export declare function builtin_download(args: string[]): Promise<CommandEnvelope>;