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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/public-api.d.mts CHANGED
@@ -106,7 +106,10 @@ type CliProcessCommand = {
106
106
  */
107
107
  command: string;
108
108
  /**
109
- * The data that was entered
109
+ * Pipeline data passed from the previous command in a pipe chain.
110
+ * When commands are piped (e.g. `cmd1 | cmd2`), the output of `cmd1`
111
+ * is captured and passed here as input to `cmd2`. The shape depends
112
+ * on what the upstream command produced (string, JSON object, array, etc.).
110
113
  */
111
114
  data?: any;
112
115
  /**
@@ -216,7 +219,7 @@ declare enum CliIcon {
216
219
  Server = "\uD83D\uDDA5",// Server or host
217
220
  Cloud = "\u2601",// Cloud or remote
218
221
  Network = "\uD83C\uDF10",// Network or connection
219
- Monitor = "\uD83D\uDDA5",// Monitor or display
222
+ Monitor = "\uD83D\uDCFA",// Monitor or display
220
223
  Printer = "\uD83D\uDDA8",// Printer or output
221
224
  USB = "\uD83D\uDD0C",// USB or connection
222
225
  Speaker = "\uD83D\uDD0A",// Speaker or audio
@@ -226,14 +229,14 @@ declare enum CliIcon {
226
229
  Music = "\uD83C\uDFB5",// Music or audio
227
230
  Phone = "\uD83D\uDCDE",// Phone or communication
228
231
  Package = "\uD83D\uDCE6",// Package or bundle
229
- Plugin = "\uD83D\uDD0C",// Plugin or extension
230
- Extension = "\uD83E\uDDE9",// Extension or component
231
- Module = "\uD83D\uDCE6",// Module or package
232
+ Plugin = "\uD83E\uDDE9",// Plugin or extension
233
+ Extension = "\uD83D\uDD0C",// Extension or connection
234
+ Module = "\uD83E\uDDF1",// Module or package
232
235
  Evaluate = "\uD83D\uDD0D",// Evaluate or search
233
- Variable = "\uD83D\uDD27",// Variable or setting
236
+ Variable = "\uD835\uDC65",// Variable or setting
234
237
  Script = "\uD83D\uDCDC",// Script or code
235
- Code = "\uD83D\uDCBE",// Code or file
236
- Logs = "\uD83D\uDCDC",// Logs or history
238
+ Code = "\uD83D\uDCDD",// Code or file
239
+ Logs = "\uD83D\uDCCB",// Logs or history
237
240
  Power = "\u23FB",// On/Off state
238
241
  Heart = "\u2764",// Love or favorite
239
242
  Flame = "\uD83D\uDD25",// Trending or hot
@@ -314,6 +317,14 @@ type CliOptions = Record<string, any> & {
314
317
  * Commands from each server are discovered and registered as proxy processors.
315
318
  */
316
319
  servers?: CliServerConfig[];
320
+ /**
321
+ * Whether the `eval` / `js` / `calc` command is enabled.
322
+ * Disabled by default because it runs arbitrary JavaScript via `eval()`
323
+ * in the host page context — a security risk in multi-tenant or
324
+ * user-facing deployments.
325
+ * @default false
326
+ */
327
+ allowEval?: boolean;
317
328
  };
318
329
  /**
319
330
  * Configuration for a remote CLI server
@@ -482,10 +493,17 @@ declare enum CliLogLevel {
482
493
  type CliState = Record<string, any>;
483
494
  /**
484
495
  * Position of the CLI panel relative to the viewport edge.
496
+ * - `'bottom'` — anchored to the bottom (default)
497
+ * - `'top'` — anchored to the top
498
+ * - `'left'` — anchored to the left (vertical layout)
499
+ * - `'right'` — anchored to the right (vertical layout)
485
500
  */
486
501
  type CliPanelPosition = 'bottom' | 'top' | 'left' | 'right';
487
502
  /**
488
503
  * Alignment of the hidden-mode tab along its viewport edge.
504
+ * - `'start'` — left for horizontal panels, top for vertical panels
505
+ * - `'center'` — centered along the edge (default)
506
+ * - `'end'` — right for horizontal panels, bottom for vertical panels
489
507
  */
490
508
  type CliPanelHideAlignment = 'start' | 'center' | 'end';
491
509
  /**
@@ -546,13 +564,123 @@ declare const enums: {
546
564
  };
547
565
 
548
566
  /**
549
- * Represents an option for the readSelect prompt.
567
+ * Token for the CLI user session service.
568
+ */
569
+ declare const ICliUserSessionService_TOKEN = "cli-user-session-service";
570
+ /**
571
+ * Token for the CLI users store service.
572
+ */
573
+ declare const ICliUsersStoreService_TOKEN = "cli-users-store-service";
574
+ /**
575
+ * Token for the CLI groups store service.
576
+ */
577
+ declare const ICliGroupsStoreService_TOKEN = "cli-groups-store-service";
578
+ /**
579
+ * Token for the CLI auth service.
580
+ */
581
+ declare const ICliAuthService_TOKEN = "cli-auth-service";
582
+ /**
583
+ * Token for registering completion providers via module services (multi: true).
584
+ */
585
+ declare const ICliCompletionProvider_TOKEN = "cli-completion-provider";
586
+ /**
587
+ * Token for the drag-and-drop service.
588
+ */
589
+ declare const ICliDragDropService_TOKEN = "cli-drag-drop-service";
590
+ /**
591
+ * Token for the file transfer service.
592
+ */
593
+ declare const ICliFileTransferService_TOKEN = "cli-file-transfer-service";
594
+ /**
595
+ * Token for the translation service.
596
+ */
597
+ declare const ICliTranslationService_TOKEN = "cli-translation-service";
598
+ /**
599
+ * Token for the permission service.
600
+ */
601
+ declare const ICliPermissionService_TOKEN = "cli-permission-service";
602
+ /**
603
+ * Token for the file picker provider.
604
+ */
605
+ declare const ICliFilePickerProvider_TOKEN = "cli-file-picker-provider";
606
+
607
+ /**
608
+ * Options for readFile file picker.
609
+ */
610
+ interface CliFilePickerOptions {
611
+ /** Allow selecting multiple files. Default: false. */
612
+ multiple?: boolean;
613
+ /**
614
+ * File type filter. Accepts MIME types (e.g. 'image/*') or extensions
615
+ * (e.g. '.json,.txt'). Maps to the HTML accept attribute in browsers
616
+ * and file filter in Electron.
617
+ */
618
+ accept?: string;
619
+ /**
620
+ * When true, pick a directory instead of files. Default: false.
621
+ * Cannot be combined with `multiple` — if both are set, `directory` takes precedence
622
+ * and a single directory is returned.
623
+ */
624
+ directory?: boolean;
625
+ /**
626
+ * How to read file content. Default: 'text'.
627
+ * - 'text': Read as UTF-8 string (suitable for text files)
628
+ * - 'arraybuffer': Read as ArrayBuffer (suitable for binary files like images)
629
+ */
630
+ readAs?: 'text' | 'arraybuffer';
631
+ }
632
+ /**
633
+ * Result returned by readFile for each selected file.
634
+ */
635
+ interface CliFileResult {
636
+ /** File name without path (e.g. 'config.json') */
637
+ name: string;
638
+ /** Full file path. Available in Electron, undefined in browser. */
639
+ path?: string;
640
+ /**
641
+ * File content. Type depends on `CliFilePickerOptions.readAs`:
642
+ * - 'text' (default): `string` (UTF-8 decoded)
643
+ * - 'arraybuffer': `ArrayBuffer` (raw bytes)
644
+ */
645
+ content: string | ArrayBuffer;
646
+ /** File size in bytes */
647
+ size: number;
648
+ /** MIME type (e.g. 'application/json', 'image/png') */
649
+ type: string;
650
+ }
651
+ /**
652
+ * Abstraction for environment-specific file picking.
653
+ * Implementations handle the actual dialog interaction for their environment.
654
+ */
655
+ interface ICliFilePickerProvider {
656
+ /** Whether file picking is supported in this environment */
657
+ readonly isSupported: boolean;
658
+ /**
659
+ * Open a file picker dialog and return selected files.
660
+ * @returns Array of selected files, or null if the user cancelled
661
+ */
662
+ pickFiles(options?: CliFilePickerOptions): Promise<CliFileResult[] | null>;
663
+ /**
664
+ * Open a directory picker dialog and return the selected directory.
665
+ * @returns The selected directory, or null if the user cancelled
666
+ */
667
+ pickDirectory(): Promise<CliFileResult | null>;
668
+ }
669
+
670
+ /**
671
+ * Represents an option for the readSelect and readSelectInline prompts.
550
672
  */
