@fnndsc/chili 3.2.5

package/dist/views/fs.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Renders the result of a mkdir operation.
+ * @param path - The path created.
+ * @param success - Whether the operation succeeded.
+ */
+export declare function mkdir_render(path: string, success: boolean): string;
+/**
+ * Renders the result of a touch operation.
+ * @param path - The path created.
+ * @param success - Whether the operation succeeded.
+ */
+export declare function touch_render(path: string, success: boolean): string;
+/**
+ * Renders the result of an upload operation.
+ * @param local - Local path.
+ * @param remote - Remote path.
+ * @param success - Whether the operation succeeded.
+ */
+export declare function upload_render(local: string, remote: string, success: boolean): string;
+/**
+ * Renders the content of a file or an error message.
+ * @param content - The file content or null if not found/error.
+ * @param path - The file path (for error message).
+ */
+export declare function cat_render(content: string | null, path: string): string;
+/**
+ * Renders the result of a copy operation.
+ * @param src - Source path.
+ * @param dest - Destination path.
+ * @param success - Whether the operation succeeded.
+ */
+export declare function cp_render(src: string, dest: string, success: boolean): string;
+/**
+ * Renders the result of a move operation.
+ * @param src - Source path.
+ * @param dest - Destination path.
+ * @param success - Whether the operation succeeded.
+ */
+export declare function mv_render(src: string, dest: string, success: boolean): string;
+/**
+ * Renders the outcome of an rm operation for terminal display.
+ *
+ * @param result - The rm result.
+ * @returns Formatted status string.
+ */
+export declare function rm_render(result: {
+    success: boolean;
+    path: string;
+    type: 'file' | 'dir' | 'link' | null;
+    error?: string;
+}): string;

package/dist/views/fs.js

@@ -0,0 +1,105 @@
+/**
+ * @file File System View components.
+ *
+ * Provides standard output formatting for file system operations
+ * (mkdir, touch, cat, upload).
+ *
+ * @module
+ */
+import chalk from 'chalk';
+/**
+ * Renders the result of a mkdir operation.
+ * @param path - The path created.
+ * @param success - Whether the operation succeeded.
+ */
+export function mkdir_render(path, success) {
+    if (success) {
+        return chalk.green(`Created directory: ${path}`);
+    }
+    else {
+        return chalk.red(`Failed to create directory: ${path}`);
+    }
+}
+/**
+ * Renders the result of a touch operation.
+ * @param path - The path created.
+ * @param success - Whether the operation succeeded.
+ */
+export function touch_render(path, success) {
+    if (success) {
+        return chalk.green(`Created file: ${path}`);
+    }
+    else {
+        return chalk.red(`Failed to create file: ${path}`);
+    }
+}
+/**
+ * Renders the result of an upload operation.
+ * @param local - Local path.
+ * @param remote - Remote path.
+ * @param success - Whether the operation succeeded.
+ */
+export function upload_render(local, remote, success) {
+    if (success) {
+        return chalk.green(`Successfully uploaded ${local}`);
+    }
+    else {
+        return chalk.red(`Failed to upload ${local}`);
+    }
+}
+/**
+ * Renders the content of a file or an error message.
+ * @param content - The file content or null if not found/error.
+ * @param path - The file path (for error message).
+ */
+export function cat_render(content, path) {
+    if (content !== null) {
+        return content;
+    }
+    else {
+        return chalk.red(`File not found or empty: ${path}`);
+    }
+}
+/**
+ * Renders the result of a copy operation.
+ * @param src - Source path.
+ * @param dest - Destination path.
+ * @param success - Whether the operation succeeded.
+ */
+export function cp_render(src, dest, success) {
+    if (success) {
+        return chalk.green(`Copied ${src} to ${dest}`);
+    }
+    else {
+        return chalk.red(`Failed to copy ${src} to ${dest}`);
+    }
+}
+/**
+ * Renders the result of a move operation.
+ * @param src - Source path.
+ * @param dest - Destination path.
+ * @param success - Whether the operation succeeded.
+ */
+export function mv_render(src, dest, success) {
+    if (success) {
+        return chalk.green(`Moved ${src} to ${dest}`);
+    }
+    else {
+        return chalk.red(`Failed to move ${src} to ${dest}`);
+    }
+}
+/**
+ * Renders the outcome of an rm operation for terminal display.
+ *
+ * @param result - The rm result.
+ * @returns Formatted status string.
+ */
+export function rm_render(result) {
+    if (result.success) {
+        const typeStr = result.type || 'item';
+        return chalk.green(`Removed ${typeStr}: ${result.path}`);
+    }
+    else {
+        return chalk.red(result.error || `Failed to remove: ${result.path}`);
+    }
+}

