@fnndsc/chili 3.2.5

package/dist/utils/admin_prompt.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @file Admin Credential Prompting
+ *
+ * Utilities for prompting users for admin credentials when required for plugin
+ * registration operations. Supports both interactive prompting and flag-based
+ * credential provision.
+ *
+ * @module
+ */
+/**
+ * Interface for admin credentials.
+ */
+export interface AdminCredentials {
+    username: string;
+    password: string;
+}
+/**
+ * Registers question functions from the active REPL.
+ * Called by chell's plugin builtin before invoking plugin_add.
+ *
+ * @param askFn - Visible-input question function.
+ * @param askHiddenFn - Hidden-input (password) question function.
+ */
+export declare function adminPrompt_register(askFn: (prompt: string) => Promise<string>, askHiddenFn: (prompt: string) => Promise<string>): void;
+/**
+ * Prompts the user for admin credentials interactively.
+ *
+ * Uses injected REPL question functions when available so the REPL's
+ * readline interface is not duplicated on stdin.
+ *
+ * @param attempt - Current attempt number (for retry logic).
+ * @param maxAttempts - Maximum number of attempts allowed.
+ * @returns Promise resolving to admin credentials, or null if user cancels.
+ */
+export declare function adminCredentials_prompt(attempt?: number, maxAttempts?: number): Promise<AdminCredentials | null>;
+/**
+ * Validates admin credentials by checking if they are non-empty.
+ *
+ * @param credentials - Admin credentials to validate.
+ * @returns True if credentials are valid, false otherwise.
+ */
+export declare function adminCredentials_validate(credentials: AdminCredentials | null): boolean;

package/dist/utils/admin_prompt.js

