@flowscripter/dynamic-cli-framework 1.2.2 → 1.3.1

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.
Files changed (166) hide show
  1. package/README/core-service-providers.md +2 -2
  2. package/README/development.md +3 -6
  3. package/README/implementation-details.md +17 -17
  4. package/README/key-concepts.md +17 -17
  5. package/README.md +4 -4
  6. package/bun.lock +0 -2
  7. package/index.ts +22 -30
  8. package/package.json +19 -19
  9. package/src/api/argument/Argument.ts +1 -1
  10. package/src/api/argument/ArgumentValueTypes.ts +3 -10
  11. package/src/api/argument/ComplexOption.ts +5 -9
  12. package/src/api/command/GlobalCommand.ts +1 -4
  13. package/src/api/service/core/ArgumentPrompterService.ts +1 -3
  14. package/src/api/service/core/AsciiBannerGeneratorService.ts +1 -4
  15. package/src/api/service/core/CompletionService.ts +2 -6
  16. package/src/api/service/core/ImagePrinterService.ts +1 -2
  17. package/src/api/service/core/KeyValueService.ts +1 -2
  18. package/src/api/service/core/PrettyPrinterService.ts +1 -4
  19. package/src/api/service/core/PrinterService.ts +8 -9
  20. package/src/api/service/core/PrompterService.ts +4 -11
  21. package/src/api/service/core/ShutdownService.ts +1 -2
  22. package/src/api/service/core/SyntaxHighlighterService.ts +1 -5
  23. package/src/api/service/core/Table.ts +7 -25
  24. package/src/api/service/core/TreePrinterService.ts +1 -2
  25. package/src/cli/BaseCLI.ts +17 -47
  26. package/src/cli/DefaultRuntimeCLI.ts +1 -4
  27. package/src/command/CompletionCommand.ts +19 -45
  28. package/src/command/MultiCommandCliHelpCommand.ts +45 -92
  29. package/src/command/SingleCommandCliHelpCommand.ts +17 -28
  30. package/src/command/UsageCommand.ts +6 -12
  31. package/src/command/VersionCommand.ts +2 -6
  32. package/src/launcher.ts +4 -2
  33. package/src/runtime/DefaultContext.ts +2 -5
  34. package/src/runtime/argument/ArgumentTypeGuards.ts +1 -3
  35. package/src/runtime/command/CommandTypeGuards.ts +5 -14
  36. package/src/runtime/command/CommandValidator.ts +56 -118
  37. package/src/runtime/parser.ts +13 -17
  38. package/src/runtime/registry/CommandRegistry.ts +2 -7
  39. package/src/runtime/registry/DefaultCommandRegistry.ts +32 -84
  40. package/src/runtime/registry/DefaultServiceProviderRegistry.ts +3 -9
  41. package/src/runtime/runner.ts +103 -142
  42. package/src/runtime/scanner.ts +28 -46
  43. package/src/runtime/values/ValuePopulationResult.ts +1 -2
  44. package/src/runtime/values/argumentValueMerge.ts +16 -28
  45. package/src/runtime/values/argumentValueValidation.ts +21 -67
  46. package/src/runtime/values/globalCommandValuePopulation.ts +9 -18
  47. package/src/runtime/values/subCommandValuePopulation.ts +42 -65
  48. package/src/service/argumentPrompter/ArgumentPrompterServiceProvider.ts +3 -10
  49. package/src/service/argumentPrompter/DefaultArgumentPrompterService.ts +22 -59
  50. package/src/service/asciiBannerGenerator/AsciiBannerGeneratorServiceProvider.ts +5 -14
  51. package/src/service/asciiBannerGenerator/DefaultAsciiBannerGeneratorService.ts +59 -77
  52. package/src/service/banner/BannerServiceProvider.ts +13 -35
  53. package/src/service/banner/command/NoBannerCommand.ts +2 -8
  54. package/src/service/chiselAsciiBannerGenerator/ChiselFontAsciiBannerGeneratorService.ts +5 -10
  55. package/src/service/completion/CompletionServiceProvider.ts +20 -48
  56. package/src/service/completion/DefaultCompletionService.ts +17 -56
  57. package/src/service/completion/shell/ShellHandler.ts +1 -3
  58. package/src/service/completion/shell/fish.ts +1 -1
  59. package/src/service/completion/shell/powershell.ts +2 -12
  60. package/src/service/completion/shell/zsh.ts +1 -1
  61. package/src/service/configuration/ConfigurationServiceProvider.ts +40 -133
  62. package/src/service/configuration/DefaultKeyValueService.ts +6 -20
  63. package/src/service/configuration/DefaultSecretService.ts +10 -14
  64. package/src/service/configuration/command/ConfigCommand.ts +1 -4
  65. package/src/service/configuration/command/DumpConfigCommand.ts +9 -21
  66. package/src/service/dataDumpGenerator/DataDumpGeneratorServiceProvider.ts +5 -14
  67. package/src/service/dataDumpGenerator/DefaultDataDumpGeneratorService.ts +5 -12
  68. package/src/service/imagePrinter/DefaultImagePrinterService.ts +1 -5
  69. package/src/service/imagePrinter/ImagePrinterServiceProvider.ts +1 -4
  70. package/src/service/prettyPrinter/DefaultPrettyPrinterService.ts +4 -12
  71. package/src/service/prettyPrinter/PrettyPrinterServiceProvider.ts +3 -10
  72. package/src/service/printer/DefaultPrinterService.ts +20 -83
  73. package/src/service/printer/PrinterServiceProvider.ts +3 -11
  74. package/src/service/printer/command/DarkModeCommand.ts +3 -10
  75. package/src/service/printer/command/LogLevelCommand.ts +7 -26
  76. package/src/service/printer/command/NoColorCommand.ts +3 -10
  77. package/src/service/printer/command/NoHyperlinksCommand.ts +3 -10
  78. package/src/service/printer/terminal/Progress.ts +99 -90
  79. package/src/service/printer/terminal/Spinner.ts +7 -26
  80. package/src/service/prompter/DefaultPrompterService.ts +2 -6
  81. package/src/service/prompter/PrompterServiceProvider.ts +3 -11
  82. package/src/service/prompter/command/NoPromptCommand.ts +3 -10
  83. package/src/service/prompter/prompt/PromptContext.ts +5 -18
  84. package/src/service/prompter/prompt/promptMultiSelect.ts +6 -21
  85. package/src/service/prompter/prompt/promptOpenUrl.ts +7 -22
  86. package/src/service/prompter/prompt/promptSingleSelect.ts +6 -23
  87. package/src/service/prompter/prompt/promptText.ts +10 -27
  88. package/src/service/prompter/prompt/promptToggle.ts +8 -8
  89. package/src/service/shutdown/ShutdownServiceProvider.ts +3 -10
  90. package/src/service/syntaxHighlighter/DefaultSyntaxHighlighterService.ts +13 -26
  91. package/src/service/syntaxHighlighter/SyntaxHighlighterServiceProvider.ts +8 -21
  92. package/src/service/tableGenerator/DefaultTableGeneratorService.ts +44 -68
  93. package/src/service/tableGenerator/TableGeneratorServiceProvider.ts +7 -16
  94. package/src/service/treePrinter/DefaultTreePrinterService.ts +2 -7
  95. package/src/service/treePrinter/TreePrinterServiceProvider.ts +4 -12
  96. package/src/terminal/ImageRenderer.ts +35 -54
  97. package/src/terminal/PngDecoder.ts +10 -19
  98. package/src/terminal/TtyStyler.ts +11 -9
  99. package/src/terminal/TtyTerminal.ts +2 -10
  100. package/src/terminal/supportsHyperlinks.ts +4 -10
  101. package/src/util/configHelper.ts +3 -10
  102. package/src/util/envVarHelper.ts +50 -88
  103. package/src/util/helpHelper.ts +123 -193
  104. package/src/util/logger.ts +12 -42
  105. package/src/util/runnerHelper.ts +20 -61
  106. package/tests/cli/BaseCLI.test.ts +23 -80
  107. package/tests/command/CompletionCommand.test.ts +1 -6
  108. package/tests/command/MultiCommandCliHelpCommand.test.ts +51 -205
  109. package/tests/command/SingleCommandCliHelpCommand.test.ts +21 -103
  110. package/tests/command/UsageCommand.test.ts +4 -10
  111. package/tests/fixtures/Command.ts +87 -68
  112. package/tests/fixtures/CommandRegistry.ts +1 -3
  113. package/tests/fixtures/Context.ts +3 -11
  114. package/tests/fixtures/ServiceProviderRegistry.ts +1 -1
  115. package/tests/fixtures/prettierPluginFoo.ts +1 -1
  116. package/tests/fixtures/util.ts +2 -8
  117. package/tests/runtime/argument/ArgumentTypeGuards.test.ts +1 -3
  118. package/tests/runtime/command/CommandValidator.test.ts +881 -604
  119. package/tests/runtime/parser.test.ts +222 -246
  120. package/tests/runtime/registry/DefaultCommandRegistry.test.ts +15 -37
  121. package/tests/runtime/registry/DefaultServiceProviderRegistry.test.ts +2 -8
  122. package/tests/runtime/runner.test.ts +231 -281
  123. package/tests/runtime/scanner.test.ts +277 -475
  124. package/tests/runtime/values/argumentValueMerge.test.ts +133 -81
  125. package/tests/runtime/values/argumentValueValidation.test.ts +444 -588
  126. package/tests/runtime/values/globalCommandValuePopulation.test.ts +71 -253
  127. package/tests/runtime/values/subCommandValuePopulation.test.ts +1342 -1570
  128. package/tests/service/argumentPrompter/ArgumentPrompterServiceProvider.test.ts +3 -12
  129. package/tests/service/argumentPrompter/DefaultArgumentPrompterService.test.ts +36 -45
  130. package/tests/service/asciiBannerGenerator/AsciiBannerGeneratorServiceProvider.test.ts +2 -8
  131. package/tests/service/asciiBannerGenerator/DefaultAsciiBannerGeneratorService.test.ts +40 -62
  132. package/tests/service/banner/BannerServiceProvider.test.ts +5 -18
  133. package/tests/service/banner/command/NoBannerCommand.test.ts +1 -4
  134. package/tests/service/completion/CompletionServiceProvider.test.ts +145 -214
  135. package/tests/service/completion/DefaultCompletionService.test.ts +17 -79
  136. package/tests/service/completion/shell/fish.test.ts +1 -3
  137. package/tests/service/configuration/ConfigurationServiceProvider.test.ts +26 -75
  138. package/tests/service/configuration/DefaultKeyValueService.test.ts +9 -21
  139. package/tests/service/configuration/DefaultSecretService.test.ts +7 -15
  140. package/tests/service/configuration/command/DumpConfigCommand.test.ts +4 -13
  141. package/tests/service/dataDumpGenerator/DataDumpGeneratorServiceProvider.test.ts +6 -12
  142. package/tests/service/dataDumpGenerator/DefaultDataDumpGeneratorService.test.ts +1 -10
  143. package/tests/service/imagePrinter/DefaultImagePrinterService.test.ts +5 -70
  144. package/tests/service/prettyPrinter/DefaultPrettyPrinterService.test.ts +4 -11
  145. package/tests/service/prettyPrinter/PrettyPrinterServiceProvider.test.ts +2 -6
  146. package/tests/service/printer/DefaultPrinterService.test.ts +57 -255
  147. package/tests/service/printer/PrinterServiceProvider.test.ts +2 -8
  148. package/tests/service/printer/command/DarkModeCommand.test.ts +4 -12
  149. package/tests/service/printer/command/LogLevelCommand.test.ts +4 -17
  150. package/tests/service/printer/command/NoColorCommand.test.ts +4 -12
  151. package/tests/service/printer/command/NoHyperlinksCommand.test.ts +7 -21
  152. package/tests/service/printer/terminal/Progress.test.ts +1 -3
  153. package/tests/service/printer/terminal/Spinner.test.ts +2 -8
  154. package/tests/service/prompter/DefaultPrompterService.test.ts +52 -69
  155. package/tests/service/prompter/PrompterServiceProvider.test.ts +2 -8
  156. package/tests/service/shutdown/ShutdownServiceProvider.test.ts +1 -3
  157. package/tests/service/syntaxHighlighter/DefaultSyntaxHighlighterService.test.ts +13 -99
  158. package/tests/service/syntaxHighlighter/SyntaxHighlighterServiceProvider.test.ts +2 -7
  159. package/tests/service/tableGenerator/DefaultTableGeneratorService.test.ts +12 -33
  160. package/tests/service/tableGenerator/TableGeneratorServiceProvider.test.ts +2 -2
  161. package/tests/service/treePrinter/DefaultTreePrinterService.test.ts +4 -6
  162. package/tests/service/treePrinter/TreePrinterServiceProvider.test.ts +4 -8
  163. package/tests/terminal/ImageRenderer.test.ts +2 -11
  164. package/tests/terminal/PngDecoder.test.ts +2 -6
  165. package/tests/util/configHelper.test.ts +55 -137
  166. package/tests/util/envVarHelper.test.ts +46 -110
