@fnndsc/chili 3.2.5

package/dist/path/pathCommand.js

@@ -0,0 +1,805 @@
+/**
+ * @file Path scan/transfer commands and the recursive ChRIS path scanner.
+ *
+ * @module
+ */
+import { chrisIO, chrisContext, Context, errorStack, objContext_create, } from "@fnndsc/cumin";
+import { vfsDispatcher } from "@fnndsc/salsa";
+import chalk from "chalk";
+import fs from "fs";
+import path from "path";
+import cliProgress from "cli-progress";
+import { table_display, border_draw } from "../screen/screen.js";
+import { options_toParams } from "../utils/cli.js";
+import archy from "archy";
+import open from "open";
+import { exec } from "child_process";
+import os from "os";
+import { files_downloadWithProgress } from "../commands/fs/download.js";
+/**
+ * Creates a summary table for file transfer details.
+ *
+ * @param summary - The TransferDetail object containing transfer statistics.
+ * @returns A 2D array representing the summary table.
+ */
+function summaryTable_create(summary) {
+    const summaryTable = [
+        ["Total files", summary.totalFiles.toString()],
+        [
+            "Successfully transferred",
+            chalk.green(summary.transferredCount.toString()),
+        ],
+        ["Failed to transfer", chalk.red(summary.failedCount.toString())],
+        [
+            "Total data transferred",
+            chalk.blueBright(bytes_format(summary.transferSize)),
+        ],
+        [
+            "Average transfer speed",
+            chalk.blueBright(`${bytes_format(summary.speed)}/s`),
+        ],
+        ["Duration", `${summary.duration.toFixed(2)} seconds`],
+    ];
+    return summaryTable;
+}
+/**
+ * Creates resource groups (files, directories, links) for a given ChRIS path.
+ *
+ * @param currentPath - The ChRIS path to create resource groups for.
+ * @returns A Promise resolving to an object containing the resource groups, or null on error.
+ */
+async function resourceGroups_create(currentPath) {
+    try {
+        const filesGroup = (await objContext_create("ChRISFilesContext", `folder:${currentPath}`));
+        const dirsGroup = (await objContext_create("ChRISDirsContext", `folder:${currentPath}`));
+        const linksGroup = (await objContext_create("ChRISLinksContext", `folder:${currentPath}`));
+        return { filesGroup, dirsGroup, linksGroup };
+    }
+    catch (error) {
+        errorStack.stack_push("error", `Failed to create ChRISEmbeddedResourceGroup objects for path ${currentPath}: ${error}`);
+        return null;
+    }
+}
+/**
+ * Generates a Mermaid diagram definition from a scan result.
+ *
+ * @param scanResult - The ScanRecord containing file information.
+ * @returns The Mermaid diagram definition string.
+ */
+function mermaidDefinition_generate(scanResult) {
+    let definition = "graph TD\n";
+    definition += "    %% Styles\n";
+    definition +=
+        "    classDef default fill:#f9f,stroke:#333,stroke-width:2px;\n";
+    definition += "    classDef root fill:#ff9,stroke:#333,stroke-width:4px;\n";
+    definition += "    classDef leaf fill:#9f9,stroke:#333,stroke-width:2px;\n\n";
+    const nodes = new Map();
+    const edges = new Set();
+    let nodeCounter = 0;
+    function nodeId_getOrCreate(path) {
+        if (!nodes.has(path)) {
+            nodes.set(path, nodeCounter++);
+        }
+        return nodes.get(path);
+    }
+    const leafNodes = new Set();
+    scanResult.fileInfo.forEach((file) => {
+        const parts = file.chrisPath.split("/").filter(Boolean);
+        for (let i = 1; i < parts.length; i++) {
+            const parentPath = "/" + parts.slice(0, i).join("/");
+            const currentPath = "/" + parts.slice(0, i + 1).join("/");
+            const parentNode = nodeId_getOrCreate(parentPath);
+            const currentNode = nodeId_getOrCreate(currentPath);
+            const edge = `${parentNode} --> ${currentNode}`;
+            if (!edges.has(edge)) {
+                edges.add(edge);
+                definition += `    ${parentNode}[${parts[i - 1]}] --> ${currentNode}[${parts[i]}]
+`;
+            }
+            if (i === parts.length - 1) {
+                leafNodes.add(currentNode);
+            }
+        }
+    });
+    // Apply styles
+    definition += "\n    %% Applying styles\n";
+    definition += `    class ${nodeId_getOrCreate("/")} root;\n`;
+    leafNodes.forEach((nodeId) => {
+        definition += `    class ${nodeId} leaf;\n`;
+    });
+    return definition;
+}
+/**
+ * Generates an HTML page for displaying a Mermaid diagram.
+ *
+ * @param mermaidDefinition - The Mermaid diagram definition string.
+ * @returns The HTML content as a string.
+ */
+function mermaidHtml_generate(mermaidDefinition) {
+    return `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Plugin DAG</title>
+    <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
+</head>
+<body>
+    <div class="mermaid">
+    ${mermaidDefinition}
+    </div>
+    <script>
+        mermaid.initialize({ startOnLoad: true });
+    </script>
+</body>
+</html>
+  `;
+}
+/**
+ * Renders a Mermaid diagram in a browser window.
+ *
+ * @param mermaidDefinition - The Mermaid diagram definition string.
+ */
+async function mermaid_renderInBrowser(mermaidDefinition) {
+    const html = mermaidHtml_generate(mermaidDefinition);
+    const tempDir = os.tmpdir();
+    const filePath = path.join(tempDir, "mermaid-diagram.html");
+    fs.writeFileSync(filePath, html);
+    await open(filePath);
+}
+/**
+ * Renders a Mermaid diagram on the server-side and saves it to a file.
+ * Requires `mmdc` (Mermaid CLI) to be installed.
+ *
+ * @param mermaidDefinition - The Mermaid diagram definition string.
+ * @param outputFile - The path to save the output file.
+ * @returns A Promise resolving to the output file path.
+ */
+async function mermaid_renderServerSide(mermaidDefinition, outputFile) {
+    const tempDir = os.tmpdir();
+    const inputFile = path.join(tempDir, "input.mmd");
+    fs.writeFileSync(inputFile, mermaidDefinition);
+    return new Promise((resolve, reject) => {
+        exec(`npx mmdc -i ${inputFile} -o ${outputFile}`, (error, stdout, stderr) => {
+            if (error) {
+                console.error(`exec error: ${error}`);
+                reject(error);
+                return;
+            }
+            resolve(outputFile);
+        });
+    });
+}
+/**
+ * Creates an Archy-formatted tree structure from file information.
+ *
+ * @param files - An array of FileInfo objects.
+ * @returns The Archy-formatted tree string.
+ */
+export function archyTree_create(files) {
+    const root = { label: "", nodes: {} };
+    files.forEach((file) => {
+        if (file.chrisPath) {
+            const parts = file.chrisPath.split("/").filter(Boolean);
+            let current = root;
+            parts.forEach((part, index) => {
+                if (!current.nodes[part]) {
+                    current.nodes[part] = { label: part, nodes: {} };
+                }
+                current = current.nodes[part];
+                if (index === parts.length - 1 && file.isLink) {
+                    current.label += ` -> ${file.linkTarget}`;
+                }
+            });
+        }
+    });
+    function archyFormat_convert(node) {
+        return {
+            label: node.label,
+            nodes: Object.values(node.nodes).map(archyFormat_convert),
+        };
+    }
+    return archy(archyFormat_convert(root));
+}
+/**
+ * Scans directories within ChRIS.
+ *
+ * @param dirsGroup - The ChRISEmbeddedResourceGroup for directories.
+ * @param chrisPath - The base ChRIS path.
+ * @param hostBasePath - The base path on the host system.
+ * @param linkedPath - Optional linked path for resolving relative paths.
+ * @returns A Promise resolving to an array of FileInfo objects for directories.
+ */
+async function dirs_scan(dirsGroup, chrisPath, hostBasePath, linkedPath = "") {
+    const dirs = [];
+    const dirResults = await dirsGroup.asset.resources_listAndFilterByOptions(options_toParams({ fields: "path" }));
+    if (dirResults && dirResults.tableData) {
+        for (const dir of dirResults.tableData) {
+            const dirPath = "/" + String(dir.path);
+            const relativeChrisPath = linkedPath
+                ? path.join(linkedPath, path.basename(dirPath))
+                : dirPath;
+            const dirInfo = {
+                id: 0,
+                hostPath: path.join(hostBasePath, path.relative(chrisPath, relativeChrisPath)),
+                chrisPath: relativeChrisPath,
+                size: 0,
+                isLink: false,
+                linkTarget: "",
+                isDirectory: true,
+            };
+            dirs.push(dirInfo);
+        }
+    }
+    return dirs;
+}
+/**
+ * Scans files within ChRIS.
+ *
+ * @param filesGroup - The ChRISEmbeddedResourceGroup for files.
+ * @param chrisPath - The base ChRIS path.
+ * @param hostBasePath - The base path on the host system.
+ * @param linkedPath - Optional linked path for resolving relative paths.
+ * @returns A Promise resolving to an array of FileInfo objects for files.
+ */
+async function files_scan(filesGroup, chrisPath, hostBasePath, linkedPath = "") {
+    const files = [];
+    const fileResults = await filesGroup.asset.resources_listAndFilterByOptions(options_toParams({ fields: "id,fname,fsize" }));
+    if (fileResults && fileResults.tableData) {
+        for (const file of fileResults.tableData) {
+            const size = parseInt(String(file.fsize), 10);
+            const fname = "/" + String(file.fname);
+            const relativeChrisPath = linkedPath
+                ? path.join(linkedPath, path.basename(fname))
+                : fname;
+            const fileInfo = {
+                id: parseInt(String(file.id), 10),
+                hostPath: path.join(hostBasePath, path.relative(chrisPath, relativeChrisPath)),
+                chrisPath: relativeChrisPath,
+                size: isNaN(size) ? 0 : size,
+                isLink: !!linkedPath,
+                linkTarget: linkedPath ? fname : "",
+                isDirectory: false,
+            };
+            files.push(fileInfo);
+        }
+    }
+    return files;
+}
+/**
+ * Scans links within ChRIS.
+ *
+ * @param linksGroup - The ChRISEmbeddedResourceGroup for links.
+ * @param chrisPath - The base ChRIS path.
+ * @param hostBasePath - The base path on the host system.
+ * @param linkedPath - Optional linked path for resolving relative paths.
+ * @returns A Promise resolving to an array of FileInfo objects for links.
+ */
+async function links_scan(linksGroup, chrisPath, hostBasePath, linkedPath = "") {
+    const links = [];
+    const linkResults = await linksGroup.asset.resources_listAndFilterByOptions(options_toParams({ fields: "id,path,fname" }));
+    if (linkResults && linkResults.tableData) {
+        for (const link of linkResults.tableData) {
+            const linkPath = "/" + String(link.path);
+            const linkFname = "/" + String(link.fname);
+            const relativeChrisPath = linkedPath
+                ? path.join(linkedPath, path.basename(linkFname))
+                : linkFname;
+            const linkInfo = {
+                id: parseInt(String(link.id), 10),
+                hostPath: path.join(hostBasePath, path.relative(chrisPath, relativeChrisPath)),
+                chrisPath: relativeChrisPath,
+                isLink: true,
+                linkTarget: linkPath,
+                size: 0,
+                isDirectory: false,
+            };
+            links.push(linkInfo);
+        }
+    }
+    return links;
+}
+async function chrisDir_walk(currentPath, chrisPath, hostBasePath, followLinks, dirsOnly, linkedPath = "") {
+    const listResult = await vfsDispatcher.list(currentPath);
+    if (!listResult.ok) {
+        return { files: [], totalSize: 0 };
+    }
+    const items = listResult.value || [];
+    const dirs = items.filter((item) => item.type === "dir" || item.type === "vfs" || item.type === "job");
+    const normalFiles = items.filter((item) => item.type === "file");
+    const links = items.filter((item) => item.type === "link");
+    const files = [];
+    let totalSize = 0;
+    const dirInfos = dirs.map((dir) => {
+        const fullPath = currentPath === "/" ? "/" + dir.name : path.join(currentPath, dir.name);
+        const relativeChrisPath = linkedPath ? path.join(linkedPath, dir.name) : fullPath;
+        return {
+            id: 0,
+            hostPath: path.join(hostBasePath, path.relative(chrisPath, relativeChrisPath)),
+            chrisPath: relativeChrisPath,
+            size: 0,
+            isLink: false,
+            linkTarget: "",
+            isDirectory: true,
+        };
+    });
+    files.push(...dirInfos);
+    if (!dirsOnly) {
+        const fileInfos = normalFiles.map((file) => {
+            const fullPath = currentPath === "/" ? "/" + file.name : path.join(currentPath, file.name);
+            const relativeChrisPath = linkedPath ? path.join(linkedPath, file.name) : fullPath;
+            return {
+                id: 0,
+                hostPath: path.join(hostBasePath, path.relative(chrisPath, relativeChrisPath)),
+                chrisPath: relativeChrisPath,
+                size: file.size,
+                isLink: !!linkedPath,
+                linkTarget: linkedPath ? fullPath : "",
+                isDirectory: false,
+            };
+        });
+        files.push(...fileInfos);
+        totalSize += fileInfos.reduce((sum, f) => sum + f.size, 0);
+        const linkInfos = links.map((link) => {
+            const fullPath = currentPath === "/" ? "/" + link.name : path.join(currentPath, link.name);
+            const relativeChrisPath = linkedPath ? path.join(linkedPath, link.name) : fullPath;
+            return {
+                id: 0,
+                hostPath: path.join(hostBasePath, path.relative(chrisPath, relativeChrisPath)),
+                chrisPath: relativeChrisPath,
+                isLink: true,
+                linkTarget: link.target || "",
+                size: 0,
+                isDirectory: false,
+            };
+        });
+        files.push(...linkInfos);
+        if (followLinks) {
+            for (const link of linkInfos) {
+                const sub = await chrisDir_walk(link.linkTarget, chrisPath, hostBasePath, followLinks, dirsOnly, link.chrisPath);
+                files.push(...sub.files);
+                totalSize += sub.totalSize;
+            }
+        }
+    }
+    for (const dir of dirs) {
+        const fullPath = currentPath === "/" ? "/" + dir.name : path.join(currentPath, dir.name);
+        const nextLinkedPath = linkedPath ? path.join(linkedPath, dir.name) : "";
+        const sub = await chrisDir_walk(fullPath, chrisPath, hostBasePath, followLinks, dirsOnly, nextLinkedPath);
+        files.push(...sub.files);
+        totalSize += sub.totalSize;
+    }
+    return { files, totalSize };
+}
+async function chrisFS_scan(chrisPath, hostBasePath, followLinks = false, dirsOnly = false) {
+    try {
+        const result = await chrisDir_walk(chrisPath, chrisPath, hostBasePath, followLinks, dirsOnly);
+        return { fileInfo: result.files, totalSize: result.totalSize };
+    }
+    catch (error) {
+        errorStack.stack_push("error", `Failed to scan ChRIS filesystem: ${error}`);
+        return null;
+    }
+}
+function scanResult_filter(scanResult, options) {
+    if (!options.filter && !options.endsWith) {
+        return scanResult;
+    }
+    const keepPaths = new Set();
+    for (const file of scanResult.fileInfo) {
+        const basename = path.basename(file.chrisPath);
+        if ((!options.filter || file.chrisPath.includes(options.filter)) &&
+            (!options.endsWith || basename.includes(options.endsWith))) {
+            let currentPath = file.chrisPath;
+            while (currentPath !== "/") {
+                keepPaths.add(currentPath);
+                currentPath = path.dirname(currentPath);
+            }
+            keepPaths.add("/");
+        }
+    }
+    const fileInfo = scanResult.fileInfo.filter((f) => keepPaths.has(f.chrisPath));
+    return { fileInfo, totalSize: fileInfo.reduce((sum, f) => sum + f.size, 0) };
+}
+async function scanResult_render(scanResult, options) {
+    if (options.mermaid) {
+        const mermaidDefinition = mermaidDefinition_generate(scanResult);
+        if (options.save) {
+            try {
+                const outputFile = path.resolve(options.save);
+                const savedFilePath = await mermaid_renderServerSide(mermaidDefinition, outputFile);
+                console.log(`Mermaid diagram saved to: ${savedFilePath}`);
+            }
+            catch (error) {
+                console.error(`Failed to save Mermaid diagram: ${error}`);
+            }
+        }
+        else {
+            await mermaid_renderInBrowser(mermaidDefinition);
+        }
+        return;
+    }
+    if (options.tree) {
+        console.log(archyTree_create(scanResult.fileInfo));
+        return;
+    }
+    if (!options.silent) {
+        for (const file of scanResult.fileInfo) {
+            if (file.isLink && !options.follow) {
+                console.log(`${file.chrisPath} -> ${file.linkTarget}`);
+            }
+            else {
+                console.log(`${file.chrisPath}`);
+            }
+        }
+    }
+}
+/**
+ * Performs a recursive scan of the current ChRIS folder.
+ *
+ * @param options - Scan options.
+ * @returns The scan record, or null if no context is set.
+ */
+export async function scan_do(options) {
+    const chrisFolder = await chrisContext.current_get(Context.ChRISfolder);
+    if (!chrisFolder) {
+        console.error(chalk.red("No ChRIS folder context set. Use 'folder=' to set a context."));
+        return null;
+    }
+    if (!options.silent) {
+        console.log(chalk.cyan(`Scanning for ${options.dirsOnly ? "directories" : "all files"} recursively from ${chrisFolder}`));
+    }
+    const hostBasePath = options.hostpath || process.cwd();
+    const scanResult = await chrisFS_scan(chrisFolder, hostBasePath, options.follow, options.dirsOnly);
+    if (!scanResult) {
+        console.error(chalk.red("Failed to scan ChRIS filesystem."));
+        return null;
+    }
+    const filtered = scanResult_filter(scanResult, options);
+    await scanResult_render(filtered, options);
+    if (!options.silent) {
+        console.log(chalk.green(`Total size: ${bytes_format(filtered.totalSize)}`));
+        if (options.filter || options.endsWith) {
+            console.log(chalk.cyan(`Filtered results: ${filtered.fileInfo.length} items`));
+        }
+    }
+    return filtered;
+}
+/**
+ * Recursively gets files from the host path to be uploaded to ChRIS.
+ *
+ * @param hostpath - The host system path to scan.
+ * @param chrisdir - The target ChRIS directory path.
+ * @returns A Promise resolving to an array of FileInfo objects for files to upload.
+ */
+async function filesToUpload_get(hostpath, chrisdir) {
+    const files = [];
+    let idCounter = 1;
+    async function dir_walk(currentPath, currentChrisPath) {
+        const entries = await fs.promises.readdir(currentPath, {
+            withFileTypes: true,
+        });
+        for (const entry of entries) {
+            const hostFilePath = path.join(currentPath, entry.name);
+            const chrisFilePath = path.join(currentChrisPath, entry.name);
+            if (entry.isDirectory()) {
+                await dir_walk(hostFilePath, chrisFilePath);
+            }
+            else {
+                files.push({
+                    id: idCounter++,
+                    hostPath: hostFilePath,
+                    chrisPath: chrisFilePath,
+                    isLink: false, // Assuming local files are not symlinks
+                    size: (await fs.promises.stat(hostFilePath)).size,
+                    linkTarget: "",
+                    isDirectory: false,
+                });
+            }
+        }
+    }
+    // Preserve the basename of the source directory in the target path
+    const hostBasename = path.basename(hostpath);
+    await dir_walk(hostpath, path.join(chrisdir, hostBasename));
+    return files;
+}
+/**
+ * Scans the local filesystem for files to upload to ChRIS.
+ *
+ * @param options - TransferCLI options specifying the host path.
+ * @returns A Promise resolving to a ScanRecord of local files, or null on error.
+ */
+async function localFS_scan(options) {
+    await chrisContext.currentContext_update();
+    const folder = chrisContext.singleContext.folder;
+    if (!folder) {
+        console.error("ChRIS folder context is undefined, cannot initialize chrisIO.");
+        return null;
+    }
+    // Validate that the folder context exists in CUBE before proceeding
+    try {
+        const testGroup = await objContext_create("ChRISDirsContext", `folder:${folder}`);
+        if (!testGroup) {
+            console.error(chalk.red(`Folder context '${folder}' does not exist in CUBE. Please specify an existing directory.`));
+            return null;
+        }
+    }
+    catch (error) {
+        console.error(chalk.red(`Folder context '${folder}' does not exist in CUBE. Please specify an existing directory.`));
+        return null;
+    }
+    // Folder exists, so just set chrisFolder without calling init()
+    // (init() tries to CREATE the folder which will fail if it already exists)
+    chrisIO.chrisFolder = folder;
+    console.log(border_draw(chalk.cyan("Scanning files to upload...")));
+    const filesToUpload = await filesToUpload_get(options.hostpath, folder);
+    let totalSize = 0;
+    for (const file of filesToUpload) {
+        if (file.hostPath) {
+            const stats = await fs.promises.stat(file.hostPath);
+            totalSize += stats.size;
+        }
+    }
+    return {
+        fileInfo: filesToUpload,
+        totalSize: totalSize,
+    };
+}
+/**
+ * Sets up and starts a CLI progress bar for file transfers.
+ *
+ * @param scanRecord - The ScanRecord containing total files and size.
+ * @returns The initialized cliProgress.SingleBar instance.
+ */
+function progressBar_setupAndStart(scanRecord) {
+    const progressBar = new cliProgress.SingleBar({
+        format: "Transferring [{bar}] {percentage}% | ETA: {eta}s | {value}/{total} files | {bytes}/{totalBytes}",
+    }, cliProgress.Presets.shades_classic);
+    progressBar.start(scanRecord.fileInfo.length, 0, {
+        bytes: "0 B",
+        totalBytes: bytes_format(scanRecord.totalSize), // Renamed
+    });
+    return progressBar;
+}
+/**
+ * Initializes a TransferDetail object.
+ *
+ * @returns An initialized TransferDetail object.
+ */
+function transferDetail_init() {
+    const uploadSummary = {
+        startTime: 0,
+        endTime: 0,
+        totalFiles: 0,
+        transferredCount: 0,
+        failedCount: 0,
+        transferSize: 0,
+        speed: 0,
+        duration: 0,
+    };
+    return uploadSummary;
+}
+/**
+ * Calculates transmission summary details (duration and speed).
+ *
+ * @param transfer - The TransferDetail object to update.
+ * @returns A Tranmission object with calculated speed and duration.
+ */
+function transmissionSummary_get(transfer) {
+    let transmission = {
+        duration: 0,
+        speed: 0,
+    };
+    transfer.endTime = Date.now();
+    transmission.duration = (transfer.endTime - transfer.startTime) / 1000; // in seconds
+    transmission.speed = transfer.transferSize / transmission.duration; // bytes per second
+    return transmission;
+}
+/**
+ * Resolves the parent directory name for pulled files.
+ *
+ * @returns The parent directory name or an empty string.
+ */
+function pulledParentDir_resolve() {
+    const chrisFolder = chrisContext.singleContext.folder;
+    if (!chrisFolder) {
+        return "";
+    }
+    if (chrisFolder.endsWith("/")) {
+        return "";
+    }
+    return path.basename(chrisFolder);
+}
+/**
+ * Pulls files from ChRIS to the local filesystem.
+ *
+ * @param scanRecord - The ScanRecord of files to pull.
+ * @param progressBar - The CLI progress bar instance.
+ * @returns A Promise resolving to a TransferDetail object with pull statistics.
+ */
+async function chris_pull(scanRecord, progressBar) {
+    let summary = transferDetail_init();
+    summary.startTime = Date.now();
+    const parentDir = pulledParentDir_resolve();
+    const baseDir = process.cwd();
+    for (const [index, file] of scanRecord.fileInfo.entries()) {
+        try {
+            if (!file.hostPath) {
+                continue;
+            }
+            const fileBuffer = await chrisIO.file_download(file.id);
+            if (fileBuffer) {
+                const relativePath = path.relative(baseDir, file.hostPath);
+                const hostPath = path.join(baseDir, parentDir, relativePath);
+                const dirPath = path.dirname(hostPath);
+                fs.mkdirSync(dirPath, { recursive: true });
+                fs.writeFileSync(hostPath, fileBuffer);
+                summary.transferredCount++;
+                summary.transferSize += fileBuffer.length;
+            }
+            else {
+                summary.failedCount++;
+                console.log(chalk.yellow(`Failed to download: ${file.hostPath}`));
+            }
+        }
+        catch (error) {
+            summary.failedCount++;
+            console.log(chalk.red(`Error downloading ${file.hostPath}: ${error instanceof Error ? error.message : String(error)}`));
+        }
+        progressBar.update(index + 1, {
+            bytes: bytes_format(summary.transferSize), // Renamed
+        });
+    }
+    const transmission = transmissionSummary_get(summary);
+    progressBar.stop();
+    summary.totalFiles = scanRecord.fileInfo.length;
+    summary.duration = transmission.duration;
+    summary.speed = transmission.speed;
+    return summary;
+}
+/**
+ * Pushes files from the local filesystem to ChRIS.
+ *
+ * @param scanRecord - The ScanRecord of files to push.
+ * @param progressBar - The CLI progress bar instance.
+ * @returns A Promise resolving to a TransferDetail object with push statistics.
+ */
+async function chris_push(scanRecord, progressBar) {
+    let summary = transferDetail_init();
+    summary.startTime = Date.now();
+    for (const [index, file] of scanRecord.fileInfo.entries()) {
+        try {
+            if (!file.hostPath) {
+                continue;
+            }
+            const fileContent = await fs.promises.readFile(file.hostPath);
+            const fileBlob = new Blob([fileContent]);
+            const uploadResult = await chrisIO.file_upload(fileBlob, path.dirname(file.chrisPath), path.basename(file.chrisPath));
+            if (uploadResult) {
+                summary.transferredCount++;
+                summary.transferSize += fileContent.length;
+            }
+            else {
+                summary.failedCount++;
+                console.log(chalk.yellow(`Failed to upload: ${file.hostPath}`));
+            }
+        }
+        catch (error) {
+            summary.failedCount++;
+            console.log(chalk.red(`Error uploading ${file.hostPath}: ${error instanceof Error ? error.message : String(error)}`));
+        }
+        progressBar.update(index + 1, {
+            bytes: bytes_format(summary.transferSize), // Renamed
+        });
+    }
+    const transmission = transmissionSummary_get(summary);
+    progressBar.stop();
+    summary.totalFiles = scanRecord.fileInfo.length;
+    summary.duration = transmission.duration;
+    summary.speed = transmission.speed;
+    return summary;
+}
+/**
+ * Downloads files from ChRIS to the local filesystem.
+ *
+ * @param options - TransferCLI options including host path.
+ * @returns A Promise resolving to true if download was successful, false otherwise.
+ */
+async function download_handle(options) {
+    await chrisContext.currentContext_update();
+    const folder = chrisContext.singleContext.folder;
+    if (!folder) {
+        console.error(chalk.red("No ChRIS folder context set. Use 'connect' to establish a session."));
+        return false;
+    }
+    const localTarget = path.resolve(options.hostpath || process.cwd());
+    try {
+        const summary = await files_downloadWithProgress(folder, localTarget, {
+            force: options.force,
+        });
+        table_display(summaryTable_create(summary), ["Metric", "Value"], {
+            title: { title: "Download summary", justification: "center" },
+        });
+        return summary.failedCount === 0;
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        console.error(chalk.red(`Download failed: ${msg}`));
+        return false;
+    }
+}
+/**
+ * Uploads files from the local filesystem to ChRIS.
+ *
+ * @param options - TransferCLI options including host path.
+ * @returns A Promise resolving to true if upload was successful, false otherwise.
+ */
+async function upload_handle(options) {
+    const scanRecord = await localFS_scan(options);
+    if (!scanRecord) {
+        return false;
+    }
+    const progressBar = progressBar_setupAndStart(scanRecord);
+    const summary = await chris_push(scanRecord, progressBar);
+    table_display(summaryTable_create(summary), ["Metric", "Value"], {
+        title: { title: "Upload summary", justification: "center" },
+    });
+    return summary.failedCount === 0;
+}
+/**
+ * Formats a number of bytes into a human-readable string.
+ *
+ * @param bytes - The number of bytes.
+ * @returns A formatted string (e.g., "1.23 MB").
+ */
+export function bytes_format(bytes) {
+    if (bytes === 0)
+        return "0 B";
+    const k = 1024;
+    const sizes = ["B", "KB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
+}
+/**
+ * Sets up the 'path' command for performing operations on ChRIS paths.
+ *
+ * @param program - The Commander.js program instance.
+ */
+export async function pathCommand_setup(program) {
+    const pathCommand = program
+        .command("path")
+        .description("Perform operations on ChRIS paths");
+    pathCommand
+        .command("upload <hostpath>")
+        .description("upload the <hostpath> from your computer into the current ChRIS folder context")
+        .action(async (hostpath) => {
+        const result = await upload_handle({ hostpath });
+    });
+    pathCommand
+        .command("download [hostpath]")
+        .description("download the current ChRIS folder context to current dir or [hostdir]")
+        .option("-f, --force", "overwrite existing local path")
+        .action(async (hostpath, options) => {
+        const result = await download_handle({
+            hostpath: hostpath || process.cwd(),
+            force: options.force,
+        });
+        console.log(result);
+    });
+    pathCommand
+        .command("scan")
+        .description("scan and list all files recursively from the current ChRIS folder context")
+        .option("--tree", "present in a style reminiscent of the UNIX tree command")
+        .option("--follow", "follow chrislinks")
+        .option("--dirsOnly", "scan only directories")
+        .option("--silent", "suppress output")
+        .option("--hostpath <path>", "specify host path for file mapping")
+        .option("--filter <text>", "filter results to include only paths containing the specified text")
+        .option("--endsWith <text>", "filter results to include only paths ending with the specified text")
+        .option("--mermaid", "render the result as a Mermaid.js diagram")
+        .option("--save <filename>", "save the Mermaid diagram to the specified file")
+        .action(async (options) => {
+        await scan_do(options);
+    });
+}