551
673
  interface CliSelectOption {
552
674
  /** Display text shown to the user */
553
675
  label: string;
554
676
  /** Value returned when this option is selected */
555
677
  value: string;
678
+ /** Optional description shown as dimmed italic text after the label */
679
+ description?: string;
680
+ /** Group name — options sharing the same group are displayed under a group header */
681
+ group?: string;
682
+ /** When true, the option is visible but cannot be selected (rendered dimmed) */
683
+ disabled?: boolean;
556
684
  }
557
685
  /**
558
686
  * Represents an option for the readMultiSelect prompt.
@@ -561,70 +689,151 @@ interface CliMultiSelectOption extends CliSelectOption {
561
689
  /** Whether the option is pre-selected */
562
690
  checked?: boolean;
563
691
  }
692
+ /**
693
+ * Options for readLine input.
694
+ */
695
+ interface CliLineOptions {
696
+ /**
697
+ * Pre-filled default value. Shown in the buffer when the prompt opens.
698
+ * The cursor starts at the end of the default text.
699
+ */
700
+ default?: string;
701
+ /**
702
+ * Validation function called on Enter.
703
+ * Return an error message string to reject the input and display the error.
704
+ * Return null to accept the input.
705
+ */
706
+ validate?: (value: string) => string | null;
707
+ /** Placeholder text shown dimmed when the buffer is empty */
708
+ placeholder?: string;
709
+ }
710
+ /**
711
+ * Options for readSelect and readSelectInline.
712
+ */
713
+ interface CliSelectOptions {
714
+ /** Pre-select an option by its value */
715
+ default?: string;
716
+ /** Enable type-to-filter. When true, printable keystrokes filter the option list. Default: false. */
717
+ searchable?: boolean;
718
+ /** Callback invoked each time the highlighted option changes */
719
+ onChange?: (value: string) => void;
720
+ }
721
+ /**
722
+ * Options for readMultiSelect.
723
+ */
724
+ interface CliMultiSelectOptions {
725
+ /** Enable type-to-filter. When true, printable keystrokes filter the option list. Default: false. */
726
+ searchable?: boolean;
727
+ /** Callback invoked each time the set of checked options changes */
728
+ onChange?: (values: string[]) => void;
729
+ }
730
+ /**
731
+ * Options for readNumber input.
732
+ */
733
+ interface CliNumberOptions {
734
+ /** Minimum allowed value */
735
+ min?: number;
736
+ /** Maximum allowed value */
737
+ max?: number;
738
+ /** Pre-filled default value */
739
+ default?: number;
740
+ }
741
+ /**
742
+ * Options for readDate input.
743
+ */
744
+ interface CliDateOptions {
745
+ /**
746
+ * Date format string. Supported tokens: YYYY (4-digit year), MM (2-digit month),
747
+ * DD (2-digit day). Separators can be `-`, `/`, or `.`.
748
+ * @default 'YYYY-MM-DD'
749
+ */
750
+ format?: string;
751
+ /** Minimum allowed date in the same format as `format` */
752
+ min?: string;
753
+ /** Maximum allowed date in the same format as `format` */
754
+ max?: string;
755
+ /** Pre-filled default value */
756
+ default?: string;
757
+ }
564
758
  /**
565
759
  * Provides interactive input reading from the terminal.
566
760
  * All methods resolve with `null` when the user aborts (Ctrl+C or Escape).
567
761
  */
