@fnndsc/chili 3.2.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 FNNDSC / BCH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+```
+  ____ _     ___ _     ___
+ / ___| |__ |_ _| |   |_ _|
+| |   | '_ \ | || |    | |
+| |___| | | || || |___ | |
+ \____|_| |_|___|_____|___|
+```
+**ChILI handles Intelligent Line Interactions**
+
+`chili` is both a standalone CLI and a reusable library for interacting with the ChRIS ecosystem. It serves as the controller layer in the ChRIS interface stack, bridging raw business logic (`salsa`) and user presentation.
+
+## Installation
+
+Install globally to use the `chili` command:
+
+```bash
+npm install -g @fnndsc/chili
+chili --help
+```
+
+Requires Node.js ≥ 20.12. See [Quick Start](#quick-start) for usage.
+
+`chili` is also consumed as a library (e.g. by [`chell`](https://github.com/FNNDSC/chell)): its headless **Commands** return typed **Models**, free of presentation concerns.
+
+```bash
+npm install @fnndsc/chili
+```
+
+## Abstract
+
+Designed for developers and power-users who want to script and control a ChRIS instance from the terminal. Maintains a persistent local context: connection details, active user, and current ChRIS working directory survive across invocations.
+
+## Architecture: The Sandwich Model
+
+`chili` implements the controller layer:
+
+1.  **`chili` (Library & CLI)**:
+    *   **Commands (`src/commands`)**: Headless controllers that execute logic via `salsa` and return typed **Models**. Consumed directly by `chell`.
+    *   **Models (`src/models`)**: Explicit interfaces (`Plugin`, `Feed`, `ListingItem`, etc.) defining data structures.
+    *   **Views (`src/views`)**: Pure functions that render Models into formatted strings and tables.
+    *   **CLI (`src/index.ts`)**: Commander.js entry point orchestrating Commands and Views.
+2.  **[`salsa`](https://github.com/FNNDSC/salsa) (Logic)**: Shared Application Logic and Service Assets — high-level business intents.
+3.  **[`cumin`](https://github.com/FNNDSC/cumin) (Infrastructure)**: State and connection layer — authentication, context persistence, low-level API.
+
+## Installation & Development
+
+### Full build (all layers)
+
+```bash
+cd chili
+make meal
+```
+
+### Individual steps
+
+| Target | Action |
+|--------|--------|
+| `make shop` | Clone `cumin` and `salsa` if missing |
+| `make prep` | `npm install` across all packages |
+| `make cook` | Build (compile TypeScript) all packages |
+| `make taste` | Run tests |
+| `make serve` | Link packages globally |
+| `make scrub` | Clean build artifacts and `node_modules` |
+
+> Use [NVM](https://github.com/nvm-sh/nvm) to avoid needing `sudo` for global links.
+
+## Core Features
+
+- **Context-Aware**: Remembers active server, user, and working directory between invocations.
+- **Library Mode**: Exports strictly-typed commands and views consumed by `chell` and other frontends.
+- **Resource Commands**: Full CRUD for plugins, feeds, files, links, pipelines, compute resources, groups, tags, and more.
+- **Plugin Management**: Search, install (from peer store or Docker), and register plugins.
+- **Feed Sub-resources**: Notes and comments on feeds (create, read, update, delete).
+
+## Quick Start
+
+**Connect to ChRIS:**
+```bash
+chili connect <URL> --user <USERNAME> --password <PASSWORD>
+```
+
+**Plugins:**
+```bash
+chili plugins list
+chili plugins list --search "name:pl-dircopy"
+chili plugin run pl-dircopy-v2.1.0 --args "..."
+```
+
+**Feeds:**
+```bash
+chili feeds list
+chili feeds list --user rudolphpienaar
+chili feed note 42
+chili feed comments 42
+```
+
+**Store / plugin install:**
+```bash
+chili plugins add pl-fshack               # auto-discovers compute resources
+chili plugins add pl-fshack --compute ares,argentum
+```
+
+**Files:**
+```bash
+chili files list --path /home/user/uploads
+```
+
+## License
+
+MIT — part of the [ChRIS Project](https://chrisproject.org).
+
+---
+_-30-_

package/dist/chefs/chefs.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @file ChEFS - ChRIS Experimental File System Shell Primitives.
+ *
+ * This module provides basic shell-like commands (`ls`, `cd`, `mkdir`, `touch`, `pwd`)
+ * that operate on the ChRIS filesystem context.
+ *
+ * @module
+ */
+import { Command } from "commander";
+/**
+ * Sets up the 'chefs' command group in Commander.
+ *
+ * @param program - The Commander program instance.
+ */
+export declare function chefsCommand_setup(program: Command): void;

package/dist/chefs/chefs.js

@@ -0,0 +1,195 @@
+import { chrisContext, Context } from "@fnndsc/cumin";
+import { files_list } from '../commands/fs/ls.js';
+import { grid_render, long_render } from '../views/ls.js';
+import { files_mkdir } from '../commands/fs/mkdir.js';
+import { files_touch } from '../commands/fs/touch.js';
+import { files_upload } from '../commands/fs/upload.js';
+import { files_cat } from '../commands/fs/cat.js';
+import { files_rm } from '../commands/fs/rm.js';
+import { files_cp } from '../commands/fs/cp.js';
+import { files_mv } from '../commands/fs/mv.js';
+import { mkdir_render, touch_render, upload_render, cat_render, rm_render, cp_render, mv_render } from '../views/fs.js';
+/**
+ * Lists directory contents.
+ *
+ * @param options - Listing options.
+ * @param pathStr - The path to list.
+ */
+async function chefs_ls(options, pathStr = "") {
+    const items = await files_list(options, pathStr); // Call the core logic
+    if (items.length === 0) {
+        return;
+    }
+    if (options.long) {
+        console.log(long_render(items, { human: !!options.human }));
+    }
+    else {
+        console.log(grid_render(items));
+    }
+}
+/**
+ * Copies a file or directory.
+ *
+ * @param src - Source path.
+ * @param dest - Destination path.
+ * @param options - Copy options.
+ */
+async function chefs_cp(src, dest, options) {
+    const success = await files_cp(src, dest, options);
+    console.log(cp_render(src, dest, success));
+}
+/**
+ * Moves a file or directory.
+ *
+ * @param src - Source path.
+ * @param dest - Destination path.
+ * @param options - Move options.
+ */
+async function chefs_mv(src, dest, _options) {
+    const success = await files_mv(src, dest);
+    console.log(mv_render(src, dest, success));
+}
+/**
+ * Creates a directory.
+ *
+ * @param dirPath - The path of the directory to create.
+ */
+async function chefs_mkdir(dirPath) {
+    const success = await files_mkdir(dirPath);
+    console.log(mkdir_render(dirPath, success));
+}
+/**
+ * Creates an empty file.
+ *
+ * @param filePath - The path of the file to create.
+ */
+async function chefs_touch(filePath) {
+    const success = await files_touch(filePath);
+    console.log(touch_render(filePath, success));
+}
+/**
+ * Uploads a local file or directory to ChRIS.
+ *
+ * @param localPath - Local path.
+ * @param remotePath - Remote ChRIS path.
+ */
+async function chefs_upload(localPath, remotePath) {
+    console.log(`Uploading ${localPath} to ${remotePath}...`);
+    const success = await files_upload(localPath, remotePath);
+    console.log(upload_render(localPath, remotePath, success));
+}
+/**
+ * Changes the current working directory.
+ *
+ * @param path - The path to change to.
+ */
+async function chefs_cd(path) {
+    if (!path) {
+        await chefs_pwd();
+        return;
+    }
+    await chrisContext.current_set(Context.ChRISfolder, path);
+    await chefs_pwd();
+}
+/**
+ * Prints the current working directory.
+ */
+async function chefs_pwd() {
+    const current = await chrisContext.current_get(Context.ChRISfolder);
+    console.log(current || "/");
+}
+/**
+ * Displays file content.
+ *
+ * @param filePath - The path of the file to read.
+ */
+async function chefs_cat(filePath) {
+    const result = await files_cat(filePath);
+    const content = result.ok ? result.value : null;
+    console.log(cat_render(content, filePath));
+}
+/**
+ * Removes a file or directory.
+ *
+ * @param targetPath - The path to remove.
+ * @param options - Options including recursive flag.
+ */
+async function chefs_rm(targetPath, options) {
+    const result = await files_rm(targetPath, options);
+    console.log(rm_render(result));
+}
+/**
+ * Sets up the 'chefs' command group in Commander.
+ *
+ * @param program - The Commander program instance.
+ */
+export function chefsCommand_setup(program) {
+    const chefsCommand = program
+        .command("chefs")
+        .description("Chris Experimental File System - Shell primitives");
+    chefsCommand
+        .command("ls [path]")
+        .description("List filesystem elements (files, dirs, links)")
+        .option("-l, --long", "Long listing format")
+        .option("-h, --human", "Human readable sizes")
+        .action(async (path, options) => {
+        await chefs_ls(options, path || "");
+    });
+    chefsCommand
+        .command("cp <src> <dest>")
+        .description("Copy files or directories")
+        .option("-r, --recursive", "Recursive copy")
+        .action(async (src, dest, options) => {
+        await chefs_cp(src, dest, options);
+    });
+    chefsCommand
+        .command("mv <src> <dest>")
+        .description("Move or rename files or directories")
+        .action(async (src, dest, options) => {
+        await chefs_mv(src, dest, options);
+    });
+    chefsCommand
+        .command("cat <path>")
+        .description("Display file content")
+        .action(async (path) => {
+        await chefs_cat(path);
+    });
+    chefsCommand
+        .command("mkdir <path>")
+        .description("Create a new folder")
+        .action(async (path) => {
+        await chefs_mkdir(path);
+    });
+    chefsCommand
+        .command("touch <path>")
+        .description("Create an empty file")
+        .action(async (path) => {
+        await chefs_touch(path);
+    });
+    chefsCommand
+        .command("upload <local> <remote>")
+        .description("Upload a local file or directory to ChRIS")
+        .action(async (local, remote) => {
+        await chefs_upload(local, remote);
+    });
+    chefsCommand
+        .command("cd [path]")
+        .description("Change current working directory")
+        .action(async (path) => {
+        await chefs_cd(path);
+    });
+    chefsCommand
+        .command("pwd")
+        .description("Print working directory")
+        .action(async () => {
+        await chefs_pwd();
+    });
+    chefsCommand
+        .command("rm <path>")
+        .description("Remove a file or directory")
+        .option("-r, --recursive", "Remove directories and their contents recursively")
+        .option("-f, --force", "Force removal (ignore nonexistent files)")
+        .action(async (path, options) => {
+        await chefs_rm(path, options);
+    });
+}

package/dist/commands/compute/fields.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Fetches the available compute resource field names.
+ *
+ * @returns The compute resource field names, or null on failure.
+ */
+export declare function computeFields_fetch(): Promise<string[] | null>;

package/dist/commands/compute/fields.js

@@ -0,0 +1,13 @@
+/**
+ * @file Fetches available fields for compute resources.
+ * @module
+ */
+import { computeResourceFields_get } from '@fnndsc/salsa';
+/**
+ * Fetches the available compute resource field names.
+ *
+ * @returns The compute resource field names, or null on failure.
+ */
+export async function computeFields_fetch() {
+    return await computeResourceFields_get();
+}

package/dist/commands/compute/list.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @file Implements compute resource listing for ChRIS CUBE.
+ *
+ * @module
+ */
+import { ComputeResource } from '@fnndsc/cumin';
+/**
+ * Result structure for compute resource listing.
+ */
+export interface ComputeListResult {
+    resources: ComputeResource[];
+    selectedFields: string[];
+}
+/**
+ * Fetches all available compute resources from ChRIS CUBE.
+ *
+ * @returns Promise resolving to ComputeListResult.
+ */
+export declare function computeResources_fetchList(): Promise<ComputeListResult>;

package/dist/commands/compute/list.js

@@ -0,0 +1,20 @@
+/**
+ * @file Implements compute resource listing for ChRIS CUBE.
+ *
+ * @module
+ */
+import { computeResources_getAll } from '@fnndsc/cumin';
+/**
+ * Fetches all available compute resources from ChRIS CUBE.
+ *
+ * @returns Promise resolving to ComputeListResult.
+ */
+export async function computeResources_fetchList() {
+    const result = await computeResources_getAll();
+    if (!result.ok)
+        return { resources: [], selectedFields: [] };
+    return {
+        resources: result.value,
+        selectedFields: ['id', 'name', 'compute_url', 'description'],
+    };
+}

package/dist/commands/connect/login.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file Implements the logic for logging into the ChRIS backend.
+ *
+ * This module provides functionality to authenticate the user
+ * with a ChRIS instance.
+ *
+ * @module
+ */
+import { ConnectOptions } from "@fnndsc/salsa";
+/**
+ * Handles the login process.
+ *
+ * @param options - Connection options (url, username, password).
+ * @returns A Promise resolving to true on success, false on failure.
+ */
+export declare function connect_login(options: ConnectOptions): Promise<boolean>;

package/dist/commands/connect/login.js

@@ -0,0 +1,18 @@
+/**
+ * @file Implements the logic for logging into the ChRIS backend.
+ *
+ * This module provides functionality to authenticate the user
+ * with a ChRIS instance.
+ *
+ * @module
+ */
+import { connect_do as salsaConnect_do } from "@fnndsc/salsa";
+/**
+ * Handles the login process.
+ *
+ * @param options - Connection options (url, username, password).
+ * @returns A Promise resolving to true on success, false on failure.
+ */
+export async function connect_login(options) {
+    return await salsaConnect_do(options);
+}

package/dist/commands/connect/logout.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Handles the logout process.
+ *
+ * @returns A Promise resolving to `void`.
+ */
+export declare function connect_logout(): Promise<void>;

package/dist/commands/connect/logout.js

@@ -0,0 +1,16 @@
+/**
+ * @file Implements the logic for logging out from the ChRIS backend.
+ *
+ * This module provides functionality to clear the user's authentication session.
+ *
+ * @module
+ */
+import { logout_do as salsaLogout_do } from "@fnndsc/salsa";
+/**
+ * Handles the logout process.
+ *
+ * @returns A Promise resolving to `void`.
+ */
+export async function connect_logout() {
+    await salsaLogout_do();
+}

package/dist/commands/feed/comments.d.ts

@@ -0,0 +1,41 @@
+import type { FeedComment } from '@fnndsc/salsa';
+import { Result } from '@fnndsc/cumin';
+export type { FeedComment };
+/**
+ * Lists the comments on a feed.
+ *
+ * @param feedId - The feed ID.
+ * @returns Result wrapping the comments.
+ */
+export declare function feed_commentsList(feedId: number): Promise<Result<FeedComment[]>>;
+/**
+ * Creates a comment on a feed.
+ *
+ * @param feedId - The feed ID.
+ * @param data - Comment title and/or content.
+ * @returns Result wrapping the created comment.
+ */
+export declare function feed_commentCreate(feedId: number, data: {
+    title?: string;
+    content?: string;
+}): Promise<Result<FeedComment>>;
+/**
+ * Deletes a feed comment.
+ *
+ * @param feedId - The feed ID.
+ * @param commentId - The comment ID.
+ * @returns Result indicating success.
+ */
+export declare function feed_commentDelete(feedId: number, commentId: number): Promise<Result<boolean>>;
+/**
+ * Updates a feed comment.
+ *
+ * @param feedId - The feed ID.
+ * @param commentId - The comment ID.
+ * @param data - Updated title and/or content.
+ * @returns Result indicating success.
+ */
+export declare function feed_commentUpdate(feedId: number, commentId: number, data: {
+    title?: string;
+    content?: string;
+}): Promise<Result<boolean>>;

package/dist/commands/feed/comments.js

@@ -0,0 +1,45 @@
+/**
+ * @file Feed comments command logic.
+ * @module
+ */
+import { feedComments_list, feedComment_create, feedComment_delete, feedComment_update, } from '@fnndsc/salsa';
+/**
+ * Lists the comments on a feed.
+ *
+ * @param feedId - The feed ID.
+ * @returns Result wrapping the comments.
+ */
+export async function feed_commentsList(feedId) {
+    return feedComments_list(feedId);
+}
+/**
+ * Creates a comment on a feed.
+ *
+ * @param feedId - The feed ID.
+ * @param data - Comment title and/or content.
+ * @returns Result wrapping the created comment.
+ */
+export async function feed_commentCreate(feedId, data) {
+    return feedComment_create(feedId, data);
+}
+/**
+ * Deletes a feed comment.
+ *
+ * @param feedId - The feed ID.
+ * @param commentId - The comment ID.
+ * @returns Result indicating success.
+ */
+export async function feed_commentDelete(feedId, commentId) {
+    return feedComment_delete(feedId, commentId);
+}
+/**
+ * Updates a feed comment.
+ *
+ * @param feedId - The feed ID.
+ * @param commentId - The comment ID.
+ * @param data - Updated title and/or content.
+ * @returns Result indicating success.
+ */
+export async function feed_commentUpdate(feedId, commentId, data) {
+    return feedComment_update(feedId, commentId, data);
+}

package/dist/commands/feed/create.d.ts

@@ -0,0 +1,13 @@
+import { CLIoptions } from "../../utils/cli.js";
+import { Feed } from "../../models/feed.js";
+/**
+ * Creates a new ChRIS feed.
+ *
+ * Parses CLI options to extract feed parameters and input directories,
+ * then invokes the creation process.
+ *
+ * @param options - CLI options including `params` (string) and `dirs` (string or array).
+ * @returns A Promise resolving to a `Feed` object representing the created feed, or `null` on failure.
+ * @throws {Error} If feed parameters cannot be parsed or if directories are missing.
+ */
+export declare function feed_create(options: CLIoptions): Promise<Feed | null>;

package/dist/commands/feed/create.js

@@ -0,0 +1,40 @@
+/**
+ * @file Implements the logic for creating new ChRIS feeds.
+ *
+ * This module provides functionality to create a new feed
+ * from a set of directories and parameters.
+ *
+ * @module
+ */
+import { dictionary_fromCLI } from "@fnndsc/cumin";
+import { feed_create as salsaFeed_create } from "@fnndsc/salsa";
+/**
+ * Creates a new ChRIS feed.
+ *
+ * Parses CLI options to extract feed parameters and input directories,
+ * then invokes the creation process.
+ *
+ * @param options - CLI options including `params` (string) and `dirs` (string or array).
+ * @returns A Promise resolving to a `Feed` object representing the created feed, or `null` on failure.
+ * @throws {Error} If feed parameters cannot be parsed or if directories are missing.
+ */
+export async function feed_create(options) {
+    const params = options.params;
+    const dirs = options.dirs; // Expects a comma-separated string for directories
+    let feedParams = {};
+    if (params) {
+        try {
+            feedParams = dictionary_fromCLI(params);
+        }
+        catch (e) {
+            // Original error handling without errorStack.push
+            throw new Error(`Error parsing feed parameters: ${e}`);
+        }
+    }
+    const dirsArray = typeof dirs === 'string' ? dirs.split(',') : (Array.isArray(dirs) ? dirs : []);
+    if (dirsArray.length === 0) {
+        throw new Error("Directories for feed creation are required (e.g., --dirs '/some/path').");
+    }
+    const result = await salsaFeed_create(dirsArray, feedParams);
+    return result;
+}

package/dist/commands/feed/note.d.ts

@@ -0,0 +1,21 @@
+import type { FeedNote } from '@fnndsc/salsa';
+import { Result } from '@fnndsc/cumin';
+export type { FeedNote };
+/**
+ * Fetches the note for a feed.
+ *
+ * @param feedId - Feed ID.
+ * @returns Result containing note data.
+ */
+export declare function feed_noteGet(feedId: number): Promise<Result<FeedNote>>;
+/**
+ * Updates the note for a feed.
+ *
+ * @param feedId - Feed ID.
+ * @param data - Fields to update.
+ * @returns Result containing true on success.
+ */
+export declare function feed_noteUpdate(feedId: number, data: {
+    title?: string;
+    content?: string;
+}): Promise<Result<boolean>>;

package/dist/commands/feed/note.js

@@ -0,0 +1,24 @@
+/**
+ * @file Feed note command logic.
+ * @module
+ */
+import { feedNote_get, feedNote_update } from '@fnndsc/salsa';
+/**
+ * Fetches the note for a feed.
+ *
+ * @param feedId - Feed ID.
+ * @returns Result containing note data.
+ */
+export async function feed_noteGet(feedId) {
+    return feedNote_get(feedId);
+}
+/**
+ * Updates the note for a feed.
+ *
+ * @param feedId - Feed ID.
+ * @param data - Fields to update.
+ * @returns Result containing true on success.
+ */
+export async function feed_noteUpdate(feedId, data) {
+    return feedNote_update(feedId, data);
+}

package/dist/commands/feeds/delete.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Resolves search terms to a list of feed items.
+ *
+ * @param searchable - The search string.
+ * @returns A Promise resolving to an array of feed items (table data).
+ */
+export declare function feeds_searchByTerm(searchable: string): Promise<Record<string, unknown>[]>;
+/**
+ * Deletes a feed by its ID.
+ *
+ * @param id - The ID of the feed to delete.
+ * @returns A Promise resolving to `true` on success, `false` otherwise.
+ */
+export declare function feed_deleteById(id: number): Promise<boolean>;