@fnndsc/chell 4.2.8

package/dist/lib/pipe.js

@@ -0,0 +1,90 @@
+/**
+ * @file Process piping helper for shell command chains.
+ *
+ * Spawns a single shell segment, feeds it an input buffer (with backpressure
+ * handling), and resolves with its captured stdout.
+ *
+ * @module
+ */
+import { spawn } from 'child_process';
+/**
+ * Pipes an input buffer through a spawned shell command and captures its stdout.
+ *
+ * Writes the input to the child's stdin with drain-aware backpressure handling,
+ * tolerates early-close EPIPE, and rejects on non-zero exit or spawn error.
+ *
+ * @param segment - The shell command to run (executed with `shell: true`).
+ * @param input - The data to write to the command's stdin.
+ * @returns The command's captured stdout.
+ */
+export function segment_pipeThrough(segment, input) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        // When using shell: true, pass the entire command as a single string
+        const child = spawn(segment, {
+            stdio: ['pipe', 'pipe', 'inherit'],
+            shell: true,
+        });
+        child.stdout.on('data', (chunk) => {
+            chunks.push(chunk);
+        });
+        child.on('close', (code) => {
+            if (code !== 0 && code !== null) {
+                reject(new Error(`Command '${segment}' exited with code ${code}`));
+            }
+            else {
+                resolve(Buffer.concat(chunks));
+            }
+        });
+        child.on('error', (err) => {
+            reject(err);
+        });
+        // Handle EPIPE errors when child closes stdin early
+        child.stdin.on('error', (err) => {
+            if (err.code === 'EPIPE') {
+                // Child closed stdin, this is normal if it exits early — handled by 'close'.
+            }
+            else {
+                reject(err);
+            }
+        });
+        /**
+         * Writes all buffered data to child stdin with backpressure handling.
+         * Splits large buffers into chunks and waits for drain events when needed.
+         */
+        const data_writeAll = async () => {
+            if (input.length === 0) {
+                child.stdin.end();
+                return;
+            }
+            return new Promise((resolveWrite, rejectWrite) => {
+                let offset = 0;
+                const chunkSize = 64 * 1024; // 64KB chunks
+                const chunk_writeNext = () => {
+                    try {
+                        while (offset < input.length) {
+                            const end = Math.min(offset + chunkSize, input.length);
+                            const chunk = input.subarray(offset, end);
+                            offset = end;
+                            const canContinue = child.stdin.write(chunk);
+                            if (!canContinue) {
+                                child.stdin.once('drain', chunk_writeNext);
+                                return;
+                            }
+                        }
+                        child.stdin.end();
+                        resolveWrite();
+                    }
+                    catch (err) {
+                        rejectWrite(err);
+                    }
+                };
+                chunk_writeNext();
+            });
+        };
+        // Start writing in parallel with reading output; ignore write errors if the
+        // child already closed (EPIPE is handled by the stdin error handler).
+        data_writeAll().catch(() => { });
+    });
+}
+//# sourceMappingURL=pipe.js.map

package/dist/lib/pipe.js.map

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

package/dist/lib/prefetch.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Outcome of a prefetch operation (counts and status).
+ */
+export interface PrefetchResult {
+    ok: boolean;
+    count?: number;
+    pipelineCount?: number;
+    message?: string;
+}
+/**
+ * Prefetch a VFS path into the list cache.
+ *
+ * @param target - Absolute VFS path to prefetch.
+ * @returns Count of items cached on success, error message on failure.
+ */
+export declare function prefetch_path(target: string): Promise<PrefetchResult>;
+/**
+ * Run a prefetch action behind a spinner (interactive) or plain log (non-interactive).
+ *
+ * @param label        - Short label shown in the spinner column (padded to 12 chars).
+ * @param message      - Descriptive message shown next to the label.
+ * @param isInteractive - Whether the session is interactive (controls spinner vs plain log).
+ * @param action       - Async work to run; returns a PrefetchResult.
+ */
+export declare function prefetch_withSpinner(label: string, message: string, isInteractive: boolean, action: () => Promise<PrefetchResult>): Promise<PrefetchResult>;

package/dist/lib/prefetch.js

