@fnndsc/chili 3.2.5 → 3.4.0

package/README.md

@@ -42,27 +42,34 @@ Designed for developers and power-users who want to script and control a ChRIS i
 2.  **[`salsa`](https://github.com/FNNDSC/salsa) (Logic)**: Shared Application Logic and Service Assets — high-level business intents.
 3.  **[`cumin`](https://github.com/FNNDSC/cumin) (Infrastructure)**: State and connection layer — authentication, context persistence, low-level API.
 
-## Installation & Development
+## Development
 
-### Full build (all layers)
+`chili` lives in the [`mise` monorepo](https://github.com/FNNDSC/mise) alongside
+`cumin`, `salsa`, and `chell`. Build the whole stack from the repository root —
+npm workspaces links the four packages together, so there is nothing to clone or
+hand-link:
 
 ```bash
-cd chili
-make meal
+git clone https://github.com/FNNDSC/mise
+cd mise
+make taco            # scrub → prep → cook → taste → serve (the full course)
 ```
 
-### Individual steps
+### Individual steps (run from the repo root)
 
 | Target | Action |
 |--------|--------|
-| `make shop` | Clone `cumin` and `salsa` if missing |
-| `make prep` | `npm install` across all packages |
-| `make cook` | Build (compile TypeScript) all packages |
-| `make taste` | Run tests |
-| `make serve` | Link packages globally |
+| `make prep` | `npm install` — install deps and link all four workspaces |
+| `make cook` | Build (compile TypeScript) all packages in dependency order |
+| `make taste` | Run the full test suite |
+| `make serve` | Link `chell` globally |
 | `make scrub` | Clean build artifacts and `node_modules` |
 
-> Use [NVM](https://github.com/nvm-sh/nvm) to avoid needing `sudo` for global links.
+To build or test just this package: `npm run build -w @fnndsc/chili` /
+`npm test -w @fnndsc/chili`.
+
+> Use [NVM](https://github.com/nvm-sh/nvm) and Node 22.x to avoid needing `sudo`
+> for the global link in `make serve`.
 
 ## Core Features
 

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

@@ -13,13 +13,28 @@ export interface DownloadSummary {
     duration: number;
     speed: number;
 }
+/** Download progress fact emitted to callers that want to render progress. */
+export interface DownloadProgressEvent {
+    operation: "download";
+    kind: "transfer";
+    phase: "scanning" | "transferring" | "complete" | "failed";
+    label?: string;
+    current?: number;
+    total?: number;
+    percent?: number;
+    unit?: "files" | "bytes";
+    status?: "running" | "done" | "error";
+}
+/** Options for download execution. */
+export interface DownloadOptions {
+    force?: boolean;
+    onProgress?: (event: DownloadProgressEvent) => void;
+}
 /**
- * Downloads files from ChRIS with a progress bar display.
+ * Downloads files from ChRIS and optionally emits structured progress events.
  * @param chrisPath - Remote ChRIS path (file or directory).
  * @param localPath - Local filesystem path.
  * @param options - Download options.
  * @returns Promise<DownloadSummary> with download statistics.
  */
-export declare function files_downloadWithProgress(chrisPath: string, localPath: string, options?: {
-    force?: boolean;
-}): Promise<DownloadSummary>;
+export declare function files_downloadWithProgress(chrisPath: string, localPath: string, options?: DownloadOptions): Promise<DownloadSummary>;

package/dist/commands/fs/download.js

@@ -6,10 +6,9 @@ import { fileContent_getBinaryStream, files_listRecursive } from "@fnndsc/salsa"
 import { path_resolveChrisFs } from "../../utils/cli.js";
 import fs from "fs";
 import path from "path";
-import cliProgress from "cli-progress";
 import chalk from "chalk";
 import { pipeline } from "stream/promises";
-import { bytes_format, eta_format, rate_format } from "./upload.js";
+import { bytes_format } from "./upload.js";
 import { prompt_confirmOrThrow } from "../../utils/input_format.js";
 export { bytes_format };
 /**
@@ -36,7 +35,7 @@ async function chrisPath_isDirectory(chrisPath) {
     }
 }
 /**
- * Downloads files from ChRIS with a progress bar display.
+ * Downloads files from ChRIS and optionally emits structured progress events.
  * @param chrisPath - Remote ChRIS path (file or directory).
  * @param localPath - Local filesystem path.
  * @param options - Download options.
@@ -93,61 +92,66 @@ export async function files_downloadWithProgress(chrisPath, localPath, options =
             // Ensure parent directory exists
             const parentDir = path.dirname(finalLocalPath);
             await directory_ensureExists(parentDir);
-            const showProgress = !!process.stdout.isTTY;
-            const progressBar = typeof size === "number" && showProgress
-                ? new cliProgress.SingleBar({
-                    format: "Downloading [{bar}] {percentage}% | ETA: {etaHuman} | Rate: {rate} | {bytes}/{totalBytes}",
-                }, cliProgress.Presets.shades_classic)
-                : null;
-            if (progressBar) {
-                progressBar.start(size, 0, {
-                    etaHuman: "--",
-                    rate: "--",
-                    bytes: bytes_format(0),
-                    totalBytes: bytes_format(size),
-                });
-            }
             let transferred = 0;
             const writeStream = fs.createWriteStream(finalLocalPath);
             stream.on("data", (chunk) => {
                 transferred += chunk.length;
-                if (progressBar) {
-                    const elapsedSeconds = Math.max(1e-6, (Date.now() - summary.startTime) / 1000);
-                    const rateCurrent = transferred / elapsedSeconds;
-                    const remainingBytes = Math.max(0, (size ?? transferred) - transferred);
-                    const etaSeconds = rateCurrent > 0 ? remainingBytes / rateCurrent : null;
-                    progressBar.update(Math.min(transferred, size || transferred), {
-                        etaHuman: eta_format(etaSeconds),
-                        rate: rate_format(rateCurrent),
-                        bytes: bytes_format(transferred),
-                        totalBytes: bytes_format(size ?? transferred),
-                    });
-                }
+                options.onProgress?.({
+                    operation: "download",
+                    kind: "transfer",
+                    phase: "transferring",
+                    label: `Downloading ${path.basename(finalLocalPath)}`,
+                    current: transferred,
+                    total: size,
+                    percent: typeof size === "number" && size > 0 ? (Math.min(transferred, size) / size) * 100 : undefined,
+                    unit: "bytes",
+                    status: "running",
+                });
             });
             await pipeline(stream, writeStream);
-            if (progressBar) {
-                progressBar.update(size || transferred);
-                progressBar.stop();
-            }
             summary.totalFiles = 1;
             summary.transferredCount = 1;
             summary.transferSize = transferred;
             summary.endTime = Date.now();
             summary.duration = (summary.endTime - summary.startTime) / 1000;
             summary.speed = summary.duration > 0 ? summary.transferSize / summary.duration : 0;
+            options.onProgress?.({
+                operation: "download",
+                kind: "transfer",
+                phase: "complete",
+                label: "Download complete",
+                current: transferred,
+                total: size,
+                percent: typeof size === "number" && size > 0 ? 100 : undefined,
+                unit: "bytes",
+                status: "done",
+            });
             return summary;
         }
         catch (error) {
             summary.failedCount = 1;
+            options.onProgress?.({
+                operation: "download",
+                kind: "transfer",
+                phase: "failed",
+                label: "Download failed",
+                status: "error",
+            });
             throw error;
         }
     }
     // Download directory
     console.log(chalk.cyan("Scanning files to download..."));
+    options.onProgress?.({
+        operation: "download",
+        kind: "transfer",
+        phase: "scanning",
+        label: "Scanning files to download",
+        status: "running",
+    });
     const items = await files_listRecursive(resolvedChris);
     const files = items.filter((item) => item.type === 'file');
     summary.totalFiles = files.length;
-    const totalSize = files.reduce((sum, f) => sum + (f.size || 0), 0);
     // Apply Unix semantics: trailing slash determines merge behavior
     const targetDir = resolvedChris.endsWith('/')
         ? localPath // Merge contents
@@ -169,20 +173,17 @@ export async function files_downloadWithProgress(chrisPath, localPath, options =
     }
     // Ensure target directory exists
     await directory_ensureExists(targetDir);
-    const showProgress = !!process.stdout.isTTY;
-    const progressBar = showProgress
-        ? new cliProgress.SingleBar({
-            format: "Downloading [{bar}] {percentage}% | ETA: {etaHuman} | Rate: {rate} | {value}/{total} files | {bytes}/{totalBytes}",
-        }, cliProgress.Presets.shades_classic)
-        : null;
-    if (progressBar) {
-        progressBar.start(files.length, 0, {
-            bytes: bytes_format(0),
-            totalBytes: bytes_format(totalSize),
-            etaHuman: "--",
-            rate: "--",
-        });
-    }
+    options.onProgress?.({
+        operation: "download",
+        kind: "transfer",
+        phase: "transferring",
+        label: "Downloading files",
+        current: 0,
+        total: files.length,
+        percent: files.length === 0 ? 100 : 0,
+        unit: "files",
+        status: "running",
+    });
     // Download each file
     for (const [index, file] of files.entries()) {
         try {
@@ -213,23 +214,31 @@ export async function files_downloadWithProgress(chrisPath, localPath, options =
             const msg = error instanceof Error ? error.message : String(error);
             console.log(chalk.red(`\nError downloading ${file.path}: ${msg}`));
         }
-        const elapsedSeconds = Math.max(1e-6, (Date.now() - summary.startTime) / 1000);
-        const rateCurrent = summary.transferSize > 0 ? summary.transferSize / elapsedSeconds : 0;
-        const remainingBytes = Math.max(0, totalSize - summary.transferSize);
-        const etaSeconds = rateCurrent > 0 ? remainingBytes / rateCurrent : null;
-        if (progressBar) {
-            progressBar.update(index + 1, {
-                bytes: bytes_format(summary.transferSize),
-                etaHuman: eta_format(etaSeconds),
-                rate: rate_format(rateCurrent),
-            });
-        }
-    }
-    if (progressBar) {
-        progressBar.stop();
+        options.onProgress?.({
+            operation: "download",
+            kind: "transfer",
+            phase: "transferring",
+            label: "Downloading files",
+            current: index + 1,
+            total: files.length,
+            percent: files.length === 0 ? 100 : ((index + 1) / files.length) * 100,
+            unit: "files",
+            status: "running",
+        });
     }
     summary.endTime = Date.now();
     summary.duration = (summary.endTime - summary.startTime) / 1000;
     summary.speed = summary.duration > 0 ? summary.transferSize / summary.duration : 0;
+    options.onProgress?.({
+        operation: "download",
+        kind: "transfer",
+        phase: summary.failedCount === 0 ? "complete" : "failed",
+        label: "Download complete",
+        current: summary.transferredCount,
+        total: summary.totalFiles,
+        percent: summary.totalFiles === 0 ? 100 : (summary.transferredCount / summary.totalFiles) * 100,
+        unit: "files",
+        status: summary.failedCount === 0 ? "done" : "error",
+    });
     return summary;
 }

package/dist/commands/fs/upload.d.ts

@@ -20,6 +20,23 @@ export interface UploadSummary {
     speed: number;
     actualTargetPath: string;
 }
+/** Upload progress fact emitted to callers that want to render progress. */
+export interface UploadProgressEvent {
+    operation: "upload";
+    kind: "transfer";
+    phase: "scanning" | "transferring" | "complete" | "failed";
+    label?: string;
+    current?: number;
+    total?: number;
+    percent?: number;
+    unit?: "files";
+    status?: "running" | "done" | "error";
+}
+/** Options for upload execution. */
+export interface UploadOptions {
+    force?: boolean;
+    onProgress?: (event: UploadProgressEvent) => void;
+}
 /**
  * Formats bytes into human-readable format.
  * @param bytes - Number of bytes.
@@ -37,14 +54,13 @@ export declare function eta_format(seconds: number | null): string;
  */
 export declare function rate_format(rateBytesPerSec: number): string;
 /**
- * Uploads files with a progress bar display.
+ * Uploads files and optionally emits structured progress events.
  * @param localPath - Local path (file or directory).
  * @param remotePath - Remote ChRIS path.
+ * @param options - Upload options, including an optional progress callback.
  * @returns Promise<UploadSummary> with upload statistics.
  */
-export declare function files_uploadWithProgress(localPath: string, remotePath: string, options?: {
-    force?: boolean;
-}): Promise<UploadSummary>;
+export declare function files_uploadWithProgress(localPath: string, remotePath: string, options?: UploadOptions): Promise<UploadSummary>;
 /**
  * Uploads a local file or directory to ChRIS.
  *

package/dist/commands/fs/upload.js

@@ -7,7 +7,6 @@ import { chrisIO } from "@fnndsc/cumin";
 import { path_resolveChrisFs } from "../../utils/cli.js";
 import fs from "fs";
 import path from "path";
-import cliProgress from "cli-progress";
 import chalk from "chalk";
 import { prompt_confirmOrThrow } from "../../utils/input_format.js";
 /**
@@ -101,17 +100,24 @@ async function localFiles_scan(localPath, remotePath) {
     return files;
 }
 /**
- * Uploads files with a progress bar display.
+ * Uploads files and optionally emits structured progress events.
  * @param localPath - Local path (file or directory).
  * @param remotePath - Remote ChRIS path.
+ * @param options - Upload options, including an optional progress callback.
  * @returns Promise<UploadSummary> with upload statistics.
  */
 export async function files_uploadWithProgress(localPath, remotePath, options = {}) {
     const resolvedRemote = await path_resolveChrisFs(remotePath, {});
     // Scan files
     console.log(chalk.cyan("Scanning files to upload..."));
+    options.onProgress?.({
+        operation: "upload",
+        kind: "transfer",
+        phase: "scanning",
+        label: "Scanning files to upload",
+        status: "running",
+    });
     const fileList = await localFiles_scan(localPath, resolvedRemote);
-    const totalSize = fileList.reduce((sum, f) => sum + f.size, 0);
     // Determine actual target path (where files will be uploaded)
     const stats = await fs.promises.stat(localPath);
     let actualTarget = resolvedRemote;
@@ -140,20 +146,6 @@ export async function files_uploadWithProgress(localPath, remotePath, options =
     else {
         // Force mode: if target exists and is a directory, no prompt. If it's a file and we're uploading a single file, proceed.
     }
-    const showProgress = !!process.stdout.isTTY;
-    const progressBar = showProgress
-        ? new cliProgress.SingleBar({
-            format: "Transferring [{bar}] {percentage}% | ETA: {etaHuman} | Rate: {rate} | {value}/{total} files | {bytes}/{totalBytes}",
-        }, cliProgress.Presets.shades_classic)
-        : null;
-    if (progressBar) {
-        progressBar.start(fileList.length, 0, {
-            bytes: "0 B",
-            totalBytes: bytes_format(totalSize),
-            etaHuman: "--",
-            rate: "--",
-        });
-    }
     // Upload files
     const summary = {
         startTime: Date.now(),
@@ -166,6 +158,17 @@ export async function files_uploadWithProgress(localPath, remotePath, options =
         speed: 0,
         actualTargetPath: actualTarget,
     };
+    options.onProgress?.({
+        operation: "upload",
+        kind: "transfer",
+        phase: "transferring",
+        label: "Uploading files",
+        current: 0,
+        total: fileList.length,
+        percent: fileList.length === 0 ? 100 : 0,
+        unit: "files",
+        status: "running",
+    });
     for (const [index, file] of fileList.entries()) {
         try {
             const fileContent = await fs.promises.readFile(file.hostPath);
@@ -188,24 +191,32 @@ export async function files_uploadWithProgress(localPath, remotePath, options =
             summary.failedCount++;
             console.log(chalk.red(`Error uploading ${file.hostPath}: ${error instanceof Error ? error.message : String(error)}`));
         }
-        const elapsedSeconds = Math.max(1e-6, (Date.now() - summary.startTime) / 1000);
-        const rateCurrent = summary.transferSize > 0 ? summary.transferSize / elapsedSeconds : 0;
-        const remainingBytes = Math.max(0, totalSize - summary.transferSize);
-        const etaSeconds = rateCurrent > 0 ? remainingBytes / rateCurrent : null;
-        if (progressBar) {
-            progressBar.update(index + 1, {
-                bytes: bytes_format(summary.transferSize),
-                etaHuman: eta_format(etaSeconds),
-                rate: rate_format(rateCurrent),
-            });
-        }
-    }
-    if (progressBar) {
-        progressBar.stop();
+        options.onProgress?.({
+            operation: "upload",
+            kind: "transfer",
+            phase: "transferring",
+            label: "Uploading files",
+            current: index + 1,
+            total: fileList.length,
+            percent: fileList.length === 0 ? 100 : ((index + 1) / fileList.length) * 100,
+            unit: "files",
+            status: "running",
+        });
     }
     summary.endTime = Date.now();
     summary.duration = (summary.endTime - summary.startTime) / 1000; // seconds
     summary.speed = summary.transferSize / summary.duration; // bytes per second
+    options.onProgress?.({
+        operation: "upload",
+        kind: "transfer",
+        phase: summary.failedCount === 0 ? "complete" : "failed",
+        label: "Upload complete",
+        current: summary.transferredCount,
+        total: summary.totalFiles,
+        percent: summary.totalFiles === 0 ? 100 : (summary.transferredCount / summary.totalFiles) * 100,
+        unit: "files",
+        status: summary.failedCount === 0 ? "done" : "error",
+    });
     return summary;
 }
 /**

package/dist/commands/man/doc.js

@@ -23,7 +23,7 @@ export async function manPage_display(options) {
         return;
     }
     if (options.browser) {
-        browser_open(docPath);
+        await browser_open(docPath);
     }
     else {
         const content = fs.readFileSync(docPath, "utf-8");

package/dist/commands/plugin/readme.js

@@ -11,6 +11,9 @@ import { marked } from "marked";
 import TerminalRenderer from "marked-terminal";
 import chalk from "chalk";
 marked.setOptions({
+    // @ts-expect-error marked-terminal@6 ships .d.ts that drift from marked@9's
+    // Renderer type at this runtime-compatible version pair. (Tracked: align the
+    // marked / marked-terminal versions across chili & chell.)
     renderer: new TerminalRenderer({
         code: chalk.yellow,
         blockquote: chalk.gray.italic,

package/dist/filesystem/fileGroupHandler.d.ts

@@ -25,11 +25,6 @@ export declare class FileGroupHandler {
      * @returns A Promise resolving to a new FileGroupHandler instance.
      */
     static handler_create(assetName: string, path?: string): Promise<FileGroupHandler>;
-    /**
-     * Removes duplicate column headers from FilteredResourceData results.
-     * Copied from BaseGroupHandler to support local listing logic.
-     */
-    private columns_removeDuplicates;
     /**
      * Lists files, links, or directories using the new command logic.
      */

package/dist/filesystem/fileGroupHandler.js

@@ -4,6 +4,7 @@ import { path_resolveChrisFs } from "../utils/cli.js";
 import { FileController } from "../controllers/fileController.js";
 import { files_create } from "../commands/fs/create.js";
 import { errorStack } from "@fnndsc/cumin";
+import { resourceColumns_removeDuplicates } from "../utils/resourceData.js";
 import { table_display } from "../screen/screen.js";
 import { files_fetchList } from "../commands/files/list.js";
 import { fileFields_fetch } from "../commands/files/fields.js";
@@ -41,24 +42,6 @@ export class FileGroupHandler {
             throw new Error(`Failed to initialize FileGroupHandler for ${assetName}: ${errorMessage}`);
         }
     }
-    /**
-     * Removes duplicate column headers from FilteredResourceData results.
-     * Copied from BaseGroupHandler to support local listing logic.
-     */
-    columns_removeDuplicates(results) {
-        const uniqueHeaders = Array.from(new Set(results.selectedFields));
-        const uniqueTableData = results.tableData.map((row) => uniqueHeaders.reduce((acc, header) => {
-            if (typeof header === "string" && header in row) {
-                acc[header] = row[header];
-            }
-            return acc;
-        }, {}));
-        return {
-            ...results,
-            selectedFields: uniqueHeaders,
-            tableData: uniqueTableData,
-        };
-    }
     /**
      * Lists files, links, or directories using the new command logic.
      */
@@ -73,7 +56,7 @@ export class FileGroupHandler {
                 console.log(`No ${this.assetName} found matching the criteria.`);
             }
             else {
-                const uniqueResults = this.columns_removeDuplicates(results);
+                const uniqueResults = resourceColumns_removeDuplicates(results);
                 // cumin returns dynamic table rows (Record<string, unknown>[]);
                 // narrow to the FileResource view model at this boundary.
                 console.log(fileList_render(uniqueResults.tableData, uniqueResults.selectedFields, { table: options.table, csv: options.csv }));

package/dist/handlers/baseGroupHandler.d.ts

@@ -4,7 +4,7 @@
  * @module
  */
 import { Command } from "commander";
-import { ChRISPluginGroup, ChRISFeedGroup, ChRISEmbeddedResourceGroup, ChRISPACSGroup } from "@fnndsc/cumin";
+import { ChRISPluginGroup, ChRISFeedGroup, ChRISEmbeddedResourceGroup, ChRISPACSGroup, type CommandEnvelope } from "@fnndsc/cumin";
 import { CLIoptions } from "../utils/cli.js";
 import { TableOptions } from "../screen/screen.js";
 /**
@@ -16,13 +16,6 @@ export declare class BaseGroupHandler {
     displayOptions: TableOptions;
     chrisObject: ChRISPluginGroup | ChRISFeedGroup | ChRISEmbeddedResourceGroup<unknown> | ChRISPACSGroup;
     constructor(assetName: string, chrisObject: ChRISPluginGroup | ChRISFeedGroup | ChRISEmbeddedResourceGroup<unknown> | ChRISPACSGroup);
-    /**
-     * Removes duplicate column headers from FilteredResourceData results.
-     *
-     * @param results - The FilteredResourceData to process.
-     * @returns FilteredResourceData with unique headers and corresponding data.
-     */
-    private columns_removeDuplicates;
     /**
      * Lists ChRIS resources based on provided CLI options.
      *
@@ -33,6 +26,15 @@ export declare class BaseGroupHandler {
      * Lists available fields for the current ChRIS resource type.
      */
     resourceFields_list(): Promise<void>;
+    /**
+     * Renders available fields for the current ChRIS resource type as an envelope.
+     *
+     * Sans-I/O counterpart to {@link resourceFields_list} — returns the rendered
+     * text instead of printing it, so hosted surfaces can carry it over the wire.
+     *
+     * @returns An envelope carrying the field listing or an error.
+     */
+    resourceFields_render(): Promise<CommandEnvelope>;
     /**
      * Prompts the user for confirmation before performing an operation.
      *

package/dist/handlers/baseGroupHandler.js

@@ -4,9 +4,10 @@
  * @module
  */
 import { Command } from "commander";
-import { ChRISFeedGroup, record_extract, errorStack, } from "@fnndsc/cumin";
+import { ChRISFeedGroup, record_extract, errorStack, envelope_ok, envelope_error, } from "@fnndsc/cumin";
 import { options_toParams } from "../utils/cli.js";
-import { table_display, border_draw } from "../screen/screen.js";
+import { resourceColumns_removeDuplicates } from "../utils/resourceData.js";
+import { table_display, table_render, border_draw } from "../screen/screen.js";
 import * as readline from "readline";
 /**
  * Base handler for groups of ChRIS resources.
@@ -21,26 +22,6 @@ export class BaseGroupHandler {
             title: { title: this.assetName, justification: "center" },
         };
     }
-    /**
-     * Removes duplicate column headers from FilteredResourceData results.
-     *
-     * @param results - The FilteredResourceData to process.
-     * @returns FilteredResourceData with unique headers and corresponding data.
-     */
-    columns_removeDuplicates(results) {
-        const uniqueHeaders = Array.from(new Set(results.selectedFields));
-        const uniqueTableData = results.tableData.map((row) => uniqueHeaders.reduce((acc, header) => {
-            if (typeof header === "string" && header in row) {
-                acc[header] = row[header];
-            }
-            return acc;
-        }, {}));
-        return {
-            ...results,
-            selectedFields: uniqueHeaders,
-            tableData: uniqueTableData,
-        };
-    }
     /**
      * Lists ChRIS resources based on provided CLI options.
      *
@@ -77,7 +58,7 @@ export class BaseGroupHandler {
                 console.log(`No ${this.assetName} found matching the criteria.`);
             }
             else {
-                const uniqueResults = this.columns_removeDuplicates(results);
+                const uniqueResults = resourceColumns_removeDuplicates(results);
                 // Construct column options based on parsed widths
                 const columns = uniqueResults.selectedFields.map(field => {
                     const width = columnWidths[field];
@@ -147,6 +128,30 @@ export class BaseGroupHandler {
             console.log(errorStack.stack_search(this.assetName)[0]);
         }
     }
+    /**
+     * Renders available fields for the current ChRIS resource type as an envelope.
+     *
+     * Sans-I/O counterpart to {@link resourceFields_list} — returns the rendered
+     * text instead of printing it, so hosted surfaces can carry it over the wire.
+     *
+     * @returns An envelope carrying the field listing or an error.
+     */
+    async resourceFields_render() {
+        try {
+            const results = await this.chrisObject.asset.resourceFields_get();
+            if (!results) {
+                return envelope_error('', undefined, `An error occurred while fetching resource fields for ${this.assetName}.\n`);
+            }
+            if (results.fields.length === 0) {
+                return envelope_ok(`No resource fields found for ${this.assetName}.\n`);
+            }
+            return envelope_ok(table_render(results.fields, ["fields"]));
+        }
+        catch (error) {
+            const stacked = errorStack.stack_search(this.assetName)[0];
+            return envelope_error('', undefined, `${stacked ?? String(error)}\n`);
+        }
+    }
     /**
      * Prompts the user for confirmation before performing an operation.
      *

package/dist/index.d.ts

@@ -2,6 +2,11 @@
 /**
  * @file Command-line entry point for the chili (ChILI) CLI.
  *
+ * This is a thin wrapper: all command wiring and execution live in {@link run}
+ * (./run.js) so the same logic can be driven in-process by a host such as chell
+ * without spawning a separate `node` subprocess. This file only adds the
+ * bin-only concerns — shell completion and fatal-exit handling.
+ *
  * @module
  */
-export { logical_toPhysical } from './utils/cli.js';
+export { logical_toPhysical } from "./utils/cli.js";