@fnndsc/chell 4.2.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 FNNDSC / BCH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,325 @@
+# ChELL: ChELL Executes Layered Logic
+
+**The Interactive Shell for ChRIS**
+
+ChELL is a command-line shell that presents a ChRIS distributed-computing platform as a familiar Unix filesystem. If you know `bash` or `zsh`, you already know most of ChELL.
+
+## Installation
+
+```bash
+npm install -g @fnndsc/chell
+```
+
+Requires Node.js ≥ 20.12. This installs the `chell` command — see [Getting Started](#getting-started) to connect to a CUBE.
+
+## The Concept
+
+ChRIS stores data, analysis tools, and results behind a REST API. ChELL maps all of that onto paths:
+
+- your data lives under `/home/<user>/`
+- every registered plugin is a virtual executable in `/bin`
+- system configuration is readable at `/etc`
+- PACS query results surface under `/net/pacs/queries/`
+
+You navigate with `cd`, inspect with `ls`, read files with `cat`, and run analyses by invoking plugin names — the same muscle memory you use on any Unix system.
+
+---
+
+## The Virtual Filesystem
+
+The ChELL filesystem has two kinds of paths:
+
+- **CFS (CubeFS)** — real ChRIS storage: files you upload, feed outputs, symlink files. Readable, writable, persistent.
+- **VFS (Virtual)** — synthesised on the fly from API resources: plugins, config, PACS results. Read-only views, no stored bytes.
+
+| Path | Type | What you see |
+|------|:----:|-------------|
+| `/home/<user>/` | CFS | Your uploaded files and directories |
+| `/home/<user>/feeds/` | CFS | Your analysis feeds and their output trees |
+| `/PIPELINES/` | CFS | Shared pipeline output data |
+| `/PUBLIC/` | CFS | Publicly accessible files |
+| `/SERVICES/` | CFS | Service-level data |
+| `/SHARED/` | CFS | Cross-user shared data |
+| `*.chrislink` | CFS | Symbolic links to other ChRIS paths |
+| `/bin` | VFS | Every plugin registered in this CUBE |
+| `/usr/bin` | VFS | Built-in shell commands (`whoami`, `whereami`, …) |
+| `/etc/` | VFS | Config: compute environments, groups, users, CUBE info |
+| `/net/pacs/queries/` | VFS | PACS query result sets |
+| `/proc/feeds/` | VFS | Job monitoring — live status of all plugin instances |
+
+```bash
+cd /etc
+cat compute.yaml          # inspect available compute environments
+cat group                 # list groups
+
+cd /bin
+ls pl-mri*                # browse MRI-related plugins
+
+cd /home/chris/feeds
+ls -l                     # see your analysis feeds
+```
+
+### Symlinks (`.chrislink` files)
+
+ChRIS uses `.chrislink` files as symbolic links. `ls -l` renders them as `l` entries; `cd` and `cat` follow them transparently. The link target is resolved through the VFS dispatcher — it can point anywhere in the virtual tree.
+
+---
+
+## Running Plugins
+
+Because plugins live in `/bin` as virtual executables, you invoke them **directly by name** — exactly like running a local binary. ChELL uses your **current working directory** to determine context automatically, so you never need to supply a `--previous_id` by hand.
+
+### Case 1 — Starting a new analysis from a data directory
+
+```bash
+cd /home/chris/uploads/SAG-anon
+pl-fshack-v1.2.0 --inputFile brain.mgz --outputFile brain.nii
+```
+
+ChELL detects you are **outside a feed**. It:
+1. Automatically runs `pl-dircopy` on the current directory to stage the data into a new feed
+2. Attaches your plugin to that dircopy instance as the next step
+
+A new feed is created for you — no boilerplate.
+
+### Case 2 — Continuing an existing analysis
+
+```bash
+cd /home/chris/feeds/feed_123/pl-fshack_456/data
+pl-segmentation-v1.0.0 --threshold 0.5
+```
+
+ChELL detects you are **inside a feed**. It extracts the plugin instance ID from the path (`456`) and uses it as `previous_id` automatically. The new plugin node is wired into the existing computation DAG.
+
+### Naming feeds and instances
+
+Use `--` to separate plugin parameters from feed-level context:
+
+```bash
+pl-fshack-v1.2.0 --inputFile brain.mgz -- feed_title="Brain MRI Study" instance_title="FreeSurfer recon"
+```
+
+Everything before `--` goes to the plugin; everything after sets ChRIS metadata.
+
+### Monitoring
+
+```bash
+job inspect <instance_id>
+jobs list --feed <feed_id>
+```
+
+### Installing new plugins
+
+```bash
+# Search the public peer store
+store search simplefs
+
+# Install (auto-discovers compute resources)
+store install pl-simplefsapp
+
+# Install pinned to specific compute
+store install pl-simplefsapp --compute ares,argentum
+```
+
+`store install` runs a three-phase resolution:
+1. Already in this CUBE → reports `[INFO] already registered`
+2. Found in peer store (cube.chrisproject.org) → imports via admin API (prompts for admin credentials if needed)
+3. Not found → Docker extraction and registration
+
+---
+
+## Running Pipelines
+
+A **pipeline** is a registered template — a named, reusable graph of plugins with their parameter defaults wired together. Pipelines are static definitions; they do not run on their own.
+
+A **workflow** is a live instantiation of a pipeline, attached to a specific feed node. Creating a workflow is the act of "running" a pipeline: ChRIS schedules each plugin step in order, feeding outputs of one into the inputs of the next.
+
+```bash
+# Browse registered pipeline templates
+pipeline list
+pipeline inspect <id>
+
+# Instantiate a pipeline on an existing feed node → creates a workflow
+workflow create <pipeline_id> --previous_id <instance_id>
+
+# Monitor all the jobs it spawns
+jobs list --feed <feed_id>
+```
+
+The `--previous_id` here is the feed node to attach the first pipeline step to — the same context that ChELL resolves automatically when you invoke a single plugin directly.
+
+---
+
+## Monitoring Jobs: `/proc/feeds/`
+
+Because every plugin runs asynchronously in ChRIS, `/proc/feeds/` is where you come back to see what happened. It exposes all your visible feeds and their plugin instances as a navigable DAG — the same tree structure the computation actually ran in.
+
+```
+/proc/feeds/
+└── feed_123/
+    ├── status                        ← aggregate feed status
+    ├── title                         ← feed name
+    └── pl-dircopy_456/               ← root node (j = job type in ls -l)
+        ├── status                    ← finishedSuccessfully
+        ├── params
+        ├── log
+        └── pl-fshack_789/
+            ├── status                ← started
+            └── pl-segmentation_1011/
+                └── status            ← scheduled
+```
+
+```bash
+ls -l /proc/feeds/feed_123            # see all nodes with colour-coded status
+cat /proc/feeds/feed_123/pl-fshack_789/status   # live status fetch
+cat /proc/feeds/feed_123/pl-fshack_789/log      # stdout/stderr
+cat /proc/feeds/feed_123/pl-fshack_789/params   # what it ran with
+
+# Search across all jobs
+tree /proc/feeds | grep 789           # find instance 789 and see its full lineage
+
+# Cancel a running job
+rm /proc/feeds/feed_123/pl-fshack_789
+
+# Cancel all jobs in a feed (requires -r)
+rm -r /proc/feeds/feed_123
+```
+
+Status colours in `ls -l`: green = `finishedSuccessfully`, yellow = `started`/`running`, gray = `scheduled`/`cancelled`, red = `finishedWithError`.
+
+The cache is built lazily on first access to `/proc`. Rebuild explicitly after external activity (other users, web GUI):
+
+```bash
+proc refresh              # rebuild all
+proc refresh feed_123     # scope to one feed
+```
+
+Since `/proc` paths encode the instance ID, you can also **continue an analysis from any node** just by `cd`-ing into it:
+
+```bash
+cd /proc/feeds/feed_123/pl-dircopy_456
+pl-fshack-v1.2.0 --inputFile brain.mgz   # attaches here, no --previous_id needed
+```
+
+---
+
+## Key Commands
+
+### Filesystem
+```bash
+ls [-l] [-h] [-a]       # list directory
+cd <path>               # change directory (follows .chrislinks)
+cat <file>              # print file content
+edit <file>             # open in $EDITOR, save back to ChRIS
+cp / mv / rm            # copy, move, delete
+mkdir / touch           # create directory or empty file
+upload <local> <remote> # upload local file or directory tree
+download <remote> <local>
+tree                    # recursive listing
+du                      # disk usage
+```
+
+### Resources
+```bash
+plugin list / search / inspect / run
+plugins list [--search <term>] [--all]
+feed list / inspect
+feeds list [--user <name>] [--all]
+feed note <id>          # read feed note
+feed note edit <id>     # edit feed note in $EDITOR
+feed comments <id>      # list comments
+pipeline list / inspect
+workflow list / create
+job inspect <id>
+compute list            # list compute environments
+```
+
+### Store
+```bash
+store list              # browse peer store
+store search <query>
+store install <plugin>  # install with admin escalation if needed
+store inspect           # show current peer store URL
+store set <url>         # override peer store
+```
+
+### System
+```bash
+whoami                  # current user and CUBE URL
+whereami                # current working directory
+connect --user <u> --password <p> <url>
+logout
+proc refresh            # rebuild /proc job cache
+proc refresh feed_123   # scope rebuild to one feed
+```
+
+---
+
+## Getting Started
+
+```bash
+# Start the shell, then connect interactively
+chell
+> connect --user chris --password chris1234 http://localhost:8000/api/v1/
+
+# Connect via flags
+chell -u chris -p chris1234 http://localhost:8000/api/v1/
+
+# Compact user@host form (password prompted if omitted)
+chell chris@localhost:8000/api/v1/
+chell -p chris1234 chris@localhost:8000/api/v1/
+```
+
+### Scripting
+
+```bash
+# Non-interactive: single command via -c
+chell -c "ls -l /home/user/study" > study_contents.txt
+chell -c "store install pl-dircopy"
+
+# Run a script file
+chell -f my_workflow.chell
+```
+
+---
+
+## Architecture
+
+ChELL is the presentation layer of the "Sandwich Model":
+
+1. **ChELL** — REPL, builtins, tab completion, prompt
+2. **ChILI** — typed commands, views, CLI controllers
+3. **Salsa** — business logic, VFS dispatcher, intent layer
+4. **Cumin** — connection, context persistence, state
+5. **`@fnndsc/chrisapi`** — raw ChRIS REST client
+
+---
+
+## Further Reading
+
+| Document | Topic |
+|----------|-------|
+| [docs/vfs.adoc](docs/vfs.adoc) | VFS architecture — providers, dispatch, path resolution |
+| [docs/pluginrun.adoc](docs/pluginrun.adoc) | Plugin execution in depth — new feed vs continue feed |
+| [docs/plugin-run-summary.md](docs/plugin-run-summary.md) | Quick-reference summary of plugin run modes |
+| [docs/store.adoc](docs/store.adoc) | Store install — three-phase resolution, admin escalation |
+| [docs/login.adoc](docs/login.adoc) | Connection and authentication options |
+| [docs/execution.adoc](docs/execution.adoc) | Command execution, scripting, and pipeline mode |
+| [docs/commands.adoc](docs/commands.adoc) | Full command reference |
+| [docs/pacsqr.adoc](docs/pacsqr.adoc) | PACS query and retrieve |
+| [docs/physicalMode.adoc](docs/physicalMode.adoc) | Physical vs logical filesystem mode |
+| [docs/gotchas.adoc](docs/gotchas.adoc) | Known edge cases and workarounds |
+| [docs/architecture.adoc](docs/architecture.adoc) | Full architecture deep-dive |
+| [CONTEXT.md](CONTEXT.md) | Domain glossary — ChRIS concepts, permission model, resource contract |
+
+---
+
+## License
+
+Part of the [ChRIS Project](https://chrisproject.org).
+
+---
+*ChELL is part of the ChRIS Project.*
+
+---
+_-30-_

package/dist/builtins/debug.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Toggles or displays debug mode status.
+ *
+ * @param args - Command line arguments: 'on', 'off', or empty to display status.
+ */
+export declare function builtin_debug(args: string[]): Promise<void>;

package/dist/builtins/debug.js

@@ -0,0 +1,47 @@
+/**
+ * @file Debug Command
+ *
+ * Toggles debug mode for the application, enabling verbose error logging.
+ */
+import chalk from 'chalk';
+import { session } from '../session/index.js';
+/**
+ * Toggles or displays debug mode status.
+ *
+ * @param args - Command line arguments: 'on', 'off', or empty to display status.
+ */
+export async function builtin_debug(args) {
+    const subcommand = args[0];
+    const config = session.connection.config;
+    if (!config) {
+        console.error(chalk.red('Error: Connection configuration not initialized.'));
+        return;
+    }
+    if (!subcommand) {
+        const status = config.debug ? 'enabled' : 'disabled';
+        console.log(`Debug mode: ${chalk.yellow(status)}`);
+        if (config.debug) {
+            console.log(chalk.gray('  Verbose error logging is enabled.'));
+        }
+        else {
+            console.log(chalk.gray('  Verbose error logging is disabled.'));
+        }
+        console.log(chalk.gray('\nUsage: debug [on|off]'));
+        return;
+    }
+    if (subcommand === 'on') {
+        config.debug = true;
+        console.log(chalk.yellow('[!] Debug mode enabled'));
+        console.log(chalk.gray('    Verbose error logging activated.'));
+    }
+    else if (subcommand === 'off') {
+        config.debug = false;
+        console.log(chalk.green('[+] Debug mode disabled'));
+        console.log(chalk.gray('    Verbose error logging deactivated.'));
+    }
+    else {
+        console.log(chalk.red(`Unknown argument: ${subcommand}`));
+        console.log(chalk.gray('Usage: debug [on|off]'));
+    }
+}
+//# 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,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAE9C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAc;IAChD,MAAM,UAAU,GAAuB,IAAI,CAAC,CAAC,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC;IAEzC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,kDAAkD,CAAC,CAAC,CAAC;QAC7E,OAAO;IACT,CAAC;IAED,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,MAAM,GAAW,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC;QAC7D,OAAO,CAAC,GAAG,CAAC,eAAe,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACnD,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC,CAAC;QACjE,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC,CAAC;QAClE,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC,CAAC;QACnD,OAAO;IACT,CAAC;IAED,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QACxB,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,wBAAwB,CAAC,CAAC,CAAC;QACpD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC,CAAC;IAClE,CAAC;SAAM,IAAI,UAAU,KAAK,KAAK,EAAE,CAAC;QAChC,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;QACrB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC,CAAC;QACpD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,wCAAwC,CAAC,CAAC,CAAC;IACpE,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,qBAAqB,UAAU,EAAE,CAAC,CAAC,CAAC;QAC1D,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC,CAAC;IACnD,CAAC;AACH,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 @@
+/**
+ * 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.
+ *
+ * @param args - Command line arguments (file paths and optional --binary flag).
+ *
+ * @example
+ * ```typescript
+ * await builtin_cat(['file1.txt', 'file2.txt']);
+ * await builtin_cat(['--binary', 'image.dcm']);
+ * await builtin_cat(['*.json']);  // After wildcard expansion
+ * ```
+ */
+export declare function builtin_cat(args: string[]): Promise<void>;