@@ -0,0 +1,64 @@
+/**
+ * @file Boot-time prefetch helpers for warming the VFS cache.
+ *
+ * Extracted from chell_start() to keep that fn focused on orchestration.
+ * All functions are pure top-level — no closure over session state.
+ *
+ * @module
+ */
+import { errorStack } from '@fnndsc/cumin';
+import { vfs } from './vfs/vfs.js';
+import { spinner } from './spinner.js';
+import { error_stripDebugPrefix } from '../builtins/index.js';
+/**
+ * Prefetch a VFS path into the list cache.
+ *
+ * @param target - Absolute VFS path to prefetch.
+ * @returns Count of items cached on success, error message on failure.
+ */
+export async function prefetch_path(target) {
+    try {
+        const result = await vfs.data_get(target);
+        if (result.ok) {
+            return { ok: true, count: result.value.length };
+        }
+        const err = errorStack.stack_pop();
+        return { ok: false, message: err ? error_stripDebugPrefix(err.message) : `Prefetch failed for ${target}` };
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return { ok: false, message: msg };
+    }
+}
+/**
+ * Run a prefetch action behind a spinner (interactive) or plain log (non-interactive).
+ *
+ * @param label        - Short label shown in the spinner column (padded to 12 chars).
+ * @param message      - Descriptive message shown next to the label.
+ * @param isInteractive - Whether the session is interactive (controls spinner vs plain log).
+ * @param action       - Async work to run; returns a PrefetchResult.
+ */
+export async function prefetch_withSpinner(label, message, isInteractive, action) {
+    const paddedLabel = label.padEnd(12);
+    // Spinner adds its own glyph and a following space. Pad so the label column
+    // aligns with the fixed-width status logs (e.g., "[ OK ] " = 7 chars).
+    const spinnerPrefix = ' '.repeat(5); // 1 glyph + 1 space + 5 = 7
+    const spinnerMessage = `${spinnerPrefix}${paddedLabel} ${message}`;
+    const showSpinner = isInteractive && process.stdout.isTTY;
+    if (showSpinner) {
+        spinner.start(spinnerMessage, true);
+    }
+    else {
+        console.log(spinnerMessage);
+    }
+    try {
+        return await action();
+    }
+    finally {
+        if (showSpinner) {
+            spinner.stop();
+            process.stdout.write('\r\x1b[K');
+        }
+    }
+}
+//# sourceMappingURL=prefetch.js.map

package/dist/lib/prefetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefetch.js","sourceRoot":"","sources":["../../src/lib/prefetch.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAY9D;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAc;IAChD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACd,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QAClD,CAAC;QACD,MAAM,GAAG,GAAG,UAAU,CAAC,SAAS,EAAE,CAAC;QACnC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,sBAAsB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,uBAAuB,MAAM,EAAE,EAAE,CAAC;IAC7G,CAAC;IAAC,OAAO,CAAU,EAAE,CAAC;QACpB,MAAM,GAAG,GAAW,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAC/D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;IACrC,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,KAAa,EACb,OAAe,EACf,aAAsB,EACtB,MAAqC;IAErC,MAAM,WAAW,GAAW,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC7C,4EAA4E;IAC5E,uEAAuE;IACvE,MAAM,aAAa,GAAW,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,4BAA4B;IACzE,MAAM,cAAc,GAAW,GAAG,aAAa,GAAG,WAAW,IAAI,OAAO,EAAE,CAAC;IAC3E,MAAM,WAAW,GAAY,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;IAEnE,IAAI,WAAW,EAAE,CAAC;QAChB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI,CAAC;QACH,OAAO,MAAM,MAAM,EAAE,CAAC;IACxB,CAAC;YAAS,CAAC;QACT,IAAI,WAAW,EAAE,CAAC;YAChB,OAAO,CAAC,IAAI,EAAE,CAAC;YACf,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/lib/semicolonParser.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @file Semicolon command parser
+ *
+ * Parses semicolon-separated commands while respecting quotes.
+ *
+ * @module
+ */
+/**
+ * Parses a command line for semicolon separators and returns individual commands.
+ * Respects quoted strings - semicolons inside quotes are not treated as separators.
+ *
+ * @param line - The full command line.
+ * @returns An array of individual commands.
+ *
+ * @example
+ * ```typescript
+ * semicolons_parse("ls; pwd")                    // Returns: ["ls", "pwd"]
+ * semicolons_parse("echo 'a;b'; pwd")            // Returns: ["echo 'a;b'", "pwd"]
+ * semicolons_parse("cd /tmp; ls; cat file.txt")  // Returns: ["cd /tmp", "ls", "cat file.txt"]
+ * ```
+ */
+export declare function semicolons_parse(line: string): string[];

