@qodalis/cli 2.0.0-beta.8 → 2.0.0-beta.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qodalis/cli",
-  "version": "2.0.0-beta.8",
+  "version": "2.0.0-beta.9",
   "description": "Framework-agnostic CLI engine for @qodalis terminal applications.",
   "author": "Nicolae Lupei, Qodalis Solutions",
   "license": "MIT",
@@ -30,7 +30,7 @@
     "./assets/*": "./assets/*"
   },
   "dependencies": {
-    "@qodalis/cli-core": "2.0.0-beta.8",
+    "@qodalis/cli-core": "2.0.0-beta.9",
     "@xterm/xterm": "^5.5.0",
     "@xterm/addon-fit": "^0.10.0",
     "@xterm/addon-web-links": "^0.11.0",

package/public-api.d.mts

@@ -1,5 +1,5 @@
 import * as _qodalis_cli_core from '@qodalis/cli-core';
-import { ICliCommandProcessor, ICliCommandParameterDescriptor, ICliCommandProcessorRegistry, ICliCommandChildProcessor, CliProcessorMetadata, CliStateConfiguration, ICliExecutionContext, CliProcessCommand, ICliCommandAuthor, CliThemeInfo, ICliExecutionProcess, ICliUserSession, ICliSpinner, ICliPercentageProgressBar, ICliTextAnimator, ICliTerminalWriter, ICliCommandExecutorService, ICliClipboard, ICliStateStore, CliOptions, ICliLogger, ICliServiceProvider, ICliTranslationService, ICliInputReader, ICliBackgroundServiceRegistry, ICliManagedInterval, ICliManagedTimer, ICliKeyValueStore, ICliCompletionProvider, ICliFilePickerProvider, ICliGlobalParameterHandler, CliProvider, CliForegroundColor, CliBackgroundColor, CliLogLevel, CliPercentageProgressBarUpdateValueOptions, CliTextAnimatorOptions, ICliModule, CliModuleRegistry, Package, ICliPingServerService, CliLineOptions, CliSelectOption, CliSelectOptions, CliMultiSelectOption, CliMultiSelectOptions, CliDateOptions, CliFilePickerOptions, CliFileResult, ICliProcessRegistry, ICliProcessRegisterOptions, ICliProcessEntry, ICliDragDropService, CliState, CliEngineSnapshot, CliServerConfig, CliServerCommandDescriptor, CliServerCapabilities, CliServerResponse, CliIcon } from '@qodalis/cli-core';
+import { ICliCommandProcessor, ICliCommandParameterDescriptor, ICliCommandProcessorRegistry, ICliCommandChildProcessor, CliProcessorMetadata, CliStateConfiguration, ICliExecutionContext, CliProcessCommand, ICliCommandAuthor, CliThemeInfo, ICliExecutionProcess, ICliUserSession, ICliSpinner, ICliPercentageProgressBar, ICliTextAnimator, ICliTerminalWriter, ICliCommandExecutorService, ICliClipboard, ICliStateStore, CliOptions, ICliLogger, ICliServiceProvider, ICliTranslationService, ICliInputReader, ICliBackgroundServiceRegistry, ICliManagedInterval, ICliManagedTimer, ICliKeyValueStore, ICliCompletionProvider, ICliFilePickerProvider, ICliGlobalParameterHandler, CliProvider, CliForegroundColor, CliBackgroundColor, CliLogLevel, CliPercentageProgressBarUpdateValueOptions, CliTextAnimatorOptions, ICliModule, CliModuleRegistry, Package, ICliPingServerService, CliLineOptions, CliSelectOption, CliSelectOptions, CliMultiSelectOption, CliMultiSelectOptions, CliNumberOptions, CliDateOptions, CliFilePickerOptions, CliFileResult, ICliProcessRegistry, ICliProcessRegisterOptions, ICliProcessEntry, ICliDragDropService, CliState, CliEngineSnapshot, CliServerConfig, CliServerCommandDescriptor, CliServerCapabilities, CliServerResponse, CliIcon } from '@qodalis/cli-core';
 export { ICliUserSessionService_TOKEN, ICliUsersStoreService_TOKEN } from '@qodalis/cli-core';
 import { ITheme, Terminal, ITerminalAddon, ITerminalOptions, ITerminalInitOnlyOptions } from '@xterm/xterm';
 import { Subject, Observable, Subscription } from 'rxjs';
@@ -140,7 +140,7 @@ declare const CliBackgroundServiceRegistry_TOKEN = "cli-background-service-regis
  */
 declare const CliPackageManagerService_TOKEN = "cli-package-manager-service";
 
-declare const LIBRARY_VERSION = "2.0.0-beta.8";
+declare const LIBRARY_VERSION = "2.0.0-beta.9";
 declare const API_VERSION = 2;
 
 declare class CliAliasCommandProcessor implements ICliCommandProcessor {
@@ -984,6 +984,11 @@ declare class CliStateStoreManager implements ICliStateStoreManager {
         name: string;
         state: Record<string, any>;
     }[];
+    /**
+     * Dispose all stores (completes their BehaviorSubjects).
+     * Called during engine teardown.
+     */
+    dispose(): void;
 }
 
 /**
@@ -1191,8 +1196,10 @@ declare class CliExecutionContext implements ICliExecutionContext, InputModeHost
     readonly commandHistory: CliCommandHistory;
     readonly filePickerProvider: ICliFilePickerProvider;
     private readonly modeStack;
+    private readonly stateStoreManager;
     private readonly managedTimers;
     private resizeDisposable;
+    private windowKeydownListener?;
     constructor(deps: CliExecutionContextDeps, terminal: Terminal, executor: ICliCommandExecutorService, cliOptions?: CliOptions);
     writeToTerminal(text: string): void;
     getTerminalRows(): number;
@@ -1258,7 +1265,6 @@ declare class CliCommandExecutor implements ICliCommandExecutorService {
     protected readonly registry: ICliCommandProcessorRegistry;
     private commandParser;
     private globalParameters;
-    private lastCapturingWriter?;
     constructor(registry: ICliCommandProcessorRegistry);
     registerGlobalParameter(handler: ICliGlobalParameterHandler): void;
     getGlobalParameters(): ICliCommandParameterDescriptor[];
@@ -1405,6 +1411,13 @@ declare class CliTerminalWriter implements ICliTerminalWriter {
         columns?: number;
         padding?: number;
     }): void;
+    writeLink(text: string, url: string): void;
+    writeBox(content: string | string[], options?: {
+        title?: string;
+        borderColor?: CliForegroundColor;
+        padding?: number;
+    }): void;
+    writeIndented(text: string, level?: number): void;
     writeTable(headers: string[], rows: string[][]): void;
 }
 
@@ -1506,6 +1519,7 @@ declare class CliBoot {
     private initializing;
     private readonly moduleRegistry;
     private readonly bootedModules;
+    private readonly initializedProcessors;
     constructor(registry: ICliCommandProcessorRegistry, services: ICliServiceProvider);
     /**
      * Get the module registry for external access.
@@ -1576,6 +1590,13 @@ declare class ScriptLoaderService {
         content?: string;
         error?: any;
     }>;
+    /**
+     * Inject an inline script into the page.
+     *
+     * **Security:** This runs `code` in the host page context with full
+     * DOM access. Only call with trusted content (e.g. verified UMD bundles
+     * loaded via the package manager). Never pass user-supplied strings.
+     */
     injectBodyScript(code: string): void;
     /**
      * Returns CDN URLs for a given npm package path.
@@ -1606,14 +1627,18 @@ declare class CliPackageManagerService {
     private readonly storageKey;
     QODALIS_COMMAND_PREFIX: string;
     private store;
+    /** In-memory cache; `null` means "not yet loaded from storage". */
+    private cache;
+    /** Whether the one-time localStorage migration has been checked. */
+    private migrationDone;
     constructor();
     /**
      * Set the key-value store instance for persistence.
      */
     setStore(store: ICliKeyValueStore): void;
     /**
-     * Retrieves the list of packages
-     * @returns {Package[]} Array of packages
+     * Retrieves the list of packages.
+     * Uses an in-memory cache after the first load.
      */
     getPackages(): Promise<Package[]>;
     /**
@@ -1656,11 +1681,7 @@ declare class CliInputReader implements ICliInputReader {
     readSelect(prompt: string, options: CliSelectOption[], selectOptions?: CliSelectOptions): Promise<string | null>;
     readSelectInline(prompt: string, options: CliSelectOption[], selectOptions?: CliSelectOptions): Promise<string | null>;
     readMultiSelect(prompt: string, options: CliMultiSelectOption[], selectOptions?: CliMultiSelectOptions): Promise<string[] | null>;
-    readNumber(prompt: string, options?: {
-        min?: number;
-        max?: number;
-        default?: number;
-    }): Promise<number | null>;
+    readNumber(prompt: string, options?: CliNumberOptions): Promise<number | null>;
     readDate(prompt: string, options?: CliDateOptions): Promise<string | null>;
     readFile(prompt: string, options?: CliFilePickerOptions): Promise<CliFileResult[] | null>;
 }
@@ -1717,6 +1738,13 @@ declare class CapturingTerminalWriter implements ICliTerminalWriter {
         columns?: number;
         padding?: number;
     }): void;
+    writeLink(text: string, url: string): void;
+    writeBox(content: string | string[], options?: {
+        title?: string;
+        borderColor?: CliForegroundColor;
+        padding?: number;
+    }): void;
+    writeIndented(text: string, level?: number): void;
     /**
      * Returns true if any stdout-equivalent output was captured.
      */
@@ -1871,6 +1899,11 @@ declare class CliStateStore implements ICliStateStore {
     reset(): void;
     persist(): Promise<void>;
     initialize(): Promise<void>;
+    /**
+     * Complete the BehaviorSubject so all subscribers are notified
+     * and no further emissions occur. Called during engine teardown.
+     */
+    dispose(): void;
 }
 
 interface CliEngineOptions extends CliOptions {
@@ -1974,9 +2007,12 @@ declare class CliEngine {
      * so intermediate resize events cannot leave stale artefacts.
      */
     private deferResizeFix;
+    /** Maximum time (ms) to wait for container layout before rejecting. */
+    private static readonly LAYOUT_TIMEOUT_MS;
     /**
      * Wait until the container element has non-zero dimensions.
      * xterm.js requires the host element to be laid out before open() is called.
+     * Rejects after {@link LAYOUT_TIMEOUT_MS} if the container stays hidden.
      */
     private waitForLayout;
 }
@@ -1984,12 +2020,13 @@ declare class CliEngine {
 declare class CliServerConnection {
     private readonly _config;
     private readonly _backgroundServices?;
+    private readonly _logger?;
     private _connected;
     private _commands;
     private _capabilities;
     private _eventSocket;
     onDisconnect?: () => void;
-    constructor(_config: CliServerConfig, _backgroundServices?: ICliBackgroundServiceRegistry | undefined);
+    constructor(_config: CliServerConfig, _backgroundServices?: ICliBackgroundServiceRegistry | undefined, _logger?: ICliLogger | undefined);
     get config(): CliServerConfig;
     get connected(): boolean;
     get commands(): CliServerCommandDescriptor[];
@@ -2065,6 +2102,7 @@ declare class CliServerManager implements DefaultServerProvider {
     private readonly registry;
     readonly connections: Map<string, CliServerConnection>;
     private _logger?;
+    private _cliLogger?;
     private _defaultServer;
     private _backgroundServices?;
     constructor(registry: ICliCommandProcessorRegistry);
@@ -2073,7 +2111,7 @@ declare class CliServerManager implements DefaultServerProvider {
     connectAll(servers: CliServerConfig[], logger?: {
         warn(msg: string): void;
         info(msg: string): void;
-    }, backgroundServices?: ICliBackgroundServiceRegistry): Promise<void>;
+    }, backgroundServices?: ICliBackgroundServiceRegistry, cliLogger?: ICliLogger): Promise<void>;
     reconnect(name: string): Promise<{
         success: boolean;
         commandCount: number;

package/public-api.d.ts

@@ -1,5 +1,5 @@
 import * as _qodalis_cli_core from '@qodalis/cli-core';
-import { ICliCommandProcessor, ICliCommandParameterDescriptor, ICliCommandProcessorRegistry, ICliCommandChildProcessor, CliProcessorMetadata, CliStateConfiguration, ICliExecutionContext, CliProcessCommand, ICliCommandAuthor, CliThemeInfo, ICliExecutionProcess, ICliUserSession, ICliSpinner, ICliPercentageProgressBar, ICliTextAnimator, ICliTerminalWriter, ICliCommandExecutorService, ICliClipboard, ICliStateStore, CliOptions, ICliLogger, ICliServiceProvider, ICliTranslationService, ICliInputReader, ICliBackgroundServiceRegistry, ICliManagedInterval, ICliManagedTimer, ICliKeyValueStore, ICliCompletionProvider, ICliFilePickerProvider, ICliGlobalParameterHandler, CliProvider, CliForegroundColor, CliBackgroundColor, CliLogLevel, CliPercentageProgressBarUpdateValueOptions, CliTextAnimatorOptions, ICliModule, CliModuleRegistry, Package, ICliPingServerService, CliLineOptions, CliSelectOption, CliSelectOptions, CliMultiSelectOption, CliMultiSelectOptions, CliDateOptions, CliFilePickerOptions, CliFileResult, ICliProcessRegistry, ICliProcessRegisterOptions, ICliProcessEntry, ICliDragDropService, CliState, CliEngineSnapshot, CliServerConfig, CliServerCommandDescriptor, CliServerCapabilities, CliServerResponse, CliIcon } from '@qodalis/cli-core';
+import { ICliCommandProcessor, ICliCommandParameterDescriptor, ICliCommandProcessorRegistry, ICliCommandChildProcessor, CliProcessorMetadata, CliStateConfiguration, ICliExecutionContext, CliProcessCommand, ICliCommandAuthor, CliThemeInfo, ICliExecutionProcess, ICliUserSession, ICliSpinner, ICliPercentageProgressBar, ICliTextAnimator, ICliTerminalWriter, ICliCommandExecutorService, ICliClipboard, ICliStateStore, CliOptions, ICliLogger, ICliServiceProvider, ICliTranslationService, ICliInputReader, ICliBackgroundServiceRegistry, ICliManagedInterval, ICliManagedTimer, ICliKeyValueStore, ICliCompletionProvider, ICliFilePickerProvider, ICliGlobalParameterHandler, CliProvider, CliForegroundColor, CliBackgroundColor, CliLogLevel, CliPercentageProgressBarUpdateValueOptions, CliTextAnimatorOptions, ICliModule, CliModuleRegistry, Package, ICliPingServerService, CliLineOptions, CliSelectOption, CliSelectOptions, CliMultiSelectOption, CliMultiSelectOptions, CliNumberOptions, CliDateOptions, CliFilePickerOptions, CliFileResult, ICliProcessRegistry, ICliProcessRegisterOptions, ICliProcessEntry, ICliDragDropService, CliState, CliEngineSnapshot, CliServerConfig, CliServerCommandDescriptor, CliServerCapabilities, CliServerResponse, CliIcon } from '@qodalis/cli-core';
 export { ICliUserSessionService_TOKEN, ICliUsersStoreService_TOKEN } from '@qodalis/cli-core';
 import { ITheme, Terminal, ITerminalAddon, ITerminalOptions, ITerminalInitOnlyOptions } from '@xterm/xterm';
 import { Subject, Observable, Subscription } from 'rxjs';
@@ -140,7 +140,7 @@ declare const CliBackgroundServiceRegistry_TOKEN = "cli-background-service-regis
  */
 declare const CliPackageManagerService_TOKEN = "cli-package-manager-service";
 
-declare const LIBRARY_VERSION = "2.0.0-beta.8";
+declare const LIBRARY_VERSION = "2.0.0-beta.9";
 declare const API_VERSION = 2;
 
 declare class CliAliasCommandProcessor implements ICliCommandProcessor {
@@ -984,6 +984,11 @@ declare class CliStateStoreManager implements ICliStateStoreManager {
         name: string;
         state: Record<string, any>;
     }[];
+    /**
+     * Dispose all stores (completes their BehaviorSubjects).
+     * Called during engine teardown.
+     */
+    dispose(): void;
 }
 
 /**
@@ -1191,8 +1196,10 @@ declare class CliExecutionContext implements ICliExecutionContext, InputModeHost
     readonly commandHistory: CliCommandHistory;
     readonly filePickerProvider: ICliFilePickerProvider;
     private readonly modeStack;
+    private readonly stateStoreManager;
     private readonly managedTimers;
     private resizeDisposable;
+    private windowKeydownListener?;
     constructor(deps: CliExecutionContextDeps, terminal: Terminal, executor: ICliCommandExecutorService, cliOptions?: CliOptions);
     writeToTerminal(text: string): void;
     getTerminalRows(): number;
@@ -1258,7 +1265,6 @@ declare class CliCommandExecutor implements ICliCommandExecutorService {
     protected readonly registry: ICliCommandProcessorRegistry;
     private commandParser;
     private globalParameters;
-    private lastCapturingWriter?;
     constructor(registry: ICliCommandProcessorRegistry);
     registerGlobalParameter(handler: ICliGlobalParameterHandler): void;
     getGlobalParameters(): ICliCommandParameterDescriptor[];
@@ -1405,6 +1411,13 @@ declare class CliTerminalWriter implements ICliTerminalWriter {
         columns?: number;
         padding?: number;
     }): void;
+    writeLink(text: string, url: string): void;
+    writeBox(content: string | string[], options?: {
+        title?: string;
+        borderColor?: CliForegroundColor;
+        padding?: number;
+    }): void;
+    writeIndented(text: string, level?: number): void;
     writeTable(headers: string[], rows: string[][]): void;
 }
 
@@ -1506,6 +1519,7 @@ declare class CliBoot {
     private initializing;
     private readonly moduleRegistry;
     private readonly bootedModules;
+    private readonly initializedProcessors;
     constructor(registry: ICliCommandProcessorRegistry, services: ICliServiceProvider);
     /**
      * Get the module registry for external access.
@@ -1576,6 +1590,13 @@ declare class ScriptLoaderService {
         content?: string;
         error?: any;
     }>;
+    /**
+     * Inject an inline script into the page.
+     *
+     * **Security:** This runs `code` in the host page context with full
+     * DOM access. Only call with trusted content (e.g. verified UMD bundles
+     * loaded via the package manager). Never pass user-supplied strings.
+     */
     injectBodyScript(code: string): void;
     /**
      * Returns CDN URLs for a given npm package path.
@@ -1606,14 +1627,18 @@ declare class CliPackageManagerService {
     private readonly storageKey;
     QODALIS_COMMAND_PREFIX: string;
     private store;
+    /** In-memory cache; `null` means "not yet loaded from storage". */
+    private cache;
+    /** Whether the one-time localStorage migration has been checked. */
+    private migrationDone;
     constructor();
     /**
      * Set the key-value store instance for persistence.
      */
     setStore(store: ICliKeyValueStore): void;
     /**
-     * Retrieves the list of packages
-     * @returns {Package[]} Array of packages
+     * Retrieves the list of packages.
+     * Uses an in-memory cache after the first load.
      */
     getPackages(): Promise<Package[]>;
     /**
@@ -1656,11 +1681,7 @@ declare class CliInputReader implements ICliInputReader {
     readSelect(prompt: string, options: CliSelectOption[], selectOptions?: CliSelectOptions): Promise<string | null>;
     readSelectInline(prompt: string, options: CliSelectOption[], selectOptions?: CliSelectOptions): Promise<string | null>;
     readMultiSelect(prompt: string, options: CliMultiSelectOption[], selectOptions?: CliMultiSelectOptions): Promise<string[] | null>;
-    readNumber(prompt: string, options?: {
-        min?: number;
-        max?: number;
-        default?: number;
-    }): Promise<number | null>;
+    readNumber(prompt: string, options?: CliNumberOptions): Promise<number | null>;
     readDate(prompt: string, options?: CliDateOptions): Promise<string | null>;
     readFile(prompt: string, options?: CliFilePickerOptions): Promise<CliFileResult[] | null>;
 }
@@ -1717,6 +1738,13 @@ declare class CapturingTerminalWriter implements ICliTerminalWriter {
         columns?: number;
         padding?: number;
     }): void;
+    writeLink(text: string, url: string): void;
+    writeBox(content: string | string[], options?: {
+        title?: string;
+        borderColor?: CliForegroundColor;
+        padding?: number;
+    }): void;
+    writeIndented(text: string, level?: number): void;
     /**
      * Returns true if any stdout-equivalent output was captured.
      */
@@ -1871,6 +1899,11 @@ declare class CliStateStore implements ICliStateStore {
     reset(): void;
     persist(): Promise<void>;
     initialize(): Promise<void>;
+    /**
+     * Complete the BehaviorSubject so all subscribers are notified
+     * and no further emissions occur. Called during engine teardown.
+     */
+    dispose(): void;
 }
 
 interface CliEngineOptions extends CliOptions {
@@ -1974,9 +2007,12 @@ declare class CliEngine {
      * so intermediate resize events cannot leave stale artefacts.
      */
     private deferResizeFix;
+    /** Maximum time (ms) to wait for container layout before rejecting. */
+    private static readonly LAYOUT_TIMEOUT_MS;
     /**
      * Wait until the container element has non-zero dimensions.
      * xterm.js requires the host element to be laid out before open() is called.
+     * Rejects after {@link LAYOUT_TIMEOUT_MS} if the container stays hidden.
      */
     private waitForLayout;
 }
@@ -1984,12 +2020,13 @@ declare class CliEngine {
 declare class CliServerConnection {
     private readonly _config;
     private readonly _backgroundServices?;
+    private readonly _logger?;
     private _connected;
     private _commands;
     private _capabilities;
     private _eventSocket;
     onDisconnect?: () => void;
-    constructor(_config: CliServerConfig, _backgroundServices?: ICliBackgroundServiceRegistry | undefined);
+    constructor(_config: CliServerConfig, _backgroundServices?: ICliBackgroundServiceRegistry | undefined, _logger?: ICliLogger | undefined);
     get config(): CliServerConfig;
     get connected(): boolean;
     get commands(): CliServerCommandDescriptor[];
@@ -2065,6 +2102,7 @@ declare class CliServerManager implements DefaultServerProvider {
     private readonly registry;
     readonly connections: Map<string, CliServerConnection>;
     private _logger?;
+    private _cliLogger?;
     private _defaultServer;
     private _backgroundServices?;
     constructor(registry: ICliCommandProcessorRegistry);
@@ -2073,7 +2111,7 @@ declare class CliServerManager implements DefaultServerProvider {
     connectAll(servers: CliServerConfig[], logger?: {
         warn(msg: string): void;
         info(msg: string): void;
-    }, backgroundServices?: ICliBackgroundServiceRegistry): Promise<void>;
+    }, backgroundServices?: ICliBackgroundServiceRegistry, cliLogger?: ICliLogger): Promise<void>;
     reconnect(name: string): Promise<{
         success: boolean;
         commandCount: number;