@fnndsc/brasa 0.1.0

package/dist/builtins/debug.d.ts

@@ -0,0 +1,8 @@
+import { CommandEnvelope } from '@fnndsc/cumin';
+/**
+ * Toggles or displays debug mode status.
+ *
+ * @param args - Command line arguments: 'on', 'off', or empty to display status.
+ * @returns An envelope describing the (possibly updated) debug state.
+ */
+export declare function builtin_debug(args: string[]): Promise<CommandEnvelope>;

package/dist/builtins/debug.js

@@ -0,0 +1,39 @@
+/**
+ * @file Debug Command
+ *
+ * Toggles debug mode for the application, reported as a command envelope.
+ */
+import chalk from 'chalk';
+import { envelope_ok, envelope_error } from '@fnndsc/cumin';
+import { session } from '../session/index.js';
+/**
+ * Toggles or displays debug mode status.
+ *
+ * @param args - Command line arguments: 'on', 'off', or empty to display status.
+ * @returns An envelope describing the (possibly updated) debug state.
+ */
+export async function builtin_debug(args) {
+    const subcommand = args[0];
+    const config = session.connection.config;
+    if (!config) {
+        return envelope_error('', [{ type: 'error', message: 'Error: Connection configuration not initialized.' }], `${chalk.red('Error: Connection configuration not initialized.')}\n`);
+    }
+    if (!subcommand) {
+        const enabled = config.debug;
+        const status = enabled ? 'enabled' : 'disabled';
+        const detail = enabled
+            ? chalk.gray('  Verbose error logging is enabled.')
+            : chalk.gray('  Verbose error logging is disabled.');
+        return envelope_ok(`Debug mode: ${chalk.yellow(status)}\n${detail}\n${chalk.gray('\nUsage: debug [on|off]')}\n`, { kind: 'sys.debug', data: { enabled } });
+    }
+    if (subcommand === 'on') {
+        config.debug = true;
+        return envelope_ok(`${chalk.yellow('[!] Debug mode enabled')}\n${chalk.gray('    Verbose error logging activated.')}\n`, { kind: 'sys.debug', data: { enabled: true } });
+    }
+    if (subcommand === 'off') {
+        config.debug = false;
+        return envelope_ok(`${chalk.green('[+] Debug mode disabled')}\n${chalk.gray('    Verbose error logging deactivated.')}\n`, { kind: 'sys.debug', data: { enabled: false } });
+    }
+    return envelope_error(`${chalk.red(`Unknown argument: ${subcommand}`)}\n${chalk.gray('Usage: debug [on|off]')}\n`);
+}
+//# sourceMappingURL=debug.js.map

package/dist/builtins/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../../src/builtins/debug.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAmB,WAAW,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE7E,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAc;IAChD,MAAM,UAAU,GAAuB,IAAI,CAAC,CAAC,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAiC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC;IAEvE,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,cAAc,CACnB,EAAE,EACF,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,kDAAkD,EAAE,CAAC,EAChF,GAAG,KAAK,CAAC,GAAG,CAAC,kDAAkD,CAAC,IAAI,CACrE,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,OAAO,GAAY,MAAM,CAAC,KAAK,CAAC;QACtC,MAAM,MAAM,GAAW,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC;QACxD,MAAM,MAAM,GAAW,OAAO;YAC5B,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,qCAAqC,CAAC;YACnD,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;QACvD,OAAO,WAAW,CAChB,eAAe,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,MAAM,KAAK,KAAK,CAAC,IAAI,CAAC,yBAAyB,CAAC,IAAI,EAC5F,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,EAAE,CACzC,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QACxB,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,OAAO,WAAW,CAChB,GAAG,KAAK,CAAC,MAAM,CAAC,wBAAwB,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,sCAAsC,CAAC,IAAI,EACpG,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,CAC/C,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,KAAK,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;QACrB,OAAO,WAAW,CAChB,GAAG,KAAK,CAAC,KAAK,CAAC,yBAAyB,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,wCAAwC,CAAC,IAAI,EACtG,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,CAChD,CAAC;IACJ,CAAC;IAED,OAAO,cAAc,CACnB,GAAG,KAAK,CAAC,GAAG,CAAC,qBAAqB,UAAU,EAAE,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAC5F,CAAC;AACJ,CAAC"}

