@fnndsc/chell 4.2.8

package/dist/builtins/pluginExecute.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @file Plugin Execute Builtin
+ *
+ * This module implements the builtin for executing plugins "in place"
+ * based on current directory context.
+ *
+ * @module
+ */
+/**
+ * Executes a plugin in the current directory context.
+ *
+ * This function is called when the user types a plugin name that exists in /bin.
+ * It handles parameter parsing, interactive prompts, and delegates execution to salsa.
+ *
+ * @param pluginName - Full plugin name with version (e.g., pl-dcm2niix-v2.1.1).
+ * @param args - Array of command line arguments.
+ * @returns Promise that resolves when execution completes.
+ *
+ * @example
+ * ```typescript
+ * // User types: pl-dcm2niix-v2.1.1 --outputdir results -- feed_title="Brain MRI"
+ * await builtin_executePlugin('pl-dcm2niix-v2.1.1', [
+ *   '--outputdir', 'results', '--', 'feed_title=Brain MRI'
+ * ]);
+ * ```
+ */
+export declare function builtin_executePlugin(pluginName: string, args: string[]): Promise<void>;

package/dist/builtins/pluginExecute.js

@@ -0,0 +1,165 @@
+/**
+ * @file Plugin Execute Builtin
+ *
+ * This module implements the builtin for executing plugins "in place"
+ * based on current directory context.
+ *
+ * @module
+ */
+import { plugin_executeInPlace } from '@fnndsc/salsa';
+import { dictionary_fromCLI, errorStack, procCache_get } from '@fnndsc/cumin';
+import chalk from 'chalk';
+import { session } from '../session/index.js';
+import { vfs } from '../lib/vfs/vfs.js';
+/**
+ * Parses a plugin name from /bin format (name-vVersion) into ChRIS search format.
+ *
+ * @param pluginName - Plugin name in format: pl-name-vX.Y.Z
+ * @returns Search string in format: name_exact:pl-name,version:X.Y.Z
+ *
+ * @example
+ * ```typescript
+ * pluginName_toSearchString('pl-dcm2niix-v1.0.2')
+ * // Returns: 'name_exact:pl-dcm2niix,version:1.0.2'
+ * ```
+ */
+function pluginName_toSearchString(pluginName) {
+    // Pattern: (name)-v(version)
+    const match = pluginName.match(/^(.+)-v(.+)$/);
+    if (match) {
+        const name = match[1];
+        const version = match[2];
+        return `name_exact:${name},version:${version}`;
+    }
+    // Fallback: if no version suffix, search by name only
+    return `name_exact:${pluginName}`;
+}
+/**
+ * Executes a plugin in the current directory context.
+ *
+ * This function is called when the user types a plugin name that exists in /bin.
+ * It handles parameter parsing, interactive prompts, and delegates execution to salsa.
+ *
+ * @param pluginName - Full plugin name with version (e.g., pl-dcm2niix-v2.1.1).
+ * @param args - Array of command line arguments.
+ * @returns Promise that resolves when execution completes.
+ *
+ * @example
+ * ```typescript
+ * // User types: pl-dcm2niix-v2.1.1 --outputdir results -- feed_title="Brain MRI"
+ * await builtin_executePlugin('pl-dcm2niix-v2.1.1', [
+ *   '--outputdir', 'results', '--', 'feed_title=Brain MRI'
+ * ]);
+ * ```
+ */
+export async function builtin_executePlugin(pluginName, args) {
+    try {
+        // 1. Parse arguments - split on '--' delimiter
+        const argsString = args.join(' ');
+        let pluginArgsStr = argsString;
+        let contextArgsStr = '';
+        // Check for ' -- ' delimiter (space-dash-dash-space)
+        const delimiterIndex = argsString.indexOf(' -- ');
+        if (delimiterIndex !== -1) {
+            pluginArgsStr = argsString.substring(0, delimiterIndex);
+            contextArgsStr = argsString.substring(delimiterIndex + 4); // +4 to skip ' -- '
+        }
+        // 2. Parse both sets of parameters
+        let pluginParams = {};
+        let contextParams = {};
+        if (pluginArgsStr.trim()) {
+            try {
+                pluginParams = dictionary_fromCLI(pluginArgsStr);
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                console.error(chalk.red(`Error parsing plugin parameters: ${msg}`));
+                return;
+            }
+        }
+        if (contextArgsStr.trim()) {
+            try {
+                contextParams = dictionary_fromCLI(contextArgsStr);
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                console.error(chalk.red(`Error parsing context parameters: ${msg}`));
+                return;
+            }
+        }
+        // 3. Set default context params if not provided
+        const cwd = await session.getCWD();
+        const isInFeed = cwd.includes('/feeds/feed_');
+        // If no context params provided and not in a feed, use directory name as feed title
+        if (!contextArgsStr && !isInFeed) {
+            const defaultTitle = cwd.split('/').pop() || 'Untitled';
+            contextParams.feed_title = defaultTitle;
+            console.log(chalk.cyan(`Using feed title: "${defaultTitle}" (customize with -- feed_title="Custom Title")`));
+        }
+        // 4. Get /bin listing for finding pl-dircopy
+        const binResult = await vfs.data_get('/bin');
+        if (!binResult.ok) {
+            console.error(chalk.red('Failed to access /bin directory'));
+            return;
+        }
+        const binListing = binResult.value.map((item) => item.name);
+        // 5. Convert plugin name from /bin format to ChRIS search format
+        // Example: pl-dcm2niix-v1.0.2 → name_exact:pl-dcm2niix,version:1.0.2
+        const pluginSearchString = pluginName_toSearchString(pluginName);
+        // 6. Execute via salsa
+        const result = await plugin_executeInPlace(pluginSearchString, pluginParams, contextParams, cwd, binListing);
+        if (!result) {
+            // Display all errors from the stack for better debugging
+            console.error(chalk.red('Plugin execution failed:'));
+            let error = errorStack.stack_pop();
+            while (error) {
+                console.error(chalk.red(`  - ${error.message}`));
+                error = errorStack.stack_pop();
+            }
+            return;
+        }
+        // 7. Push to procCache so /proc reflects new jobs immediately
+        if (result.feedID !== undefined && result.dircopyInstanceID !== undefined) {
+            // New feed: push dircopy root node + plugin node
+            const feedTitle = cwd.split('/').pop() || `feed_${result.feedID}`;
+            procCache_get().feed_add({
+                id: result.feedID, title: feedTitle,
+                creationDate: new Date().toISOString(),
+                finishedJobs: 0, erroredJobs: 0, startedJobs: 0,
+                scheduledJobs: 2, cancelledJobs: 0, createdJobs: 0,
+            });
+            procCache_get().instance_add({
+                id: result.dircopyInstanceID, feedID: result.feedID,
+                parentID: null, pluginName: 'pl-dircopy', params: null,
+            });
+            procCache_get().instance_add({
+                id: result.pluginInstanceID, feedID: result.feedID,
+                parentID: result.dircopyInstanceID, pluginName: result.pluginName, params: null,
+            });
+        }
+        else if (result.parentID !== null) {
+            // Continue feed: push just the new instance
+            const feedID = (() => {
+                const inst = procCache_get().instance_get(result.parentID);
+                return inst ? inst.feedID : null;
+            })();
+            if (feedID !== null) {
+                procCache_get().instance_add({
+                    id: result.pluginInstanceID, feedID,
+                    parentID: result.parentID, pluginName: result.pluginName, params: null,
+                });
+            }
+        }
+        // 8. Render output
+        if (result.feedID) {
+            console.log(chalk.green(`Feed created: ${result.feedID}`));
+        }
+        console.log(chalk.green(`Job scheduled: ${pluginName} (ID: ${result.pluginInstanceID})`));
+        console.log(chalk.cyan(`Output will be in: ${result.outputPath}`));
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        console.error(chalk.red(`Error executing plugin: ${msg}`));
+    }
+}
+//# sourceMappingURL=pluginExecute.js.map