@@ -149,8 +149,8 @@ Handles SIGINT (Ctrl-C) and SIGTERM signals:
149
149
  - **Long-running mode**: Commands can opt in via `enterLongRunningMode()`. In
150
150
  this mode, the first SIGINT sets a cooperative `isShutdownRequested` flag that
151
151
  the command can poll. A third SIGINT forces graceful shutdown and exit.
152
- - **SIGTERM**: Always triggers immediate graceful shutdown and exits with code
153
- 143.
152
+ - **SIGTERM**: Always triggers immediate graceful shutdown and exits with
153
+ code 143.
154
154
 
155
155
  Cooperative cancellation pattern which can be used in a long running command:
156
156
 
@@ -8,20 +8,17 @@ Test:
8
8
 
9
9
  `bun test`
10
10
 
11
- **NOTE**: The following tasks use Deno as it excels at these and Bun does not
12
- currently provide such functionality:
13
-
14
11
  Format:
15
12
 
16
- `deno fmt`
13
+ `bunx oxfmt`
17
14
 
18
15
  Lint:
19
16
 
20
- `deno lint index.ts src/ tests/`
17
+ `bunx oxlint index.ts src/ tests/`
21
18
 
22
19
  Generate HTML API Documentation:
23
20
 
24
- `deno doc --html --name=template-bun-library index.ts`
21
+ `bunx typedoc --readme none index.ts`
25
22
 
