@fnndsc/brasa 0.56.2 → 0.56.4

package/dist/builtins/fs/touch.js

@@ -1,15 +1,37 @@
 /**
- * @file Builtin touch command.
- * Creates files, reported as a command envelope.
+ * @file `touch`: makes files in ChRIS's filesystem (CFS), empty or with text.
+ *
+ * Declared in one record (`touchCommand`): files, which glob, and the text
+ * to write, given inline (`--withContents`) or from a file on this machine
+ * (`--withContentsFromFile`). A path through a link is written where the
+ * link points.
+ *
+ * Key components:
+ * - touchCommand: the declaration.
+ * - builtin_touch: the declaration run over words already split.
+ * - touch_run: the typed core behind both, and the typed API.
+ *
+ * Typical usage:
+ * ```ts
+ * await builtin_touch(['--withContents', 'Hello!', 'greeting.txt']);
+ * await touch_run({ paths: ['greeting.txt'], contents: 'Hello!' });
+ * ```
+ *
+ * Dependencies: the session's filesystem and listing cache, the store-path
+ * resolver, and this machine's disk (for `--withContentsFromFile`).
+ *
+ * @module
  */
 import chalk from 'chalk';
 import fs from 'fs';
 import path from 'path';
-import { commandArgs_process, optionsUnknown_refusal, path_resolve } from '../utils.js';
+import { path_resolve, storePath_resolve } from '../utils.js';
 import { listingCache_get, vfsDispatcher_get } from '../../core/filesystem.js';
 import { pathEntry_find, entry_isFolder } from './entries.js';
 import { errno_words, touch_render, vfs_fail } 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';
 /**
  * Reads the local file whose text a touch writes.
  *
@@ -53,6 +75,64 @@ async function file_touch(dispatcher, targetPath, content) {
     const written = await dispatcher.write(targetPath, content ?? '');
     return written.ok || written.errno !== 'EISDIR' ? written : vfs_fail('EISDIR', `Is a directory: a folder already holds ${targetPath}`);
 }
+/**
+ * Forgets the listing of the folder that holds a touched file, by the
+ * session's path and by the store's.
+ *
+ * @param shown - The file as the session names it.
+ * @param targetPath - The file in the store.
+ */
+function parentListings_forget(shown, targetPath) {
+    for (const at of new Set([shown, targetPath]))
+        listingCache_get().cache_invalidate?.(path.posix.dirname(at));
+}
+/** What a `touch` line may hold. */
+const TOUCH_GRAMMAR = {
+    operands: [
+        { name: 'paths', kind: 'cfsPath', repeat: true, glob: true, summary: 'The files to make; with text, only the first takes it' },
+    ],
+    options: {
+        withContents: { long: 'withContents', summary: 'Create the file with this text inline', value: { name: 'string', kind: 'word' } },
+        withContentsFromFile: { long: 'withContentsFromFile', summary: 'Create the file with the text of a file on this machine', value: { name: 'file', kind: 'hostPath' } },
+    },
+};
+/**
+ * `touch [--withContents <string>] [--withContentsFromFile <file>] <file…>`: the declaration.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [touchCommand] });
+ * ```
+ */
+export const touchCommand = command_declare({
+    name: 'touch',
+    grammar: TOUCH_GRAMMAR,
+    help: {
+        summary: 'Create empty files or files with content',
+        description: "Makes each file in ChRIS's filesystem: a file already there is left as it is, a missing one is made empty. With --withContents or --withContentsFromFile the first file is written whole with that text. A path through a link is written where the link points. touch makes no folders (mkdir -p does).",
+        category: 'Files',
+        posix: { group: 'Files', differs: 'makes a CFS file; --withContents writes text into it' },
+        examples: [
+            'touch file.txt                                   # Create empty file',
+            'touch --withContents "Hello!" greeting.txt       # Create file with string',
+            'touch --withContentsFromFile template.json config.json  # Create from local file',
+        ],
+    },
+    handler: async (args) => touch_run({
+        paths: args.operands.paths,
+        contents: args.options.withContents,
+        contentsFromFile: args.options.withContentsFromFile,
+    }),
+});
+/**
+ * `touch` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `touch`.
+ * @returns The envelope from {@link touch_run}, or the refusal of a bad line.
+ */
+export async function builtin_touch(args) {
+    return declaredCommand_run(touchCommand, args);
+}
 /**
  * Creates empty files or updates timestamps: the shared typed core behind
  * the parsed builtin and the typed API.
@@ -77,24 +157,25 @@ export async function touch_run(runOptions) {
     }
     const wrote = content !== undefined;
     // Only the first path takes content.
-    const filesToTouch = wrote ? [pathArgs[0]] : pathArgs;
+    const filesToTouch = wrote ? pathArgs.slice(0, 1) : pathArgs;
     let rendered = '';
     let renderedErr = '';
     const outcomes = [];
     const dispatcher = vfsDispatcher_get();
     for (const pathArg of filesToTouch) {
         try {
-            const targetPath = await path_resolve(pathArg);
+            const shown = await path_resolve(pathArg);
+            const targetPath = await storePath_resolve(pathArg);
             const done = await file_touch(dispatcher, targetPath, content);
             if (done.ok) {
-                rendered += `${touch_render(targetPath, true, wrote)}\n`;
-                outcomes.push({ path: targetPath, created: true });
-                listingCache_get().cache_invalidate?.(path.posix.dirname(targetPath));
+                rendered += `${touch_render(shown, true, wrote)}\n`;
+                outcomes.push({ path: shown, created: true });
+                parentListings_forget(shown, targetPath);
             }
             else {
-                renderedErr += `${chalk.red(`Failed to create file: ${targetPath}`)}\n`;
+                renderedErr += `${chalk.red(`Failed to create file: ${shown}`)}\n`;
                 renderedErr += `${chalk.gray(`  ${done.reason ?? errno_words(done.errno)}`)}\n`;
-                outcomes.push({ path: targetPath, created: false });
+                outcomes.push({ path: shown, created: false });
             }
         }
         catch (e) {
@@ -112,21 +193,4 @@ export async function touch_run(runOptions) {
     }
     return envelope_ok(rendered, model);
 }
-/**
- * Creates files from parsed command-line arguments.
- *
- * @param args - Command line arguments (paths and --withContents flags).
- * @returns The envelope from {@link touch_run}.
- */
-export async function builtin_touch(args) {
-    const parsed = commandArgs_process(args);
-    const refusal = optionsUnknown_refusal('touch', parsed, ['withContents', 'withContentsFromFile']);
-    if (refusal !== null)
-        return envelope_error('', undefined, `${chalk.red(refusal)}\n`);
-    return touch_run({
-        paths: parsed._,
-        contents: parsed['withContents'] !== undefined ? String(parsed['withContents']) : undefined,
-        contentsFromFile: parsed['withContentsFromFile'] !== undefined ? String(parsed['withContentsFromFile']) : undefined,
-    });
-}
 //# sourceMappingURL=touch.js.map

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

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

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

