@fnndsc/chili 3.2.5

package/dist/commands/fs/download.js

@@ -0,0 +1,235 @@
+/**
+ * @file Download command implementation.
+ * @module
+ */
+import { fileContent_getBinaryStream, files_listRecursive } from "@fnndsc/salsa";
+import { path_resolveChrisFs } from "../../utils/cli.js";
+import fs from "fs";
+import path from "path";
+import cliProgress from "cli-progress";
+import chalk from "chalk";
+import { pipeline } from "stream/promises";
+import { bytes_format, eta_format, rate_format } from "./upload.js";
+import { prompt_confirmOrThrow } from "../../utils/input_format.js";
+export { bytes_format };
+/**
+ * Recursively creates a directory and all parent directories.
+ * @param dirPath - Directory path to create.
+ */
+async function directory_ensureExists(dirPath) {
+    await fs.promises.mkdir(dirPath, { recursive: true });
+}
+/**
+ * Checks if a ChRIS path is a directory by attempting to list it.
+ * @param chrisPath - ChRIS path to check.
+ * @returns True if it's a directory, false if it's a file.
+ */
+async function chrisPath_isDirectory(chrisPath) {
+    try {
+        // Try to list it - if it succeeds, it's a directory
+        const items = await files_listRecursive(chrisPath);
+        return items.length > 0 || chrisPath.endsWith('/');
+    }
+    catch {
+        // If listing fails, assume it's a file
+        return false;
+    }
+}
+/**
+ * Downloads files from ChRIS with a progress bar display.
+ * @param chrisPath - Remote ChRIS path (file or directory).
+ * @param localPath - Local filesystem path.
+ * @param options - Download options.
+ * @returns Promise<DownloadSummary> with download statistics.
+ */
+export async function files_downloadWithProgress(chrisPath, localPath, options = {}) {
+    const resolvedChris = await path_resolveChrisFs(chrisPath, {});
+    // Check if local path exists (only block overwriting regular files unless force)
+    if (fs.existsSync(localPath)) {
+        const localStat = await fs.promises.stat(localPath);
+        if (localStat.isFile() && !options.force) {
+            throw new Error(`Local path already exists: ${localPath}. Use -f flag to overwrite.`);
+        }
+        // If it's a directory, allow and handle below.
+    }
+    const summary = {
+        startTime: Date.now(),
+        endTime: 0,
+        totalFiles: 0,
+        transferredCount: 0,
+        failedCount: 0,
+        transferSize: 0,
+        duration: 0,
+        speed: 0,
+    };
+    const isDirectory = await chrisPath_isDirectory(resolvedChris);
+    if (!isDirectory) {
+        // Download single file
+        try {
+            const result = await fileContent_getBinaryStream(resolvedChris);
+            if (!result.ok) {
+                throw new Error("Failed to download file");
+            }
+            const { stream, size } = result.value;
+            // If localPath is a directory, place the file inside using remote basename
+            const stats = fs.existsSync(localPath) ? await fs.promises.stat(localPath) : null;
+            const finalLocalPath = stats && stats.isDirectory()
+                ? path.join(localPath, path.basename(resolvedChris))
+                : localPath;
+            // Warn if target file already exists (non-overwrite) or directory already exists
+            if (fs.existsSync(finalLocalPath)) {
+                const existingStat = await fs.promises.stat(finalLocalPath);
+                if (existingStat.isFile()) {
+                    if (!options.force) {
+                        await prompt_confirmOrThrow(`Local file exists at ${finalLocalPath}. Overwrite? (y/N)`);
+                    }
+                }
+                else if (existingStat.isDirectory()) {
+                    if (!options.force) {
+                        await prompt_confirmOrThrow(`Target directory exists. Download into existing folder: ${finalLocalPath}? (y/N)`);
+                    }
+                }
+            }
+            // Ensure parent directory exists
+            const parentDir = path.dirname(finalLocalPath);
+            await directory_ensureExists(parentDir);
+            const showProgress = !!process.stdout.isTTY;
+            const progressBar = typeof size === "number" && showProgress
+                ? new cliProgress.SingleBar({
+                    format: "Downloading [{bar}] {percentage}% | ETA: {etaHuman} | Rate: {rate} | {bytes}/{totalBytes}",
+                }, cliProgress.Presets.shades_classic)
+                : null;
+            if (progressBar) {
+                progressBar.start(size, 0, {
+                    etaHuman: "--",
+                    rate: "--",
+                    bytes: bytes_format(0),
+                    totalBytes: bytes_format(size),
+                });
+            }
+            let transferred = 0;
+            const writeStream = fs.createWriteStream(finalLocalPath);
+            stream.on("data", (chunk) => {
+                transferred += chunk.length;
+                if (progressBar) {
+                    const elapsedSeconds = Math.max(1e-6, (Date.now() - summary.startTime) / 1000);
+                    const rateCurrent = transferred / elapsedSeconds;
+                    const remainingBytes = Math.max(0, (size ?? transferred) - transferred);
+                    const etaSeconds = rateCurrent > 0 ? remainingBytes / rateCurrent : null;
+                    progressBar.update(Math.min(transferred, size || transferred), {
+                        etaHuman: eta_format(etaSeconds),
+                        rate: rate_format(rateCurrent),
+                        bytes: bytes_format(transferred),
+                        totalBytes: bytes_format(size ?? transferred),
+                    });
+                }
+            });
+            await pipeline(stream, writeStream);
+            if (progressBar) {
+                progressBar.update(size || transferred);
+                progressBar.stop();
+            }
+            summary.totalFiles = 1;
+            summary.transferredCount = 1;
+            summary.transferSize = transferred;
+            summary.endTime = Date.now();
+            summary.duration = (summary.endTime - summary.startTime) / 1000;
+            summary.speed = summary.duration > 0 ? summary.transferSize / summary.duration : 0;
+            return summary;
+        }
+        catch (error) {
+            summary.failedCount = 1;
+            throw error;
+        }
+    }
+    // Download directory
+    console.log(chalk.cyan("Scanning files to download..."));
+    const items = await files_listRecursive(resolvedChris);
+    const files = items.filter((item) => item.type === 'file');
+    summary.totalFiles = files.length;
+    const totalSize = files.reduce((sum, f) => sum + (f.size || 0), 0);
+    // Apply Unix semantics: trailing slash determines merge behavior
+    const targetDir = resolvedChris.endsWith('/')
+        ? localPath // Merge contents
+        : path.join(localPath, path.basename(resolvedChris)); // Create subdir
+    // Warn/confirm if target directory exists
+    if (fs.existsSync(targetDir)) {
+        const statTarget = await fs.promises.stat(targetDir);
+        if (statTarget.isDirectory()) {
+            const entries = await fs.promises.readdir(targetDir);
+            if (!options.force) {
+                await prompt_confirmOrThrow(`Target directory exists${entries.length ? ' (will merge contents)' : ''}: ${targetDir}. Continue? (y/N)`);
+            }
+        }
+        else if (statTarget.isFile()) {
+            if (!options.force) {
+                await prompt_confirmOrThrow(`Local file exists at ${targetDir}. Overwrite? (y/N)`);
+            }
+        }
+    }
+    // Ensure target directory exists
+    await directory_ensureExists(targetDir);
+    const showProgress = !!process.stdout.isTTY;
+    const progressBar = showProgress
+        ? new cliProgress.SingleBar({
+            format: "Downloading [{bar}] {percentage}% | ETA: {etaHuman} | Rate: {rate} | {value}/{total} files | {bytes}/{totalBytes}",
+        }, cliProgress.Presets.shades_classic)
+        : null;
+    if (progressBar) {
+        progressBar.start(files.length, 0, {
+            bytes: bytes_format(0),
+            totalBytes: bytes_format(totalSize),
+            etaHuman: "--",
+            rate: "--",
+        });
+    }
+    // Download each file
+    for (const [index, file] of files.entries()) {
+        try {
+            const result = await fileContent_getBinaryStream(file.path);
+            if (!result.ok) {
+                summary.failedCount++;
+                console.log(chalk.yellow(`\nFailed to download: ${file.path}`));
+                continue;
+            }
+            const { stream, size } = result.value;
+            // Calculate relative path
+            const relativePath = file.path.substring(resolvedChris.length).replace(/^\//, '');
+            const localFilePath = path.join(targetDir, relativePath);
+            // Ensure parent directory exists
+            const parentDir = path.dirname(localFilePath);
+            await directory_ensureExists(parentDir);
+            const writeStream = fs.createWriteStream(localFilePath);
+            let transferred = 0;
+            stream.on("data", (chunk) => {
+                transferred += chunk.length;
+            });
+            await pipeline(stream, writeStream);
+            summary.transferredCount++;
+            summary.transferSize += size ?? transferred;
+        }
+        catch (error) {
+            summary.failedCount++;
+            const msg = error instanceof Error ? error.message : String(error);
+            console.log(chalk.red(`\nError downloading ${file.path}: ${msg}`));
+        }
+        const elapsedSeconds = Math.max(1e-6, (Date.now() - summary.startTime) / 1000);
+        const rateCurrent = summary.transferSize > 0 ? summary.transferSize / elapsedSeconds : 0;
+        const remainingBytes = Math.max(0, totalSize - summary.transferSize);
+        const etaSeconds = rateCurrent > 0 ? remainingBytes / rateCurrent : null;
+        if (progressBar) {
+            progressBar.update(index + 1, {
+                bytes: bytes_format(summary.transferSize),
+                etaHuman: eta_format(etaSeconds),
+                rate: rate_format(rateCurrent),
+            });
+        }
+    }
+    if (progressBar) {
+        progressBar.stop();
+    }
+    summary.endTime = Date.now();
+    summary.duration = (summary.endTime - summary.startTime) / 1000;
+    summary.speed = summary.duration > 0 ? summary.transferSize / summary.duration : 0;
+    return summary;
+}

package/dist/commands/fs/edit.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Result of an edit operation.
+ */
+export interface EditResult {
+    success: boolean;
+    error?: string;
+}
+/**
+ * Replaces a ChRIS file in-place by deleting the original and uploading
+ * a new version from a local path.
+ *
+ * @param chrisPath - The resolved ChRIS path of the file to replace.
+ * @param localPath - The local temp file containing the new content.
+ * @returns EditResult indicating success or failure with error message.
+ */
+export declare function file_replaceContent(chrisPath: string, localPath: string): Promise<EditResult>;

package/dist/commands/fs/edit.js

@@ -0,0 +1,25 @@
+/**
+ * @file File edit-in-place: delete original + re-upload modified content.
+ * @module
+ */
+import { files_rm } from './rm.js';
+import { files_uploadPath } from '@fnndsc/salsa';
+/**
+ * Replaces a ChRIS file in-place by deleting the original and uploading
+ * a new version from a local path.
+ *
+ * @param chrisPath - The resolved ChRIS path of the file to replace.
+ * @param localPath - The local temp file containing the new content.
+ * @returns EditResult indicating success or failure with error message.
+ */
+export async function file_replaceContent(chrisPath, localPath) {
+    const rmResult = await files_rm(chrisPath, { recursive: false, force: false });
+    if (!rmResult.success) {
+        return { success: false, error: rmResult.error ?? 'Delete failed' };
+    }
+    const uploaded = await files_uploadPath(localPath, chrisPath);
+    return {
+        success: uploaded,
+        error: uploaded ? undefined : 'Upload failed after delete — original is gone, check tmp file',
+    };
+}

package/dist/commands/fs/ls.d.ts

@@ -0,0 +1,18 @@
+import { ListingItem } from "../../models/listing.js";
+/**
+ * Options for the list (ls) operation.
+ */
+export interface LsOptions {
+    path?: string;
+    sort?: string;
+    reverse?: boolean;
+    [key: string]: string | boolean | undefined;
+}
+/**
+ * Core logic for the 'ls' command, returning structured data.
+ *
+ * @param options - Options for the ls command, including path.
+ * @param pathStr - The path to list. Defaults to an empty string if not provided.
+ * @returns A Promise resolving to an array of ListingItem.
+ */
+export declare function files_list(options: LsOptions, pathStr?: string): Promise<ListingItem[]>;

package/dist/commands/fs/ls.js

@@ -0,0 +1,142 @@
+/**
+ * @file Implements the core logic for the `ls` command in the ChRIS CLI.
+ *
+ * This module provides functionality to list files, directories, and links
+ * from a specified path within the ChRIS file system. It interacts with the
+ * `@fnndsc/salsa` and `@fnndsc/cumin` libraries to fetch and filter resource data.
+ *
+ * @module
+ */
+import { files_listAll, feeds_list, pluginInstances_list } from "@fnndsc/salsa";
+import { path_resolveChrisFs } from "../../utils/cli.js";
+import { list_applySort } from "../../utils/sort.js";
+import { errorStack } from "@fnndsc/cumin";
+/**
+ * Core logic for the 'ls' command, returning structured data.
+ *
+ * @param options - Options for the ls command, including path.
+ * @param pathStr - The path to list. Defaults to an empty string if not provided.
+ * @returns A Promise resolving to an array of ListingItem.
+ */
+export async function files_list(options, pathStr = "") {
+    const items = [];
+    // Note: If pathStr is invalid, this might throw, which is handled by caller
+    const resolvedPath = await path_resolveChrisFs(pathStr, {});
+    const fetchOpts = { limit: 100, offset: 0 }; // Starting options
+    // Fetch all resources in parallel, but allow some to fail
+    const results = await Promise.allSettled([
+        files_listAll(fetchOpts, 'dirs', resolvedPath),
+        files_listAll(fetchOpts, 'files', resolvedPath),
+        files_listAll(fetchOpts, 'links', resolvedPath)
+    ]);
+    // Process results: 0=dirs, 1=files, 2=links
+    const [dirsResult, filesResult, linksResult] = results;
+    // Helper to map raw API objects to ListingItem
+    const mapToItem = (raw, type) => {
+        let name = raw.fname || raw.path || "";
+        if (name.includes('/')) {
+            name = name.split('/').pop() || name;
+        }
+        const normalizedPath = raw.path
+            ? (raw.path.startsWith('/') ? raw.path : `/${raw.path}`)
+            : undefined;
+        // For links, strip the .chrislink extension from the display name
+        if (type === 'link' && name.endsWith('.chrislink')) {
+            name = name.slice(0, -10); // Remove '.chrislink' (10 characters)
+        }
+        // Normalize target for all item types when a path is present
+        const target = normalizedPath;
+        return {
+            name,
+            type,
+            size: raw.fsize || 0,
+            owner: raw.owner_username || 'unknown',
+            date: raw.creation_date || '',
+            target
+        };
+    };
+    if (dirsResult.status === 'fulfilled') {
+        const dirs = dirsResult.value;
+        if (dirs && dirs.tableData) {
+            dirs.tableData.forEach((d) => items.push(mapToItem(d, 'dir')));
+        }
+    }
+    else {
+        errorStack.stack_push('error', `Failed to list directories: ${dirsResult.reason}`);
+    }
+    if (filesResult.status === 'fulfilled') {
+        const files = filesResult.value;
+        if (files && files.tableData) {
+            files.tableData.forEach((f) => items.push(mapToItem(f, 'file')));
+        }
+    }
+    else {
+        errorStack.stack_push('error', `Failed to list files: ${filesResult.reason}`);
+    }
+    if (linksResult.status === 'fulfilled') {
+        const links = linksResult.value;
+        if (links && links.tableData) {
+            links.tableData.forEach((l) => items.push(mapToItem(l, 'link')));
+        }
+    }
+    else {
+        errorStack.stack_push('error', `Failed to list links: ${linksResult.reason}`);
+    }
+    // Enrich items with titles for feeds and plugin instances
+    await listingItems_enrichTitles(items);
+    // Apply sorting (default to name if not specified)
+    const sortField = options.sort || 'name';
+    const sortedItems = list_applySort(items, sortField, options.reverse);
+    return sortedItems;
+}
+/**
+ * Enriches listing items with titles for feeds and plugin instances.
+ * Detects patterns: feed_XXXX and pl-<name>_XXXX
+ *
+ * @param items - Array of listing items to enrich.
+ */
+async function listingItems_enrichTitles(items) {
+    const enrichPromises = items.map(async (item) => {
+        if (item.type !== 'dir')
+            return; // Only process directories
+        // Pattern 1: feed_XXXX
+        const feedMatch = item.name.match(/^feed_(\d+)$/);
+        if (feedMatch) {
+            const feedId = parseInt(feedMatch[1], 10);
+            try {
+                const feedData = await feeds_list({ id: feedId, limit: 1 });
+                if (feedData && feedData.tableData && feedData.tableData.length > 0) {
+                    const feed = feedData.tableData[0];
+                    if (feed && typeof feed['name'] === 'string') {
+                        item.title = feed['name'];
+                    }
+                }
+            }
+            catch (e) {
+                // Silently ignore errors
+            }
+            return;
+        }
+        // Pattern 2: pl-<name>_XXXX
+        const pluginMatch = item.name.match(/^(pl-.+)_(\d+)$/);
+        if (pluginMatch) {
+            const pluginInstanceId = parseInt(pluginMatch[2], 10);
+            try {
+                const instanceData = await pluginInstances_list({ id: pluginInstanceId, limit: 1 });
+                if (instanceData && instanceData.tableData && instanceData.tableData.length > 0) {
+                    const instance = instanceData.tableData[0];
+                    if (instance) {
+                        const pluginName = typeof instance['plugin_name'] === 'string' ? instance['plugin_name'] : '';
+                        const pluginVersion = typeof instance['plugin_version'] === 'string' ? instance['plugin_version'] : '';
+                        item.title = pluginVersion ? `${pluginName} v${pluginVersion}` : pluginName;
+                    }
+                }
+            }
+            catch (e) {
+                // Silently ignore errors
+            }
+            return;
+        }
+    });
+    await Promise.all(enrichPromises);
+}

package/dist/commands/fs/mkdir.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Core logic for the 'mkdir' command.
+ * This function does not perform any console output.
+ *
+ * @param dirPath - The full or relative ChRIS path for the new folder.
+ * @returns A Promise resolving to true on success, false on failure.
+ */
+export declare function files_mkdir(dirPath: string): Promise<boolean>;

package/dist/commands/fs/mkdir.js

@@ -0,0 +1,21 @@
+/**
+ * @file Implements the core logic for the `mkdir` command in the ChRIS CLI.
+ *
+ * This module provides functionality to create new directories
+ * within the ChRIS file system. It interacts with the `@fnndsc/salsa` library.
+ *
+ * @module
+ */
+import { files_mkdir as salsaFiles_mkdir } from "@fnndsc/salsa";
+import { path_resolveChrisFs } from "../../utils/cli.js";
+/**
+ * Core logic for the 'mkdir' command.
+ * This function does not perform any console output.
+ *
+ * @param dirPath - The full or relative ChRIS path for the new folder.
+ * @returns A Promise resolving to true on success, false on failure.
+ */
+export async function files_mkdir(dirPath) {
+    const resolvedPath = await path_resolveChrisFs(dirPath, {});
+    return await salsaFiles_mkdir(resolvedPath);
+}

package/dist/commands/fs/mv.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Options for the move (mv) operation.
+ */
+export interface MvOptions {
+}
+/**
+ * Moves a file or directory.
+ *
+ * @param src - Source path.
+ * @param dest - Destination path.
+ * @returns Promise<boolean> success.
+ */
+export declare function files_mv(src: string, dest: string): Promise<boolean>;

package/dist/commands/fs/mv.js

@@ -0,0 +1,73 @@
+/**
+ * @file Move command logic.
+ *
+ * Performs server-side moves (renames) for files and directories.
+ *
+ * @module
+ */
+import { files_move as salsa_files_move, files_listAll } from "@fnndsc/salsa";
+import { path_resolveChrisFs } from "../../utils/cli.js";
+import { errorStack } from "@fnndsc/cumin";
+import path from "path";
+/**
+ * Moves a file or directory.
+ *
+ * @param src - Source path.
+ * @param dest - Destination path.
+ * @returns Promise<boolean> success.
+ */
+export async function files_mv(src, dest) {
+    const srcPath = await path_resolveChrisFs(src, {});
+    const destPath = await path_resolveChrisFs(dest, {});
+    const srcIsDir = await path_checkIsDir(srcPath);
+    if (!srcIsDir && !(await path_checkExists(srcPath))) {
+        errorStack.stack_push("error", `Source not found: ${src}`);
+        return false;
+    }
+    const destIsDir = await path_checkIsDir(destPath);
+    const destLooksDir = dest.endsWith("/");
+    const finalDest = (destIsDir || destLooksDir)
+        ? path.posix.join(destPath, path.posix.basename(srcPath))
+        : destPath;
+    return await salsa_files_move(srcPath, finalDest);
+}
+/**
+ * Determines whether a given ChRIS path refers to a directory.
+ *
+ * @param targetPath - The absolute ChRIS path to check.
+ * @returns Promise<boolean> indicating directory existence.
+ */
+async function path_checkIsDir(targetPath) {
+    const parent = path.posix.dirname(targetPath);
+    const results = await files_listAll({ limit: 1000, offset: 0 }, "dirs", parent);
+    if (!results || !results.tableData) {
+        return false;
+    }
+    const name = path.posix.basename(targetPath);
+    return results.tableData.some((entry) => {
+        const candidate = typeof entry.path === "string" && entry.path.length > 0
+            ? entry.path
+            : typeof entry.fname === "string"
+                ? entry.fname
+                : "";
+        return candidate === targetPath || path.posix.basename(candidate) === name;
+    });
+}
+/**
+ * Determines whether a given ChRIS path exists as a file in its parent directory.
+ *
+ * @param targetPath - The absolute ChRIS path to check.
+ * @returns Promise<boolean> indicating file existence.
+ */
+async function path_checkExists(targetPath) {
+    const parent = path.posix.dirname(targetPath);
+    const name = path.posix.basename(targetPath);
+    const results = await files_listAll({ limit: 1000, offset: 0 }, "files", parent);
+    if (!results || !results.tableData) {
+        return false;
+    }
+    return results.tableData.some((entry) => {
+        const candidate = typeof entry.fname === "string" ? entry.fname : "";
+        return candidate === targetPath || path.posix.basename(candidate) === name;
+    });
+}

package/dist/commands/fs/rm.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Options for the remove (rm) operation.
+ */
+export interface RmOptions {
+    recursive?: boolean;
+    force?: boolean;
+}
+/**
+ * Result of a remove (rm) operation.
+ */
+export interface RmResult {
+    success: boolean;
+    path: string;
+    type: 'file' | 'dir' | 'link' | null;
+    error?: string;
+}
+/**
+ * Core logic for the 'rm' command.
+ *
+ * @param targetPath - The path to delete.
+ * @param options - Options including recursive and force flags.
+ * @returns A Promise resolving to RmResult.
+ */
+export declare function files_rm(targetPath: string, options?: RmOptions): Promise<RmResult>;