@fnndsc/chili 3.3.0 → 3.4.0

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/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";
 /**
@@ -26,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,10 +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 { resourceColumns_removeDuplicates } from "../utils/resourceData.js";
-import { table_display, border_draw } from "../screen/screen.js";
+import { table_display, table_render, border_draw } from "../screen/screen.js";
 import * as readline from "readline";
 /**
  * Base handler for groups of ChRIS resources.
@@ -128,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/plugins/pluginGroupHandler.d.ts

@@ -5,6 +5,7 @@
  */
 import { Command } from "commander";
 import { CLIoptions } from "../utils/cli.js";
+import { type CommandEnvelope } from "@fnndsc/cumin";
 /**
  * Handles commands related to groups of plugin contexts (computes, instances, parameters).
  */
@@ -33,6 +34,23 @@ export declare class PluginContextGroupHandler {
      * Lists available fields for the current plugin context resource.
      */
     parameters_fieldsList(): Promise<void>;
+    /**
+     * Renders plugin parameters in "man page" style as an envelope.
+     *
+     * Sans-I/O counterpart to {@link parameters_listMan}.
+     *
+     * @param options - CLI options for filtering.
+     * @returns An envelope carrying the rendered parameters or an error.
+     */
+    parameters_listManRender(options: CLIoptions): Promise<CommandEnvelope>;
+    /**
+     * Renders available fields for the current plugin context resource as an envelope.
+     *
+     * Sans-I/O counterpart to {@link parameters_fieldsList}.
+     *
+     * @returns An envelope carrying the field listing.
+     */
+    parameters_fieldsRender(): Promise<CommandEnvelope>;
     /**
      * Sets up the Commander.js commands for plugin context group operations.
      *

package/dist/plugins/pluginGroupHandler.js

@@ -6,7 +6,8 @@
 import { BaseGroupHandler } from "../handlers/baseGroupHandler.js";
 import { options_toParams } from "../utils/cli.js";
 import { PluginContextController } from "../controllers/pluginContextController.js";
-import { pluginParameters_renderMan } from "../views/pluginParameters.js";
+import { pluginParameters_renderMan, pluginParameters_manRender } from "../views/pluginParameters.js";
+import { envelope_ok, envelope_error } from "@fnndsc/cumin";
 class InitializationError extends Error {
     constructor(message) {
         super(message);
@@ -76,6 +77,44 @@ export class PluginContextGroupHandler {
             await this.baseGroupHandler.resourceFields_list();
         }
     }
+    /**
+     * Renders plugin parameters in "man page" style as an envelope.
+     *
+     * Sans-I/O counterpart to {@link parameters_listMan}.
+     *
+     * @param options - CLI options for filtering.
+     * @returns An envelope carrying the rendered parameters or an error.
+     */
+    async parameters_listManRender(options) {
+        try {
+            const asset = this.controller.chrisObject.asset;
+            if (!asset || typeof asset.resources_listAndFilterByOptions !== 'function') {
+                return envelope_error('', undefined, "Underlying resource does not support listing.\n");
+            }
+            const params = options_toParams(options);
+            const results = await asset.resources_listAndFilterByOptions(params);
+            if (results) {
+                return envelope_ok(`${pluginParameters_manRender(results)}\n`);
+            }
+            return envelope_ok("No parameters found.\n");
+        }
+        catch (error) {
+            return envelope_error('', undefined, `Error listing parameters: ${error}\n`);
+        }
+    }
+    /**
+     * Renders available fields for the current plugin context resource as an envelope.
+     *
+     * Sans-I/O counterpart to {@link parameters_fieldsList}.
+     *
+     * @returns An envelope carrying the field listing.
+     */
+    async parameters_fieldsRender() {
+        if (this.baseGroupHandler) {
+            return this.baseGroupHandler.resourceFields_render();
+        }
+        return envelope_ok('');
+    }
     /**
      * Sets up the Commander.js commands for plugin context group operations.
      *

package/dist/screen/screen.d.ts

@@ -75,6 +75,19 @@ export declare function border_draw(text: string, borders?: Borders): string;
  * @param options - Optional table display options.
  * @returns The `TableContent` object or null on error.
  */
+/**
+ * Renders a table to a string, the string form of {@link table_display}.
+ *
+ * Envelope-returning callers use this to return their output rather than
+ * printing it; table_display remains the printing form for callers not yet
+ * converted. Returns an empty string when there is no table to render.
+ *
+ * @param tableData - The rows to render.
+ * @param headers - Column headers.
+ * @param options - Table formatting options.
+ * @returns The rendered table (with a trailing newline), or an empty string.
+ */
+export declare function table_render(tableData: TableDataRow[] | string[][] | string[], headers: string[] | string, options?: TableOptions): string;
 export declare function table_display(tableData: TableDataRow[] | string[][] | string[], headers: string[] | string, options?: TableOptions): TableContent | null;
 /**
  * Provides screen utilities for logging and table output.

package/dist/screen/screen.js

@@ -118,6 +118,50 @@ function firstColumnSettings_apply(columns) {
  * @param options - Optional table display options.
  * @returns The `TableContent` object or null on error.
  */
+/**
+ * Renders a table to a string, the string form of {@link table_display}.
+ *
+ * Envelope-returning callers use this to return their output rather than
+ * printing it; table_display remains the printing form for callers not yet
+ * converted. Returns an empty string when there is no table to render.
+ *
+ * @param tableData - The rows to render.
+ * @param headers - Column headers.
+ * @param options - Table formatting options.
+ * @returns The rendered table (with a trailing newline), or an empty string.
+ */
+export function table_render(tableData, headers, options = {}) {
+    const { processedTableData, processedHeaders } = tableInput_process(tableData, headers);
+    const tableObj = tableContent_pack(processedTableData, processedHeaders);
+    if (!tableObj) {
+        return "";
+    }
+    const columns = tableObj.headers.map((_, index) => {
+        const existingCol = options.columns?.[index] || {};
+        return {
+            justification: "left",
+            ...existingCol,
+        };
+    });
+    const updatedColumns = firstColumnSettings_apply(columns);
+    const tableOptions = {
+        ...options,
+        head: processedHeaders,
+        columns: updatedColumns,
+        typeColors: {
+            string: "green",
+            number: "yellow",
+            boolean: "cyan",
+            object: "magenta",
+        },
+    };
+    let out = `${screen.table_output(processedTableData, tableOptions)}\n`;
+    if (options.pagination && options.pagination.shown < options.pagination.total) {
+        const { shown, total } = options.pagination;
+        out += `${chalk.dim(`  ↓ showing ${shown} of ${total}  ·  --all to fetch all  ·  --limit <n> for page size`)}\n`;
+    }
+    return out;
+}
 export function table_display(tableData, headers, options = {}) {
     const { processedTableData, processedHeaders } = tableInput_process(tableData, headers);
     const tableObj = tableContent_pack(processedTableData, processedHeaders);

package/dist/views/pluginParameters.d.ts

@@ -15,3 +15,13 @@ import { FilteredResourceData } from '@fnndsc/cumin';
  * @param data - The filtered resource data containing plugin parameters.
  */
 export declare function pluginParameters_renderMan(data: FilteredResourceData): void;
+/**
+ * Builds the "man page" style rendering of plugin parameters as a string.
+ *
+ * Same format as {@link pluginParameters_renderMan} but returns the text
+ * instead of printing it, so hosted surfaces can carry it in an envelope.
+ *
+ * @param data - The filtered resource data containing plugin parameters.
+ * @returns The rendered parameter listing.
+ */
+export declare function pluginParameters_manRender(data: FilteredResourceData): string;

package/dist/views/pluginParameters.js

@@ -15,10 +15,22 @@ import chalk from 'chalk';
  * @param data - The filtered resource data containing plugin parameters.
  */
 export function pluginParameters_renderMan(data) {
+    console.log(pluginParameters_manRender(data));
+}
+/**
+ * Builds the "man page" style rendering of plugin parameters as a string.
+ *
+ * Same format as {@link pluginParameters_renderMan} but returns the text
+ * instead of printing it, so hosted surfaces can carry it in an envelope.
+ *
+ * @param data - The filtered resource data containing plugin parameters.
+ * @returns The rendered parameter listing.
+ */
+export function pluginParameters_manRender(data) {
     if (!data.tableData || data.tableData.length === 0) {
-        console.log("No parameters found.");
-        return;
+        return "No parameters found.";
     }
+    const lines = [];
     data.tableData.forEach((param) => {
         // 1. Construct the first line: Flags and Value
         let line1Parts = [];
@@ -52,28 +64,23 @@ export function pluginParameters_renderMan(data) {
             line1Parts.push(chalk.gray(`(default: ${param.default})`));
         }
         if (line1Parts.length > 0) {
-            console.log(line1Parts.join(' '));
+            lines.push(line1Parts.join(' '));
         }
-        else {
-            // Fallback if both are suppressed (e.g. name 'v', no flag)?
-            // In strict adherence, we show nothing on line 1, which is weird.
-            // But assuming a valid plugin definition, one of them should appear.
-            // If name is 'v', it implies it should probably have a flag '-v'.
-            // If not, we might want to show '--v' anyway despite the rule, or '-v'.
-            // For safety, if line1 is empty but we have a name, show it as long flag to avoid invisible params.
-            if (param.name) {
-                console.log(chalk.bold(`--${param.name}`) + ' ' + chalk.gray('(implicit)'));
-            }
+        else if (param.name) {
+            // Fallback: if line1 is empty but we have a name, show it as a long flag
+            // to avoid invisible params.
+            lines.push(chalk.bold(`--${param.name}`) + ' ' + chalk.gray('(implicit)'));
         }
         // 2. Type line
         if (param.type) {
-            console.log(`Type: ${chalk.yellow(param.type)}`);
+            lines.push(`Type: ${chalk.yellow(param.type)}`);
         }
         // 3. Help description
         if (param.help) {
-            console.log(chalk.white(param.help));
+            lines.push(chalk.white(param.help));
         }
-        // Separator (newline)
-        console.log('');
+        // Separator (blank line)
+        lines.push('');
     });
+    return lines.join('\n');
 }

package/docs/pacs.adoc

@@ -21,7 +21,7 @@
 == PACS Queries
 
 - **Create**: `chili pacsqueries create "<query>" [--title <title>] [--description <desc>] [--pacsserver <pacs>]`
-  - `<query>` can be JSON (`{"PatientID":"12345"}`) or comma-separated `key:value` pairs (`PatientID:12345,StudyDate:20251003`).
+  - `<query>` can be JSON (`{"PatientID":"12345"}`) or comma-separated `key:value` pairs (`PatientID:12345,StudyDate:20240101`).
   - On success prints: `Created PACS query id=<ID> status=<status> pacs=<pacs> title="<title>"`.
 - **List**: `chili pacsqueries list [--pacsserver <pacs>] [--fields ...] [--table|--csv]`
   - Filters to current/override PACS server. Use `fieldslist` to discover columns.
@@ -64,7 +64,7 @@
 ```bash
 chili context set --pacsserver PACSDCM
 chili pacsservers list --table
-chili pacsqueries create "PatientID:4456554" --title "PID 4456554"
+chili pacsqueries create "PatientID:7654321" --title "PID 7654321"
 chili pacsqueries list --fields id,title,status,pacs_id,query
 chili pacsqueries decode <id>
 ```
@@ -76,7 +76,7 @@ chili pacsqueries decode <id>
 chili context set --pacsserver PACSDCM
 
 # 2. Create query
-chili pacsqueries create "PatientID:4456554" --title "Patient scan"
+chili pacsqueries create "PatientID:7654321" --title "Patient scan"
 # Returns: Created PACS query id=123
 
 # 3. See what's available on PACS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fnndsc/chili",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "ChILI handles Intelligent Line Interactions: A CLI and library for ChRIS, acting as the controller layer for business logic and user presentation.",
   "repository": {
     "type": "git",