package/dist/lib/semicolonParser.js

@@ -0,0 +1,53 @@
+/**
+ * @file Semicolon command parser
+ *
+ * Parses semicolon-separated commands while respecting quotes.
+ *
+ * @module
+ */
+/**
+ * Parses a command line for semicolon separators and returns individual commands.
+ * Respects quoted strings - semicolons inside quotes are not treated as separators.
+ *
+ * @param line - The full command line.
+ * @returns An array of individual commands.
+ *
+ * @example
+ * ```typescript
+ * semicolons_parse("ls; pwd")                    // Returns: ["ls", "pwd"]
+ * semicolons_parse("echo 'a;b'; pwd")            // Returns: ["echo 'a;b'", "pwd"]
+ * semicolons_parse("cd /tmp; ls; cat file.txt")  // Returns: ["cd /tmp", "ls", "cat file.txt"]
+ * ```
+ */
+export function semicolons_parse(line) {
+    const commands = [];
+    let currentCommand = '';
+    let inSingleQuote = false;
+    let inDoubleQuote = false;
+    for (let i = 0; i < line.length; i++) {
+        const char = line[i];
+        if (char === "'" && !inDoubleQuote) {
+            inSingleQuote = !inSingleQuote;
+            currentCommand += char;
+        }
+        else if (char === '"' && !inSingleQuote) {
+            inDoubleQuote = !inDoubleQuote;
+            currentCommand += char;
+        }
+        else if (char === ';' && !inSingleQuote && !inDoubleQuote) {
+            const trimmed = currentCommand.trim();
+            if (trimmed)
+                commands.push(trimmed);
+            currentCommand = '';
+        }
+        else {
+            currentCommand += char;
+        }
+    }
+    // Add final command
+    const trimmed = currentCommand.trim();
+    if (trimmed)
+        commands.push(trimmed);
+    return commands;
+}
+//# sourceMappingURL=semicolonParser.js.map

package/dist/lib/semicolonParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semicolonParser.js","sourceRoot":"","sources":["../../src/lib/semicolonParser.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,cAAc,GAAW,EAAE,CAAC;IAChC,IAAI,aAAa,GAAY,KAAK,CAAC;IACnC,IAAI,aAAa,GAAY,KAAK,CAAC;IAEnC,KAAK,IAAI,CAAC,GAAW,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7C,MAAM,IAAI,GAAW,IAAI,CAAC,CAAC,CAAC,CAAC;QAE7B,IAAI,IAAI,KAAK,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;YACnC,aAAa,GAAG,CAAC,aAAa,CAAC;YAC/B,cAAc,IAAI,IAAI,CAAC;QACzB,CAAC;aAAM,IAAI,IAAI,KAAK,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;YAC1C,aAAa,GAAG,CAAC,aAAa,CAAC;YAC/B,cAAc,IAAI,IAAI,CAAC;QACzB,CAAC;aAAM,IAAI,IAAI,KAAK,GAAG,IAAI,CAAC,aAAa,IAAI,CAAC,aAAa,EAAE,CAAC;YAC5D,MAAM,OAAO,GAAW,cAAc,CAAC,IAAI,EAAE,CAAC;YAC9C,IAAI,OAAO;gBAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACpC,cAAc,GAAG,EAAE,CAAC;QACtB,CAAC;aAAM,CAAC;YACN,cAAc,IAAI,IAAI,CAAC;QACzB,CAAC;IACH,CAAC;IAED,oBAAoB;IACpB,MAAM,OAAO,GAAW,cAAc,CAAC,IAAI,EAAE,CAAC;IAC9C,IAAI,OAAO;QAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAEpC,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/lib/spinner.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @file Terminal spinner utility for long-running operations.
+ *
+ * @module
+ */
+/**
+ * Terminal spinner indicating progress of async work.
+ */
+export declare class Spinner {
+    private interval;
+    private message;
+    private frames;
+    private frameIndex;
+    private spinnerActive;
+    private startTime;
+    private showTiming;
+    constructor(initialMessage?: string);
+    start(message?: string, showTiming?: boolean): void;
+    stop(clearLine?: boolean): void;
+    updateMessage(newMessage: string): void;
+}
+declare const globalSpinner: Spinner;
+export { globalSpinner as spinner };