package/dist/builtins/executable.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @file Builtin handler for executing a plugin as a shell command.
+ *
+ * @module
+ */
+type PluginExecutableOptions = {
+    piped?: boolean;
+};
+/**
+ * Handles simulated execution of plugins (e.g., "pl-simpledsapp-v1.2.3 --parameters").
+ *
+ * This acts as an interceptor for the main shell loop. If the user input matches a
+ * known plugin name format, it routes the request to the appropriate ChRIS/ChILI logic,
+ * simulating a native executable experience.
+ *
+ * @param command - The command string (potentially a plugin name).
+ * @param args - The arguments passed to the command.
+ * @param options - Optional flags for piped/non-interactive handling.
+ * @returns A Promise resolving to true if the command was handled as a plugin execution, false otherwise.
+ */
+export declare function pluginExecutable_handle(command: string, args: string[], options?: PluginExecutableOptions): Promise<boolean>;
+export {};

package/dist/builtins/executable.js

@@ -0,0 +1,115 @@
+/**
+ * @file Builtin handler for executing a plugin as a shell command.
+ *
+ * @module
+ */
+import chalk from 'chalk';
+import { spinner } from '../lib/spinner.js';
+import { builtin_parametersofplugin } from './parametersofplugin.js';
+import { plugins_list, plugins_listAll } from '@fnndsc/salsa';
+import { pluginReadme_fetch, pluginReadme_render } from '@fnndsc/chili/commands/plugin/readme.js';
+/**
+ * Handles simulated execution of plugins (e.g., "pl-simpledsapp-v1.2.3 --parameters").
+ *
+ * This acts as an interceptor for the main shell loop. If the user input matches a
+ * known plugin name format, it routes the request to the appropriate ChRIS/ChILI logic,
+ * simulating a native executable experience.
+ *
+ * @param command - The command string (potentially a plugin name).
+ * @param args - The arguments passed to the command.
+ * @param options - Optional flags for piped/non-interactive handling.
+ * @returns A Promise resolving to true if the command was handled as a plugin execution, false otherwise.
+ */
+export async function pluginExecutable_handle(command, args, options) {
+    // Expected format: name-vVersion (e.g., "pl-simpledsapp-v2.1.3")
+    const versionSeparatorIndex = command.lastIndexOf('-v');
+    if (versionSeparatorIndex === -1) {
+        return false;
+    }
+    const name = command.substring(0, versionSeparatorIndex);
+    const version = command.substring(versionSeparatorIndex + 2);
+    if (!name || !version) {
+        return false;
+    }
+    const showHelp = args.includes('--help') || args.includes('-h');
+    const isPipedOutput = !!options?.piped || !process.stdout.isTTY;
+    if (showHelp) {
+        console.log(chalk.cyan(`Plugin executable flags for ${name}-v${version}:`));
+        console.log('  --parameters   Show parameter definitions for this plugin version');
+        console.log('  --readme       Show README (rendered) from plugin metadata repository URL');
+        console.log('  --readme --raw Output raw markdown, suitable for piping to glow or bat');
+        return true;
+    }
+    const plugin_resolveExact = async () => {
+        try {
+            const resultsExactUnknown = await plugins_list({
+                search: {
+                    name_exact: name,
+                    version: version
+                }
+            });
+            const resultsExact = resultsExactUnknown;
+            let candidate = resultsExact?.tableData?.[0];
+            if (!candidate || candidate.name !== name || candidate.version !== version) {
+                const allVersionsUnknown = await plugins_listAll({
+                    search: { name: name }
+                });
+                const allVersions = allVersionsUnknown;
+                candidate = allVersions?.tableData?.find((p) => p.name === name && p.version === version);
+            }
+            if (!candidate ||
+                typeof candidate.id !== 'number' ||
+                typeof candidate.name !== 'string' ||
+                typeof candidate.version !== 'string') {
+                return null;
+            }
+            return { id: candidate.id, name: candidate.name, version: candidate.version };
+        }
+        catch (error) {
+            console.error(chalk.red(`Error resolving plugin: ${error instanceof Error ? error.message : String(error)}`));
+            return null;
+        }
+    };
+    if (args.includes('--readme')) {
+        const rawMode = args.includes('--raw');
+        console.log(chalk.cyan(`Resolving plugin ${name} v${version} for README...`));
+        const resolved = await plugin_resolveExact();
+        if (!resolved) {
+            console.log(chalk.red(`Plugin ${name} v${version} not found.`));
+            return true;
+        }
+        spinner.start(`Fetching README for ${resolved.name} v${resolved.version}...`);
+        try {
+            const content = await pluginReadme_fetch(String(resolved.id));
+            spinner.stop();
+            if (content) {
+                console.log(rawMode ? content : pluginReadme_render(content));
+            }
+            else {
+                console.log(chalk.yellow(`No README found for ${resolved.name} v${resolved.version}.`));
+            }
+        }
+        catch (error) {
+            spinner.stop();
+            const message = error instanceof Error ? error.message : String(error);
+            console.log(chalk.red(`Failed to fetch README: ${message}`));
+        }
+        return true;
+    }
+    if (args.includes('--parameters')) {
+        console.log(chalk.cyan(`Fetching parameters for plugin ${name} v${version}...`));
+        const resolved = await plugin_resolveExact();
+        if (!resolved) {
+            console.log(chalk.red(`Plugin ${name} v${version} not found.`));
+            return true; // Handled (attempted), but failed
+        }
+        console.log(chalk.cyan(`Resolved Plugin: ${resolved.name} v${resolved.version} (ID: ${resolved.id})`));
+        // Delegate to parametersofplugin builtin with the resolved context
+        await builtin_parametersofplugin(['list', '--plugin-id', String(resolved.id)]);
+        return true;
+    }
+    // If command matches plugin format but no handled flags are present,
+    // return false to let the main loop handle it (or show unknown command).
+    return false;
+}
+//# sourceMappingURL=executable.js.map

