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

package/public-api.d.ts

@@ -106,7 +106,10 @@ type CliProcessCommand = {
      */
     command: string;
     /**
-     * The data that was entered
+     * Pipeline data passed from the previous command in a pipe chain.
+     * When commands are piped (e.g. `cmd1 | cmd2`), the output of `cmd1`
+     * is captured and passed here as input to `cmd2`. The shape depends
+     * on what the upstream command produced (string, JSON object, array, etc.).
      */
     data?: any;
     /**
@@ -216,7 +219,7 @@ declare enum CliIcon {
     Server = "\uD83D\uDDA5",// Server or host
     Cloud = "\u2601",// Cloud or remote
     Network = "\uD83C\uDF10",// Network or connection
-    Monitor = "\uD83D\uDDA5",// Monitor or display
+    Monitor = "\uD83D\uDCFA",// Monitor or display
     Printer = "\uD83D\uDDA8",// Printer or output
     USB = "\uD83D\uDD0C",// USB or connection
     Speaker = "\uD83D\uDD0A",// Speaker or audio
@@ -226,14 +229,14 @@ declare enum CliIcon {
     Music = "\uD83C\uDFB5",// Music or audio
     Phone = "\uD83D\uDCDE",// Phone or communication
     Package = "\uD83D\uDCE6",// Package or bundle
-    Plugin = "\uD83D\uDD0C",// Plugin or extension
-    Extension = "\uD83E\uDDE9",// Extension or component
-    Module = "\uD83D\uDCE6",// Module or package
+    Plugin = "\uD83E\uDDE9",// Plugin or extension
+    Extension = "\uD83D\uDD0C",// Extension or connection
+    Module = "\uD83E\uDDF1",// Module or package
     Evaluate = "\uD83D\uDD0D",// Evaluate or search
-    Variable = "\uD83D\uDD27",// Variable or setting
+    Variable = "\uD835\uDC65",// Variable or setting
     Script = "\uD83D\uDCDC",// Script or code
-    Code = "\uD83D\uDCBE",// Code or file
-    Logs = "\uD83D\uDCDC",// Logs or history
+    Code = "\uD83D\uDCDD",// Code or file
+    Logs = "\uD83D\uDCCB",// Logs or history
     Power = "\u23FB",// On/Off state
     Heart = "\u2764",// Love or favorite
     Flame = "\uD83D\uDD25",// Trending or hot
@@ -314,6 +317,14 @@ type CliOptions = Record<string, any> & {
      * Commands from each server are discovered and registered as proxy processors.
      */
     servers?: CliServerConfig[];
+    /**
+     * Whether the `eval` / `js` / `calc` command is enabled.
+     * Disabled by default because it runs arbitrary JavaScript via `eval()`
+     * in the host page context — a security risk in multi-tenant or
+     * user-facing deployments.
+     * @default false
+     */
+    allowEval?: boolean;
 };
 /**
  * Configuration for a remote CLI server
@@ -482,10 +493,17 @@ declare enum CliLogLevel {
 type CliState = Record<string, any>;
 /**
  * Position of the CLI panel relative to the viewport edge.
+ * - `'bottom'` — anchored to the bottom (default)
+ * - `'top'` — anchored to the top
+ * - `'left'` — anchored to the left (vertical layout)
+ * - `'right'` — anchored to the right (vertical layout)
  */
 type CliPanelPosition = 'bottom' | 'top' | 'left' | 'right';
 /**
  * Alignment of the hidden-mode tab along its viewport edge.
+ * - `'start'` — left for horizontal panels, top for vertical panels
+ * - `'center'` — centered along the edge (default)
+ * - `'end'` — right for horizontal panels, bottom for vertical panels
  */
 type CliPanelHideAlignment = 'start' | 'center' | 'end';
 /**
@@ -545,6 +563,47 @@ declare const enums: {
     CliLogLevel: typeof CliLogLevel;
 };
 
+/**
+ * Token for the CLI user session service.
+ */
+declare const ICliUserSessionService_TOKEN = "cli-user-session-service";
+/**
+ * Token for the CLI users store service.
+ */
+declare const ICliUsersStoreService_TOKEN = "cli-users-store-service";
+/**
+ * Token for the CLI groups store service.
+ */
+declare const ICliGroupsStoreService_TOKEN = "cli-groups-store-service";
+/**
+ * Token for the CLI auth service.
+ */
+declare const ICliAuthService_TOKEN = "cli-auth-service";
+/**
+ * Token for registering completion providers via module services (multi: true).
+ */
+declare const ICliCompletionProvider_TOKEN = "cli-completion-provider";
+/**
+ * Token for the drag-and-drop service.
+ */
+declare const ICliDragDropService_TOKEN = "cli-drag-drop-service";
+/**
+ * Token for the file transfer service.
+ */
+declare const ICliFileTransferService_TOKEN = "cli-file-transfer-service";
+/**
+ * Token for the translation service.
+ */
+declare const ICliTranslationService_TOKEN = "cli-translation-service";
+/**
+ * Token for the permission service.
+ */
+declare const ICliPermissionService_TOKEN = "cli-permission-service";
+/**
+ * Token for the file picker provider.
+ */
+declare const ICliFilePickerProvider_TOKEN = "cli-file-picker-provider";
+
 /**
  * Options for readFile file picker.
  */