package/dist/views/ls.d.ts

@@ -0,0 +1,37 @@
+import { ListingItem } from '../models/listing.js';
+/**
+ * Options for the view renderers.
+ */
+export interface ViewOptions {
+    human?: boolean;
+    oneColumn?: boolean;
+    sort?: 'name' | 'size' | 'date' | 'owner';
+    reverse?: boolean;
+}
+/**
+ * Formats bytes into human-readable string.
+ */
+export declare function size_format(bytes: number): string;
+/**
+ * DEPRECATED: Sorts an array of listing items based on specified criteria.
+ * @deprecated Sorting should be done at the command layer, not in views.
+ * @param items - Array of items to sort.
+ * @param sortBy - Field to sort by (default: 'name').
+ * @param reverse - Whether to reverse the sort order.
+ * @returns Sorted array of items.
+ */
+export declare function items_sort(items: ListingItem[], sortBy?: 'name' | 'size' | 'date' | 'owner', reverse?: boolean): ListingItem[];
+/**
+ * Renders the items in a multi-column grid format (standard `ls`).
+ * Note: Items should already be sorted at the command layer.
+ */
+export declare function grid_render(items: ListingItem[], options?: ViewOptions): string;
+/**
+ * Renders the items in a long list format (`ls -l`).
+ * Note: Items should already be sorted at the command layer.
+ */
+export declare function long_render(items: ListingItem[], options?: ViewOptions): string;
+/**
+ * Renders the items as a JSON string.
+ */
+export declare function json_render(items: ListingItem[]): string;

package/dist/views/ls.js

