@qodalis/cli-core 2.0.0-beta.11 → 2.0.0-beta.13

package/public-api.d.mts

@@ -1,5 +1,5 @@
 import { ITerminalOptions, ITerminalInitOnlyOptions, Terminal, ITheme } from '@xterm/xterm';
-import { Subject, Observable, Subscription } from 'rxjs';
+import { Observable, Subscription, Subject } from 'rxjs';
 
 type CliProcessCommand = {
     /**
@@ -170,559 +170,428 @@ declare enum CliIcon {
     Gift = "\uD83C\uDF81"
 }
 
-/**
- * Configuration for a remote CLI server
- */
-type CliServerConfig = {
-    /** Unique identifier, used for namespacing commands */
-    name: string;
-    /** Base URL of the server, e.g. "https://api.example.com" */
-    url: string;
-    /** Whether this server is enabled. @default true */
-    enabled?: boolean;
-    /** Custom headers sent with every request (e.g. auth tokens) */
-    headers?: Record<string, string>;
-    /** Request timeout in milliseconds. @default 30000 */
-    timeout?: number;
-};
-/**
- * A single output item in a server response
- */
-type CliServerOutput = {
-    type: 'text';
-    value: string;
-    style?: 'success' | 'error' | 'info' | 'warning';
-} | {
-    type: 'table';
-    headers: string[];
-    rows: string[][];
-} | {
-    type: 'list';
-    items: string[];
-    ordered?: boolean;
-} | {
-    type: 'json';
-    value: any;
-} | {
-    type: 'key-value';
-    entries: {
-        key: string;
-        value: string;
-    }[];
-};
-/**
- * Structured response from a server command execution
- */
-type CliServerResponse = {
-    exitCode: number;
-    outputs: CliServerOutput[];
-};
-/**
- * Metadata about a remote command processor, returned by GET /api/qcli/commands
- */
-type CliServerCommandDescriptor = {
-    command: string;
-    description?: string;
-    version?: string;
-    parameters?: {
-        name: string;
-        aliases?: string[];
-        description: string;
-        required: boolean;
-        type: string;
-        defaultValue?: any;
-    }[];
-    processors?: CliServerCommandDescriptor[];
-};
-/**
- * Server capabilities returned by GET /api/qcli/capabilities
- */
-type CliServerCapabilities = {
-    /** Whether this server supports remote shell access */
-    shell: boolean;
-    /** Server operating system (e.g. "linux", "win32", "darwin") */
-    os?: string;
-    /** Path to the shell binary on the server */
-    shellPath?: string;
-    /** Server version string */
-    version?: string;
-    /** Whether this server supports SSE streaming execution */
-    streaming?: boolean;
-};
-
-/**
- * Represents a package source for the CLI package manager
- */
-interface CliPackageSource {
+interface CliTableOptions {
+    /** Expand columns to fill the full terminal width. Default: false */
+    fullWidth?: boolean;
+}
+interface ICliTerminalWriter {
     /**
-     * The name of the source, e.g. 'local', 'unpkg', 'jsdelivr'
+     * Write text to the terminal
+     * @param text The text to write
      */
-    name: string;
+    write(text: string): void;
     /**
-     * The base URL for fetching package files, e.g. 'http://localhost:3000/'
+     * Write text to the terminal followed by a newline
+     * @param text The text to write
      */
-    url: string;
+    writeln(text?: string): void;
     /**
-     * The kind of source.
-     * - 'registry': npm-compatible registry with search API (e.g. npmjs.org, Verdaccio)
-     * - 'file': static file server, packages are discovered by probing known paths
-     * @default 'file'
+     * Write a success message to the terminal
+     * @param message The message to write
      */
-    kind?: 'registry' | 'file';
-}
-/**
- * Represents a log level for the CLI
- */
-declare enum CliLogLevel {
-    None = 0,
-    DEBUG = 1,
-    LOG = 2,
-    INFO = 3,
-    WARN = 4,
-    ERROR = 5
-}
-/**
- * Options for the CLI
- */
-type CliOptions = Record<string, any> & {
+    writeSuccess(message: string): void;
     /**
-     * Custom terminal options
+     * Write an info message to the terminal
+     * @param message The message to write
      */
-    terminalOptions?: ITerminalOptions & ITerminalInitOnlyOptions;
+    writeInfo(message: string): void;
     /**
-     * The minimum log level to display
+     * Write an error message to the terminal
+     * @param message The message to write
      */
-    logLevel?: CliLogLevel;
+    writeError(message: string): void;
     /**
-     * Custom package sources for the package manager.
-     * Built-in sources (unpkg, jsdelivr) are always available.
+     * Write a warning message to the terminal
+     * @param message The message to write
      */
-    packageSources?: {
-        /**
-         * Name of the primary source. Defaults to 'unpkg'.
-         */
-        primary?: string;
-        /**
-         * Additional custom sources
-         */
-        sources?: CliPackageSource[];
-    };
+    writeWarning(message: string): void;
     /**
-     * Remote CLI servers to connect to.
-     * Commands from each server are discovered and registered as proxy processors.
+     * 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
      */
-    servers?: CliServerConfig[];
+    wrapInColor(text: string, color: CliForegroundColor): string;
     /**
-     * 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
+     * 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
      */
-    allowEval?: boolean;
-};
-/**
- * Represents a package that can be installed
- */
-interface Package {
+    wrapInBackgroundColor(text: string, color: CliBackgroundColor): string;
     /**
-     * The name of the package
+     * Write a JSON object to the terminal
+     * @param json The JSON object to write
      */
-    name: string;
+    writeJson(json: any): void;
     /**
-     * The global name used to access the package
+     * 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
      */
-    globalName?: string;
+    writeToFile(fileName: string, content: string): void;
     /**
-     * The version of the package
+     * Write an object array as a table to the terminal
+     * @param objects The objects to write to the table
      */
-    version: string;
+    writeObjectsAsTable(objects: any[]): void;
     /**
-     * The unpkg url to the package
+     * Write a table to the terminal
+     * @param headers The headers of the table
+     * @param rows The rows of the table
+     * @param options Optional table rendering options
      */
-    url: string;
+    writeTable(headers: string[], rows: string[][], options?: CliTableOptions): void;
     /**
-     * The dependencies for the module
+     * Write a divider to the terminal
+     * @param options Optional: color, length, character
      */
-    dependencies?: Package[];
-}
-/**
- * Represents command processor metadata
- */
-type CliProcessorMetadata = Record<string, any> & {
+    writeDivider(options?: {
+        color?: CliForegroundColor;
+        length?: number;
+        char?: string;
+    }): void;
     /**
-     * If true, the processor is sealed and cannot be replaced or removed.
-     * Sealed processors can still be extended (wrapped) by processors with `extendsProcessor = true`.
+     * Write a list of items to the terminal with bullet, numbered, or custom prefix.
+     * @param items The list items to display
+     * @param options Optional: ordered (numbered), prefix (custom marker), color
      */
-    sealed?: boolean;
+    writeList(items: string[], options?: {
+        ordered?: boolean;
+        prefix?: string;
+        color?: CliForegroundColor;
+    }): void;
     /**
-     * If true, the processor requires the server to be running
+     * Write aligned key-value pairs to the terminal.
+     * @param entries Key-value pairs as a Record or array of tuples
+     * @param options Optional: separator string, key color
      */
-    requireServer?: boolean;
+    writeKeyValue(entries: Record<string, string> | [string, string][], options?: {
+        separator?: string;
+        keyColor?: CliForegroundColor;
+    }): void;
     /**
-     * The module the processor belongs to
+     * Write items in a multi-column layout.
+     * @param items The items to arrange in columns
+     * @param options Optional: number of columns, padding between columns
      */
-    module?: string;
+    writeColumns(items: string[], options?: {
+        columns?: number;
+        padding?: number;
+    }): void;
     /**
-     * An icon to display for the processor
+     * 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
      */
-    icon?: CliIcon | string;
+    writeLink(text: string, url: string): void;
     /**
-     * The minimum required version of @qodalis/cli-core for this processor.
-     * If the installed core version is lower, the processor will be skipped during boot.
+     * 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
      */
-    requiredCoreVersion?: string;
+    writeBox(content: string | string[], options?: {
+        title?: string;
+        borderColor?: CliForegroundColor;
+        padding?: number;
+    }): void;
     /**
-     * The minimum required version of @qodalis/cli for this processor.
-     * If the installed CLI version is lower, the processor will be skipped during boot.
-     */
-    requiredCliVersion?: string;
-    /**
-     * If true, the processor is hidden from the help command listing.
-     * The command still works when typed directly and `help <command>` still shows its details.
+     * 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)
      */
-    hidden?: boolean;
-};
+    writeIndented(text: string, level?: number): void;
+}
+
 /**
- * Represents a state configuration for the CLI processor
+ * Represents a clipboard for the CLI
  */
-type CliStateConfiguration = {
+interface ICliClipboard {
     /**
-     * The initial state for the processor
+     * Write text to the clipboard
+     * @param text The text to write to the clipboard
+     * @returns void
      */
-    initialState: Record<string, any>;
+    write: (text: string) => Promise<void>;
     /**
-     * The store identifier for the processor, if any
-     * @remarks If the store identifier is not set, the processor command name is used
+     * Read text from the clipboard
+     * @returns The text read from the clipboard
      */
-    storeName?: string;
-};
-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';
+    read: () => Promise<string>;
+}
+
 /**
- * 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
+ * Describes a global parameter (e.g. --help, --version) together with
+ * the handler that executes when the parameter is present.
+ *
+ * Global parameters are checked for every command before the command
+ * processor's own `processCommand` runs. If the handler returns `true`,
+ * command execution is halted (the parameter "consumed" the invocation).
  */
-type CliPanelHideAlignment = 'start' | 'center' | 'end';
+interface ICliGlobalParameterHandler {
+    /**
+     * The parameter descriptor shown in help output and used for tab-completion.
+     */
+    parameter: ICliCommandParameterDescriptor;
+    /**
+     * Execution priority — lower values run first.
+     * @default 0
+     */
+    priority?: number;
+    /**
+     * Evaluate and optionally handle the parameter.
+     * @returns `true` to halt command execution, `false` to continue.
+     */
+    handle(args: Record<string, any>, processor: ICliCommandProcessor, command: CliProcessCommand, context: ICliExecutionContext): boolean | Promise<boolean>;
+}
+
 /**
- * Configuration for the CLI panel component.
+ * Represents a service that executes commands
  */
-interface CliPanelConfig {
+interface ICliCommandExecutorService {
     /**
-     * Whether the CLI should be collapsed by default.
-     * @default true
+     * 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
      */
-    isCollapsed?: boolean;
+    showHelp(command: CliProcessCommand, context: ICliExecutionContext): Promise<void>;
     /**
-     * Whether the panel starts hidden (showing only the small tab/arrow).
-     * @default false
+     * Execute a command
+     * @param command The command to execute
+     * @param context The context in which the command is executed
      */
-    isHidden?: boolean;
+    executeCommand(command: string, context: ICliExecutionContext): Promise<void>;
     /**
-     * Position of the panel relative to the viewport.
-     * @default 'bottom'
+     * Register a global parameter handler.
+     * Global parameters (e.g. --help, --version) are evaluated for every
+     * command before the processor's own processCommand runs.
+     * @param handler The global parameter handler to register
      */
-    position?: CliPanelPosition;
+    registerGlobalParameter(handler: ICliGlobalParameterHandler): void;
     /**
-     * Whether the close button is shown.
-     * @default true
+     * Returns the descriptors of all registered global parameters.
+     * Used by help output and tab-completion.
      */
-    closable?: boolean;
+    getGlobalParameters(): ICliCommandParameterDescriptor[];
+}
+
+/**
+ * Represents a registry for command processors
+ */
+interface ICliCommandProcessorRegistry {
     /**
-     * Whether the panel can be resized by dragging.
-     * @default true
+     * The processors registered with the registry
      */
-    resizable?: boolean;
+    readonly processors: ICliCommandProcessor[];
     /**
-     * Whether the hide button is shown. When hidden, the panel collapses
-     * to a small tab at the viewport edge.
-     * @default true
+     * Find a processor for a command
+     * @param mainCommand
+     * @param chainCommands
      */
-    hideable?: boolean;
+    findProcessor(mainCommand: string, chainCommands: string[]): ICliCommandProcessor | undefined;
     /**
-     * Alignment of the hide tab along the panel's viewport edge.
-     * For bottom/top: 'start' = left, 'center', 'end' = right.
-     * For left/right: 'start' = top, 'center', 'end' = bottom.
-     * @default 'center'
+     * Recursively searches for a processor matching the given command.
+     * @param mainCommand The main command name.
+     * @param chainCommands The remaining chain commands (if any).
+     * @param processors The list of available processors.
+     * @returns The matching processor or undefined if not found.
      */
-    hideAlignment?: CliPanelHideAlignment;
+    findProcessorInCollection(mainCommand: string, chainCommands: string[], processors: ICliCommandProcessor[]): ICliCommandProcessor | undefined;
     /**
-     * When true, the panel's chrome (header, border, background) automatically
-     * syncs its colors with the active terminal theme. CSS custom properties
-     * are derived from the xterm theme and applied as inline styles.
-     * @default false
+     * Get the root processor for a child processor
+     * @param child The child processor
      */
-    syncTheme?: boolean;
-}
-
-type MultiServices = {
+    getRootProcessor(child: ICliCommandChildProcessor): ICliCommandProcessor;
     /**
-     * When true, injector returns an array of instances. This is useful to allow multiple
-     * providers spread across many files to provide configuration information to a common token.
+     * Register a processor
+     * @param processor
      */
-    multi?: boolean;
-};
-type CliValueProvider = MultiServices & {
-    useValue: any;
-};
-type CliTypeProvider = MultiServices & {
-    useClass: any;
-};
-type CliFactoryProvider = MultiServices & {
-    useFactory: Function;
-};
-type CliProvider = {
-    provide: any;
-} & (CliValueProvider | CliTypeProvider | CliFactoryProvider) & Record<string, any>;
-
+    registerProcessor(processor: ICliCommandProcessor): void;
+    /**
+     * Unregister a processor
+     * @param processor
+     */
+    unregisterProcessor(processor: ICliCommandProcessor): void;
+}
 /**
- * Represents a user in the CLI
+ * Represents a tracked CLI process entry
  */
-interface ICliUser {
-    /** Unique user identifier */
-    id: string;
-    /** Login name (unique) */
+interface ICliProcessEntry {
+    pid: number;
+    /** Display name (service name for bg services, command text for commands) */
     name: string;
-    /** Email address (unique) */
-    email: string;
-    /** Group IDs this user belongs to */
-    groups: string[];
-    /** Virtual home directory path, e.g. /home/root */
-    homeDir?: string;
-    /** Account creation timestamp */
-    createdAt: number;
-    /** Last modification timestamp */
-    updatedAt: number;
-    /** Whether the account is locked */
-    disabled?: boolean;
+    /** Process type */
+    type: 'command' | 'daemon' | 'job' | 'service';
+    command: string;
+    startTime: number;
+    status: 'running' | 'completed' | 'failed' | 'killed';
+    exitCode?: number;
 }
-/**
- * Represents user credentials (shadow pattern — stored separately from ICliUser)
- */
-interface ICliUserCredentials {
-    /** The user ID this credential belongs to */
-    userId: string;
-    /** SHA-256 hash of salt + password */
-    passwordHash: string;
-    /** Random salt for this user */
-    salt: string;
-    /** Timestamp of last password change */
-    lastChanged: number;
+/** Options for registering a process */
+interface ICliProcessRegisterOptions {
+    /** Display name (defaults to command) */
+    name?: string;
+    /** Process type (defaults to 'command') */
+    type?: 'command' | 'daemon' | 'job' | 'service';
+    /** Custom kill handler (e.g. for background services) */
+    onKill?: () => Promise<void> | void;
 }
 /**
- * Represents a group in the CLI
+ * Registry for tracking CLI processes
  */
-interface ICliGroup {
-    /** Unique group identifier */
-    id: string;
-    /** Group name (unique) */
-    name: string;
-    /** Optional group description */
-    description?: string;
-    /** Group creation timestamp */
-    createdAt: number;
+interface ICliProcessRegistry {
+    /** Register a new process, returns assigned PID */
+    register(command: string, options?: ICliProcessRegisterOptions): {
+        pid: number;
+        abortController: AbortController;
+    };
+    /** Mark process as completed */
+    complete(pid: number, exitCode: number): void;
+    /** Mark process as failed */
+    fail(pid: number): void;
+    /** Kill a process by PID */
+    kill(pid: number): boolean;
+    /** List all processes (running + recent completed) */
+    list(): ICliProcessEntry[];
+    /** Get the current foreground process PID */
+    readonly currentPid: number | undefined;
 }
-/**
- * Represents an active user session
- */
-interface ICliUserSession {
-    /** The user associated with this session */
-    user: ICliUser;
-    /** Pre-computed display name for the prompt (set by users module) */
-    displayName?: string;
-    /** Timestamp when the session started */
-    loginTime: number;
-    /** Timestamp of last activity */
-    lastActivity: number;
-    /** Extensible data (tokens, metadata, etc.) */
-    data?: Record<string, any>;
-}
-/** Fields required to create a new user */
-type CliAddUser = Omit<ICliUser, 'id' | 'createdAt' | 'updatedAt'>;
-/** Fields that can be updated on a user */
-type CliUpdateUser = Partial<Omit<ICliUser, 'id' | 'createdAt'>>;
-
-/** Ownership metadata attached to files, directories, or other resources */
-interface ICliOwnership {
-    /** User ID of the owner */
-    uid: string;
-    /** Primary group name */
-    gid: string;
-}
-/** Default file permissions: rw-r--r-- (644) */
-declare const DEFAULT_FILE_PERMISSIONS = "rw-r--r--";
-/** Default directory permissions: rwxr-xr-x (755) */
-declare const DEFAULT_DIR_PERMISSIONS = "rwxr-xr-x";
-
-declare const enums: {
-    CliForegroundColor: typeof CliForegroundColor;
-    CliBackgroundColor: typeof CliBackgroundColor;
-    CliIcon: typeof CliIcon;
-    CliLogLevel: typeof CliLogLevel;
-};
 
-interface CliTableOptions {
-    /** Expand columns to fill the full terminal width. Default: false */
-    fullWidth?: boolean;
-}
-interface ICliTerminalWriter {
+interface ICliExecutionProcess {
     /**
-     * Write text to the terminal
-     * @param text The text to write
+     * Indicates if the process has exited
      */
-    write(text: string): void;
+    exited?: boolean;
     /**
-     * Write text to the terminal followed by a newline
-     * @param text The text to write
+     * The exit code of the process
      */
-    writeln(text?: string): void;
+    exitCode?: number;
     /**
-     * Write a success message to the terminal
-     * @param message The message to write
+     * Indicates if the process is running
      */
-    writeSuccess(message: string): void;
+    running: boolean;
     /**
-     * Write an info message to the terminal
-     * @param message The message to write
+     * The data of the process
      */
-    writeInfo(message: string): void;
+    data: any | undefined;
     /**
-     * Write an error message to the terminal
-     * @param message The message to write
+     * Exit the process
+     * @param code The exit code
+     * @returns void
      */
-    writeError(message: string): void;
+    exit: (
     /**
-     * Write a warning message to the terminal
-     * @param message The message to write
+     * The exit code
      */
-    writeWarning(message: string): void;
+    code?: number, 
     /**
-     * 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
+     * Options for exiting the process
      */
-    wrapInColor(text: string, color: CliForegroundColor): string;
+    options?: {
+        /**
+         * Indicates if the exit should be silent, i.e. not throw an error
+         */
+        silent?: boolean;
+    }) => 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
+     * Output data from the process
+     * @param data The data to output
      */
-    wrapInBackgroundColor(text: string, color: CliBackgroundColor): string;
+    output(data: any): void;
+}
+
+/**
+ * Represents a key-value store for the CLI
+ */
+interface ICliKeyValueStore {
     /**
-     * Write a JSON object to the terminal
-     * @param json The JSON object to write
+     * Retrieves a value by key.
+     * @param key - The key to retrieve the value for.
+     * @returns A promise resolving to the value or undefined if not found.
      */
-    writeJson(json: any): void;
+    get<T = any>(key: string): Promise<T | undefined>;
     /**
-     * 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
+     * Sets a key-value pair in the store.
+     * @param key - The key to set.
+     * @param value - The value to store.
+     * @returns A promise resolving when the value is stored.
      */
-    writeToFile(fileName: string, content: string): void;
+    set(key: string, value: any): Promise<void>;
     /**
-     * Write an object array as a table to the terminal
-     * @param objects The objects to write to the table
+     * Removes a key-value pair by key.
+     * @param key - The key to remove.
+     * @returns A promise resolving when the key is removed.
      */
-    writeObjectsAsTable(objects: any[]): void;
+    remove(key: string): Promise<void>;
     /**
-     * Write a table to the terminal
-     * @param headers The headers of the table
-     * @param rows The rows of the table
-     * @param options Optional table rendering options
+     * Clears all key-value pairs from the store.
+     * @returns A promise resolving when the store is cleared.
      */
-    writeTable(headers: string[], rows: string[][], options?: CliTableOptions): void;
+    clear(): Promise<void>;
+}
+/**
+ * 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 {
     /**
-     * Write a divider to the terminal
-     * @param options Optional: color, length, character
+     * Get a snapshot of the current state.
+     * @returns A shallow copy of the state object
      */
-    writeDivider(options?: {
-        color?: CliForegroundColor;
-        length?: number;
-        char?: string;
-    }): void;
+    getState<T extends CliState = CliState>(): T;
     /**
-     * Write a list of items to the terminal with bullet, numbered, or custom prefix.
-     * @param items The list items to display
-     * @param options Optional: ordered (numbered), prefix (custom marker), color
+     * 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
      */
-    writeList(items: string[], options?: {
-        ordered?: boolean;
-        prefix?: string;
-        color?: CliForegroundColor;
-    }): void;
+    updateState(newState: Partial<CliState>): void;
     /**
-     * Write aligned key-value pairs to the terminal.
-     * @param entries Key-value pairs as a Record or array of tuples
-     * @param options Optional: separator string, key color
+     * Select a specific property or computed value from the state.
+     * @param selector A function to project a slice of the state.
+     * @returns Observable of the selected value.
      */
-    writeKeyValue(entries: Record<string, string> | [string, string][], options?: {
-        separator?: string;
-        keyColor?: CliForegroundColor;
-    }): void;
+    select<K>(selector: (state: CliState) => K): Observable<K>;
     /**
-     * Write items in a multi-column layout.
-     * @param items The items to arrange in columns
-     * @param options Optional: number of columns, padding between columns
+     * Subscribe to state changes.
+     * @param callback Callback function to handle state changes.
+     * @returns Subscription object to manage the subscription.
      */
-    writeColumns(items: string[], options?: {
-        columns?: number;
-        padding?: number;
-    }): void;
+    subscribe(callback: (state: CliState) => void): Subscription;
     /**
-     * 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
+     * Reset the state to its initial value.
      */
-    writeLink(text: string, url: string): void;
+    reset(): 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
+     * Persist the state to storage.
      */
-    writeBox(content: string | string[], options?: {
-        title?: string;
-        borderColor?: CliForegroundColor;
-        padding?: number;
-    }): void;
+    persist(): Promise<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)
+     * Initialize the state from storage.
      */
-    writeIndented(text: string, level?: number): void;
+    initialize(): Promise<void>;
 }
 
-/**
- * Represents a clipboard for the CLI
- */
-interface ICliClipboard {
-    /**
-     * Write text to the clipboard
-     * @param text The text to write to the clipboard
-     * @returns void
-     */
-    write: (text: string) => Promise<void>;
-    /**
-     * Read text from the clipboard
-     * @returns The text read from the clipboard
-     */
-    read: () => Promise<string>;
+/** Ownership metadata attached to files, directories, or other resources */
+interface ICliOwnership {
+    /** User ID of the owner */
+    uid: string;
+    /** Primary group name */
+    gid: string;
 }
+/** Default file permissions: rw-r--r-- (644) */
+declare const DEFAULT_FILE_PERMISSIONS = "rw-r--r--";
+/** Default directory permissions: rwxr-xr-x (755) */
+declare const DEFAULT_DIR_PERMISSIONS = "rwxr-xr-x";
 
 /**
  * Token for the CLI user session service.
@@ -764,6 +633,31 @@ declare const ICliPermissionService_TOKEN = "cli-permission-service";
  * Token for the file picker provider.
  */
 declare const ICliFilePickerProvider_TOKEN = "cli-file-picker-provider";
+/**
+ * Token for the HTTP client service.
+ */
+declare const ICliHttpClient_TOKEN = "cli-http-client";
+
+/**
+ * Abstract permission service for checking rwx permissions on resources.
+ * The default implementation lives in @qodalis/cli-users; consumers can
+ * replace it via the DI container.
+ */
+interface ICliPermissionService {
+    /**
+     * Check whether a user may perform an action on a resource.
+     * @param user        The acting user.
+     * @param action      The requested operation.
+     * @param ownership   Owner/group of the resource.
+     * @param permissions Permission string (e.g. "rwxr-xr-x").
+     * @returns true if allowed.
+     */
+    check(user: ICliUser, action: 'read' | 'write' | 'execute', ownership: ICliOwnership, permissions: string): boolean;
+    /** Parse octal (e.g. "755") to a permission string (e.g. "rwxr-xr-x"). */
+    parseOctal(octal: string): string;
+    /** Convert a permission string (e.g. "rwxr-xr-x") to octal (e.g. "755"). */
+    toOctal(permissions: string): string;
+}
 
 /**
  * Options for readFile file picker.
@@ -989,10 +883,210 @@ interface ICliInputReader {
 }
 
 /**
- * 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.
+ * Context passed to completion providers describing the current input state.
+ */
+interface ICliCompletionContext {
+    /** Full current line text */
+    input: string;
+    /** Cursor position in the line */
+    cursor: number;
+    /** The token (word) being completed at the cursor position */
+    token: string;
+    /** Start index of the token in the input string */
+    tokenStart: number;
+    /** Index of the token among all tokens (0 = command, 1+ = arguments) */
+    tokenIndex: number;
+    /** All tokens parsed from the input */
+    tokens: string[];
+}
+/**
+ * Provides tab-completion candidates for CLI input.
+ * Plugins can register providers to extend completion (e.g. file paths, custom values).
+ */
+interface ICliCompletionProvider {
+    /**
+     * Priority order. Lower values are checked first.
+     * Built-in defaults: 100 (commands), 200 (parameters).
+     * Plugins should use lower values (e.g. 50) to take precedence for specific commands.
+     */
+    priority: number;
+    /**
+     * Return completion candidates for the current input context.
+     * Return an empty array if this provider does not apply.
+     */
+    getCompletions(context: ICliCompletionContext): string[] | Promise<string[]>;
+}
+
+interface ICliProgressBar {
+    /**
+     * Indicates if the progress bar is running
+     */
+    isRunning: boolean;
+    /**
+     * Show the progress bar
+     */
+    show: (text?: string) => void;
+    /**
+     * Hide the progress bar
+     */
+    hide: () => void;
+}
+/**
+ * Represents a spinner for the CLI
+ */
+interface ICliSpinner extends ICliProgressBar {
+    /**
+     * Set the text of the spinner
+     * @param text The text to set
+     */
+    setText: (text: string) => void;
+}
+type CliPercentageProgressBarUpdateValueOptions = {
+    /**
+     * The type of update to perform
+     * @default 'replace'
+     */
+    type?: 'replace' | 'increment';
+};
+/**
+ * Represents a progress bar for the CLI
+ */
+interface ICliPercentageProgressBar extends ICliProgressBar {
+    /**
+     * 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;
+    /**
+     * Complete the progress bar
+     * @returns void
+     */
+    complete: () => void;
+    /**
+     * Set the text of the spinner
+     * @param text The text to set
+     */
+    setText: (text: string) => void;
+}
+type CliTextAnimatorOptions = {
+    /**
+     * The speed of the animation
+     * @default 100
+     */
+    speed?: number;
+    /**
+     * The text will be removed after typing
+     */
+    removeAfterTyping?: boolean;
+};
+interface ICliTextAnimator extends ICliProgressBar {
+    /**
+     * Show animated text in a typing and erasing effect.
+     * @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>;
+}
+
+/**
+ * Represents a service that manages user sessions in the CLI
+ */
+interface ICliUserSessionService {
+    /** Gets the current user session as a reactive stream */
+    getUserSession(): Observable<ICliUserSession | undefined>;
+    /** Sets the current user session */
+    setUserSession(session: ICliUserSession): Promise<void>;
+    /** Clears the current session (logout) */
+    clearSession(): Promise<void>;
+    /** Persists the current session to storage */
+    persistSession(): Promise<void>;
+    /** Restores a session from storage (called on boot) */
+    restoreSession(): Promise<ICliUserSession | undefined>;
+}
+/**
+ * Represents a service that manages users in the CLI
+ */
+interface ICliUsersStoreService {
+    /** Gets users with optional filtering and pagination */
+    getUsers(options?: {
+        query?: string;
+        skip?: number;
+        take?: number;
+    }): Observable<ICliUser[]>;
+    /** Creates a new user */
+    createUser(user: CliAddUser): Promise<ICliUser>;
+    /** Gets a user by id, name, or email */
+    getUser(id: string): Observable<ICliUser | undefined>;
+    /** Updates an existing user */
+    updateUser(id: string, updates: CliUpdateUser): Promise<ICliUser>;
+    /** Deletes a user by id */
+    deleteUser(id: string): Promise<void>;
+}
+/**
+ * Represents a service that manages groups in the CLI
+ */
+interface ICliGroupsStoreService {
+    /** Gets all groups */
+    getGroups(): Observable<ICliGroup[]>;
+    /** Gets a group by id or name */
+    getGroup(id: string): Observable<ICliGroup | undefined>;
+    /** Creates a new group */
+    createGroup(name: string, description?: string): Promise<ICliGroup>;
+    /** Deletes a group by id */
+    deleteGroup(id: string): Promise<void>;
+    /** Gets all users that belong to a group */
+    getGroupMembers(groupId: string): Observable<ICliUser[]>;
+}
+/**
+ * Represents a service that handles authentication in the CLI
+ */
+interface ICliAuthService {
+    /** Authenticates a user and returns a session */
+    login(username: string, password: string): Promise<ICliUserSession>;
+    /** Ends the current session */
+    logout(): Promise<void>;
+    /** Sets or updates a user's password */
+    setPassword(userId: string, password: string): Promise<void>;
+    /** Verifies a password against stored credentials */
+    verifyPassword(userId: string, password: string): Promise<boolean>;
+    /** Hashes a password with a salt using Web Crypto SHA-256 */
+    hashPassword(password: string, salt: string): Promise<string>;
+}
+
+/**
+ * Represents a serialized snapshot of a CLI engine's state.
+ * Used to duplicate terminal tabs with full state preservation.
+ */
+interface CliEngineSnapshot {
+    /** Schema version for forward compatibility */
+    version: 1;
+    /** Timestamp (ms since epoch) when the snapshot was taken */
+    timestamp: number;
+    /** Serialized terminal state */
+    terminal: {
+        /** Terminal buffer serialized via @xterm/addon-serialize */
+        serializedBuffer: string;
+        /** Terminal column count at time of snapshot */
+        cols: number;
+        /** Terminal row count at time of snapshot */
+        rows: number;
+    };
+    /** Command history entries (most recent last) */
+    commandHistory: string[];
+    /** Named state store entries */
+    stateStores: Array<{
+        name: string;
+        state: Record<string, any>;
+    }>;
+}
+
+/**
+ * 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.
  */
@@ -1122,6 +1216,485 @@ interface ICliBackgroundServiceRegistry {
     destroyAll(): Promise<void>;
 }
 
+/**
+ * Messages sent from the main thread to a background service Worker.
+ */
+type CliWorkerInboundMessage = {
+    type: 'start';
+    config?: Record<string, unknown>;
+} | {
+    type: 'stop';
+} | {
+    type: 'abort';
+};
+/**
+ * Messages sent from a background service Worker to the main thread.
+ */
+type CliWorkerOutboundMessage = {
+    type: 'log';
+    level: 'info' | 'warn' | 'error';
+    message: string;
+} | {
+    type: 'event';
+    event: Omit<ICliServiceEvent, 'timestamp'>;
+} | {
+    type: 'state-update';
+    patch: Record<string, unknown>;
+} | {
+    type: 'status';
+    status: CliBackgroundServiceStatus;
+} | {
+    type: 'error';
+    message: string;
+    stack?: string;
+};
+
+/**
+ * Represents an entry in a file listing.
+ */
+interface ICliFileEntry {
+    name: string;
+    type: 'file' | 'directory';
+    size: number;
+    modified: string;
+}
+
+/**
+ * Abstraction for file transfer operations.
+ * Default implementation uses browser-native APIs (file picker, download dialog).
+ * @qodalis/cli-files overrides with virtual FS backed by IndexedDB.
+ */
+interface ICliFileTransferService {
+    readFile(path: string): Promise<string | null>;
+    writeFile(path: string, content: string): Promise<void>;
+    listFiles(path: string): Promise<ICliFileEntry[]>;
+    exists(path: string): Promise<boolean>;
+    downloadToBrowser(filename: string, content: string | Blob): void;
+    uploadFromBrowser(accept?: string): Promise<{
+        name: string;
+        content: string;
+    } | null>;
+}
+
+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;
+    tokenType: string;
+    captureGroup?: number;
+}
+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[];
+    getNextLineState(line: string, currentState: LineState): LineState;
+}
+interface ISyntaxTheme {
+    name: string;
+    colors: Record<string, string>;
+}
+
+/**
+ * Represents a package source for the CLI package manager
+ */
+interface CliPackageSource {
+    /**
+     * The name of the source, e.g. 'local', 'unpkg', 'jsdelivr'
+     */
+    name: string;
+    /**
+     * The base URL for fetching package files, e.g. 'http://localhost:3000/'
+     */
+    url: string;
+    /**
+     * The kind of source.
+     * - 'registry': npm-compatible registry with search API (e.g. npmjs.org, Verdaccio)
+     * - 'file': static file server, packages are discovered by probing known paths
+     * @default 'file'
+     */
+    kind?: 'registry' | 'file';
+}
+/**
+ * Represents a log level for the CLI
+ */
+declare enum CliLogLevel {
+    None = 0,
+    DEBUG = 1,
+    LOG = 2,
+    INFO = 3,
+    WARN = 4,
+    ERROR = 5
+}
+/**
+ * Options for the CLI
+ */
+type CliOptions = Record<string, any> & {
+    /**
+     * Custom terminal options
+     */
+    terminalOptions?: ITerminalOptions & ITerminalInitOnlyOptions;
+    /**
+     * The minimum log level to display
+     */
+    logLevel?: CliLogLevel;
+    /**
+     * Custom package sources for the package manager.
+     * Built-in sources (unpkg, jsdelivr) are always available.
+     */
+    packageSources?: {
+        /**
+         * Name of the primary source. Defaults to 'unpkg'.
+         */
+        primary?: string;
+        /**
+         * Additional custom sources
+         */
+        sources?: CliPackageSource[];
+    };
+    /**
+     * Remote CLI servers to connect to.
+     * 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;
+};
+/**
+ * Represents a package that can be installed
+ */
+interface Package {
+    /**
+     * The name of the package
+     */
+    name: string;
+    /**
+     * The global name used to access the package
+     */
+    globalName?: string;
+    /**
+     * The version of the package
+     */
+    version: string;
+    /**
+     * The unpkg url to the package
+     */
+    url: string;
+    /**
+     * The dependencies for the module
+     */
+    dependencies?: Package[];
+}
+/**
+ * Represents command processor metadata
+ */
+type CliProcessorMetadata = Record<string, any> & {
+    /**
+     * If true, the processor is sealed and cannot be replaced or removed.
+     * Sealed processors can still be extended (wrapped) by processors with `extendsProcessor = true`.
+     */
+    sealed?: boolean;
+    /**
+     * If true, the processor requires the server to be running
+     */
+    requireServer?: boolean;
+    /**
+     * The module the processor belongs to
+     */
+    module?: string;
+    /**
+     * An icon to display for the processor
+     */
+    icon?: CliIcon | string;
+    /**
+     * The minimum required version of @qodalis/cli-core for this processor.
+     * If the installed core version is lower, the processor will be skipped during boot.
+     */
+    requiredCoreVersion?: string;
+    /**
+     * The minimum required version of @qodalis/cli for this processor.
+     * If the installed CLI version is lower, the processor will be skipped during boot.
+     */
+    requiredCliVersion?: string;
+    /**
+     * If true, the processor is hidden from the help command listing.
+     * The command still works when typed directly and `help <command>` still shows its details.
+     */
+    hidden?: boolean;
+};
+/**
+ * Represents a state configuration for the CLI processor
+ */
+type CliStateConfiguration = {
+    /**
+     * The initial state for the processor
+     */
+    initialState: Record<string, any>;
+    /**
+     * The store identifier for the processor, if any
+     * @remarks If the store identifier is not set, the processor command name is used
+     */
+    storeName?: string;
+};
+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';
+/**
+ * Configuration for the CLI panel component.
+ */
+interface CliPanelConfig {
+    /**
+     * Whether the CLI should be collapsed by default.
+     * @default true
+     */
+    isCollapsed?: boolean;
+    /**
+     * Whether the panel starts hidden (showing only the small tab/arrow).
+     * @default false
+     */
+    isHidden?: boolean;
+    /**
+     * Position of the panel relative to the viewport.
+     * @default 'bottom'
+     */
+    position?: CliPanelPosition;
+    /**
+     * Whether the close button is shown.
+     * @default true
+     */
+    closable?: boolean;
+    /**
+     * Whether the panel can be resized by dragging.
+     * @default true
+     */
+    resizable?: boolean;
+    /**
+     * Whether the hide button is shown. When hidden, the panel collapses
+     * to a small tab at the viewport edge.
+     * @default true
+     */
+    hideable?: boolean;
+    /**
+     * Alignment of the hide tab along the panel's viewport edge.
+     * For bottom/top: 'start' = left, 'center', 'end' = right.
+     * For left/right: 'start' = top, 'center', 'end' = bottom.
+     * @default 'center'
+     */
+    hideAlignment?: CliPanelHideAlignment;
+    /**
+     * When true, the panel's chrome (header, border, background) automatically
+     * syncs its colors with the active terminal theme. CSS custom properties
+     * are derived from the xterm theme and applied as inline styles.
+     * @default false
+     */
+    syncTheme?: boolean;
+}
+
+/**
+ * Framework-agnostic interface for programmatic control of the CLI panel.
+ *
+ * CliEngine is referenced as a generic to avoid a circular dependency
+ * between @qodalis/cli-core and @qodalis/cli. Framework implementations
+ * resolve this to the concrete CliEngine class.
+ */
+interface ICliPanelRef<TEngine = unknown> {
+    /** Expand the panel (sets collapsed=false). Initializes the first tab on first call. */
+    open(): void;
+    /** Collapse the panel body (sets collapsed=true). */
+    collapse(): void;
+    toggleCollapse(): void;
+    /** Hide the panel to a small viewport-edge tab (reversible via unhide). */
+    hide(): void;
+    unhide(): void;
+    toggleHide(): void;
+    /** Destroy the panel (removes from DOM). Irreversible. */
+    close(): void;
+    maximize(): void;
+    restore(): void;
+    toggleMaximize(): void;
+    /**
+     * Set panel dimensions. Only the dimension relevant to the current
+     * position is applied immediately (height for top/bottom, width for
+     * left/right). The other dimension is stored for when the position changes.
+     */
+    resize(dimensions: {
+        height?: number;
+        width?: number;
+    }): void;
+    setPosition(position: CliPanelPosition): void;
+    /** Create a new tab. Returns the new tab's ID. Title defaults to "Terminal {id}". */
+    addTab(title?: string): number;
+    /** Close a tab by ID. No-op if the ID does not exist. */
+    closeTab(tabId: number): void;
+    /** Activate a tab by ID. No-op if the ID does not exist. */
+    selectTab(tabId: number): void;
+    /** Programmatically rename a tab. No-op if the ID does not exist. */
+    renameTab(tabId: number, title: string): void;
+    /**
+     * Split the active pane (or a pane within the specified tab) to create
+     * a new pane to the right. Returns the new pane's ID.
+     */
+    splitPane(tabId?: number): number;
+    /**
+     * Close a pane by ID. Searches all tabs for the pane.
+     * No-op if the ID does not exist.
+     */
+    closePane(paneId: number): void;
+    /** Get the engine for a specific pane, or the active pane if omitted. */
+    getEngine(paneId?: number): TEngine | undefined;
+    getState(): CliPanelState;
+}
+interface CliPanelState {
+    collapsed: boolean;
+    hidden: boolean;
+    maximized: boolean;
+    position: CliPanelPosition;
+    height: number;
+    width: number;
+    activeTabId: number;
+    activePaneId: number;
+    tabs: CliPanelTabState[];
+}
+interface CliPanelTabState {
+    id: number;
+    title: string;
+    panes: CliPanelPaneState[];
+}
+interface CliPanelPaneState {
+    id: number;
+    widthPercent: number;
+}
+
+/**
+ * Options for HTTP client requests.
+ * Extends standard RequestInit with convenience fields.
+ */
+interface CliHttpRequestOptions extends Omit<RequestInit, 'method' | 'body'> {
+    /**
+     * Request timeout in milliseconds. When set, the request is automatically
+     * aborted after this duration. Combines with any existing abort signal.
+     */
+    timeout?: number;
+}
+/**
+ * HTTP client for making requests from command processors.
+ *
+ * Automatically merges the command's abort signal so that requests are
+ * cancelled when the user presses Ctrl+C. Provides typed convenience
+ * methods for common HTTP verbs as well as a raw `fetch()` for cases
+ * that need full Response access (streaming, progress, etc.).
+ *
+ * Available on the execution context as `context.http`.
+ *
+ * @example
+ * ```ts
+ * // Typed JSON response
+ * const users = await context.http.get<User[]>('https://api.example.com/users');
+ *
+ * // POST with body
+ * await context.http.post('https://api.example.com/users', { name: 'John' });
+ *
+ * // Raw fetch for streaming
+ * const response = await context.http.fetch('https://example.com/file.zip');
+ * const reader = response.body?.getReader();
+ * ```
+ */
+interface ICliHttpClient {
+    /**
+     * Make a raw HTTP request. Returns the full Response object for cases
+     * that need streaming, headers, or status inspection.
+     * The command's abort signal is automatically merged.
+     */
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+    /**
+     * HTTP GET request. Returns the parsed JSON response body.
+     */
+    get<T = any>(url: string, options?: CliHttpRequestOptions): Promise<T>;
+    /**
+     * HTTP POST request. Automatically serializes the body as JSON
+     * (unless body is FormData, Blob, string, or ArrayBuffer).
+     * Returns the parsed JSON response body.
+     */
+    post<T = any>(url: string, body?: any, options?: CliHttpRequestOptions): Promise<T>;
+    /**
+     * HTTP PUT request. Automatically serializes the body as JSON.
+     * Returns the parsed JSON response body.
+     */
+    put<T = any>(url: string, body?: any, options?: CliHttpRequestOptions): Promise<T>;
+    /**
+     * HTTP PATCH request. Automatically serializes the body as JSON.
+     * Returns the parsed JSON response body.
+     */
+    patch<T = any>(url: string, body?: any, options?: CliHttpRequestOptions): Promise<T>;
+    /**
+     * HTTP DELETE request. Returns the parsed JSON response body (if any).
+     */
+    delete<T = any>(url: string, options?: CliHttpRequestOptions): Promise<T>;
+    /**
+     * HTTP HEAD request. Returns the full Response (no body parsing).
+     */
+    head(url: string, options?: CliHttpRequestOptions): Promise<Response>;
+    /**
+     * HTTP OPTIONS request. Returns the parsed JSON response body.
+     */
+    options<T = any>(url: string, options?: CliHttpRequestOptions): Promise<T>;
+}
+
+type CliNotificationLevel = 'info' | 'success' | 'warn' | 'error';
+interface CliNotification {
+    level: CliNotificationLevel;
+    message: string;
+    timestamp: number;
+}
+
+interface ICliNotifier {
+    /** Set an info-level notification (progress, status updates). */
+    info(message: string): void;
+    /** Set a success-level notification. */
+    success(message: string): void;
+    /** Set a warn-level notification. */
+    warn(message: string): void;
+    /** Set an error-level notification. */
+    error(message: string): void;
+    /** Clear the current notification. */
+    clear(): void;
+    /** The current notification, or undefined if cleared. */
+    readonly current: CliNotification | undefined;
+    /** Observable that emits on every change (set or clear). */
+    readonly change$: Observable<CliNotification | undefined>;
+}
+
 /**
  * A managed timer handle returned by createInterval/createTimeout.
  * Managed timers are automatically cleared when full-screen mode exits
@@ -1214,6 +1787,27 @@ interface ICliExecutionContext {
         newLine?: boolean;
         keepCurrentLine?: boolean;
     }) => void;
+    /**
+     * Submit and execute a command — adds to history, runs the command,
+     * and shows a new prompt afterwards. Used by both interactive input
+     * and programmatic execution to ensure identical behaviour.
+     */
+    submitCommand(command: string): Promise<void>;
+    /**
+     * Notifier service for displaying status notifications in the panel header bar.
+     * Supports severity levels: info, success, warn, error.
+     * Cleared automatically when the command finishes.
+     *
+     * @example
+     * ```ts
+     * context.notifier.info('Downloading 45%...');
+     * context.notifier.success('Connected to server');
+     * context.notifier.warn('Rate limited, retrying...');
+     * context.notifier.error('Connection failed');
+     * context.notifier.clear();
+     * ```
+     */
+    notifier: ICliNotifier;
     /**
      * Set the current processor as the context processor, i.e. the processor that will handle the command
      * @param processor The processor to set
@@ -1271,565 +1865,318 @@ interface ICliExecutionContext {
     /**
      * Optional callback that returns the current path to display in the prompt.
      * Any plugin can set this to customize the path segment of the prompt
-     * (e.g. a filesystem plugin showing the current working directory).
-     * When set, the returned path replaces the default `~` in the prompt.
-     * Return null to fall back to the default `~`.
-     */
-    promptPathProvider?: () => string | null;
-    /**
-     * Enter full-screen mode: switches to the alternate screen buffer,
-     * positions the cursor at row 1 col 1, and sets the given processor
-     * as the context processor so that all terminal input is routed to
-     * its `onData` method.
-     *
-     * By default the cursor is hidden (suitable for games / editors that
-     * manage their own cursor). Pass `{ showCursor: true }` to keep it
-     * visible (suitable for REPL / input-line interfaces).
-     *
-     * @param processor The processor that will handle all input in full-screen mode
-     * @param options Optional settings for full-screen mode
-     */
-    enterFullScreenMode: (processor: ICliCommandProcessor, options?: CliFullScreenOptions) => void;
-    /**
-     * Exit full-screen mode: restores the cursor, leaves the alternate screen buffer,
-     * clears the context processor, and re-displays the prompt.
-     */
-    exitFullScreenMode: () => void;
-    /**
-     * Creates a managed interval that is automatically cleared when full-screen
-     * mode exits or the CLI component is destroyed.
-     * @param callback The function to call on each interval tick
-     * @param ms The interval delay in milliseconds
-     * @returns A managed interval handle with clear() and setDelay() methods
-     */
-    createInterval: (callback: () => void, ms: number) => ICliManagedInterval;
-    /**
-     * Creates a managed timeout that is automatically cleared when full-screen
-     * mode exits or the CLI component is destroyed.
-     * @param callback The function to call when the timeout fires
-     * @param ms The timeout delay in milliseconds
-     * @returns A managed timer handle with a clear() method
-     */
-    createTimeout: (callback: () => void, ms: number) => ICliManagedTimer;
-    /**
-     * Registry for managing background services and jobs.
-     * Each CLI session owns its own isolated registry. Services registered here
-     * are scoped to this session and destroyed when the engine shuts down.
-     */
-    backgroundServices: ICliBackgroundServiceRegistry;
-}
-
-interface ICliProcessorHook {
-    when: 'before' | 'after';
-    execute: (context: ICliExecutionContext) => Promise<void>;
-}
-
-interface ICliCommandAuthor {
-    /**
-     * The name of the author
-     */
-    name: string;
-    /**
-     * The email of the author
-     */
-    email: string;
-}
-/**
- * Represents a command parameter
- */
-interface ICliCommandParameterDescriptor {
-    /**
-     * The name of the parameter
-     */
-    name: string;
-    /**
-     * Aliases for the parameter
-     */
-    aliases?: string[];
-    /**
-     * A description of the parameter
-     */
-    description: string;
-    /**
-     * If true, the parameter is required
-     */
-    required: boolean;
-    /**
-     * The type of the parameter
-     */
-    type: 'string' | 'number' | 'boolean' | 'array' | 'object' | string;
-    /**
-     * The default value of the parameter
-     */
-    defaultValue?: any;
-    /**
-     * A validator function that validates the value of the parameter
-     * @param value The value to validate
-     * @returns An object with a valid property that indicates if the value is valid and an optional message property that contains a message to display if the value is not valid
-     */
-    validator?: (value: any) => {
-        /**
-         * Indicates if the value is valid
-         */
-        valid: boolean;
-        /**
-         * An optional message to display if the value is not valid
-         */
-        message?: string;
-    };
-}
-/**
- * Represents a configuration option that a command processor exposes
- * for management via the `configure` command.
- */
-interface ICliConfigurationOption {
-    /**
-     * The key used to store and retrieve this option, e.g. 'maxItems'
-     */
-    key: string;
-    /**
-     * Human-readable label shown in the interactive menu
-     */
-    label: string;
-    /**
-     * Description of what this option controls
-     */
-    description: string;
-    /**
-     * The data type of the option
-     */
-    type: 'string' | 'number' | 'boolean' | 'select';
-    /**
-     * The default value when no configuration has been set
-     */
-    defaultValue: any;
-    /**
-     * Available choices for 'select' type options
-     */
-    options?: {
-        label: string;
-        value: any;
-    }[];
-    /**
-     * Optional validator function
-     */
-    validator?: (value: any) => {
-        valid: boolean;
-        message?: string;
-    };
-    /**
-     * Override the category grouping (defaults to the processor command name)
-     */
-    category?: string;
-}
-/**
- * Represents a command processor
- */
-interface ICliCommandProcessor {
-    /**
-     * The command that this processor handles
-     */
-    command: string;
-    /**
-     * Alternative names for the command
-     */
-    aliases?: string[];
-    /**
-     * A description of the command
-     */
-    description?: string;
-    /**
-     * The author of the command
-     */
-    author?: ICliCommandAuthor;
-    /**
-     * If true, the processor accepts raw text input after the command name as its value.
-     * The captured text is available via `command.value` in `processCommand`.
-     * @default false
-     * @remarks When true, any text following the command name is extracted as the command value
-     * rather than being interpreted as sub-commands. Use `valueRequired` instead if the value is mandatory.
-     */
-    acceptsRawInput?: boolean;
-    /**
-     * If true, the command requires some form of input before it can execute.
-     *
-     * The requirement is satisfied by **any** of:
-     * - A positional value (text after the command name, available via `command.value`)
-     * - Piped data from a previous command (available via `command.data`)
-     * - Named arguments (e.g. `--server=node --path=/app`)
-     *
-     * When set, `command.value` is automatically extracted from the raw input
-     * (equivalent to setting `acceptsRawInput`).
-     *
-     * Additionally, when positional input is present the engine skips
-     * required-parameter validation — the processor is responsible for
-     * parsing positional text into individual values.  Required-parameter
-     * checks still apply when the user provides only named arguments.
-     *
-     * @default false
-     */
-    valueRequired?: boolean;
-    /**
-     * The version of the command processor
-     * @default '1.0.0'
-     */
-    version?: string;
-    /**
-     * The metadata for the command processor
-     */
-    metadata?: CliProcessorMetadata;
-    /**
-     * Processors that are nested under this processor
-     */
-    processors?: ICliCommandChildProcessor[];
-    /**
-     * Parameters that the command accepts
-     */
-    parameters?: ICliCommandParameterDescriptor[];
-    /**
-     * Hooks that are executed before and after the command is processed
-     */
-    hooks?: ICliProcessorHook[];
-    /**
-     * 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 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;
-    /**
-     * Configuration options exposed by this processor for the `configure` command.
-     * When defined, these options appear in the interactive configuration menu
-     * and can be managed via `configure get/set` subcommands.
-     */
-    configurationOptions?: ICliConfigurationOption[];
-    /**
-     * When true, this processor extends (wraps) an existing processor with the same
-     * command name instead of replacing it. The registry sets `originalProcessor`
-     * to the previous processor so this one can delegate to it.
-     */
-    extendsProcessor?: boolean;
-    /**
-     * Reference to the original processor that this one extends.
-     * Set automatically by the registry — do not set manually.
-     * Call `this.originalProcessor.processCommand(command, context)` to delegate.
+     * (e.g. a filesystem plugin showing the current working directory).
+     * When set, the returned path replaces the default `~` in the prompt.
+     * Return null to fall back to the default `~`.
      */
-    originalProcessor?: ICliCommandProcessor;
+    promptPathProvider?: () => string | null;
     /**
-     * Process the command
-     * @param command The command to process
-     * @param context The context in which the command is executed
+     * Enter full-screen mode: switches to the alternate screen buffer,
+     * positions the cursor at row 1 col 1, and sets the given processor
+     * as the context processor so that all terminal input is routed to
+     * its `onData` method.
+     *
+     * By default the cursor is hidden (suitable for games / editors that
+     * manage their own cursor). Pass `{ showCursor: true }` to keep it
+     * visible (suitable for REPL / input-line interfaces).
+     *
+     * @param processor The processor that will handle all input in full-screen mode
+     * @param options Optional settings for full-screen mode
      */
-    processCommand(command: CliProcessCommand, context: ICliExecutionContext): Promise<void>;
+    enterFullScreenMode: (processor: ICliCommandProcessor, options?: CliFullScreenOptions) => void;
     /**
-     * Write the description of the command
-     * @param context The context in which the command is executed
+     * Exit full-screen mode: restores the cursor, leaves the alternate screen buffer,
+     * clears the context processor, and re-displays the prompt.
      */
-    writeDescription?(context: ICliExecutionContext): void;
+    exitFullScreenMode: () => void;
     /**
-     * A function that validates the command before execution
-     * @param value The value to validate
-     * @returns An object with a valid property that indicates if the value is valid and an optional message property that contains a message to display if the value is not valid
+     * Creates a managed interval that is automatically cleared when full-screen
+     * mode exits or the CLI component is destroyed.
+     * @param callback The function to call on each interval tick
+     * @param ms The interval delay in milliseconds
+     * @returns A managed interval handle with clear() and setDelay() methods
      */
-    validateBeforeExecution?: (command: CliProcessCommand, context: ICliExecutionContext) => {
-        valid: boolean;
-        message?: string;
-    };
+    createInterval: (callback: () => void, ms: number) => ICliManagedInterval;
     /**
-     * Initialize the command processor
-     * @param context The context in which the command is executed
+     * Creates a managed timeout that is automatically cleared when full-screen
+     * mode exits or the CLI component is destroyed.
+     * @param callback The function to call when the timeout fires
+     * @param ms The timeout delay in milliseconds
+     * @returns A managed timer handle with a clear() method
      */
-    initialize?(context: ICliExecutionContext): Promise<void>;
+    createTimeout: (callback: () => void, ms: number) => ICliManagedTimer;
     /**
-     * Handle raw terminal data when this processor is the active context processor.
-     * When implemented, ALL terminal input is routed here instead of normal CLI input handling.
-     * Used for full-screen interactive modes (editors, pagers, etc.).
-     * @param data The raw terminal data string (escape sequences, control chars, printable text)
-     * @param context The execution context
+     * Registry for managing background services and jobs.
+     * Each CLI session owns its own isolated registry. Services registered here
+     * are scoped to this session and destroyed when the engine shuts down.
      */
-    onData?(data: string, context: ICliExecutionContext): Promise<void>;
+    backgroundServices: ICliBackgroundServiceRegistry;
     /**
-     * Called when the terminal is resized while this processor is the active
-     * full-screen context processor. Allows processors to adapt their rendering
-     * to the new terminal dimensions.
-     * @param cols The new number of columns
-     * @param rows The new number of rows
-     * @param context The execution context
+     * HTTP client for making requests. Automatically wires the command's
+     * abort signal so requests are cancelled on Ctrl+C.
+     *
+     * @example
+     * ```ts
+     * const data = await context.http.get<MyData>('https://api.example.com/data');
+     * ```
      */
-    onResize?(cols: number, rows: number, context: ICliExecutionContext): void;
+    http: ICliHttpClient;
+}
+
+interface ICliProcessorHook {
+    when: 'before' | 'after';
+    execute: (context: ICliExecutionContext) => Promise<void>;
+}
+
+interface ICliCommandAuthor {
     /**
-     * Called when the processor is being disposed — either because full-screen
-     * mode ended, the terminal disconnected, or the CLI component is being
-     * destroyed. Use this to clean up resources (timers, subscriptions, etc.).
-     * @param context The execution context
+     * The name of the author
      */
-    onDispose?(context: ICliExecutionContext): void;
-}
-/**
- * Represents a child command processor
- */
-interface ICliCommandChildProcessor extends ICliCommandProcessor {
+    name: string;
     /**
-     * The parent processor, it is populated by the processor manager
+     * The email of the author
      */
-    parent?: ICliCommandProcessor;
+    email: string;
 }
-
 /**
- * Describes a global parameter (e.g. --help, --version) together with
- * the handler that executes when the parameter is present.
- *
- * Global parameters are checked for every command before the command
- * processor's own `processCommand` runs. If the handler returns `true`,
- * command execution is halted (the parameter "consumed" the invocation).
+ * Represents a command parameter
  */
-interface ICliGlobalParameterHandler {
+interface ICliCommandParameterDescriptor {
     /**
-     * The parameter descriptor shown in help output and used for tab-completion.
+     * The name of the parameter
      */
-    parameter: ICliCommandParameterDescriptor;
+    name: string;
     /**
-     * Execution priority — lower values run first.
-     * @default 0
+     * Aliases for the parameter
      */
-    priority?: number;
+    aliases?: string[];
     /**
-     * Evaluate and optionally handle the parameter.
-     * @returns `true` to halt command execution, `false` to continue.
+     * A description of the parameter
      */
-    handle(args: Record<string, any>, processor: ICliCommandProcessor, command: CliProcessCommand, context: ICliExecutionContext): boolean | Promise<boolean>;
-}
-
-/**
- * Represents a service that executes commands
- */
-interface ICliCommandExecutorService {
+    description: string;
     /**
-     * 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
+     * If true, the parameter is required
      */
-    showHelp(command: CliProcessCommand, context: ICliExecutionContext): Promise<void>;
+    required: boolean;
     /**
-     * Execute a command
-     * @param command The command to execute
-     * @param context The context in which the command is executed
+     * The type of the parameter
      */
-    executeCommand(command: string, context: ICliExecutionContext): Promise<void>;
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object' | string;
     /**
-     * Register a global parameter handler.
-     * Global parameters (e.g. --help, --version) are evaluated for every
-     * command before the processor's own processCommand runs.
-     * @param handler The global parameter handler to register
+     * The default value of the parameter
      */
-    registerGlobalParameter(handler: ICliGlobalParameterHandler): void;
+    defaultValue?: any;
     /**
-     * Returns the descriptors of all registered global parameters.
-     * Used by help output and tab-completion.
+     * A validator function that validates the value of the parameter
+     * @param value The value to validate
+     * @returns An object with a valid property that indicates if the value is valid and an optional message property that contains a message to display if the value is not valid
      */
-    getGlobalParameters(): ICliCommandParameterDescriptor[];
+    validator?: (value: any) => {
+        /**
+         * Indicates if the value is valid
+         */
+        valid: boolean;
+        /**
+         * An optional message to display if the value is not valid
+         */
+        message?: string;
+    };
 }
-
 /**
- * Represents a registry for command processors
+ * Represents a configuration option that a command processor exposes
+ * for management via the `configure` command.
  */
-interface ICliCommandProcessorRegistry {
+interface ICliConfigurationOption {
     /**
-     * The processors registered with the registry
+     * The key used to store and retrieve this option, e.g. 'maxItems'
      */
-    readonly processors: ICliCommandProcessor[];
+    key: string;
     /**
-     * Find a processor for a command
-     * @param mainCommand
-     * @param chainCommands
+     * Human-readable label shown in the interactive menu
      */
-    findProcessor(mainCommand: string, chainCommands: string[]): ICliCommandProcessor | undefined;
+    label: string;
     /**
-     * Recursively searches for a processor matching the given command.
-     * @param mainCommand The main command name.
-     * @param chainCommands The remaining chain commands (if any).
-     * @param processors The list of available processors.
-     * @returns The matching processor or undefined if not found.
+     * Description of what this option controls
      */
-    findProcessorInCollection(mainCommand: string, chainCommands: string[], processors: ICliCommandProcessor[]): ICliCommandProcessor | undefined;
+    description: string;
     /**
-     * Get the root processor for a child processor
-     * @param child The child processor
+     * The data type of the option
      */
-    getRootProcessor(child: ICliCommandChildProcessor): ICliCommandProcessor;
+    type: 'string' | 'number' | 'boolean' | 'select';
     /**
-     * Register a processor
-     * @param processor
+     * The default value when no configuration has been set
      */
-    registerProcessor(processor: ICliCommandProcessor): void;
+    defaultValue: any;
     /**
-     * Unregister a processor
-     * @param processor
+     * Available choices for 'select' type options
      */
-    unregisterProcessor(processor: ICliCommandProcessor): void;
-}
-/**
- * Represents a tracked CLI process entry
- */
-interface ICliProcessEntry {
-    pid: number;
-    /** Display name (service name for bg services, command text for commands) */
-    name: string;
-    /** Process type */
-    type: 'command' | 'daemon' | 'job' | 'service';
-    command: string;
-    startTime: number;
-    status: 'running' | 'completed' | 'failed' | 'killed';
-    exitCode?: number;
-}
-/** Options for registering a process */
-interface ICliProcessRegisterOptions {
-    /** Display name (defaults to command) */
-    name?: string;
-    /** Process type (defaults to 'command') */
-    type?: 'command' | 'daemon' | 'job' | 'service';
-    /** Custom kill handler (e.g. for background services) */
-    onKill?: () => Promise<void> | void;
-}
-/**
- * Registry for tracking CLI processes
- */
-interface ICliProcessRegistry {
-    /** Register a new process, returns assigned PID */
-    register(command: string, options?: ICliProcessRegisterOptions): {
-        pid: number;
-        abortController: AbortController;
+    options?: {
+        label: string;
+        value: any;
+    }[];
+    /**
+     * Optional validator function
+     */
+    validator?: (value: any) => {
+        valid: boolean;
+        message?: string;
     };
-    /** Mark process as completed */
-    complete(pid: number, exitCode: number): void;
-    /** Mark process as failed */
-    fail(pid: number): void;
-    /** Kill a process by PID */
-    kill(pid: number): boolean;
-    /** List all processes (running + recent completed) */
-    list(): ICliProcessEntry[];
-    /** Get the current foreground process PID */
-    readonly currentPid: number | undefined;
+    /**
+     * Override the category grouping (defaults to the processor command name)
+     */
+    category?: string;
 }
-
-interface ICliExecutionProcess {
+/**
+ * Represents a command processor
+ */
+interface ICliCommandProcessor {
     /**
-     * Indicates if the process has exited
+     * The command that this processor handles
      */
-    exited?: boolean;
+    command: string;
     /**
-     * The exit code of the process
+     * Alternative names for the command
      */
-    exitCode?: number;
+    aliases?: string[];
     /**
-     * Indicates if the process is running
+     * A description of the command
      */
-    running: boolean;
+    description?: string;
     /**
-     * The data of the process
+     * The author of the command
      */
-    data: any | undefined;
+    author?: ICliCommandAuthor;
     /**
-     * Exit the process
-     * @param code The exit code
-     * @returns void
+     * If true, the processor accepts raw text input after the command name as its value.
+     * The captured text is available via `command.value` in `processCommand`.
+     * @default false
+     * @remarks When true, any text following the command name is extracted as the command value
+     * rather than being interpreted as sub-commands. Use `valueRequired` instead if the value is mandatory.
      */
-    exit: (
+    acceptsRawInput?: boolean;
     /**
-     * The exit code
+     * If true, the command requires some form of input before it can execute.
+     *
+     * The requirement is satisfied by **any** of:
+     * - A positional value (text after the command name, available via `command.value`)
+     * - Piped data from a previous command (available via `command.data`)
+     * - Named arguments (e.g. `--server=node --path=/app`)
+     *
+     * When set, `command.value` is automatically extracted from the raw input
+     * (equivalent to setting `acceptsRawInput`).
+     *
+     * Additionally, when positional input is present the engine skips
+     * required-parameter validation — the processor is responsible for
+     * parsing positional text into individual values.  Required-parameter
+     * checks still apply when the user provides only named arguments.
+     *
+     * @default false
      */
-    code?: number, 
+    valueRequired?: boolean;
     /**
-     * Options for exiting the process
+     * The version of the command processor
+     * @default '1.0.0'
      */
-    options?: {
-        /**
-         * Indicates if the exit should be silent, i.e. not throw an error
-         */
-        silent?: boolean;
-    }) => void;
+    version?: string;
     /**
-     * Output data from the process
-     * @param data The data to output
+     * The metadata for the command processor
      */
-    output(data: any): void;
-}
-
-/**
- * Represents a key-value store for the CLI
- */
-interface ICliKeyValueStore {
+    metadata?: CliProcessorMetadata;
     /**
-     * Retrieves a value by key.
-     * @param key - The key to retrieve the value for.
-     * @returns A promise resolving to the value or undefined if not found.
+     * Processors that are nested under this processor
      */
-    get<T = any>(key: string): Promise<T | undefined>;
+    processors?: ICliCommandChildProcessor[];
     /**
-     * Sets a key-value pair in the store.
-     * @param key - The key to set.
-     * @param value - The value to store.
-     * @returns A promise resolving when the value is stored.
+     * Parameters that the command accepts
      */
-    set(key: string, value: any): Promise<void>;
+    parameters?: ICliCommandParameterDescriptor[];
     /**
-     * Removes a key-value pair by key.
-     * @param key - The key to remove.
-     * @returns A promise resolving when the key is removed.
+     * Hooks that are executed before and after the command is processed
      */
-    remove(key: string): Promise<void>;
+    hooks?: ICliProcessorHook[];
     /**
-     * Clears all key-value pairs from the store.
-     * @returns A promise resolving when the store is cleared.
+     * 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 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
      */
-    clear(): Promise<void>;
-}
-/**
- * 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 {
+    stateConfiguration?: CliStateConfiguration;
     /**
-     * Get a snapshot of the current state.
-     * @returns A shallow copy of the state object
+     * Configuration options exposed by this processor for the `configure` command.
+     * When defined, these options appear in the interactive configuration menu
+     * and can be managed via `configure get/set` subcommands.
      */
-    getState<T extends CliState = CliState>(): T;
+    configurationOptions?: ICliConfigurationOption[];
     /**
-     * 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
+     * When true, this processor extends (wraps) an existing processor with the same
+     * command name instead of replacing it. The registry sets `originalProcessor`
+     * to the previous processor so this one can delegate to it.
      */
-    updateState(newState: Partial<CliState>): void;
+    extendsProcessor?: boolean;
     /**
-     * Select a specific property or computed value from the state.
-     * @param selector A function to project a slice of the state.
-     * @returns Observable of the selected value.
+     * Reference to the original processor that this one extends.
+     * Set automatically by the registry — do not set manually.
+     * Call `this.originalProcessor.processCommand(command, context)` to delegate.
      */
-    select<K>(selector: (state: CliState) => K): Observable<K>;
+    originalProcessor?: ICliCommandProcessor;
     /**
-     * Subscribe to state changes.
-     * @param callback Callback function to handle state changes.
-     * @returns Subscription object to manage the subscription.
+     * Process the command
+     * @param command The command to process
+     * @param context The context in which the command is executed
      */
-    subscribe(callback: (state: CliState) => void): Subscription;
+    processCommand(command: CliProcessCommand, context: ICliExecutionContext): Promise<void>;
     /**
-     * Reset the state to its initial value.
+     * Write the description of the command
+     * @param context The context in which the command is executed
      */
-    reset(): void;
+    writeDescription?(context: ICliExecutionContext): void;
     /**
-     * Persist the state to storage.
+     * A function that validates the command before execution
+     * @param value The value to validate
+     * @returns An object with a valid property that indicates if the value is valid and an optional message property that contains a message to display if the value is not valid
      */
-    persist(): Promise<void>;
+    validateBeforeExecution?: (command: CliProcessCommand, context: ICliExecutionContext) => {
+        valid: boolean;
+        message?: string;
+    };
     /**
-     * Initialize the state from storage.
+     * Initialize the command processor
+     * @param context The context in which the command is executed
      */
-    initialize(): Promise<void>;
+    initialize?(context: ICliExecutionContext): Promise<void>;
+    /**
+     * Handle raw terminal data when this processor is the active context processor.
+     * When implemented, ALL terminal input is routed here instead of normal CLI input handling.
+     * Used for full-screen interactive modes (editors, pagers, etc.).
+     * @param data The raw terminal data string (escape sequences, control chars, printable text)
+     * @param context The execution context
+     */
+    onData?(data: string, context: ICliExecutionContext): Promise<void>;
+    /**
+     * Called when the terminal is resized while this processor is the active
+     * full-screen context processor. Allows processors to adapt their rendering
+     * to the new terminal dimensions.
+     * @param cols The new number of columns
+     * @param rows The new number of rows
+     * @param context The execution context
+     */
+    onResize?(cols: number, rows: number, context: ICliExecutionContext): void;
+    /**
+     * Called when the processor is being disposed — either because full-screen
+     * mode ended, the terminal disconnected, or the CLI component is being
+     * destroyed. Use this to clean up resources (timers, subscriptions, etc.).
+     * @param context The execution context
+     */
+    onDispose?(context: ICliExecutionContext): void;
+}
+/**
+ * Represents a child command processor
+ */
+interface ICliCommandChildProcessor extends ICliCommandProcessor {
+    /**
+     * The parent processor, it is populated by the processor manager
+     */
+    parent?: ICliCommandProcessor;
 }
 
 /**
@@ -1974,446 +2321,354 @@ interface ICliLogger {
      * Log a debug message (DEBUG level)
      * @param args The arguments to log
      */
-    debug(...args: any[]): void;
-}
-
-/**
- * Provides internationalization (i18n) support for CLI strings.
- */
-interface ICliTranslationService {
-    /**
-     * Translate a key to the current locale.
-     * @param key The translation key (e.g. 'cli.echo.description')
-     * @param defaultValue The English fallback string (returned if no translation found)
-     * @param params Optional interpolation parameters for `{param}` placeholders
-     */
-    t(key: string, defaultValue: string, params?: Record<string, string | number>): string;
-    /**
-     * Get the current locale code (e.g. 'en', 'es', 'fr').
-     */
-    getLocale(): string;
-    /**
-     * Set the active locale.
-     * @param locale The locale code to switch to
-     */
-    setLocale(locale: string): void;
-    /**
-     * Register translations for a locale.
-     * Can be called multiple times — translations are merged, with later calls overriding earlier ones.
-     * @param locale The locale code
-     * @param translations Flat key-value map of translation keys to translated strings
-     */
-    addTranslations(locale: string, translations: Record<string, string>): void;
-    /**
-     * Get all locale codes that have at least one registered translation.
-     */
-    getAvailableLocales(): string[];
-}
-/**
- * Dependency injection container for CLI services.
- * Services are registered with string tokens and retrieved by type.
- */
-interface ICliServiceProvider {
-    /**
-     * 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 = unknown>(service: any): T;
-    /**
-     * Register one or more service definitions.
-     * @param definition A single provider or an array of providers to register
-     */
-    set(definition: CliProvider | CliProvider[]): void;
-}
-
-/**
- * Abstract permission service for checking rwx permissions on resources.
- * The default implementation lives in @qodalis/cli-users; consumers can
- * replace it via the DI container.
- */
-interface ICliPermissionService {
-    /**
-     * Check whether a user may perform an action on a resource.
-     * @param user        The acting user.
-     * @param action      The requested operation.
-     * @param ownership   Owner/group of the resource.
-     * @param permissions Permission string (e.g. "rwxr-xr-x").
-     * @returns true if allowed.
-     */
-    check(user: ICliUser, action: 'read' | 'write' | 'execute', ownership: ICliOwnership, permissions: string): boolean;
-    /** Parse octal (e.g. "755") to a permission string (e.g. "rwxr-xr-x"). */
-    parseOctal(octal: string): string;
-    /** Convert a permission string (e.g. "rwxr-xr-x") to octal (e.g. "755"). */
-    toOctal(permissions: string): string;
+    debug(...args: any[]): void;
 }
 
 /**
- * Context passed to completion providers describing the current input state.
- */
-interface ICliCompletionContext {
-    /** Full current line text */
-    input: string;
-    /** Cursor position in the line */
-    cursor: number;
-    /** The token (word) being completed at the cursor position */
-    token: string;
-    /** Start index of the token in the input string */
-    tokenStart: number;
-    /** Index of the token among all tokens (0 = command, 1+ = arguments) */
-    tokenIndex: number;
-    /** All tokens parsed from the input */
-    tokens: string[];
-}
-/**
- * Provides tab-completion candidates for CLI input.
- * Plugins can register providers to extend completion (e.g. file paths, custom values).
+ * Provides internationalization (i18n) support for CLI strings.
  */
-interface ICliCompletionProvider {
+interface ICliTranslationService {
     /**
-     * Priority order. Lower values are checked first.
-     * Built-in defaults: 100 (commands), 200 (parameters).
-     * Plugins should use lower values (e.g. 50) to take precedence for specific commands.
+     * Translate a key to the current locale.
+     * @param key The translation key (e.g. 'cli.echo.description')
+     * @param defaultValue The English fallback string (returned if no translation found)
+     * @param params Optional interpolation parameters for `{param}` placeholders
      */
-    priority: number;
+    t(key: string, defaultValue: string, params?: Record<string, string | number>): string;
     /**
-     * Return completion candidates for the current input context.
-     * Return an empty array if this provider does not apply.
+     * Get the current locale code (e.g. 'en', 'es', 'fr').
      */
-    getCompletions(context: ICliCompletionContext): string[] | Promise<string[]>;
-}
-
-interface ICliProgressBar {
+    getLocale(): string;
     /**
-     * Indicates if the progress bar is running
+     * Set the active locale.
+     * @param locale The locale code to switch to
      */
-    isRunning: boolean;
+    setLocale(locale: string): void;
     /**
-     * Show the progress bar
+     * Register translations for a locale.
+     * Can be called multiple times — translations are merged, with later calls overriding earlier ones.
+     * @param locale The locale code
+     * @param translations Flat key-value map of translation keys to translated strings
      */
-    show: (text?: string) => void;
+    addTranslations(locale: string, translations: Record<string, string>): void;
     /**
-     * Hide the progress bar
+     * Get all locale codes that have at least one registered translation.
      */
-    hide: () => void;
+    getAvailableLocales(): string[];
 }
 /**
- * Represents a spinner for the CLI
+ * Dependency injection container for CLI services.
+ * Services are registered with string tokens and retrieved by type.
  */
-interface ICliSpinner extends ICliProgressBar {
+interface ICliServiceProvider {
     /**
-     * Set the text of the spinner
-     * @param text The text to set
+     * Retrieve a service by its injection token.
+     * Returns `undefined` when no provider is registered for the token.
+     * For multi-provider tokens, returns the last registered value (use `getAll` for the full array).
+     * @param service The token (typically a `*_TOKEN` constant) identifying the service
+     * @returns The service instance cast to `T`, or `undefined` if not registered
      */
-    setText: (text: string) => void;
-}
-type CliPercentageProgressBarUpdateValueOptions = {
+    get<T = unknown>(service: any): T | undefined;
     /**
-     * The type of update to perform
-     * @default 'replace'
+     * Retrieve all registered services for a multi-provider token.
+     * Returns an empty array when no provider is registered for the token.
+     * @param service The token (typically a `*_TOKEN` constant) identifying the service
+     * @returns Array of all resolved service instances
      */
-    type?: 'replace' | 'increment';
-};
-/**
- * Represents a progress bar for the CLI
- */
-interface ICliPercentageProgressBar extends ICliProgressBar {
+    getAll<T = unknown>(service: any): T[];
     /**
-     * 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')
+     * Retrieve a service by its injection token, throwing if not registered.
+     * Use this when the service is required and its absence is a programming error.
+     * For multi-provider tokens, returns the last registered value (use `getAll` for the full array).
+     * @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
      */
-    update: (progress: number, options?: CliPercentageProgressBarUpdateValueOptions) => void;
+    getRequired<T = unknown>(service: any): T;
     /**
-     * Complete the progress bar
-     * @returns void
+     * Check whether a service is registered for the given token.
+     * @param service The token identifying the service
+     * @returns `true` if a service is registered, `false` otherwise
      */
-    complete: () => void;
+    has(service: any): boolean;
     /**
-     * Set the text of the spinner
-     * @param text The text to set
+     * Register one or more service definitions.
+     * @param definition A single provider or an array of providers to register
      */
-    setText: (text: string) => void;
+    set(definition: CliProvider | CliProvider[]): void;
 }
-type CliTextAnimatorOptions = {
-    /**
-     * The speed of the animation
-     * @default 100
-     */
-    speed?: number;
+/** DI token for `ICliServerAuthTokenProvider` (multi-provider) */
+declare const ICliServerAuthTokenProvider_TOKEN = "cli-server-auth-token-provider";
+/** DI token for `ICliServerAuthService` */
+declare const ICliServerAuthService_TOKEN = "cli-server-auth-service";
+/**
+ * Integrators implement this interface to supply auth credentials
+ * for server requests. Multiple providers can be registered — the
+ * auth service merges headers from all of them (later providers
+ * override earlier ones for the same header name).
+ *
+ * @example
+ * ```ts
+ * class MyAuthProvider implements ICliServerAuthTokenProvider {
+ *     getHeaders(serverName: string) {
+ *         return { Authorization: `Bearer ${this.oauthService.getAccessToken()}` };
+ *     }
+ * }
+ *
+ * // Register in a module:
+ * const myModule: ICliModule = {
+ *     name: 'my-auth',
+ *     services: [{
+ *         provide: ICliServerAuthTokenProvider_TOKEN,
+ *         useValue: new MyAuthProvider(),
+ *         multi: true,
+ *     }],
+ * };
+ * ```
+ */
+interface ICliServerAuthTokenProvider {
     /**
-     * The text will be removed after typing
+     * Return headers for a given server. Called on every request,
+     * so implementations can return fresh tokens.
+     *
+     * @param serverName  The `name` field from `CliServerConfig`
+     * @returns Headers to merge into the request, or an empty object
      */
-    removeAfterTyping?: boolean;
-};
-interface ICliTextAnimator extends ICliProgressBar {
+    getHeaders(serverName: string): Record<string, string>;
+}
+/**
+ * Internal service that resolves auth headers for a server by merging:
+ * 1. Static/dynamic headers from `CliServerConfig.headers`
+ * 2. Headers from all registered `ICliServerAuthTokenProvider`s
+ *
+ * Consumers should use this service instead of reading `config.headers` directly.
+ */
+interface ICliServerAuthService {
     /**
-     * Show animated text in a typing and erasing effect.
-     * @param text The text to animate
-     * @param options Optional: speed (ms per character), removeAfterTyping
-     * @returns A promise that resolves when the animation completes
+     * Resolve the final set of headers for a server request.
+     * Merges config headers with all registered token providers.
+     *
+     * @param serverName  The server's `name` field
+     * @param configHeaders  The `headers` field from `CliServerConfig`
+     * @returns Merged headers ready for use in fetch/WebSocket calls
      */
-    showText: (text: string, options?: CliTextAnimatorOptions) => Promise<void>;
+    getHeaders(serverName: string, configHeaders?: CliHeadersProvider): Record<string, string>;
 }
 
 /**
- * Represents a service that manages user sessions in the CLI
+ * A static header map or a function that returns one.
+ * Use a function when headers contain short-lived tokens (e.g. JWTs)
+ * so that every request gets a fresh value.
+ *
+ * @example
+ * // Static
+ * headers: { 'X-Api-Key': 'abc123' }
+ *
+ * // Dynamic (token refresh)
+ * headers: () => ({ Authorization: `Bearer ${auth.getToken()}` })
  */
-interface ICliUserSessionService {
-    /** Gets the current user session as a reactive stream */
-    getUserSession(): Observable<ICliUserSession | undefined>;
-    /** Sets the current user session */
-    setUserSession(session: ICliUserSession): Promise<void>;
-    /** Clears the current session (logout) */
-    clearSession(): Promise<void>;
-    /** Persists the current session to storage */
-    persistSession(): Promise<void>;
-    /** Restores a session from storage (called on boot) */
-    restoreSession(): Promise<ICliUserSession | undefined>;
-}
+type CliHeadersProvider = Record<string, string> | (() => Record<string, string>);
 /**
- * Represents a service that manages users in the CLI
+ * Resolves a CliHeadersProvider to a plain header map.
  */
-interface ICliUsersStoreService {
-    /** Gets users with optional filtering and pagination */
-    getUsers(options?: {
-        query?: string;
-        skip?: number;
-        take?: number;
-    }): Observable<ICliUser[]>;
-    /** Creates a new user */
-    createUser(user: CliAddUser): Promise<ICliUser>;
-    /** Gets a user by id, name, or email */
-    getUser(id: string): Observable<ICliUser | undefined>;
-    /** Updates an existing user */
-    updateUser(id: string, updates: CliUpdateUser): Promise<ICliUser>;
-    /** Deletes a user by id */
-    deleteUser(id: string): Promise<void>;
-}
+declare function resolveHeaders(provider?: CliHeadersProvider): Record<string, string>;
 /**
- * Represents a service that manages groups in the CLI
+ * Resolves auth headers for a server request using the auth service if available,
+ * otherwise falls back to resolving config headers directly.
+ *
+ * This is the single entry point plugins should use to get headers for server requests.
+ *
+ * @param services  The service provider (from context.services)
+ * @param serverName  The server name
+ * @param configHeaders  The headers from CliServerConfig
+ * @returns Resolved headers ready for use
  */
-interface ICliGroupsStoreService {
-    /** Gets all groups */
-    getGroups(): Observable<ICliGroup[]>;
-    /** Gets a group by id or name */
-    getGroup(id: string): Observable<ICliGroup | undefined>;
-    /** Creates a new group */
-    createGroup(name: string, description?: string): Promise<ICliGroup>;
-    /** Deletes a group by id */
-    deleteGroup(id: string): Promise<void>;
-    /** Gets all users that belong to a group */
-    getGroupMembers(groupId: string): Observable<ICliUser[]>;
-}
+declare function resolveServerHeaders(services: ICliServiceProvider | undefined, serverName: string, configHeaders?: CliHeadersProvider): Record<string, string>;
 /**
- * Represents a service that handles authentication in the CLI
+ * Configuration for a remote CLI server
  */
-interface ICliAuthService {
-    /** Authenticates a user and returns a session */
-    login(username: string, password: string): Promise<ICliUserSession>;
-    /** Ends the current session */
-    logout(): Promise<void>;
-    /** Sets or updates a user's password */
-    setPassword(userId: string, password: string): Promise<void>;
-    /** Verifies a password against stored credentials */
-    verifyPassword(userId: string, password: string): Promise<boolean>;
-    /** Hashes a password with a salt using Web Crypto SHA-256 */
-    hashPassword(password: string, salt: string): Promise<string>;
-}
-
+type CliServerConfig = {
+    /** Unique identifier, used for namespacing commands */
+    name: string;
+    /** Base URL of the server, e.g. "https://api.example.com" */
+    url: string;
+    /** Whether this server is enabled. @default true */
+    enabled?: boolean;
+    /**
+     * Custom headers sent with every request (e.g. auth tokens).
+     * Can be a static object or a function that returns fresh headers
+     * on each call (useful for rotating tokens / JWTs).
+     */
+    headers?: CliHeadersProvider;
+    /** Request timeout in milliseconds. @default 30000 */
+    timeout?: number;
+};
 /**
- * Represents a serialized snapshot of a CLI engine's state.
- * Used to duplicate terminal tabs with full state preservation.
+ * A single output item in a server response
  */
-interface CliEngineSnapshot {
-    /** Schema version for forward compatibility */
-    version: 1;
-    /** Timestamp (ms since epoch) when the snapshot was taken */
-    timestamp: number;
-    /** Serialized terminal state */
-    terminal: {
-        /** Terminal buffer serialized via @xterm/addon-serialize */
-        serializedBuffer: string;
-        /** Terminal column count at time of snapshot */
-        cols: number;
-        /** Terminal row count at time of snapshot */
-        rows: number;
-    };
-    /** Command history entries (most recent last) */
-    commandHistory: string[];
-    /** Named state store entries */
-    stateStores: Array<{
-        name: string;
-        state: Record<string, any>;
-    }>;
-}
-
+type CliServerOutput = {
+    type: 'text';
+    value: string;
+    style?: 'success' | 'error' | 'info' | 'warning';
+} | {
+    type: 'table';
+    headers: string[];
+    rows: string[][];
+} | {
+    type: 'list';
+    items: string[];
+    ordered?: boolean;
+} | {
+    type: 'json';
+    value: any;
+} | {
+    type: 'key-value';
+    entries: {
+        key: string;
+        value: string;
+    }[];
+};
+/**
+ * Structured response from a server command execution
+ */
+type CliServerResponse = {
+    exitCode: number;
+    outputs: CliServerOutput[];
+};
 /**
- * Messages sent from the main thread to a background service Worker.
+ * Metadata about a remote command processor, returned by GET /api/qcli/commands
  */
-type CliWorkerInboundMessage = {
-    type: 'start';
-    config?: Record<string, unknown>;
-} | {
-    type: 'stop';
-} | {
-    type: 'abort';
+type CliServerCommandDescriptor = {
+    command: string;
+    description?: string;
+    version?: string;
+    parameters?: {
+        name: string;
+        aliases?: string[];
+        description: string;
+        required: boolean;
+        type: string;
+        defaultValue?: any;
+    }[];
+    processors?: CliServerCommandDescriptor[];
 };
 /**
- * Messages sent from a background service Worker to the main thread.
+ * Server capabilities returned by GET /api/qcli/capabilities
  */
-type CliWorkerOutboundMessage = {
-    type: 'log';
-    level: 'info' | 'warn' | 'error';
-    message: string;
-} | {
-    type: 'event';
-    event: Omit<ICliServiceEvent, 'timestamp'>;
-} | {
-    type: 'state-update';
-    patch: Record<string, unknown>;
-} | {
-    type: 'status';
-    status: CliBackgroundServiceStatus;
-} | {
-    type: 'error';
-    message: string;
-    stack?: string;
+type CliServerCapabilities = {
+    /** Whether this server supports remote shell access */
+    shell: boolean;
+    /** Server operating system (e.g. "linux", "win32", "darwin") */
+    os?: string;
+    /** Path to the shell binary on the server */
+    shellPath?: string;
+    /** Server version string */
+    version?: string;
+    /** Whether this server supports SSE streaming execution */
+    streaming?: boolean;
+};
+
+type MultiServices = {
+    /**
+     * When true, injector returns an array of instances. This is useful to allow multiple
+     * providers spread across many files to provide configuration information to a common token.
+     */
+    multi?: boolean;
+};
+type CliValueProvider = MultiServices & {
+    useValue: any;
 };
+type CliTypeProvider = MultiServices & {
+    useClass: any;
+    /** DI tokens resolved from the container and passed as constructor arguments. */
+    deps?: any[];
+};
+type CliFactoryProvider = MultiServices & {
+    useFactory: Function;
+    /** DI tokens resolved from the container and passed as factory arguments. */
+    deps?: any[];
+};
+type CliProvider = {
+    provide: any;
+    /** When true, this token is sealed after registration and cannot be overwritten. */
+    sealed?: boolean;
+    /** When true, a new instance is created on every `get()` call instead of returning a singleton. */
+    transient?: boolean;
+} & (CliValueProvider | CliTypeProvider | CliFactoryProvider) & Record<string, any>;
 
 /**
- * Represents an entry in a file listing.
+ * Represents a user in the CLI
  */
-interface ICliFileEntry {
+interface ICliUser {
+    /** Unique user identifier */
+    id: string;
+    /** Login name (unique) */
     name: string;
-    type: 'file' | 'directory';
-    size: number;
-    modified: string;
+    /** Email address (unique) */
+    email: string;
+    /** Group IDs this user belongs to */
+    groups: string[];
+    /** Virtual home directory path, e.g. /home/root */
+    homeDir?: string;
+    /** Account creation timestamp */
+    createdAt: number;
+    /** Last modification timestamp */
+    updatedAt: number;
+    /** Whether the account is locked */
+    disabled?: boolean;
 }
-
 /**
- * Abstraction for file transfer operations.
- * Default implementation uses browser-native APIs (file picker, download dialog).
- * @qodalis/cli-files overrides with virtual FS backed by IndexedDB.
+ * Represents user credentials (shadow pattern — stored separately from ICliUser)
  */
-interface ICliFileTransferService {
-    readFile(path: string): Promise<string | null>;
-    writeFile(path: string, content: string): Promise<void>;
-    listFiles(path: string): Promise<ICliFileEntry[]>;
-    exists(path: string): Promise<boolean>;
-    downloadToBrowser(filename: string, content: string | Blob): void;
-    uploadFromBrowser(accept?: string): Promise<{
-        name: string;
-        content: string;
-    } | null>;
-}
-
-interface ICliDragDropService {
-    /** Emits an array of dropped File objects each time files are dropped onto the terminal */
-    readonly onFileDrop: Observable<File[]>;
+interface ICliUserCredentials {
+    /** The user ID this credential belongs to */
+    userId: string;
+    /** SHA-256 hash of salt + password */
+    passwordHash: string;
+    /** Random salt for this user */
+    salt: string;
+    /** Timestamp of last password change */
+    lastChanged: number;
 }
-
 /**
- * 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.
+ * Represents a group in the CLI
  */
-type LineState = number;
-interface ISyntaxHighlightRule {
-    pattern: RegExp;
-    tokenType: string;
-    captureGroup?: number;
-}
-interface ISyntaxHighlighter {
+interface ICliGroup {
+    /** Unique group identifier */
     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[];
-    getNextLineState(line: string, currentState: LineState): LineState;
-}
-interface ISyntaxTheme {
+    /** Group name (unique) */
     name: string;
-    colors: Record<string, string>;
+    /** Optional group description */
+    description?: string;
+    /** Group creation timestamp */
+    createdAt: number;
 }
-
 /**
- * Framework-agnostic interface for programmatic control of the CLI panel.
- *
- * CliEngine is referenced as a generic to avoid a circular dependency
- * between @qodalis/cli-core and @qodalis/cli. Framework implementations
- * resolve this to the concrete CliEngine class.
+ * Represents an active user session
  */
-interface ICliPanelRef<TEngine = unknown> {
-    /** Expand the panel (sets collapsed=false). Initializes the first tab on first call. */
-    open(): void;
-    /** Collapse the panel body (sets collapsed=true). */
-    collapse(): void;
-    toggleCollapse(): void;
-    /** Hide the panel to a small viewport-edge tab (reversible via unhide). */
-    hide(): void;
-    unhide(): void;
-    toggleHide(): void;
-    /** Destroy the panel (removes from DOM). Irreversible. */
-    close(): void;
-    maximize(): void;
-    restore(): void;
-    toggleMaximize(): void;
-    /**
-     * Set panel dimensions. Only the dimension relevant to the current
-     * position is applied immediately (height for top/bottom, width for
-     * left/right). The other dimension is stored for when the position changes.
-     */
-    resize(dimensions: {
-        height?: number;
-        width?: number;
-    }): void;
-    setPosition(position: CliPanelPosition): void;
-    /** Create a new tab. Returns the new tab's ID. Title defaults to "Terminal {id}". */
-    addTab(title?: string): number;
-    /** Close a tab by ID. No-op if the ID does not exist. */
-    closeTab(tabId: number): void;
-    /** Activate a tab by ID. No-op if the ID does not exist. */
-    selectTab(tabId: number): void;
-    /** Programmatically rename a tab. No-op if the ID does not exist. */
-    renameTab(tabId: number, title: string): void;
-    /**
-     * Split the active pane (or a pane within the specified tab) to create
-     * a new pane to the right. Returns the new pane's ID.
-     */
-    splitPane(tabId?: number): number;
-    /**
-     * Close a pane by ID. Searches all tabs for the pane.
-     * No-op if the ID does not exist.
-     */
-    closePane(paneId: number): void;
-    /** Get the engine for a specific pane, or the active pane if omitted. */
-    getEngine(paneId?: number): TEngine | undefined;
-    getState(): CliPanelState;
-}
-interface CliPanelState {
-    collapsed: boolean;
-    hidden: boolean;
-    maximized: boolean;
-    position: CliPanelPosition;
-    height: number;
-    width: number;
-    activeTabId: number;
-    activePaneId: number;
-    tabs: CliPanelTabState[];
-}
-interface CliPanelTabState {
-    id: number;
-    title: string;
-    panes: CliPanelPaneState[];
-}
-interface CliPanelPaneState {
-    id: number;
-    widthPercent: number;
+interface ICliUserSession {
+    /** The user associated with this session */
+    user: ICliUser;
+    /** Pre-computed display name for the prompt (set by users module) */
+    displayName?: string;
+    /** Timestamp when the session started */
+    loginTime: number;
+    /** Timestamp of last activity */
+    lastActivity: number;
+    /** Extensible data (tokens, metadata, etc.) */
+    data?: Record<string, any>;
 }
+/** Fields required to create a new user */
+type CliAddUser = Omit<ICliUser, 'id' | 'createdAt' | 'updatedAt'>;
+/** Fields that can be updated on a user */
+type CliUpdateUser = Partial<Omit<ICliUser, 'id' | 'createdAt'>>;
+
+declare const enums: {
+    CliForegroundColor: typeof CliForegroundColor;
+    CliBackgroundColor: typeof CliBackgroundColor;
+    CliIcon: typeof CliIcon;
+    CliLogLevel: typeof CliLogLevel;
+};
 
 /**
  * Registry that tracks loaded web CLI modules (frontend plugins) and dispatches
@@ -2577,12 +2832,36 @@ declare class ServerVersionNegotiator {
      * Returns the negotiated API version and the base path for all subsequent calls,
      * or null if the server is unreachable or incompatible.
      */
-    static discover(baseUrl: string): Promise<{
+    static discover(baseUrl: string, headers?: CliHeadersProvider): Promise<{
         apiVersion: number;
         basePath: string;
     } | null>;
 }
 
+/**
+ * Builds a WebSocket URL that includes authentication credentials from headers
+ * as query parameters. Since the browser WebSocket API does not support custom
+ * request headers, this allows the host server's auth middleware to validate
+ * the connection during the HTTP upgrade handshake.
+ *
+ * All configured headers are forwarded as query parameters prefixed with
+ * `_header_` to avoid collisions with application-level query params.
+ *
+ * Accepts both static header maps and dynamic provider functions.
+ *
+ * **Security note:** Query parameters are visible in browser history, server
+ * access logs, proxy/CDN logs, and the `Referer` header. Tokens placed in the
+ * URL are therefore more exposed than those sent via HTTP headers. This is an
+ * inherent limitation of the browser WebSocket API (no custom headers).
+ * Server-side middleware that reads `_header_*` params should strip them from
+ * logs and avoid forwarding them in redirects.
+ *
+ * @param wsUrl  The base WebSocket URL (may already contain query parameters)
+ * @param headers  The headers provider from CliServerConfig (may include Authorization, etc.)
+ * @returns The WebSocket URL with auth credentials appended as query parameters
+ */
+declare function buildAuthenticatedWebSocketUrl(wsUrl: string, headers?: CliHeadersProvider): string;
+
 /**
  * Derives CLI panel CSS custom property values from an xterm ITheme object.
  * Used when `syncTheme` is enabled on the panel config.
@@ -2623,10 +2902,11 @@ declare function nextPanelPosition(current: CliPanelPosition): CliPanelPosition;
  */
 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.
+ * Return the visible (display) width of a string in terminal columns,
+ * ignoring ANSI escape codes and accounting for wide characters (emoji,
+ * East Asian fullwidth, etc.) that occupy two columns.
  * @param text The text potentially containing ANSI codes
- * @returns The number of visible characters
+ * @returns The number of terminal columns the text occupies
  */
 declare function visibleLength(text: string): number;
 
@@ -2782,7 +3062,7 @@ interface CliThemeInfo {
 
 declare const DefaultThemeInfos: Record<string, CliThemeInfo>;
 
-declare const LIBRARY_VERSION = "2.0.0-beta.11";
+declare const LIBRARY_VERSION = "2.0.0-beta.13";
 declare const API_VERSION = 2;
 
 /**
@@ -2843,4 +3123,4 @@ declare class BrowserFileTransferService implements ICliFileTransferService {
     private _pickFile;
 }
 
-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, type CliFullScreenOptions, CliIcon, type CliLineOptions, CliLogLevel, CliModuleRegistry, type CliMultiSelectOption, type CliMultiSelectOptions, type CliNumberOptions, type CliOptions, type CliPackageSource, type CliPanelConfig, type CliPanelHideAlignment, type CliPanelPaneState, type CliPanelPosition, type CliPanelState, type CliPanelTabState, 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 CliTableOptions, 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 DefaultThemesType, 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 ICliPanelRef, 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 };
+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, type CliFullScreenOptions, type CliHeadersProvider, type CliHttpRequestOptions, CliIcon, type CliLineOptions, CliLogLevel, CliModuleRegistry, type CliMultiSelectOption, type CliMultiSelectOptions, type CliNotification, type CliNotificationLevel, type CliNumberOptions, type CliOptions, type CliPackageSource, type CliPanelConfig, type CliPanelHideAlignment, type CliPanelPaneState, type CliPanelPosition, type CliPanelState, type CliPanelTabState, 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 CliTableOptions, 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 DefaultThemesType, 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 ICliHttpClient, ICliHttpClient_TOKEN, type ICliInputReader, type ICliKeyValueStore, type ICliLogger, type ICliManagedInterval, type ICliManagedTimer, type ICliModule, type ICliNotifier, type ICliOwnership, type ICliPanelRef, type ICliPercentageProgressBar, type ICliPermissionService, ICliPermissionService_TOKEN, type ICliPingServerService, type ICliProcessEntry, type ICliProcessRegisterOptions, type ICliProcessRegistry, type ICliProcessorHook, type ICliProgressBar, type ICliServerAuthService, ICliServerAuthService_TOKEN, type ICliServerAuthTokenProvider, ICliServerAuthTokenProvider_TOKEN, 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, buildAuthenticatedWebSocketUrl, clearTerminalLine, colorFirstWord, colorizeJson, compareVersions, constants, createWorkerService, delay, derivePanelThemeStyles, enums, formatJson, getConfigValue, getParameterValue, getPluginConfigValue, getRightOfWord, highlightTextWithBg, initializeBrowserEnvironment, loadPanelPosition, nextPanelPosition, resolveConfigurationCategories, resolveHeaders, resolveServerHeaders, satisfiesMinVersion, satisfiesVersionRange, savePanelPosition, stripAnsi, toQueryString, utils, visibleLength };