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

package/public-api.d.mts

@@ -1,112 +1,16 @@
 import { ITerminalOptions, ITerminalInitOnlyOptions, Terminal, ITheme } from '@xterm/xterm';
 import { Subject, Observable, Subscription } from 'rxjs';
 
-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;
-};
-type CliFactoryProvider = MultiServices & {
-    useFactory: Function;
-};
-type CliProvider = {
-    provide: any;
-} & (CliValueProvider | CliTypeProvider | CliFactoryProvider) & Record<string, any>;
-
-/**
- * Represents a user in the CLI
- */
-interface ICliUser {
-    /** Unique user identifier */
-    id: string;
-    /** Login name (unique) */
-    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;
-}
-/**
- * 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;
-}
-/**
- * Represents a group in the CLI
- */
-interface ICliGroup {
-    /** Unique group identifier */
-    id: string;
-    /** Group name (unique) */
-    name: string;
-    /** Optional group description */
-    description?: string;
-    /** Group creation timestamp */
-    createdAt: number;
-}
-/**
- * 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";
-
 type CliProcessCommand = {
     /**
      * The command that was entered
      */
     command: string;
     /**
-     * The data that was entered
+     * Pipeline data passed from the previous command in a pipe chain.
+     * When commands are piped (e.g. `cmd1 | cmd2`), the output of `cmd1`
+     * is captured and passed here as input to `cmd2`. The shape depends
+     * on what the upstream command produced (string, JSON object, array, etc.).
      */
     data?: any;
     /**
@@ -126,6 +30,7 @@ type CliProcessCommand = {
      */
     args: Record<string, any>;
 };
