@fnndsc/chili 3.3.0 → 3.5.0

package/dist/screen/output.js

@@ -0,0 +1,95 @@
+/**
+ * @file chili's output seam.
+ *
+ * chili historically printed straight to `console.log`/`console.error`, which
+ * fused its command layer to a terminal and forced any in-process host (the
+ * brasa engine, which drives chili headless) to capture output with a console
+ * monkeypatch. This seam inverts that: command output is written to whatever
+ * writer is installed, and by default that writer simply delegates to the
+ * process console — so chili's standalone CLI behaves exactly as it always has.
+ *
+ * A host captures a run's output with {@link chili_capture}, which swaps in a
+ * buffering writer for the duration of a call and returns the collected text.
+ * This is explicit dependency injection through a module seam, not a runtime
+ * override of the global `console`: the default writer calls `console.log`
+ * normally, and capture bypasses the console entirely.
+ *
+ * @module
+ */
+import { format } from "util";
+/**
+ * The default writer: delegates to the process console. Installed at import so
+ * the standalone CLI prints exactly as before.
+ */
+const consoleWriter = {
+    log: (...args) => { console.log(...args); },
+    errLog: (...args) => { console.error(...args); },
+    write: (chunk) => { process.stdout.write(chunk); },
+};
+/** The writer in effect. Swapped for the duration of a captured run. */
+let activeWriter = consoleWriter;
+/**
+ * Installs a writer as the active output destination.
+ *
+ * @param writer - The writer to install.
+ * @returns The previously installed writer, so callers can restore it.
+ */
+export function chiliWriter_set(writer) {
+    const previous = activeWriter;
+    activeWriter = writer;
+    return previous;
+}
+/**
+ * Writes to the output channel with `console.log` semantics.
+ *
+ * @param args - The values to format, exactly as passed to `console.log`.
+ */
+export function chiliLog(...args) {
+    activeWriter.log(...args);
+}
+/**
+ * Writes to the error channel with `console.error` semantics.
+ *
+ * @param args - The values to format, exactly as passed to `console.error`.
+ */
+export function chiliErrLog(...args) {
+    activeWriter.errLog(...args);
+}
+/**
+ * Writes raw text or bytes to the output channel without adding a newline —
+ * the replacement for direct `process.stdout.write` calls.
+ *
+ * @param chunk - The text or bytes to write.
+ */
+export function chiliWrite(chunk) {
+    activeWriter.write(chunk);
+}
+/**
+ * Runs `fn` with both channels captured into memory and returns the collected
+ * text, restoring the previous writer afterwards even if `fn` throws.
+ *
+ * Formatting matches `console.log`: arguments are rendered with `util.format`
+ * and each `log`/`errLog` call contributes a trailing newline, exactly as the
+ * console would have written.
+ *
+ * @param fn - The work whose output should be captured.
+ * @returns The captured output and error text.
+ */
+export async function chili_capture(fn) {
+    const outChunks = [];
+    const errChunks = [];
+    const previous = chiliWriter_set({
+        log: (...args) => { outChunks.push(`${format(...args)}\n`); },
+        errLog: (...args) => { errChunks.push(`${format(...args)}\n`); },
+        write: (chunk) => {
+            outChunks.push(typeof chunk === "string" ? chunk : chunk.toString("utf-8"));
+        },
+    });
+    try {
+        await fn();
+    }
+    finally {
+        chiliWriter_set(previous);
+    }
+    return { out: outChunks.join(""), err: errChunks.join("") };
+}

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

@@ -5,6 +5,7 @@
  */
 import { table, getBorderCharacters } from "table";
 import chalk from "chalk";