package/dist/builtins/executable.js.map

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

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

@@ -0,0 +1,16 @@
+import type { CommandEnvelope } from '@fnndsc/cumin';
+/**
+ * Displays the content of one or more files.
+ *
+ * Supports multiple files and concatenates their output. Binary mode is applied
+ * consistently to all files if any file is detected as binary or --binary is specified.
+ * Text content and errors are buffered into the envelope; binary content streams
+ * to the terminal directly with backpressure (raw bytes are not envelope text),
+ * and the binary auto-detection notice is emitted live on the err channel so it
+ * precedes the bytes it describes.
+ *
+ * @param args - Command line arguments (file paths and optional --binary flag).
+ * @returns An envelope whose rendered text carries the (highlighted) file
+ *   contents and whose model lists per-file outcomes.
+ */
+export declare function builtin_cat(args: string[]): Promise<CommandEnvelope>;

package/dist/builtins/fs/cat.js

@@ -0,0 +1,266 @@
+/**
+ * @file Builtin cat command.
+ * Displays file contents, reported as a command envelope.
+ */
+import chalk from 'chalk';
+import { path_resolve, error_stripDebugPrefix } from '../utils.js';
+import { files_cat as chefs_cat_cmd, files_catBinary as chefs_catBinary_cmd } from '@fnndsc/chili/commands/fs/cat.js';
+import { cat_render } from '@fnndsc/chili/views/fs.js';
+import { errorStack, envelope_ok, envelope_error } from '@fnndsc/cumin';
+import { sink_get } from '../../core/sink.js';
+import * as path from 'path';
+/** File extensions that receive syntax highlighting. */
+const HIGHLIGHT_EXTENSIONS = new Set(['.json', '.yaml', '.yml']);
+/**
+ * Applies chalk-based syntax highlighting to JSON content.
+ * Returns the original string if the content is not valid JSON.
+ *
+ * @param content - Raw JSON string.
+ * @returns Highlighted string, or original on parse failure.
+ */
+function json_highlight(content) {
+    try {
+        JSON.parse(content);
+    }
+    catch {
+        return content;
+    }
+    return content.replace(/("(?:\\u[0-9a-fA-F]{4}|\\[^u]|[^\\"])*"(\s*:)?|true|false|null|-?\d+(?:\.\d*)?(?:[eE][+-]?\d+)?)/g, (match) => {
+        if (match.endsWith(':'))
+            return chalk.cyan(match); // key
+        if (match.startsWith('"'))
+            return chalk.green(match); // string value
+        if (match === 'true' || match === 'false')
+            return chalk.yellow(match);
+        if (match === 'null')
+            return chalk.gray(match);
+        return chalk.magenta(match); // number
+    });
+}
+/**
+ * Applies chalk-based syntax highlighting to YAML content line by line.
+ *
+ * @param content - Raw YAML string.
+ * @returns Highlighted string.
+ */
+function yaml_highlight(content) {
+    return content.split('\n').map((line) => {
+        if (/^\s*#/.test(line))
+            return chalk.gray(line);
+        const kv = line.match(/^(\s*)([\w./-]+)(\s*:\s*)(.*)/);
+        if (kv) {
+            const [, indent, key, sep, value] = kv;
+            const coloredValue = value_yamlColor(value);
+            return `${indent}${chalk.cyan(key)}${chalk.gray(sep)}${coloredValue}`;
+        }
+        const listItem = line.match(/^(\s*-\s+)(.*)/);
+        if (listItem) {
+            return `${chalk.gray(listItem[1])}${chalk.green(listItem[2])}`;
+        }
+        return line;
+    }).join('\n');
+}
+/**
+ * Colors a scalar YAML value based on its type.
+ *
+ * @param value - The raw value string from a YAML key: value line.
+ * @returns Chalk-colored value string.
+ */
+function value_yamlColor(value) {
+    if (!value)
+        return value;
+    if (value === 'true' || value === 'false')
+        return chalk.yellow(value);
+    if (value === 'null' || value === '~')
+        return chalk.gray(value);
+    if (/^-?\d+(\.\d+)?$/.test(value))
+        return chalk.magenta(value);
+    if (/^["']/.test(value))
+        return chalk.green(value);
+    return chalk.white(value);
+}
+/**
+ * Applies syntax highlighting to text content based on file extension.
+ * Returns the original string unchanged when stdout is not a TTY (piping).
+ *
+ * @param content - File content string.
+ * @param filePath - Full path used to determine the file type.
+ * @returns Highlighted or original content.
+ */
+function content_highlight(content, filePath) {
+    if (!process.stdout.isTTY)
+        return content;
+    const ext = path.extname(filePath).toLowerCase();
+    if (ext === '.json')
+        return json_highlight(content);
+    if (ext === '.yaml' || ext === '.yml')
+        return yaml_highlight(content);
+    return content;
+}
+/**
+ * List of file extensions that are considered binary.
+ */
+const BINARY_EXTENSIONS = new Set([
+    '.dcm', // DICOM medical images
+    '.png', '.jpg', '.jpeg', '.gif', '.bmp', '.ico', '.webp', // Images
+    '.pdf', // Documents
+    '.zip', '.tar', '.gz', '.bz2', '.xz', '.7z', '.rar', // Archives
+    '.exe', '.dll', '.so', '.dylib', '.bin', // Executables/Libraries
+    '.mp3', '.mp4', '.avi', '.mov', '.wav', '.flac', // Media
+]);
+/**
+ * Checks if a file path has a binary extension.
+ *
+ * @param filePath - The file path to check.
+ * @returns True if the file has a binary extension.
+ */
+function extension_isBinary(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return BINARY_EXTENSIONS.has(ext);
+}
+/**
+ * Writes a buffer to stdout with proper backpressure handling.
+ *
+ * Splits large buffers into 64KB chunks and waits for drain events when the
+ * output buffer is full. This prevents data loss when piping large binary files
+ * to external commands. Waits for all data to be flushed before resolving.
+ *
+ * @param buffer - The buffer to write to stdout.
+ * @returns A Promise that resolves when all data has been written and flushed.
+ *
+ * @example
+ * ```typescript
+ * const dicomData: Buffer = await fetchDicomFile();
+ * await buffer_writeToStdout(dicomData);
+ * ```
+ */
+async function buffer_writeToStdout(buffer) {
+    return new Promise((resolve, reject) => {
+        if (buffer.length === 0) {
+            resolve();
+            return;
+        }
+        let offset = 0;
+        const chunkSize = 64 * 1024; // 64KB chunks
+        /**
+         * Recursively writes the next chunk of data to stdout.
+         * Handles backpressure by waiting for drain events when buffer is full.
+         */
+        const chunk_writeNext = () => {
+            try {
+                while (offset < buffer.length) {
+                    const end = Math.min(offset + chunkSize, buffer.length);
+                    const chunk = buffer.subarray(offset, end);
+                    offset = end;
+                    const canContinue = process.stdout.write(chunk);
+                    if (!canContinue) {
+                        // Buffer is full, wait for drain event
+                        process.stdout.once('drain', chunk_writeNext);
+                        return;
+                    }
+                }
+                // All chunks written - ensure stdout is flushed before resolving
+                // Writing an empty string forces a flush check. If write() returns false,
+                // the buffer is full and we must wait for drain. This prevents truncation
+                // when piping to external processes, as Node.js won't exit until we resolve.
+                if (process.stdout.write('')) {
+                    // Buffer has space, all data is flushed
+                    resolve();
+                }
+                else {
+                    // Buffer is full, wait for final drain before resolving
+                    process.stdout.once('drain', () => resolve());
+                }
+            }
+            catch (err) {
+                reject(err);
+            }
+        };
+        chunk_writeNext();
+    });
+}
+/**
+ * Displays the content of one or more files.
+ *
+ * Supports multiple files and concatenates their output. Binary mode is applied
+ * consistently to all files if any file is detected as binary or --binary is specified.
+ * Text content and errors are buffered into the envelope; binary content streams
+ * to the terminal directly with backpressure (raw bytes are not envelope text),
+ * and the binary auto-detection notice is emitted live on the err channel so it
+ * precedes the bytes it describes.
+ *
+ * @param args - Command line arguments (file paths and optional --binary flag).
+ * @returns An envelope whose rendered text carries the (highlighted) file
+ *   contents and whose model lists per-file outcomes.
+ */
+export async function builtin_cat(args) {
+    let binaryMode = false;
+    const filePaths = [];
+    for (const arg of args) {
+        if (arg === '--binary') {
+            binaryMode = true;
+        }
+        else {
+            filePaths.push(arg);
+        }
+    }
+    if (filePaths.length === 0) {
+        return envelope_error('', undefined, `${chalk.red('Usage: cat [--binary] <file> [file...]')}\n`);
+    }
+    let rendered = '';
+    let renderedErr = '';
+    const outcomes = [];
+    let anyFailed = false;
+    for (let i = 0; i < filePaths.length; i++) {
+        const pathArg = filePaths[i];
+        const target = await path_resolve(pathArg);
+        // Auto-detect binary files
+        const isBinaryFile = extension_isBinary(target);
+        // Inform user about auto-detection only if in interactive mode (stdout is TTY).
+        // Emitted live (not buffered) so the notice precedes the raw bytes it announces.
+        // Only show on first file to avoid spam.
+        if (i === 0 && isBinaryFile && !binaryMode && process.stdout.isTTY) {
+            sink_get().err_write(`${chalk.cyan(`Info: ${pathArg} detected as binary file (${path.extname(target)}), using binary mode.`)}\n`);
+            sink_get().err_write(`${chalk.cyan('Tip: Use "cat --binary <file>" to explicitly request binary mode.')}\n`);
+            sink_get().err_write('\n');
+        }
+        // Use binary mode if requested OR if file is detected as binary
+        if (binaryMode || isBinaryFile) {
+            const result = await chefs_catBinary_cmd(target);
+            if (!result.ok) {
+                const error = errorStack.stack_pop();
+                renderedErr += `${chalk.red(`cat: ${pathArg}: ${error ? error_stripDebugPrefix(error.message) : 'Unknown error'}`)}\n`;
+                outcomes.push({ path: pathArg, ok: false, binary: true });
+                anyFailed = true;
+                process.exitCode = 1;
+                continue;
+            }
+            // Output raw buffer to stdout with backpressure handling
+            await buffer_writeToStdout(result.value);
+            outcomes.push({ path: pathArg, ok: true, binary: true, bytes: result.value.length });
+        }
+        else {
+            const result = await chefs_cat_cmd(target);
+            if (!result.ok) {
+                const error = errorStack.stack_pop();
+                renderedErr += `${chalk.red(`cat: ${pathArg}: ${error ? error_stripDebugPrefix(error.message) : 'Unknown error'}`)}\n`;
+                outcomes.push({ path: pathArg, ok: false, binary: false });
+                anyFailed = true;
+                process.exitCode = 1;
+                continue;
+            }
+            const highlighted = content_highlight(result.value, target);
+            rendered += `${cat_render(highlighted, pathArg)}\n`;
+            outcomes.push({ path: pathArg, ok: true, binary: false });
+        }
+    }
+    const model = { kind: 'fs.cat', data: outcomes };
+    if (anyFailed) {
+        const envelope = envelope_error(rendered, undefined, renderedErr || undefined);
+        envelope.model = model;
+        return envelope;
+    }
+    const envelope = envelope_ok(rendered, model);
+    return envelope;
+}
+//# sourceMappingURL=cat.js.map

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

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

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

@@ -0,0 +1,42 @@
+import type { CommandEnvelope } from '@fnndsc/cumin';
+/**
+ * Interface representing a FileBrowserFolder from ChRIS API.
+ */
+interface FileBrowserFolder {
+    path?: string;
+    data?: {
+        path?: string;
+    };
+}
+/**
+ * Normalizes a logical path for VFS comparison by stripping a single trailing
+ * slash (except for the root path).
+ *
+ * @param logicalPath - The resolved logical path.
+ * @returns The normalized path.
+ */
+export declare function vfsPath_normalize(logicalPath: string): string;
+/**
+ * Reports whether a path is a structural VFS container (always valid).
+ *
+ * @param cleanPath - The normalized path.
+ * @returns True if the path is a known structural VFS container.
+ */
+export declare function vfsPath_isStructural(cleanPath: string): boolean;
+/**
+ * Verifies if a given FileBrowserFolder object exactly matches the validation path.
+ *
+ * @param folder - The FileBrowserFolder object to verify.
+ * @param validationPath - The path to match against.
+ * @returns True if the folder path exactly matches validationPath, false otherwise.
+ */
+export declare function folder_verifyPathMatch(folder: FileBrowserFolder | null | undefined, validationPath: string): boolean;
+/**
+ * Changes the current working directory in the ChRIS filesystem context.
+ * Validates the existence of the target path before setting it.
+ *
+ * @param args - An array containing the target path as the first element.
+ * @returns An envelope carrying the new working directory on success.
+ */
+export declare function builtin_cd(args: string[]): Promise<CommandEnvelope>;
+export {};