@@ -668,6 +727,17 @@ interface CliMultiSelectOptions {
     /** Callback invoked each time the set of checked options changes */
     onChange?: (values: string[]) => void;
 }
+/**
+ * Options for readNumber input.
+ */
+interface CliNumberOptions {
+    /** Minimum allowed value */
+    min?: number;
+    /** Maximum allowed value */
+    max?: number;
+    /** Pre-filled default value */
+    default?: number;
+}
 /**
  * Options for readDate input.
  */
@@ -740,11 +810,7 @@ interface ICliInputReader {
      * @param options - Optional configuration for min, max, and default value
      * @returns The entered number, or null if aborted
      */
-    readNumber(prompt: string, options?: {
-        min?: number;
-        max?: number;
-        default?: number;
-    }): Promise<number | null>;
+    readNumber(prompt: string, options?: CliNumberOptions): Promise<number | null>;
     /**
      * Read a date input with format validation.
      * @param prompt - The prompt text displayed to the user
@@ -762,7 +828,12 @@ interface ICliInputReader {
 }
 
 /**
- * Whether a background service is a long-running daemon or a one-shot job.
+ * Background service lifecycle type.
+ * - `'daemon'` — Long-running service whose `onStart` blocks until the abort signal
+ *   fires. Suitable for event loops, polling, or WebSocket connections. Can be
+ *   stopped and restarted.
+ * - `'job'` — Run-to-completion task whose `onStart` resolves when the work is done.
+ *   Automatically transitions to `'done'` status on success. Cannot be restarted.
  */
 type CliBackgroundServiceType = 'daemon' | 'job';
 /**
@@ -791,12 +862,18 @@ interface ICliServiceEvent {
  * Handler function for service events.
  */
 type CliServiceEventHandler = (event: ICliServiceEvent) => void;
+/**
+ * Log severity level for background service messages.
+ * Shared by `ICliServiceLogEntry`, `ICliServiceContext.log()`,
+ * and `WorkerServiceContext.log()`.
+ */
+type CliServiceLogLevel = 'info' | 'warn' | 'error';
 /**
  * A single log entry from a background service.
  */
 interface ICliServiceLogEntry {
     timestamp: Date;
-    level: 'info' | 'warn' | 'error';
+    level: CliServiceLogLevel;
     message: string;
 }
 /**
@@ -810,7 +887,7 @@ interface ICliServiceContext {
     /** Emit an event from this service */
     emit(event: ICliServiceEvent): void;
     /** Log a message to this service's private log buffer */
-    log(message: string, level?: 'info' | 'warn' | 'error'): void;
+    log(message: string, level?: CliServiceLogLevel): void;
     /** Create an interval scoped to this service (auto-cleared on stop) */
     createInterval(callback: () => void, ms: number): ICliManagedInterval;
     /** Create a timeout scoped to this service (auto-cleared on stop) */
@@ -838,7 +915,11 @@ interface ICliBackgroundService {
     onStart(context: ICliServiceContext): Promise<void>;
     /** Called for graceful shutdown */
     onStop?(context: ICliServiceContext): Promise<void>;
-    /** Called on unrecoverable error */
+    /**
+     * Called when the service throws an unrecoverable error.
+     * Use this hook for logging or cleanup; throwing from `onError` itself
+     * is safe — the registry catches it and marks the service as failed.
+     */
     onError?(error: Error, context: ICliServiceContext): void;
 }
 /**
@@ -869,7 +950,7 @@ interface ICliBackgroundServiceRegistry {
     restart(name: string): Promise<void>;
     startJob(name: string, task: (context: ICliServiceContext) => Promise<void>, options?: {
         workerCompatible?: boolean;
-    }): void;
+    }): Promise<void>;
     getStatus(name: string): ICliBackgroundServiceInfo | undefined;
     list(): ICliBackgroundServiceInfo[];
     getLogs(name: string, limit?: number): ICliServiceLogEntry[];
@@ -887,14 +968,14 @@ interface ICliBackgroundServiceRegistry {
  */
 interface ICliManagedTimer {
     /** Clear this timer immediately. */
-    clear(): void;
+    readonly clear: () => void;
 }
 /**
  * A managed interval handle with the ability to change the delay.
  */
 interface ICliManagedInterval extends ICliManagedTimer {
     /** Change the interval delay. Restarts the interval with the new delay. */
-    setDelay(ms: number): void;
+    readonly setDelay: (ms: number) => void;
 }
 /**
  * Represents the context in which a command is executed
@@ -1234,7 +1315,7 @@ interface ICliCommandProcessor {
     /**
      * Represents the state configuration for the command processor
      * @remarks The state configuration is used to store and retrieve state information for the command processor
-     * @remarks State confihuration is optional and can be used to store and retrieve state information for the command processor
+     * @remarks State configuration is optional and can be used to store and retrieve state information for the command processor
      * @remarks The state configuration is used only for root command processors and not for child command processors
      */
     stateConfiguration?: CliStateConfiguration;
@@ -1341,10 +1422,6 @@ interface ICliGlobalParameterHandler {
     handle(args: Record<string, any>, processor: ICliCommandProcessor, command: CliProcessCommand, context: ICliExecutionContext): boolean | Promise<boolean>;
 }
 
-/**
- * Token for registering completion providers via module services (multi: true).
- */
-declare const ICliCompletionProvider_TOKEN = "cli-completion-provider";
 /**
  * Context passed to completion providers describing the current input state.
  */
@@ -1416,9 +1493,9 @@ type CliPercentageProgressBarUpdateValueOptions = {
  */
 interface ICliPercentageProgressBar extends ICliProgressBar {
     /**
-     * Update the progress of the progress bar
-     * @param progress The progress to update to
-     * @returns void
+     * Update the progress of the progress bar.
+     * @param progress The progress value (0–100). Values outside this range are clamped.
+     * @param options Optional: update type ('replace' or 'increment')
      */
     update: (progress: number, options?: CliPercentageProgressBarUpdateValueOptions) => void;
     /**
@@ -1446,9 +1523,9 @@ type CliTextAnimatorOptions = {
 interface ICliTextAnimator extends ICliProgressBar {
     /**
      * Show animated text in a typing and erasing effect.
-     * @param text
-     * @param options
-     * @returns
+     * @param text The text to animate
+     * @param options Optional: speed (ms per character), removeAfterTyping
+     * @returns A promise that resolves when the animation completes
      */
     showText: (text: string, options?: CliTextAnimatorOptions) => Promise<void>;
 }
@@ -1587,10 +1664,7 @@ interface ICliFileEntry {
     size: number;
     modified: string;
 }
-/**
- * Token for the file transfer service.
- */
-declare const ICliFileTransferService_TOKEN = "cli-file-transfer-service";
+
 /**
  * Abstraction for file transfer operations.
  * Default implementation uses browser-native APIs (file picker, download dialog).
@@ -1608,12 +1682,17 @@ interface ICliFileTransferService {
     } | null>;
 }
 
-declare const ICliDragDropService_TOKEN = "cli-drag-drop-service";
 interface ICliDragDropService {
     /** Emits an array of dropped File objects each time files are dropped onto the terminal */
     readonly onFileDrop: Observable<File[]>;
 }
 
+/**
+ * Opaque state value carried between lines during syntax highlighting.
+ * Encodes context such as "inside a multi-line string" or "inside a block comment"
+ * so the highlighter can resume correctly on the next line.
+ * `0` typically represents the default/root state.
+ */
 type LineState = number;
 interface ISyntaxHighlightRule {
     pattern: RegExp;
@@ -1622,6 +1701,8 @@ interface ISyntaxHighlightRule {
 }
 interface ISyntaxHighlighter {
     id: string;
+    /** Human-readable language name (e.g. 'TypeScript'). Falls back to `id` when absent. */
+    name?: string;
     extensions: string[];
     initialState: LineState;
     getRules(state: LineState): ISyntaxHighlightRule[];
@@ -1645,72 +1726,63 @@ interface ICliTerminalWriter {
     writeln(text?: string): void;
     /**
      * Write a success message to the terminal
-     * @param messag The message to write
-     * @returns void
+     * @param message The message to write
      */
-    writeSuccess: (message: string) => void;
+    writeSuccess(message: string): void;
     /**
      * Write an info message to the terminal
-     * @param messag The message to write
-     * @returns void
+     * @param message The message to write
      */
-    writeInfo: (message: string) => void;
+    writeInfo(message: string): void;
     /**
      * Write an error message to the terminal
      * @param message The message to write
-     * @returns void
      */
-    writeError: (message: string) => void;
+    writeError(message: string): void;
     /**
      * Write a warning message to the terminal
      * @param message The message to write
-     * @returns void
      */
-    writeWarning: (message: string) => void;
+    writeWarning(message: string): void;
     /**
-     * Write a message to the terminal with the specified color
-     * @param message The message to write
-     * @param color The color to use
-     * @returns void
+     * Wrap text in the specified foreground color.
+     * @param text The text to wrap
+     * @param color The foreground color to apply
+     * @returns The text wrapped in ANSI color codes
      */
-    wrapInColor: (text: string, color: CliForegroundColor) => string;
+    wrapInColor(text: string, color: CliForegroundColor): string;
     /**
-     * Write a message to the terminal with the specified background color
-     * @param message The message to write
-     * @param color The background color to use
-     * @returns void
+     * Wrap text in the specified background color.
+     * @param text The text to wrap
+     * @param color The background color to apply
+     * @returns The text wrapped in ANSI background color codes
      */
-    wrapInBackgroundColor: (text: string, color: CliBackgroundColor) => string;
+    wrapInBackgroundColor(text: string, color: CliBackgroundColor): string;
     /**
      * Write a JSON object to the terminal
      * @param json The JSON object to write
-     * @returns void
      */
-    writeJson: (json: any) => void;
+    writeJson(json: any): void;
     /**
-     * Write content to a file
-     * @param fileName The name of the file to write to
+     * Write content to a file (triggers a browser download)
+     * @param fileName The name of the file to download
      * @param content The content to write to the file
-     * @returns void
      */
-    writeToFile: (fileName: string, content: string) => void;
+    writeToFile(fileName: string, content: string): void;
     /**
      * Write an object array as a table to the terminal
      * @param objects The objects to write to the table
-     * @returns void
      */
     writeObjectsAsTable(objects: any[]): void;
     /**
      * Write a table to the terminal
      * @param headers The headers of the table
      * @param rows The rows of the table
-     * @returns void
      */
     writeTable(headers: string[], rows: string[][]): void;
     /**
      * Write a divider to the terminal
-     * @param options The options for the divider
-     * @returns void
+     * @param options Optional: color, length, character
      */
     writeDivider(options?: {
         color?: CliForegroundColor;
@@ -1745,6 +1817,32 @@ interface ICliTerminalWriter {
         columns?: number;
         padding?: number;
     }): void;
+    /**
+     * Write a clickable hyperlink using OSC 8 escape sequences.
+     * In terminals that support OSC 8, the text is clickable. In others,
+     * it falls back to displaying "text (url)".
+     * @param text The visible link text
+     * @param url The URL to link to
+     */
+    writeLink(text: string, url: string): void;
+    /**
+     * Write text inside a bordered box.
+     * Useful for callouts, notices, and highlighted information.
+     * @param content The content lines to display inside the box
+     * @param options Optional: title, border color, padding
+     */
+    writeBox(content: string | string[], options?: {
+        title?: string;
+        borderColor?: CliForegroundColor;
+        padding?: number;
+    }): void;
+    /**
+     * Write text with a specified indentation level.
+     * Each level adds 2 spaces of indentation.
+     * @param text The text to write
+     * @param level The indentation level (default: 1)
+     */
+    writeIndented(text: string, level?: number): void;
 }
 /**
  * Represents a clipboard for the CLI
@@ -1767,9 +1865,10 @@ interface ICliClipboard {
  */
 interface ICliCommandExecutorService {
     /**
-     *
-     * @param command
-     * @param context
+     * Display the help output for a command, including its description,
+     * sub-commands, and parameters.
+     * @param command The parsed command to show help for
+     * @param context The execution context
      */
     showHelp(command: CliProcessCommand, context: ICliExecutionContext): Promise<void>;
     /**
@@ -1944,16 +2043,24 @@ interface ICliKeyValueStore {
     clear(): Promise<void>;
 }
 /**
- * Represents a store for storing data associated with commands
+ * Reactive state store scoped to a command processor or module.
+ *
+ * State is a plain object (`Record<string, any>`). Updates are shallow-merged
+ * (top-level keys are replaced, nested objects are not deep-merged).
+ * `getState()` returns a snapshot — mutating the returned object has no effect;
+ * always use `updateState()` to change state.
  */
 interface ICliStateStore {
     /**
-     * Get the current state as an object.
+     * Get a snapshot of the current state.
+     * @returns A shallow copy of the state object
      */
     getState<T extends CliState = CliState>(): T;
     /**
-     * Update the state with new values. Supports partial updates.
-     * @param newState Partial state to merge with the current state.
+     * Shallow-merge new values into the current state.
+     * Only the provided keys are updated; other keys are preserved.
+     * Triggers subscribers and persists if a storage backend is configured.
+     * @param newState Partial state to merge with the current state
      */
     updateState(newState: Partial<CliState>): void;
     /**
@@ -2052,6 +2159,22 @@ interface ICliModule {
     /** Called when the module is being torn down */
     onDestroy?(context: ICliExecutionContext): Promise<void>;
 }
+/**
+ * A module that accepts typed configuration via `configure()`.
+ * Extend this instead of `ICliModule` when your module has a config type.
+ *
+ * @example
+ * ```ts
+ * interface MyModuleConfig { verbose?: boolean }
+ * const myModule: ICliConfigurableModule<MyModuleConfig> = {
+ *     configure(config) { return { ...this, config }; },
+ *     // ...
+ * };
+ * ```
+ */
+interface ICliConfigurableModule<T extends Record<string, any> = Record<string, any>> extends ICliModule {
+    configure(config: T): ICliModule;
+}
 /**
  * @deprecated Use ICliModule instead
  */
@@ -2068,32 +2191,32 @@ interface ICliLogger {
      */
     setCliLogLevel(level: CliLogLevel): void;
     /**
-     * Log a message
+     * Log a general message (LOG level)
      * @param args The arguments to log
      */
     log(...args: any[]): void;
     /**
-     * Log a message
+     * Log an informational message (INFO level)
      * @param args The arguments to log
      */
     info(...args: any[]): void;
     /**
-     * Log a message
+     * Log a warning message (WARN level)
      * @param args The arguments to log
      */
     warn(...args: any[]): void;
     /**
-     * Log a message
+     * Log an error message (ERROR level)
      * @param args The arguments to log
      */
     error(...args: any[]): void;
     /**
-     * Log a message
+     * Log a debug message (DEBUG level)
      * @param args The arguments to log
      */
     debug(...args: any[]): void;
 }
-declare const ICliTranslationService_TOKEN = "cli-translation-service";
+
 /**
  * Provides internationalization (i18n) support for CLI strings.
  */
@@ -2127,23 +2250,24 @@ interface ICliTranslationService {
     getAvailableLocales(): string[];
 }
 /**
- * Represents a service provider for the CLI
+ * Dependency injection container for CLI services.
+ * Services are registered with string tokens and retrieved by type.
  */
 interface ICliServiceProvider {
     /**
-     * Get a service
-     * @param service The service to get
+     * Retrieve a service by its injection token.
+     * @param service The token (typically a `*_TOKEN` constant) identifying the service
+     * @returns The service instance, cast to `T`
+     * @throws If no service is registered for the given token
      */
-    get<T>(service: any): T;
+    get<T = unknown>(service: any): T;
     /**
-     * Set a service
-     * @param definition The definition of the service
+     * Register one or more service definitions.
+     * @param definition A single provider or an array of providers to register
      */
     set(definition: CliProvider | CliProvider[]): void;
 }
 
-declare const ICliPermissionService_TOKEN = "cli-permission-service";
-
 /**
  * Abstract permission service for checking rwx permissions on resources.
  * The default implementation lives in @qodalis/cli-users; consumers can
@@ -2172,13 +2296,15 @@ interface ICliPermissionService {
 declare class CliModuleRegistry {
     private readonly modules;
     private readonly bootHandlers;
+    /** Optional warning callback — set by the engine to route through ICliLogger */
+    onWarn?: (message: string) => void;
     /**
      * Register a handler that is called whenever a new module is registered.
      */
     onModuleBoot(handler: (module: ICliModule) => Promise<void>): void;
     /**
      * Register a module and notify all boot handlers.
-     * Modules that do not meet the required API version are silently skipped.
+     * Modules that do not meet the required API version are skipped with a warning.
      */
     register(module: ICliModule): Promise<void>;
     /**
@@ -2242,6 +2368,17 @@ declare const CLI_CONFIGURE_STORE_NAME = "configure";
  * @returns The configured value or the default
  */
 declare function getConfigValue<T = any>(state: ICliStateStore, category: string, key: string, defaultValue: T): T;
+/**
+ * Retrieves a plugin configuration value from the execution context.
+ * This is a convenience wrapper for plugins — handles store lookup internally.
+ *
+ * @param context The execution context
+ * @param category The category (usually the processor's command name)
+ * @param key The configuration key
+ * @param defaultValue Fallback value if not configured
+ * @returns The configured value or the default
+ */
+declare function getPluginConfigValue<T = any>(context: ICliExecutionContext, category: string, key: string, defaultValue: T): T;
 /**
  * Resolves all configuration options from registered processors,
  * grouped by category.
@@ -2251,6 +2388,10 @@ declare function resolveConfigurationCategories(registry: ICliCommandProcessorRe
     options: ICliConfigurationOption[];
 }>;
 
+/**
+ * Returns a promise that resolves after the given number of milliseconds.
+ * @param ms Delay duration in milliseconds
+ */
 declare const delay: (ms: number) => Promise<void>;
 
 /**
@@ -2288,7 +2429,7 @@ interface ServerVersionInfo {
  * Negotiates the API version between a frontend CLI client and a backend server.
  *
  * Flow:
- * 1. Client calls `discover(baseUrl)` which hits `GET /api/qcli/versions`
+ * 1. Client calls `discover(baseUrl)` which hits `GET ${VERSIONS_ENDPOINT}`
  * 2. Server returns supported versions
  * 3. Client picks the highest mutually supported version
  * 4. All subsequent calls use `/api/v{n}/qcli/*`
@@ -2344,18 +2485,72 @@ declare function savePanelPosition(position: CliPanelPosition): void;
  */
 declare function nextPanelPosition(current: CliPanelPosition): CliPanelPosition;
 
-declare const getParameterValue: (p: ICliCommandParameterDescriptor, args: Record<string, any>) => any | undefined;
+/**
+ * Strip all ANSI escape sequences from a string.
+ * @param text The text potentially containing ANSI codes
+ * @returns The text with all ANSI codes removed
+ */
+declare function stripAnsi(text: string): string;
+/**
+ * Return the visible length of a string, ignoring ANSI escape codes.
+ * Useful for padding/alignment calculations in terminal output.
+ * @param text The text potentially containing ANSI codes
+ * @returns The number of visible characters
+ */
+declare function visibleLength(text: string): number;
+
+/**
+ * Retrieve a parameter's value from the parsed arguments, checking aliases.
+ * @param p The parameter descriptor
+ * @param args The parsed command arguments
+ * @returns The matched value, or `undefined` if not found
+ */
+declare const getParameterValue: (p: ICliCommandParameterDescriptor, args: Record<string, any>) => unknown;
+/**
+ * Pretty-print a JSON value with ANSI color highlighting.
+ * @param json The value to format
+ * @returns A colorized, indented string suitable for terminal output
+ */
 declare const formatJson: (json: any) => string;
-declare const colorizeJson: (jsonString: any) => string;
+/**
+ * Apply ANSI color codes to a JSON string (keys, strings, numbers, booleans, null).
+ * @param jsonString The raw JSON string to colorize
+ * @returns The colorized string
+ */
+declare const colorizeJson: (jsonString: string) => string;
+/**
+ * Convert a key-value object to a URL query string. Arrays produce repeated keys.
+ * @param params The parameters to encode
+ * @returns The encoded query string (without leading `?`)
+ */
 declare const toQueryString: (params: Record<string, any>) => string;
+/**
+ * Highlight regex matches in text using an ANSI background color.
+ * @param text The source text
+ * @param pattern The regex pattern to highlight
+ * @param bgColor The background color to apply (default: Yellow)
+ * @returns The text with matching segments wrapped in ANSI background color codes
+ */
 declare const highlightTextWithBg: (text: string, pattern: RegExp, bgColor?: CliBackgroundColor) => string;
+/**
+ * Extract the substring to the right of a given word in a command string.
+ * @param command The full command string
+ * @param word The word to search for
+ * @returns The trimmed text after the word, or `undefined` if not found
+ */
 declare const getRightOfWord: (command: string, word: string) => string | undefined;
+/**
+ * Apply a color function to the first word of a text string, preserving leading whitespace.
+ * @param text The text to process
+ * @param colorFunction A function that wraps a word in ANSI color codes
+ * @returns The text with only the first word colorized
+ */
 declare const colorFirstWord: (text: string, colorFunction: (word: string) => string) => string;
 
 declare const utils: {
-    getParameterValue: (p: ICliCommandParameterDescriptor, args: Record<string, any>) => any | undefined;
+    getParameterValue: (p: ICliCommandParameterDescriptor, args: Record<string, any>) => unknown;
     formatJson: (json: any) => string;
-    colorizeJson: (jsonString: any) => string;
+    colorizeJson: (jsonString: string) => string;
     toQueryString: (params: Record<string, any>) => string;
     highlightTextWithBg: (text: string, pattern: RegExp, bgColor?: CliBackgroundColor) => string;
     getRightOfWord: (command: string, word: string) => string | undefined;
@@ -2363,6 +2558,7 @@ declare const utils: {
     ObjectDescriber: typeof ObjectDescriber;
     delay: (ms: number) => Promise<void>;
     getConfigValue: typeof getConfigValue;
+    getPluginConfigValue: typeof getPluginConfigValue;
     resolveConfigurationCategories: typeof resolveConfigurationCategories;
     CLI_CONFIGURE_STORE_NAME: string;
 };
@@ -2372,12 +2568,38 @@ declare const constants: {
     DefaultLibraryAuthor: ICliCommandAuthor;
 };
 
+/** Error message used when a `CancellablePromise` is cancelled. */
+declare const CANCELLATION_ERROR_MESSAGE = "Promise cancelled";
+/**
+ * A promise wrapper that supports cooperative cancellation.
+ *
+ * Create with an executor (like `new Promise`), then call `execute()` to run.
+ * Call `cancel()` to reject with a cancellation error and prevent further
+ * resolve/reject callbacks from firing.
+ *
+ * @example
+ * ```ts
+ * const cp = new CancellablePromise<string>((resolve) => {
+ *     setTimeout(() => resolve('done'), 5000);
+ * });
+ * cp.execute().catch(e => console.log(e.message)); // 'Promise cancelled'
+ * cp.cancel();
+ * ```
+ */
 declare class CancellablePromise<T> {
     private executor;
     private hasCancelled;
     private abortController;
     constructor(executor: (resolve: (value: T) => void, reject: (reason?: any) => void) => void);
+    /**
+     * Run the executor and return a promise for its result.
+     * If `cancel()` has been called, the promise rejects immediately.
+     */
     execute(): Promise<T>;
+    /**
+     * Cancel the promise. The executing promise rejects with
+     * `Error('Promise cancelled')` and subsequent resolve/reject calls are ignored.
+     */
     cancel(): void;
 }
 
@@ -2427,30 +2649,9 @@ declare const DefaultThemes: DefaultThemesType;
 
 declare const DefaultThemeInfos: Record<string, CliThemeInfo>;
 
-declare const LIBRARY_VERSION = "2.0.0-beta.8";
+declare const LIBRARY_VERSION = "2.0.0-beta.9";
 declare const API_VERSION = 2;
 
-/**
- * Framework-agnostic token for the CLI user session service.
- * Used as a key in the service provider to retrieve the user session service.
- */
-declare const ICliUserSessionService_TOKEN = "cli-user-session-service";
-/**
- * Framework-agnostic token for the CLI users store service.
- * Used as a key in the service provider to retrieve the users store service.
- */
-declare const ICliUsersStoreService_TOKEN = "cli-users-store-service";
-/**
- * Framework-agnostic token for the CLI groups store service.
- * Used as a key in the service provider to retrieve the groups store service.
- */
-declare const ICliGroupsStoreService_TOKEN = "cli-groups-store-service";
-/**
- * Framework-agnostic token for the CLI auth service.
- * Used as a key in the service provider to retrieve the auth service.
- */
-declare const ICliAuthService_TOKEN = "cli-auth-service";
-
 /**
  * Context provided to worker service handlers inside a Web Worker.
  */
@@ -2458,7 +2659,7 @@ interface WorkerServiceContext {
     /** Emit an event to the main thread */
     emit(event: Omit<ICliServiceEvent, 'timestamp'>): void;
     /** Log a message (forwarded to the main-thread log buffer) */
-    log(message: string, level?: 'info' | 'warn' | 'error'): void;
+    log(message: string, level?: CliServiceLogLevel): void;
     /** Update state on the main thread */
     updateState(patch: Record<string, unknown>): void;
     /** Create an interval that is auto-cleared on stop */
@@ -2477,10 +2678,29 @@ declare function createWorkerService(handlers: {
     onStop?(): Promise<void>;
 }): void;
 
+/**
+ * Browser-based file transfer service using native browser APIs.
+ *
+ * This is the default implementation when no virtual filesystem is available.
+ * `readFile` and `uploadFromBrowser` open a file picker dialog.
+ * `writeFile` and `downloadToBrowser` trigger a browser download.
+ *
+ * **Limitations:** `listFiles()` and `exists()` are not supported in the
+ * browser environment and always return empty/false respectively.
+ * Use `@qodalis/cli-files` for full filesystem capabilities.
+ */
 declare class BrowserFileTransferService implements ICliFileTransferService {
     readFile(_path: string): Promise<string | null>;
     writeFile(path: string, content: string): Promise<void>;
+    /**
+     * Not supported in browser — always returns an empty array.
+     * Use `@qodalis/cli-files` for directory listing.
+     */
     listFiles(_path: string): Promise<ICliFileEntry[]>;
+    /**
+     * Not supported in browser — always returns `false`.
+     * Use `@qodalis/cli-files` for file existence checks.
+     */
     exists(_path: string): Promise<boolean>;
     downloadToBrowser(filename: string, content: string | Blob): void;
     uploadFromBrowser(accept?: string): Promise<{
@@ -2490,4 +2710,4 @@ declare class BrowserFileTransferService implements ICliFileTransferService {
     private _pickFile;
 }
 
-export { API_VERSION, BrowserFileTransferService, CLI_CONFIGURE_STORE_NAME, CancellablePromise, type CliAddUser, CliBackgroundColor, type CliBackgroundServiceStatus, type CliBackgroundServiceType, type CliDateOptions, type CliEngineSnapshot, type CliFactoryProvider, type CliFilePickerOptions, type CliFileResult, CliForegroundColor, CliIcon, type CliLineOptions, CliLogLevel, CliModuleRegistry, type CliMultiSelectOption, type CliMultiSelectOptions, type CliOptions, type CliPackageSource, type CliPanelConfig, type CliPanelHideAlignment, type CliPanelPosition, type CliPercentageProgressBarUpdateValueOptions, type CliProcessCommand, type CliProcessorMetadata, type CliProvider, type CliSelectOption, type CliSelectOptions, type CliServerCapabilities, type CliServerCommandDescriptor, type CliServerConfig, type CliServerOutput, type CliServerResponse, type CliServiceEventHandler, type CliServiceExecutionMode, type CliState, type CliStateConfiguration, type CliTextAnimatorOptions, type CliTheme, type CliThemeCategory, type CliThemeInfo, type CliTypeProvider, type CliUpdateUser, type CliValueProvider, type CliWorkerInboundMessage, type CliWorkerOutboundMessage, DEFAULT_DIR_PERMISSIONS, DEFAULT_FILE_PERMISSIONS, DefaultLibraryAuthor, DefaultThemeInfos, DefaultThemes, type ICliAuthService, ICliAuthService_TOKEN, type ICliBackgroundService, type ICliBackgroundServiceInfo, type ICliBackgroundServiceRegistry, type ICliClipboard, type ICliCommandAuthor, type ICliCommandChildProcessor, type ICliCommandExecutorService, type ICliCommandParameterDescriptor, type ICliCommandProcessor, type ICliCommandProcessorRegistry, type ICliCompletionContext, type ICliCompletionProvider, ICliCompletionProvider_TOKEN, type ICliConfigurationOption, type ICliDragDropService, ICliDragDropService_TOKEN, type ICliExecutionContext, type ICliExecutionProcess, type ICliFileEntry, type ICliFilePickerProvider, type ICliFileTransferService, ICliFileTransferService_TOKEN, type ICliGlobalParameterHandler, type ICliGroup, type ICliGroupsStoreService, ICliGroupsStoreService_TOKEN, type ICliInputReader, type ICliKeyValueStore, type ICliLogger, type ICliManagedInterval, type ICliManagedTimer, type ICliModule, type ICliOwnership, type ICliPercentageProgressBar, type ICliPermissionService, ICliPermissionService_TOKEN, type ICliPingServerService, type ICliProcessEntry, type ICliProcessRegisterOptions, type ICliProcessRegistry, type ICliProcessorHook, type ICliProgressBar, type ICliServiceContext, type ICliServiceEvent, type ICliServiceLogEntry, type ICliServiceProvider, type ICliSpinner, type ICliStateStore, type ICliTerminalWriter, type ICliTextAnimator, type ICliTranslationService, ICliTranslationService_TOKEN, type ICliUmdModule, type ICliUser, type ICliUserCredentials, type ICliUserSession, type ICliUserSessionService, ICliUserSessionService_TOKEN, type ICliUsersStoreService, ICliUsersStoreService_TOKEN, type ISyntaxHighlightRule, type ISyntaxHighlighter, type ISyntaxTheme, LIBRARY_VERSION, type LineState, ObjectDescriber, type Package, type ServerVersionInfo, ServerVersionNegotiator, type WorkerServiceContext, bootCliModule, bootUmdModule, clearTerminalLine, colorFirstWord, colorizeJson, compareVersions, constants, createWorkerService, delay, derivePanelThemeStyles, enums, formatJson, getConfigValue, getParameterValue, getRightOfWord, highlightTextWithBg, initializeBrowserEnvironment, loadPanelPosition, nextPanelPosition, resolveConfigurationCategories, satisfiesMinVersion, satisfiesVersionRange, savePanelPosition, toQueryString, utils };
+export { API_VERSION, BrowserFileTransferService, CANCELLATION_ERROR_MESSAGE, CLI_CONFIGURE_STORE_NAME, CancellablePromise, type CliAddUser, CliBackgroundColor, type CliBackgroundServiceStatus, type CliBackgroundServiceType, type CliDateOptions, type CliEngineSnapshot, type CliFactoryProvider, type CliFilePickerOptions, type CliFileResult, CliForegroundColor, CliIcon, type CliLineOptions, CliLogLevel, CliModuleRegistry, type CliMultiSelectOption, type CliMultiSelectOptions, type CliNumberOptions, type CliOptions, type CliPackageSource, type CliPanelConfig, type CliPanelHideAlignment, type CliPanelPosition, type CliPercentageProgressBarUpdateValueOptions, type CliProcessCommand, type CliProcessorMetadata, type CliProvider, type CliSelectOption, type CliSelectOptions, type CliServerCapabilities, type CliServerCommandDescriptor, type CliServerConfig, type CliServerOutput, type CliServerResponse, type CliServiceEventHandler, type CliServiceExecutionMode, type CliServiceLogLevel, type CliState, type CliStateConfiguration, type CliTextAnimatorOptions, type CliTheme, type CliThemeCategory, type CliThemeInfo, type CliTypeProvider, type CliUpdateUser, type CliValueProvider, type CliWorkerInboundMessage, type CliWorkerOutboundMessage, DEFAULT_DIR_PERMISSIONS, DEFAULT_FILE_PERMISSIONS, DefaultLibraryAuthor, DefaultThemeInfos, DefaultThemes, type ICliAuthService, ICliAuthService_TOKEN, type ICliBackgroundService, type ICliBackgroundServiceInfo, type ICliBackgroundServiceRegistry, type ICliClipboard, type ICliCommandAuthor, type ICliCommandChildProcessor, type ICliCommandExecutorService, type ICliCommandParameterDescriptor, type ICliCommandProcessor, type ICliCommandProcessorRegistry, type ICliCompletionContext, type ICliCompletionProvider, ICliCompletionProvider_TOKEN, type ICliConfigurableModule, type ICliConfigurationOption, type ICliDragDropService, ICliDragDropService_TOKEN, type ICliExecutionContext, type ICliExecutionProcess, type ICliFileEntry, type ICliFilePickerProvider, ICliFilePickerProvider_TOKEN, type ICliFileTransferService, ICliFileTransferService_TOKEN, type ICliGlobalParameterHandler, type ICliGroup, type ICliGroupsStoreService, ICliGroupsStoreService_TOKEN, type ICliInputReader, type ICliKeyValueStore, type ICliLogger, type ICliManagedInterval, type ICliManagedTimer, type ICliModule, type ICliOwnership, type ICliPercentageProgressBar, type ICliPermissionService, ICliPermissionService_TOKEN, type ICliPingServerService, type ICliProcessEntry, type ICliProcessRegisterOptions, type ICliProcessRegistry, type ICliProcessorHook, type ICliProgressBar, type ICliServiceContext, type ICliServiceEvent, type ICliServiceLogEntry, type ICliServiceProvider, type ICliSpinner, type ICliStateStore, type ICliTerminalWriter, type ICliTextAnimator, type ICliTranslationService, ICliTranslationService_TOKEN, type ICliUmdModule, type ICliUser, type ICliUserCredentials, type ICliUserSession, type ICliUserSessionService, ICliUserSessionService_TOKEN, type ICliUsersStoreService, ICliUsersStoreService_TOKEN, type ISyntaxHighlightRule, type ISyntaxHighlighter, type ISyntaxTheme, LIBRARY_VERSION, type LineState, ObjectDescriber, type Package, type ServerVersionInfo, ServerVersionNegotiator, type WorkerServiceContext, bootCliModule, bootUmdModule, clearTerminalLine, colorFirstWord, colorizeJson, compareVersions, constants, createWorkerService, delay, derivePanelThemeStyles, enums, formatJson, getConfigValue, getParameterValue, getPluginConfigValue, getRightOfWord, highlightTextWithBg, initializeBrowserEnvironment, loadPanelPosition, nextPanelPosition, resolveConfigurationCategories, satisfiesMinVersion, satisfiesVersionRange, savePanelPosition, stripAnsi, toQueryString, utils, visibleLength };