@@ -0,0 +1,190 @@
+/**
+ * @file View layer for the `ls` command.
+ *
+ * Provides different rendering strategies for file listing data:
+ * - Grid: Multi-column standard view.
+ * - Long: Detailed list with metadata (-l).
+ * - JSON: Raw structured data.
+ *
+ * @module
+ */
+import chalk from 'chalk';
+import { fileSystemItem_colorize } from '../config/colorConfig.js';
+/**
+ * Formats bytes into human-readable string.
+ */
+export function size_format(bytes) {
+    if (bytes === 0)
+        return '0 B';
+    const k = 1024;
+    const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return parseFloat((bytes / Math.pow(k, i)).toFixed(1)) + ' ' + sizes[i];
+}
+/**
+ * Formats a resource item name based on its type (color coding).
+ * Uses color configuration from cumin.
+ */
+function name_format(item) {
+    const base = fileSystemItem_colorize(item.name, item.type);
+    // Append / to navigable container types so they're visually distinct from files
+    if (item.type === 'dir' || item.type === 'job') {
+        return base + chalk.cyan.bold('/');
+    }
+    return base;
+}
+/**
+ * Calculates the visible length of a string, stripping ANSI codes.
+ */
+function string_lengthVisible(str) {
+    return str.replace(/\u001b\[[0-9;]*m/g, "").length;
+}
+/**
+ * DEPRECATED: Sorts an array of listing items based on specified criteria.
+ * @deprecated Sorting should be done at the command layer, not in views.
+ * @param items - Array of items to sort.
+ * @param sortBy - Field to sort by (default: 'name').
+ * @param reverse - Whether to reverse the sort order.
+ * @returns Sorted array of items.
+ */
+export function items_sort(items, sortBy = 'name', reverse = false) {
+    const sorted = [...items].sort((a, b) => {
+        let comparison = 0;
+        switch (sortBy) {
+            case 'name':
+                comparison = a.name.localeCompare(b.name);
+                break;
+            case 'size':
+                comparison = a.size - b.size;
+                break;
+            case 'date':
+                comparison = a.date.localeCompare(b.date);
+                break;
+            case 'owner':
+                comparison = a.owner.localeCompare(b.owner);
+                break;
+        }
+        return reverse ? -comparison : comparison;
+    });
+    return sorted;
+}
+/**
+ * Renders the items in a multi-column grid format (standard `ls`).
+ * Note: Items should already be sorted at the command layer.
+ */
+export function grid_render(items, options = {}) {
+    if (items.length === 0)
+        return '';
+    // Legacy sorting support (deprecated - sort at command layer instead)
+    let displayItems = items;
+    if (options.sort) {
+        const sortBy = options.sort;
+        const reverse = options.reverse || false;
+        displayItems = items_sort(items, sortBy, reverse);
+    }
+    const formattedItems = displayItems.map((item) => {
+        let str = name_format(item);
+        if (item.version)
+            str += chalk.dim(` (${item.version})`);
+        return str;
+    });
+    if (options.oneColumn) {
+        return formattedItems.join('\n');
+    }
+    const termWidth = process.stdout.columns || 80;
+    const padding = 2;
+    const maxLen = Math.max(...formattedItems.map(string_lengthVisible));
+    // Cap colWidth at termWidth so padding never causes a terminal line wrap.
+    const colWidth = Math.min(maxLen + padding, termWidth);
+    const cols = Math.max(1, Math.floor(termWidth / colWidth));
+    let output = "";
+    for (let i = 0; i < formattedItems.length; i++) {
+        const item = formattedItems[i];
+        const visibleLen = string_lengthVisible(item);
+        const padLen = Math.max(0, colWidth - visibleLen);
+        output += item + " ".repeat(padLen);
+        if ((i + 1) % cols === 0) {
+            output += "\n";
+        }
+    }
+    return output.trimEnd();
+}
+/**
+ * Renders the items in a long list format (`ls -l`).
+ * Note: Items should already be sorted at the command layer.
+ */
+export function long_render(items, options = {}) {
+    if (items.length === 0)
+        return '';
+    // Legacy sorting support (deprecated - sort at command layer instead)
+    let displayItems = items;
+    if (options.sort) {
+        const sortBy = options.sort;
+        const reverse = options.reverse || false;
+        displayItems = items_sort(items, sortBy, reverse);
+    }
+    // Calculate max name width for alignment
+    const maxNameWidth = Math.max(...displayItems.map((item) => {
+        const nameStr = name_format(item);
+        const visibleLen = string_lengthVisible(nameStr);
+        return item.version ? visibleLen + item.version.length + 3 : visibleLen;
+    }));
+    return displayItems.map((item) => {
+        // Type
+        let typeChar = '-';
+        if (item.type === 'dir')
+            typeChar = 'd';
+        else if (item.type === 'link')
+            typeChar = 'l';
+        else if (item.type === 'plugin')
+            typeChar = 'p';
+        else if (item.type === 'pipeline')
+            typeChar = 'P';
+        else if (item.type === 'vfs')
+            typeChar = 'v';
+        else if (item.type === 'job')
+            typeChar = 'j';
+        // Owner
+        const owner = item.owner.padEnd(10);
+        // Size — for job entries replace with colour-coded status
+        let sizeStr;
+        if (item.type === 'job' && item.status) {
+            const s = item.status;
+            const statusColoured = s === 'finishedSuccessfully' ? chalk.green(s) :
+                s === 'finishedWithError' ? chalk.red(s) :
+                    s === 'cancelled' ? chalk.gray(s) :
+                        s === 'started' || s === 'running' ? chalk.yellow(s) :
+                            chalk.gray(s);
+            sizeStr = statusColoured.padEnd(30);
+        }
+        else {
+            sizeStr = (options.human ? size_format(item.size) : item.size.toString()).padEnd(8);
+        }
+        // Date
+        // Assuming date is ISO, just take the first 19 chars "YYYY-MM-DD HH:mm:ss"
+        const dateStr = item.date.replace('T', ' ').slice(0, 19);
+        // Name
+        let nameStr = name_format(item);
+        if (item.version)
+            nameStr += ` (${item.version})`;
+        // Pad name to max width for alignment
+        const nameVisibleLen = string_lengthVisible(nameStr);
+        const namePadding = ' '.repeat(Math.max(0, maxNameWidth - nameVisibleLen));
+        let line = `${typeChar} ${owner} ${sizeStr} ${dateStr} ${nameStr}${namePadding}`;
+        // Title (for feeds, plugin instances)
+        if (item.title) {
+            line += `    ${chalk.greenBright(item.title)}`;
+        }
+        // Link Target
+        if (item.type === 'link' && item.target) {
+            line += ` -> ${item.target}`;
+        }
+        return line;
+    }).join('\n');
+}
+/**
+ * Renders the items as a JSON string.
+ */
+export function json_render(items) {
+    return JSON.stringify(items, null, 2);
+}

package/dist/views/plugin.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @file View layer for Plugin commands.
+ *
+ * Provides output formatting for plugin listing, execution, and details.
+ *
+ * @module
+ */
+import { Plugin, PluginInstance } from '../models/plugin.js';
+/**
+ * Options for rendering output.
+ */
+export interface OutputOptions {
+    table?: boolean;
+    csv?: boolean;
+}
+/**
+ * Renders the result of a plugin execution.
+ * @param instance - The created plugin instance.
+ * @returns Formatted string.
+ */
+export declare function pluginRun_render(instance: PluginInstance): string;
+/**
+ * Renders a list of plugins.
+ * @param plugins - Array of Plugin objects.
+ * @param selectedFields - The fields to display, in order.
+ * @param options - Output options (e.g., table, csv).
+ */
+export declare function pluginList_render(plugins: Plugin[], selectedFields: string[], options?: OutputOptions): string;

package/dist/views/plugin.js

@@ -0,0 +1,71 @@
+import chalk from 'chalk';
+import { screen } from '../screen/screen.js';
+/**
+ * Renders the result of a plugin execution.
+ * @param instance - The created plugin instance.
+ * @returns Formatted string.
+ */
+export function pluginRun_render(instance) {
+    return chalk.green(`Plugin started successfully.\nInstance ID: ${chalk.bold(instance.id)}\nStatus: ${instance.status}`);
+}
+/**
+ * Renders a list of plugins.
+ * @param plugins - Array of Plugin objects.
+ * @param selectedFields - The fields to display, in order.
+ * @param options - Output options (e.g., table, csv).
+ */
+export function pluginList_render(plugins, selectedFields, options = {}) {
+    if (plugins.length === 0)
+        return chalk.gray("No plugins found.");
+    // Define default fields if none are specified or if the fields are empty
+    const effectiveFields = selectedFields.length > 0 ? selectedFields : ['name', 'version', 'title'];
+    const rows = plugins.map(p => {
+        return effectiveFields.map(field => {
+            const fieldKey = field;
+            const rawValue = p[fieldKey];
+            let value = rawValue !== undefined && rawValue !== null ? String(rawValue) : '';
+            // Apply basic styling for key fields only in non-CSV/non-Table output
+            if (!options.csv && !options.table) {
+                if (field === 'id')
+                    return chalk.bold(value);
+                if (field === 'name')
+                    return chalk.cyan(value);
+            }
+            return value;
+        });
+    });
+    const headerForDisplay = effectiveFields.map(field => field.toUpperCase());
+    if (options.csv) {
+        // CSV format
+        const csvHeader = headerForDisplay.map(h => `"${h}"`).join(',');
+        const csvRows = rows.map(row => row.map(cell => `"${String(cell).split('"').join('""')}"`).join(',')).join('\n');
+        return [csvHeader, csvRows].join('\n');
+    }
+    else if (options.table) {
+        // Prepare data for screen.table_output
+        const tableDataForScreen = plugins.map(plugin => {
+            const row = {};
+            effectiveFields.forEach(field => {
+                const fieldKey = field;
+                const val = plugin[fieldKey];
+                row[field] = val !== undefined && val !== null ? val : '';
+            });
+            return row;
+        });
+        // Pass original effectiveFields as head for correct data mapping, headerForDisplay for title
+        return screen.table_output(tableDataForScreen, {
+            head: effectiveFields,
+            title: { title: "Plugins", justification: "center" },
+            typeColors: {
+                string: "green",
+                number: "yellow",
+                boolean: "cyan",
+                object: "magenta"
+            }
+        });
+    }
+    else {
+        // Default list format (tab-separated)
+        return rows.map(row => row.join('\t')).join('\n');
+    }
+}

package/dist/views/pluginParameters.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @file Renderer for plugin parameter tables in man/help output.
+ *
+ * @module
+ */
+import { FilteredResourceData } from '@fnndsc/cumin';
+/**
+ * Renders plugin parameters in a "man page" style format.
+ *
+ * Format:
+ * [long parameter] [short parameter -- only if different] <value> (default: <default value>)
+ * Type: <type>
+ * [help description]
+ *
+ * @param data - The filtered resource data containing plugin parameters.
+ */
+export declare function pluginParameters_renderMan(data: FilteredResourceData): void;

package/dist/views/pluginParameters.js

@@ -0,0 +1,79 @@
+/**
+ * @file Renderer for plugin parameter tables in man/help output.
+ *
+ * @module
+ */
+import chalk from 'chalk';
+/**
+ * Renders plugin parameters in a "man page" style format.
+ *
+ * Format:
+ * [long parameter] [short parameter -- only if different] <value> (default: <default value>)
+ * Type: <type>
+ * [help description]
+ *
+ * @param data - The filtered resource data containing plugin parameters.
+ */
+export function pluginParameters_renderMan(data) {
+    if (!data.tableData || data.tableData.length === 0) {
+        console.log("No parameters found.");
+        return;
+    }
+    data.tableData.forEach((param) => {
+        // 1. Construct the first line: Flags and Value
+        let line1Parts = [];
+        // Long flag: Display only if name length > 1
+        if (param.name && param.name.length > 1) {
+            line1Parts.push(chalk.bold(`--${param.name}`));
+        }
+        // Short flag: Display only if it exists and is a single character (excluding dashes)
+        // Note: 'param.flag' usually comes with dashes (e.g. '-v').
+        if (param.flag) {
+            const cleanFlag = param.flag.replace(/^-+/, '');
+            if (cleanFlag.length === 1) {
+                // Avoid duplicating if it somehow matches the long flag visual (unlikely given logic)
+                // The prompt says "only if different to long parameter".
+                // Since long parameter is always --name (length > 1) and this is -f (length 1),
+                // they are visually different.
+                line1Parts.push(chalk.bold(param.flag));
+            }
+        }
+        // Value placeholder
+        if (param.action === 'store_true' || param.action === 'store_false') {
+            // Boolean flags usually don't take a value in the signature invocation
+        }
+        else {
+            // Generic value placeholder based on type
+            const valueType = param.type ? `<${param.type}>` : '<value>';
+            line1Parts.push(chalk.cyan(valueType));
+        }
+        // Default value
+        if (param.default !== undefined && param.default !== null && param.default !== "") {
+            line1Parts.push(chalk.gray(`(default: ${param.default})`));
+        }
+        if (line1Parts.length > 0) {
+            console.log(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)'));
+            }
+        }
+        // 2. Type line
+        if (param.type) {
+            console.log(`Type: ${chalk.yellow(param.type)}`);
+        }
+        // 3. Help description
+        if (param.help) {
+            console.log(chalk.white(param.help));
+        }
+        // Separator (newline)
+        console.log('');
+    });
+}