package/dist/builtins/pluginExecute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluginExecute.js","sourceRoot":"","sources":["../../src/builtins/pluginExecute.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,qBAAqB,EAAyB,MAAM,eAAe,CAAC;AAC7E,OAAO,EAAE,kBAAkB,EAAc,UAAU,EAAU,aAAa,EAAE,MAAM,eAAe,CAAC;AAElG,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAExC;;;;;;;;;;;GAWG;AACH,SAAS,yBAAyB,CAAC,UAAkB;IACnD,6BAA6B;IAC7B,MAAM,KAAK,GAA4B,UAAU,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IAExE,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,IAAI,GAAW,KAAK,CAAC,CAAC,CAAC,CAAC;QAC9B,MAAM,OAAO,GAAW,KAAK,CAAC,CAAC,CAAC,CAAC;QACjC,OAAO,cAAc,IAAI,YAAY,OAAO,EAAE,CAAC;IACjD,CAAC;IAED,sDAAsD;IACtD,OAAO,cAAc,UAAU,EAAE,CAAC;AACpC,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,UAAkB,EAClB,IAAc;IAEd,IAAI,CAAC;QACH,+CAA+C;QAC/C,MAAM,UAAU,GAAW,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,aAAa,GAAW,UAAU,CAAC;QACvC,IAAI,cAAc,GAAW,EAAE,CAAC;QAEhC,qDAAqD;QACrD,MAAM,cAAc,GAAW,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC1D,IAAI,cAAc,KAAK,CAAC,CAAC,EAAE,CAAC;YAC1B,aAAa,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;YACxD,cAAc,GAAG,UAAU,CAAC,SAAS,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC,CAAC,oBAAoB;QACjF,CAAC;QAED,mCAAmC;QACnC,IAAI,YAAY,GAAe,EAAE,CAAC;QAClC,IAAI,aAAa,GAAe,EAAE,CAAC;QAEnC,IAAI,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC;YACzB,IAAI,CAAC;gBACH,YAAY,GAAG,kBAAkB,CAAC,aAAa,CAAC,CAAC;YACnD,CAAC;YAAC,OAAO,CAAU,EAAE,CAAC;gBACpB,MAAM,GAAG,GAAW,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;gBAC/D,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,oCAAoC,GAAG,EAAE,CAAC,CAAC,CAAC;gBACpE,OAAO;YACT,CAAC;QACH,CAAC;QAED,IAAI,cAAc,CAAC,IAAI,EAAE,EAAE,CAAC;YAC1B,IAAI,CAAC;gBACH,aAAa,GAAG,kBAAkB,CAAC,cAAc,CAAC,CAAC;YACrD,CAAC;YAAC,OAAO,CAAU,EAAE,CAAC;gBACpB,MAAM,GAAG,GAAW,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;gBAC/D,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,qCAAqC,GAAG,EAAE,CAAC,CAAC,CAAC;gBACrE,OAAO;YACT,CAAC;QACH,CAAC;QAED,gDAAgD;QAChD,MAAM,GAAG,GAAW,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC;QAC3C,MAAM,QAAQ,GAAY,GAAG,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;QAEvD,oFAAoF;QACpF,IAAI,CAAC,cAAc,IAAI,CAAC,QAAQ,EAAE,CAAC;YACjC,MAAM,YAAY,GAAW,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,UAAU,CAAC;YAChE,aAAa,CAAC,UAAU,GAAG,YAAY,CAAC;YACxC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,sBAAsB,YAAY,iDAAiD,CAAC,CAAC,CAAC;QAC/G,CAAC;QAED,6CAA6C;QAC7C,MAAM,SAAS,GAA0B,MAAM,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACpE,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;YAClB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC,CAAC;YAC5D,OAAO;QACT,CAAC;QAED,MAAM,UAAU,GAAa,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAiB,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEnF,iEAAiE;QACjE,qEAAqE;QACrE,MAAM,kBAAkB,GAAW,yBAAyB,CAAC,UAAU,CAAC,CAAC;QAEzE,uBAAuB;QACvB,MAAM,MAAM,GAAiC,MAAM,qBAAqB,CACtE,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,GAAG,EACH,UAAU,CACX,CAAC;QAEF,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,yDAAyD;YACzD,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC,CAAC;YACrD,IAAI,KAAK,GAAG,UAAU,CAAC,SAAS,EAAE,CAAC;YACnC,OAAO,KAAK,EAAE,CAAC;gBACb,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;gBACjD,KAAK,GAAG,UAAU,CAAC,SAAS,EAAE,CAAC;YACjC,CAAC;YACD,OAAO;QACT,CAAC;QAED,8DAA8D;QAC9D,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;YAC1E,iDAAiD;YACjD,MAAM,SAAS,GAAW,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,QAAQ,MAAM,CAAC,MAAM,EAAE,CAAC;YAC1E,aAAa,EAAE,CAAC,QAAQ,CAAC;gBACvB,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,SAAS;gBACnC,YAAY,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACtC,YAAY,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC;gBAC/C,aAAa,EAAE,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC;aACnD,CAAC,CAAC;YACH,aAAa,EAAE,CAAC,YAAY,CAAC;gBAC3B,EAAE,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM;gBACnD,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI;aACvD,CAAC,CAAC;YACH,aAAa,EAAE,CAAC,YAAY,CAAC;gBAC3B,EAAE,EAAE,MAAM,CAAC,gBAAgB,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM;gBAClD,QAAQ,EAAE,MAAM,CAAC,iBAAiB,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI;aAChF,CAAC,CAAC;QACL,CAAC;aAAM,IAAI,MAAM,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;YACpC,4CAA4C;YAC5C,MAAM,MAAM,GAAkB,CAAC,GAAG,EAAE;gBAClC,MAAM,IAAI,GAAG,aAAa,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,QAAS,CAAC,CAAC;gBAC5D,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;YACnC,CAAC,CAAC,EAAE,CAAC;YACL,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBACpB,aAAa,EAAE,CAAC,YAAY,CAAC;oBAC3B,EAAE,EAAE,MAAM,CAAC,gBAAgB,EAAE,MAAM;oBACnC,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI;iBACvE,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,mBAAmB;QACnB,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAClB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,iBAAiB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QAC7D,CAAC;QACD,OAAO,CAAC,GAAG,CACT,KAAK,CAAC,KAAK,CACT,kBAAkB,UAAU,SAAS,MAAM,CAAC,gBAAgB,GAAG,CAChE,CACF,CAAC;QACF,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,sBAAsB,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;IACrE,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,MAAM,GAAG,GAAW,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC3E,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,2BAA2B,GAAG,EAAE,CAAC,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC"}

