@qodalis/cli-core 2.0.0-beta.12 → 2.0.0-beta.14

package/public-api.d.ts

@@ -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,37 +633,88 @@ declare const ICliPermissionService_TOKEN = "cli-permission-service";
  * Token for the file picker provider.
  */
 declare const ICliFilePickerProvider_TOKEN = "cli-file-picker-provider";
-
 /**
- * Options for readFile file picker.
+ * Token for the HTTP client service.
  */
-interface CliFilePickerOptions {
-    /** Allow selecting multiple files. Default: false. */
-    multiple?: boolean;
-    /**
-     * File type filter. Accepts MIME types (e.g. 'image/*') or extensions
-     * (e.g. '.json,.txt'). Maps to the HTML accept attribute in browsers
-     * and file filter in Electron.
-     */
-    accept?: string;
-    /**
-     * When true, pick a directory instead of files. Default: false.
-     * Cannot be combined with `multiple` — if both are set, `directory` takes precedence
-     * and a single directory is returned.
-     */
-    directory?: boolean;
-    /**
-     * How to read file content. Default: 'text'.
-     * - 'text': Read as UTF-8 string (suitable for text files)
-     * - 'arraybuffer': Read as ArrayBuffer (suitable for binary files like images)
-     */
-    readAs?: 'text' | 'arraybuffer';
-}
+declare const ICliHttpClient_TOKEN = "cli-http-client";
 /**
- * Result returned by readFile for each selected file.
+ * Token for the user event service (lifecycle events).
  */
-interface CliFileResult {
-    /** File name without path (e.g. 'config.json') */
+declare const ICliUserEventService_TOKEN = "cli-user-event-service";
+/**
+ * Token for the audit service (persistent event logging).
+ */
+declare const ICliAuditService_TOKEN = "cli-audit-service";
+/**
+ * Token for the authorization service ({@link ICliAuthorizationService}).
+ * Provided by an auth module (e.g. `@qodalis/cli-users`); absent otherwise.
+ */
+declare const ICliAuthorizationService_TOKEN = "cli-authorization-service";
+/**
+ * Token for the permission registry ({@link ICliPermissionRegistry}).
+ * Always provided by the CLI engine.
+ */
+declare const ICliPermissionRegistry_TOKEN = "cli-permission-registry";
+/**
+ * Token for the sessions service ({@link ICliSessionsService}).
+ */
+declare const ICliSessionsService_TOKEN = "cli-sessions-service";
+/**
+ * Token for the persistent key-value store used by modules (setup state, etc.).
+ */
+declare const ICliKeyValueStore_TOKEN = "cli-key-value-store";
+
+/**
+ * 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.
+ */
+interface CliFilePickerOptions {
+    /** Allow selecting multiple files. Default: false. */
+    multiple?: boolean;
+    /**
+     * File type filter. Accepts MIME types (e.g. 'image/*') or extensions
+     * (e.g. '.json,.txt'). Maps to the HTML accept attribute in browsers
+     * and file filter in Electron.
+     */
+    accept?: string;
+    /**
+     * When true, pick a directory instead of files. Default: false.
+     * Cannot be combined with `multiple` — if both are set, `directory` takes precedence
+     * and a single directory is returned.
+     */
+    directory?: boolean;
+    /**
+     * How to read file content. Default: 'text'.
+     * - 'text': Read as UTF-8 string (suitable for text files)
+     * - 'arraybuffer': Read as ArrayBuffer (suitable for binary files like images)
+     */
+    readAs?: 'text' | 'arraybuffer';
+}
+/**
+ * Result returned by readFile for each selected file.
+ */
+interface CliFileResult {
+    /** File name without path (e.g. 'config.json') */
     name: string;
     /** Full file path. Available in Electron, undefined in browser. */
     path?: string;
@@ -989,69 +909,523 @@ 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.
- * - `'job'` — Run-to-completion task whose `onStart` resolves when the work is done.
- *   Automatically transitions to `'done'` status on success. Cannot be restarted.
+ * Context passed to completion providers describing the current input state.
  */
-type CliBackgroundServiceType = 'daemon' | 'job';
+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[];
+}
 /**
- * Lifecycle status of a background service.
+ * Provides tab-completion candidates for CLI input.
+ * Plugins can register providers to extend completion (e.g. file paths, custom values).
  */
-type CliBackgroundServiceStatus = 'pending' | 'running' | 'stopped' | 'failed' | 'done';
+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;
+}
 /**
- * Where the service code is executing.
+ * Represents a spinner for the CLI
  */
-type CliServiceExecutionMode = 'main-thread' | 'worker';
+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';
+};
 /**
- * An event emitted by a background service.
- * Services control terminal notification visibility by setting `data.notify: true`.
+ * Represents a progress bar for the CLI
  */
-interface ICliServiceEvent {
-    /** Name of the service that emitted this event */
-    source: string;
-    /** Event type — services define their own, registry emits lifecycle events */
-    type: string;
-    /** Arbitrary payload */
-    data?: unknown;
-    /** Set automatically by the registry */
-    timestamp?: Date;
+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>;
 }