package/docs/00_intro.adoc

@@ -0,0 +1,25 @@
+= intro
+
+== welcome
+
+Welome to the inline `chili` documentation system! This set of documents provides help text for each `chili` command. Additionally several important concepts like _searchable_ and _context_ are discussed.
+
+== how to use
+
+To use this documentation system, simply read it!
+
+== Architectural Goals
+
+The `chili` and `cumin` projects are designed with a clear separation of concerns, with the goal of creating a reusable library of business logic for interacting with ChRIS.
+
+=== The `chili` and `cumin` relationship
+
+*`cumin`* is a "backend" or "runtime" library that is specific to a nodejs environment. It is responsible for all direct interaction with the ChRIS API, as well as managing state, credentials, and access to the local filesystem. It provides a high-level, object-oriented interface over the ChRIS API.
+
+*`chili`* is the "frontend" or business logic library. It is designed to be environment-agnostic. It contains the core logic and workflow for interacting with ChRIS resources, but it does not perform any direct API or filesystem access. Instead, it is designed to be paired with a backend like `cumin`.
+
+This separation allows the `chili` library to be potentially used in other environments, for instance as the logic layer for a future ChRIS web UI, by simply swapping `cumin` with a browser-compatible backend.
+
+=== The Naming Convention
+
+The codebase follows a strict `<object>_<method>` naming convention (e.g., `userNames_get`). This Reverse Polish Notation (RPN) style is designed for high discoverability and grouping of related functions. It is also machine-parsable, which aids in automated tooling and analysis. Further details can be found in the `TYPESCRIPT-STYLE-GUIDE.md` document.