+
 declare enum CliForegroundColor {
     Black = "\u001B[30m",
     Red = "\u001B[31m",
@@ -147,174 +52,124 @@ declare enum CliBackgroundColor {
     Cyan = "\u001B[46m",
     White = "\u001B[47m"
 }
+
 declare enum CliIcon {
-    CheckIcon = "\u2714",
-    CrossIcon = "\u2718",
-    InfoIcon = "\u2139",
-    WarningIcon = "\u26A0",
-    QuestionMark = "?",
-    Exclamation = "\u2757",
-    Ellipsis = "\u2026",
-    Dot = "\u2022",
-    Bullet = "\u2023",
-    ArrowRight = "\u2192",
-    ArrowLeft = "\u2190",
-    ArrowUp = "\u2191",
-    ArrowDown = "\u2193",
-    ArrowRightFilled = "\u25B6",
-    ArrowLeftFilled = "\u25C0",
-    ArrowUpFilled = "\u25B2",
-    ArrowDownFilled = "\u25BC",
-    DoubleArrowRight = "\u00BB",
-    DoubleArrowLeft = "\u00AB",
-    Star = "\u2605",
-    StarEmpty = "\u2606",
-    Plus = "+",
-    Minus = "-",
-    Progress = "\u23F3",
-    Success = "\u2705",
-    Failure = "\u274C",
-    Clock = "\u23F0",
-    Timer = "\u23F1",
-    Alarm = "\uD83D\uDD14",
-    Calendar = "\uD83D\uDCC5",
-    Folder = "\uD83D\uDCC1",
-    FolderOpen = "\uD83D\uDCC2",
-    File = "\uD83D\uDCC4",
-    Archive = "\uD83D\uDDC3",
-    Link = "\uD83D\uDD17",
-    Chain = "\u26D3",
-    Bookmark = "\uD83D\uDD16",
-    Edit = "\u270F",
-    Trash = "\uD83D\uDDD1",
-    Add = "\u2795",
-    Remove = "\u2796",
-    Reload = "\uD83D\uDD04",
-    Save = "\uD83D\uDCBE",
-    Undo = "\u21A9",
-    Redo = "\u21AA",
-    Play = "\u25B6",
-    Pause = "\u23F8",
-    Stop = "\u23F9",
-    Cancel = "\u274E",
-    User = "\uD83D\uDC64",
-    Group = "\uD83D\uDC65",
-    Lock = "\uD83D\uDD12",
-    Unlock = "\uD83D\uDD13",
-    Help = "\u2753",
-    Key = "\uD83D\uDD11",
-    Shield = "\uD83D\uDEE1",
-    Gear = "\u2699",
-    Settings = "\u2699\uFE0F",
-    Theme = "\uD83C\uDFA8",
-    Light = "\uD83D\uDCA1",
-    Bug = "\uD83D\uDC1E",
-    Wrench = "\uD83D\uDD27",
-    Hammer = "\uD83D\uDD28",
-    Terminal = "\uD83D\uDCBB",
-    Database = "\uD83D\uDDC4",
-    Server = "\uD83D\uDDA5",
-    Cloud = "\u2601",
-    Network = "\uD83C\uDF10",
-    Monitor = "\uD83D\uDDA5",
-    Printer = "\uD83D\uDDA8",
-    USB = "\uD83D\uDD0C",
-    Speaker = "\uD83D\uDD0A",
-    Microphone = "\uD83C\uDF99",
-    Camera = "\uD83D\uDCF7",
-    Video = "\uD83C\uDFA5",
-    Music = "\uD83C\uDFB5",
-    Phone = "\uD83D\uDCDE",
-    Package = "\uD83D\uDCE6",
-    Plugin = "\uD83D\uDD0C",
-    Extension = "\uD83E\uDDE9",
-    Module = "\uD83D\uDCE6",
-    Evaluate = "\uD83D\uDD0D",
-    Variable = "\uD83D\uDD27",
-    Script = "\uD83D\uDCDC",
-    Code = "\uD83D\uDCBE",
-    Logs = "\uD83D\uDCDC",
-    Power = "\u23FB",
-    Heart = "\u2764",
-    Flame = "\uD83D\uDD25",
-    Growth = "\uD83D\uDCC8",
-    Decline = "\uD83D\uDCC9",
-    WarningFilled = "\u26A0\uFE0F",
-    Sun = "\u2600",
-    Moon = "\uD83C\uDF19",
-    Rain = "\uD83C\uDF27",
-    Snow = "\u2744",
-    Lightning = "\u26A1",
-    Tree = "\uD83C\uDF32",
-    Smile = "\uD83D\uDE0A",
-    Sad = "\uD83D\uDE22",
-    Angry = "\uD83D\uDE21",
-    Clap = "\uD83D\uDC4F",
-    ThumbsUp = "\uD83D\uDC4D",
-    ThumbsDown = "\uD83D\uDC4E",
-    Rocket = "\uD83D\uDE80",
-    Globe = "\uD83C\uDF0D",
-    Medal = "\uD83C\uDFC5",
-    Trophy = "\uD83C\uDFC6",
-    Flag = "\uD83D\uDEA9",
-    StarFilled = "\u2B50",
-    StarOutline = "\u2729",
-    Fireworks = "\uD83C\uDF86",
-    Balloon = "\uD83C\uDF88",
+    CheckIcon = "\u2714",// Success, completion
+    CrossIcon = "\u2718",// Failure, error
+    InfoIcon = "\u2139",// Information
+    WarningIcon = "\u26A0",// Warning
+    QuestionMark = "?",// Help or unknown state
+    Exclamation = "\u2757",// Emphasis or alert
+    Ellipsis = "\u2026",// Loading or truncated text
+    Dot = "\u2022",// List item
+    Bullet = "\u2023",// Alternate bullet point
+    ArrowRight = "\u2192",// Navigation or next step
+    ArrowLeft = "\u2190",// Previous step or navigation
+    ArrowUp = "\u2191",// Up direction
+    ArrowDown = "\u2193",// Down direction
+    ArrowRightFilled = "\u25B6",// Navigation or next step (filled)
+    ArrowLeftFilled = "\u25C0",// Previous step or navigation (filled)
+    ArrowUpFilled = "\u25B2",// Up direction (filled)
+    ArrowDownFilled = "\u25BC",// Down direction (filled)
+    DoubleArrowRight = "\u00BB",// Fast forward or next
+    DoubleArrowLeft = "\u00AB",// Rewind or previous
+    Star = "\u2605",// Highlight or favorite (filled)
+    StarEmpty = "\u2606",// Highlight or favorite (empty)
+    Plus = "+",// Addition or increment
+    Minus = "-",// Subtraction or decrement
+    Progress = "\u23F3",// Indicating progress
+    Success = "\u2705",// Success (alternative to CheckIcon)
+    Failure = "\u274C",// Failure (alternative to CrossIcon)
+    Clock = "\u23F0",// Time-related
+    Timer = "\u23F1",// Stopwatch or timer
+    Alarm = "\uD83D\uDD14",// Alarm or alert
+    Calendar = "\uD83D\uDCC5",// Calendar or date
+    Folder = "\uD83D\uDCC1",// Directory or file grouping
+    FolderOpen = "\uD83D\uDCC2",// Open folder
+    File = "\uD83D\uDCC4",// File or document
+    Archive = "\uD83D\uDDC3",// Archive or file grouping
+    Link = "\uD83D\uDD17",// Hyperlink or connection
+    Chain = "\u26D3",// Chain or linked
+    Bookmark = "\uD83D\uDD16",// Bookmark or save
+    Edit = "\u270F",// Edit or modify
+    Trash = "\uD83D\uDDD1",// Deletion or removal
+    Add = "\u2795",// Add user or item
+    Remove = "\u2796",// Remove user or item
+    Reload = "\uD83D\uDD04",// Refresh or reload
+    Save = "\uD83D\uDCBE",// Save or store
+    Undo = "\u21A9",// Undo action
+    Redo = "\u21AA",// Redo action
+    Play = "\u25B6",// Start or play
+    Pause = "\u23F8",// Pause or stop temporarily
+    Stop = "\u23F9",// Stop or end
+    Cancel = "\u274E",// Cancel or close
+    User = "\uD83D\uDC64",// User or profile
+    Group = "\uD83D\uDC65",// Group or team
+    Lock = "\uD83D\uDD12",// Secured or locked
+    Unlock = "\uD83D\uDD13",// Unlocked or accessible
+    Help = "\u2753",// Help or support
+    Key = "\uD83D\uDD11",// Authentication or key
+    Shield = "\uD83D\uDEE1",// Security or protection
+    Gear = "\u2699",// Settings or configuration
+    Settings = "\u2699\uFE0F",// Settings (alternative)
+    Theme = "\uD83C\uDFA8",// Theme or appearance
+    Light = "\uD83D\uDCA1",// Light mode
+    Bug = "\uD83D\uDC1E",// Bug or issue
+    Wrench = "\uD83D\uDD27",// Maintenance or tools
+    Hammer = "\uD83D\uDD28",// Build or fix
+    Terminal = "\uD83D\uDCBB",// Terminal or command line
+    Database = "\uD83D\uDDC4",// Database or storage
+    Server = "\uD83D\uDDA5",// Server or host
+    Cloud = "\u2601",// Cloud or remote
+    Network = "\uD83C\uDF10",// Network or connection
+    Monitor = "\uD83D\uDCFA",// Monitor or display
+    Printer = "\uD83D\uDDA8",// Printer or output
+    USB = "\uD83D\uDD0C",// USB or connection
+    Speaker = "\uD83D\uDD0A",// Speaker or audio
+    Microphone = "\uD83C\uDF99",// Microphone or input
+    Camera = "\uD83D\uDCF7",// Camera or video
+    Video = "\uD83C\uDFA5",// Video or media
+    Music = "\uD83C\uDFB5",// Music or audio
+    Phone = "\uD83D\uDCDE",// Phone or communication
+    Package = "\uD83D\uDCE6",// Package or bundle
+    Plugin = "\uD83E\uDDE9",// Plugin or extension
+    Extension = "\uD83D\uDD0C",// Extension or connection
+    Module = "\uD83E\uDDF1",// Module or package
+    Evaluate = "\uD83D\uDD0D",// Evaluate or search
+    Variable = "\uD835\uDC65",// Variable or setting
+    Script = "\uD83D\uDCDC",// Script or code
+    Code = "\uD83D\uDCDD",// Code or file
+    Logs = "\uD83D\uDCCB",// Logs or history
+    Power = "\u23FB",// On/Off state
+    Heart = "\u2764",// Love or favorite
+    Flame = "\uD83D\uDD25",// Trending or hot
+    Growth = "\uD83D\uDCC8",// Growth or increase
+    Decline = "\uD83D\uDCC9",// Decline or decrease
+    WarningFilled = "\u26A0\uFE0F",// Warning (filled)
+    Sun = "\u2600",// Brightness or day
+    Moon = "\uD83C\uDF19",// Night or dark mode
+    Rain = "\uD83C\uDF27",// Rain or bad weather
+    Snow = "\u2744",// Snow or cold
+    Lightning = "\u26A1",// Lightning or danger
+    Tree = "\uD83C\uDF32",// Nature or environment
+    Smile = "\uD83D\uDE0A",// Happiness or positive state
+    Sad = "\uD83D\uDE22",// Sadness or negative state
+    Angry = "\uD83D\uDE21",// Anger or frustration
+    Clap = "\uD83D\uDC4F",// Applause or celebration
+    ThumbsUp = "\uD83D\uDC4D",// Approval or success
+    ThumbsDown = "\uD83D\uDC4E",// Disapproval or failure
+    Rocket = "\uD83D\uDE80",// Launch or deploy
+    Globe = "\uD83C\uDF0D",// Earth or international
+    Medal = "\uD83C\uDFC5",// Achievement or award
+    Trophy = "\uD83C\uDFC6",// Winner or champion
+    Flag = "\uD83D\uDEA9",// Mark or flag
+    StarFilled = "\u2B50",// Highlight or favorite
+    StarOutline = "\u2729",// Alternate star icon
+    Fireworks = "\uD83C\uDF86",// Celebration
+    Balloon = "\uD83C\uDF88",// Party or fun
     Gift = "\uD83C\uDF81"
 }
-/**
- * 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';
-}
-/**
- * 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[];
-};
+
 /**
  * Configuration for a remote CLI server
  */
@@ -363,7 +218,7 @@ type CliServerResponse = {
     outputs: CliServerOutput[];
 };
 /**
- * Metadata about a remote command processor, returned by GET /api/cli/commands
+ * Metadata about a remote command processor, returned by GET /api/qcli/commands
  */
 type CliServerCommandDescriptor = {
     command: string;
@@ -380,7 +235,7 @@ type CliServerCommandDescriptor = {
     processors?: CliServerCommandDescriptor[];
 };
 /**
- * Server capabilities returned by GET /api/cli/capabilities
+ * Server capabilities returned by GET /api/qcli/capabilities
  */
 type CliServerCapabilities = {
     /** Whether this server supports remote shell access */
@@ -391,6 +246,80 @@ type CliServerCapabilities = {
     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 {
+    /**
+     * 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
@@ -468,24 +397,20 @@ type CliStateConfiguration = {
      */
     storeName?: string;
 };
-/**
- * Represents a log level for the CLI
- */
-declare enum CliLogLevel {
-    None = 0,
-    DEBUG = 1,
-    LOG = 2,
-    INFO = 3,
-    WARN = 4,
-    ERROR = 5
-}
 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';
 /**
@@ -538,175 +463,632 @@ interface CliPanelConfig {
      */
     syncTheme?: boolean;
 }
-declare const enums: {
-    CliForegroundColor: typeof CliForegroundColor;
-    CliBackgroundColor: typeof CliBackgroundColor;
-    CliIcon: typeof CliIcon;
-    CliLogLevel: typeof CliLogLevel;
+
+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;
+};
+type CliFactoryProvider = MultiServices & {
+    useFactory: Function;
 };
+type CliProvider = {
+    provide: any;
+} & (CliValueProvider | CliTypeProvider | CliFactoryProvider) & Record<string, any>;
 
 /**
- * Represents an option for the readSelect prompt.
+ * Represents a user in the CLI
  */
-interface CliSelectOption {
-    /** Display text shown to the user */
-    label: string;
-    /** Value returned when this option is selected */
-    value: string;
+interface ICliUser {
+    /** Unique user identifier */
+    id: string;
+    /** Login name (unique) */
+    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;
 }
 /**
- * Represents an option for the readMultiSelect prompt.
+ * Represents user credentials (shadow pattern — stored separately from ICliUser)
  */
-interface CliMultiSelectOption extends CliSelectOption {
-    /** Whether the option is pre-selected */
-    checked?: boolean;
+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;
 }
 /**
- * Provides interactive input reading from the terminal.
- * All methods resolve with `null` when the user aborts (Ctrl+C or Escape).
+ * Represents a group in the CLI
  */
-interface ICliInputReader {
+interface ICliGroup {
+    /** Unique group identifier */
+    id: string;
+    /** Group name (unique) */
+    name: string;
+    /** Optional group description */
+    description?: string;
+    /** Group creation timestamp */
+    createdAt: number;
+}
+/**
+ * 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 {
+    /**
+     * Write text to the terminal
+     * @param text The text to write
+     */
+    write(text: string): void;
     /**
-     * Prompt the user for a line of text input.
-     * @param prompt The prompt text to display (e.g. "Enter your name: ")
-     * @returns The entered text, empty string if Enter pressed with no input, or null if aborted
+     * Write text to the terminal followed by a newline
+     * @param text The text to write
      */
-    readLine(prompt: string): Promise<string | null>;
+    writeln(text?: string): void;
     /**
-     * Prompt the user for password input. Characters are masked with asterisks.
-     * @param prompt The prompt text to display (e.g. "Password: ")
-     * @returns The entered password, empty string if Enter pressed with no input, or null if aborted
+     * Write a success message to the terminal
+     * @param message The message to write
      */
-    readPassword(prompt: string): Promise<string | null>;
+    writeSuccess(message: string): void;
     /**
-     * Prompt the user for a yes/no confirmation.
-     * @param prompt The prompt text to display (e.g. "Continue?")
-     * @param defaultValue The default value when Enter is pressed without input (defaults to false)
-     * @returns true for yes, false for no, defaultValue on empty Enter, or null if aborted
+     * Write an info message to the terminal
+     * @param message The message to write
      */
-    readConfirm(prompt: string, defaultValue?: boolean): Promise<boolean | null>;
+    writeInfo(message: string): void;
     /**
-     * Prompt the user to select from a list of options using arrow keys.
-     * @param prompt The prompt text to display (e.g. "Pick one:")
-     * @param options The list of options to choose from
-     * @param onChange Optional callback invoked each time the highlighted option changes
-     * @returns The value of the selected option, or null if aborted
+     * Write an error message to the terminal
+     * @param message The message to write
      */
-    readSelect(prompt: string, options: CliSelectOption[], onChange?: (value: string) => void): Promise<string | null>;
+    writeError(message: string): void;
     /**
-     * Prompt the user to select from a horizontal single-line option picker.
-     * Navigate with Left/Right arrow keys.
-     * @param prompt The prompt text to display
-     * @param options The list of options to choose from
-     * @param onChange Optional callback invoked each time the highlighted option changes
-     * @returns The value of the selected option, or null if aborted
+     * Write a warning message to the terminal
+     * @param message The message to write
      */
-    readSelectInline(prompt: string, options: CliSelectOption[], onChange?: (value: string) => void): Promise<string | null>;
+    writeWarning(message: string): void;
     /**
-     * Prompt the user to select multiple items from a checkbox list.
-     * Navigate with Up/Down, toggle with Space, confirm with Enter.
-     * @param prompt The prompt text to display
-     * @param options The list of options with optional pre-checked state
-     * @returns Array of selected values, or null if aborted
+     * 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
      */
-    readMultiSelect(prompt: string, options: CliMultiSelectOption[]): Promise<string[] | null>;
+    wrapInColor(text: string, color: CliForegroundColor): string;
     /**
-     * Prompt the user for numeric input with optional min/max validation.
-     * @param prompt The prompt text to display
-     * @param options Optional constraints: min, max, and default value
-     * @returns The entered number, or null if aborted
+     * Wrap text in the specified background color.
+     * @param text The text to wrap
+     * @param color The background color to apply
+     * @returns The text wrapped in ANSI background color codes
+     */
+    wrapInBackgroundColor(text: string, color: CliBackgroundColor): string;
+    /**
+     * Write a JSON object to the terminal
+     * @param json The JSON object to write
+     */
+    writeJson(json: any): void;
+    /**
+     * 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
+     */
+    writeToFile(fileName: string, content: string): void;
+    /**
+     * Write an object array as a table to the terminal
+     * @param objects The objects to write to the table
+     */
+    writeObjectsAsTable(objects: any[]): 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
      */
-    readNumber(prompt: string, options?: {
-        min?: number;
-        max?: number;
-        default?: number;
-    }): Promise<number | null>;
+    writeTable(headers: string[], rows: string[][], options?: CliTableOptions): void;
+    /**
+     * Write a divider to the terminal
+     * @param options Optional: color, length, character
+     */
+    writeDivider(options?: {
+        color?: CliForegroundColor;
+        length?: number;
+        char?: string;
+    }): void;
+    /**
+     * 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
+     */
+    writeList(items: string[], options?: {
+        ordered?: boolean;
+        prefix?: string;
+        color?: CliForegroundColor;
+    }): 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
+     */
+    writeKeyValue(entries: Record<string, string> | [string, string][], options?: {
+        separator?: string;
+        keyColor?: CliForegroundColor;
+    }): void;
+    /**
+     * Write items in a multi-column layout.
+     * @param items The items to arrange in columns
+     * @param options Optional: number of columns, padding between columns
+     */
+    writeColumns(items: string[], options?: {
+        columns?: number;
+        padding?: number;
+    }): void;
+    /**
+     * Write a clickable hyperlink using OSC 8 escape sequences.
+     * In terminals that support OSC 8, the text is clickable. In others,
+     * it falls back to displaying "text (url)".
+     * @param text The visible link text
+     * @param url The URL to link to
+     */
+    writeLink(text: string, url: string): void;
+    /**
+     * Write text inside a bordered box.
+     * Useful for callouts, notices, and highlighted information.
+     * @param content The content lines to display inside the box
+     * @param options Optional: title, border color, padding
+     */
+    writeBox(content: string | string[], options?: {
+        title?: string;
+        borderColor?: CliForegroundColor;
+        padding?: number;
+    }): void;
+    /**
+     * Write text with a specified indentation level.
+     * Each level adds 2 spaces of indentation.
+     * @param text The text to write
+     * @param level The indentation level (default: 1)
+     */
+    writeIndented(text: string, level?: number): void;
 }
 
 /**
- * Whether a background service is a long-running daemon or a one-shot job.
+ * Represents a clipboard for the CLI
  */
-type CliBackgroundServiceType = 'daemon' | 'job';
+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>;
+}
+
 /**
- * Lifecycle status of a background service.
+ * Token for the CLI user session service.
  */
-type CliBackgroundServiceStatus = 'pending' | 'running' | 'stopped' | 'failed' | 'done';
+declare const ICliUserSessionService_TOKEN = "cli-user-session-service";
 /**
- * Where the service code is executing.
+ * Token for the CLI users store service.
  */
-type CliServiceExecutionMode = 'main-thread' | 'worker';
+declare const ICliUsersStoreService_TOKEN = "cli-users-store-service";
 /**
- * An event emitted by a background service.
- * Services control terminal notification visibility by setting `data.notify: true`.
+ * Token for the CLI groups store service.
  */
-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;
-}
+declare const ICliGroupsStoreService_TOKEN = "cli-groups-store-service";
 /**
- * Handler function for service events.
+ * Token for the CLI auth service.
  */
-type CliServiceEventHandler = (event: ICliServiceEvent) => void;
+declare const ICliAuthService_TOKEN = "cli-auth-service";
 /**
- * A single log entry from a background service.
+ * Token for registering completion providers via module services (multi: true).
  */
-interface ICliServiceLogEntry {
-    timestamp: Date;
-    level: 'info' | 'warn' | 'error';
-    message: string;
-}
+declare const ICliCompletionProvider_TOKEN = "cli-completion-provider";
 /**
- * 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).
+ * Token for the drag-and-drop service.
  */
-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?: 'info' | 'warn' | 'error'): 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;
-    /** Access the shared service container */
-    services: ICliServiceProvider;
-}
+declare const ICliDragDropService_TOKEN = "cli-drag-drop-service";
 /**
- * A background service that can run as a daemon or job.
+ * Token for the file transfer service.
  */