@@ -1,16 +1,43 @@
 import { CommandEnvelope } from '@fnndsc/menu';
 /**
- * Displays a directory tree of the ChRIS filesystem.
- * Uses chili's scan_do machinery for recursive filesystem traversal.
- *
- * @param args - Command line arguments (optional path and flags).
- * @returns A Promise that resolves when the tree is displayed.
+ * `tree [--follow] [--path] [--dirs] [--dirpath] [path]`: the declaration.
  *
  * @example
+ * ```ts
+ * commands_register({ declarations: [treeCommand] }, 'backend');
  * ```
- * tree                    # Tree of current directory
- * tree /home/user/data    # Tree of specific path
- * tree --follow           # Follow symbolic links
- * ```
+ */
+export declare const treeCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly operands: readonly [{
+        readonly name: "path";
+        readonly kind: "cfsPath";
+        readonly optional: true;
+        readonly glob: true;
+        readonly summary: "The folder to draw; the working directory when none is given";
+    }];
+    readonly options: {
+        readonly follow: {
+            readonly long: "follow";
+            readonly summary: "Follow symbolic links when traversing";
+        };
+        readonly listPaths: {
+            readonly long: "path";
+            readonly summary: "Emit one full path per entry (grep-friendly, no tree art)";
+        };
+        readonly dirs: {
+            readonly long: "dirs";
+            readonly summary: "Show directories only";
+        };
+        readonly dirpath: {
+            readonly long: "dirpath";
+            readonly summary: "Emit one full directory path per line";
+        };
+    };
+}>;
+/**
+ * `tree` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `tree`.
+ * @returns The tree, or the refusal of a bad line.
  */
 export declare function builtin_tree(args: string[]): Promise<CommandEnvelope>;

package/dist/builtins/fs/tree.js

@@ -1,9 +1,27 @@
 /**
- * @file Builtin tree command.
- * Displays directory structure.
+ * @file `tree`: a folder of ChRIS's filesystem (CFS) drawn as a tree, or
+ * listed one path per line.
+ *
+ * Declared in one record (`treeCommand`): one path, and its switches.
+ *
+ * Key components:
+ * - treeCommand: the declaration.
+ * - builtin_tree: the declaration run over words already split.
+ *
+ * Typical usage:
+ * ```ts
+ * await builtin_tree(['--dirs', '~/feeds']);
+ * ```
+ *
+ * Dependencies: chili's scan for the walk; the listing for whether a path
+ * is there.
+ *
+ * @module
  */
 import chalk from 'chalk';