package/docs/01_setup.adoc

@@ -0,0 +1,63 @@
+= Setup Guide
+
+This guide outlines the steps required to build and install `chili` from source.
+
+== Prerequisites: The Kitchen Sink
+
+To cook `chili` without needing `sudo` or running into permission errors (EACCES), we strictly recommend using **NVM (Node Version Manager)**.
+
+### Why NVM?
+The build process (`make meal`) uses `npm link` to symlink the packages globally. On a standard Linux system, the global npm directory is `/usr/lib/node_modules`, which requires root access. `nvm` installs Node.js in your home directory (e.g., `~/.nvm`), allowing you to install and link global packages without `sudo`.
+
+=== 1. Install NVM
+
+If you don't have it yet, install NVM:
+
+[source,bash]
+----
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
+----
+
+Restart your terminal, then install and use the latest Node LTS:
+
+[source,bash]
+----
+nvm install --lts
+nvm use --lts
+----
+
+== Developer Setup
+
+Once NVM is set up, you can use the "Cooking" makefile to handle everything.
+
+=== 1. Clone the Repository
+
+Clone the `chili` repository (and its siblings `cumin` and `salsa` if they are separate, though the Makefile handles cloning them if missing).
+
+[source,bash]
+----
+git clone <repo_url>
+cd chili
+----
+
+=== 2. The Full Meal
+
+Run the all-in-one command to clone dependencies, install packages, build, test, and link everything globally.
+
+[source,bash]
+----
+make meal
+----
+
+If your NVM environment is correct, this will complete successfully, and you will have the `chili` command available in your terminal immediately.
+
+== Verification
+
+To verify the installation, try running the help command:
+
+[source,bash]
+----
+chili --help
+----
+
+You should see the ChILI logo and a list of available commands.