26
23
  ### Debug Logging
27
24
 
@@ -100,11 +100,11 @@ classDiagram
100
100
  BaseCLI --> CLIConfig
101
101
 
102
102
  Context --> ServiceProviderRegistry
103
-
103
+
104
104
  ServiceProvider --> ServiceXYZ : provides
105
105
 
106
106
  Context --> ServiceXYZ : access to
107
-
107
+
108
108
  DefaultRuntimeCLI <-- launcher
109
109
  ```
110
110
 
@@ -189,26 +189,26 @@ flowchart TD
189
189
  subgraph 1 [for each ServiceProvider in servicePriority order:]
190
190
 
191
191
  B([scan args for provided\nGlobalModifierCommand clauses])
192
-
192
+
193
193
  subgraph 2 [for each discovered clause:]
194
194
  C([set default\narg values])
195
195
  D([parse args])
196
196
  E([add to list of\nGlobalModifierCommands\nclauses to execute])
197
197
  end
198
-
198
+
199
199
  F([scan default arg values for provided\nGlobalModifierCommand clauses])
200
-
200
+
201
201
  subgraph 3 [for each discovered clause:]
202
202
  G([parse args])
203
203
  H([add to list of\nGlobalModifierCommands\nclauses to execute])
204
204
  end
205
-
205
+
206
206
  I([order GlobalModifierCommands\nclauses by executePriority])
207
-
207
+
208
208
  subgraph 4 [for each discovered clause:]
209
209
  J([execute GlobalModifierCommand])
210
210
  end
211
-
211
+
212
212
  K([init service provided by ServiceProvider])
213
213
  end
214
214
 
@@ -259,7 +259,7 @@ flowchart TD
259
259
 
260
260
  M --> N
261
261
  N --> O
262
-
262
+
263
263
  Q --> R
264
264
 
265
265
  A --> 1
@@ -281,27 +281,27 @@ flowchart TD
281
281
  V --> |no|W
282
282
  W --> |yes|W1
283
283
  W --> |no|Z
284
-
284
+
285
285
  V1 --> V2
286
286
  V2 --> V3
287
287
  V3 --> Z
288
-
288
+
289
289
  W1 --> W2
290
290
  W2 --> |yes|W21
291
291
  W2 --> |no|W3
292
-
292
+
293
293
  W21 --> W22
294
294
  W22 --> W23
295
-
295
+
296
296
  W23 --> |yes|W24
297
297
  W23 --> |no|Z
298
-
298
+
299
299
  W24 --> Z
300
-
300
+
301
301
  W3 --> W31
302
302
  W31 --> |yes|W32
303
303
  W31 --> |no|Z
304
-
304
+
305
305
  W32 --> Z
306
306
  ```