-import { commandArgs_process, optionsUnknown_refusal, path_resolve, error_stripDebugPrefix } from '../utils.js';
+import { path_resolve, storePath_resolve, error_stripDebugPrefix } from '../utils.js';
+import { command_declare } from '../../core/commandDeclaration.js';
+import { declaredCommand_run } from '../../core/commandParse.js';
 import { vfs } from '../../lib/vfs/vfs.js';
 import { session } from '../../session/index.js';
 import { spinner } from '../../lib/spinner.js';
@@ -12,55 +30,92 @@ import { bytes_format } from '@fnndsc/chili/commands/fs/upload.js';
 import { errorStack } from '@fnndsc/fond';
 import { envelope_ok, envelope_error } from '@fnndsc/menu';
 import { exitCode_set } from '../../core/handlerRun.js';
-/** The options tree reads; any other is refused by name. */
-const TREE_OPTIONS = ['follow', 'path', 'dirs', 'dirpath'];
 /**
- * Displays a directory tree of the ChRIS filesystem.
- * Uses chili's scan_do machinery for recursive filesystem traversal.
- *
- * @param args - Command line arguments (optional path and flags).
- * @returns A Promise that resolves when the tree is displayed.
+ * What a `tree` line may hold. An option it does not have is refused, not
+ * skipped: `tree -L 1 x` once scanned a folder named `1`, and
+ * `tree --bogus x` the whole home.
+ */
+const TREE_GRAMMAR = {
+    operands: [
+        { name: 'path', kind: 'cfsPath', optional: true, glob: true, summary: 'The folder to draw; the working directory when none is given' },
+    ],
+    options: {
+        follow: { long: 'follow', summary: 'Follow symbolic links when traversing' },
+        listPaths: { long: 'path', summary: 'Emit one full path per entry (grep-friendly, no tree art)' },
+        dirs: { long: 'dirs', summary: 'Show directories only' },
+        dirpath: { long: 'dirpath', summary: 'Emit one full directory path per line' },
+    },
+};
+/**
+ * `tree [--follow] [--path] [--dirs] [--dirpath] [path]`: the declaration.
  *
  * @example
- * ```
- * tree                    # Tree of current directory
- * tree /home/user/data    # Tree of specific path
- * tree --follow           # Follow symbolic links
+ * ```ts
+ * commands_register({ declarations: [treeCommand] }, 'backend');
  * ```
  */
