@kjanat/dreamcli 4.0.0-rc.3 → 4.0.0

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 (212) hide show
  1. package/README.md +5 -7
  2. package/dist/{runtime/adapter.d.mts → adapter-D0hbBNVB.d.mts} +2 -4
  3. package/dist/completion-D4mz6axB.mjs +6 -0
  4. package/dist/completion.d.mts +90 -0
  5. package/dist/completion.mjs +1 -0
  6. package/dist/config-B9ddC-Kb.mjs +1 -0
  7. package/dist/config.d.mts +2 -0
  8. package/dist/config.mjs +1 -0
  9. package/dist/core-Cp2w8vRq.mjs +17 -0
  10. package/dist/index-BziI2aKc.d.mts +5440 -0
  11. package/dist/index-DOfClfYR.d.mts +370 -0
  12. package/dist/index-DWsnGZlx.d.mts +831 -0
  13. package/dist/{core/cli/index.d.mts → index-DXROeDPC.d.mts} +116 -57
  14. package/dist/index-DndPmT8J.d.mts +275 -0
  15. package/dist/{core/json-schema/index.d.mts → index-DyoaS234.d.mts} +43 -34
  16. package/dist/index.d.mts +190 -41
  17. package/dist/index.mjs +1 -26
  18. package/dist/json-schema-C9SzZ7jY.mjs +52 -0
  19. package/dist/json-schema.d.mts +2 -0
  20. package/dist/json-schema.mjs +1 -0
  21. package/dist/package-json-BgE9YjjQ.mjs +3 -0
  22. package/dist/prompt.d.mts +48 -0
  23. package/dist/prompt.mjs +1 -0
  24. package/dist/rolldown-runtime-G4Kt5YOX.mjs +1 -0
  25. package/dist/runtime.d.mts +2 -6
  26. package/dist/runtime.mjs +1 -6
  27. package/dist/terminal-C8KTXjv5.mjs +6 -0
  28. package/dist/test-prompter-v__jT2yG.mjs +1 -0
  29. package/dist/testkit.d.mts +54 -6
  30. package/dist/testkit.mjs +1 -5
  31. package/dist/version.mjs +1 -7
  32. package/dreamcli.schema.json +697 -538
  33. package/package.json +29 -7
  34. package/skills/cli-creation/SKILL.md +16 -11
  35. package/CHANGELOG.md +0 -1116
  36. package/dist/core/cli/builtins.d.mts +0 -117
  37. package/dist/core/cli/builtins.mjs +0 -135
  38. package/dist/core/cli/compiled.d.mts +0 -66
  39. package/dist/core/cli/compiled.mjs +0 -76
  40. package/dist/core/cli/dispatch.d.mts +0 -115
  41. package/dist/core/cli/dispatch.mjs +0 -205
  42. package/dist/core/cli/help-links.d.mts +0 -27
  43. package/dist/core/cli/help-links.mjs +0 -41
  44. package/dist/core/cli/index.mjs +0 -1271
  45. package/dist/core/cli/planner.d.mts +0 -174
  46. package/dist/core/cli/planner.mjs +0 -323
  47. package/dist/core/cli/plugin.d.mts +0 -94
  48. package/dist/core/cli/plugin.mjs +0 -41
  49. package/dist/core/cli/propagate.d.mts +0 -39
  50. package/dist/core/cli/propagate.mjs +0 -57
  51. package/dist/core/cli/reserved-flags.d.mts +0 -19
  52. package/dist/core/cli/reserved-flags.mjs +0 -158
  53. package/dist/core/cli/root-help.d.mts +0 -53
  54. package/dist/core/cli/root-help.mjs +0 -221
  55. package/dist/core/cli/root-output-flags.d.mts +0 -74
  56. package/dist/core/cli/root-output-flags.mjs +0 -169
  57. package/dist/core/cli/root-surface.d.mts +0 -64
  58. package/dist/core/cli/root-surface.mjs +0 -28
  59. package/dist/core/cli/runtime-preflight.d.mts +0 -213
  60. package/dist/core/cli/runtime-preflight.mjs +0 -221
  61. package/dist/core/completion/index.d.mts +0 -76
  62. package/dist/core/completion/index.mjs +0 -90
  63. package/dist/core/completion/shells/bash.d.mts +0 -23
  64. package/dist/core/completion/shells/bash.mjs +0 -312
  65. package/dist/core/completion/shells/fish.d.mts +0 -19
  66. package/dist/core/completion/shells/fish.mjs +0 -164
  67. package/dist/core/completion/shells/powershell.d.mts +0 -13
  68. package/dist/core/completion/shells/powershell.mjs +0 -360
  69. package/dist/core/completion/shells/shared.d.mts +0 -164
  70. package/dist/core/completion/shells/shared.mjs +0 -147
  71. package/dist/core/completion/shells/zsh.d.mts +0 -23
  72. package/dist/core/completion/shells/zsh.mjs +0 -256
  73. package/dist/core/config/index.d.mts +0 -191
  74. package/dist/core/config/index.mjs +0 -285
  75. package/dist/core/config/package-json.d.mts +0 -179
  76. package/dist/core/config/package-json.mjs +0 -353
  77. package/dist/core/errors/index.d.mts +0 -125
  78. package/dist/core/errors/index.mjs +0 -87
  79. package/dist/core/execution/index.d.mts +0 -61
  80. package/dist/core/execution/index.mjs +0 -220
  81. package/dist/core/help/ansi.d.mts +0 -84
  82. package/dist/core/help/ansi.mjs +0 -121
  83. package/dist/core/help/index.d.mts +0 -149
  84. package/dist/core/help/index.mjs +0 -418
  85. package/dist/core/help/theme.d.mts +0 -86
  86. package/dist/core/help/theme.mjs +0 -69
  87. package/dist/core/json-schema/index.mjs +0 -1008
  88. package/dist/core/json-schema/meta-descriptions.generated.d.mts +0 -274
  89. package/dist/core/json-schema/meta-descriptions.generated.mjs +0 -136
  90. package/dist/core/output/activity.d.mts +0 -193
  91. package/dist/core/output/activity.mjs +0 -452
  92. package/dist/core/output/bind.d.mts +0 -37
  93. package/dist/core/output/bind.mjs +0 -56
  94. package/dist/core/output/contracts.d.mts +0 -82
  95. package/dist/core/output/contracts.mjs +0 -57
  96. package/dist/core/output/display-value.d.mts +0 -19
  97. package/dist/core/output/display-value.mjs +0 -32
  98. package/dist/core/output/index.d.mts +0 -344
  99. package/dist/core/output/index.mjs +0 -514
  100. package/dist/core/output/renderers.d.mts +0 -45
  101. package/dist/core/output/renderers.mjs +0 -46
  102. package/dist/core/output/writer.d.mts +0 -39
  103. package/dist/core/output/writer.mjs +0 -12
  104. package/dist/core/parse/index.d.mts +0 -178
  105. package/dist/core/parse/index.mjs +0 -850
  106. package/dist/core/parse/occurrences.d.mts +0 -90
  107. package/dist/core/parse/occurrences.mjs +0 -114
  108. package/dist/core/prompt/index.d.mts +0 -213
  109. package/dist/core/prompt/index.mjs +0 -348
  110. package/dist/core/read-flags/index.d.mts +0 -150
  111. package/dist/core/read-flags/index.mjs +0 -217
  112. package/dist/core/resolve/args.d.mts +0 -39
  113. package/dist/core/resolve/args.mjs +0 -182
  114. package/dist/core/resolve/coerce.d.mts +0 -79
  115. package/dist/core/resolve/coerce.mjs +0 -900
  116. package/dist/core/resolve/config.d.mts +0 -10
  117. package/dist/core/resolve/config.mjs +0 -19
  118. package/dist/core/resolve/contracts.d.mts +0 -146
  119. package/dist/core/resolve/errors.d.mts +0 -10
  120. package/dist/core/resolve/errors.mjs +0 -148
  121. package/dist/core/resolve/flags.d.mts +0 -74
  122. package/dist/core/resolve/flags.mjs +0 -246
  123. package/dist/core/resolve/index.d.mts +0 -44
  124. package/dist/core/resolve/index.mjs +0 -123
  125. package/dist/core/resolve/path-checks.d.mts +0 -48
  126. package/dist/core/resolve/path-checks.mjs +0 -102
  127. package/dist/core/resolve/redaction.d.mts +0 -13
  128. package/dist/core/resolve/redaction.mjs +0 -14
  129. package/dist/core/resolve/stages.d.mts +0 -86
  130. package/dist/core/resolve/stages.mjs +0 -170
  131. package/dist/core/resolve/standard.d.mts +0 -26
  132. package/dist/core/resolve/standard.mjs +0 -212
  133. package/dist/core/schema/activity.d.mts +0 -189
  134. package/dist/core/schema/arg.d.mts +0 -1461
  135. package/dist/core/schema/arg.mjs +0 -1139
  136. package/dist/core/schema/brand.d.mts +0 -17
  137. package/dist/core/schema/cardinality.d.mts +0 -302
  138. package/dist/core/schema/cardinality.mjs +0 -514
  139. package/dist/core/schema/command.d.mts +0 -1132
  140. package/dist/core/schema/command.mjs +0 -999
  141. package/dist/core/schema/flag.d.mts +0 -1495
  142. package/dist/core/schema/flag.mjs +0 -1207
  143. package/dist/core/schema/index.d.mts +0 -15
  144. package/dist/core/schema/index.mjs +0 -10
  145. package/dist/core/schema/middleware.d.mts +0 -129
  146. package/dist/core/schema/middleware.mjs +0 -41
  147. package/dist/core/schema/number-constraints.d.mts +0 -96
  148. package/dist/core/schema/number-constraints.mjs +0 -60
  149. package/dist/core/schema/prompt.d.mts +0 -135
  150. package/dist/core/schema/provenance.d.mts +0 -99
  151. package/dist/core/schema/provenance.mjs +0 -28
  152. package/dist/core/schema/run.d.mts +0 -211
  153. package/dist/core/schema/source.d.mts +0 -180
  154. package/dist/core/schema/source.mjs +0 -206
  155. package/dist/core/schema/standard.d.mts +0 -100
  156. package/dist/core/schema/standard.mjs +0 -15
  157. package/dist/core/schema/stdin.d.mts +0 -97
  158. package/dist/core/schema/stdin.mjs +0 -91
  159. package/dist/core/schema/string-constraints.d.mts +0 -108
  160. package/dist/core/schema/string-constraints.mjs +0 -86
  161. package/dist/core/schema/value-parsers.d.mts +0 -150
  162. package/dist/core/schema/value-parsers.mjs +0 -160
  163. package/dist/core/schema/value.d.mts +0 -243
  164. package/dist/core/schema/value.mjs +0 -573
  165. package/dist/core/testkit/index.d.mts +0 -63
  166. package/dist/core/testkit/index.mjs +0 -102
  167. package/dist/runtime/adapter.mjs +0 -92
  168. package/dist/runtime/auto.d.mts +0 -25
  169. package/dist/runtime/auto.mjs +0 -45
  170. package/dist/runtime/deno.d.mts +0 -99
  171. package/dist/runtime/deno.mjs +0 -265
  172. package/dist/runtime/detect.d.mts +0 -86
  173. package/dist/runtime/detect.mjs +0 -45
  174. package/dist/runtime/index.d.mts +0 -6
  175. package/dist/runtime/node.d.mts +0 -71
  176. package/dist/runtime/node.mjs +0 -228
  177. package/dist/runtime/paths.d.mts +0 -31
  178. package/dist/runtime/paths.mjs +0 -48
  179. package/dist/strings.d.mts +0 -27
  180. package/dist/strings.mjs +0 -22
  181. package/examples/basic.ts +0 -37
  182. package/examples/flag-types.ts +0 -79
  183. package/examples/gh/package.json +0 -45
  184. package/examples/gh/src/commands/auth.ts +0 -66
  185. package/examples/gh/src/commands/issue.ts +0 -120
  186. package/examples/gh/src/commands/pr.ts +0 -125
  187. package/examples/gh/src/data/issues.yaml +0 -5
  188. package/examples/gh/src/data/issues.yaml.d.ts +0 -17
  189. package/examples/gh/src/data/pull-requests.yaml +0 -7
  190. package/examples/gh/src/data/pull-requests.yaml.d.ts +0 -18
  191. package/examples/gh/src/docs.ts +0 -11
  192. package/examples/gh/src/lib/auth.ts +0 -37
  193. package/examples/gh/src/lib/utils.ts +0 -17
  194. package/examples/gh/src/main.test.ts +0 -307
  195. package/examples/gh/src/main.ts +0 -46
  196. package/examples/help-config.ts +0 -43
  197. package/examples/interactive.ts +0 -67
  198. package/examples/json-mode.ts +0 -95
  199. package/examples/middleware.ts +0 -71
  200. package/examples/multi-command.ts +0 -66
  201. package/examples/output-extras.ts +0 -46
  202. package/examples/parser-control.ts +0 -40
  203. package/examples/pwsh-demo/README.md +0 -40
  204. package/examples/pwsh-demo/package.json +0 -41
  205. package/examples/pwsh-demo/pwsh-demo.cmd +0 -3
  206. package/examples/pwsh-demo/smoke-powershell.ps1 +0 -218
  207. package/examples/pwsh-demo/src/main.test.ts +0 -45
  208. package/examples/pwsh-demo/src/main.ts +0 -140
  209. package/examples/spinner-progress.ts +0 -49
  210. package/examples/standard-schema.ts +0 -45
  211. package/examples/testing.ts +0 -147
  212. package/examples/transport-launcher.ts +0 -85