+
 /**
- * Handler function for service events.
- */
-type CliServiceEventHandler = (event: ICliServiceEvent) => void;
+ * Result of a guard check.
+ *
+ * - `true` or `undefined`: allow the command.
+ * - `false`: block it with the generic message `<command>: permission denied`.
+ * - a non-empty `string`: block it and print this message.
+ * - `{ allowed, message }`: explicit form; `message` is used when `allowed` is false.
+ */
+type CliCommandGuardResult = boolean | string | void | {
+    allowed: boolean;
+    message?: string;
+};
 /**
- * Log severity level for background service messages.
- * Shared by `ICliServiceLogEntry`, `ICliServiceContext.log()`,
- * and `WorkerServiceContext.log()`.
+ * A global command guard: a check that runs before **every** command, across
+ * all processors and modules, and can block it.
+ *
+ * Use guards for cross-cutting policies such as authentication, permission
+ * checks, feature flags, maintenance windows or rate limiting, instead of
+ * repeating the check inside each processor.
+ *
+ * ## When guards run
+ *
+ * For each command the executor:
+ * 1. parses the input and resolves the processor (and sub-processor);
+ * 2. handles global parameters such as `--help` (help is never guarded);
+ * 3. extracts the positional value into `command.value`;
+ * 4. **runs the guards**;
+ * 5. validates required values/parameters, runs processor hooks and finally
+ *    calls `processCommand`.
+ *
+ * Guards run in ascending `priority` (default `0`). For each guard the executor
+ * calls `appliesTo` (if defined) and skips the guard when it returns `false`;
+ * otherwise it awaits `canActivate`. The **first** guard that blocks stops the
+ * chain: its message is written as an error and the command exits with code
+ * `-1`. A guard that throws (in `appliesTo` or `canActivate`) also blocks the
+ * command, so a broken guard fails closed.
+ *
+ * ## Access to the context
+ *
+ * Both `appliesTo` and `canActivate` receive the {@link ICliExecutionContext}
+ * of the command about to run, so a guard can:
+ * - resolve services with `context.services.get(...)` / `getRequired(...)`
+ *   (e.g. a policy, feature-flag or permission service registered by any
+ *   module) to decide **what** should be guarded and **whether** it may run;
+ * - inspect `context.userSession` for the signed-in user and their groups;
+ * - read the processor's `metadata` (for example `requireAuth` or
+ *   `requiredGroups`) and the parsed `command` (`command.value`, `command.args`);
+ * - prompt the user via `context.reader` (e.g. a confirmation guard).
+ *
+ * Guards should not write to the terminal to report a denial; return a message
+ * instead so the executor prints it consistently.
+ *
+ * ## Registering guards
+ *
+ * The preferred way is the module's `guards` array; the boot sequence
+ * registers each entry as a multi-provider under {@link ICliCommandGuard_TOKEN}.
+ * Several modules can contribute guards; all of them run.
+ *
+ * ```ts
+ * const billingModule: ICliModule = {
+ *     apiVersion: 2,
+ *     name: 'billing',
+ *     processors: [new InvoiceProcessor()],
+ *     guards: [billingGuard],
+ * };
+ * ```
+ *
+ * Guards can also be added at runtime (e.g. from `onInit`):
+ *
+ * ```ts
+ * context.services.set({ provide: ICliCommandGuard_TOKEN, useValue: myGuard, multi: true });
+ * ```
+ *
+ * ## Example: policy resolved from a service
+ *
+ * ```ts
+ * const featureFlagGuard: ICliCommandGuard = {
+ *     name: 'feature-flags',
+ *     // Only guard commands that are behind a flag; the flag list comes from a service
+ *     appliesTo: (processor, _command, context) =>
+ *         context.services.get<FeatureFlags>(FeatureFlags_TOKEN)?.isFlagged(processor.command) ?? false,
+ *     canActivate: async (_command, processor, context) => {
+ *         const flags = context.services.getRequired<FeatureFlags>(FeatureFlags_TOKEN);
+ *         return (await flags.isEnabled(processor.command, context.userSession?.user))
+ *             ? true
+ *             : `${processor.command}: not available for your account`;
+ *     },
+ * };
+ * ```
+ *
+ * ## Without a guard-providing module
+ *
+ * Guards are opt-in. When no guard is registered every command runs as before.
+ * The engine registers three built-in guards that enforce the processor access
+ * metadata (`requireAuth`, `requiredGroups`, `requiredPermissions`); they stay
+ * inactive until an auth module (e.g. `@qodalis/cli-users`) registers an
+ * `ICliAuthorizationService`, so without one that metadata is informational.
+ */
+interface ICliCommandGuard {
+    /** Unique name, shown in diagnostics when the guard throws. */
+    name: string;
+    /** Execution order; lower runs first. Defaults to `0`. */
+    priority?: number;
+    /**
+     * Optional filter deciding whether this guard is relevant for the command.
+     * Return `false` to skip the guard. When omitted the guard applies to
+     * every command. May be async, and may use `context` to resolve services.
+     */
+    appliesTo?(processor: ICliCommandProcessor, command: CliProcessCommand, context: ICliExecutionContext): boolean | Promise<boolean>;
+    /**
+     * Decide whether the command may run. See {@link CliCommandGuardResult}
+     * for the accepted return values.
+     */
+    canActivate(command: CliProcessCommand, processor: ICliCommandProcessor, context: ICliExecutionContext): CliCommandGuardResult | Promise<CliCommandGuardResult>;
+}
+/** DI token for {@link ICliCommandGuard}; register guards as multi-providers. */
+declare const ICliCommandGuard_TOKEN = "cli-command-guard";
+
+/**
+ * A permission an extension uses, declared so tools (`perms --list`,
+ * `groupmod --grant` completion, docs) can show it. Declaring is optional:
+ * any `resource:action` string can be granted and checked.
  */
-type CliServiceLogLevel = 'info' | 'warn' | 'error';
+interface CliPermissionDefinition {
+    /** Permission string, `resource:action` (e.g. `files:chown`). */
+    name: string;
+    /** Human readable description. */
+    description?: string;
+    /** Module that declared it (filled in at registration). */
+    module?: string;
+}
+/** Registry of permissions declared by modules (`ICliModule.permissions`). */
+interface ICliPermissionRegistry {
+    register(definitions: CliPermissionDefinition[], module?: string): void;
+    list(): CliPermissionDefinition[];
+    get(name: string): CliPermissionDefinition | undefined;
+}
+/** The identity checks are made against. */
+interface ICliPrincipal {
+    /** User id */
+    id: string;
+    /** Login name (used as file owner) */
+    name: string;
+    /** Group (role) names */
+    groups: string[];
+    /** Effective permissions (union of the groups' permissions) */
+    permissions: string[];
+}
+/** rwx-style protected resource (files, directories, or anything an extension owns). */
+interface ICliProtectedResource {
+    ownership?: ICliOwnership;
+    /** 9-char mode string, e.g. `rwxr-x---` */
+    permissions?: string;
+}
+type CliAccessAction = 'read' | 'write' | 'execute';
 /**
- * A single log entry from a background service.
+ * Authorization service. Provided by an auth module (the users module provides
+ * one in local and in server mode). Extensions should use the helpers
+ * {@link cliAuthorize} / {@link cliCanAccess}, which allow everything when no
+ * authorization service is registered.
  */
