@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/package.json +1 -1
- package/public-api.d.mts +543 -152
- package/public-api.d.ts +543 -152
- package/public-api.js +101 -46
- package/public-api.js.map +1 -1
- package/public-api.mjs +97 -47
- package/public-api.mjs.map +1 -1
package/public-api.d.ts
CHANGED
|
@@ -106,7 +106,10 @@ type CliProcessCommand = {
|
|
|
106
106
|
*/
|
|
107
107
|
command: string;
|
|
108
108
|
/**
|
|
109
|
-
*
|
|
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\
|
|
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 = "\
|
|
230
|
-
Extension = "\
|
|
231
|
-
Module = "\
|
|
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 = "\
|
|
236
|
+
Variable = "\uD835\uDC65",// Variable or setting
|
|
234
237
|
Script = "\uD83D\uDCDC",// Script or code
|
|
235
|
-
Code = "\uD83D\
|
|
236
|
-
Logs = "\uD83D\
|
|
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
|
-
*
|
|
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
|
-
*
|
|
571
|
-
* @param prompt The prompt text to
|
|
572
|
-
* @
|
|
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
|
-
*
|
|
577
|
-
* @param prompt The prompt text to
|
|
578
|
-
* @returns The entered password,
|
|
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
|
-
*
|
|
583
|
-
* @param prompt The prompt text to
|
|
584
|
-
* @param defaultValue
|
|
585
|
-
* @returns true for yes, false for no,
|
|
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
|
-
*
|
|
590
|
-
* @param prompt The prompt text to
|
|
591
|
-
* @param options
|
|
592
|
-
* @param
|
|
593
|
-
* @returns The
|
|
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[],
|
|
790
|
+
readSelect(prompt: string, options: CliSelectOption[], selectOptions?: CliSelectOptions): Promise<string | null>;
|
|
596
791
|
/**
|
|
597
|
-
*
|
|
598
|
-
*
|
|
599
|
-
* @param
|
|
600
|
-
* @param
|
|
601
|
-
* @
|
|
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[],
|
|
798
|
+
readSelectInline(prompt: string, options: CliSelectOption[], selectOptions?: CliSelectOptions): Promise<string | null>;
|
|
605
799
|
/**
|
|
606
|
-
*
|
|
607
|
-
*
|
|
608
|
-
* @param
|
|
609
|
-
* @param
|
|
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
|
-
*
|
|
615
|
-
* @param prompt The prompt text to
|
|
616
|
-
* @param options Optional
|
|
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
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
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
|
-
*
|
|
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:
|
|
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?:
|
|
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
|
-
/**
|
|
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()
|
|
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)
|
|
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
|
|
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
|
|
1281
|
-
* @
|
|
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
|
|
1491
|
-
* @returns void
|
|
1729
|
+
* @param message The message to write
|
|
1492
1730
|
*/
|
|
1493
|
-
writeSuccess
|
|
1731
|
+
writeSuccess(message: string): void;
|
|
1494
1732
|
/**
|
|
1495
1733
|
* Write an info message to the terminal
|
|
1496
|
-
* @param
|
|
1497
|
-
* @returns void
|
|
1734
|
+
* @param message The message to write
|
|
1498
1735
|
*/
|
|
1499
|
-
writeInfo
|
|
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
|
|
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
|
|
1746
|
+
writeWarning(message: string): void;
|
|
1512
1747
|
/**
|
|
1513
|
-
*
|
|
1514
|
-
* @param
|
|
1515
|
-
* @param color The color to
|
|
1516
|
-
* @returns
|
|
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
|
|
1753
|
+
wrapInColor(text: string, color: CliForegroundColor): string;
|
|
1519
1754
|
/**
|
|
1520
|
-
*
|
|
1521
|
-
* @param
|
|
1522
|
-
* @param color The background color to
|
|
1523
|
-
* @returns
|
|
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
|
|
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
|
|
1765
|
+
writeJson(json: any): void;
|
|
1532
1766
|
/**
|
|
1533
|
-
* Write content to a file
|
|
1534
|
-
* @param fileName The name of the file 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
|
|
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
|
|
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
|
-
*
|
|
1614
|
-
* @param
|
|
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
|
-
*
|
|
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
|
|
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
|
-
*
|
|
1785
|
-
*
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
*
|
|
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
|
-
*
|
|
1964
|
-
* @param service The
|
|
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
|
-
*
|
|
1969
|
-
* @param definition
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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>) =>
|
|
2551
|
+
getParameterValue: (p: ICliCommandParameterDescriptor, args: Record<string, any>) => unknown;
|
|
2186
2552
|
formatJson: (json: any) => string;
|
|
2187
|
-
colorizeJson: (jsonString:
|
|
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.
|
|
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?:
|
|
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 };
|