-interface ICliBackgroundService {
-    /** Unique name for this service */
-    name: string;
-    /** Human-readable description */
-    description?: string;
-    /** 'daemon' for long-running, 'job' for run-to-completion */
-    type: CliBackgroundServiceType;
-    /** Whether this service can run in a Web Worker */
-    workerCompatible?: boolean;
-    /** Factory that creates the Worker instance (when workerCompatible) */
-    workerFactory?: () => Worker;
-    /** Called when the service starts */
-    onStart(context: ICliServiceContext): Promise<void>;
-    /** Called for graceful shutdown */
-    onStop?(context: ICliServiceContext): Promise<void>;
-    /** Called on unrecoverable error */
-    onError?(error: Error, context: ICliServiceContext): void;
+declare const ICliFileTransferService_TOKEN = "cli-file-transfer-service";
+/**
+ * Token for the translation service.
+ */
+declare const ICliTranslationService_TOKEN = "cli-translation-service";
+/**
+ * Token for the permission service.
+ */
+declare const ICliPermissionService_TOKEN = "cli-permission-service";
+/**
+ * Token for the file picker provider.
+ */
+declare const ICliFilePickerProvider_TOKEN = "cli-file-picker-provider";
+
+/**
+ * Options for readFile file picker.
+ */
+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;
+    /**
+     * File content. Type depends on `CliFilePickerOptions.readAs`:
+     * - 'text' (default): `string` (UTF-8 decoded)
+     * - 'arraybuffer': `ArrayBuffer` (raw bytes)
+     */
+    content: string | ArrayBuffer;
+    /** File size in bytes */
+    size: number;
+    /** MIME type (e.g. 'application/json', 'image/png') */
+    type: string;
+}
+/**
+ * Abstraction for environment-specific file picking.
+ * Implementations handle the actual dialog interaction for their environment.
+ */
+interface ICliFilePickerProvider {
+    /** Whether file picking is supported in this environment */
+    readonly isSupported: boolean;
+    /**
+     * Open a file picker dialog and return selected files.
+     * @returns Array of selected files, or null if the user cancelled
+     */
+    pickFiles(options?: CliFilePickerOptions): Promise<CliFileResult[] | null>;
+    /**
+     * Open a directory picker dialog and return the selected directory.
+     * @returns The selected directory, or null if the user cancelled
+     */
+    pickDirectory(): Promise<CliFileResult | null>;
+}
+
+/**
+ * Represents an option for the readSelect and readSelectInline prompts.
+ */
+interface CliSelectOption {
+    /** Display text shown to the user */
+    label: string;
+    /** Value returned when this option is selected */
+    value: string;
+    /** Optional description shown as dimmed italic text after the label */
+    description?: string;
+    /** Group name — options sharing the same group are displayed under a group header */
+    group?: string;
+    /** When true, the option is visible but cannot be selected (rendered dimmed) */
+    disabled?: boolean;
+}
+/**
+ * Represents an option for the readMultiSelect prompt.
+ */
+interface CliMultiSelectOption extends CliSelectOption {
+    /** Whether the option is pre-selected */
+    checked?: boolean;
+}
+/**
+ * Options for readLine input.
+ */
+interface CliLineOptions {
+    /**
+     * Pre-filled default value. Shown in the buffer when the prompt opens.
+     * The cursor starts at the end of the default text.
+     */
+    default?: string;
+    /**
+     * Validation function called on Enter.
+     * Return an error message string to reject the input and display the error.
+     * Return null to accept the input.
+     */
+    validate?: (value: string) => string | null;
+    /** Placeholder text shown dimmed when the buffer is empty */
+    placeholder?: string;
+}
+/**
+ * Options for readSelect and readSelectInline.
+ */
+interface CliSelectOptions {
+    /** Pre-select an option by its value */
+    default?: string;
+    /** Enable type-to-filter. When true, printable keystrokes filter the option list. Default: false. */
+    searchable?: boolean;
+    /** Callback invoked each time the highlighted option changes */
+    onChange?: (value: string) => void;
+}
+/**
+ * Options for readMultiSelect.
+ */
+interface CliMultiSelectOptions {
+    /** Enable type-to-filter. When true, printable keystrokes filter the option list. Default: false. */
+    searchable?: boolean;
+    /** Callback invoked each time the set of checked options changes */
+    onChange?: (values: string[]) => void;
+}
+/**
+ * Options for readNumber input.
+ */
+interface CliNumberOptions {
+    /** Minimum allowed value */
+    min?: number;
+    /** Maximum allowed value */
+    max?: number;
+    /** Pre-filled default value */
+    default?: number;
+}
+/**
+ * Options for readDate input.
+ */
+interface CliDateOptions {
+    /**
+     * Date format string. Supported tokens: YYYY (4-digit year), MM (2-digit month),
+     * DD (2-digit day). Separators can be `-`, `/`, or `.`.
+     * @default 'YYYY-MM-DD'
+     */
+    format?: string;
+    /** Minimum allowed date in the same format as `format` */
+    min?: string;
+    /** Maximum allowed date in the same format as `format` */
+    max?: string;
+    /** Pre-filled default value */
+    default?: string;
+}
+/**
+ * Provides interactive input reading from the terminal.
+ * All methods resolve with `null` when the user aborts (Ctrl+C or Escape).
+ */
+interface ICliInputReader {
+    /**
+     * Read a line of text input.
+     * @param prompt - The prompt text displayed to the user
+     * @param options - Optional configuration for default value, validation, and placeholder
+     * @returns The entered text, or null if aborted
+     */
+    readLine(prompt: string, options?: CliLineOptions): Promise<string | null>;
+    /**
+     * Read a password (masked input).
+     * @param prompt - The prompt text displayed to the user
+     * @returns The entered password, or null if aborted
+     */
+    readPassword(prompt: string): Promise<string | null>;
+    /**
+     * Read a yes/no confirmation.
+     * @param prompt - The prompt text displayed to the user
+     * @param defaultValue - Default value when Enter is pressed without input
+     * @returns true for yes, false for no, or null if aborted
+     */
+    readConfirm(prompt: string, defaultValue?: boolean): Promise<boolean | null>;
+    /**
+     * Read a selection from a vertical list of options.
+     * @param prompt - The prompt text displayed to the user
+     * @param options - Array of options to choose from
+     * @param selectOptions - Optional configuration for default, search, onChange
+     * @returns The selected option's value, or null if aborted
+     */
+    readSelect(prompt: string, options: CliSelectOption[], selectOptions?: CliSelectOptions): Promise<string | null>;
+    /**
+     * Read a selection from an inline horizontal list.
+     * @param prompt - The prompt text displayed to the user
+     * @param options - Array of options to choose from
+     * @param selectOptions - Optional configuration for default, search, onChange
+     * @returns The selected option's value, or null if aborted
+     */
+    readSelectInline(prompt: string, options: CliSelectOption[], selectOptions?: CliSelectOptions): Promise<string | null>;
+    /**
+     * Read multiple selections from a checkbox list.
+     * @param prompt - The prompt text displayed to the user
+     * @param options - Array of options with optional pre-checked state
+     * @param selectOptions - Optional configuration for search, onChange
+     * @returns Array of selected option values, or null if aborted
+     */
+    readMultiSelect(prompt: string, options: CliMultiSelectOption[], selectOptions?: CliMultiSelectOptions): Promise<string[] | null>;
+    /**
+     * Read a number input.
+     * @param prompt - The prompt text displayed to the user
+     * @param options - Optional configuration for min, max, and default value
+     * @returns The entered number, or null if aborted
+     */
+    readNumber(prompt: string, options?: CliNumberOptions): Promise<number | null>;
+    /**
+     * Read a date input with format validation.
+     * @param prompt - The prompt text displayed to the user
+     * @param options - Optional configuration for format, min/max range, default
+     * @returns The date string in the specified format, or null if aborted
+     */
+    readDate(prompt: string, options?: CliDateOptions): Promise<string | null>;
+    /**
+     * Read file(s) via the environment's file picker dialog.
+     * @param prompt - The prompt text displayed to the user
+     * @param options - Optional configuration for multiple, accept filter, directory mode
+     * @returns Array of selected files with content, or null if cancelled/unsupported
+     */
+    readFile(prompt: string, options?: CliFilePickerOptions): Promise<CliFileResult[] | null>;
+}
+
+/**
+ * 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;
+    /** Access the shared service container */
+    services: ICliServiceProvider;
+}
+/**
+ * A background service that can run as a daemon or job.
+ */
+interface ICliBackgroundService {
+    /** Unique name for this service */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** 'daemon' for long-running, 'job' for run-to-completion */
+    type: CliBackgroundServiceType;
+    /** Whether this service can run in a Web Worker */
+    workerCompatible?: boolean;
+    /** Factory that creates the Worker instance (when workerCompatible) */
+    workerFactory?: () => Worker;
+    /** Called when the service starts */
+    onStart(context: ICliServiceContext): Promise<void>;
+    /** 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.
+     */
+    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;
@@ -729,7 +1111,7 @@ interface ICliBackgroundServiceRegistry {
     restart(name: string): Promise<void>;
     startJob(name: string, task: (context: ICliServiceContext) => Promise<void>, options?: {
         workerCompatible?: boolean;
-    }): void;
+    }): Promise<void>;
     getStatus(name: string): ICliBackgroundServiceInfo | undefined;
     list(): ICliBackgroundServiceInfo[];
     getLogs(name: string, limit?: number): ICliServiceLogEntry[];