package/dist/lib/spinner.js

@@ -0,0 +1,68 @@
+/**
+ * @file Terminal spinner utility for long-running operations.
+ *
+ * @module
+ */
+import chalk from 'chalk';
+/**
+ * Terminal spinner indicating progress of async work.
+ */
+export class Spinner {
+    interval = null;
+    message = '';
+    frames = ["⣾", "⣽", "⣻", "⢿", "⡿", "⣟", "⣯", "⣷"];
+    frameIndex = 0;
+    spinnerActive = false;
+    startTime = 0;
+    showTiming = false;
+    constructor(initialMessage = 'Loading...') {
+        this.message = initialMessage;
+    }
+    start(message, showTiming = false) {
+        // Do not start spinner if not in a TTY (e.g. piped output)
+        if (!process.stdout.isTTY) {
+            return;
+        }
+        if (this.spinnerActive) {
+            this.stop(); // Stop any existing spinner
+        }
+        this.message = message || this.message;
+        this.spinnerActive = true;
+        this.frameIndex = 0;
+        this.showTiming = showTiming;
+        this.startTime = Date.now();
+        // Hide cursor
+        process.stdout.write('\x1B[?25l');
+        this.interval = setInterval(() => {
+            const frame = this.frames[this.frameIndex = (this.frameIndex + 1) % this.frames.length];
+            let displayMessage = this.message;
+            // Add timing if enabled
+            if (this.showTiming) {
+                const elapsedSeconds = ((Date.now() - this.startTime) / 1000).toFixed(1);
+                displayMessage = `${this.message} (${elapsedSeconds}s)`;
+            }
+            // Note: We use chalk.gray for the message to match the existing "Fetching..." style
+            process.stdout.write(`\r${chalk.bgBlack.cyanBright.bold(frame)} ${chalk.gray(displayMessage)}`);
+        }, 80);
+    }
+    stop(clearLine = true) {
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+        if (this.spinnerActive) {
+            if (clearLine) {
+                process.stdout.write('\r\x1b[K'); // Clear line
+            }
+            // Show cursor
+            process.stdout.write('\x1B[?25h');
+            this.spinnerActive = false;
+        }
+    }
+    updateMessage(newMessage) {
+        this.message = newMessage;
+    }
+}
+const globalSpinner = new Spinner();
+export { globalSpinner as spinner };
+//# sourceMappingURL=spinner.js.map

package/dist/lib/spinner.js.map

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