package/dist/builtins/proc.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Handles proc commands.
+ *
+ * @param args - command arguments.
+ */
+export declare function builtin_proc(args: string[]): Promise<void>;

package/dist/builtins/proc.helpers.d.ts

@@ -0,0 +1,68 @@
+import type { ProcFeed } from '@fnndsc/cumin';
+/**
+ * Flat record representing one feed entry for resource-group-style listing.
+ * All ProcFeed counter fields exposed as first-class columns.
+ */
+export interface ProcJobEntry {
+    id: number;
+    title: string;
+    status: string;
+    finishedJobs: number;
+    erroredJobs: number;
+    startedJobs: number;
+    scheduledJobs: number;
+    cancelledJobs: number;
+    createdJobs: number;
+    creationDate: string;
+    instances: number | string;
+    [key: string]: unknown;
+}
+/** All job fields available for `proc jobs` listing. */
+export declare const ALL_JOB_FIELDS: ReadonlyArray<string>;
+/** Default columns shown for `proc jobs` listing. */
+export declare const DEFAULT_JOB_FIELDS: ReadonlyArray<string>;
+/**
+ * Derives an aggregate status label for a feed from its job counters.
+ *
+ * @param feed - The feed whose counters are inspected.
+ * @returns A status label (e.g. `running`, `finishedWithError`).
+ */
+export declare function feedStatus_derive(feed: ProcFeed): string;
+/**
+ * Colorizes a status label for terminal display.
+ *
+ * @param status - The status label.
+ * @returns The colorized status string.
+ */
+export declare function statusColor(status: string): string;
+/**
+ * Resolves the selected fields for a listing from a `--fields` argument,
+ * falling back to the default set.
+ *
+ * @param fieldsArg - Comma-separated field names (may be empty).
+ * @returns The selected field names.
+ */
+export declare function jobFields_select(fieldsArg: string): string[];
+/**
+ * Filters job entries by a case-insensitive title substring.
+ *
+ * @param entries - The entries to filter.
+ * @param search - The search substring (empty returns all).
+ * @returns The matching entries.
+ */
+export declare function procEntries_filterBySearch(entries: ProcJobEntry[], search: string): ProcJobEntry[];
+/**
+ * Renders job entries as CSV with quoted fields.
+ *
+ * @param rows - The entries to render.
+ * @param fields - The columns to include, in order.
+ * @returns The CSV string (header row plus data rows).
+ */
+export declare function procCsv_render(rows: ProcJobEntry[], fields: string[]): string;
+/**
+ * Parses a feed identifier of the form `123` or `feed_123`.
+ *
+ * @param arg - The feed argument.
+ * @returns The numeric feed ID, or null if malformed.
+ */
+export declare function feedId_parse(arg: string): number | null;