307
307
 
@@ -356,7 +356,7 @@ Apart from global modifier commands, there is expected to be only one command
356
356
  specified i.e. these will **NOT** work as intended:
357
357
 
358
358
  // not valid - sub-command 2 and arguments will be treated as trailing arguments of sub-command 1.
359
- executable <sub_command_1> [sub_command_1_arguments] <sub_command_2> [sub_command_2_arguments]
359
+ executable <sub_command_1> [sub_command_1_arguments] <sub_command_2> [sub_command_2_arguments]
360
360
 
361
361
  // not valid - sub-command and arguments will be treated as trailing arguments of global command.
362
362
  executable --<global_command> <sub_command> [sub_command_arguments]
@@ -65,7 +65,7 @@ classDiagram
65
65
  CLI --> CommandRegistry
66
66
 
67
67
  CommandRegistry --> "*" Command : registers
68
-
68
+
69
69
  ServiceProviderRegistry --> "*" ServiceProvider : registers
70
70
 
71
71
  CLI --> "1..*" Command : executes
@@ -75,12 +75,12 @@ classDiagram
75
75
  Context --> CLIConfig
76
76
 
77
77
  Context --> "*" Service : access to
78
-
78
+
79
79
  ServiceProvider --> "*" Service : provides
80
80
 
81
81
  class PluginManager {
82
82
  }
83
-
83
+
84
84
  class Plugin {
85
85
  <<interface>>
86
86
  }
@@ -102,9 +102,9 @@ classDiagram
102
102
  Plugin --> "*" CommandFactory: implements
103
103
 
104
104
  Plugin --> "*" ServiceProviderFactory: implements
105
-
105
+
106
106
  CommandFactory --> "*" Command : provides
107
-
107
+
108
108
  ServiceProviderFactory --> "*" ServiceProvider : provides
109
109
  ```
110
110
 
@@ -198,31 +198,31 @@ classDiagram
198
198
  Argument <|-- SubCommandArgument
199
199
 
200
200
  Argument <|-- GlobalCommandArgument
201
-
201
+
202
202
  SubCommandArgument <|-- Option
203
203
 
204
204
  SubCommandArgument <|-- Positional
205
-
205
+
206
206
  Option <|-- ComplexOption
207
207
 
208
208
  Option "1..*" <-- ComplexOption : properties
209
209
 
210
210
  Command <|-- GroupCommand
211
-
211
+
212
212
  Option "0..*" <-- SubCommand
213
213
 
214
214
  Positional "0..*" <-- SubCommand
215
215
 
216
216
  GlobalCommand --> "0..1" GlobalCommandArgument
217
-
218
- Command <|-- SubCommand
219
-
220
- GlobalCommand <|-- GlobalModifierCommand
221
-
222
- Command <|-- GlobalCommand
223
-
224
- GroupCommand --> "1..*" SubCommand : memberSubCommands
225
-
217
+
218
+ Command <|-- SubCommand
219
+
220
+ GlobalCommand <|-- GlobalModifierCommand
221
+
222
+ Command <|-- GlobalCommand
223
+
224
+ GroupCommand --> "1..*" SubCommand : memberSubCommands
225
+
226
226
  SubCommand --> "0..*" UsageExample
227
227
  ```
228
228
 
package/README.md CHANGED
@@ -9,7 +9,7 @@
9
9
  > A framework for developing CLI applications which supports dynamic discovery
10
10
  > and installation of new commands
11
11
 