-interface ICliServiceLogEntry {
-    timestamp: Date;
-    level: CliServiceLogLevel;
-    message: string;
+interface ICliAuthorizationService {
+    /** The signed-in principal, or undefined when nobody is signed in. */
+    getPrincipal(): ICliPrincipal | undefined;
+    /** Does the current principal hold `permission` (wildcards honoured)? */
+    can(permission: string): boolean;
+    /**
+     * rwx check on a resource for the current principal (owner / group / other).
+     * Principals holding `*` or any of `bypassPermissions` are always allowed.
+     * Resources without a mode or ownership are allowed.
+     */
+    canAccess(resource: ICliProtectedResource, action: CliAccessAction, bypassPermissions?: string[]): boolean;
 }
+/** Thrown when an operation is not permitted. The message is user facing. */
+declare class CliAccessDeniedError extends Error {
+    readonly code = "EACCES";
+    constructor(message?: string);
+}
+/** True for {@link CliAccessDeniedError} (also across bundle copies). */
+declare function isCliAccessDeniedError(error: unknown): error is CliAccessDeniedError;
 /**
- * Per-service runtime context.
- * Each background service receives its own context with an independent abort signal
- * and scoped timers (not shared with the full-screen timer set).
+ * Check a permission for the current principal. Returns `true` when no
+ * authorization service is registered (no auth module loaded).
  */
-interface ICliServiceContext {
-    /** AbortSignal scoped to this service — independent of Ctrl+C */
-    signal: AbortSignal;
-    /** Emit an event from this service */
-    emit(event: ICliServiceEvent): void;
-    /** Log a message to this service's private log buffer */
-    log(message: string, level?: CliServiceLogLevel): void;
-    /** Create an interval scoped to this service (auto-cleared on stop) */
-    createInterval(callback: () => void, ms: number): ICliManagedInterval;
-    /** Create a timeout scoped to this service (auto-cleared on stop) */
+declare function cliAuthorize(context: Pick<ICliExecutionContext, 'services'>, permission: string): boolean;
+/**
+ * rwx check for the current principal. Returns `true` when no authorization
+ * service is registered.
+ */
+declare function cliCanAccess(context: Pick<ICliExecutionContext, 'services'>, resource: ICliProtectedResource, action: CliAccessAction, bypassPermissions?: string[]): boolean;
+/**
+ * Reference rwx evaluation shared by implementations of
+ * {@link ICliAuthorizationService.canAccess}.
+ */
+declare function cliEvaluateAccess(principal: ICliPrincipal | undefined, resource: ICliProtectedResource, action: CliAccessAction, bypassPermissions?: string[]): boolean;
+
+/** A sign-in session as listed by {@link ICliSessionsService}. Never carries a token. */
+interface ICliSessionInfo {
+    id: string;
+    userId: string;
+    userName: string;
+    createdAt: number;
+    lastActivity: number;
+    /** When the session expires if idle; undefined when there is no timeout */
+    expiresAt?: number;
+    /** True for the caller's own session */
+    current?: boolean;
+    metadata?: {
+        userAgent?: string;
+        remoteAddress?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Lists and revokes sign-in sessions. Implemented locally (sessions of this
+ * browser) and by servers (all sessions). Used by `sessions` / `session-kick`.
+ */
+interface ICliSessionsService {
+    /** All sessions visible to the caller */
+    list(): Promise<ICliSessionInfo[]>;
+    /** Revoke a session by id */
+    revoke(sessionId: string, reason?: string): Promise<void>;
+    /** Revoke every session of a user (optionally keeping one) */
+    revokeUser(userId: string, options?: {
+        exceptSessionId?: string;
+        reason?: string;
+    }): 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 (role), optionally with permissions */
+    createGroup(name: string, description?: string, permissions?: string[]): Promise<ICliGroup>;
+    /** Updates a group's description and/or permissions (by id or name) */
+    updateGroup(id: string, updates: {
+        description?: string;
+        permissions?: string[];
+    }): Promise<ICliGroup>;
+    /** Adds a user (id or name) to a group (id or name) */
+    addMember(groupId: string, userId: string): Promise<void>;
+    /** Removes a user (id or name) from a group (id or name) */
+    removeMember(groupId: string, userId: string): Promise<void>;
+    /** 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. `password` may be omitted
+     * only when the implementation allows passwordless sign-in.
+     */
+    login(username: string, password?: string): Promise<ICliUserSession>;
+    /** Ends the current session (the CLI is left signed out) */
+    logout(): Promise<void>;
+    /**
+     * Switch to another user (`su`). Requires the target's password unless
+     * the caller may skip it (implementation-defined, e.g. `users:update`).
+     * Goes through the same lockout, events and audit as `login`.
+     */
+    switchUser?(username: string, password?: string): Promise<ICliUserSession>;
+    /**
+     * Sets or updates a user's password.
+     * @param currentPassword The user's current password, when changing one's own
+     * password. Server-backed implementations forward it so the server can
+     * re-check it; local implementations may ignore it.
+     */
+    setPassword(userId: string, password: string, currentPassword?: 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>;
+    /** Validate password against policy. Returns error message or null if valid. */
+    validatePassword?(password: string): string | null;
+}
+
+/**
+ * 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.
+ */
+type CliBackgroundServiceType = 'daemon' | 'job';
+/**
+ * Lifecycle status of a background service.
+ */
+type CliBackgroundServiceStatus = 'pending' | 'running' | 'stopped' | 'failed' | 'done';
+/**
+ * Where the service code is executing.
+ */
+type CliServiceExecutionMode = 'main-thread' | 'worker';
+/**
+ * An event emitted by a background service.
+ * Services control terminal notification visibility by setting `data.notify: true`.
+ */
+interface ICliServiceEvent {
+    /** Name of the service that emitted this event */
+    source: string;
+    /** Event type — services define their own, registry emits lifecycle events */
+    type: string;
+    /** Arbitrary payload */
+    data?: unknown;
+    /** Set automatically by the registry */
+    timestamp?: Date;
+}
+/**
+ * Handler function for service events.
+ */
+type CliServiceEventHandler = (event: ICliServiceEvent) => void;
+/**
+ * Log severity level for background service messages.
+ * Shared by `ICliServiceLogEntry`, `ICliServiceContext.log()`,
+ * and `WorkerServiceContext.log()`.
+ */
+type CliServiceLogLevel = 'info' | 'warn' | 'error';
+/**
+ * A single log entry from a background service.
+ */
+interface ICliServiceLogEntry {
+    timestamp: Date;
+    level: CliServiceLogLevel;
+    message: string;
+}
+/**
+ * Per-service runtime context.
+ * Each background service receives its own context with an independent abort signal
+ * and scoped timers (not shared with the full-screen timer set).
+ */
+interface ICliServiceContext {
+    /** AbortSignal scoped to this service — independent of Ctrl+C */
+    signal: AbortSignal;
+    /** Emit an event from this service */
+    emit(event: ICliServiceEvent): void;
+    /** Log a message to this service's private log buffer */
+    log(message: string, level?: CliServiceLogLevel): void;
+    /** Create an interval scoped to this service (auto-cleared on stop) */
+    createInterval(callback: () => void, ms: number): ICliManagedInterval;
+    /** Create a timeout scoped to this service (auto-cleared on stop) */
     createTimeout(callback: () => void, ms: number): ICliManagedTimer;
     /** Access the shared state store */
     state: ICliStateStore;
@@ -1077,49 +1451,637 @@ interface ICliBackgroundService {
     /** Called for graceful shutdown */
     onStop?(context: ICliServiceContext): Promise<void>;
     /**
-     * Called when the service throws an unrecoverable error.
-     * Use this hook for logging or cleanup; throwing from `onError` itself
-     * is safe — the registry catches it and marks the service as failed.
+     * Called when the service throws an unrecoverable error.
+     * Use this hook for logging or cleanup; throwing from `onError` itself
+     * is safe — the registry catches it and marks the service as failed.
+     */
+    onError?(error: Error, context: ICliServiceContext): void;
+}
+/**
+ * Read-only snapshot of a background service's current state.
+ */
+interface ICliBackgroundServiceInfo {
+    /** Process ID assigned by the process registry */
+    pid?: number;
+    name: string;
+    description?: string;
+    type: CliBackgroundServiceType;
+    status: CliBackgroundServiceStatus;
+    executionMode: CliServiceExecutionMode;
+    startedAt?: Date;
+    stoppedAt?: Date;
+    error?: string;
+    /** Uptime in milliseconds (only when running) */
+    uptime?: number;
+}
+/**
+ * Registry that manages background service lifecycle.
+ * Exposed on `ICliExecutionContext.backgroundServices`.
+ */
+interface ICliBackgroundServiceRegistry {
+    register(service: ICliBackgroundService): void;
+    start(name: string): Promise<void>;
+    stop(name: string): Promise<void>;
+    restart(name: string): Promise<void>;
+    startJob(name: string, task: (context: ICliServiceContext) => Promise<void>, options?: {
+        workerCompatible?: boolean;
+    }): Promise<void>;
+    getStatus(name: string): ICliBackgroundServiceInfo | undefined;
+    list(): ICliBackgroundServiceInfo[];
+    getLogs(name: string, limit?: number): ICliServiceLogEntry[];
+    on(handler: CliServiceEventHandler, filter?: {
+        source?: string;
+        type?: string;
+    }): () => void;
+    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 command requires a signed-in user. Enforced by a
+     * core guard that activates when an auth module registers an
+     * `ICliAuthorizationService` (e.g. `@qodalis/cli-users`); without one the
+     * flag is informational.
+     */
+    requireAuth?: boolean;
+    /**
+     * The signed-in user must belong to at least one of these groups
+     * (e.g. `['admin']`). Implies `requireAuth`. Enforced like `requireAuth`.
+     */
+    requiredGroups?: string[];
+    /**
+     * The signed-in user must hold **all** of these permissions
+     * (e.g. `['users:create']`), granted through their groups (roles).
+     * Implies `requireAuth`. Enforced like `requireAuth`.
+     */
+    requiredPermissions?: 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.
      */
-    onError?(error: Error, context: ICliServiceContext): void;
+    timeout?: number;
 }
 /**
- * Read-only snapshot of a background service's current state.
+ * 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 ICliBackgroundServiceInfo {
-    /** Process ID assigned by the process registry */
-    pid?: number;
-    name: string;
-    description?: string;
-    type: CliBackgroundServiceType;
-    status: CliBackgroundServiceStatus;
-    executionMode: CliServiceExecutionMode;
-    startedAt?: Date;
-    stoppedAt?: Date;
-    error?: string;
-    /** Uptime in milliseconds (only when running) */
-    uptime?: number;
+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>;
 }
 /**
- * Registry that manages background service lifecycle.
- * Exposed on `ICliExecutionContext.backgroundServices`.
+ * Error thrown by `ICliHttpClient` JSON helpers (`get`, `post`, `put`,
+ * `patch`, `delete`, `options`) when the server responds with a non-2xx status.
+ *
+ * Exposes the HTTP status so callers can react to specific responses
+ * (for example, clearing a stored session token on `401`).
+ *
+ * @example
+ * ```ts
+ * try {
+ *     await context.http.get(url);
+ * } catch (e) {
+ *     if (e instanceof CliHttpError && e.status === 401) {
+ *         // token expired or revoked
+ *     }
+ * }
+ * ```
  */
-interface ICliBackgroundServiceRegistry {
-    register(service: ICliBackgroundService): void;
-    start(name: string): Promise<void>;
-    stop(name: string): Promise<void>;
-    restart(name: string): Promise<void>;
-    startJob(name: string, task: (context: ICliServiceContext) => Promise<void>, options?: {
-        workerCompatible?: boolean;
-    }): Promise<void>;
-    getStatus(name: string): ICliBackgroundServiceInfo | undefined;
-    list(): ICliBackgroundServiceInfo[];
-    getLogs(name: string, limit?: number): ICliServiceLogEntry[];
-    on(handler: CliServiceEventHandler, filter?: {
-        source?: string;
-        type?: string;
-    }): () => void;
-    destroyAll(): Promise<void>;
+declare class CliHttpError extends Error {
+    /** HTTP status code of the failed response */
+    readonly status: number;
+    /** HTTP status text of the failed response */
+    readonly statusText: string;
+    /** Parsed JSON error body, when the server returned one */
+    readonly body?: unknown | undefined;
+    constructor(message: string, 
+    /** HTTP status code of the failed response */
+    status: number, 
+    /** HTTP status text of the failed response */
+    statusText?: string, 
+    /** Parsed JSON error body, when the server returned one */
+    body?: unknown | undefined);
+}
+
+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>;
+}
+
+/** Represents a user lifecycle event */
+interface ICliUserEvent {
+    /** The type of event that occurred */
+    type: 'login' | 'logout' | 'login_failed' | 'user_created' | 'user_deleted' | 'user_updated' | 'password_changed' | 'user_switched' | 'user_disabled' | 'user_enabled' | 'group_created' | 'group_updated' | 'group_deleted' | 'group_member_added' | 'group_member_removed' | 'session_revoked' | 'audit_cleared';
+    /** The user involved in the event (for group events: the acting user) */
+    user: ICliUser;
+    /** The acting user's name, when different from `user` (e.g. an admin) */
+    actor?: string;
+    /** When the event occurred */
+    timestamp: number;
+    /** Optional additional details */
+    details?: string;
+    /** `user_updated`: the user's name before a rename (set only when the name changed) */
+    previousName?: string;
+}
+/** Service that emits user lifecycle events for plugins to subscribe to */
+interface ICliUserEventService {
+    /** Observable stream of user events */
+    readonly events$: Observable<ICliUserEvent>;
+    /** Emit a user event */
+    emit(event: ICliUserEvent): void;
+}
+
+/** A single audit log entry */
+interface ICliAuditEntry {
+    /** Entry id (server-assigned in server mode) */
+    id?: string;
+    /** When the event occurred */
+    timestamp: number;
+    /** Event type (e.g., 'login', 'logout', 'login_failed') */
+    event: string;
+    /** Username involved */
+    username: string;
+    /** Optional additional details */
+    details?: string;
+    /** Id of the user the entry is about, when known */
+    userId?: string;
+    /** The user who performed the action, when different from `username` */
+    actor?: string;
+    /** Id of the acting user, when different from the subject */
+    actorId?: string;
+    /** Extra data (e.g. remote address) */
+    metadata?: Record<string, unknown>;
+}
+/** Service for persistent audit logging */
+interface ICliAuditService {
+    /** Log an audit entry (timestamp is added automatically) */
+    log(entry: Omit<ICliAuditEntry, 'timestamp'>): Promise<void>;
+    /** Retrieve audit entries with optional filtering */
+    getEntries(options?: {
+        limit?: number;
+        event?: string;
+        username?: string;
+    }): Promise<ICliAuditEntry[]>;
+    /** Clear all audit entries */
+    clear(): Promise<void>;
 }
 
 /**
@@ -1221,19 +2183,20 @@ interface ICliExecutionContext {
      */
     submitCommand(command: string): Promise<void>;
     /**
-     * Set a custom status text displayed in the panel header bar.
-     * Use to show progress or state (e.g. "Downloading 45%...", "Connected to server").
+     * 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();
+     * ```
      */
-    setStatusText(text: string): void;
-    /**
-     * Clear the custom status text from the panel header bar.
-     */
-    clearStatusText(): void;
-    /**
-     * Get the current custom status text, if any.
-     */
-    getStatusText(): string | undefined;
+    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
@@ -1337,6 +2300,16 @@ interface ICliExecutionContext {
      * are scoped to this session and destroyed when the engine shuts down.
      */
     backgroundServices: ICliBackgroundServiceRegistry;
+    /**
+     * 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');
+     * ```
+     */
+    http: ICliHttpClient;
 }
 
 interface ICliProcessorHook {
@@ -1344,512 +2317,255 @@ interface ICliProcessorHook {
     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[];
+interface ICliCommandAuthor {
     /**
-     * Parameters that the command accepts
+     * The name of the author
      */
-    parameters?: ICliCommandParameterDescriptor[];
+    name: string;
     /**
-     * Hooks that are executed before and after the command is processed
+     * The email of the author
      */
-    hooks?: ICliProcessorHook[];
+    email: string;
+}
+/**
+ * Represents a command parameter
+ */
+interface ICliCommandParameterDescriptor {
     /**
-     * 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
+     * The name of the parameter
      */
-    stateConfiguration?: CliStateConfiguration;
+    name: string;
     /**
-     * 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.
+     * Aliases for the parameter
      */
-    configurationOptions?: ICliConfigurationOption[];
+    aliases?: string[];
     /**
-     * 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.
+     * A description of the parameter
      */
-    extendsProcessor?: boolean;
+    description: string;
     /**
-     * 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.
+     * If true, the parameter is required
      */
-    originalProcessor?: ICliCommandProcessor;
+    required: boolean;
     /**
-     * Process the command
-     * @param command The command to process
-     * @param context The context in which the command is executed
+     * The type of the parameter
      */
-    processCommand(command: CliProcessCommand, context: ICliExecutionContext): Promise<void>;
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object' | string;
     /**
-     * Write the description of the command
-     * @param context The context in which the command is executed
+     * The default value of the parameter
      */
-    writeDescription?(context: ICliExecutionContext): void;
+    defaultValue?: any;
     /**
-     * A function that validates the command before execution
+     * 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
      */
-    validateBeforeExecution?: (command: CliProcessCommand, context: ICliExecutionContext) => {
+    validator?: (value: any) => {
+        /**
+         * Indicates if the value is valid
+         */
         valid: boolean;
+        /**
+         * An optional message to display if the value is not valid
+         */
         message?: string;
     };
-    /**
-     * Initialize the command processor
-     * @param context The context in which the command is executed
-     */
-    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
+ * Represents a configuration option that a command processor exposes
+ * for management via the `configure` command.
  */
-interface ICliCommandChildProcessor extends ICliCommandProcessor {
+interface ICliConfigurationOption {
     /**
-     * The parent processor, it is populated by the processor manager
+     * The key used to store and retrieve this option, e.g. 'maxItems'
      */
-    parent?: ICliCommandProcessor;
-}
-
-/**
- * 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).
- */
-interface ICliGlobalParameterHandler {
+    key: string;
     /**
-     * The parameter descriptor shown in help output and used for tab-completion.
+     * Human-readable label shown in the interactive menu
      */
-    parameter: ICliCommandParameterDescriptor;
+    label: string;
     /**
-     * Execution priority — lower values run first.
-     * @default 0
+     * Description of what this option controls
      */
-    priority?: number;
+    description: string;
     /**
-     * Evaluate and optionally handle the parameter.
-     * @returns `true` to halt command execution, `false` to continue.
+     * The data type of the option
      */
-    handle(args: Record<string, any>, processor: ICliCommandProcessor, command: CliProcessCommand, context: ICliExecutionContext): boolean | Promise<boolean>;
-}
-
-/**
- * Represents a service that executes commands
- */
-interface ICliCommandExecutorService {
+    type: 'string' | 'number' | 'boolean' | 'select';
     /**
-     * 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
+     * The default value when no configuration has been set
      */
-    showHelp(command: CliProcessCommand, context: ICliExecutionContext): Promise<void>;
+    defaultValue: any;
     /**
-     * Execute a command
-     * @param command The command to execute
-     * @param context The context in which the command is executed
+     * Available choices for 'select' type options
      */
-    executeCommand(command: string, context: ICliExecutionContext): Promise<void>;
+    options?: {
+        label: string;
+        value: any;
+    }[];
     /**
-     * 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
+     * Optional validator function
      */
-    registerGlobalParameter(handler: ICliGlobalParameterHandler): void;
+    validator?: (value: any) => {
+        valid: boolean;
+        message?: string;
+    };
     /**
-     * Returns the descriptors of all registered global parameters.
-     * Used by help output and tab-completion.
+     * Override the category grouping (defaults to the processor command name)
      */
-    getGlobalParameters(): ICliCommandParameterDescriptor[];
+    category?: string;
 }
-
 /**
- * Represents a registry for command processors
+ * Represents a command processor
  */
-interface ICliCommandProcessorRegistry {
-    /**
-     * The processors registered with the registry
-     */
-    readonly processors: ICliCommandProcessor[];
-    /**
-     * Find a processor for a command
-     * @param mainCommand
-     * @param chainCommands
-     */
-    findProcessor(mainCommand: string, chainCommands: string[]): ICliCommandProcessor | undefined;
+interface ICliCommandProcessor {
     /**
-     * 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.
+     * The command that this processor handles
      */
-    findProcessorInCollection(mainCommand: string, chainCommands: string[], processors: ICliCommandProcessor[]): ICliCommandProcessor | undefined;
+    command: string;
     /**
-     * Get the root processor for a child processor
-     * @param child The child processor
+     * Alternative names for the command
      */
-    getRootProcessor(child: ICliCommandChildProcessor): ICliCommandProcessor;
+    aliases?: string[];
     /**
-     * Register a processor
-     * @param processor
+     * A description of the command
      */
-    registerProcessor(processor: ICliCommandProcessor): void;
+    description?: string;
     /**
-     * Unregister a processor
-     * @param processor
+     * The author of the command
      */
-    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;
-    };
-    /** 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;
-}
-
-interface ICliExecutionProcess {
+    author?: ICliCommandAuthor;
     /**
-     * Indicates if the process has exited
+     * 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.
      */
-    exited?: boolean;
+    acceptsRawInput?: boolean;
     /**
-     * The exit code of the process
+     * 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
      */
-    exitCode?: number;
+    valueRequired?: boolean;
     /**
-     * Indicates if the process is running
+     * The version of the command processor
+     * @default '1.0.0'
      */
-    running: boolean;
+    version?: string;
     /**
-     * The data of the process
+     * The metadata for the command processor
      */
-    data: any | undefined;
+    metadata?: CliProcessorMetadata;
     /**
-     * Exit the process
-     * @param code The exit code
-     * @returns void
+     * Processors that are nested under this processor
      */
-    exit: (
+    processors?: ICliCommandChildProcessor[];
     /**
-     * The exit code
+     * Parameters that the command accepts
      */
-    code?: number, 
+    parameters?: ICliCommandParameterDescriptor[];
     /**
-     * Options for exiting the process
+     * Hooks that are executed before and after the command is processed
      */
-    options?: {
-        /**
-         * Indicates if the exit should be silent, i.e. not throw an error
-         */
-        silent?: boolean;
-    }) => void;
+    hooks?: ICliProcessorHook[];
     /**
-     * Output data from the process
-     * @param data The data to output
+     * 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
      */
-    output(data: any): void;
-}
-
-/**
- * Represents a key-value store for the CLI
- */
-interface ICliKeyValueStore {
+    stateConfiguration?: CliStateConfiguration;
     /**
-     * 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.
+     * 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.
      */
-    get<T = any>(key: string): Promise<T | undefined>;
+    configurationOptions?: ICliConfigurationOption[];
     /**
-     * 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.
+     * 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.
      */
-    set(key: string, value: any): Promise<void>;
+    extendsProcessor?: boolean;
     /**
-     * Removes a key-value pair by key.
-     * @param key - The key to remove.
-     * @returns A promise resolving when the key is removed.
+     * 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.
      */
-    remove(key: string): Promise<void>;
+    originalProcessor?: ICliCommandProcessor;
     /**
-     * Clears all key-value pairs from the store.
-     * @returns A promise resolving when the store is cleared.
+     * Process the command
+     * @param command The command to process
+     * @param context The context in which the command is executed
      */
-    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 {
+    processCommand(command: CliProcessCommand, context: ICliExecutionContext): Promise<void>;
     /**
-     * Get a snapshot of the current state.
-     * @returns A shallow copy of the state object
+     * Write the description of the command
+     * @param context The context in which the command is executed
      */
-    getState<T extends CliState = CliState>(): T;
+    writeDescription?(context: ICliExecutionContext): void;
     /**
-     * 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
+     * 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
      */
-    updateState(newState: Partial<CliState>): void;
+    validateBeforeExecution?: (command: CliProcessCommand, context: ICliExecutionContext) => {
+        valid: boolean;
+        message?: string;
+    };
     /**
-     * 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.
+     * Initialize the command processor
+     * @param context The context in which the command is executed
      */
-    select<K>(selector: (state: CliState) => K): Observable<K>;
+    initialize?(context: ICliExecutionContext): Promise<void>;
     /**
-     * Subscribe to state changes.
-     * @param callback Callback function to handle state changes.
-     * @returns Subscription object to manage the subscription.
+     * 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
      */
-    subscribe(callback: (state: CliState) => void): Subscription;
+    onData?(data: string, context: ICliExecutionContext): Promise<void>;
     /**
-     * Reset the state to its initial value.
+     * 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
      */
-    reset(): void;
+    onResize?(cols: number, rows: number, context: ICliExecutionContext): void;
     /**
-     * Persist the state to storage.
+     * 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
      */
-    persist(): Promise<void>;
+    onDispose?(context: ICliExecutionContext): void;
+}
+/**
+ * Represents a child command processor
+ */
+interface ICliCommandChildProcessor extends ICliCommandProcessor {
     /**
-     * Initialize the state from storage.
+     * The parent processor, it is populated by the processor manager
      */
-    initialize(): Promise<void>;
+    parent?: ICliCommandProcessor;
 }
 
 /**
@@ -1900,6 +2616,17 @@ interface ICliModule {
     processors?: ICliCommandProcessor[];
     /** Services registered into the shared service container */
     services?: CliProvider[];
+    /**
+     * Global command guards contributed by this module. They are registered
+     * when the module boots and run before every command (across all modules),
+     * e.g. authentication or permission checks. See {@link ICliCommandGuard}.
+     */
+    guards?: ICliCommandGuard[];
+    /**
+     * Permissions this module uses (`resource:action`), registered in the
+     * {@link ICliPermissionRegistry} at boot so they can be listed and granted.
+     */
+    permissions?: CliPermissionDefinition[];
     /** Module configuration, set via configure() */
     config?: Record<string, any>;
     /**
@@ -1991,449 +2718,411 @@ interface ICliLogger {
      */
     error(...args: any[]): void;
     /**
-     * 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;
-}
-
-/**
- * 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[];
+     * Log a debug message (DEBUG level)
+     * @param args The arguments to log
+     */
+    debug(...args: any[]): void;
 }
+
 /**
- * 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 = {
+/** 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 speed of the animation
-     * @default 100
+     * 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
      */
-    speed?: number;
+    getHeaders(serverName: string): Record<string, string>;
     /**
-     * The text will be removed after typing
+     * Optional: query parameters for WebSocket upgrades to this server (e.g. a
+     * short-lived single-use ticket). Called right before each connection.
+     * Return `undefined` when this provider does not handle the server.
+     * When any provider returns params, headers are NOT copied into the URL
+     * (so bearer tokens never appear in WebSocket URLs).
      */
-    removeAfterTyping?: boolean;
-};
-interface ICliTextAnimator extends ICliProgressBar {
+    getWebSocketParams?(serverName: string): Promise<Record<string, string> | undefined>;
+}
+/**
+ * Minimal view of the CLI server manager (token `ICliServerManager_TOKEN`),
+ * e.g. for auth modules that must refresh a server after sign-in.
+ */
+interface ICliServerManager {
+    /** Reconnect a server: re-fetch its commands and reopen its event socket. */
+    reconnect(name: string): Promise<{
+        success: boolean;
+        commandCount: number;
+    }>;
     /**
-     * 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
+     * The server a command should target when the user names none: the
+     * default server (`server default`) when connected, otherwise the first
+     * connected server. `null` when no server is connected (for example every
+     * server requires a login the user has not done yet).
      */
-    showText: (text: string, options?: CliTextAnimatorOptions) => Promise<void>;
+    preferredServer?(): string | null;
 }
-
+/** Token for {@link ICliServerManager} */
+declare const ICliServerManager_TOKEN = "cli-server-manager";
 /**
- * Represents a service that manages user sessions in the CLI
+ * 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 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>;
+interface ICliServerAuthService {
+    /**
+     * 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
+     */
+    getHeaders(serverName: string, configHeaders?: CliHeadersProvider): Record<string, string>;
+    /**
+     * WebSocket upgrade query params from the registered token providers, or
+     * `undefined` when no provider handles this server.
+     */
+    getWebSocketParams?(serverName: string): Promise<Record<string, string> | undefined>;
 }
+
 /**
- * Represents a service that manages users 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 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>;
-}
+type CliHeadersProvider = Record<string, string> | (() => Record<string, string>);
 /**
- * Represents a service that manages groups in the CLI
+ * Resolves a CliHeadersProvider to a plain header map.
  */
-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 resolveHeaders(provider?: CliHeadersProvider): Record<string, string>;
 /**
- * Represents a service that handles authentication 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 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>;
-}
-
+declare function resolveServerHeaders(services: ICliServiceProvider | undefined, serverName: string, configHeaders?: CliHeadersProvider): Record<string, string>;
 /**
- * Represents a serialized snapshot of a CLI engine's state.
- * Used to duplicate terminal tabs with full state preservation.
+ * Configuration for a remote CLI server
  */
-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 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;
+};
 /**
- * Messages sent from the main thread to a background service Worker.
+ * A single output item in a server response
  */
-type CliWorkerInboundMessage = {
-    type: 'start';
-    config?: Record<string, unknown>;
+type CliServerOutput = {
+    type: 'text';
+    value: string;
+    style?: 'success' | 'error' | 'info' | 'warning';
 } | {
-    type: 'stop';
+    type: 'table';
+    headers: string[];
+    rows: string[][];
 } | {
-    type: 'abort';
+    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[];
 };
 /**
- * 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;
+    /** The user must set a new password before doing anything else */
+    mustChangePassword?: boolean;
+    /** Extensible metadata (department, phone, preferences, etc.) */
+    data?: Record<string, any>;
+    /** Timestamp of last successful login */
+    lastLoginAt?: number;
 }
-
 /**
- * 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;
+    /**
+     * Permissions granted to every member of the group. Groups act as roles.
+     * Permission strings are `resource:action` (e.g. `users:create`), with
+     * `*` wildcards (`users:*`, `*`). See {@link cliPermissionMatches}.
+     */
+    permissions?: string[];
+    /** Built-in groups (`admin`, `users`) cannot be deleted */
+    builtIn?: boolean;
+    /** Last modification timestamp */
+    updatedAt?: 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;
+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;
     /**
-     * Close a pane by ID. Searches all tabs for the pane.
-     * No-op if the ID does not exist.
+     * Effective permissions of the user (union of their groups' permissions),
+     * resolved by the users module at login and refreshed when groups change.
      */
-    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;
+    permissions?: string[];
+    /** 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
@@ -2597,12 +3286,45 @@ 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;
+/**
+ * Build the WebSocket URL for a configured server. Prefers upgrade params
+ * from auth providers (e.g. a single-use ticket from the users module); only
+ * when no provider handles the server are headers copied into the URL
+ * (legacy behaviour, see {@link buildAuthenticatedWebSocketUrl}).
+ */
+declare function resolveServerWebSocketUrl(services: ICliServiceProvider | undefined, serverName: string, wsUrl: string, configHeaders?: CliHeadersProvider): Promise<string>;
+/** Append query params to a URL that may already have some. */
+declare function appendQueryParams(url: string, params: Record<string, string>): string;
+
 /**
  * Derives CLI panel CSS custom property values from an xterm ITheme object.
  * Used when `syncTheme` is enabled on the panel config.
@@ -2643,13 +3365,93 @@ 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;
 
+/**
+ * Permission strings are `resource:action` (for example `users:create`).
+ * A trailing `*` segment matches anything at that level and below; a `*`
+ * in any other position matches exactly one segment:
+ *
+ * | granted       | matches                               |
+ * |---------------|---------------------------------------|
+ * | `*`           | every permission                      |
+ * | `users:*`     | `users:create`, `users:delete`, ...   |
+ * | `*:read`      | `users:read`, `groups:read`, ...      |
+ * | `users:read`  | only `users:read`                     |
+ *
+ * Matching is case-insensitive.
+ */
+declare function cliPermissionMatches(granted: string, required: string): boolean;
+/** True when any granted permission matches `required`. */
+declare function cliHasPermission(granted: readonly string[] | undefined, required: string): boolean;
+/** The subset of `required` permissions not covered by `granted`. */
+declare function cliMissingPermissions(granted: readonly string[] | undefined, required: readonly string[]): string[];
+/** Union of permissions, de-duplicated, preserving first-seen order. */
+declare function cliMergePermissions(...lists: (readonly string[] | undefined)[]): string[];
+/**
+ * Built-in permissions used by the users module. Other modules define their
+ * own (e.g. `deploy:run`); any string in `resource:action` form works.
+ */
+/** Permissions for remote CLI server features. */
+declare const CliServerPermissions: {
+    /** Open a remote shell on a server (`ssh`) */
+    readonly ShellExecute: "shell:execute";
+};
+declare const CliUsersPermissions: {
+    readonly UsersRead: "users:read";
+    readonly UsersCreate: "users:create";
+    readonly UsersUpdate: "users:update";
+    readonly UsersDelete: "users:delete";
+    readonly GroupsRead: "groups:read";
+    readonly GroupsCreate: "groups:create";
+    readonly GroupsUpdate: "groups:update";
+    readonly GroupsDelete: "groups:delete";
+    readonly SessionsRead: "sessions:read";
+    readonly SessionsRevoke: "sessions:revoke";
+    readonly AuditRead: "audit:read";
+    readonly AuditClear: "audit:clear";
+};
+
+/**
+ * `metadata.requireAuth` (also implied by `requiredGroups` /
+ * `requiredPermissions`): the command needs a signed-in principal.
+ * Active only when an {@link ICliAuthorizationService} is registered.
+ */
+declare const cliRequireAuthGuard: ICliCommandGuard;
+/**
+ * `metadata.requiredGroups`: the principal must belong to at least one group.
+ * Active only when an {@link ICliAuthorizationService} is registered.
+ */
+declare const cliRequiredGroupsGuard: ICliCommandGuard;
+/**
+ * `metadata.requiredPermissions`: the principal must hold all permissions.
+ * Active only when an {@link ICliAuthorizationService} is registered.
+ */
+declare const cliRequiredPermissionsGuard: ICliCommandGuard;
+/**
+ * Guards enforcing access metadata on processors. Registered by the CLI
+ * engine; they do nothing until an auth module registers an
+ * {@link ICliAuthorizationService}.
+ */
+declare const cliAccessMetadataGuards: ICliCommandGuard[];
+
+/**
+ * The server a command should use when the user does not name one.
+ *
+ * Prefers the server manager's choice (the default server, else the first
+ * connected one) so a command does not pick a server that is down or that
+ * rejects the user (a protected server they have not signed in to). Falls
+ * back to the first configured server when no manager is available or
+ * nothing is connected, so callers still get a clear error from that server.
+ */
+declare function cliDefaultServer(context: Pick<ICliExecutionContext, 'services' | 'options'>): CliServerConfig | undefined;
+
 /**
  * Retrieve a parameter's value from the parsed arguments, checking aliases.
  * @param p The parameter descriptor
@@ -2802,7 +3604,7 @@ interface CliThemeInfo {
 
 declare const DefaultThemeInfos: Record<string, CliThemeInfo>;
 
-declare const LIBRARY_VERSION = "2.0.0-beta.12";
+declare const LIBRARY_VERSION = "2.0.0-beta.14";
 declare const API_VERSION = 2;
 
 /**
@@ -2863,4 +3665,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 CliAccessAction, CliAccessDeniedError, type CliAddUser, CliBackgroundColor, type CliBackgroundServiceStatus, type CliBackgroundServiceType, type CliCommandGuardResult, type CliDateOptions, type CliEngineSnapshot, type CliFactoryProvider, type CliFilePickerOptions, type CliFileResult, CliForegroundColor, type CliFullScreenOptions, type CliHeadersProvider, CliHttpError, 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 CliPermissionDefinition, type CliProcessCommand, type CliProcessorMetadata, type CliProvider, type CliSelectOption, type CliSelectOptions, type CliServerCapabilities, type CliServerCommandDescriptor, type CliServerConfig, type CliServerOutput, CliServerPermissions, 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, CliUsersPermissions, type CliValueProvider, type CliWorkerInboundMessage, type CliWorkerOutboundMessage, DEFAULT_DIR_PERMISSIONS, DEFAULT_FILE_PERMISSIONS, DefaultLibraryAuthor, DefaultThemeInfos, DefaultThemes, type DefaultThemesType, type ICliAuditEntry, type ICliAuditService, ICliAuditService_TOKEN, type ICliAuthService, ICliAuthService_TOKEN, type ICliAuthorizationService, ICliAuthorizationService_TOKEN, type ICliBackgroundService, type ICliBackgroundServiceInfo, type ICliBackgroundServiceRegistry, type ICliClipboard, type ICliCommandAuthor, type ICliCommandChildProcessor, type ICliCommandExecutorService, type ICliCommandGuard, ICliCommandGuard_TOKEN, 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, ICliKeyValueStore_TOKEN, type ICliLogger, type ICliManagedInterval, type ICliManagedTimer, type ICliModule, type ICliNotifier, type ICliOwnership, type ICliPanelRef, type ICliPercentageProgressBar, type ICliPermissionRegistry, ICliPermissionRegistry_TOKEN, type ICliPermissionService, ICliPermissionService_TOKEN, type ICliPingServerService, type ICliPrincipal, type ICliProcessEntry, type ICliProcessRegisterOptions, type ICliProcessRegistry, type ICliProcessorHook, type ICliProgressBar, type ICliProtectedResource, type ICliServerAuthService, ICliServerAuthService_TOKEN, type ICliServerAuthTokenProvider, ICliServerAuthTokenProvider_TOKEN, type ICliServerManager, ICliServerManager_TOKEN, type ICliServiceContext, type ICliServiceEvent, type ICliServiceLogEntry, type ICliServiceProvider, type ICliSessionInfo, type ICliSessionsService, ICliSessionsService_TOKEN, type ICliSpinner, type ICliStateStore, type ICliTerminalWriter, type ICliTextAnimator, type ICliTranslationService, ICliTranslationService_TOKEN, type ICliUmdModule, type ICliUser, type ICliUserCredentials, type ICliUserEvent, type ICliUserEventService, ICliUserEventService_TOKEN, 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, appendQueryParams, bootCliModule, bootUmdModule, buildAuthenticatedWebSocketUrl, clearTerminalLine, cliAccessMetadataGuards, cliAuthorize, cliCanAccess, cliDefaultServer, cliEvaluateAccess, cliHasPermission, cliMergePermissions, cliMissingPermissions, cliPermissionMatches, cliRequireAuthGuard, cliRequiredGroupsGuard, cliRequiredPermissionsGuard, colorFirstWord, colorizeJson, compareVersions, constants, createWorkerService, delay, derivePanelThemeStyles, enums, formatJson, getConfigValue, getParameterValue, getPluginConfigValue, getRightOfWord, highlightTextWithBg, initializeBrowserEnvironment, isCliAccessDeniedError, loadPanelPosition, nextPanelPosition, resolveConfigurationCategories, resolveHeaders, resolveServerHeaders, resolveServerWebSocketUrl, satisfiesMinVersion, satisfiesVersionRange, savePanelPosition, stripAnsi, toQueryString, utils, visibleLength };