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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qodalis/cli-core",
-  "version": "2.0.0-beta.7",
+  "version": "2.0.0-beta.8",
   "description": "Core interfaces, types, and utilities for the @qodalis CLI ecosystem.",
   "author": "Nicolae Lupei, Qodalis Solutions",
   "license": "MIT",

package/public-api.d.mts

@@ -546,13 +546,82 @@ declare const enums: {
 };
 
 /**
- * Represents an option for the readSelect prompt.
+ * 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.
@@ -561,59 +630,114 @@ 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 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 {
     /**
-     * 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
+     * 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): Promise<string | null>;
+    readLine(prompt: string, options?: CliLineOptions): Promise<string | null>;
     /**
-     * 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
+     * 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>;
     /**
-     * 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
+     * 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>;
     /**
-     * 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
+     * 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[], onChange?: (value: string) => void): Promise<string | null>;
+    readSelect(prompt: string, options: CliSelectOption[], selectOptions?: CliSelectOptions): Promise<string | null>;
     /**
-     * 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
+     * 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[], onChange?: (value: string) => void): Promise<string | null>;
+    readSelectInline(prompt: string, options: CliSelectOption[], selectOptions?: CliSelectOptions): Promise<string | null>;
     /**
-     * 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
+     * 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[]): Promise<string[] | null>;
+    readMultiSelect(prompt: string, options: CliMultiSelectOption[], selectOptions?: CliMultiSelectOptions): Promise<string[] | null>;
     /**
-     * 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
+     * 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?: {
@@ -621,6 +745,20 @@ interface ICliInputReader {
         max?: number;
         default?: number;
     }): 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>;
 }
 
 /**
@@ -707,6 +845,8 @@ interface ICliBackgroundService {
  * 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;
@@ -1474,6 +1614,24 @@ interface ICliDragDropService {
     readonly onFileDrop: Observable<File[]>;
 }
 
+type LineState = number;
+interface ISyntaxHighlightRule {
+    pattern: RegExp;
+    tokenType: string;
+    captureGroup?: number;
+}
+interface ISyntaxHighlighter {
+    id: string;
+    extensions: string[];
+    initialState: LineState;
+    getRules(state: LineState): ISyntaxHighlightRule[];
+    getNextLineState(line: string, currentState: LineState): LineState;
+}
+interface ISyntaxTheme {
+    name: string;
+    colors: Record<string, string>;
+}
+
 interface ICliTerminalWriter {
     /**
      * Write text to the terminal
@@ -1718,17 +1876,30 @@ interface ICliExecutionProcess {
  */
 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): {
+    register(command: string, options?: ICliProcessRegisterOptions): {
         pid: number;
         abortController: AbortController;
     };
@@ -2256,7 +2427,7 @@ declare const DefaultThemes: DefaultThemesType;
 
 declare const DefaultThemeInfos: Record<string, CliThemeInfo>;
 
-declare const LIBRARY_VERSION = "2.0.0-beta.7";
+declare const LIBRARY_VERSION = "2.0.0-beta.8";
 declare const API_VERSION = 2;
 
 /**
@@ -2319,4 +2490,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, CLI_CONFIGURE_STORE_NAME, CancellablePromise, type CliAddUser, CliBackgroundColor, type CliBackgroundServiceStatus, type CliBackgroundServiceType, type CliDateOptions, type CliEngineSnapshot, type CliFactoryProvider, type CliFilePickerOptions, type CliFileResult, CliForegroundColor, CliIcon, type CliLineOptions, CliLogLevel, CliModuleRegistry, type CliMultiSelectOption, type CliMultiSelectOptions, type CliOptions, type CliPackageSource, type CliPanelConfig, type CliPanelHideAlignment, type CliPanelPosition, type CliPercentageProgressBarUpdateValueOptions, type CliProcessCommand, type CliProcessorMetadata, type CliProvider, type CliSelectOption, type CliSelectOptions, type CliServerCapabilities, type CliServerCommandDescriptor, type CliServerConfig, type CliServerOutput, type CliServerResponse, type CliServiceEventHandler, type CliServiceExecutionMode, type CliState, type CliStateConfiguration, type CliTextAnimatorOptions, type CliTheme, type CliThemeCategory, type CliThemeInfo, type CliTypeProvider, type CliUpdateUser, type CliValueProvider, type CliWorkerInboundMessage, type CliWorkerOutboundMessage, DEFAULT_DIR_PERMISSIONS, DEFAULT_FILE_PERMISSIONS, DefaultLibraryAuthor, DefaultThemeInfos, DefaultThemes, type ICliAuthService, ICliAuthService_TOKEN, type ICliBackgroundService, type ICliBackgroundServiceInfo, type ICliBackgroundServiceRegistry, type ICliClipboard, type ICliCommandAuthor, type ICliCommandChildProcessor, type ICliCommandExecutorService, type ICliCommandParameterDescriptor, type ICliCommandProcessor, type ICliCommandProcessorRegistry, type ICliCompletionContext, type ICliCompletionProvider, ICliCompletionProvider_TOKEN, type ICliConfigurationOption, type ICliDragDropService, ICliDragDropService_TOKEN, type ICliExecutionContext, type ICliExecutionProcess, type ICliFileEntry, type ICliFilePickerProvider, type ICliFileTransferService, ICliFileTransferService_TOKEN, type ICliGlobalParameterHandler, type ICliGroup, type ICliGroupsStoreService, ICliGroupsStoreService_TOKEN, type ICliInputReader, type ICliKeyValueStore, type ICliLogger, type ICliManagedInterval, type ICliManagedTimer, type ICliModule, type ICliOwnership, type ICliPercentageProgressBar, type ICliPermissionService, ICliPermissionService_TOKEN, type ICliPingServerService, type ICliProcessEntry, type ICliProcessRegisterOptions, type ICliProcessRegistry, type ICliProcessorHook, type ICliProgressBar, type ICliServiceContext, type ICliServiceEvent, type ICliServiceLogEntry, type ICliServiceProvider, type ICliSpinner, type ICliStateStore, type ICliTerminalWriter, type ICliTextAnimator, type ICliTranslationService, ICliTranslationService_TOKEN, type ICliUmdModule, type ICliUser, type ICliUserCredentials, type ICliUserSession, type ICliUserSessionService, ICliUserSessionService_TOKEN, type ICliUsersStoreService, ICliUsersStoreService_TOKEN, type ISyntaxHighlightRule, type ISyntaxHighlighter, type ISyntaxTheme, LIBRARY_VERSION, type LineState, ObjectDescriber, type Package, type ServerVersionInfo, ServerVersionNegotiator, type WorkerServiceContext, bootCliModule, bootUmdModule, clearTerminalLine, colorFirstWord, colorizeJson, compareVersions, constants, createWorkerService, delay, derivePanelThemeStyles, enums, formatJson, getConfigValue, getParameterValue, getRightOfWord, highlightTextWithBg, initializeBrowserEnvironment, loadPanelPosition, nextPanelPosition, resolveConfigurationCategories, satisfiesMinVersion, satisfiesVersionRange, savePanelPosition, toQueryString, utils };