+import { chiliLog, chiliErrLog } from "./output.js";
 /**
  * Processes raw table input data and headers into a standardized format.
  *
@@ -60,7 +61,7 @@ function tableContent_pack(tableData, selectedFields) {
         body = tableData.map((row) => headers.map((field) => (row[field] !== undefined ? row[field] : "")));
     }
     else {
-        console.error("Invalid table data");
+        chiliErrLog("Invalid table data");
         return null;
     }
     return { headers, body };
@@ -118,6 +119,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);
@@ -144,10 +189,10 @@ export function table_display(tableData, headers, options = {}) {
         },
     };
     const result = screen.table_output(processedTableData, tableOptions);
-    console.log(result);
+    chiliLog(result);
     if (options.pagination && options.pagination.shown < options.pagination.total) {
         const { shown, total } = options.pagination;
-        console.log(chalk.dim(`  ↓ showing ${shown} of ${total}  ·  --all to fetch all  ·  --limit <n> for page size`));
+        chiliLog(chalk.dim(`  ↓ showing ${shown} of ${total}  ·  --all to fetch all  ·  --limit <n> for page size`));
     }
     return tableObj;
 }
@@ -156,16 +201,16 @@ export function table_display(tableData, headers, options = {}) {
  */
 export class Screen {
     log(...args) {
-        console.log(...args);
+        chiliLog(...args);
     }
     error(...args) {
-        console.error(chalk.red(...args));
+        chiliErrLog(chalk.red(...args));
     }
     warn(...args) {
-        console.warn(chalk.yellow(...args));
+        chiliErrLog(chalk.yellow(...args));
     }
     info(...args) {
-        console.info(chalk.blue(...args));
+        chiliLog(chalk.blue(...args));
     }
     /**
      * Generates a formatted table output string.
@@ -198,7 +243,7 @@ export class Screen {
                 : output;
         }
         catch (error) {
-            console.error("Error in table_output method:", error);
+            chiliErrLog("Error in table_output method:", error);
             return "Error generating table";
         }
     }

package/dist/utils/admin_prompt.js

@@ -9,6 +9,7 @@
  */
 import * as readline from 'readline';
 import { Writable } from 'stream';
+import { chiliLog, chiliWrite } from "../screen/output.js";
 /** Injected by the host (chell) so prompts route through the active readline. */
 let _askFn = null;
 let _askHiddenFn = null;
@@ -35,24 +36,24 @@ export function adminPrompt_register(askFn, askHiddenFn) {
  */
 export async function adminCredentials_prompt(attempt = 1, maxAttempts = 3) {
     if (attempt === 1) {
-        console.log('\nAdmin credentials required to register plugins.');
-        console.log('You can provide these via --adminUser and --adminPassword flags.');
-        console.log('');
+        chiliLog('\nAdmin credentials required to register plugins.');
+        chiliLog('You can provide these via --adminUser and --adminPassword flags.');
+        chiliLog('');
     }
     else {
-        console.log(`\nAuthentication failed. Attempt ${attempt} of ${maxAttempts}.`);
-        console.log('');
+        chiliLog(`\nAuthentication failed. Attempt ${attempt} of ${maxAttempts}.`);
+        chiliLog('');
     }
     const askFn = _askFn ?? ask_fallback;
     const askHiddenFn = _askHiddenFn ?? askHidden_fallback;
     const username = await askFn('Username: ');
     if (!username) {
-        console.log('Username cannot be empty.');
+        chiliLog('Username cannot be empty.');
         return null;
     }
     const password = await askHiddenFn('Password: ');
     if (!password) {
-        console.log('Password cannot be empty.');
+        chiliLog('Password cannot be empty.');
         return null;
     }
     return { username, password };
@@ -82,9 +83,9 @@ function askHidden_fallback(prompt) {
             output: muted,
             terminal: true,
         });
-        process.stdout.write(prompt);
+        chiliWrite(prompt);
         rl.question('', (answer) => {
-            process.stdout.write('\n');
+            chiliWrite('\n');
             rl.close();
             resolve(answer.trim());
         });

package/dist/utils/docker.js

@@ -7,6 +7,7 @@
  * @module
  */
 import { exec } from "child_process";
+import { chiliErrLog, chiliLog } from "../screen/output.js";
 /**
  * Promisified version of child_process.exec.
  * @param command - The command string to execute.
@@ -33,13 +34,13 @@ export async function shellCommand_run(command) {
     try {
         const { stdout, stderr } = await childProcess_exec(command);
         if (stderr) {
-            // console.warn(`Command stderr: ${stderr.trim()}`); // Log stderr as warning, not necessarily an error
+            // chiliErrLog(`Command stderr: ${stderr.trim()}`); // Log stderr as warning, not necessarily an error
         }
         return stdout.trim();
     }
     catch (error) {
-        // console.error(`Command failed: ${command}`);
-        // console.error(`Error: ${error.message}`);
+        // chiliErrLog(`Command failed: ${command}`);
+        // chiliErrLog(`Error: ${error.message}`);
         return null;
     }
 }
@@ -77,8 +78,8 @@ export async function docker_checkAvailability() {
     if (result === "OK") {
         return true;
     }
-    console.error("Error: Docker is not installed or not running.");
-    console.error("Please ensure Docker is properly set up on your system to add plugins.");
+    chiliErrLog("Error: Docker is not installed or not running.");
+    chiliErrLog("Please ensure Docker is properly set up on your system to add plugins.");
     return false;
 }
 /**
@@ -112,17 +113,17 @@ export async function docker_imageExistsLocally(image) {
 export async function docker_pullImage(image, quiet = true) {
     const existsLocally = await docker_imageExistsLocally(image);
     if (existsLocally) {
-        console.log(`Docker image ${image} already exists locally.`);
+        chiliLog(`Docker image ${image} already exists locally.`);
         return true;
     }
-    console.log(`Pulling Docker image: ${image}...`);
+    chiliLog(`Pulling Docker image: ${image}...`);
     const quietFlag = quiet ? '--quiet' : '';
     const result = await shellCommand_run(`docker pull ${quietFlag} ${image}`);
     if (result !== null) {
-        console.log(`Successfully pulled ${image}`);
+        chiliLog(`Successfully pulled ${image}`);
         return true;
     }
-    console.error(`Failed to pull Docker image: ${image}`);
+    chiliErrLog(`Failed to pull Docker image: ${image}`);
     return false;
 }
 /**

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

@@ -4,6 +4,7 @@
  * @module
  */
 import chalk from 'chalk';
+import { chiliLog } from "../screen/output.js";
 /**
  * Renders plugin parameters in a "man page" style format.
  *
@@ -15,10 +16,22 @@ import chalk from 'chalk';
  * @param data - The filtered resource data containing plugin parameters.
  */
 export function pluginParameters_renderMan(data) {
+    chiliLog(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 +65,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.5.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",