package/dist/builtins/proc.helpers.js

@@ -0,0 +1,102 @@
+/**
+ * @file Pure helpers for the `proc` builtin.
+ *
+ * Status derivation/coloring, field selection, search filtering, CSV rendering,
+ * and feed-id parsing — all dependency-free (chalk only) for unit testing.
+ *
+ * @module
+ */
+import chalk from 'chalk';
+/** All job fields available for `proc jobs` listing. */
+export const ALL_JOB_FIELDS = [
+    'id', 'title', 'status',
+    'finishedJobs', 'erroredJobs', 'startedJobs',
+    'scheduledJobs', 'cancelledJobs', 'createdJobs',
+    'creationDate', 'instances',
+];
+/** Default columns shown for `proc jobs` listing. */
+export const DEFAULT_JOB_FIELDS = [
+    'id', 'title', 'status', 'finishedJobs', 'erroredJobs',
+];
+/**
+ * Derives an aggregate status label for a feed from its job counters.
+ *
+ * @param feed - The feed whose counters are inspected.
+ * @returns A status label (e.g. `running`, `finishedWithError`).
+ */
+export function feedStatus_derive(feed) {
+    if (feed.erroredJobs > 0)
+        return 'finishedWithError';
+    if (feed.startedJobs + feed.scheduledJobs + feed.createdJobs > 0)
+        return 'running';
+    if (feed.cancelledJobs > 0 && feed.finishedJobs === 0)
+        return 'cancelled';
+    if (feed.finishedJobs > 0)
+        return 'finishedSuccessfully';
+    return 'empty';
+}
+/**
+ * Colorizes a status label for terminal display.
+ *
+ * @param status - The status label.
+ * @returns The colorized status string.
+ */
+export function statusColor(status) {
+    if (status === 'finishedSuccessfully')
+        return chalk.green(status);
+    if (status === 'finishedWithError')
+        return chalk.red(status);
+    if (status === 'running')
+        return chalk.yellow(status);
+    if (status === 'cancelled')
+        return chalk.dim(status);
+    return chalk.gray(status);
+}
+/**
+ * Resolves the selected fields for a listing from a `--fields` argument,
+ * falling back to the default set.
+ *
+ * @param fieldsArg - Comma-separated field names (may be empty).
+ * @returns The selected field names.
+ */
+export function jobFields_select(fieldsArg) {
+    return fieldsArg
+        ? fieldsArg.split(',').map((f) => f.trim()).filter(Boolean)
+        : [...DEFAULT_JOB_FIELDS];
+}
+/**
+ * Filters job entries by a case-insensitive title substring.
+ *
+ * @param entries - The entries to filter.
+ * @param search - The search substring (empty returns all).
+ * @returns The matching entries.
+ */
+export function procEntries_filterBySearch(entries, search) {
+    if (!search)
+        return entries;
+    const lower = search.toLowerCase();
+    return entries.filter((e) => e.title.toLowerCase().includes(lower));
+}
+/**
+ * Renders job entries as CSV with quoted fields.
+ *
+ * @param rows - The entries to render.
+ * @param fields - The columns to include, in order.
+ * @returns The CSV string (header row plus data rows).
+ */
+export function procCsv_render(rows, fields) {
+    const header = fields.map((f) => `"${f}"`).join(',');
+    const body = rows.map((e) => fields.map((f) => `"${String(e[f] ?? '').replace(/"/g, '""')}"`).join(',')).join('\n');
+    return [header, body].join('\n');
+}
+/**
+ * Parses a feed identifier of the form `123` or `feed_123`.
+ *
+ * @param arg - The feed argument.
+ * @returns The numeric feed ID, or null if malformed.
+ */
+export function feedId_parse(arg) {
+    const match = arg.match(/^(?:feed_)?(\d+)$/);
+    return match ? parseInt(match[1], 10) : null;
+}
+//# sourceMappingURL=proc.helpers.js.map