@@ -747,14 +1129,24 @@ interface ICliBackgroundServiceRegistry {
  */
 interface ICliManagedTimer {
     /** Clear this timer immediately. */
-    clear(): void;
+    readonly clear: () => void;
 }
 /**
  * A managed interval handle with the ability to change the delay.
  */
 interface ICliManagedInterval extends ICliManagedTimer {
     /** Change the interval delay. Restarts the interval with the new delay. */
-    setDelay(ms: number): void;
+    readonly setDelay: (ms: number) => void;
+}
+/**
+ * Options for entering full-screen mode.
+ */
+interface CliFullScreenOptions {
+    /**
+     * Whether to show the terminal cursor. Defaults to `false` (cursor hidden).
+     * Set to `true` for REPL / input-line interfaces where the user types text.
+     */
+    showCursor?: boolean;
 }
 /**
  * Represents the context in which a command is executed
@@ -886,11 +1278,18 @@ interface ICliExecutionContext {
     promptPathProvider?: () => string | null;
     /**
      * Enter full-screen mode: switches to the alternate screen buffer,
-     * hides the cursor, and sets the given processor as the context processor
-     * so that all terminal input is routed to its `onData` method.
+     * positions the cursor at row 1 col 1, and sets the given processor
+     * as the context processor so that all terminal input is routed to
+     * its `onData` method.
+     *
+     * By default the cursor is hidden (suitable for games / editors that
+     * manage their own cursor). Pass `{ showCursor: true }` to keep it
+     * visible (suitable for REPL / input-line interfaces).
+     *
      * @param processor The processor that will handle all input in full-screen mode
+     * @param options Optional settings for full-screen mode
      */
-    enterFullScreenMode: (processor: ICliCommandProcessor) => void;
+    enterFullScreenMode: (processor: ICliCommandProcessor, options?: CliFullScreenOptions) => void;
     /**
      * Exit full-screen mode: restores the cursor, leaves the alternate screen buffer,
      * clears the context processor, and re-displays the prompt.
@@ -1094,7 +1493,7 @@ interface ICliCommandProcessor {
     /**
      * Represents the state configuration for the command processor
      * @remarks The state configuration is used to store and retrieve state information for the command processor
-     * @remarks State confihuration is optional and can be used to store and retrieve state information for the command processor
+     * @remarks State configuration is optional and can be used to store and retrieve state information for the command processor
      * @remarks The state configuration is used only for root command processors and not for child command processors
      */
     stateConfiguration?: CliStateConfiguration;
@@ -1188,430 +1587,28 @@ 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>;
-}
-
-/**
- * Token for registering completion providers via module services (multi: true).
- */
-declare const ICliCompletionProvider_TOKEN = "cli-completion-provider";
-/**
- * Context passed to completion providers describing the current input state.
- */
-interface ICliCompletionContext {
-    /** Full current line text */
-    input: string;
-    /** Cursor position in the line */
-    cursor: number;
-    /** The token (word) being completed at the cursor position */
-    token: string;
-    /** Start index of the token in the input string */
-    tokenStart: number;
-    /** Index of the token among all tokens (0 = command, 1+ = arguments) */
-    tokenIndex: number;
-    /** All tokens parsed from the input */
-    tokens: string[];
-}
-/**
- * Provides tab-completion candidates for CLI input.
- * Plugins can register providers to extend completion (e.g. file paths, custom values).
- */
-interface ICliCompletionProvider {
-    /**
-     * Priority order. Lower values are checked first.
-     * Built-in defaults: 100 (commands), 200 (parameters).
-     * Plugins should use lower values (e.g. 50) to take precedence for specific commands.
-     */
-    priority: number;
-    /**
-     * Return completion candidates for the current input context.
-     * Return an empty array if this provider does not apply.
-     */
-    getCompletions(context: ICliCompletionContext): string[] | Promise<string[]>;
-}
-
-interface ICliProgressBar {
-    /**
-     * Indicates if the progress bar is running
-     */
-    isRunning: boolean;
-    /**
-     * Show the progress bar
-     */
-    show: (text?: string) => void;
-    /**
-     * Hide the progress bar
-     */
-    hide: () => void;
-}
-/**
- * Represents a spinner for the CLI
- */
-interface ICliSpinner extends ICliProgressBar {
-    /**
-     * Set the text of the spinner
-     * @param text The text to set
-     */
-    setText: (text: string) => void;
-}
-type CliPercentageProgressBarUpdateValueOptions = {
-    /**
-     * The type of update to perform
-     * @default 'replace'
-     */
-    type?: 'replace' | 'increment';
-};
-/**
- * Represents a progress bar for the CLI
- */
-interface ICliPercentageProgressBar extends ICliProgressBar {
-    /**
-     * Update the progress of the progress bar
-     * @param progress The progress to update to
-     * @returns void
-     */
-    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
-     * @param options
-     * @returns
-     */
-    showText: (text: string, options?: CliTextAnimatorOptions) => Promise<void>;
-}
-
-/**
- * Represents a service that manages user sessions in the CLI
- */
-interface ICliUserSessionService {
-    /** Gets the current user session as a reactive stream */
-    getUserSession(): Observable<ICliUserSession | undefined>;
-    /** Sets the current user session */
-    setUserSession(session: ICliUserSession): Promise<void>;
-    /** Clears the current session (logout) */
-    clearSession(): Promise<void>;
-    /** Persists the current session to storage */
-    persistSession(): Promise<void>;
-    /** Restores a session from storage (called on boot) */
-    restoreSession(): Promise<ICliUserSession | undefined>;
-}
-/**
- * Represents a service that manages users in the CLI
- */
-interface ICliUsersStoreService {
-    /** Gets users with optional filtering and pagination */
-    getUsers(options?: {
-        query?: string;
-        skip?: number;
-        take?: number;
-    }): Observable<ICliUser[]>;
-    /** Creates a new user */
-    createUser(user: CliAddUser): Promise<ICliUser>;
-    /** Gets a user by id, name, or email */
-    getUser(id: string): Observable<ICliUser | undefined>;
-    /** Updates an existing user */
-    updateUser(id: string, updates: CliUpdateUser): Promise<ICliUser>;
-    /** Deletes a user by id */
-    deleteUser(id: string): Promise<void>;
-}
-/**
- * Represents a service that manages groups in the CLI
- */
-interface ICliGroupsStoreService {
-    /** Gets all groups */
-    getGroups(): Observable<ICliGroup[]>;
-    /** Gets a group by id or name */
-    getGroup(id: string): Observable<ICliGroup | undefined>;
-    /** Creates a new group */
-    createGroup(name: string, description?: string): Promise<ICliGroup>;
-    /** Deletes a group by id */
-    deleteGroup(id: string): Promise<void>;
-    /** Gets all users that belong to a group */
-    getGroupMembers(groupId: string): Observable<ICliUser[]>;
-}
-/**
- * Represents a service that handles authentication in the CLI
- */
-interface ICliAuthService {
-    /** Authenticates a user and returns a session */
-    login(username: string, password: string): Promise<ICliUserSession>;
-    /** Ends the current session */
-    logout(): Promise<void>;
-    /** Sets or updates a user's password */
-    setPassword(userId: string, password: string): Promise<void>;
-    /** Verifies a password against stored credentials */
-    verifyPassword(userId: string, password: string): Promise<boolean>;
-    /** Hashes a password with a salt using Web Crypto SHA-256 */
-    hashPassword(password: string, salt: string): Promise<string>;
-}
-
-/**
- * Represents a serialized snapshot of a CLI engine's state.
- * Used to duplicate terminal tabs with full state preservation.
- */
-interface CliEngineSnapshot {
-    /** Schema version for forward compatibility */
-    version: 1;
-    /** Timestamp (ms since epoch) when the snapshot was taken */
-    timestamp: number;
-    /** Serialized terminal state */
-    terminal: {
-        /** Terminal buffer serialized via @xterm/addon-serialize */
-        serializedBuffer: string;
-        /** Terminal column count at time of snapshot */
-        cols: number;
-        /** Terminal row count at time of snapshot */
-        rows: number;
-    };
-    /** Command history entries (most recent last) */
-    commandHistory: string[];
-    /** Named state store entries */
-    stateStores: Array<{
-        name: string;
-        state: Record<string, any>;
-    }>;
-}
-
-/**
- * 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;
-}
-/**
- * Token for the file transfer service.
- */
-declare const ICliFileTransferService_TOKEN = "cli-file-transfer-service";
-/**
- * Abstraction for file transfer operations.
- * Default implementation uses browser-native APIs (file picker, download dialog).
- * @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>;
-}
-
-declare const ICliDragDropService_TOKEN = "cli-drag-drop-service";
-interface ICliDragDropService {
-    /** Emits an array of dropped File objects each time files are dropped onto the terminal */
-    readonly onFileDrop: Observable<File[]>;
-}
-
-interface ICliTerminalWriter {
-    /**
-     * Write text to the terminal
-     * @param text The text to write
-     */
-    write(text: string): void;
-    /**
-     * Write text to the terminal followed by a newline
-     * @param text The text to write
-     */
-    writeln(text?: string): void;
-    /**
-     * Write a success message to the terminal
-     * @param messag The message to write
-     * @returns void
-     */
-    writeSuccess: (message: string) => void;
-    /**
-     * Write an info message to the terminal
-     * @param messag The message to write
-     * @returns void
-     */
-    writeInfo: (message: string) => void;
-    /**
-     * Write an error message to the terminal
-     * @param message The message to write
-     * @returns void
-     */
-    writeError: (message: string) => void;
-    /**
-     * Write a warning message to the terminal
-     * @param message The message to write
-     * @returns void
-     */
-    writeWarning: (message: string) => void;
-    /**
-     * Write a message to the terminal with the specified color
-     * @param message The message to write
-     * @param color The color to use
-     * @returns void
-     */
-    wrapInColor: (text: string, color: CliForegroundColor) => string;
-    /**
-     * Write a message to the terminal with the specified background color
-     * @param message The message to write
-     * @param color The background color to use
-     * @returns void
-     */
-    wrapInBackgroundColor: (text: string, color: CliBackgroundColor) => string;
-    /**
-     * Write a JSON object to the terminal
-     * @param json The JSON object to write
-     * @returns void
-     */
-    writeJson: (json: any) => void;
-    /**
-     * Write content to a file
-     * @param fileName The name of the file to write to
-     * @param content The content to write to the file
-     * @returns void
-     */
-    writeToFile: (fileName: string, content: string) => void;
-    /**
-     * Write an object array as a table to the terminal
-     * @param objects The objects to write to the table
-     * @returns void
-     */
-    writeObjectsAsTable(objects: any[]): void;
-    /**
-     * Write a table to the terminal
-     * @param headers The headers of the table
-     * @param rows The rows of the table
-     * @returns void
-     */
-    writeTable(headers: string[], rows: string[][]): void;
-    /**
-     * Write a divider to the terminal
-     * @param options The options for the divider
-     * @returns void
-     */
-    writeDivider(options?: {
-        color?: CliForegroundColor;
-        length?: number;
-        char?: string;
-    }): void;
-    /**
-     * 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
-     */
-    writeList(items: string[], options?: {
-        ordered?: boolean;
-        prefix?: string;
-        color?: CliForegroundColor;
-    }): 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
-     */
-    writeKeyValue(entries: Record<string, string> | [string, string][], options?: {
-        separator?: string;
-        keyColor?: CliForegroundColor;
-    }): void;
-    /**
-     * Write items in a multi-column layout.
-     * @param items The items to arrange in columns
-     * @param options Optional: number of columns, padding between columns
-     */
-    writeColumns(items: string[], options?: {
-        columns?: number;
-        padding?: number;
-    }): void;
-}
-/**
- * Represents a clipboard for the CLI
- */
-interface ICliClipboard {
+    parameter: ICliCommandParameterDescriptor;
     /**
-     * Write text to the clipboard
-     * @param text The text to write to the clipboard
-     * @returns void
+     * Execution priority — lower values run first.
+     * @default 0
      */
-    write: (text: string) => Promise<void>;
+    priority?: number;
     /**
-     * Read text from the clipboard
-     * @returns The text read from the clipboard
+     * Evaluate and optionally handle the parameter.
+     * @returns `true` to halt command execution, `false` to continue.
      */
-    read: () => Promise<string>;
+    handle(args: Record<string, any>, processor: ICliCommandProcessor, command: CliProcessCommand, context: ICliExecutionContext): boolean | Promise<boolean>;
 }