@@ -1,117 +0,0 @@
1
- import { schemaBrand } from "../schema/brand.mjs";
2
- //#region src/core/cli/builtins.d.ts
3
- /** A built-in flag a consumer can take over. */
4
- type BuiltinName = 'help' | 'json' | 'quiet';
5
- /** Whether the root keeps a built-in or releases it to commands. */
6
- type BuiltinMode = 'on' | 'off';
7
- /**
8
- * Built-in flag settings accepted by {@linkcode CLIBuilder.builtins} and the
9
- * `builtins` field of {@link CLIDefinition}.
10
- *
11
- * `version` and `completions` are absent by design: `.version()` and
12
- * `.completions()` are opt-in, so a CLI declines those two by not calling them.
13
- */
14
- interface BuiltinsConfig {
15
- /**
16
- * Root `--help`/`-h`, command-level `--help`/`-h`, and the bare `help` token.
17
- * @defaultValue `'on'`
18
- */
19
- readonly help?: BuiltinMode;
20
- /**
21
- * Root `--json`.
22
- * @defaultValue `'on'`
23
- */
24
- readonly json?: BuiltinMode;
25
- /**
26
- * Root `--quiet`/`-q`.
27
- * @defaultValue `'on'`
28
- */
29
- readonly quiet?: BuiltinMode;
30
- }
31
- /**
32
- * Normalized built-in flag state stored on {@link CLISchema}.
33
- *
34
- * Sealed by {@link createCLISchema}; every key is present after normalization.
35
- */
36
- interface Builtins {
37
- /** Type-only seal produced by {@link createCLISchema}. */
38
- readonly [schemaBrand]: 'builtins';
39
- /** Whether the root owns `--help`/`-h` and the bare `help` token. */
40
- readonly help: BuiltinMode;
41
- /** Whether the root owns `--json`. */
42
- readonly json: BuiltinMode;
43
- /** Whether the root owns `--quiet`/`-q`. */
44
- readonly quiet: BuiltinMode;
45
- }
46
- /**
47
- * {@link Builtins} before the type-only seal is applied.
48
- *
49
- * @internal
50
- */
51
- type BuiltinsDraft = Omit<Builtins, typeof schemaBrand>;
52
- /** Everything the framework needs to know about one built-in flag. @internal */
53
- interface BuiltinSpec {
54
- /** Long spellings, the only forms that carry an inline `=value`. */
55
- readonly long: readonly string[];
56
- /** Short spellings, which have no inline-value form. */
57
- readonly short: readonly string[];
58
- /** Description shown in the root-help `Global options:` block. */
59
- readonly description: string;
60
- }
61
- /**
62
- * The spelling table every built-in-aware layer reads.
63
- *
64
- * @internal
65
- */
66
- declare const BUILTIN_SPECS: Readonly<Record<BuiltinName, BuiltinSpec>>;
67
- /** Spelling error messages and help entries name a built-in by. @internal */
68
- declare function builtinSpelling(name: BuiltinName): string;
69
- /** Built-in names in the order root help advertises them. @internal */
70
- declare const BUILTIN_NAMES: readonly ["help", "json", "quiet"];
71
- /** Every built-in on, the state a CLI starts in. @internal */
72
- declare const DEFAULT_BUILTINS: BuiltinsDraft;
73
- /**
74
- * Whether the root still owns a built-in.
75
- *
76
- * @param builtins - Normalized state, or `undefined` for the defaults.
77
- * @param name - Built-in to check.
78
- * @returns `true` when the root reads the token, `false` once it is released.
79
- *
80
- * @internal
81
- */
82
- declare function builtinEnabled(builtins: BuiltinsConfig | undefined, name: BuiltinName): boolean;
83
- /**
84
- * The argv spellings of one built-in, joined for a help entry.
85
- *
86
- * @param name - Built-in to render.
87
- * @returns Short spellings first, e.g. `-h, --help`.
88
- *
89
- * @internal
90
- */
91
- declare function builtinFlagForms(name: BuiltinName): string;
92
- /**
93
- * The spellings of one built-in as bare tokens, dashes removed.
94
- *
95
- * @param name - Built-in to read.
96
- * @returns Tokens as a command flag would declare them, e.g. `help` and `h`.
97
- *
98
- * @internal
99
- */
100
- declare function builtinTokens(name: BuiltinName): readonly string[];
101
- /**
102
- * Normalize built-in settings into the fully populated schema state.
103
- *
104
- * Shared by {@link createCLISchema} and {@linkcode CLIBuilder.builtins}, so both
105
- * construction paths produce identical state. Re-feeding a normalized value
106
- * returns an equal value.
107
- *
108
- * @param config - Caller-supplied settings, or `undefined` for the defaults.
109
- * @returns Every built-in resolved to a mode.
110
- * @throws {@linkcode CLIError} `INVALID_SCHEMA` for a value that is neither
111
- * `'on'` nor `'off'`.
112
- *
113
- * @internal
114
- */
115
- declare function normalizeBuiltins(config: BuiltinsConfig | undefined): BuiltinsDraft;
116
- //#endregion
117
- export { BUILTIN_NAMES, BUILTIN_SPECS, type BuiltinMode, type BuiltinName, type BuiltinSpec, type Builtins, type BuiltinsConfig, type BuiltinsDraft, DEFAULT_BUILTINS, builtinEnabled, builtinFlagForms, builtinSpelling, builtinTokens, normalizeBuiltins };
@@ -1,135 +0,0 @@
1
- import { CLIError } from "../errors/index.mjs";
2
- //#region src/core/cli/builtins.ts
3
- /**
4
- * Consumer-owned built-in flags: `--help`/`-h`, `--json`, and `--quiet`/`-q`.
5
- *
6
- * The root owns these tokens by default. {@linkcode CLIBuilder.builtins} sets a
7
- * built-in to `'off'`, which releases every spelling it answers to: the root
8
- * scanner stops reading and stripping it, root help stops advertising it, and
9
- * the `RESERVED_FLAG` guard stops reserving it, so a command may declare the
10
- * flag and receive it (#86).
11
- *
12
- * This module is the single spelling table behind all three layers. A token
13
- * added here reaches the scanner, the guard, and the help block in one change.
14
- *
15
- * @module dreamcli/core/cli/builtins
16
- * @internal
17
- */
18
- /**
19
- * The spelling table every built-in-aware layer reads.
20
- *
21
- * @internal
22
- */
23
- const BUILTIN_SPECS = {
24
- help: {
25
- long: ["--help"],
26
- short: ["-h"],
27
- description: "Show this help message and exit"
28
- },
29
- json: {
30
- long: ["--json"],
31
- short: [],
32
- description: "Emit machine-readable JSON output"
33
- },
34
- quiet: {
35
- long: ["--quiet"],
36
- short: ["-q"],
37
- description: "Suppress informational output"
38
- }
39
- };
40
- /** Spelling error messages and help entries name a built-in by. @internal */
41
- function builtinSpelling(name) {
42
- return BUILTIN_SPECS[name].long[0] ?? BUILTIN_SPECS[name].short[0] ?? name;
43
- }
44
- /** Built-in names in the order root help advertises them. @internal */
45
- const BUILTIN_NAMES = [
46
- "help",
47
- "json",
48
- "quiet"
49
- ];
50
- /** Every built-in on, the state a CLI starts in. @internal */
51
- const DEFAULT_BUILTINS = {
52
- help: "on",
53
- json: "on",
54
- quiet: "on"
55
- };
56
- /**
57
- * Whether the root still owns a built-in.
58
- *
59
- * @param builtins - Normalized state, or `undefined` for the defaults.
60
- * @param name - Built-in to check.
61
- * @returns `true` when the root reads the token, `false` once it is released.
62
- *
63
- * @internal
64
- */
65
- function builtinEnabled(builtins, name) {
66
- return (builtins?.[name] ?? "on") === "on";
67
- }
68
- /**
69
- * The argv spellings of one built-in, joined for a help entry.
70
- *
71
- * @param name - Built-in to render.
72
- * @returns Short spellings first, e.g. `-h, --help`.
73
- *
74
- * @internal
75
- */
76
- function builtinFlagForms(name) {
77
- const spec = BUILTIN_SPECS[name];
78
- return [...spec.short, ...spec.long].join(", ");
79
- }
80
- /**
81
- * The spellings of one built-in as bare tokens, dashes removed.
82
- *
83
- * @param name - Built-in to read.
84
- * @returns Tokens as a command flag would declare them, e.g. `help` and `h`.
85
- *
86
- * @internal
87
- */
88
- function builtinTokens(name) {
89
- const spec = BUILTIN_SPECS[name];
90
- return [...spec.long, ...spec.short].map((spelling) => spelling.replace(/^-+/, ""));
91
- }
92
- /**
93
- * Read one built-in's mode out of a caller-supplied config.
94
- *
95
- * @param config - Caller input, which a JS caller may fill with anything.
96
- * @param name - Built-in to read.
97
- * @returns The declared mode, or `'on'` when the key is absent.
98
- * @throws {@linkcode CLIError} `INVALID_SCHEMA` when the value is neither mode.
99
- */
100
- function readBuiltinMode(config, name) {
101
- const mode = config[name];
102
- if (mode === void 0 || mode === "on" || mode === "off") return mode ?? "on";
103
- throw new CLIError(`Built-in '${name}' must be 'on' or 'off'`, {
104
- code: "INVALID_SCHEMA",
105
- details: {
106
- builtin: name,
107
- value: mode
108
- },
109
- suggest: `Pass { ${name}: 'off' } to release the flag, or omit the key to keep it on`
110
- });
111
- }
112
- /**
113
- * Normalize built-in settings into the fully populated schema state.
114
- *
115
- * Shared by {@link createCLISchema} and {@linkcode CLIBuilder.builtins}, so both
116
- * construction paths produce identical state. Re-feeding a normalized value
117
- * returns an equal value.
118
- *
119
- * @param config - Caller-supplied settings, or `undefined` for the defaults.
120
- * @returns Every built-in resolved to a mode.
121
- * @throws {@linkcode CLIError} `INVALID_SCHEMA` for a value that is neither
122
- * `'on'` nor `'off'`.
123
- *
124
- * @internal
125
- */
126
- function normalizeBuiltins(config) {
127
- if (config === void 0) return DEFAULT_BUILTINS;
128
- return {
129
- help: readBuiltinMode(config, "help"),
130
- json: readBuiltinMode(config, "json"),
131
- quiet: readBuiltinMode(config, "quiet")
132
- };
133
- }
134
- //#endregion
135
- export { BUILTIN_NAMES, BUILTIN_SPECS, DEFAULT_BUILTINS, builtinEnabled, builtinFlagForms, builtinSpelling, builtinTokens, normalizeBuiltins };
@@ -1,66 +0,0 @@
1
- import { FlagBuilder, FlagConfig } from "../schema/flag.mjs";
2
- import { ArgBuilder, ArgConfig } from "../schema/arg.mjs";
3
- import { CommandBuilder, CommandSchema, ErasedActionHandler, ExecutionStep } from "../schema/command.mjs";
4
- import { CLIPlugin } from "./plugin.mjs";
5
- //#region src/core/cli/compiled.d.ts
6
- /**
7
- * Executable form of one registered command.
8
- */
9
- interface CompiledCommand {
10
- /** The very {@linkcode CommandSchema} object the public schema tree holds. */
11
- readonly schema: CommandSchema;
12
- /** Action handler, `undefined` for commands that only group subcommands. */
13
- readonly handler: ErasedActionHandler | undefined;
14
- /** Derive and middleware steps in registration order. */
15
- readonly steps: readonly ExecutionStep[];
16
- /** Nested subcommands, keyed by name and by every alias. */
17
- readonly subcommands: ReadonlyMap<string, CompiledCommand>;
18
- }
19
- /**
20
- * Executable state of a CLI program.
21
- */
22
- interface CompiledCLI {
23
- /** Top-level commands in registration order. */
24
- readonly commands: readonly CompiledCommand[];
25
- /** The default command, `undefined` when none is registered. */
26
- readonly defaultCommand: CompiledCommand | undefined;
27
- /** Plugins in registration order. */
28
- readonly plugins: readonly CLIPlugin[];
29
- }
30
- /**
31
- * The routes a command answers to: its name followed by its aliases.
32
- *
33
- * @param schema - Command schema to read the name and aliases from.
34
- * @returns Route tokens in declaration order.
35
- *
36
- * @internal
37
- */
38
- declare function commandRoutes(schema: CommandSchema): readonly string[];
39
- /**
40
- * Reject a route already claimed by a sibling command, then record its owner.
41
- *
42
- * @param parentCommandName - Name of the command the siblings live under.
43
- * @param routeOwners - Route to owning command name, mutated with `route`.
44
- * @param route - Name or alias being registered.
45
- * @param commandName - Command claiming the route.
46
- *
47
- * @internal
48
- */
49
- declare function assertNoSiblingRouteConflict(parentCommandName: string, routeOwners: Map<string, string>, route: string, commandName: string): void;
50
- /**
51
- * Compile a command builder into its executable graph node.
52
- *
53
- * Extracts the handler and execution steps, then recurses into
54
- * `_subcommands` to index each child by name and alias. The builder itself is
55
- * not retained; `schema` is the builder's own schema object, so the compiled
56
- * node and the public schema tree share command schema identity.
57
- *
58
- * @param cmd - Command builder to compile.
59
- * @returns The compiled command node.
60
- * @throws {@linkcode CLIError} `DUPLICATE_COMMAND` when two siblings claim the same route.
61
- *
62
- * @internal
63
- */
64
- declare function compileCommand<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown>>(cmd: CommandBuilder<F, A, C>): CompiledCommand;
65
- //#endregion
66
- export { type CompiledCLI, type CompiledCommand, assertNoSiblingRouteConflict, commandRoutes, compileCommand };
@@ -1,76 +0,0 @@
1
- import { CLIError } from "../errors/index.mjs";
2
- //#region src/core/cli/compiled.ts
3
- /**
4
- * Compiled execution graph behind a CLI program.
5
- *
6
- * {@linkcode CLISchema} describes the program; the compiled graph carries the
7
- * executable half — action handlers, execution steps, and the route-indexed
8
- * subcommand tree — and is reachable only through the module-private state in
9
- * `cli/index.ts`.
10
- *
11
- * @module dreamcli/core/cli/compiled
12
- */
13
- /**
14
- * The routes a command answers to: its name followed by its aliases.
15
- *
16
- * @param schema - Command schema to read the name and aliases from.
17
- * @returns Route tokens in declaration order.
18
- *
19
- * @internal
20
- */
21
- function commandRoutes(schema) {
22
- return [schema.name, ...schema.aliases];
23
- }
24
- /**
25
- * Reject a route already claimed by a sibling command, then record its owner.
26
- *
27
- * @param parentCommandName - Name of the command the siblings live under.
28
- * @param routeOwners - Route to owning command name, mutated with `route`.
29
- * @param route - Name or alias being registered.
30
- * @param commandName - Command claiming the route.
31
- *
32
- * @internal
33
- */
34
- function assertNoSiblingRouteConflict(parentCommandName, routeOwners, route, commandName) {
35
- const owner = routeOwners.get(route);
36
- if (owner !== void 0) {
37
- const selfCollision = owner === commandName;
38
- throw new CLIError(selfCollision ? `Command '${commandName}' reuses route '${route}' under '${parentCommandName}'` : `Duplicate command route '${route}' under '${parentCommandName}' (${owner} and ${commandName})`, {
39
- code: "DUPLICATE_COMMAND",
40
- suggest: selfCollision ? `Remove route '${route}' from the aliases of '${commandName}'` : "Ensure sibling command names and aliases are unique"
41
- });
42
- }
43
- routeOwners.set(route, commandName);
44
- }
45
- /**
46
- * Compile a command builder into its executable graph node.
47
- *
48
- * Extracts the handler and execution steps, then recurses into
49
- * `_subcommands` to index each child by name and alias. The builder itself is
50
- * not retained; `schema` is the builder's own schema object, so the compiled
51
- * node and the public schema tree share command schema identity.
52
- *
53
- * @param cmd - Command builder to compile.
54
- * @returns The compiled command node.
55
- * @throws {@linkcode CLIError} `DUPLICATE_COMMAND` when two siblings claim the same route.
56
- *
57
- * @internal
58
- */
59
- function compileCommand(cmd) {
60
- const subcommands = /* @__PURE__ */ new Map();
61
- const routeOwners = /* @__PURE__ */ new Map();
62
- for (const sub of cmd._subcommands) {
63
- const routes = commandRoutes(sub.schema);
64
- for (const route of routes) assertNoSiblingRouteConflict(cmd.schema.name, routeOwners, route, sub.schema.name);
65
- const compiled = compileCommand(sub);
66
- for (const route of routes) subcommands.set(route, compiled);
67
- }
68
- return {
69
- schema: cmd.schema,
70
- handler: cmd.handler,
71
- steps: cmd._executionSteps,
72
- subcommands
73
- };
74
- }
75
- //#endregion
76
- export { assertNoSiblingRouteConflict, commandRoutes, compileCommand };
@@ -1,115 +0,0 @@
1
- import { CommandSchema } from "../schema/command.mjs";
2
- import { FlagLookupEntry, ParseOptions } from "../parse/index.mjs";
3
- import { CompiledCommand } from "./compiled.mjs";
4
- //#region src/core/cli/dispatch.d.ts
5
- /**
6
- * Flag lookup (spelling → {@link FlagLookupEntry}) used to make the
7
- * command-name scan aware of value-flag arity. Built from the flags valid at
8
- * the current dispatch level via {@link buildFlagLookup}.
9
- *
10
- * @internal
11
- */
12
- type ValueFlagLookup = ReadonlyMap<string, FlagLookupEntry>;
13
- /** Successful dispatch — target command found with argv path. */
14
- interface DispatchMatch {
15
- /** Discriminant — a command name in argv matched a registered command. */
16
- readonly kind: 'match';
17
- /** The matched (target) command. */
18
- readonly command: CompiledCommand;
19
- /** Root → target (inclusive). Used for `collectPropagatedFlags()`. */
20
- readonly commandPath: readonly CommandSchema[];
21
- /** argv after consuming command name segments. */
22
- readonly remainingArgv: readonly string[];
23
- }
24
- /** Target has subcommands but no handler and no subcommand was specified/matched. */
25
- interface DispatchNeedsSubcommand {
26
- /** Discriminant — command group reached without a subcommand or handler. */
27
- readonly kind: 'needs-subcommand';
28
- /** The group command that needs a subcommand. */
29
- readonly command: CompiledCommand;
30
- /** Root → group (inclusive). */
31
- readonly commandPath: readonly CommandSchema[];
32
- }
33
- /** Unknown command name at this dispatch level. */
34
- interface DispatchUnknown {
35
- /** Discriminant — no registered command matched the input token. */
36
- readonly kind: 'unknown';
37
- /** The unrecognised input token. Empty string when no token present. */
38
- readonly input: string;
39
- /** Commands available at the level where matching failed. */
40
- readonly candidates: readonly CompiledCommand[];
41
- /** Ancestor path up to (but not including) the unknown level. */
42
- readonly parentPath: readonly CommandSchema[];
43
- }
44
- /** Discriminated result of recursive command dispatch. */
45
- type DispatchResult = DispatchMatch | DispatchNeedsSubcommand | DispatchUnknown;
46
- /**
47
- * Recursively walk argv, consuming command name segments from the front.
48
- *
49
- * At each level, the first non-flag token is tested as a command name
50
- * against the provided command map. If matched and the matched command
51
- * has subcommands, dispatch recurses into the child level with the
52
- * remaining argv.
53
- *
54
- * Ambiguity resolution for commands that have both an action handler AND
55
- * subcommands (e.g. `git remote` lists remotes, `git remote add` dispatches):
56
- * - If the next token matches a subcommand → descend
57
- * - If the next token is unknown and the command has a handler → match here
58
- * - If the next token is unknown and no handler → propagate unknown error
59
- * - If no next token and command has a handler → match here
60
- * - If no next token and no handler → needs-subcommand
61
- *
62
- * @param argv - Remaining argv tokens (command names + flags + args).
63
- * @param commands - Command map at the current tree level.
64
- * @param ancestorPath - Schema path from root to current level (exclusive).
65
- * @param valueFlags - Lookup of flags valid at this level, used so a
66
- * space-separated value-flag's value (`--region eu`) is not mistaken for a
67
- * command name. Empty by default (arity-unaware, legacy behaviour).
68
- * @param parseOptions - Parser toggles (case parity) applied to descent-level
69
- * flag lookups built inside dispatch.
70
- * @returns Discriminated dispatch result.
71
- *
72
- * @internal
73
- */
74
- declare function dispatch(argv: readonly string[], commands: ReadonlyMap<string, CompiledCommand>, ancestorPath?: readonly CommandSchema[], valueFlags?: ValueFlagLookup, parseOptions?: ParseOptions): DispatchResult;
75
- /**
76
- * Whether a flag token consumes the following argv token as its value.
77
- *
78
- * Mirrors the parser's value-consumption rules (`parseLongFlag` /
79
- * `parseShortFlags`) so the command-name scan skips exactly the tokens the
80
- * parser would treat as flag values:
81
- * - `--flag value` → consumes when `--flag` is a known value-flag.
82
- * - `--flag=value` → self-contained, consumes nothing.
83
- * - `-abc value` → consumes only when the trailing short flag is a value-flag;
84
- * an earlier value-flag char takes the rest of the group as an inline value.
85
- *
86
- * Unknown flags conservatively consume nothing (the parser reports them later).
87
- *
88
- * @internal
89
- */
90
- declare function consumesFollowingToken(token: string, valueFlags: ValueFlagLookup): boolean;
91
- /**
92
- * Levenshtein distance between two strings.
93
- * @internal
94
- */
95
- declare function levenshtein(a: string, b: string): number;
96
- /**
97
- * Find the closest command name match for a "did you mean?" suggestion.
98
- *
99
- * Searches command names and aliases. Returns `undefined` if no
100
- * sufficiently close match exists (threshold: 3).
101
- *
102
- * @internal
103
- */
104
- declare function findClosestCommand(input: string, commands: readonly CompiledCommand[]): string | undefined;
105
- /**
106
- * Deduplicate commands from a name+alias map.
107
- *
108
- * A map keyed by name *and* alias contains duplicate entries for aliased
109
- * commands. This returns unique commands (by schema identity).
110
- *
111
- * @internal
112
- */
113
- declare function uniqueCommands(commands: ReadonlyMap<string, CompiledCommand>): readonly CompiledCommand[];
114
- //#endregion
115
- export { type DispatchMatch, type DispatchNeedsSubcommand, type DispatchResult, type DispatchUnknown, type ValueFlagLookup, consumesFollowingToken, dispatch, findClosestCommand, levenshtein, uniqueCommands };