@fnndsc/chili 3.4.0 → 3.5.0

package/dist/screen/output.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @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
+ */
+/**
+ * Destination for chili's command output.
+ */
+export interface ChiliWriter {
+    /**
+     * Writes to the output channel with `console.log` semantics.
+     *
+     * @param args - The values to format, exactly as passed to `console.log`.
+     */
+    log(...args: unknown[]): void;
+    /**
+     * Writes to the error channel with `console.error` semantics.
+     *
+     * @param args - The values to format, exactly as passed to `console.error`.
+     */
+    errLog(...args: unknown[]): void;
+    /**
+     * Writes raw text or bytes to the output channel without adding a newline.
+     *
+     * @param chunk - The text or bytes to write.
+     */
+    write(chunk: string | Buffer): void;
+}
+/**
+ * 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 declare function chiliWriter_set(writer: ChiliWriter): ChiliWriter;
+/**
+ * Writes to the output channel with `console.log` semantics.
+ *
+ * @param args - The values to format, exactly as passed to `console.log`.
+ */
+export declare function chiliLog(...args: unknown[]): void;
+/**
+ * Writes to the error channel with `console.error` semantics.
+ *
+ * @param args - The values to format, exactly as passed to `console.error`.
+ */
+export declare function chiliErrLog(...args: unknown[]): void;
+/**
+ * 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 declare function chiliWrite(chunk: string | Buffer): void;
+/**
+ * The text captured from a run, one string per channel.
+ */
+export interface ChiliCaptured {
+    /** Everything written to the output channel. */
+    out: string;
+    /** Everything written to the error channel. */
+    err: string;
+}
+/**
+ * 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 declare function chili_capture(fn: () => Promise<void>): Promise<ChiliCaptured>;

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.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 };
@@ -188,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;
 }
@@ -200,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.
@@ -242,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.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,7 +16,7 @@ import chalk from 'chalk';
  * @param data - The filtered resource data containing plugin parameters.
  */
 export function pluginParameters_renderMan(data) {
-    console.log(pluginParameters_manRender(data));
+    chiliLog(pluginParameters_manRender(data));
 }
 /**
  * Builds the "man page" style rendering of plugin parameters as a string.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fnndsc/chili",
-  "version": "3.4.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",