@fnndsc/chili 3.5.0 → 3.6.0

package/dist/filesystem/fileGroupHandler.d.ts

@@ -13,18 +13,31 @@ import { CLIoptions } from "../utils/cli.js";
  * Handles commands related to groups of ChRIS files, links, or directories.
  */
 export declare class FileGroupHandler {
-    private baseGroupHandler;
     private controller;
     readonly assetName: string;
+    private readonly path?;
     private constructor();
     /**
-     * Factory method to create a new FileGroupHandler instance.
+     * Creates a FileGroupHandler for an asset type. This performs no network work
+     * and resolves no ChRIS context — command registration needs only the asset
+     * name, and the controller is resolved lazily on first use (see
+     * {@link controller_ensure}). Keeping setup cheap means an unrelated command
+     * (or a directory that is not a ChRIS folder) pays no file-context cost.
      *
      * @param assetName - The type of asset to handle ('files', 'links', 'dirs').
-     * @param path - Optional path within ChRIS FS. Defaults to current ChRIS folder context.
-     * @returns A Promise resolving to a new FileGroupHandler instance.
+     * @param path - Optional path within ChRIS FS the controller binds to;
+     *   defaults to the current ChRIS folder context.
+     * @returns A new FileGroupHandler instance.
+     */
+    static handler_create(assetName: string, path?: string): FileGroupHandler;
+    /**
+     * Lazily resolves and memoizes the FileController for this asset against the
+     * bound path (or the current ChRIS context).
+     *
+     * @returns The controller, or null if the context cannot be resolved here
+     *   (e.g. the current directory is not a ChRIS folder).
      */
-    static handler_create(assetName: string, path?: string): Promise<FileGroupHandler>;
+    private controller_ensure;
     /**
      * Lists files, links, or directories using the new command logic.
      */

package/dist/filesystem/fileGroupHandler.js

@@ -17,31 +17,45 @@ import { chiliErrLog, chiliLog } from "../screen/output.js";
  * Handles commands related to groups of ChRIS files, links, or directories.
  */
 export class FileGroupHandler {
-    constructor(controller, assetName) {
-        this.controller = controller;
+    constructor(assetName, path) {
+        // Resolved lazily: only `share` needs a controller; list/fields/delete
+        // re-resolve their context through standalone salsa helpers.
+        this.controller = null;
         this.assetName = assetName;
-        // baseGroupHandler will be used for fieldslist, delete, share until those are refactored
-        this.baseGroupHandler = new BaseGroupHandler(this.assetName, this.controller.chrisObject);
+        this.path = path;
     }
     /**
-     * Factory method to create a new FileGroupHandler instance.
+     * Creates a FileGroupHandler for an asset type. This performs no network work
+     * and resolves no ChRIS context — command registration needs only the asset
+     * name, and the controller is resolved lazily on first use (see
+     * {@link controller_ensure}). Keeping setup cheap means an unrelated command
+     * (or a directory that is not a ChRIS folder) pays no file-context cost.
      *
      * @param assetName - The type of asset to handle ('files', 'links', 'dirs').
-     * @param path - Optional path within ChRIS FS. Defaults to current ChRIS folder context.
-     * @returns A Promise resolving to a new FileGroupHandler instance.
+     * @param path - Optional path within ChRIS FS the controller binds to;
+     *   defaults to the current ChRIS folder context.
+     * @returns A new FileGroupHandler instance.
      */
-    static async handler_create(assetName, path) {
-        try {
-            const controller = await FileController.handler_create(assetName, path);
-            if (controller === null) {
-                throw new Error(`Failed to create FileController for asset type: ${assetName}`);
+    static handler_create(assetName, path) {
+        return new FileGroupHandler(assetName, path);
+    }
+    /**
+     * Lazily resolves and memoizes the FileController for this asset against the
+     * bound path (or the current ChRIS context).
+     *
+     * @returns The controller, or null if the context cannot be resolved here
+     *   (e.g. the current directory is not a ChRIS folder).
+     */
+    async controller_ensure() {
+        if (!this.controller) {
+            try {
+                this.controller = await FileController.handler_create(this.assetName, this.path);
+            }
+            catch {
+                this.controller = null;
             }
-            return new FileGroupHandler(controller, assetName);
-        }
-        catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            throw new Error(`Failed to initialize FileGroupHandler for ${assetName}: ${errorMessage}`);
         }
+        return this.controller;
     }
     /**
      * Lists files, links, or directories using the new command logic.
@@ -137,12 +151,17 @@ export class FileGroupHandler {
      * @param options - CLI options for sharing files.
      */
     async files_share(options) {
+        const controller = await this.controller_ensure();
+        if (!controller) {
+            chiliErrLog(`Cannot share ${this.assetName}: no ChRIS context is available in the current directory.`);
+            return;
+        }
         try {
-            chiliLog(`Sharing ${this.assetName} from ${this.controller.path_get}...`);
+            chiliLog(`Sharing ${this.assetName} from ${controller.path_get}...`);
             if (options.force) {
                 chiliLog("Force sharing enabled");
             }
-            await this.controller.files_share(options);
+            await controller.files_share(options);
         }
         catch (error) {
             if (error instanceof Error) {
@@ -162,7 +181,9 @@ export class FileGroupHandler {
         const fileGroupCommand = program
             .command(this.assetName)
             .description(`Interact with a group of ChRIS ${this.assetName}`);
-        const listCommand = this.baseGroupHandler.baseListCommand_create(async (options) => {
+        // The list command only needs the asset name to register; a context-less
+        // BaseGroupHandler is enough to build it (its actions re-resolve context).
+        const listCommand = new BaseGroupHandler(this.assetName).baseListCommand_create(async (options) => {
             await this.files_list(options);
         });
         // Add path argument and override action to handle it properly

package/dist/filesystem/inodeCommand.js

@@ -19,7 +19,7 @@ export async function inodeCommand_setup(program) {
         const args = command.args.slice(1);
         const subcommand = args[0];
         if (subcommand === "files") {
-            const fileGroupHandler = await FileGroupHandler.handler_create("files", path);
+            const fileGroupHandler = FileGroupHandler.handler_create("files", path);
             const filesProgram = new Command();
             fileGroupHandler.fileGroupCommand_setup(filesProgram);
             await filesProgram.parseAsync(args);

package/dist/handlers/baseGroupHandler.d.ts

@@ -14,8 +14,14 @@ import { TableOptions } from "../screen/screen.js";
 export declare class BaseGroupHandler {
     assetName: string;
     displayOptions: TableOptions;
-    chrisObject: ChRISPluginGroup | ChRISFeedGroup | ChRISEmbeddedResourceGroup<unknown> | ChRISPACSGroup;
-    constructor(assetName: string, chrisObject: ChRISPluginGroup | ChRISFeedGroup | ChRISEmbeddedResourceGroup<unknown> | ChRISPACSGroup);
+    chrisObject: ChRISPluginGroup | ChRISFeedGroup | ChRISEmbeddedResourceGroup<unknown> | ChRISPACSGroup | null;
+    constructor(assetName: string, chrisObject?: ChRISPluginGroup | ChRISFeedGroup | ChRISEmbeddedResourceGroup<unknown> | ChRISPACSGroup | null);
+    /**
+     * The resolved ChRIS context, for use inside actions. Throws if read before
+     * the context has been set — a lazy handler must resolve its context before
+     * an action dereferences it.
+     */
+    private get chrisObjectResolved();
     /**
      * Lists ChRIS resources based on provided CLI options.
      *

package/dist/handlers/baseGroupHandler.js

@@ -15,7 +15,7 @@ import { chiliErrLog, chiliLog } from "../screen/output.js";
  * Provides common functionality for listing and deleting resources.
  */
 export class BaseGroupHandler {
-    constructor(assetName, chrisObject) {
+    constructor(assetName, chrisObject = null) {
         this.assetName = "";
         this.assetName = assetName;
         this.chrisObject = chrisObject;
@@ -23,6 +23,17 @@ export class BaseGroupHandler {
             title: { title: this.assetName, justification: "center" },
         };
     }
+    /**
+     * The resolved ChRIS context, for use inside actions. Throws if read before
+     * the context has been set — a lazy handler must resolve its context before
+     * an action dereferences it.
+     */
+    get chrisObjectResolved() {
+        if (!this.chrisObject) {
+            throw new Error(`ChRIS context for '${this.assetName}' is not available in the current context.`);
+        }
+        return this.chrisObject;
+    }
     /**
      * Lists ChRIS resources based on provided CLI options.
      *
@@ -50,7 +61,7 @@ export class BaseGroupHandler {
                 options.fields = cleanFields.join(',');
             }
             const params = options_toParams(options);
-            const results = await this.chrisObject.asset.resources_listAndFilterByOptions(params);
+            const results = await this.chrisObjectResolved.asset.resources_listAndFilterByOptions(params);
             if (!results) {
                 chiliErrLog(`No ${this.assetName} resources found. Perhaps check your current context?`);
                 return;
@@ -113,7 +124,7 @@ export class BaseGroupHandler {
      */
     async resourceFields_list() {
         try {
-            const results = await this.chrisObject.asset.resourceFields_get();
+            const results = await this.chrisObjectResolved.asset.resourceFields_get();
             if (!results) {
                 chiliErrLog(`An error occurred while fetching resource fields for ${this.assetName}.`);
                 return;
@@ -139,7 +150,7 @@ export class BaseGroupHandler {
      */
     async resourceFields_render() {
         try {
-            const results = await this.chrisObject.asset.resourceFields_get();
+            const results = await this.chrisObjectResolved.asset.resourceFields_get();
             if (!results) {
                 return envelope_error('', undefined, `An error occurred while fetching resource fields for ${this.assetName}.\n`);
             }
@@ -241,7 +252,7 @@ export class BaseGroupHandler {
         let OKorNot = "";
         for (const id of IDs) {
             try {
-                const searchResults = await this.chrisObject.asset.resources_listAndFilterByOptions({
+                const searchResults = await this.chrisObjectResolved.asset.resources_listAndFilterByOptions({
                     id: id,
                 });
                 chiliLog(border_draw(`checking ${this.assetName} id ${id} ... ${this.msg_OKorNot(searchResults)}`));
@@ -251,7 +262,7 @@ export class BaseGroupHandler {
                         continue;
                     }
                 }
-                delop = await this.chrisObject.asset.resourceItem_delete(id);
+                delop = await this.chrisObjectResolved.asset.resourceItem_delete(id);
                 border_draw(`deleting ${this.assetName} id ${id} ... ${this.msg_OKorNot(true)}`);
             }
             catch (error) {
@@ -269,7 +280,7 @@ export class BaseGroupHandler {
      */
     async IDs_getFromSearch(options) {
         const params = options_toParams(options);
-        const searchResults = await this.chrisObject.asset.resources_listAndFilterByOptions(params);
+        const searchResults = await this.chrisObjectResolved.asset.resources_listAndFilterByOptions(params);
         if (!searchResults) {
             return null;
         }

package/dist/plugins/pluginGroupHandler.d.ts

@@ -13,16 +13,27 @@ export declare class PluginContextGroupHandler {
     private baseGroupHandler;
     private controller;
     readonly assetName: string;
+    private readonly id?;
     private constructor();
     /**
-     * Factory method to create a new PluginContextGroupHandler instance.
+     * Creates a PluginContextGroupHandler for an asset type. This performs no
+     * network work and resolves no plugin context — command registration needs
+     * only the asset name; the controller is resolved lazily on first action (see
+     * {@link controller_ensure}).
      *
-     * @param assetName - The type of plugin context to handle ('computesofplugin', 'instancesofplugin', 'parametersofplugin').
-     * @param id - Optional plugin ID. Defaults to current ChRIS plugin context.
-     * @returns A Promise resolving to a new PluginContextGroupHandler instance.
-     * @throws InitializationError if an unsupported asset type is provided.
+     * @param assetName - The type of plugin context ('computesofplugin', 'instancesofplugin', 'parametersofplugin').
+     * @param id - Optional plugin ID the context binds to; defaults to the current plugin context.
+     * @returns A new PluginContextGroupHandler instance.
      */
-    static handler_create(assetName: string, id?: number | null): Promise<PluginContextGroupHandler>;
+    static handler_create(assetName: string, id?: number | null): PluginContextGroupHandler;
+    /**
+     * Lazily resolves and memoizes the plugin-context controller against the bound
+     * plugin id (or the current ChRIS context), wiring it into the
+     * registration-only base handler so its actions can read the context.
+     *
+     * @returns The controller, or null if the context cannot be resolved here.
+     */
+    private controller_ensure;
     /**
      * Lists plugin parameters in a "man page" style format.
      * This is a specialized view for parameters that differs from the standard table view.

package/dist/plugins/pluginGroupHandler.js

@@ -9,39 +9,49 @@ import { PluginContextController } from "../controllers/pluginContextController.
 import { pluginParameters_renderMan, pluginParameters_manRender } from "../views/pluginParameters.js";
 import { envelope_ok, envelope_error } from "@fnndsc/cumin";
 import { chiliErrLog, chiliLog } from "../screen/output.js";
-class InitializationError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "InitializationError";
-    }
-}
 /**
  * Handles commands related to groups of plugin contexts (computes, instances, parameters).
  */
 export class PluginContextGroupHandler {
-    constructor(controller, assetName) {
-        this.baseGroupHandler = null;
-        this.controller = controller;
+    constructor(assetName, id) {
+        // Resolved lazily on first action.
+        this.controller = null;
         this.assetName = assetName;
-        // Cast ChRISEmbeddedResourceGroup to ChRISEmbeddedResourceGroup<unknown> safely.
-        this.baseGroupHandler = new BaseGroupHandler(this.assetName, this.controller.chrisObject);
+        this.id = id;
+        this.baseGroupHandler = new BaseGroupHandler(this.assetName);
     }
     /**
-     * Factory method to create a new PluginContextGroupHandler instance.
+     * Creates a PluginContextGroupHandler for an asset type. This performs no
+     * network work and resolves no plugin context — command registration needs
+     * only the asset name; the controller is resolved lazily on first action (see
+     * {@link controller_ensure}).
      *
-     * @param assetName - The type of plugin context to handle ('computesofplugin', 'instancesofplugin', 'parametersofplugin').
-     * @param id - Optional plugin ID. Defaults to current ChRIS plugin context.
-     * @returns A Promise resolving to a new PluginContextGroupHandler instance.
-     * @throws InitializationError if an unsupported asset type is provided.
+     * @param assetName - The type of plugin context ('computesofplugin', 'instancesofplugin', 'parametersofplugin').
+     * @param id - Optional plugin ID the context binds to; defaults to the current plugin context.
+     * @returns A new PluginContextGroupHandler instance.
      */
-    static async handler_create(assetName, id) {
-        try {
-            const controller = await PluginContextController.controller_create(assetName, id);
-            return new PluginContextGroupHandler(controller, assetName);
-        }
-        catch (error) {
-            throw new InitializationError(`Failed to initialize PluginContextGroupHandler: ${error}`);
+    static handler_create(assetName, id) {
+        return new PluginContextGroupHandler(assetName, id);
+    }
+    /**
+     * Lazily resolves and memoizes the plugin-context controller against the bound
+     * plugin id (or the current ChRIS context), wiring it into the
+     * registration-only base handler so its actions can read the context.
+     *
+     * @returns The controller, or null if the context cannot be resolved here.
+     */
+    async controller_ensure() {
+        if (!this.controller) {
+            try {
+                this.controller = await PluginContextController.controller_create(this.assetName, this.id);
+                this.baseGroupHandler.chrisObject =
+                    this.controller.chrisObject;
+            }
+            catch {
+                this.controller = null;
+            }
         }
+        return this.controller;
     }
     /**
      * Lists plugin parameters in a "man page" style format.
@@ -51,8 +61,13 @@ export class PluginContextGroupHandler {
      */
     async parameters_listMan(options) {
         try {
+            const controller = await this.controller_ensure();
+            if (!controller) {
+                chiliErrLog(`No plugin context is available for ${this.assetName} in the current context.`);
+                return;
+            }
             // We access the asset directly from the controller
-            const asset = this.controller.chrisObject.asset;
+            const asset = controller.chrisObject.asset;
             if (!asset || typeof asset.resources_listAndFilterByOptions !== 'function') {
                 chiliErrLog("Underlying resource does not support listing.");
                 return;
@@ -74,9 +89,12 @@ export class PluginContextGroupHandler {
      * Lists available fields for the current plugin context resource.
      */
     async parameters_fieldsList() {
-        if (this.baseGroupHandler) {
-            await this.baseGroupHandler.resourceFields_list();
+        const controller = await this.controller_ensure();
+        if (!controller) {
+            chiliErrLog(`No plugin context is available for ${this.assetName} in the current context.`);
+            return;
         }
+        await this.baseGroupHandler.resourceFields_list();
     }
     /**
      * Renders plugin parameters in "man page" style as an envelope.
@@ -88,7 +106,11 @@ export class PluginContextGroupHandler {
      */
     async parameters_listManRender(options) {
         try {
-            const asset = this.controller.chrisObject.asset;
+            const controller = await this.controller_ensure();
+            if (!controller) {
+                return envelope_error('', undefined, `No plugin context is available for ${this.assetName} in the current context.\n`);
+            }
+            const asset = controller.chrisObject.asset;
             if (!asset || typeof asset.resources_listAndFilterByOptions !== 'function') {
                 return envelope_error('', undefined, "Underlying resource does not support listing.\n");
             }
@@ -111,10 +133,11 @@ export class PluginContextGroupHandler {
      * @returns An envelope carrying the field listing.
      */
     async parameters_fieldsRender() {
-        if (this.baseGroupHandler) {
-            return this.baseGroupHandler.resourceFields_render();
+        const controller = await this.controller_ensure();
+        if (!controller) {
+            return envelope_ok('');
         }
-        return envelope_ok('');
+        return this.baseGroupHandler.resourceFields_render();
     }
     /**
      * Sets up the Commander.js commands for plugin context group operations.
@@ -122,9 +145,6 @@ export class PluginContextGroupHandler {
      * @param program - The Commander.js program instance.
      */
     pluginContextGroupCommand_setup(program) {
-        if (this.baseGroupHandler) {
-            this.baseGroupHandler.command_setup(program);
-        }
-        const fileGroupCommand = program.commands.find((cmd) => cmd.name() === this.assetName);
+        this.baseGroupHandler.command_setup(program);
     }
 }

package/dist/run.d.ts

@@ -10,6 +10,15 @@
  * @module
  */
 import { type ChiliCaptured } from "./screen/output.js";
+/**
+ * The set of top-level chili command names. Builds a fresh program and registers
+ * every handler — now a cheap, network-free operation — then reads the
+ * registered command names. A host (the brasa engine) uses this to decide
+ * whether an unknown chell command is worth delegating to chili at all.
+ *
+ * @returns The registered top-level command names.
+ */
+export declare function commandNames_get(): Promise<Set<string>>;
 /**
  * Executes a single chili command in the current process.
  *

package/dist/run.js

@@ -25,7 +25,7 @@ import { chefsCommand_setup } from "./chefs/chefs.js";
 import { PACSServerGroupHandler } from "./pacs/pacsServerHandler.js";
 import { PACSQueryGroupHandler } from "./pacs/pacsQueryHandler.js";
 import { PACSRetrieveGroupHandler } from "./pacs/pacsRetrieveHandler.js";
-import { chrisConnection_init, NodeStorageProvider, errorStack_getAllOfType, } from "@fnndsc/cumin";
+import { chrisConnection_init, NodeStorageProvider, } from "@fnndsc/cumin";
 import { FileGroupHandler } from "./filesystem/fileGroupHandler.js";
 import { chiliErrLog, chiliLog, chili_capture } from "./screen/output.js";
 /**
@@ -73,51 +73,32 @@ async function handlers_initialize(program) {
     feedMemberHandler.feedCommand_setup(program);
     const pluginMemberHandler = new PluginMemberHandler();
     pluginMemberHandler.pluginCommand_setup(program);
-    try {
-        const filesGroupHandler = await FileGroupHandler.handler_create("files");
-        filesGroupHandler.fileGroupCommand_setup(program);
-        const linksGroupHandler = await FileGroupHandler.handler_create("links");
-        linksGroupHandler.fileGroupCommand_setup(program);
-        const dirsGroupHandler = await FileGroupHandler.handler_create("dirs");
-        dirsGroupHandler.fileGroupCommand_setup(program);
-    }
-    catch (e) {
-        const err = e instanceof Error ? e.message : String(e);
-        const errors = errorStack_getAllOfType("error");
-        const warnings = errorStack_getAllOfType("warning");
-        chiliLog(`Note: File group commands (files, dirs, links) are unavailable. Reason: ${err}`);
-        if (errors.length > 0) {
-            chiliLog("Errors:");
-            errors.forEach((msg) => chiliLog(`  - ${msg}`));
-        }
-        if (warnings.length > 0) {
-            chiliLog("Warnings:");
-            warnings.forEach((msg) => chiliLog(`  - ${msg}`));
-        }
+    // File-group and plugin-context commands register with no ChRIS context: each
+    // handler resolves its context lazily, only when one of its actions runs. This
+    // keeps setup free of network work, so an unrelated command (or a directory
+    // that is not a ChRIS folder) pays no file-context cost and produces no
+    // context-init noise.
+    for (const assetName of ["files", "links", "dirs"]) {
+        FileGroupHandler.handler_create(assetName).fileGroupCommand_setup(program);
     }
-    try {
-        const computesOfPluginHandler = await PluginContextGroupHandler.handler_create("computesofplugin");
-        computesOfPluginHandler.pluginContextGroupCommand_setup(program);
-        const pluginInstancesHandler = await PluginContextGroupHandler.handler_create("instancesofplugin");
-        pluginInstancesHandler.pluginContextGroupCommand_setup(program);
-        const pluginParametersHandler = await PluginContextGroupHandler.handler_create("parametersofplugin");
-        pluginParametersHandler.pluginContextGroupCommand_setup(program);
-    }
-    catch (e) {
-        const err = e instanceof Error ? e.message : String(e);
-        const errors = errorStack_getAllOfType("error");
-        const warnings = errorStack_getAllOfType("warning");
-        chiliLog(`Note: Plugin context commands are unavailable. Reason: ${err}`);
-        if (errors.length > 0) {
-            chiliLog("Errors:");
-            errors.forEach((msg) => chiliLog(`  - ${msg}`));
-        }
-        if (warnings.length > 0) {
-            chiliLog("Warnings:");
-            warnings.forEach((msg) => chiliLog(`  - ${msg}`));
-        }
+    for (const assetName of ["computesofplugin", "instancesofplugin", "parametersofplugin"]) {
+        PluginContextGroupHandler.handler_create(assetName).pluginContextGroupCommand_setup(program);
     }
 }
+/**
+ * The set of top-level chili command names. Builds a fresh program and registers
+ * every handler — now a cheap, network-free operation — then reads the
+ * registered command names. A host (the brasa engine) uses this to decide
+ * whether an unknown chell command is worth delegating to chili at all.
+ *
+ * @returns The registered top-level command names.
+ */
+export async function commandNames_get() {
+    const program = new Command();
+    connectCommand_setup(program);
+    await handlers_initialize(program);
+    return new Set(program.commands.map((cmd) => cmd.name()));
+}
 /**
  * Extracts a leading `key=value` context string from an argv array.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fnndsc/chili",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "ChILI handles Intelligent Line Interactions: A CLI and library for ChRIS, acting as the controller layer for business logic and user presentation.",
   "repository": {
     "type": "git",