@@ -0,0 +1,105 @@
+/**
+ * @file Admin Credential Prompting
+ *
+ * Utilities for prompting users for admin credentials when required for plugin
+ * registration operations. Supports both interactive prompting and flag-based
+ * credential provision.
+ *
+ * @module
+ */
+import * as readline from 'readline';
+import { Writable } from 'stream';
+/** Injected by the host (chell) so prompts route through the active readline. */
+let _askFn = null;
+let _askHiddenFn = null;
+/**
+ * Registers question functions from the active REPL.
+ * Called by chell's plugin builtin before invoking plugin_add.
+ *
+ * @param askFn - Visible-input question function.
+ * @param askHiddenFn - Hidden-input (password) question function.
+ */
+export function adminPrompt_register(askFn, askHiddenFn) {
+    _askFn = askFn;
+    _askHiddenFn = askHiddenFn;
+}
+/**
+ * Prompts the user for admin credentials interactively.
+ *
+ * Uses injected REPL question functions when available so the REPL's
+ * readline interface is not duplicated on stdin.
+ *
+ * @param attempt - Current attempt number (for retry logic).
+ * @param maxAttempts - Maximum number of attempts allowed.
+ * @returns Promise resolving to admin credentials, or null if user cancels.
+ */
+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('');
+    }
+    else {
+        console.log(`\nAuthentication failed. Attempt ${attempt} of ${maxAttempts}.`);
+        console.log('');
+    }
+    const askFn = _askFn ?? ask_fallback;
+    const askHiddenFn = _askHiddenFn ?? askHidden_fallback;
+    const username = await askFn('Username: ');
+    if (!username) {
+        console.log('Username cannot be empty.');
+        return null;
+    }
+    const password = await askHiddenFn('Password: ');
+    if (!password) {
+        console.log('Password cannot be empty.');
+        return null;
+    }
+    return { username, password };
+}
+/**
+ * Fallback visible-input prompt (used outside the REPL).
+ */
+function ask_fallback(prompt) {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        rl.question(prompt, (answer) => { rl.close(); resolve(answer.trim()); });
+    });
+}
+/**
+ * Fallback hidden-input prompt (used outside the REPL).
+ */
+function askHidden_fallback(prompt) {
+    return new Promise((resolve) => {
+        const muted = new Writable({
+            write(_chunk, _enc, cb) { cb(); }
+        });
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: muted,
+            terminal: true,
+        });
+        process.stdout.write(prompt);
+        rl.question('', (answer) => {
+            process.stdout.write('\n');
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+/**
+ * Validates admin credentials by checking if they are non-empty.
+ *
+ * @param credentials - Admin credentials to validate.
+ * @returns True if credentials are valid, false otherwise.
+ */
+export function adminCredentials_validate(credentials) {
+    if (!credentials) {
+        return false;
+    }
+    return credentials.username.trim().length > 0 &&
+        credentials.password.trim().length > 0;
+}

package/dist/utils/cli.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @file CLI option helpers: parsing, param conversion, and ChRIS path resolution.
+ *
+ * @module
+ */
+import { ListOptions, Result } from "@fnndsc/cumin";
+/**
+ * Common CLI option flags shared across chili commands.
+ */
+export interface CLIoptions {
+    page?: string;
+    fields?: string;
+    search?: string;
+    params?: string;
+    content?: string;
+    fromFile?: string;
+    path?: string;
+    name?: string;
+    all?: boolean;
+    user?: string;
+    table?: boolean;
+    csv?: boolean;
+    sort?: string;
+    reverse?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Converts CLI options into ChRIS list query parameters.
+ *
+ * @param options - The CLI options.
+ * @param keyPairField - Field treated as the search key-pair.
+ * @returns ListOptions suitable for a ChRIS list query.
+ */
+export declare function options_toParams(options: CLIoptions, keyPairField?: keyof CLIoptions): ListOptions;
+/**
+ * Resolves a ChRIS filesystem path based on various inputs.
+ *
+ * This function builds the logical path from inputs, then converts it to
+ * the physical path where data actually resides (resolving any links).
+ *
+ * @param fileIdentifier - The primary argument, which can be a filename or a path fragment (relative or absolute).
+ * @param options - CLI options including optional `path` (base directory) and `name` (explicit filename).
+ * @returns The fully resolved absolute ChRIS physical path.
+ */
+export declare function path_resolveChrisFs(fileIdentifier: string | undefined, options: {
+    path?: string;
+    name?: string;
+}): Promise<string>;
+/**
+ * Resolves a logical path to its physical path by following links.
+ *
+ * This function delegates to the PathMapper singleton, which uses
+ * hierarchical caching to optimize repeated resolutions with common prefixes.
+ *
+ * Example:
+ *   Logical:  /home/user/public/data
+ *   Where:    public -> /PUBLIC
+ *   Physical: /PUBLIC/data
+ *
+ * @param logicalPath - The logical (apparent) path the user sees/navigates
+ * @returns A Result containing the physical path, or Err if path is invalid
+ */
+export declare function logical_toPhysical(logicalPath: string): Promise<Result<string>>;
+/**
+ * Clears the path mapping cache. Useful when links are created/deleted.
+ */
+export declare function linkCache_clear(): void;

package/dist/utils/cli.js

@@ -0,0 +1,112 @@
+/**
+ * @file CLI option helpers: parsing, param conversion, and ChRIS path resolution.
+ *
+ * @module
+ */
+import { chrisContext, Context, errorStack } from "@fnndsc/cumin";
+import { keyPairParams_apply } from "@fnndsc/cumin";
+import path from "path"; // Node.js path module for joining paths
+import { pathMapper_get } from "../path/pathMapper.js";
+/**
+ * Converts CLI options into ChRIS list query parameters.
+ *
+ * @param options - The CLI options.
+ * @param keyPairField - Field treated as the search key-pair.
+ * @returns ListOptions suitable for a ChRIS list query.
+ */
+export function options_toParams(options, keyPairField = "search") {
+    const baseParams = {
+        limit: options.limit ? Number(options.limit) : (options.page ? parseInt(options.page, 10) : 20),
+        offset: options.offset ? Number(options.offset) : 0,
+        fields: options.fields,
+    };
+    const keyPairValue = options[keyPairField];
+    if (typeof keyPairValue === "string") {
+        return keyPairParams_apply(baseParams, keyPairValue);
+    }
+    return baseParams;
+}
+/**
+ * Resolves a ChRIS filesystem path based on various inputs.
+ *
+ * This function builds the logical path from inputs, then converts it to
+ * the physical path where data actually resides (resolving any links).
+ *
+ * @param fileIdentifier - The primary argument, which can be a filename or a path fragment (relative or absolute).
+ * @param options - CLI options including optional `path` (base directory) and `name` (explicit filename).
+ * @returns The fully resolved absolute ChRIS physical path.
+ */
+export async function path_resolveChrisFs(fileIdentifier, options) {
+    // 1. Build the logical path first
+    let logicalPath;
+    if (fileIdentifier && fileIdentifier.startsWith('/')) {
+        // Absolute path provided
+        logicalPath = fileIdentifier.replace(/\/\//g, '/');
+    }
+    else {
+        // Relative path - determine base directory
+        let baseDir;
+        if (options.path) {
+            baseDir = options.path;
+        }
+        else {
+            const currentContext = await chrisContext.current_get(Context.ChRISfolder);
+            baseDir = currentContext || "/";
+        }
+        if (!baseDir.startsWith('/')) {
+            baseDir = `/${baseDir}`;
+        }
+        // Determine the path fragment to join
+        let pathFragment;
+        if (options.name) {
+            pathFragment = options.name;
+        }
+        else if (fileIdentifier) {
+            pathFragment = fileIdentifier;
+        }
+        else {
+            // No fileIdentifier or name - use current directory as logical path
+            logicalPath = baseDir.replace(/\/\//g, '/');
+            // Convert to physical and return
+            const physicalResult = await logical_toPhysical(logicalPath);
+            if (!physicalResult.ok) {
+                errorStack.stack_push('error', 'Failed to resolve current directory to physical location');
+                return logicalPath; // Fallback to logical
+            }
+            return physicalResult.value;
+        }
+        logicalPath = path.posix.join(baseDir, pathFragment).replace(/\/\/\//g, '/');
+    }
+    // 2. Convert logical path to physical path
+    const physicalResult = await logical_toPhysical(logicalPath);
+    if (!physicalResult.ok) {
+        errorStack.stack_push('error', `Failed to resolve logical path '${logicalPath}' to physical location`);
+        return logicalPath; // Fallback to using logical path directly
+    }
+    return physicalResult.value;
+}
+/**
+ * Resolves a logical path to its physical path by following links.
+ *
+ * This function delegates to the PathMapper singleton, which uses
+ * hierarchical caching to optimize repeated resolutions with common prefixes.
+ *
+ * Example:
+ *   Logical:  /home/user/public/data
+ *   Where:    public -> /PUBLIC
+ *   Physical: /PUBLIC/data
+ *
+ * @param logicalPath - The logical (apparent) path the user sees/navigates
+ * @returns A Result containing the physical path, or Err if path is invalid
+ */
+export async function logical_toPhysical(logicalPath) {
+    const mapper = pathMapper_get();
+    return mapper.logical_toPhysical(logicalPath);
+}
+/**
+ * Clears the path mapping cache. Useful when links are created/deleted.
+ */
+export function linkCache_clear() {
+    const mapper = pathMapper_get();
+    mapper.cache_clear();
+}

package/dist/utils/docker.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Promisified version of child_process.exec.
+ * @param command - The command string to execute.
+ * @returns A Promise that resolves with { stdout, stderr }.
+ */
+export declare function childProcess_exec(command: string): Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * Executes a shell command and returns its stdout.
+ * @param command - The command to execute.
+ * @returns The stdout of the command, or null if an error occurred.
+ */
+export declare function shellCommand_run(command: string): Promise<string | null>;
+/**
+ * Executes a shell command and returns detailed result including stderr.
+ *
+ * @param command - The command to execute.
+ * @returns Object with stdout, stderr, and success status.
+ */
+export declare function shellCommand_runWithDetails(command: string): Promise<{
+    stdout: string;
+    stderr: string;
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Checks if Docker is installed and running.
+ * @returns True if Docker is available, false otherwise.
+ */
+export declare function docker_checkAvailability(): Promise<boolean>;
+/**
+ * Checks if a Docker image exists locally.
+ *
+ * @param image - The Docker image name/tag to check (e.g., 'fnndsc/pl-dircopy:2.1.1').
+ * @returns Promise resolving to true if image exists locally, false otherwise.
+ *
+ * @example
+ * ```typescript
+ * const exists = await docker_imageExistsLocally('fnndsc/pl-dircopy:2.1.1');
+ * if (!exists) {
+ *   await docker_pullImage('fnndsc/pl-dircopy:2.1.1');
+ * }
+ * ```
+ */
+export declare function docker_imageExistsLocally(image: string): Promise<boolean>;
+/**
+ * Pulls a Docker image from a registry.
+ *
+ * Checks if image exists locally first. If it exists, skips pull.
+ * Output is suppressed for CLI use (use --quiet flag).
+ *
+ * @param image - The Docker image name/tag to pull.
+ * @param quiet - Whether to suppress verbose output (default: true for CLI).
+ * @returns Promise resolving to true if pull succeeded or image already exists, false otherwise.
+ */
+export declare function docker_pullImage(image: string, quiet?: boolean): Promise<boolean>;
+/**
+ * Gets the CMD directive from a Docker image.
+ *
+ * Inspects the Docker image configuration to extract the default command.
+ * This is useful for running plugins that don't have chris_plugin_info.
+ *
+ * @param image - The Docker image name/tag.
+ * @returns Promise resolving to array of command parts, or empty array if not found.
+ *
+ * @example
+ * ```typescript
+ * const cmd = await docker_getImageCmd('fnndsc/pl-civet:2.1.1.3');
+ * // Returns: ['civet.py'] or similar
+ * ```
+ */
+export declare function docker_getImageCmd(image: string): Promise<string[]>;

package/dist/utils/docker.js

@@ -0,0 +1,155 @@
+/**
+ * @file Docker utility functions.
+ *
+ * This module provides helper functions for interacting with the Docker CLI,
+ * such as checking availability and running commands.
+ *
+ * @module
+ */
+import { exec } from "child_process";
+/**
+ * Promisified version of child_process.exec.
+ * @param command - The command string to execute.
+ * @returns A Promise that resolves with { stdout, stderr }.
+ */
+export async function childProcess_exec(command) {
+    return new Promise((resolve, reject) => {
+        exec(command, (error, stdout, stderr) => {
+            if (error) {
+                reject(error);
+            }
+            else {
+                resolve({ stdout, stderr });
+            }
+        });
+    });
+}
+/**
+ * Executes a shell command and returns its stdout.
+ * @param command - The command to execute.
+ * @returns The stdout of the command, or null if an error occurred.
+ */
+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
+        }
+        return stdout.trim();
+    }
+    catch (error) {
+        // console.error(`Command failed: ${command}`);
+        // console.error(`Error: ${error.message}`);
+        return null;
+    }
+}
+/**
+ * Executes a shell command and returns detailed result including stderr.
+ *
+ * @param command - The command to execute.
+ * @returns Object with stdout, stderr, and success status.
+ */
+export async function shellCommand_runWithDetails(command) {
+    try {
+        const { stdout, stderr } = await childProcess_exec(command);
+        return {
+            stdout: stdout.trim(),
+            stderr: stderr.trim(),
+            success: true,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            stdout: '',
+            stderr: '',
+            success: false,
+            error: errorMessage,
+        };
+    }
+}
+/**
+ * Checks if Docker is installed and running.
+ * @returns True if Docker is available, false otherwise.
+ */
+export async function docker_checkAvailability() {
+    const result = await shellCommand_run("docker info > /dev/null 2>&1 && echo OK");
+    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.");
+    return false;
+}
+/**
+ * Checks if a Docker image exists locally.
+ *
+ * @param image - The Docker image name/tag to check (e.g., 'fnndsc/pl-dircopy:2.1.1').
+ * @returns Promise resolving to true if image exists locally, false otherwise.
+ *
+ * @example
+ * ```typescript
+ * const exists = await docker_imageExistsLocally('fnndsc/pl-dircopy:2.1.1');
+ * if (!exists) {
+ *   await docker_pullImage('fnndsc/pl-dircopy:2.1.1');
+ * }
+ * ```
+ */
+export async function docker_imageExistsLocally(image) {
+    const result = await shellCommand_run(`docker images -q ${image} 2>/dev/null`);
+    return result !== null && result.trim().length > 0;
+}
+/**
+ * Pulls a Docker image from a registry.
+ *
+ * Checks if image exists locally first. If it exists, skips pull.
+ * Output is suppressed for CLI use (use --quiet flag).
+ *
+ * @param image - The Docker image name/tag to pull.
+ * @param quiet - Whether to suppress verbose output (default: true for CLI).
+ * @returns Promise resolving to true if pull succeeded or image already exists, false otherwise.
+ */
+export async function docker_pullImage(image, quiet = true) {
+    const existsLocally = await docker_imageExistsLocally(image);
+    if (existsLocally) {
+        console.log(`Docker image ${image} already exists locally.`);
+        return true;
+    }
+    console.log(`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}`);
+        return true;
+    }
+    console.error(`Failed to pull Docker image: ${image}`);
+    return false;
+}
+/**
+ * Gets the CMD directive from a Docker image.
+ *
+ * Inspects the Docker image configuration to extract the default command.
+ * This is useful for running plugins that don't have chris_plugin_info.
+ *
+ * @param image - The Docker image name/tag.
+ * @returns Promise resolving to array of command parts, or empty array if not found.
+ *
+ * @example
+ * ```typescript
+ * const cmd = await docker_getImageCmd('fnndsc/pl-civet:2.1.1.3');
+ * // Returns: ['civet.py'] or similar
+ * ```
+ */
+export async function docker_getImageCmd(image) {
+    const result = await shellCommand_run(`docker inspect --format='{{json .Config.Cmd}}' ${image} 2>/dev/null`);
+    if (!result || result.trim() === '' || result === 'null') {
+        return [];
+    }
+    try {
+        const cmd = JSON.parse(result);
+        return Array.isArray(cmd) ? cmd : [];
+    }
+    catch {
+        return [];
+    }
+}

package/dist/utils/input_format.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @file Input Format Detection
+ *
+ * Utilities for detecting the format of plugin input strings (name, Docker image, or store URL).
+ * Used by plugin_add to determine the appropriate registration strategy.
+ *
+ * @module
+ */
+/**
+ * Recognized input formats for plugin add (e.g. docker image, source URL).
+ */
+export declare enum PluginInputFormat {
+    PLUGIN_NAME = "plugin_name",
+    DOCKER_IMAGE = "docker_image",
+    STORE_URL = "store_url"
+}
+/**
+ * Interface describing the detected input format.
+ */
+export interface DetectedFormat {
+    format: PluginInputFormat;
+    value: string;
+    pluginName?: string;
+    version?: string;
+}
+/**
+ * Detects the format of a plugin input string.
+ *
+ * Determines whether the input is:
+ * - A store URL (starts with http:// or https://)
+ * - A Docker image (contains / or :)
+ * - A plugin name (everything else)
+ *
+ * @param input - The plugin input string to analyze.
+ * @returns DetectedFormat object describing the input type.
+ *
+ * @example
+ * ```typescript
+ * input_detectFormat('pl-dircopy')
+ * // { format: 'plugin_name', value: 'pl-dircopy' }
+ *
+ * input_detectFormat('fnndsc/pl-dircopy:2.1.1')
+ * // { format: 'docker_image', value: 'fnndsc/pl-dircopy:2.1.1', pluginName: 'pl-dircopy', version: '2.1.1' }
+ *
+ * input_detectFormat('https://cube.chrisproject.org/api/v1/plugins/96/')
+ * // { format: 'store_url', value: 'https://...' }
+ * ```
+ */
+export declare function input_detectFormat(input: string): DetectedFormat;
+/**
+ * Extracts a plugin name and version from a Docker image string.
+ *
+ * Examples:
+ *   'fnndsc/pl-dircopy:2.1.1' -> { name: 'pl-dircopy', version: '2.1.1' }
+ *   'fnndsc/pl-dircopy' -> { name: 'pl-dircopy', version: undefined }
+ *   'pl-dircopy:latest' -> { name: 'pl-dircopy', version: 'latest' }
+ *
+ * @param dockerImage - Docker image string.
+ * @returns Object containing extracted plugin name and optional version.
+ */
+export declare function pluginNameAndVersion_extractFromImage(dockerImage: string): {
+    name: string;
+    version?: string;
+};
+/**
+ * Backward-compatible helper to extract only the plugin name from a Docker image.
+ *
+ * @param dockerImage - Docker image string.
+ * @returns The extracted plugin name.
+ */
+export declare function pluginName_extractFromImage(dockerImage: string): string;
+/**
+ * Prompts the user for confirmation. Throws if declined or if prompt cannot be shown (non-TTY) without force.
+ *
+ * @param message - The confirmation message to display.
+ */
+export declare function prompt_confirmOrThrow(message: string): Promise<void>;