12
- [//]: # (TODO: Remove this when plugin support.)
12
+ [//]: # "TODO: Remove this when plugin support."
13
13
 
14
14
  NOTE: The dynamic aspect is still in development as it relies upon:
15
15
 
@@ -68,9 +68,9 @@ The following example projects are available:
68
68
  - [mpeg-sdl-tool](https://github.com/flowscripter/mpeg-sdl-tool) is a real world
69
69
  use case CLI application based on this framework.
70
70
 
71
- [//]: # (TODO: Add this when implemented.)
72
- [//]: # (- [example-cli-plugin]&#40;https://github.com/flowscripter/example-cli-plugin&#41; is an)
73
- [//]: # ( example command and service plugin based on this framework.)
71
+ [//]: # "TODO: Add this when implemented."
72
+ [//]: # "- [example-cli-plugin](https://github.com/flowscripter/example-cli-plugin) is an"
73
+ [//]: # "example command and service plugin based on this framework."
74
74
 
75
75
  ## Further Details
76
76
 
package/bun.lock CHANGED
@@ -61,8 +61,6 @@
61
61
 
62
62
  "undici-types": ["undici-types@7.24.6", "", {}, "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg=="],
63
63
 
64
- "bun-types/@types/node": ["@types/node@25.9.1", "", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-xfrlY7UD5rMJk3ZVJP8BNzS28J36YJg+xp+LPXV1TdWxr8uMH5A860QNxYDGQe/ylDSgjxE52Q9VnO7p75tJxg=="],
65
-
66
64
  "emphasize/highlight.js": ["highlight.js@11.9.0", "", {}, "sha512-fJ7cW7fQGCYAkgv4CPfwFHrfd/cLS4Hau96JuJ+ZTOWhjnhoeN1ub1tFmALm/+lW5z4WCAuAV9bm05AP0mS6Gw=="],
67
65
 
68
66
  "lowlight/highlight.js": ["highlight.js@11.9.0", "", {}, "sha512-fJ7cW7fQGCYAkgv4CPfwFHrfd/cLS4Hau96JuJ+ZTOWhjnhoeN1ub1tFmALm/+lW5z4WCAuAV9bm05AP0mS6Gw=="],
package/index.ts CHANGED
@@ -13,7 +13,9 @@ export {
13
13
  ComplexValueTypeName,
14
14
  } from "./src/api/argument/ArgumentValueTypes.ts";
15
15
  export type { default as ComplexOption } from "./src/api/argument/ComplexOption.ts";
16
+ export { MAXIMUM_COMPLEX_OPTION_NESTING_DEPTH } from "./src/api/argument/ComplexOption.ts";
16
17
  export type { default as SubCommandArgument } from "./src/api/argument/SubCommandArgument.ts";
18
+ export { MAXIMUM_ARGUMENT_ARRAY_SIZE } from "./src/api/argument/SubCommandArgument.ts";
17
19
  export type { default as GlobalCommandArgument } from "./src/api/argument/GlobalCommandArgument.ts";
18
20
  export type { default as Option } from "./src/api/argument/Option.ts";
19
21
  export type { default as Positional } from "./src/api/argument/Positional.ts";
@@ -27,10 +29,7 @@ export type { default as SubCommand } from "./src/api/command/SubCommand.ts";
27
29
  export type { default as UsageExample } from "./src/api/command/UsageExample.ts";
28
30
 
29
31
  // Service API
30
- export type {
31
- ServiceInfo,
32
- ServiceProvider,
33
- } from "./src/api/service/ServiceProvider.ts";
32
+ export type { ServiceInfo, ServiceProvider } from "./src/api/service/ServiceProvider.ts";
34
33
 
35
34
  // Registry API
36
35
  export type { default as CommandRegistry } from "./src/runtime/registry/CommandRegistry.ts";
@@ -64,18 +63,13 @@ export type { default as KeyValueService } from "./src/api/service/core/KeyValue
64
63
  export type { default as SecretService } from "./src/api/service/core/SecretService.ts";
65
64
  export { default as DefaultKeyValueService } from "./src/service/configuration/DefaultKeyValueService.ts";
66
65
  export { default as DefaultSecretService } from "./src/service/configuration/DefaultSecretService.ts";
66
+ export type { SecretsApi } from "./src/service/configuration/DefaultSecretService.ts";
67
+ export { default as ConfigCommand } from "./src/service/configuration/command/ConfigCommand.ts";
67
68
  export { default as ConfigurationServiceProvider } from "./src/service/configuration/ConfigurationServiceProvider.ts";
68
69
 
69
70
  export { PRINTER_SERVICE_ID } from "./src/api/service/core/PrinterService.ts";
70
- export type {
71
- default as PrinterService,
72
- } from "./src/api/service/core/PrinterService.ts";
73
- export {
74
- Icon,
75
- Level,
76
- ProgressStyle,
77
- SpinnerStyle,
78
- } from "./src/api/service/core/PrinterService.ts";
71
+ export type { default as PrinterService } from "./src/api/service/core/PrinterService.ts";
72
+ export { Icon, Level, ProgressStyle, SpinnerStyle } from "./src/api/service/core/PrinterService.ts";
79
73
  export { default as DefaultPrinterService } from "./src/service/printer/DefaultPrinterService.ts";
80
74
  export { default as PrinterServiceProvider } from "./src/service/printer/PrinterServiceProvider.ts";
81
75
 
@@ -131,10 +125,7 @@ export { default as DataDumpGeneratorServiceProvider } from "./src/service/dataD
131
125
 
132
126
  export { COMPLETION_SERVICE_ID } from "./src/api/service/core/CompletionService.ts";
133
127
  export type { default as CompletionService } from "./src/api/service/core/CompletionService.ts";
134
- export {
135
- type CompletionItem,
136
- ShellType,
137
- } from "./src/api/service/core/CompletionService.ts";
128
+ export { type CompletionItem, ShellType } from "./src/api/service/core/CompletionService.ts";
138
129
  export { default as DefaultCompletionService } from "./src/service/completion/DefaultCompletionService.ts";
139
130
  export { default as CompletionServiceProvider } from "./src/service/completion/CompletionServiceProvider.ts";
140
131
 
@@ -155,21 +146,28 @@ export { default as PrompterServiceProvider } from "./src/service/prompter/Promp
155
146
 
156
147
  export { ARGUMENT_PROMPTER_SERVICE_ID } from "./src/api/service/core/ArgumentPrompterService.ts";
157
148
  export type { default as ArgumentPrompterService } from "./src/api/service/core/ArgumentPrompterService.ts";
149
+ export type { ParseResult } from "./src/runtime/parser.ts";
158
150
  export { default as DefaultArgumentPrompterService } from "./src/service/argumentPrompter/DefaultArgumentPrompterService.ts";
159
151
  export { default as ArgumentPrompterServiceProvider } from "./src/service/argumentPrompter/ArgumentPrompterServiceProvider.ts";
160
152
 
161
153
  // CLI API
162
154
  export type { InvalidArgument } from "./src/api/RunResult.ts";
163
155
  export type { default as Context } from "./src/api/Context.ts";
164
- export type {
165
- default as RunResult,
166
- InvalidArgumentReason,
167
- RunState,
168
- } from "./src/api/RunResult.ts";
156
+ export type { default as RunResult, InvalidArgumentReason, RunState } from "./src/api/RunResult.ts";
169
157
  export type { default as BaseCLIFeatureOptions } from "./src/api/BaseCLIFeatureOptions.ts";
170
158
  export type { default as CLIConfig } from "./src/api/CLIConfig.ts";
171
159
  export type { default as CLI } from "./src/api/CLI.ts";
172
160
 
161
+ // Help Commands
162
+ export {
163
+ SingleCommandCliHelpGlobalCommand,
164
+ SingleCommandCliHelpSubCommand,
165
+ } from "./src/command/SingleCommandCliHelpCommand.ts";
166
+ export {
167
+ MultiCommandCliHelpGlobalCommand,
168
+ MultiCommandCliHelpSubCommand,
169
+ } from "./src/command/MultiCommandCliHelpCommand.ts";
170
+
173
171
  // Core CLI
174
172
  export { default as BaseCLI } from "./src/cli/BaseCLI.ts";
175
173
  export { default as DefaultRuntimeCLI } from "./src/cli/DefaultRuntimeCLI.ts";
@@ -177,15 +175,9 @@ export { default as DefaultRuntimeCLI } from "./src/cli/DefaultRuntimeCLI.ts";
177
175
  // Terminal API
178
176
  export type { default as Terminal } from "./src/terminal/Terminal.ts";
179
177
  export type { default as Styler } from "./src/terminal/Styler.ts";
180
- export type {
181
- default as KeyReader,
182
- KeyEvent,
183
- } from "./src/terminal/KeyReader.ts";
178
+ export type { default as KeyReader, KeyEvent } from "./src/terminal/KeyReader.ts";
184
179
  export { SpecialKey } from "./src/terminal/KeyReader.ts";
185
180
  export { default as TtyKeyReader } from "./src/terminal/TtyKeyReader.ts";
186
181
 
187
182
  // Convenience functions
188
- export {
189
- launchMultiCommandCLI,
190
- launchSingleCommandCLI,
191
- } from "./src/launcher.ts";
183
+ export { launchMultiCommandCLI, launchSingleCommandCLI } from "./src/launcher.ts";
package/package.json CHANGED
@@ -1,34 +1,27 @@
1
1
  {
2
2
  "name": "@flowscripter/dynamic-cli-framework",
3
+ "version": "1.3.1",
3
4
  "description": "A framework for developing CLI applications which supports dynamic discovery and installation of new commands",
4
- "homepage": "https://github.com/flowscripter/dynamic-cli-framework#readme",
5
- "repository": {
6
- "type": "git",
7
- "url": "git+https://github.com/flowscripter/dynamic-cli-framework.git"
8
- },
9
- "license": "MIT",
10
5
  "keywords": [
11
6
  "bun",
12
- "plugin",
13
- "framework",
7
+ "cli",
14
8
  "dynamic",
15
- "import",
16
9
  "executable",
17
- "cli"
10
+ "framework",
11
+ "import",
12
+ "plugin"
18
13
  ],
19
- "module": "index.ts",
14
+ "homepage": "https://github.com/flowscripter/dynamic-cli-framework#readme",
15
+ "license": "MIT",
16
+ "repository": {
17
+ "type": "git",
18
+ "url": "git+https://github.com/flowscripter/dynamic-cli-framework.git"
19
+ },
20
20
  "type": "module",
21
- "version": "1.2.2",
21
+ "module": "index.ts",
22
22
  "publishConfig": {
23
23
  "access": "public"
24
24
  },
25
- "devDependencies": {
26
- "@types/bun": "^1.3.14",
27
- "@types/node": "^25.9.2"
28
- },
29
- "peerDependencies": {
30
- "typescript": "^6.0.3"
31
- },
32
25
  "dependencies": {
33
26
  "emphasize": "^7.0.0",
34
27
  "fastest-levenshtein": "^1.0.16",
@@ -37,5 +30,12 @@
37
30
  "prettier": "^3.8.3",
38
31
  "supports-color": "^10.2.2",
39
32
  "supports-terminal-graphics": "^0.1.0"
33
+ },
34
+ "devDependencies": {
35
+ "@types/bun": "^1.3.14",
36
+ "@types/node": "^25.9.2"
37
+ },
38
+ "peerDependencies": {
39
+ "typescript": "^6.0.3"
40
40
  }
41
41
  }
@@ -38,7 +38,7 @@ export default interface Argument {
38
38
  * Optional configuration key to use for the argument. Must consist of alphanumeric non-whitespace uppercase
39
39
  * ASCII or `_` characters. Must not start with a digit.
40
40
  *
41
- * If not specified a default configuration key is determined as follows: The {@link Argument.name} is capitalized
41
+ * If not specified a default configuration key is determined as follows: The {@link SubCommandArgument.name} is capitalized
42
42
  * and any `-` characters are replaced with `_` characters. If the result starts with a digit, it is
43
43
  * prefixed with `_`. Some examples:
44
44
  *
@@ -9,9 +9,7 @@ export type ArgumentSingleValueType = number | string | boolean;
9
9
  /**
10
10
  * The type of the value to be parsed as an argument can be: `boolean`, `number` or `string` or an array of these.
11
11
  */
12
- export type ArgumentValueType =
13
- | ArgumentSingleValueType
14
- | Array<ArgumentSingleValueType>;
12
+ export type ArgumentValueType = ArgumentSingleValueType | Array<ArgumentSingleValueType>;
15
13
 
16
14
  /**
17
15
  * A container object for populated argument values.
@@ -34,10 +32,7 @@ export type ArgumentValueType =
34
32
  * * `{ foo: [ [ 1, 2 ], [3, 4 ] ] }`
35
33
  */
36
34
  export type ArgumentValues = {
37
- [argName: string]:
38
- | ArgumentValueType
39
- | ArgumentValues
40
- | Array<ArgumentValues>;
35
+ [argName: string]: ArgumentValueType | ArgumentValues | Array<ArgumentValues>;
41
36
  };
42
37
 
43
38
  /**
@@ -62,9 +57,7 @@ export enum ComplexValueTypeName {
62
57
  * Populated single value type is very similar to {@link ArgumentSingleValueType} but allows for an illegal
63
58
  * undefined value.
64
59
  */
65
- export type PopulatedArgumentSingleValueType =
66
- | ArgumentSingleValueType
67
- | undefined;
60
+ export type PopulatedArgumentSingleValueType = ArgumentSingleValueType | undefined;
68
61
 
69
62
  /**
70
63
  * Populated argument value types are very similar to {@link ArgumentValueType} but allow for illegal
@@ -1,19 +1,15 @@
1
1
  import type Option from "./Option.ts";
2
- import type {
3
- ArgumentValues,
4
- ComplexValueTypeName,
5
- } from "./ArgumentValueTypes.ts";
2
+ import type { ArgumentValues, ComplexValueTypeName } from "./ArgumentValueTypes.ts";
6
3
 
7
4
  export const MAXIMUM_COMPLEX_OPTION_NESTING_DEPTH = 10;
8
5
 
9
6
  /**
10
7
  * A container option argument for defining {@link SubCommand} nested argument hierarchies.
11
8
  */
12
- export default interface ComplexOption extends
13
- Omit<
14
- Option,
15
- "type" | "defaultValue" | "allowableValues"
16
- > {
9
+ export default interface ComplexOption extends Omit<
10
+ Option,
11
+ "type" | "defaultValue" | "allowableValues"
12
+ > {
17
13
  /**
18
14
  * Type of the argument value.
19
15
  */
@@ -26,8 +26,5 @@ export default interface GlobalCommand extends Command {
26
26
  * @param argumentValue optional argument value for the command. This will be populated unless
27
27
  * the command's {@link GlobalCommandArgument} is optional and the argument value was not provided.
28
28
  */
29
- execute(
30
- context: Context,
31
- argumentValue?: ArgumentSingleValueType,
32
- ): Promise<void>;
29
+ execute(context: Context, argumentValue?: ArgumentSingleValueType): Promise<void>;
33
30
  }
@@ -4,7 +4,5 @@ export const ARGUMENT_PROMPTER_SERVICE_ID =
4
4
  "@flowscripter/dynamic-cli-framework/argument-prompter-service";
5
5
 
6
6
  export default interface ArgumentPrompterService {
7
- promptForMissingArguments(
8
- parseResult: ParseResult,
9
- ): Promise<ParseResult>;
7
+ promptForMissingArguments(parseResult: ParseResult): Promise<ParseResult>;
10
8
  }
@@ -22,10 +22,7 @@ export interface RainbowColorEffect {
22
22
  direction: ColorEffectDirection;
23
23
  }
24
24
 
25
- export type ColorEffect =
26
- | FixedColorEffect
27
- | GradientColorEffect
28
- | RainbowColorEffect;
25
+ export type ColorEffect = FixedColorEffect | GradientColorEffect | RainbowColorEffect;
29
26
 
30
27
  export interface BannerColorEffects {
31
28
  background?: ColorEffect;
@@ -1,5 +1,4 @@
1
- export const COMPLETION_SERVICE_ID =
2
- "@flowscripter/dynamic-cli-framework/completion-service";
1
+ export const COMPLETION_SERVICE_ID = "@flowscripter/dynamic-cli-framework/completion-service";
3
2
 
4
3
  export enum ShellType {
5
4
  BASH = "bash",
@@ -29,8 +28,5 @@ export default interface CompletionService {
29
28
 
30
29
  validateShellEnvironment(shellType: ShellType): Promise<boolean>;
31
30
 
32
- formatCompletions(
33
- shellType: ShellType,
34
- completions: ReadonlyArray<CompletionItem>,
35
- ): string;
31
+ formatCompletions(shellType: ShellType, completions: ReadonlyArray<CompletionItem>): string;
36
32
  }
@@ -1,5 +1,4 @@
1
- export const IMAGE_PRINTER_SERVICE_ID =
2
- "@flowscripter/dynamic-cli-framework/image-printer-service";
1
+ export const IMAGE_PRINTER_SERVICE_ID = "@flowscripter/dynamic-cli-framework/image-printer-service";
3
2
 
4
3
  /**
5
4
  * Service for rendering images in the terminal.
@@ -1,5 +1,4 @@
1
- export const KEY_VALUE_SERVICE_ID =
2
- "@flowscripter/dynamic-cli-framework/key-value-service";
1
+ export const KEY_VALUE_SERVICE_ID = "@flowscripter/dynamic-cli-framework/key-value-service";
3
2
 
4
3
  /**
5
4
  * The sentinel prefix used to indicate a value is stored as an OS-native secret.
@@ -22,10 +22,7 @@ export default interface PrettyPrinterService {
22
22
  * @param syntaxName the name used to refer to the syntax.
23
23
  * @param syntaxDefinition the definition for the syntax conforming to the Prettier plugin interface.
24
24
  */
25
- registerSyntax(
26
- syntaxName: string,
27
- syntaxDefinition: Plugin<unknown>,
28
- ): Promise<void>;
25
+ registerSyntax(syntaxName: string, syntaxDefinition: Plugin<unknown>): Promise<void>;
29
26
 
30
27
  /**
31
28
  * Return the names of the currently registered syntaxes.
@@ -1,5 +1,4 @@
1
- export const PRINTER_SERVICE_ID =
2
- "@flowscripter/dynamic-cli-framework/printer-service";
1
+ export const PRINTER_SERVICE_ID = "@flowscripter/dynamic-cli-framework/printer-service";
3
2
  import { WritableStream } from "node:stream/web";
4
3
 
5
4
  /**
@@ -276,7 +275,7 @@ export default interface PrinterService {
276
275
  print(message: string, icon?: Icon): Promise<void>;
277
276
 
278
277
  /**
279
- * Print a {@link DEBUG} level message on `stderr`.
278
+ * Print a {@link Level.DEBUG} level message on `stderr`.
280
279
  * Will be displayed as secondary content if {@link colorEnabled} is `true`.
281
280
  *
282
281
  * @param message the message to output.
@@ -285,7 +284,7 @@ export default interface PrinterService {
285
284
  debug(message: string, icon?: Icon): Promise<void>;
286
285
 
287
286
  /**
288
- * Print an {@link INFO} level message on `stderr`.
287
+ * Print an {@link Level.INFO} level message on `stderr`.
289
288
  * Will be displayed as primary content if {@link colorEnabled} is `true`.
290
289
  *
291
290
  * @param message the message to output.
@@ -294,7 +293,7 @@ export default interface PrinterService {
294
293
  info(message: string, icon?: Icon): Promise<void>;
295
294
 
296
295
  /**
297
- * Print a {@link WARN} level message on `stderr`.
296
+ * Print a {@link Level.WARN} level message on `stderr`.
298
297
  * Will be displayed as yellow content if {@link colorEnabled} is `true`.
299
298
  *
300
299
  * @param message the message to output.
@@ -303,7 +302,7 @@ export default interface PrinterService {
303
302
  warn(message: string, icon?: Icon): Promise<void>;
304
303
 
305
304
  /**
306
- * Print an {@link ERROR} level message on `stderr`.
305
+ * Print an {@link Level.ERROR} level message on `stderr`.
307
306
  * Will be displayed as red content if {@link colorEnabled} is `true`.
308
307
  *
309
308
  * @param message the message to output.
@@ -314,7 +313,7 @@ export default interface PrinterService {
314
313
  /**
315
314
  * Set the output threshold {@link Level} for `stderr`.
316
315
  *
317
- * Default level is {@link INFO}.
316
+ * Default level is {@link Level.INFO}.
318
317
  *
319
318
  * @param level any message below this level will be filtered from output,
320
319
  */
@@ -331,7 +330,7 @@ export default interface PrinterService {
331
330
  * The spinner will be displayed as emphasised content and the message will
332
331
  * be displayed as primary content if {@link colorEnabled} is `true`.
333
332
  *
334
- * NOTE: The spinner and message will be displayed at {@link INFO} level.
333
+ * NOTE: The spinner and message will be displayed at {@link Level.INFO} level.
335
334
  *
336
335
  * NOTE: If the spinner is already displayed the message will be updated to that specified.
337
336
  *
@@ -354,7 +353,7 @@ export default interface PrinterService {
354
353
  *
355
354
  * The progress will be displayed in green if {@link colorEnabled} is `true`.
356
355
  *
357
- * NOTE: The progress bar and message will be displayed at {@link INFO} level.
356
+ * NOTE: The progress bar and message will be displayed at {@link Level.INFO} level.
358
357
  *
359
358
  * NOTE: If the spinner is currently displayed it will be hidden.
360
359
  *