package/dist/lib/vfs/providers/static.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @file Static Virtual File System Provider.
+ *
+ * Implements virtual directories for `/bin`, `/usr`, and `/usr/bin` under the VFSDispatcher.
+ *
+ * @module
+ */
+import { Result } from '@fnndsc/cumin';
+import { VFSProvider, VFSItem, CpOptions } from '@fnndsc/salsa';
+/**
+ * Static virtual filesystem provider for command and builtin paths.
+ */
+export declare class StaticVfsProvider implements VFSProvider {
+    /** The prefix path this provider handles. */
+    prefix: string;
+    /**
+     * Initializes the static provider with its target prefix path.
+     *
+     * @param prefix - The absolute virtual directory prefix.
+     */
+    constructor(prefix: string);
+    /**
+     * Lists the contents of the matched static prefix path.
+     *
+     * @param pathStr - The absolute path.
+     * @param options - Sort controls.
+     * @returns Promise resolving to Result of VFSItems.
+     */
+    list(pathStr: string, options?: {
+        sort?: "name" | "size" | "date" | "owner";
+        reverse?: boolean;
+    }): Promise<Result<VFSItem[]>>;
+    /**
+     * Block copy operations for static paths.
+     *
+     * @param src - Source path.
+     * @param dest - Destination path.
+     * @param options - Copy options.
+     * @returns Promise resolving to false always to block copying.
+     */
+    cp(src: string, dest: string, options: CpOptions): Promise<boolean>;
+    /**
+     * Standard sort helper for virtual items.
+     *
+     * @param items - The VFSItem array to sort.
+     * @param sortField - Field to sort by.
+     * @param reverse - True to reverse output sorting.
+     * @returns Sorted VFSItem array.
+     */
+    private staticVfsItems_sort;
+    /**
+     * Reads virtual file content under command and builtin static paths.
+     *
+     * @param pathStr - The absolute virtual path of the file to read.
+     * @returns Promise resolving to a Result containing the file contents.
+     */
+    read(pathStr: string): Promise<Result<string>>;
+    /**
+     * Reads virtual file binary content under command and builtin static paths.
+     *
+     * @param pathStr - The absolute virtual path of the file to read.
+     * @returns Promise resolving to a Result containing the file contents as a Buffer.
+     */
+    readBinary(pathStr: string): Promise<Result<Buffer>>;
+}

package/dist/lib/vfs/providers/static.js