568
762
  interface ICliInputReader {
569
763
  /**
570
- * Prompt the user for a line of text input.
571
- * @param prompt The prompt text to display (e.g. "Enter your name: ")
572
- * @returns The entered text, empty string if Enter pressed with no input, or null if aborted
764
+ * Read a line of text input.
765
+ * @param prompt - The prompt text displayed to the user
766
+ * @param options - Optional configuration for default value, validation, and placeholder
767
+ * @returns The entered text, or null if aborted
573
768
  */
574
- readLine(prompt: string): Promise<string | null>;
769
+ readLine(prompt: string, options?: CliLineOptions): Promise<string | null>;
575
770
  /**
576
- * Prompt the user for password input. Characters are masked with asterisks.
577
- * @param prompt The prompt text to display (e.g. "Password: ")
578
- * @returns The entered password, empty string if Enter pressed with no input, or null if aborted
771
+ * Read a password (masked input).
772
+ * @param prompt - The prompt text displayed to the user
773
+ * @returns The entered password, or null if aborted
579
774
  */
580
775
  readPassword(prompt: string): Promise<string | null>;
581
776
  /**
582
- * Prompt the user for a yes/no confirmation.
583
- * @param prompt The prompt text to display (e.g. "Continue?")
584
- * @param defaultValue The default value when Enter is pressed without input (defaults to false)
585
- * @returns true for yes, false for no, defaultValue on empty Enter, or null if aborted
777
+ * Read a yes/no confirmation.
778
+ * @param prompt - The prompt text displayed to the user
779
+ * @param defaultValue - Default value when Enter is pressed without input
780
+ * @returns true for yes, false for no, or null if aborted
586
781
  */
587
782
  readConfirm(prompt: string, defaultValue?: boolean): Promise<boolean | null>;
588
783
  /**
589
- * Prompt the user to select from a list of options using arrow keys.
590
- * @param prompt The prompt text to display (e.g. "Pick one:")
591
- * @param options The list of options to choose from
592
- * @param onChange Optional callback invoked each time the highlighted option changes
593
- * @returns The value of the selected option, or null if aborted
784
+ * Read a selection from a vertical list of options.
785
+ * @param prompt - The prompt text displayed to the user
786
+ * @param options - Array of options to choose from
787
+ * @param selectOptions - Optional configuration for default, search, onChange
788
+ * @returns The selected option's value, or null if aborted
594
789
  */
595
- readSelect(prompt: string, options: CliSelectOption[], onChange?: (value: string) => void): Promise<string | null>;
790
+ readSelect(prompt: string, options: CliSelectOption[], selectOptions?: CliSelectOptions): Promise<string | null>;
596
791
  /**
597
- * Prompt the user to select from a horizontal single-line option picker.
598
- * Navigate with Left/Right arrow keys.
599
- * @param prompt The prompt text to display
600
- * @param options The list of options to choose from
601
- * @param onChange Optional callback invoked each time the highlighted option changes
602
- * @returns The value of the selected option, or null if aborted
792
+ * Read a selection from an inline horizontal list.
793
+ * @param prompt - The prompt text displayed to the user
794
+ * @param options - Array of options to choose from
795
+ * @param selectOptions - Optional configuration for default, search, onChange
796
+ * @returns The selected option's value, or null if aborted
603
797
  */
604
- readSelectInline(prompt: string, options: CliSelectOption[], onChange?: (value: string) => void): Promise<string | null>;
798
+ readSelectInline(prompt: string, options: CliSelectOption[], selectOptions?: CliSelectOptions): Promise<string | null>;
605
799
  /**
606
- * Prompt the user to select multiple items from a checkbox list.
607
- * Navigate with Up/Down, toggle with Space, confirm with Enter.
608
- * @param prompt The prompt text to display
609
- * @param options The list of options with optional pre-checked state
610
- * @returns Array of selected values, or null if aborted
800
+ * Read multiple selections from a checkbox list.
801
+ * @param prompt - The prompt text displayed to the user
802
+ * @param options - Array of options with optional pre-checked state
803
+ * @param selectOptions - Optional configuration for search, onChange
804
+ * @returns Array of selected option values, or null if aborted
611
805
  */
612
- readMultiSelect(prompt: string, options: CliMultiSelectOption[]): Promise<string[] | null>;
806
+ readMultiSelect(prompt: string, options: CliMultiSelectOption[], selectOptions?: CliMultiSelectOptions): Promise<string[] | null>;
613
807
  /**
614
- * Prompt the user for numeric input with optional min/max validation.
615
- * @param prompt The prompt text to display
616
- * @param options Optional constraints: min, max, and default value
808
+ * Read a number input.
809
+ * @param prompt - The prompt text displayed to the user
810
+ * @param options - Optional configuration for min, max, and default value
617
811
  * @returns The entered number, or null if aborted
618
812
  */
619
- readNumber(prompt: string, options?: {
620
- min?: number;
621
- max?: number;
622
- default?: number;
623
- }): Promise<number | null>;
813
+ readNumber(prompt: string, options?: CliNumberOptions): Promise<number | null>;
814
+ /**
815
+ * Read a date input with format validation.
816
+ * @param prompt - The prompt text displayed to the user
817
+ * @param options - Optional configuration for format, min/max range, default
818
+ * @returns The date string in the specified format, or null if aborted
819
+ */
820
+ readDate(prompt: string, options?: CliDateOptions): Promise<string | null>;
821
+ /**
822
+ * Read file(s) via the environment's file picker dialog.
823
+ * @param prompt - The prompt text displayed to the user
824
+ * @param options - Optional configuration for multiple, accept filter, directory mode
825
+ * @returns Array of selected files with content, or null if cancelled/unsupported
826
+ */
827
+ readFile(prompt: string, options?: CliFilePickerOptions): Promise<CliFileResult[] | null>;
624
828
  }
625
829
 
626
830
  /**
627
- * Whether a background service is a long-running daemon or a one-shot job.
831
+ * Background service lifecycle type.
832
+ * - `'daemon'` — Long-running service whose `onStart` blocks until the abort signal
833
+ * fires. Suitable for event loops, polling, or WebSocket connections. Can be
834
+ * stopped and restarted.
835
+ * - `'job'` — Run-to-completion task whose `onStart` resolves when the work is done.
836
+ * Automatically transitions to `'done'` status on success. Cannot be restarted.
628
837
  */
629
838
  type CliBackgroundServiceType = 'daemon' | 'job';
630
839
  /**
@@ -653,12 +862,18 @@ interface ICliServiceEvent {
653
862
  * Handler function for service events.
654
863
  */
655
864
  type CliServiceEventHandler = (event: ICliServiceEvent) => void;
865
+ /**
866
+ * Log severity level for background service messages.
867
+ * Shared by `ICliServiceLogEntry`, `ICliServiceContext.log()`,
868
+ * and `WorkerServiceContext.log()`.
869
+ */
870
+ type CliServiceLogLevel = 'info' | 'warn' | 'error';
656
871
  /**
657
872
  * A single log entry from a background service.
658
873
  */
659
874
  interface ICliServiceLogEntry {
660
875
  timestamp: Date;
661
- level: 'info' | 'warn' | 'error';
876
+ level: CliServiceLogLevel;
662
877
  message: string;
663
878
  }
664
879
  /**
@@ -672,7 +887,7 @@ interface ICliServiceContext {
672
887
  /** Emit an event from this service */
673
888
  emit(event: ICliServiceEvent): void;
674
889
  /** Log a message to this service's private log buffer */
675
- log(message: string, level?: 'info' | 'warn' | 'error'): void;
890
+ log(message: string, level?: CliServiceLogLevel): void;
676
891
  /** Create an interval scoped to this service (auto-cleared on stop) */
677
892
  createInterval(callback: () => void, ms: number): ICliManagedInterval;
678
893
  /** Create a timeout scoped to this service (auto-cleared on stop) */
@@ -700,13 +915,19 @@ interface ICliBackgroundService {
700
915
  onStart(context: ICliServiceContext): Promise<void>;
701
916
  /** Called for graceful shutdown */
702
917
  onStop?(context: ICliServiceContext): Promise<void>;
703
- /** Called on unrecoverable error */
918
+ /**
919
+ * Called when the service throws an unrecoverable error.
920
+ * Use this hook for logging or cleanup; throwing from `onError` itself
921
+ * is safe — the registry catches it and marks the service as failed.
922
+ */
704
923
  onError?(error: Error, context: ICliServiceContext): void;
705
924
  }
706
925
  /**
707
926
  * Read-only snapshot of a background service's current state.
708
927
  */
709
928
  interface ICliBackgroundServiceInfo {
929
+ /** Process ID assigned by the process registry */
930
+ pid?: number;
710
931
  name: string;
711
932
  description?: string;
712
933
  type: CliBackgroundServiceType;
@@ -729,7 +950,7 @@ interface ICliBackgroundServiceRegistry {
729
950
  restart(name: string): Promise<void>;
730
951
  startJob(name: string, task: (context: ICliServiceContext) => Promise<void>, options?: {
731
952
  workerCompatible?: boolean;
732
- }): void;
953
+ }): Promise<void>;
733
954
  getStatus(name: string): ICliBackgroundServiceInfo | undefined;
734
955
  list(): ICliBackgroundServiceInfo[];
735
956
  getLogs(name: string, limit?: number): ICliServiceLogEntry[];