+
 /**
  * Represents a service that executes commands
  */
 interface ICliCommandExecutorService {
     /**
-     *
-     * @param command
-     * @param context
+     * Display the help output for a command, including its description,
+     * sub-commands, and parameters.
+     * @param command The parsed command to show help for
+     * @param context The execution context
      */
     showHelp(command: CliProcessCommand, context: ICliExecutionContext): Promise<void>;
     /**
@@ -1633,6 +1630,7 @@ interface ICliCommandExecutorService {
      */
     getGlobalParameters(): ICliCommandParameterDescriptor[];
 }
+
 /**
  * Represents a registry for command processors
  */
@@ -1671,6 +1669,50 @@ interface ICliCommandProcessorRegistry {
      */
     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 {
     /**
      * Indicates if the process has exited
@@ -1713,301 +1755,687 @@ interface ICliExecutionProcess {
      */
     output(data: any): void;
 }
+
 /**
- * Represents a tracked CLI process entry
+ * Represents a key-value store for the CLI
  */
-interface ICliProcessEntry {
-    pid: number;
-    command: string;
-    startTime: number;
-    status: 'running' | 'completed' | 'failed' | 'killed';
-    exitCode?: number;
+interface ICliKeyValueStore {
+    /**
+     * 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.
+     */
+    get<T = any>(key: string): Promise<T | undefined>;
+    /**
+     * 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.
+     */
+    set(key: string, value: any): Promise<void>;
+    /**
+     * Removes a key-value pair by key.
+     * @param key - The key to remove.
+     * @returns A promise resolving when the key is removed.
+     */
+    remove(key: string): Promise<void>;
+    /**
+     * Clears all key-value pairs from the store.
+     * @returns A promise resolving when the store is cleared.
+     */
+    clear(): Promise<void>;
 }
 /**
- * Registry for tracking CLI processes
+ * 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 ICliProcessRegistry {
-    /** Register a new process, returns assigned PID */
-    register(command: string): {
-        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 ICliStateStore {
+    /**
+     * Get a snapshot of the current state.
+     * @returns A shallow copy of the state object
+     */
+    getState<T extends CliState = CliState>(): T;
+    /**
+     * Shallow-merge new values into the current state.
+     * Only the provided keys are updated; other keys are preserved.
+     * Triggers subscribers and persists if a storage backend is configured.
+     * @param newState Partial state to merge with the current state
+     */
+    updateState(newState: Partial<CliState>): void;
+    /**
+     * 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.
+     */
+    select<K>(selector: (state: CliState) => K): Observable<K>;
+    /**
+     * Subscribe to state changes.
+     * @param callback Callback function to handle state changes.
+     * @returns Subscription object to manage the subscription.
+     */
+    subscribe(callback: (state: CliState) => void): Subscription;
+    /**
+     * Reset the state to its initial value.
+     */
+    reset(): void;
+    /**
+     * Persist the state to storage.
+     */
+    persist(): Promise<void>;
+    /**
+     * Initialize the state from storage.
+     */
+    initialize(): Promise<void>;
 }
+
 /**
- * Represents a key-value store for the CLI
+ * Represents a service that pings the server
  */
-interface ICliKeyValueStore {
+interface ICliPingServerService {
+    /**
+     * Pings the server
+     */
+    ping(): Promise<void>;
+}
+/**
+ * Represents a module for the web CLI (frontend).
+ *
+ * This interface is for **web/frontend plugins only** — browser-side modules
+ * that extend the CLI terminal UI (e.g. `@qodalis/cli-guid`, `@qodalis/cli-tetris`).
+ *
+ * It is **not** related to backend server processors (Node/Python/.NET).
+ * Backend command processors implement their own `ICliCommandProcessor` interfaces
+ * in their respective server packages and do not use `apiVersion`.
+ */
+interface ICliModule {
+    /**
+     * The web plugin API version this module targets.
+     *
+     * This is a **frontend-only** concept used by the browser CLI runtime
+     * to ensure plugin compatibility. It has no relation to backend server
+     * API versioning (e.g. `/api/v1/qcli/`).
+     *
+     * Modules with `apiVersion` less than the runtime's `API_VERSION` are
+     * rejected with a warning at boot time.
+     *
+     * Use the `API_VERSION` constant exported from `@qodalis/cli-core` to
+     * target the current runtime version.
+     */
+    apiVersion: number;
+    /** Unique module identifier, e.g. '@qodalis/cli-guid' */
+    name: string;
+    /** Semver version string */
+    version?: string;
+    /** Human-readable description */
+    description?: string;
+    /** Module names this module depends on (resolved before this module boots) */
+    dependencies?: string[];
+    /** Boot priority — lower values boot first (default: 0) */
+    priority?: number;
+    /** Command processors provided by this module */
+    processors?: ICliCommandProcessor[];
+    /** Services registered into the shared service container */
+    services?: CliProvider[];
+    /** Module configuration, set via configure() */
+    config?: Record<string, any>;
+    /**
+     * Per-locale translation maps shipped by this module.
+     * Keyed by locale code (e.g. 'es', 'fr'), each value is a flat
+     * key-value map of translation keys to translated strings.
+     *
+     * These are automatically registered with the translation service
+     * during module boot — no manual onInit() code required.
+     *
+     * @example
+     * translations: {
+     *   es: { 'cli.guid.description': 'Generar y validar UUIDs' },
+     *   fr: { 'cli.guid.description': 'Générer et valider des UUIDs' },
+     * }
+     */
+    translations?: Record<string, Record<string, string>>;
+    /**
+     * Returns a configured copy of this module.
+     * Modules should narrow the config type via a module-specific interface.
+     */
+    configure?(config: any): ICliModule;
+    /** Called after services are registered and before processors are initialized */
+    onInit?(context: ICliExecutionContext): Promise<void>;
+    /**
+     * Optional first-run setup flow. Called during boot if the module
+     * has not been set up yet (determined by a persisted flag in the
+     * key-value store). Use context.reader to prompt the user for
+     * initial configuration.
+     *
+     * @returns true to mark setup as complete; false/throw to abort
+     * (module still loads, setup re-triggers next boot).
+     */
+    onSetup?(context: ICliExecutionContext): Promise<boolean>;
+    /** Called after all modules have booted and the terminal is interactive */
+    onAfterBoot?(context: ICliExecutionContext): Promise<void>;
+    /** Called when the module is being torn down */
+    onDestroy?(context: ICliExecutionContext): Promise<void>;
+}
+/**
+ * A module that accepts typed configuration via `configure()`.
+ * Extend this instead of `ICliModule` when your module has a config type.
+ *
+ * @example
+ * ```ts
+ * interface MyModuleConfig { verbose?: boolean }
+ * const myModule: ICliConfigurableModule<MyModuleConfig> = {
+ *     configure(config) { return { ...this, config }; },
+ *     // ...
+ * };
+ * ```
+ */
+interface ICliConfigurableModule<T extends Record<string, any> = Record<string, any>> extends ICliModule {
+    configure(config: T): ICliModule;
+}
+/**
+ * @deprecated Use ICliModule instead
+ */
+type ICliUmdModule = ICliModule;
+/**
+ * Represents a logger for the CLI
+ */
+interface ICliLogger {
+    /**
+     * Set the log level of the logger
+     * @param level The log level to set
+     * @returns void
+     * @default CliLogLevel.ERROR
+     */
+    setCliLogLevel(level: CliLogLevel): void;
+    /**
+     * Log a general message (LOG level)
+     * @param args The arguments to log
+     */
+    log(...args: any[]): void;
+    /**
+     * Log an informational message (INFO level)
+     * @param args The arguments to log
+     */
+    info(...args: any[]): void;
+    /**
+     * Log a warning message (WARN level)
+     * @param args The arguments to log
+     */
+    warn(...args: any[]): void;
+    /**
+     * Log an error message (ERROR level)
+     * @param args The arguments to log
+     */
+    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;
     /**
-     * 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.
+     * Get the current locale code (e.g. 'en', 'es', 'fr').
      */
-    get<T = any>(key: string): Promise<T | undefined>;
+    getLocale(): string;
     /**
-     * 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.
+     * Set the active locale.
+     * @param locale The locale code to switch to
      */
-    set(key: string, value: any): Promise<void>;
+    setLocale(locale: string): void;
     /**
-     * Removes a key-value pair by key.
-     * @param key - The key to remove.
-     * @returns A promise resolving when the key is removed.
+     * 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
      */
-    remove(key: string): Promise<void>;
+    addTranslations(locale: string, translations: Record<string, string>): void;
     /**
-     * Clears all key-value pairs from the store.
-     * @returns A promise resolving when the store is cleared.
+     * Get all locale codes that have at least one registered translation.
      */
-    clear(): Promise<void>;
+    getAvailableLocales(): string[];
 }
 /**
- * Represents a store for storing data associated with commands
+ * Dependency injection container for CLI services.
+ * Services are registered with string tokens and retrieved by type.
  */
-interface ICliStateStore {
+interface ICliServiceProvider {
     /**
-     * Get the current state as an object.
+     * 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
      */
-    getState<T extends CliState = CliState>(): T;
+    get<T = unknown>(service: any): T;
     /**
-     * Update the state with new values. Supports partial updates.
-     * @param newState Partial state to merge with the current state.
+     * Register one or more service definitions.
+     * @param definition A single provider or an array of providers to register
      */
-    updateState(newState: Partial<CliState>): void;
+    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 {
     /**
-     * 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.
+     * 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.
      */
-    select<K>(selector: (state: CliState) => K): Observable<K>;
+    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[];
+}
+/**
+ * Provides tab-completion candidates for CLI input.
+ * Plugins can register providers to extend completion (e.g. file paths, custom values).
+ */
+interface ICliCompletionProvider {
     /**
-     * Subscribe to state changes.
-     * @param callback Callback function to handle state changes.
-     * @returns Subscription object to manage the subscription.
+     * 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.
      */
-    subscribe(callback: (state: CliState) => void): Subscription;
+    priority: number;
     /**
-     * Reset the state to its initial value.
+     * Return completion candidates for the current input context.
+     * Return an empty array if this provider does not apply.
      */
-    reset(): void;
+    getCompletions(context: ICliCompletionContext): string[] | Promise<string[]>;
+}
+
+interface ICliProgressBar {
     /**
-     * Persist the state to storage.
+     * Indicates if the progress bar is running
      */
-    persist(): Promise<void>;
+    isRunning: boolean;
     /**
-     * Initialize the state from storage.
+     * Show the progress bar
      */
-    initialize(): Promise<void>;
+    show: (text?: string) => void;
+    /**
+     * Hide the progress bar
+     */
+    hide: () => void;
 }
 /**
- * Represents a service that pings the server
+ * Represents a spinner for the CLI
  */
-interface ICliPingServerService {
+interface ICliSpinner extends ICliProgressBar {
     /**
-     * Pings the server
+     * Set the text of the spinner
+     * @param text The text to set
      */
-    ping(): Promise<void>;
+    setText: (text: string) => void;
 }
+type CliPercentageProgressBarUpdateValueOptions = {
+    /**
+     * The type of update to perform
+     * @default 'replace'
+     */
+    type?: 'replace' | 'increment';
+};
 /**
- * Represents a module for the CLI
+ * Represents a progress bar for the CLI
  */
-interface ICliModule {
+interface ICliPercentageProgressBar extends ICliProgressBar {
     /**
-     * API version this module targets.
-     * Modules with apiVersion < 2 (or missing) are rejected by v2 runtimes.
+     * 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')
      */
-    apiVersion: number;
-    /** Unique module identifier, e.g. '@qodalis/cli-guid' */
-    name: string;
-    /** Semver version string */
-    version?: string;
-    /** Human-readable description */
-    description?: string;
-    /** Module names this module depends on (resolved before this module boots) */
-    dependencies?: string[];
-    /** Boot priority — lower values boot first (default: 0) */
-    priority?: number;
-    /** Command processors provided by this module */
-    processors?: ICliCommandProcessor[];
-    /** Services registered into the shared service container */
-    services?: CliProvider[];
-    /** Module configuration, set via configure() */
-    config?: Record<string, any>;
+    update: (progress: number, options?: CliPercentageProgressBarUpdateValueOptions) => void;
     /**
-     * Per-locale translation maps shipped by this module.
-     * Keyed by locale code (e.g. 'es', 'fr'), each value is a flat
-     * key-value map of translation keys to translated strings.
-     *
-     * These are automatically registered with the translation service
-     * during module boot — no manual onInit() code required.
-     *
-     * @example
-     * translations: {
-     *   es: { 'cli.guid.description': 'Generar y validar UUIDs' },
-     *   fr: { 'cli.guid.description': 'Générer et valider des UUIDs' },
-     * }
+     * Complete the progress bar
+     * @returns void
      */
-    translations?: Record<string, Record<string, string>>;
+    complete: () => void;
     /**
-     * Returns a configured copy of this module.
-     * Modules should narrow the config type via a module-specific interface.
+     * Set the text of the spinner
+     * @param text The text to set
      */
-    configure?(config: any): ICliModule;
-    /** Called after services are registered and before processors are initialized */
-    onInit?(context: ICliExecutionContext): Promise<void>;
+    setText: (text: string) => void;
+}
+type CliTextAnimatorOptions = {
     /**
-     * Optional first-run setup flow. Called during boot if the module
-     * has not been set up yet (determined by a persisted flag in the
-     * key-value store). Use context.reader to prompt the user for
-     * initial configuration.
-     *
-     * @returns true to mark setup as complete; false/throw to abort
-     * (module still loads, setup re-triggers next boot).
+     * The speed of the animation
+     * @default 100
      */
-    onSetup?(context: ICliExecutionContext): Promise<boolean>;
-    /** Called after all modules have booted and the terminal is interactive */
-    onAfterBoot?(context: ICliExecutionContext): Promise<void>;
-    /** Called when the module is being torn down */
-    onDestroy?(context: ICliExecutionContext): Promise<void>;
+    speed?: number;
+    /**
+     * The text will be removed after typing
+     */
+    removeAfterTyping?: boolean;
+};
+interface ICliTextAnimator extends ICliProgressBar {
+    /**
+     * Show animated text in a typing and erasing effect.
+     * @param text The text to animate
+     * @param options Optional: speed (ms per character), removeAfterTyping
+     * @returns A promise that resolves when the animation completes
+     */
+    showText: (text: string, options?: CliTextAnimatorOptions) => Promise<void>;
+}
+
+/**
+ * Represents a service that manages user sessions in the CLI
+ */
+interface ICliUserSessionService {
+    /** Gets the current user session as a reactive stream */
+    getUserSession(): Observable<ICliUserSession | undefined>;
+    /** Sets the current user session */
+    setUserSession(session: ICliUserSession): Promise<void>;
+    /** Clears the current session (logout) */
+    clearSession(): Promise<void>;
+    /** Persists the current session to storage */
+    persistSession(): Promise<void>;
+    /** Restores a session from storage (called on boot) */
+    restoreSession(): Promise<ICliUserSession | undefined>;
+}
+/**
+ * Represents a service that manages users in the CLI
+ */
+interface ICliUsersStoreService {
+    /** Gets users with optional filtering and pagination */
+    getUsers(options?: {
+        query?: string;
+        skip?: number;
+        take?: number;
+    }): Observable<ICliUser[]>;
+    /** Creates a new user */
+    createUser(user: CliAddUser): Promise<ICliUser>;
+    /** Gets a user by id, name, or email */
+    getUser(id: string): Observable<ICliUser | undefined>;
+    /** Updates an existing user */
+    updateUser(id: string, updates: CliUpdateUser): Promise<ICliUser>;
+    /** Deletes a user by id */
+    deleteUser(id: string): Promise<void>;
+}
+/**
+ * Represents a service that manages groups in the CLI
+ */
+interface ICliGroupsStoreService {
+    /** Gets all groups */
+    getGroups(): Observable<ICliGroup[]>;
+    /** Gets a group by id or name */
+    getGroup(id: string): Observable<ICliGroup | undefined>;
+    /** Creates a new group */
+    createGroup(name: string, description?: string): Promise<ICliGroup>;
+    /** Deletes a group by id */
+    deleteGroup(id: string): Promise<void>;
+    /** Gets all users that belong to a group */
+    getGroupMembers(groupId: string): Observable<ICliUser[]>;
+}
+/**
+ * Represents a service that handles authentication in the CLI
+ */
+interface ICliAuthService {
+    /** Authenticates a user and returns a session */
+    login(username: string, password: string): Promise<ICliUserSession>;
+    /** Ends the current session */
+    logout(): Promise<void>;
+    /** Sets or updates a user's password */
+    setPassword(userId: string, password: string): Promise<void>;
+    /** Verifies a password against stored credentials */
+    verifyPassword(userId: string, password: string): Promise<boolean>;
+    /** Hashes a password with a salt using Web Crypto SHA-256 */
+    hashPassword(password: string, salt: string): Promise<string>;
 }
+
 /**
- * @deprecated Use ICliModule instead
+ * Represents a serialized snapshot of a CLI engine's state.
+ * Used to duplicate terminal tabs with full state preservation.
  */
-type ICliUmdModule = ICliModule;
+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>;
+    }>;
+}
+
 /**
- * Represents a logger for the CLI
+ * Messages sent from the main thread to a background service Worker.
  */
-interface ICliLogger {
-    /**
-     * Set the log level of the logger
-     * @param level The log level to set
-     * @returns void
-     * @default CliLogLevel.ERROR
-     */
-    setCliLogLevel(level: CliLogLevel): void;
-    /**
-     * Log a message
-     * @param args The arguments to log
-     */
-    log(...args: any[]): void;
-    /**
-     * Log a message
-     * @param args The arguments to log
-     */
-    info(...args: any[]): void;
-    /**
-     * Log a message
-     * @param args The arguments to log
-     */
-    warn(...args: any[]): void;
-    /**
-     * Log a message
-     * @param args The arguments to log
-     */
-    error(...args: any[]): void;
-    /**
-     * Log a message
-     * @param args The arguments to log
-     */
-    debug(...args: any[]): void;
-}
-declare const ICliTranslationService_TOKEN = "cli-translation-service";
+type CliWorkerInboundMessage = {
+    type: 'start';
+    config?: Record<string, unknown>;
+} | {
+    type: 'stop';
+} | {
+    type: 'abort';
+};
 /**
- * Provides internationalization (i18n) support for CLI strings.
+ * Messages sent from a background service Worker to the main thread.
  */
-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[];
+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;
 }
+
 /**
- * Represents a service provider for the CLI
+ * 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 ICliServiceProvider {
-    /**
-     * Get a service
-     * @param service The service to get
-     */
-    get<T>(service: any): T;
-    /**
-     * Set a service
-     * @param definition The definition of the service
-     */
-    set(definition: CliProvider | CliProvider[]): void;
+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>;
 }
 
-declare const ICliPermissionService_TOKEN = "cli-permission-service";
+interface ICliDragDropService {
+    /** Emits an array of dropped File objects each time files are dropped onto the terminal */
+    readonly onFileDrop: Observable<File[]>;
+}
 
 /**
- * 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.
+ * 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.
  */
-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;
+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>;
+}
+
+/**
+ * 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;
 }
 
 /**
- * Registry that tracks loaded CLI modules and dispatches boot handlers
- * when new modules are registered (including dynamically via UMD).
+ * Registry that tracks loaded web CLI modules (frontend plugins) and dispatches
+ * boot handlers when new modules are registered (including dynamically via UMD).
+ *
+ * This registry is for **browser-side web plugins only**. Backend server
+ * processors (Node/Python/.NET) have their own registries and do not use
+ * this class or the `apiVersion` gating mechanism.
  */
 declare class CliModuleRegistry {
     private readonly modules;
     private readonly bootHandlers;
+    /** Optional warning callback — set by the engine to route through ICliLogger */
+    onWarn?: (message: string) => void;
     /**
      * Register a handler that is called whenever a new module is registered.
      */
     onModuleBoot(handler: (module: ICliModule) => Promise<void>): void;
     /**
-     * Register a module and notify all boot handlers.
-     * Modules that do not meet the required API version are silently skipped.
+     * Register a web plugin module and notify all boot handlers.
+     * Modules whose `apiVersion` is below the runtime's `API_VERSION` are
+     * skipped with a warning — this ensures only compatible frontend plugins load.
      */
     register(module: ICliModule): Promise<void>;
     /**
@@ -2071,6 +2499,17 @@ declare const CLI_CONFIGURE_STORE_NAME = "configure";
  * @returns The configured value or the default
  */
 declare function getConfigValue<T = any>(state: ICliStateStore, category: string, key: string, defaultValue: T): T;
+/**
+ * Retrieves a plugin configuration value from the execution context.
+ * This is a convenience wrapper for plugins — handles store lookup internally.
+ *
+ * @param context The execution context
+ * @param category The category (usually the processor's command name)
+ * @param key The configuration key
+ * @param defaultValue Fallback value if not configured
+ * @returns The configured value or the default
+ */
+declare function getPluginConfigValue<T = any>(context: ICliExecutionContext, category: string, key: string, defaultValue: T): T;
 /**
  * Resolves all configuration options from registered processors,
  * grouped by category.
@@ -2080,6 +2519,10 @@ declare function resolveConfigurationCategories(registry: ICliCommandProcessorRe
     options: ICliConfigurationOption[];
 }>;
 
+/**
+ * Returns a promise that resolves after the given number of milliseconds.
+ * @param ms Delay duration in milliseconds
+ */
 declare const delay: (ms: number) => Promise<void>;
 
 /**
@@ -2117,10 +2560,10 @@ interface ServerVersionInfo {
  * Negotiates the API version between a frontend CLI client and a backend server.
  *
  * Flow:
- * 1. Client calls `discover(baseUrl)` which hits `GET /api/cli/versions`
+ * 1. Client calls `discover(baseUrl)` which hits `GET ${VERSIONS_ENDPOINT}`
  * 2. Server returns supported versions
  * 3. Client picks the highest mutually supported version
- * 4. All subsequent calls use `/api/v{n}/cli/*`
+ * 4. All subsequent calls use `/api/v{n}/qcli/*`
  */
 declare class ServerVersionNegotiator {
     private static readonly CLIENT_SUPPORTED_VERSIONS;
@@ -2173,18 +2616,73 @@ declare function savePanelPosition(position: CliPanelPosition): void;
  */
 declare function nextPanelPosition(current: CliPanelPosition): CliPanelPosition;
 
-declare const getParameterValue: (p: ICliCommandParameterDescriptor, args: Record<string, any>) => any | undefined;
+/**
+ * Strip all ANSI escape sequences from a string.
+ * @param text The text potentially containing ANSI codes
+ * @returns The text with all ANSI codes removed
+ */
+declare function stripAnsi(text: string): string;
+/**
+ * Return the visible length of a string, ignoring ANSI escape codes.
+ * Useful for padding/alignment calculations in terminal output.
+ * @param text The text potentially containing ANSI codes
+ * @returns The number of visible characters
+ */
+declare function visibleLength(text: string): number;
+
+/**
+ * Retrieve a parameter's value from the parsed arguments, checking aliases.
+ * @param p The parameter descriptor
+ * @param args The parsed command arguments
+ * @returns The matched value, or `undefined` if not found
+ */
+declare const getParameterValue: (p: ICliCommandParameterDescriptor, args: Record<string, any>) => unknown;
+/**
+ * Pretty-print a JSON value with ANSI color highlighting.
+ * @param json The value to format
+ * @returns A colorized, indented string suitable for terminal output
+ */
 declare const formatJson: (json: any) => string;
-declare const colorizeJson: (jsonString: any) => string;
+/**
+ * Apply ANSI color codes to a JSON string using token-based scanning.
+ * Handles keys, strings, numbers, booleans, null, and structural characters.
+ * @param jsonString The raw JSON string to colorize
+ * @returns The colorized string
+ */
+declare const colorizeJson: (jsonString: string) => string;
+/**
+ * Convert a key-value object to a URL query string. Arrays produce repeated keys.
+ * @param params The parameters to encode
+ * @returns The encoded query string (without leading `?`)
+ */
 declare const toQueryString: (params: Record<string, any>) => string;
+/**
+ * Highlight regex matches in text using an ANSI background color.
+ * @param text The source text
+ * @param pattern The regex pattern to highlight
+ * @param bgColor The background color to apply (default: Yellow)
+ * @returns The text with matching segments wrapped in ANSI background color codes
+ */
 declare const highlightTextWithBg: (text: string, pattern: RegExp, bgColor?: CliBackgroundColor) => string;
+/**
+ * Extract the substring to the right of a given word in a command string.
+ * @param command The full command string
+ * @param word The word to search for
+ * @returns The trimmed text after the word, or `undefined` if not found
+ */
 declare const getRightOfWord: (command: string, word: string) => string | undefined;
+/**
+ * Apply a color function to the first word of a text string, preserving leading whitespace.
+ * @param text The text to process
+ * @param colorFunction A function that wraps a word in ANSI color codes
+ * @returns The text with only the first word colorized
+ */
 declare const colorFirstWord: (text: string, colorFunction: (word: string) => string) => string;
 
 declare const utils: {
-    getParameterValue: (p: ICliCommandParameterDescriptor, args: Record<string, any>) => any | undefined;
+    getParameterValue: (p: ICliCommandParameterDescriptor, args: Record<string, any>) => unknown;
     formatJson: (json: any) => string;
-    colorizeJson: (jsonString: any) => string;
+    colorizeJson: (jsonString: string) => string;
     toQueryString: (params: Record<string, any>) => string;
     highlightTextWithBg: (text: string, pattern: RegExp, bgColor?: CliBackgroundColor) => string;
     getRightOfWord: (command: string, word: string) => string | undefined;
@@ -2192,6 +2690,7 @@ declare const utils: {
     ObjectDescriber: typeof ObjectDescriber;
     delay: (ms: number) => Promise<void>;
     getConfigValue: typeof getConfigValue;
+    getPluginConfigValue: typeof getPluginConfigValue;
     resolveConfigurationCategories: typeof resolveConfigurationCategories;
     CLI_CONFIGURE_STORE_NAME: string;
 };
@@ -2201,23 +2700,41 @@ declare const constants: {
     DefaultLibraryAuthor: ICliCommandAuthor;
 };
 
+/** Error message used when a `CancellablePromise` is cancelled. */
+declare const CANCELLATION_ERROR_MESSAGE = "Promise cancelled";
+/**
+ * A promise wrapper that supports cooperative cancellation.
+ *
+ * Create with an executor (like `new Promise`), then call `execute()` to run.
+ * Call `cancel()` to reject with a cancellation error and prevent further
+ * resolve/reject callbacks from firing.
+ *
+ * @example
+ * ```ts
+ * const cp = new CancellablePromise<string>((resolve) => {
+ *     setTimeout(() => resolve('done'), 5000);
+ * });
+ * cp.execute().catch(e => console.log(e.message)); // 'Promise cancelled'
+ * cp.cancel();
+ * ```
+ */
 declare class CancellablePromise<T> {
     private executor;
     private hasCancelled;
     private abortController;
     constructor(executor: (resolve: (value: T) => void, reject: (reason?: any) => void) => void);
+    /**
+     * Run the executor and return a promise for its result.
+     * If `cancel()` has been called, the promise rejects immediately.
+     */
     execute(): Promise<T>;
+    /**
+     * Cancel the promise. The executing promise rejects with
+     * `Error('Promise cancelled')` and subsequent resolve/reject calls are ignored.
+     */
     cancel(): void;
 }
 
-type CliThemeCategory = 'dark' | 'light';
-interface CliThemeInfo {
-    theme: ITheme;
-    category: CliThemeCategory;
-    tags: string[];
-    description: string;
-}
-
 type CliTheme = ITheme;
 type DefaultThemesType = {
     default: CliTheme;
@@ -2252,34 +2769,22 @@ type DefaultThemesType = {
     yellow: CliTheme;
     [key: string]: CliTheme;
 };
+
 declare const DefaultThemes: DefaultThemesType;
 
+type CliThemeCategory = 'dark' | 'light';
+interface CliThemeInfo {
+    theme: ITheme;
+    category: CliThemeCategory;
+    tags: string[];
+    description: string;
+}
+
 declare const DefaultThemeInfos: Record<string, CliThemeInfo>;
 
-declare const LIBRARY_VERSION = "2.0.0-beta.1";
+declare const LIBRARY_VERSION = "2.0.0-beta.11";
 declare const API_VERSION = 2;
 
-/**
- * Framework-agnostic token for the CLI user session service.
- * Used as a key in the service provider to retrieve the user session service.
- */
-declare const ICliUserSessionService_TOKEN = "cli-user-session-service";
-/**
- * Framework-agnostic token for the CLI users store service.
- * Used as a key in the service provider to retrieve the users store service.
- */
-declare const ICliUsersStoreService_TOKEN = "cli-users-store-service";
-/**
- * Framework-agnostic token for the CLI groups store service.
- * Used as a key in the service provider to retrieve the groups store service.
- */
-declare const ICliGroupsStoreService_TOKEN = "cli-groups-store-service";
-/**
- * Framework-agnostic token for the CLI auth service.
- * Used as a key in the service provider to retrieve the auth service.
- */
-declare const ICliAuthService_TOKEN = "cli-auth-service";
-
 /**
  * Context provided to worker service handlers inside a Web Worker.
  */
@@ -2287,7 +2792,7 @@ interface WorkerServiceContext {
     /** Emit an event to the main thread */
     emit(event: Omit<ICliServiceEvent, 'timestamp'>): void;
     /** Log a message (forwarded to the main-thread log buffer) */
-    log(message: string, level?: 'info' | 'warn' | 'error'): void;
+    log(message: string, level?: CliServiceLogLevel): void;
     /** Update state on the main thread */
     updateState(patch: Record<string, unknown>): void;
     /** Create an interval that is auto-cleared on stop */
@@ -2306,10 +2811,29 @@ declare function createWorkerService(handlers: {
     onStop?(): Promise<void>;
 }): void;
 
+/**
+ * Browser-based file transfer service using native browser APIs.
+ *
+ * This is the default implementation when no virtual filesystem is available.
+ * `readFile` and `uploadFromBrowser` open a file picker dialog.
+ * `writeFile` and `downloadToBrowser` trigger a browser download.
+ *
+ * **Limitations:** `listFiles()` and `exists()` are not supported in the
+ * browser environment and always return empty/false respectively.
+ * Use `@qodalis/cli-files` for full filesystem capabilities.
+ */
 declare class BrowserFileTransferService implements ICliFileTransferService {
     readFile(_path: string): Promise<string | null>;
     writeFile(path: string, content: string): Promise<void>;
+    /**
+     * Not supported in browser — always returns an empty array.
+     * Use `@qodalis/cli-files` for directory listing.
+     */
     listFiles(_path: string): Promise<ICliFileEntry[]>;
+    /**
+     * Not supported in browser — always returns `false`.
+     * Use `@qodalis/cli-files` for file existence checks.
+     */
     exists(_path: string): Promise<boolean>;
     downloadToBrowser(filename: string, content: string | Blob): void;
     uploadFromBrowser(accept?: string): Promise<{
@@ -2319,4 +2843,4 @@ declare class BrowserFileTransferService implements ICliFileTransferService {
     private _pickFile;
 }
 
-export { API_VERSION, BrowserFileTransferService, CLI_CONFIGURE_STORE_NAME, CancellablePromise, type CliAddUser, CliBackgroundColor, type CliBackgroundServiceStatus, type CliBackgroundServiceType, type CliEngineSnapshot, type CliFactoryProvider, CliForegroundColor, CliIcon, CliLogLevel, CliModuleRegistry, type CliMultiSelectOption, type CliOptions, type CliPackageSource, type CliPanelConfig, type CliPanelHideAlignment, type CliPanelPosition, type CliPercentageProgressBarUpdateValueOptions, type CliProcessCommand, type CliProcessorMetadata, type CliProvider, type CliSelectOption, type CliServerCapabilities, type CliServerCommandDescriptor, type CliServerConfig, type CliServerOutput, type CliServerResponse, type CliServiceEventHandler, type CliServiceExecutionMode, type CliState, type CliStateConfiguration, type CliTextAnimatorOptions, type CliTheme, type CliThemeCategory, type CliThemeInfo, type CliTypeProvider, type CliUpdateUser, type CliValueProvider, type CliWorkerInboundMessage, type CliWorkerOutboundMessage, DEFAULT_DIR_PERMISSIONS, DEFAULT_FILE_PERMISSIONS, DefaultLibraryAuthor, DefaultThemeInfos, DefaultThemes, type ICliAuthService, ICliAuthService_TOKEN, type ICliBackgroundService, type ICliBackgroundServiceInfo, type ICliBackgroundServiceRegistry, type ICliClipboard, type ICliCommandAuthor, type ICliCommandChildProcessor, type ICliCommandExecutorService, type ICliCommandParameterDescriptor, type ICliCommandProcessor, type ICliCommandProcessorRegistry, type ICliCompletionContext, type ICliCompletionProvider, ICliCompletionProvider_TOKEN, type ICliConfigurationOption, type ICliDragDropService, ICliDragDropService_TOKEN, type ICliExecutionContext, type ICliExecutionProcess, type ICliFileEntry, type ICliFileTransferService, ICliFileTransferService_TOKEN, type ICliGlobalParameterHandler, type ICliGroup, type ICliGroupsStoreService, ICliGroupsStoreService_TOKEN, type ICliInputReader, type ICliKeyValueStore, type ICliLogger, type ICliManagedInterval, type ICliManagedTimer, type ICliModule, type ICliOwnership, type ICliPercentageProgressBar, type ICliPermissionService, ICliPermissionService_TOKEN, type ICliPingServerService, type ICliProcessEntry, type 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, LIBRARY_VERSION, ObjectDescriber, type Package, type ServerVersionInfo, ServerVersionNegotiator, type WorkerServiceContext, bootCliModule, bootUmdModule, clearTerminalLine, colorFirstWord, colorizeJson, compareVersions, constants, createWorkerService, delay, derivePanelThemeStyles, enums, formatJson, getConfigValue, getParameterValue, getRightOfWord, highlightTextWithBg, initializeBrowserEnvironment, loadPanelPosition, nextPanelPosition, resolveConfigurationCategories, satisfiesMinVersion, satisfiesVersionRange, savePanelPosition, toQueryString, utils };
+export { API_VERSION, BrowserFileTransferService, CANCELLATION_ERROR_MESSAGE, CLI_CONFIGURE_STORE_NAME, CancellablePromise, type CliAddUser, CliBackgroundColor, type CliBackgroundServiceStatus, type CliBackgroundServiceType, type CliDateOptions, type CliEngineSnapshot, type CliFactoryProvider, type CliFilePickerOptions, type CliFileResult, CliForegroundColor, 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 };