package/dist/builtins/proc.helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proc.helpers.js","sourceRoot":"","sources":["../../src/builtins/proc.helpers.ts"],"names":[],"mappings":"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"}

package/dist/builtins/proc.js

@@ -0,0 +1,289 @@
+/**
+ * @file Builtin proc command.
+ * Manages the /proc VFS cache (job monitoring).
+ */
+import chalk from 'chalk';
+import { procCache_refresh, procFeed_ensureLoaded, jobs_find } from '@fnndsc/salsa';
+import { procCache_get } from '@fnndsc/cumin';
+import { spinner } from '../lib/spinner.js';
+import { commandArgs_process } from './utils.js';
+import { list_applySort } from '@fnndsc/chili/utils/sort.js';
+import { screen, table_display } from '@fnndsc/chili/screen/screen.js';
+import { ALL_JOB_FIELDS, feedStatus_derive, statusColor, jobFields_select, procEntries_filterBySearch, procCsv_render, feedId_parse, } from './proc.helpers.js';
+// ── proc jobs ─────────────────────────────────────────────────────────────────
+/**
+ * Builds flat job entries from the proc cache.
+ *
+ * @param cache - The proc cache.
+ * @returns One entry per known feed.
+ */
+function procEntries_fromCache(cache) {
+    return cache.feedIDs_get().map((feedID) => {
+        const feed = cache.feed_get(feedID);
+        const topoLoaded = cache.topologyLoaded_has(feedID);
+        return {
+            id: feed.id,
+            title: feed.title,
+            status: feedStatus_derive(feed),
+            finishedJobs: feed.finishedJobs,
+            erroredJobs: feed.erroredJobs,
+            startedJobs: feed.startedJobs,
+            scheduledJobs: feed.scheduledJobs,
+            cancelledJobs: feed.cancelledJobs,
+            createdJobs: feed.createdJobs,
+            creationDate: feed.creationDate ? feed.creationDate.substring(0, 10) : '',
+            instances: topoLoaded ? cache.instancesForFeed_count(feedID) : '-',
+        };
+    });
+}
+/**
+ * Renders job entries as a bordered table.
+ *
+ * @param page - The entries to render.
+ * @param selectedFields - The columns to show.
+ */
+function procJobs_renderTable(page, selectedFields) {
+    const tableData = page.map((e) => {
+        const row = {};
+        selectedFields.forEach((f) => { row[f] = e[f] ?? ''; });
+        return row;
+    });
+    console.log(screen.table_output(tableData, {
+        head: selectedFields,
+        title: { title: 'proc jobs', justification: 'center' },
+        typeColors: { string: 'green', number: 'yellow', boolean: 'cyan', object: 'magenta' },
+    }));
+}
+/**
+ * Renders job entries as colorized, tab-separated lines.
+ *
+ * @param page - The entries to render.
+ * @param selectedFields - The columns to show.
+ */
+function procJobs_renderLines(page, selectedFields) {
+    for (const e of page) {
+        const cols = selectedFields.map((f) => {
+            const val = String(e[f] ?? '');
+            if (f === 'id')
+                return chalk.bold(val);
+            if (f === 'title')
+                return chalk.cyan(val);
+            if (f === 'status')
+                return statusColor(val);
+            if (f === 'erroredJobs' && e.erroredJobs > 0)
+                return chalk.red(val);
+            return val;
+        });
+        console.log(cols.join('\t'));
+    }
+}
+/**
+ * Handles `proc jobs [inspect|list]`: lists cached feed jobs with optional
+ * search, sort, paging, field selection, and CSV/table output.
+ *
+ * @param args - Arguments following `proc jobs`.
+ */
+async function jobs_subcmd(args) {
+    const second = args[0];
+    if (second === 'inspect') {
+        table_display([...ALL_JOB_FIELDS].map((f) => ({ field: f })), ['field'], { title: { title: 'proc jobs fields', justification: 'center' } });
+        return;
+    }
+    const listArgs = second === 'list' ? args.slice(1) : args;
+    const parsed = commandArgs_process(listArgs);
+    let entries = procEntries_fromCache(procCache_get());
+    entries = procEntries_filterBySearch(entries, String(parsed['search'] ?? ''));
+    if (entries.length === 0) {
+        console.log(chalk.gray('No feeds in cache.'));
+        return;
+    }
+    const sortField = String(parsed['sort'] ?? '');
+    if (sortField)
+        entries = list_applySort(entries, sortField, !!parsed['reverse']);
+    const showAll = !!parsed['all'];
+    const limit = showAll ? entries.length : Math.max(1, Number(parsed['limit'] ?? 20));
+    const page = entries.slice(0, limit);
+    const selectedFields = jobFields_select(String(parsed['fields'] ?? ''));
+    if (parsed['csv']) {
+        console.log(procCsv_render(page, selectedFields));
+        return;
+    }
+    if (parsed['table']) {
+        procJobs_renderTable(page, selectedFields);
+        return;
+    }
+    procJobs_renderLines(page, selectedFields);
+    if (!showAll && entries.length > limit) {
+        console.log(chalk.gray(`  … ${entries.length - limit} more. Use --all or --limit <n>.`));
+    }
+}
+// ── proc subcommand handlers ────────────────────────────────────────────────
+/**
+ * Handles `proc refresh [feed]`: refreshes the cache for one feed or all.
+ *
+ * @param args - Full command args (`args[1]` is the optional feed).
+ */
+async function procRefresh_handle(args) {
+    const feedArg = args[1];
+    let feedID;
+    if (feedArg) {
+        const parsedId = feedId_parse(feedArg);
+        if (parsedId === null) {
+            console.error(chalk.red(`proc refresh: invalid feed ID '${feedArg}'`));
+            return;
+        }
+        feedID = parsedId;
+    }
+    const scope = feedID !== undefined ? `feed_${feedID}` : 'all feeds';
+    spinner.start(`Refreshing /proc cache (${scope})...`);
+    try {
+        await procCache_refresh(feedID);
+        spinner.stop();
+        console.log(chalk.green(`/proc cache refreshed (${scope})`));
+    }
+    catch (error) {
+        spinner.stop();
+        const msg = error instanceof Error ? error.message : String(error);
+        console.error(chalk.red(`proc refresh failed: ${msg}`));
+    }
+}
+/**
+ * Handles `proc find <query>`: locates instances by id/plugin-name and prints
+ * their /proc paths.
+ *
+ * @param args - Full command args (`args[1]` is the query).
+ */
+async function procFind_handle(args) {
+    const query = args[1];
+    if (!query) {
+        console.error(chalk.red('Usage: proc find <instance_id | plugin_name_substring>'));
+        return;
+    }
+    spinner.start(`Finding "${query}"...`);
+    try {
+        const cache = procCache_get();
+        const result = await jobs_find(query);
+        if (!result.ok) {
+            spinner.stop();
+            console.error(chalk.red(`Search failed.`));
+            return;
+        }
+        const matches = result.value;
+        if (matches.length === 0) {
+            spinner.stop();
+            console.error(chalk.yellow(`No instances found matching "${query}".`));
+            return;
+        }
+        const feedIDs = [...new Set(matches.map((m) => m.feedID))];
+        await Promise.all(feedIDs.map((feedID) => procFeed_ensureLoaded(feedID)));
+        spinner.stop();
+        for (const m of matches) {
+            const path = cache.path_build(m.id);
+            if (path)
+                console.log(path);
+        }
+    }
+    catch (error) {
+        spinner.stop();
+        const msg = error instanceof Error ? error.message : String(error);
+        console.error(chalk.red(`proc find failed: ${msg}`));
+    }
+}
+/**
+ * Handles `proc feeds <query>`: lists cached feeds whose title matches.
+ *
+ * @param args - Full command args (`args[1]` is the query).
+ */
+async function procFeeds_handle(args) {
+    const query = args[1];
+    if (!query) {
+        console.error(chalk.red('Usage: proc feeds <title_substring>'));
+        return;
+    }
+    const cache = procCache_get();
+    const matches = cache.feeds_find(query);
+    if (matches.length === 0) {
+        console.error(chalk.yellow(`No feeds found with title containing "${query}".`));
+        return;
+    }
+    for (const feed of matches) {
+        const status = feedStatus_derive(feed);
+        console.log(`/proc/jobs/feed_${feed.id}  ${statusColor(status)}  ${chalk.dim(feed.title)}`);
+    }
+}
+/**
+ * Handles `proc stat [feed]`: prints a cache summary or a single feed's detail.
+ *
+ * @param args - Full command args (`args[1]` is the optional feed).
+ */
+async function procStat_handle(args) {
+    const cache = procCache_get();
+    const feedArg = args[1];
+    if (!feedArg) {
+        const warmup = cache.warmupProgress_get();
+        const warmupLine = warmup.active
+            ? chalk.yellow(`in progress (${warmup.loaded} instances loaded)`)
+            : cache.warmupComplete
+                ? chalk.green('complete')
+                : chalk.dim('not started');
+        console.log(chalk.bold('proc cache summary'));
+        console.log(`  feeds known    : ${chalk.cyan(String(cache.feedIDs_get().length))}`);
+        console.log(`  instances      : ${chalk.cyan(String(cache.instances_count()))}`);
+        console.log(`  topology sweep : ${warmupLine}`);
+        return;
+    }
+    const feedID = feedId_parse(feedArg);
+    if (feedID === null) {
+        console.error(chalk.red(`proc stat: invalid feed ID '${feedArg}'`));
+        return;
+    }
+    const feed = cache.feed_get(feedID);
+    if (!feed) {
+        console.error(chalk.yellow(`proc stat: feed_${feedID} not in cache`));
+        return;
+    }
+    const topoLoaded = cache.topologyLoaded_has(feedID);
+    const instCount = topoLoaded ? cache.instancesForFeed_count(feedID) : -1;
+    const status = feedStatus_derive(feed);
+    console.log(chalk.bold(`feed_${feedID}`));
+    console.log(`  title          : ${chalk.cyan(feed.title)}`);
+    console.log(`  status         : ${statusColor(status)}`);
+    console.log(`  finishedJobs   : ${feed.finishedJobs}`);
+    console.log(`  erroredJobs    : ${chalk[feed.erroredJobs > 0 ? 'red' : 'white'](String(feed.erroredJobs))}`);
+    console.log(`  startedJobs    : ${feed.startedJobs}`);
+    console.log(`  scheduledJobs  : ${feed.scheduledJobs}`);
+    console.log(`  cancelledJobs  : ${feed.cancelledJobs}`);
+    console.log(`  createdJobs    : ${feed.createdJobs}`);
+    console.log(`  topology       : ${topoLoaded ? chalk.green(`loaded (${instCount} instances)`) : chalk.dim('not loaded')}`);
+}
+// ── Main dispatcher ───────────────────────────────────────────────────────────
+/**
+ * Handles proc commands.
+ *
+ * @param args - command arguments.
+ */
+export async function builtin_proc(args) {
+    const subcommand = args[0];
+    if (!subcommand || subcommand === 'refresh') {
+        await procRefresh_handle(args);
+        return;
+    }
+    if (subcommand === 'jobs') {
+        await jobs_subcmd(args.slice(1));
+        return;
+    }
+    if (subcommand === 'find') {
+        await procFind_handle(args);
+        return;
+    }
+    if (subcommand === 'feeds') {
+        await procFeeds_handle(args);
+        return;
+    }
+    if (subcommand === 'stat') {
+        await procStat_handle(args);
+        return;
+    }
+    console.error(chalk.red(`proc: unknown subcommand '${subcommand}'. Use proc --help.`));
+}
+//# sourceMappingURL=proc.js.map