@@ -747,14 +968,14 @@ interface ICliBackgroundServiceRegistry {
747
968
  */
748
969
  interface ICliManagedTimer {
749
970
  /** Clear this timer immediately. */
750
- clear(): void;
971
+ readonly clear: () => void;
751
972
  }
752
973
  /**
753
974
  * A managed interval handle with the ability to change the delay.
754
975
  */
755
976
  interface ICliManagedInterval extends ICliManagedTimer {
756
977
  /** Change the interval delay. Restarts the interval with the new delay. */
757
- setDelay(ms: number): void;
978
+ readonly setDelay: (ms: number) => void;
758
979
  }
759
980
  /**
760
981
  * Represents the context in which a command is executed
@@ -1094,7 +1315,7 @@ interface ICliCommandProcessor {
1094
1315
  /**
1095
1316
  * Represents the state configuration for the command processor
1096
1317
  * @remarks The state configuration is used to store and retrieve state information for the command processor
1097
- * @remarks State confihuration is optional and can be used to store and retrieve state information for the command processor
1318
+ * @remarks State configuration is optional and can be used to store and retrieve state information for the command processor
1098
1319
  * @remarks The state configuration is used only for root command processors and not for child command processors
1099
1320
  */
1100
1321
  stateConfiguration?: CliStateConfiguration;
@@ -1201,10 +1422,6 @@ interface ICliGlobalParameterHandler {
1201
1422
  handle(args: Record<string, any>, processor: ICliCommandProcessor, command: CliProcessCommand, context: ICliExecutionContext): boolean | Promise<boolean>;
1202
1423
  }
1203
1424
 
1204
- /**
1205
- * Token for registering completion providers via module services (multi: true).
1206
- */
1207
- declare const ICliCompletionProvider_TOKEN = "cli-completion-provider";
1208
1425
  /**
1209
1426
  * Context passed to completion providers describing the current input state.
1210
1427
  */
@@ -1276,9 +1493,9 @@ type CliPercentageProgressBarUpdateValueOptions = {
1276
1493
  */
1277
1494
  interface ICliPercentageProgressBar extends ICliProgressBar {
1278
1495
  /**
1279
- * Update the progress of the progress bar
1280
- * @param progress The progress to update to
1281
- * @returns void
1496
+ * Update the progress of the progress bar.
1497
+ * @param progress The progress value (0–100). Values outside this range are clamped.
1498
+ * @param options Optional: update type ('replace' or 'increment')
1282
1499
  */
1283
1500
  update: (progress: number, options?: CliPercentageProgressBarUpdateValueOptions) => void;
1284
1501
  /**
@@ -1306,9 +1523,9 @@ type CliTextAnimatorOptions = {
1306
1523
  interface ICliTextAnimator extends ICliProgressBar {
1307
1524
  /**
1308
1525
  * Show animated text in a typing and erasing effect.
1309
- * @param text
1310
- * @param options
1311
- * @returns
1526
+ * @param text The text to animate
1527
+ * @param options Optional: speed (ms per character), removeAfterTyping
1528
+ * @returns A promise that resolves when the animation completes
1312
1529
  */
1313
1530
  showText: (text: string, options?: CliTextAnimatorOptions) => Promise<void>;
1314
1531
  }
@@ -1447,10 +1664,7 @@ interface ICliFileEntry {
1447
1664
  size: number;
1448
1665
  modified: string;
1449
1666
  }
1450
- /**
1451
- * Token for the file transfer service.
1452
- */
1453
- declare const ICliFileTransferService_TOKEN = "cli-file-transfer-service";
1667
+
1454
1668
  /**
1455
1669
  * Abstraction for file transfer operations.
1456
1670
  * Default implementation uses browser-native APIs (file picker, download dialog).
@@ -1468,12 +1682,37 @@ interface ICliFileTransferService {
1468
1682
  } | null>;
1469
1683
  }
1470
1684
 
1471
- declare const ICliDragDropService_TOKEN = "cli-drag-drop-service";
1472
1685
  interface ICliDragDropService {
1473
1686
  /** Emits an array of dropped File objects each time files are dropped onto the terminal */
1474
1687
  readonly onFileDrop: Observable<File[]>;
1475
1688
  }
1476
1689
 
1690
+ /**
1691
+ * Opaque state value carried between lines during syntax highlighting.
1692
+ * Encodes context such as "inside a multi-line string" or "inside a block comment"
1693
+ * so the highlighter can resume correctly on the next line.
1694
+ * `0` typically represents the default/root state.
1695
+ */
1696
+ type LineState = number;
1697
+ interface ISyntaxHighlightRule {
1698
+ pattern: RegExp;
1699
+ tokenType: string;
1700
+ captureGroup?: number;
1701
+ }
1702
+ interface ISyntaxHighlighter {
1703
+ id: string;
1704
+ /** Human-readable language name (e.g. 'TypeScript'). Falls back to `id` when absent. */
1705
+ name?: string;
1706
+ extensions: string[];
1707
+ initialState: LineState;
1708
+ getRules(state: LineState): ISyntaxHighlightRule[];
1709
+ getNextLineState(line: string, currentState: LineState): LineState;
1710
+ }
1711
+ interface ISyntaxTheme {
1712
+ name: string;
1713
+ colors: Record<string, string>;
1714
+ }
1715
+
1477
1716
  interface ICliTerminalWriter {
1478
1717
  /**
1479
1718
  * Write text to the terminal
@@ -1487,72 +1726,63 @@ interface ICliTerminalWriter {
1487
1726
  writeln(text?: string): void;
1488
1727
  /**
1489
1728
  * Write a success message to the terminal
1490
- * @param messag The message to write
1491
- * @returns void
1729
+ * @param message The message to write
1492
1730
  */
1493
- writeSuccess: (message: string) => void;
1731
+ writeSuccess(message: string): void;
1494
1732
  /**
1495
1733
  * Write an info message to the terminal
1496
- * @param messag The message to write
1497
- * @returns void
1734
+ * @param message The message to write
1498
1735
  */
1499
- writeInfo: (message: string) => void;
1736
+ writeInfo(message: string): void;
1500
1737
  /**
1501
1738
  * Write an error message to the terminal
1502
1739
  * @param message The message to write
1503
- * @returns void
1504
1740
  */
1505
- writeError: (message: string) => void;
1741
+ writeError(message: string): void;
1506
1742
  /**
1507
1743
  * Write a warning message to the terminal
1508
1744
  * @param message The message to write
1509
- * @returns void
1510
1745
  */
1511
- writeWarning: (message: string) => void;
1746
+ writeWarning(message: string): void;
1512
1747
  /**
1513
- * Write a message to the terminal with the specified color
1514
- * @param message The message to write
1515
- * @param color The color to use
1516
- * @returns void
1748
+ * Wrap text in the specified foreground color.
1749
+ * @param text The text to wrap
1750
+ * @param color The foreground color to apply
1751
+ * @returns The text wrapped in ANSI color codes
1517
1752
  */
1518
- wrapInColor: (text: string, color: CliForegroundColor) => string;
1753
+ wrapInColor(text: string, color: CliForegroundColor): string;
1519
1754
  /**
1520
- * Write a message to the terminal with the specified background color
1521
- * @param message The message to write
1522
- * @param color The background color to use
1523
- * @returns void
1755
+ * Wrap text in the specified background color.
1756
+ * @param text The text to wrap
1757
+ * @param color The background color to apply
1758
+ * @returns The text wrapped in ANSI background color codes
1524
1759
  */
1525
- wrapInBackgroundColor: (text: string, color: CliBackgroundColor) => string;
1760
+ wrapInBackgroundColor(text: string, color: CliBackgroundColor): string;
1526
1761
  /**
1527
1762
  * Write a JSON object to the terminal
1528
1763
  * @param json The JSON object to write
1529
- * @returns void
1530
1764
  */
1531
- writeJson: (json: any) => void;
1765
+ writeJson(json: any): void;
1532
1766
  /**
1533
- * Write content to a file
1534
- * @param fileName The name of the file to write to
1767
+ * Write content to a file (triggers a browser download)
1768
+ * @param fileName The name of the file to download
1535
1769
  * @param content The content to write to the file
1536
- * @returns void
1537
1770
  */
1538
- writeToFile: (fileName: string, content: string) => void;
1771
+ writeToFile(fileName: string, content: string): void;
1539
1772
  /**
1540
1773
  * Write an object array as a table to the terminal
1541
1774
  * @param objects The objects to write to the table
1542
- * @returns void
1543
1775
  */
1544
1776
  writeObjectsAsTable(objects: any[]): void;
1545
1777
  /**
1546
1778
  * Write a table to the terminal
1547
1779
  * @param headers The headers of the table
1548
1780
  * @param rows The rows of the table
1549
- * @returns void
1550
1781
  */
1551
1782
  writeTable(headers: string[], rows: string[][]): void;
1552
1783
  /**
1553
1784
  * Write a divider to the terminal
1554
- * @param options The options for the divider
1555
- * @returns void
1785
+ * @param options Optional: color, length, character
1556
1786
  */
1557
1787
  writeDivider(options?: {
1558
1788
  color?: CliForegroundColor;
@@ -1587,6 +1817,32 @@ interface ICliTerminalWriter {
1587
1817
  columns?: number;
1588
1818
  padding?: number;
1589
1819
  }): void;
1820
+ /**
1821
+ * Write a clickable hyperlink using OSC 8 escape sequences.
1822
+ * In terminals that support OSC 8, the text is clickable. In others,
1823
+ * it falls back to displaying "text (url)".
1824
+ * @param text The visible link text
1825
+ * @param url The URL to link to
1826
+ */
1827
+ writeLink(text: string, url: string): void;
1828
+ /**
1829
+ * Write text inside a bordered box.
1830
+ * Useful for callouts, notices, and highlighted information.
1831
+ * @param content The content lines to display inside the box
1832
+ * @param options Optional: title, border color, padding
1833
+ */
1834
+ writeBox(content: string | string[], options?: {
1835
+ title?: string;
1836
+ borderColor?: CliForegroundColor;
1837
+ padding?: number;
1838
+ }): void;
1839
+ /**
1840
+ * Write text with a specified indentation level.
1841
+ * Each level adds 2 spaces of indentation.
1842
+ * @param text The text to write
1843
+ * @param level The indentation level (default: 1)
1844
+ */
1845
+ writeIndented(text: string, level?: number): void;
1590
1846
  }
1591
1847
  /**
1592
1848
  * Represents a clipboard for the CLI
@@ -1609,9 +1865,10 @@ interface ICliClipboard {
1609
1865
  */
1610
1866
  interface ICliCommandExecutorService {
1611
1867
  /**
1612
- *
1613
- * @param command
1614
- * @param context
1868
+ * Display the help output for a command, including its description,
1869
+ * sub-commands, and parameters.
1870
+ * @param command The parsed command to show help for
1871
+ * @param context The execution context
1615
1872
  */
1616
1873
  showHelp(command: CliProcessCommand, context: ICliExecutionContext): Promise<void>;
1617
1874
  /**
@@ -1718,17 +1975,30 @@ interface ICliExecutionProcess {
1718
1975
  */
1719
1976
  interface ICliProcessEntry {
1720
1977
  pid: number;
1978
+ /** Display name (service name for bg services, command text for commands) */
1979
+ name: string;
1980
+ /** Process type */
1981
+ type: 'command' | 'daemon' | 'job' | 'service';
1721
1982
  command: string;
1722
1983
  startTime: number;
1723
1984
  status: 'running' | 'completed' | 'failed' | 'killed';
1724
1985
  exitCode?: number;
1725
1986
  }
1987
+ /** Options for registering a process */
1988
+ interface ICliProcessRegisterOptions {
1989
+ /** Display name (defaults to command) */
1990
+ name?: string;
1991
+ /** Process type (defaults to 'command') */
1992
+ type?: 'command' | 'daemon' | 'job' | 'service';
1993
+ /** Custom kill handler (e.g. for background services) */
1994
+ onKill?: () => Promise<void> | void;
1995
+ }
1726
1996
  /**
1727
1997
  * Registry for tracking CLI processes
1728
1998
  */
1729
1999
  interface ICliProcessRegistry {
1730
2000
  /** Register a new process, returns assigned PID */
1731
- register(command: string): {
2001
+ register(command: string, options?: ICliProcessRegisterOptions): {
1732
2002
  pid: number;
1733
2003
  abortController: AbortController;
1734
2004
  };
@@ -1773,16 +2043,24 @@ interface ICliKeyValueStore {
1773
2043
  clear(): Promise<void>;
1774
2044
  }
1775
2045
  /**
1776
- * Represents a store for storing data associated with commands
2046
+ * Reactive state store scoped to a command processor or module.
2047
+ *
2048
+ * State is a plain object (`Record<string, any>`). Updates are shallow-merged
2049
+ * (top-level keys are replaced, nested objects are not deep-merged).
2050
+ * `getState()` returns a snapshot — mutating the returned object has no effect;
2051
+ * always use `updateState()` to change state.
1777
2052
  */
1778
2053
  interface ICliStateStore {
1779
2054
  /**
1780
- * Get the current state as an object.
2055
+ * Get a snapshot of the current state.
2056
+ * @returns A shallow copy of the state object
1781
2057
  */
1782
2058
  getState<T extends CliState = CliState>(): T;
1783
2059
  /**
1784
- * Update the state with new values. Supports partial updates.
1785
- * @param newState Partial state to merge with the current state.
2060
+ * Shallow-merge new values into the current state.
2061
+ * Only the provided keys are updated; other keys are preserved.
2062
+ * Triggers subscribers and persists if a storage backend is configured.
2063
+ * @param newState Partial state to merge with the current state
1786
2064
  */
1787
2065
  updateState(newState: Partial<CliState>): void;
1788
2066
  /**
@@ -1881,6 +2159,22 @@ interface ICliModule {
1881
2159
  /** Called when the module is being torn down */
1882
2160
  onDestroy?(context: ICliExecutionContext): Promise<void>;
1883
2161
  }
2162
+ /**
2163
+ * A module that accepts typed configuration via `configure()`.
2164
+ * Extend this instead of `ICliModule` when your module has a config type.
2165
+ *
2166
+ * @example
2167
+ * ```ts
2168
+ * interface MyModuleConfig { verbose?: boolean }
2169
+ * const myModule: ICliConfigurableModule<MyModuleConfig> = {
2170
+ * configure(config) { return { ...this, config }; },
2171
+ * // ...
2172
+ * };
2173
+ * ```
2174
+ */
2175
+ interface ICliConfigurableModule<T extends Record<string, any> = Record<string, any>> extends ICliModule {
2176
+ configure(config: T): ICliModule;
2177
+ }
1884
2178
  /**
1885
2179
  * @deprecated Use ICliModule instead
1886
2180
  */
@@ -1897,32 +2191,32 @@ interface ICliLogger {
1897
2191
  */
1898
2192
  setCliLogLevel(level: CliLogLevel): void;
1899
2193
  /**
1900
- * Log a message
2194
+ * Log a general message (LOG level)
1901
2195
  * @param args The arguments to log
1902
2196
  */
1903
2197
  log(...args: any[]): void;
1904
2198
  /**
1905
- * Log a message
2199
+ * Log an informational message (INFO level)
1906
2200
  * @param args The arguments to log
1907
2201
  */
1908
2202
  info(...args: any[]): void;
1909
2203
  /**
1910
- * Log a message
2204
+ * Log a warning message (WARN level)
1911
2205
  * @param args The arguments to log
1912
2206
  */
1913
2207
  warn(...args: any[]): void;
1914
2208
  /**
1915
- * Log a message
2209
+ * Log an error message (ERROR level)
1916
2210
  * @param args The arguments to log
1917
2211
  */
1918
2212
  error(...args: any[]): void;
1919
2213
  /**
1920
- * Log a message
2214
+ * Log a debug message (DEBUG level)
1921
2215
  * @param args The arguments to log
1922
2216
  */
1923
2217
  debug(...args: any[]): void;
1924
2218
  }
1925
- declare const ICliTranslationService_TOKEN = "cli-translation-service";
2219
+
1926
2220
  /**
1927
2221
  * Provides internationalization (i18n) support for CLI strings.
1928
2222
  */
@@ -1956,23 +2250,24 @@ interface ICliTranslationService {
1956
2250
  getAvailableLocales(): string[];
1957
2251
  }
1958
2252
  /**
1959
- * Represents a service provider for the CLI
2253
+ * Dependency injection container for CLI services.
2254
+ * Services are registered with string tokens and retrieved by type.
1960
2255
  */
1961
2256
  interface ICliServiceProvider {
1962
2257
  /**
1963
- * Get a service
1964
- * @param service The service to get
2258
+ * Retrieve a service by its injection token.
2259
+ * @param service The token (typically a `*_TOKEN` constant) identifying the service
2260
+ * @returns The service instance, cast to `T`
2261
+ * @throws If no service is registered for the given token
1965
2262
  */
1966
- get<T>(service: any): T;
2263
+ get<T = unknown>(service: any): T;
1967
2264
  /**
1968
- * Set a service
1969
- * @param definition The definition of the service
2265
+ * Register one or more service definitions.
2266
+ * @param definition A single provider or an array of providers to register
1970
2267
  */
1971
2268
  set(definition: CliProvider | CliProvider[]): void;
1972
2269
  }
1973
2270
 
1974
- declare const ICliPermissionService_TOKEN = "cli-permission-service";
1975
-
1976
2271
  /**
1977
2272
  * Abstract permission service for checking rwx permissions on resources.
1978
2273
  * The default implementation lives in @qodalis/cli-users; consumers can
@@ -2001,13 +2296,15 @@ interface ICliPermissionService {
2001
2296
  declare class CliModuleRegistry {
2002
2297
  private readonly modules;
2003
2298
  private readonly bootHandlers;
2299
+ /** Optional warning callback — set by the engine to route through ICliLogger */
2300
+ onWarn?: (message: string) => void;
2004
2301
  /**
2005
2302
  * Register a handler that is called whenever a new module is registered.
2006
2303
  */
2007
2304
  onModuleBoot(handler: (module: ICliModule) => Promise<void>): void;
2008
2305
  /**
2009
2306
  * Register a module and notify all boot handlers.
2010
- * Modules that do not meet the required API version are silently skipped.
2307
+ * Modules that do not meet the required API version are skipped with a warning.
2011
2308
  */
2012
2309
  register(module: ICliModule): Promise<void>;
2013
2310
  /**
@@ -2071,6 +2368,17 @@ declare const CLI_CONFIGURE_STORE_NAME = "configure";
2071
2368
  * @returns The configured value or the default
2072
2369
  */
2073
2370
  declare function getConfigValue<T = any>(state: ICliStateStore, category: string, key: string, defaultValue: T): T;
2371
+ /**
2372
+ * Retrieves a plugin configuration value from the execution context.
2373
+ * This is a convenience wrapper for plugins — handles store lookup internally.
2374
+ *
2375
+ * @param context The execution context
2376
+ * @param category The category (usually the processor's command name)
2377
+ * @param key The configuration key
2378
+ * @param defaultValue Fallback value if not configured
2379
+ * @returns The configured value or the default
2380
+ */
2381
+ declare function getPluginConfigValue<T = any>(context: ICliExecutionContext, category: string, key: string, defaultValue: T): T;
2074
2382
  /**
2075
2383
  * Resolves all configuration options from registered processors,
2076
2384
  * grouped by category.
@@ -2080,6 +2388,10 @@ declare function resolveConfigurationCategories(registry: ICliCommandProcessorRe
2080
2388
  options: ICliConfigurationOption[];
2081
2389
  }>;
2082
2390
 
2391
+ /**
2392
+ * Returns a promise that resolves after the given number of milliseconds.
2393
+ * @param ms Delay duration in milliseconds
2394
+ */
2083
2395
  declare const delay: (ms: number) => Promise<void>;
2084
2396
 
2085
2397
  /**
@@ -2117,7 +2429,7 @@ interface ServerVersionInfo {
2117
2429
  * Negotiates the API version between a frontend CLI client and a backend server.
2118
2430
  *
2119
2431
  * Flow:
2120
- * 1. Client calls `discover(baseUrl)` which hits `GET /api/qcli/versions`
2432
+ * 1. Client calls `discover(baseUrl)` which hits `GET ${VERSIONS_ENDPOINT}`
2121
2433
  * 2. Server returns supported versions
2122
2434
  * 3. Client picks the highest mutually supported version
2123
2435
  * 4. All subsequent calls use `/api/v{n}/qcli/*`
@@ -2173,18 +2485,72 @@ declare function savePanelPosition(position: CliPanelPosition): void;
2173
2485
  */
2174
2486
  declare function nextPanelPosition(current: CliPanelPosition): CliPanelPosition;
2175
2487
 
2176
- declare const getParameterValue: (p: ICliCommandParameterDescriptor, args: Record<string, any>) => any | undefined;
2488
+ /**
2489
+ * Strip all ANSI escape sequences from a string.
2490
+ * @param text The text potentially containing ANSI codes
2491
+ * @returns The text with all ANSI codes removed
2492
+ */
2493
+ declare function stripAnsi(text: string): string;
2494
+ /**
2495
+ * Return the visible length of a string, ignoring ANSI escape codes.
2496
+ * Useful for padding/alignment calculations in terminal output.
2497
+ * @param text The text potentially containing ANSI codes
2498
+ * @returns The number of visible characters
2499
+ */
2500
+ declare function visibleLength(text: string): number;
2501
+
2502
+ /**
2503
+ * Retrieve a parameter's value from the parsed arguments, checking aliases.
2504
+ * @param p The parameter descriptor
2505
+ * @param args The parsed command arguments
2506
+ * @returns The matched value, or `undefined` if not found
2507
+ */
2508
+ declare const getParameterValue: (p: ICliCommandParameterDescriptor, args: Record<string, any>) => unknown;
2509
+ /**
2510
+ * Pretty-print a JSON value with ANSI color highlighting.
2511
+ * @param json The value to format
2512
+ * @returns A colorized, indented string suitable for terminal output
2513
+ */
2177
2514
  declare const formatJson: (json: any) => string;
2178
- declare const colorizeJson: (jsonString: any) => string;
2515
+ /**
2516
+ * Apply ANSI color codes to a JSON string (keys, strings, numbers, booleans, null).
2517
+ * @param jsonString The raw JSON string to colorize
2518
+ * @returns The colorized string
2519
+ */
2520
+ declare const colorizeJson: (jsonString: string) => string;
2521
+ /**
2522
+ * Convert a key-value object to a URL query string. Arrays produce repeated keys.
2523
+ * @param params The parameters to encode
2524
+ * @returns The encoded query string (without leading `?`)
2525
+ */
2179
2526
  declare const toQueryString: (params: Record<string, any>) => string;
2527
+ /**
2528
+ * Highlight regex matches in text using an ANSI background color.
2529
+ * @param text The source text
2530
+ * @param pattern The regex pattern to highlight
2531
+ * @param bgColor The background color to apply (default: Yellow)
2532
+ * @returns The text with matching segments wrapped in ANSI background color codes
2533
+ */
2180
2534
  declare const highlightTextWithBg: (text: string, pattern: RegExp, bgColor?: CliBackgroundColor) => string;
2535
+ /**
2536
+ * Extract the substring to the right of a given word in a command string.
2537
+ * @param command The full command string
2538
+ * @param word The word to search for
2539
+ * @returns The trimmed text after the word, or `undefined` if not found
2540
+ */
2181
2541
  declare const getRightOfWord: (command: string, word: string) => string | undefined;
2542
+ /**
2543
+ * Apply a color function to the first word of a text string, preserving leading whitespace.
2544
+ * @param text The text to process
2545
+ * @param colorFunction A function that wraps a word in ANSI color codes
2546
+ * @returns The text with only the first word colorized
2547
+ */
2182
2548
  declare const colorFirstWord: (text: string, colorFunction: (word: string) => string) => string;
2183
2549
 
2184
2550
  declare const utils: {
2185
- getParameterValue: (p: ICliCommandParameterDescriptor, args: Record<string, any>) => any | undefined;
2551
+ getParameterValue: (p: ICliCommandParameterDescriptor, args: Record<string, any>) => unknown;
2186
2552
  formatJson: (json: any) => string;
2187
- colorizeJson: (jsonString: any) => string;
2553
+ colorizeJson: (jsonString: string) => string;
2188
2554
  toQueryString: (params: Record<string, any>) => string;
2189
2555
  highlightTextWithBg: (text: string, pattern: RegExp, bgColor?: CliBackgroundColor) => string;
2190
2556
  getRightOfWord: (command: string, word: string) => string | undefined;
@@ -2192,6 +2558,7 @@ declare const utils: {
2192
2558
  ObjectDescriber: typeof ObjectDescriber;
2193
2559
  delay: (ms: number) => Promise<void>;
2194
2560
  getConfigValue: typeof getConfigValue;
2561
+ getPluginConfigValue: typeof getPluginConfigValue;
2195
2562
  resolveConfigurationCategories: typeof resolveConfigurationCategories;
2196
2563
  CLI_CONFIGURE_STORE_NAME: string;
2197
2564
  };
@@ -2201,12 +2568,38 @@ declare const constants: {
2201
2568
  DefaultLibraryAuthor: ICliCommandAuthor;
2202
2569
  };
2203
2570
 
2571
+ /** Error message used when a `CancellablePromise` is cancelled. */
2572
+ declare const CANCELLATION_ERROR_MESSAGE = "Promise cancelled";
2573
+ /**
2574
+ * A promise wrapper that supports cooperative cancellation.
2575
+ *
2576
+ * Create with an executor (like `new Promise`), then call `execute()` to run.
2577
+ * Call `cancel()` to reject with a cancellation error and prevent further
2578
+ * resolve/reject callbacks from firing.
2579
+ *
2580
+ * @example
2581
+ * ```ts
2582
+ * const cp = new CancellablePromise<string>((resolve) => {
2583
+ * setTimeout(() => resolve('done'), 5000);
2584
+ * });
2585
+ * cp.execute().catch(e => console.log(e.message)); // 'Promise cancelled'
2586
+ * cp.cancel();
2587
+ * ```
2588
+ */
2204
2589
  declare class CancellablePromise<T> {
2205
2590
  private executor;
2206
2591
  private hasCancelled;
2207
2592
  private abortController;
2208
2593
  constructor(executor: (resolve: (value: T) => void, reject: (reason?: any) => void) => void);
2594
+ /**
2595
+ * Run the executor and return a promise for its result.
2596
+ * If `cancel()` has been called, the promise rejects immediately.
2597
+ */
2209
2598
  execute(): Promise<T>;
2599
+ /**
2600
+ * Cancel the promise. The executing promise rejects with
2601
+ * `Error('Promise cancelled')` and subsequent resolve/reject calls are ignored.
2602
+ */
2210
2603
  cancel(): void;
2211
2604
  }
2212
2605
 
@@ -2256,30 +2649,9 @@ declare const DefaultThemes: DefaultThemesType;
2256
2649
 
2257
2650
  declare const DefaultThemeInfos: Record<string, CliThemeInfo>;
2258
2651
 
2259
- declare const LIBRARY_VERSION = "2.0.0-beta.7";
2652
+ declare const LIBRARY_VERSION = "2.0.0-beta.9";
2260
2653
  declare const API_VERSION = 2;
2261
2654
 
2262
- /**
2263
- * Framework-agnostic token for the CLI user session service.
2264
- * Used as a key in the service provider to retrieve the user session service.
2265
- */
2266
- declare const ICliUserSessionService_TOKEN = "cli-user-session-service";
2267
- /**
2268
- * Framework-agnostic token for the CLI users store service.
2269
- * Used as a key in the service provider to retrieve the users store service.
2270
- */
2271
- declare const ICliUsersStoreService_TOKEN = "cli-users-store-service";
2272
- /**
2273
- * Framework-agnostic token for the CLI groups store service.
2274
- * Used as a key in the service provider to retrieve the groups store service.
2275
- */
2276
- declare const ICliGroupsStoreService_TOKEN = "cli-groups-store-service";
2277
- /**
2278
- * Framework-agnostic token for the CLI auth service.
2279
- * Used as a key in the service provider to retrieve the auth service.
2280
- */
2281
- declare const ICliAuthService_TOKEN = "cli-auth-service";
2282
-
2283
2655
  /**
2284
2656
  * Context provided to worker service handlers inside a Web Worker.
2285
2657
  */
@@ -2287,7 +2659,7 @@ interface WorkerServiceContext {
2287
2659
  /** Emit an event to the main thread */
2288
2660
  emit(event: Omit<ICliServiceEvent, 'timestamp'>): void;
2289
2661
  /** Log a message (forwarded to the main-thread log buffer) */
2290
- log(message: string, level?: 'info' | 'warn' | 'error'): void;
2662
+ log(message: string, level?: CliServiceLogLevel): void;
2291
2663
  /** Update state on the main thread */
2292
2664
  updateState(patch: Record<string, unknown>): void;
2293
2665
  /** Create an interval that is auto-cleared on stop */
@@ -2306,10 +2678,29 @@ declare function createWorkerService(handlers: {
2306
2678
  onStop?(): Promise<void>;
2307
2679
  }): void;
2308
2680
 
2681
+ /**
2682
+ * Browser-based file transfer service using native browser APIs.
2683
+ *
2684
+ * This is the default implementation when no virtual filesystem is available.
2685
+ * `readFile` and `uploadFromBrowser` open a file picker dialog.
2686
+ * `writeFile` and `downloadToBrowser` trigger a browser download.
2687
+ *
2688
+ * **Limitations:** `listFiles()` and `exists()` are not supported in the
2689
+ * browser environment and always return empty/false respectively.
2690
+ * Use `@qodalis/cli-files` for full filesystem capabilities.
2691
+ */
2309
2692
  declare class BrowserFileTransferService implements ICliFileTransferService {
2310
2693
  readFile(_path: string): Promise<string | null>;
2311
2694
  writeFile(path: string, content: string): Promise<void>;
2695
+ /**
2696
+ * Not supported in browser — always returns an empty array.
2697
+ * Use `@qodalis/cli-files` for directory listing.
2698
+ */
2312
2699
  listFiles(_path: string): Promise<ICliFileEntry[]>;
2700
+ /**
2701
+ * Not supported in browser — always returns `false`.
2702
+ * Use `@qodalis/cli-files` for file existence checks.
2703
+ */
2313
2704
  exists(_path: string): Promise<boolean>;
2314
2705
  downloadToBrowser(filename: string, content: string | Blob): void;
2315
2706
  uploadFromBrowser(accept?: string): Promise<{
@@ -2319,4 +2710,4 @@ declare class BrowserFileTransferService implements ICliFileTransferService {
2319
2710
  private _pickFile;
2320
2711
  }
2321
2712
 
2322
- 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 };
2713
+ export { API_VERSION, BrowserFileTransferService, CANCELLATION_ERROR_MESSAGE, CLI_CONFIGURE_STORE_NAME, CancellablePromise, type CliAddUser, CliBackgroundColor, type CliBackgroundServiceStatus, type CliBackgroundServiceType, type CliDateOptions, type CliEngineSnapshot, type CliFactoryProvider, type CliFilePickerOptions, type CliFileResult, CliForegroundColor, CliIcon, type CliLineOptions, CliLogLevel, CliModuleRegistry, type CliMultiSelectOption, type CliMultiSelectOptions, type CliNumberOptions, type CliOptions, type CliPackageSource, type CliPanelConfig, type CliPanelHideAlignment, type CliPanelPosition, type CliPercentageProgressBarUpdateValueOptions, type CliProcessCommand, type CliProcessorMetadata, type CliProvider, type CliSelectOption, type CliSelectOptions, type CliServerCapabilities, type CliServerCommandDescriptor, type CliServerConfig, type CliServerOutput, type CliServerResponse, type CliServiceEventHandler, type CliServiceExecutionMode, type CliServiceLogLevel, type CliState, type CliStateConfiguration, type CliTextAnimatorOptions, type CliTheme, type CliThemeCategory, type CliThemeInfo, type CliTypeProvider, type CliUpdateUser, type CliValueProvider, type CliWorkerInboundMessage, type CliWorkerOutboundMessage, DEFAULT_DIR_PERMISSIONS, DEFAULT_FILE_PERMISSIONS, DefaultLibraryAuthor, DefaultThemeInfos, DefaultThemes, type ICliAuthService, ICliAuthService_TOKEN, type ICliBackgroundService, type ICliBackgroundServiceInfo, type ICliBackgroundServiceRegistry, type ICliClipboard, type ICliCommandAuthor, type ICliCommandChildProcessor, type ICliCommandExecutorService, type ICliCommandParameterDescriptor, type ICliCommandProcessor, type ICliCommandProcessorRegistry, type ICliCompletionContext, type ICliCompletionProvider, ICliCompletionProvider_TOKEN, type ICliConfigurableModule, type ICliConfigurationOption, type ICliDragDropService, ICliDragDropService_TOKEN, type ICliExecutionContext, type ICliExecutionProcess, type ICliFileEntry, type ICliFilePickerProvider, ICliFilePickerProvider_TOKEN, type ICliFileTransferService, ICliFileTransferService_TOKEN, type ICliGlobalParameterHandler, type ICliGroup, type ICliGroupsStoreService, ICliGroupsStoreService_TOKEN, type ICliInputReader, type ICliKeyValueStore, type ICliLogger, type ICliManagedInterval, type ICliManagedTimer, type ICliModule, type ICliOwnership, type ICliPercentageProgressBar, type ICliPermissionService, ICliPermissionService_TOKEN, type ICliPingServerService, type ICliProcessEntry, type ICliProcessRegisterOptions, type ICliProcessRegistry, type ICliProcessorHook, type ICliProgressBar, type ICliServiceContext, type ICliServiceEvent, type ICliServiceLogEntry, type ICliServiceProvider, type ICliSpinner, type ICliStateStore, type ICliTerminalWriter, type ICliTextAnimator, type ICliTranslationService, ICliTranslationService_TOKEN, type ICliUmdModule, type ICliUser, type ICliUserCredentials, type ICliUserSession, type ICliUserSessionService, ICliUserSessionService_TOKEN, type ICliUsersStoreService, ICliUsersStoreService_TOKEN, type ISyntaxHighlightRule, type ISyntaxHighlighter, type ISyntaxTheme, LIBRARY_VERSION, type LineState, ObjectDescriber, type Package, type ServerVersionInfo, ServerVersionNegotiator, type WorkerServiceContext, bootCliModule, bootUmdModule, clearTerminalLine, colorFirstWord, colorizeJson, compareVersions, constants, createWorkerService, delay, derivePanelThemeStyles, enums, formatJson, getConfigValue, getParameterValue, getPluginConfigValue, getRightOfWord, highlightTextWithBg, initializeBrowserEnvironment, loadPanelPosition, nextPanelPosition, resolveConfigurationCategories, satisfiesMinVersion, satisfiesVersionRange, savePanelPosition, stripAnsi, toQueryString, utils, visibleLength };