@@ -0,0 +1,164 @@
+/**
+ * @file Static Virtual File System Provider.
+ *
+ * Implements virtual directories for `/bin`, `/usr`, and `/usr/bin` under the VFSDispatcher.
+ *
+ * @module
+ */
+import { Ok, Err, errorStack } from '@fnndsc/cumin';
+import { plugins_listAll, pipelines_getAll } from '@fnndsc/salsa';
+import { builtinCommands_list } from '../../../builtins/help.js';
+import { staticVfs_read, staticVfs_readBinary } from './static_content.js';
+/**
+ * Static virtual filesystem provider for command and builtin paths.
+ */
+export class StaticVfsProvider {
+    /** The prefix path this provider handles. */
+    prefix;
+    /**
+     * Initializes the static provider with its target prefix path.
+     *
+     * @param prefix - The absolute virtual directory prefix.
+     */
+    constructor(prefix) {
+        this.prefix = prefix;
+    }
+    /**
+     * Lists the contents of the matched static prefix path.
+     *
+     * @param pathStr - The absolute path.
+     * @param options - Sort controls.
+     * @returns Promise resolving to Result of VFSItems.
+     */
+    async list(pathStr, options) {
+        try {
+            let effectivePath = pathStr.startsWith("/") ? pathStr : "/" + pathStr;
+            if (effectivePath.length > 1 && effectivePath.endsWith("/")) {
+                effectivePath = effectivePath.slice(0, -1);
+            }
+            if (effectivePath === "/bin") {
+                const [plugins, pipelinesResult] = await Promise.all([
+                    plugins_listAll({}),
+                    pipelines_getAll(),
+                ]);
+                const items = [];
+                if (plugins && plugins.tableData) {
+                    plugins.tableData.forEach((plugin) => {
+                        const pluginName = typeof plugin.name === 'string' ? plugin.name : String(plugin.name);
+                        const pluginVersion = typeof plugin.version === 'string' ? plugin.version : String(plugin.version || '');
+                        const displayName = pluginVersion ? `${pluginName}-v${pluginVersion}` : pluginName;
+                        items.push({
+                            name: displayName,
+                            type: "plugin",
+                            size: 0,
+                            owner: "system",
+                            date: typeof plugin.creation_date === 'string' ? plugin.creation_date : '',
+                        });
+                    });
+                }
+                if (pipelinesResult.ok) {
+                    pipelinesResult.value.forEach((pipeline) => {
+                        const slug = typeof pipeline.slug === 'string' ? pipeline.slug : pipeline.name.replace(/\s+/g, '_');
+                        items.push({
+                            name: slug,
+                            type: "pipeline",
+                            size: 0,
+                            owner: typeof pipeline.authors === 'string' ? pipeline.authors : 'system',
+                            date: '',
+                            title: pipeline.name,
+                        });
+                    });
+                }
+                const sorted = this.staticVfsItems_sort(items, options?.sort, options?.reverse);
+                return Ok(sorted);
+            }
+            if (effectivePath === "/usr") {
+                const items = [
+                    {
+                        name: "bin",
+                        type: "vfs",
+                        size: 0,
+                        owner: "root",
+                        date: new Date().toISOString(),
+                    }
+                ];
+                return Ok(items);
+            }
+            if (effectivePath === "/usr/bin") {
+                const builtinNames = builtinCommands_list();
+                const items = builtinNames.map((name) => ({
+                    name,
+                    type: "plugin",
+                    size: 0,
+                    owner: "system",
+                    date: new Date().toISOString(),
+                }));
+                const sorted = this.staticVfsItems_sort(items, options?.sort, options?.reverse);
+                return Ok(sorted);
+            }
+            return Ok([]);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            errorStack.stack_push("error", `Static VFS list failed for prefix ${this.prefix}: ${msg}`);
+            return Err();
+        }
+    }
+    /**
+     * Block copy operations for static paths.
+     *
+     * @param src - Source path.
+     * @param dest - Destination path.
+     * @param options - Copy options.
+     * @returns Promise resolving to false always to block copying.
+     */
+    async cp(src, dest, options) {
+        errorStack.stack_push("error", `cp: Copying from static VFS path '${src}' is not supported.`);
+        return false;
+    }
+    /**
+     * Standard sort helper for virtual items.
+     *
+     * @param items - The VFSItem array to sort.
+     * @param sortField - Field to sort by.
+     * @param reverse - True to reverse output sorting.
+     * @returns Sorted VFSItem array.
+     */
+    staticVfsItems_sort(items, sortField, reverse) {
+        const field = sortField || "name";
+        const sorted = [...items].sort((a, b) => {
+            const valA = a[field];
+            const valB = b[field];
+            if (typeof valA === "string" && typeof valB === "string") {
+                return valA.localeCompare(valB);
+            }
+            if (typeof valA === "number" && typeof valB === "number") {
+                return valA - valB;
+            }
+            return 0;
+        });
+        if (reverse) {
+            sorted.reverse();
+        }
+        return sorted;
+    }
+    /**
+     * Reads virtual file content under command and builtin static paths.
+     *
+     * @param pathStr - The absolute virtual path of the file to read.
+     * @returns Promise resolving to a Result containing the file contents.
+     */
+    async read(pathStr) {
+        return staticVfs_read(pathStr, this.prefix);
+    }
+    /**
+     * Reads virtual file binary content under command and builtin static paths.
+     *
+     * @param pathStr - The absolute virtual path of the file to read.
+     * @returns Promise resolving to a Result containing the file contents as a Buffer.
+     */
+    async readBinary(pathStr) {
+        return staticVfs_readBinary(pathStr, this.prefix);
+    }
+}
+//# sourceMappingURL=static.js.map

package/dist/lib/vfs/providers/static.js.map

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

package/dist/lib/vfs/providers/static_content.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @file Static VFS Content Handler.
+ *
+ * Implements specialized virtual file reading and content generation
+ * for static command directories (/bin, /usr/bin).
+ *
+ * @module
+ */
+import { Result } from '@fnndsc/cumin';
+/**
+ * Reads virtual file content under command and builtin static paths.
+ *
+ * Handles help text formatting for /usr/bin and fetches parameter specifications for /bin plugins.
+ *
+ * @param pathStr - The absolute virtual path of the file to read.
+ * @param prefix - The prefix of the calling provider (e.g. '/usr/bin', '/bin').
+ * @returns Promise resolving to a Result containing the file contents as a string.
+ */
+export declare function staticVfs_read(pathStr: string, prefix: string): Promise<Result<string>>;
+/**
+ * Reads virtual file binary content under command and builtin static paths.
+ *
+ * @param pathStr - The absolute virtual path of the file to read.
+ * @param prefix - The prefix of the calling provider.
+ * @returns Promise resolving to a Result containing the file contents as a Buffer.
+ */
+export declare function staticVfs_readBinary(pathStr: string, prefix: string): Promise<Result<Buffer>>;