+export const treeCommand = command_declare({
+    name: 'tree',
+    grammar: TREE_GRAMMAR,
+    help: {
+        summary: 'Display directory tree structure',
+        description: "Draws a folder of ChRIS's filesystem and everything under it as a tree, with the total size and the number of items; or, with --path or --dirpath, lists one full path per line. The working directory when no path is given.",
+        category: 'Navigation',
+        posix: { group: 'Files', differs: 'a CFS tree' },
+        examples: [
+            'tree                  # Tree of current directory',
+            'tree /home/user/data  # Tree of specific path',
+            'tree --follow         # Follow symbolic links',
+            'tree --path           # One path per line, no decoration',
+            'tree --dirs           # Directory hierarchy only',
+            'tree --dirpath        # One directory path per line',
+        ],
+    },
+    holds: [],
+    handler: tree_run,
+});
+/**
+ * `tree` over words already split: the declaration's parse and handler.
+ *
+ * @param args - The words after `tree`.
+ * @returns The tree, or the refusal of a bad line.
+ */
 export async function builtin_tree(args) {
-    const parsed = commandArgs_process(args, {
-        booleanLongOptions: TREE_OPTIONS,
-    });
-    // An option tree does not have is refused, not skipped: `tree -L 1 x`
-    // once scanned a folder named `1`, and `tree --bogus x` the whole home.
-    const unknown = optionsUnknown_refusal('tree', parsed, TREE_OPTIONS);
-    if (unknown !== null) {
-        exitCode_set(1);
-        return envelope_error('', undefined, `${chalk.red(unknown)}\n`);
-    }
-    const pathArgs = parsed._;
-    const dirpathMode = !!parsed['dirpath'];
-    const pathMode = !!parsed['path'] || dirpathMode;
-    const dirsOnly = !!parsed['dirs'] || dirpathMode;
-    // Determine target path
+    return declaredCommand_run(treeCommand, args);
+}
+/**
+ * Displays a directory tree of the ChRIS filesystem.
+ * Uses chili's scan_do machinery for recursive filesystem traversal.
+ *
+ * @param args - The line, parsed.
+ * @returns The tree and its summary, or why it could not be drawn.
+ */
+async function tree_run(args) {
+    const pathArg = args.operands.path;
+    const dirpathMode = args.options.dirpath;
+    const pathMode = args.options.listPaths || dirpathMode;
+    const dirsOnly = args.options.dirs || dirpathMode;
+    // Read where the store keeps it (a run's data path, a link on the line),
+    // and shown as it was asked: the tree's root is the path as typed.
     let targetPath;
-    if (pathArgs.length > 0) {
-        targetPath = await path_resolve(pathArgs[0]);
+    let logicalRoot;
+    if (pathArg !== undefined) {
+        logicalRoot = await path_resolve(pathArg);
+        targetPath = await storePath_resolve(pathArg);
         // A path that is not there is said to be not there, as tree says it,
         // rather than scanned into an empty tree.
         const entry = await vfs.data_get(targetPath, { directory: true });
         if (!entry.ok) {
             errorStack.stack_pop();
             exitCode_set(1);
-            return envelope_error('', undefined, `${chalk.red(`tree: ${pathArgs[0]}: No such file or directory`)}\n`);
+            return envelope_error('', undefined, `${chalk.red(`tree: ${pathArg}: No such file or directory`)}\n`);
         }
     }
     // Build scan options
     const scanOptions = {
         silent: true,
         tree: false, // We'll format it ourselves
-        follow: !!parsed['follow'],
+        follow: args.options.follow,
         dirsOnly,
         // A named folder is scanned where it stands: the shared directory stays put.
         ...(targetPath ? { folder: targetPath } : {}),
@@ -78,14 +133,18 @@ export async function builtin_tree(args) {
     spinner.stop();
     let rendered = '';
     if (pathMode) {
-        // --path: emit one full chrisPath per entry — grep-friendly
+        // --path: emit one full path per entry — grep-friendly, under the path asked
         for (const item of scanResult.fileInfo) {
-            rendered += `${item.chrisPath}\n`;
+            rendered += `${shownPath_derive(item.chrisPath, targetPath, logicalRoot)}\n`;
         }
     }
     else if (scanResult.fileInfo.length === 0) {
         // An empty folder is its own tree: its name, and nothing under it.
-        rendered += `${targetPath ?? originalFolder}\n`;
+        rendered += `${pathArg ?? originalFolder}\n`;
+    }
+    else if (targetPath !== undefined && pathArg !== undefined) {
+        // The tree hangs from the path as typed, its entries below it.
+        rendered += `${treeUnder_render(scanResult.fileInfo, targetPath, pathArg)}\n`;
     }
     else {
         // Default: ASCII tree
@@ -96,4 +155,35 @@ export async function builtin_tree(args) {
     rendered += `${chalk.gray(`${scanResult.fileInfo.length} items`)}\n`;
     return envelope_ok(rendered);
 }
+/**
+ * A scanned path as the person asked for it: under the logical root in
+ * place of the store folder it was read from.
+ *
+ * @param chrisPath - The path the scan gave (a store path).
+ * @param storeRoot - The store folder scanned, when one was named.
+ * @param logicalRoot - The same folder as the session names it.
+ * @returns The path to show.
+ */
+function shownPath_derive(chrisPath, storeRoot, logicalRoot) {
+    if (storeRoot === undefined || logicalRoot === undefined)
+        return chrisPath;
+    if (chrisPath === storeRoot)
+        return logicalRoot;
+    return chrisPath.startsWith(`${storeRoot}/`) ? `${logicalRoot}${chrisPath.slice(storeRoot.length)}` : chrisPath;
+}
+/**
+ * Draws a scanned folder's tree hanging from the path as typed: its entries
+ * relative to the store folder they were read from.
+ *
+ * @param files - What the scan found.
+ * @param storeRoot - The store folder scanned.
+ * @param shown - The root's label: the path as typed.
+ * @returns The tree.
+ */
+function treeUnder_render(files, storeRoot, shown) {
+    const under = files.map((file) => (file.chrisPath.startsWith(`${storeRoot}/`) ? { ...file, chrisPath: file.chrisPath.slice(storeRoot.length + 1) } : file));
+    // archy draws the root's own label first: an empty line, which the path takes.
+    const lines = archyTree_create(under).split('\n');
+    return [shown, ...lines.slice(1)].join('\n').replace(/\n+$/, '');
+}
 //# sourceMappingURL=tree.js.map

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

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