@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,174 +0,0 @@
1
- import { BuiltinsConfig } from "./builtins.mjs";
2
- import { CLIError } from "../errors/index.mjs";
3
- import { OutputPolicy } from "../output/contracts.mjs";
4
- import { CommandMeta, CommandSchema } from "../schema/command.mjs";
5
- import { HelpOptions } from "../help/index.mjs";
6
- import { ParseOptions } from "../parse/index.mjs";
7
- import { CLIPlugin } from "./plugin.mjs";
8
- import { CompiledCLI, CompiledCommand } from "./compiled.mjs";
9
- import { CompletionOptions } from "../completion/shells/shared.mjs";
10
- import { Shell } from "../completion/index.mjs";
11
- //#region src/core/cli/planner.d.ts
12
- /**
13
- * Descriptive subset of CLISchema used by the planner.
14
- *
15
- * Decouples invocation planning from the full CLIBuilder surface so the
16
- * planner can be tested and reasoned about without constructing a real CLI.
17
- * The executable half of a program reaches the planner separately, as the
18
- * {@linkcode CompiledCLI} passed alongside this schema.
19
- * @internal
20
- */
21
- interface PlannerSchemaLike {
22
- /** CLI program name used in help text and error messages. */
23
- readonly name: string;
24
- /** Declared version string; `undefined` disables `--version` interception. */
25
- readonly version: string | undefined;
26
- /** Whether the default command is also exposed as a named top-level route. */
27
- readonly defaultCommandRouted: boolean;
28
- /**
29
- * Eager `--completions <shell>` flag configuration, when `.completions()`
30
- * was registered with `{ as: 'flag' }`. `undefined` disables interception.
31
- */
32
- readonly completionsFlag: {
33
- readonly shells: readonly Shell[];
34
- readonly options: CompletionOptions | undefined;
35
- } | undefined;
36
- /** Flag-parsing behavior settings (case parity) applied to flag lookups. */
37
- readonly flagSettings?: ParseOptions | undefined;
38
- /**
39
- * Built-in flag state. `help: 'off'` stops root `--help`/`-h` interception
40
- * and bare `help` routing, and `json`/`quiet` stop being read out of argv.
41
- */
42
- readonly builtins: BuiltinsConfig | undefined;
43
- }
44
- /** Root-level help interception outcome. */
45
- interface RootHelpOutcome {
46
- /** Discriminant — argv matched `--help` / `-h` before any command. */
47
- readonly kind: 'root-help';
48
- /** Help options to render root-level usage. */
49
- readonly help: HelpOptions;
50
- }
51
- /** Root-level version interception outcome. */
52
- interface RootVersionOutcome {
53
- /** Discriminant — argv matched `--version` / `-V` and schema declares a version. */
54
- readonly kind: 'root-version';
55
- /** Resolved version string to render. */
56
- readonly version: string;
57
- }
58
- /** Root-level `--completions [shell]` interception outcome. */
59
- interface RootCompletionsOutcome {
60
- /** Discriminant — argv matched the eager `--completions [shell]` flag. */
61
- readonly kind: 'root-completions';
62
- /**
63
- * Resolved, validated target shell, or `undefined` when the flag was given
64
- * without a value and the shell should be auto-detected from the environment.
65
- */
66
- readonly shell: Shell | undefined;
67
- /** Generator options captured at build time. */
68
- readonly options: CompletionOptions | undefined;
69
- }
70
- /** CLI-level dispatch failure before command execution starts. */
71
- interface DispatchErrorOutcome {
72
- /** Discriminant — dispatch could not resolve a command from argv. */
73
- readonly kind: 'dispatch-error';
74
- /** Structured error with suggestion text for the caller to render. */
75
- readonly error: CLIError;
76
- }
77
- /** Successful planner handoff to the shared command execution path. */
78
- interface PlannerMatchOutcome {
79
- /** Discriminant — dispatch found a matching command for argv. */
80
- readonly kind: 'match';
81
- /** Fully resolved execution plan ready for the executor pipeline. */
82
- readonly plan: CommandExecutionPlan;
83
- }
84
- /**
85
- * Stable planner result union for the re-foundation workstream.
86
- *
87
- * `CLIBuilder.execute()` still renders and executes these outcomes, but
88
- * planning itself is intentionally bounded to this union.
89
- */
90
- type DispatchOutcome = RootHelpOutcome | RootVersionOutcome | RootCompletionsOutcome | DispatchErrorOutcome | PlannerMatchOutcome;
91
- /**
92
- * Concrete execution handoff produced by a successful planner match.
93
- *
94
- * `mergedSchema` is the exact command schema the executor sees after
95
- * propagated ancestor flags are collected and child definitions shadow them.
96
- */
97
- interface CommandExecutionPlan {
98
- /** Compiled command node that owns the handler and execution steps. */
99
- readonly command: CompiledCommand;
100
- /** Command schema with propagated ancestor flags merged in. */
101
- readonly mergedSchema: CommandSchema;
102
- /** Remaining argv tokens after command dispatch consumed the command path. */
103
- readonly argv: readonly string[];
104
- /** CLI-level metadata (program name, bin, version) for the handler context. */
105
- readonly meta: CommandMeta;
106
- /** Plugins to run through the execution lifecycle. */
107
- readonly plugins: readonly CLIPlugin[];
108
- /** Output policy (json mode, TTY, verbosity) governing handler rendering. */
109
- readonly output: OutputPolicy;
110
- /** Help options for rendering per-command help; `undefined` when unavailable. */
111
- readonly help: HelpOptions | undefined;
112
- }
113
- interface BuildCommandExecutionPlanOptions {
114
- readonly command: CompiledCommand;
115
- readonly commandPath: readonly CommandSchema[];
116
- readonly argv: readonly string[];
117
- readonly meta: CommandMeta;
118
- readonly plugins: readonly CLIPlugin[];
119
- readonly output: OutputPolicy;
120
- readonly help: HelpOptions | undefined;
121
- }
122
- /**
123
- * Dispatch resolved a group command that requires a subcommand selection.
124
- *
125
- * The caller should render subcommand-level help for the matched group.
126
- * @internal
127
- */
128
- interface NeedsSubcommandOutcome {
129
- /** Discriminant — group command matched but no leaf subcommand was selected. */
130
- readonly kind: 'needs-subcommand';
131
- /** The group command that was matched. */
132
- readonly command: CompiledCommand;
133
- /** Full ancestor path from root to this group, used for propagated flag collection. */
134
- readonly commandPath: readonly CommandSchema[];
135
- /** Help options scoped to the group command's bin path. */
136
- readonly help: HelpOptions;
137
- }
138
- /** Full planner result including the `needs-subcommand` variant used by CLIBuilder. @internal */
139
- type InvocationPlan = DispatchOutcome | NeedsSubcommandOutcome;
140
- /** Options bag for {@linkcode planInvocation}. @internal */
141
- interface PlanInvocationOptions {
142
- /** CLI schema subset driving dispatch decisions. */
143
- readonly schema: PlannerSchemaLike;
144
- /** Compiled execution graph the dispatch walk resolves commands from. */
145
- readonly compiled: CompiledCLI;
146
- /** Raw argv tokens (typically `adapter.argv.slice(2)`). */
147
- readonly argv: readonly string[];
148
- /** Root-level help configuration for rendering. */
149
- readonly help: HelpOptions;
150
- /** Output policy propagated into matched execution plans. */
151
- readonly output: OutputPolicy;
152
- }
153
- /** Build a name+alias lookup map for top-level commands. @internal */
154
- declare function buildRootCommandMap(commands: readonly CompiledCommand[]): ReadonlyMap<string, CompiledCommand>;
155
- /**
156
- * Merge propagated ancestor flags into the matched command schema.
157
- *
158
- * Child flag definitions win when names collide, matching current CLI
159
- * dispatch semantics and the future planner contract.
160
- */
161
- declare function mergeCommandSchema(command: CompiledCommand, commandPath: readonly CommandSchema[]): CommandSchema;
162
- /** Build the planner handoff for a matched command invocation. */
163
- declare function buildCommandExecutionPlan(options: BuildCommandExecutionPlanOptions): CommandExecutionPlan;
164
- /**
165
- * Decide what to do with an argv invocation before any command executes.
166
- *
167
- * Handles root interception (`--help`, `--version`, `--completions <shell>`,
168
- * bare `help` token), dispatches into the command tree, falls back to the
169
- * default command, and produces structured errors for unknown commands/flags.
170
- * @internal
171
- */
172
- declare function planInvocation(options: PlanInvocationOptions): InvocationPlan;
173
- //#endregion
174
- export { type CommandExecutionPlan, type DispatchErrorOutcome, type DispatchOutcome, type InvocationPlan, type NeedsSubcommandOutcome, type OutputPolicy, type PlanInvocationOptions, type PlannerMatchOutcome, type PlannerSchemaLike, type RootCompletionsOutcome, type RootHelpOutcome, type RootVersionOutcome, buildCommandExecutionPlan, buildRootCommandMap, mergeCommandSchema, planInvocation };
@@ -1,323 +0,0 @@
1
- import { CLIError, ParseError } from "../errors/index.mjs";
2
- import { buildFlagLookup, flagExpectsValue, includesBeforeSeparator, requestsHelp } from "../parse/index.mjs";
3
- import { builtinEnabled } from "./builtins.mjs";
4
- import { collectPropagatedFlags } from "./propagate.mjs";
5
- import { normalizeShell } from "../completion/index.mjs";
6
- import { dispatch, findClosestCommand } from "./dispatch.mjs";
7
- import { readRootOutputFlags } from "./root-output-flags.mjs";
8
- //#region src/core/cli/planner.ts
9
- function buildMeta(schema, helpOptions, commandName) {
10
- return {
11
- name: schema.name,
12
- bin: helpOptions.binName ?? schema.name,
13
- version: schema.version,
14
- command: commandName
15
- };
16
- }
17
- /** Build a name+alias lookup map for top-level commands. @internal */
18
- function buildRootCommandMap(commands) {
19
- const rootCommands = /* @__PURE__ */ new Map();
20
- const addRoute = (route, command) => {
21
- const existing = rootCommands.get(route);
22
- if (existing !== void 0) throw new CLIError(`Duplicate root command route '${route}' (${existing.schema.name} and ${command.schema.name})`, {
23
- code: "DUPLICATE_COMMAND",
24
- suggest: "Ensure root command names and aliases are unique"
25
- });
26
- rootCommands.set(route, command);
27
- };
28
- for (const cmd of commands) {
29
- addRoute(cmd.schema.name, cmd);
30
- for (const alias of cmd.schema.aliases) addRoute(alias, cmd);
31
- }
32
- return rootCommands;
33
- }
34
- /**
35
- * Merge propagated ancestor flags into the matched command schema.
36
- *
37
- * Child flag definitions win when names collide, matching current CLI
38
- * dispatch semantics and the future planner contract.
39
- */
40
- function mergeCommandSchema(command, commandPath) {
41
- const propagated = collectPropagatedFlags(commandPath);
42
- if (Object.keys(propagated).length === 0) return command.schema;
43
- return {
44
- ...command.schema,
45
- flags: {
46
- ...propagated,
47
- ...command.schema.flags
48
- }
49
- };
50
- }
51
- /** Build the planner handoff for a matched command invocation. */
52
- function buildCommandExecutionPlan(options) {
53
- return {
54
- command: options.command,
55
- mergedSchema: mergeCommandSchema(options.command, options.commandPath),
56
- argv: options.argv,
57
- meta: options.meta,
58
- plugins: options.plugins,
59
- output: options.output,
60
- help: options.help
61
- };
62
- }
63
- function buildPlannerMatchOutcome(options, command, commandPath, argv) {
64
- return {
65
- kind: "match",
66
- plan: buildCommandExecutionPlan({
67
- command,
68
- commandPath,
69
- argv,
70
- meta: buildMeta(options.schema, options.help, command.schema.name),
71
- plugins: options.compiled.plugins,
72
- output: options.output,
73
- help: options.help
74
- })
75
- };
76
- }
77
- function canDelegateUnknownRootToDefault(command, input) {
78
- return input === "" || command.schema.args.length > 0;
79
- }
80
- function findUnknownFlagBeforePositional(argv, flags, parseOptions) {
81
- const lookup = buildFlagLookup(flags, parseOptions);
82
- for (let index = 0; index < argv.length; index++) {
83
- const token = argv[index];
84
- if (token === void 0 || token === "--") return void 0;
85
- if (token === "-" || !token.startsWith("-")) return void 0;
86
- if (token.startsWith("--")) {
87
- const equalsIndex = token.indexOf("=");
88
- const name = token.slice(2, equalsIndex === -1 ? void 0 : equalsIndex);
89
- const entry = lookup.get(name);
90
- if (entry === void 0) return equalsIndex === -1 ? token : `--${name}`;
91
- if (equalsIndex === -1 && flagExpectsValue(entry.schema)) index++;
92
- continue;
93
- }
94
- const chars = token.slice(1);
95
- for (let charIndex = 0; charIndex < chars.length; charIndex++) {
96
- const char = chars.charAt(charIndex);
97
- const entry = lookup.get(char);
98
- if (entry === void 0) return `-${char}`;
99
- if (!flagExpectsValue(entry.schema)) continue;
100
- if (charIndex === chars.length - 1) index++;
101
- break;
102
- }
103
- }
104
- }
105
- /**
106
- * Scan the pre-`--`, `--json`-stripped head to locate the first command-dispatch
107
- * token and detect a root-level `--help` / `-h` ahead of it.
108
- *
109
- * Value-flag arity is honoured (via `valueFlags`) so a flag value that happens
110
- * to look like a command name is not mistaken for one — matching how
111
- * {@linkcode dispatch} reads the same argv.
112
- *
113
- * @internal
114
- */
115
- function scanRootHead(head, valueFlags, helpOwned) {
116
- for (let index = 0; index < head.length; index++) {
117
- const token = head[index];
118
- if (token === void 0) continue;
119
- if (helpOwned && (token === "--help" || token === "-h")) return {
120
- helpBeforeCommand: true,
121
- firstCommandToken: void 0,
122
- commandTokenIndex: -1
123
- };
124
- if (token === "-" || !token.startsWith("-")) return {
125
- helpBeforeCommand: false,
126
- firstCommandToken: token,
127
- commandTokenIndex: index
128
- };
129
- if (token.startsWith("--")) {
130
- const equalsIndex = token.indexOf("=");
131
- const name = token.slice(2, equalsIndex === -1 ? void 0 : equalsIndex);
132
- const entry = valueFlags?.get(name);
133
- if (entry !== void 0 && equalsIndex === -1 && flagExpectsValue(entry.schema)) index++;
134
- continue;
135
- }
136
- const chars = token.slice(1);
137
- for (let charIndex = 0; charIndex < chars.length; charIndex++) {
138
- const entry = valueFlags?.get(chars.charAt(charIndex));
139
- if (entry === void 0 || !flagExpectsValue(entry.schema)) continue;
140
- if (charIndex === chars.length - 1) index++;
141
- break;
142
- }
143
- }
144
- return {
145
- helpBeforeCommand: false,
146
- firstCommandToken: void 0,
147
- commandTokenIndex: -1
148
- };
149
- }
150
- /**
151
- * Build the `Run '<scope> --help'` hint carried by a dispatch failure.
152
- *
153
- * A CLI that released `help` through `.builtins({ help: 'off' })` rejects the
154
- * token, so the hint is dropped rather than pointing at a flag the program
155
- * answers with `Unknown flag --help`.
156
- *
157
- * @param scopePath - Binary name plus any ancestor command names.
158
- * @param helpOwned - Whether the root still owns `--help`.
159
- * @returns The `suggest` field, or an empty object.
160
- *
161
- * @internal
162
- */
163
- function helpHint(scopePath, helpOwned) {
164
- return helpOwned ? { suggest: `Run '${scopePath} --help' for available commands` } : {};
165
- }
166
- /**
167
- * Detect and resolve the eager `--completions [shell]` flag before dispatch.
168
- *
169
- * Accepts `--completions <shell>` and `--completions=<shell>`. When no value is
170
- * given (`--completions` alone, or followed by another flag), the shell is left
171
- * `undefined` so the caller can auto-detect it from the environment. Scans only
172
- * before a `--` separator so a literal positional survives.
173
- *
174
- * Returns `undefined` when the flag is absent, a `root-completions` outcome
175
- * otherwise, or a `dispatch-error` when an explicit value names an unknown shell.
176
- *
177
- * @internal
178
- */
179
- function planCompletionsFlag(argv, config) {
180
- const separatorIndex = argv.indexOf("--");
181
- const scanEnd = separatorIndex === -1 ? argv.length : separatorIndex;
182
- for (let index = 0; index < scanEnd; index++) {
183
- const token = argv[index];
184
- if (token === void 0) continue;
185
- let rawShell;
186
- if (token === "--completions") {
187
- const next = index + 1 < scanEnd ? argv[index + 1] : void 0;
188
- rawShell = next !== void 0 && !next.startsWith("-") ? next : void 0;
189
- } else if (token.startsWith("--completions=")) rawShell = token.slice(14);
190
- else continue;
191
- if (rawShell === void 0 || rawShell === "") return {
192
- kind: "root-completions",
193
- shell: void 0,
194
- options: config.options
195
- };
196
- const shell = normalizeShell(rawShell);
197
- if (shell === void 0 || !config.shells.includes(shell)) return {
198
- kind: "dispatch-error",
199
- error: new ParseError(`Unknown shell '${rawShell}'`, {
200
- code: "INVALID_VALUE",
201
- suggest: `Valid shells: ${config.shells.join(", ")}`
202
- })
203
- };
204
- return {
205
- kind: "root-completions",
206
- shell,
207
- options: config.options
208
- };
209
- }
210
- }
211
- /**
212
- * Decide what to do with an argv invocation before any command executes.
213
- *
214
- * Handles root interception (`--help`, `--version`, `--completions <shell>`,
215
- * bare `help` token), dispatches into the command tree, falls back to the
216
- * default command, and produces structured errors for unknown commands/flags.
217
- * @internal
218
- */
219
- function planInvocation(options) {
220
- const helpOwned = builtinEnabled(options.schema.builtins, "help");
221
- const rootOutputFlags = readRootOutputFlags(options.argv, options.schema.builtins);
222
- const filteredArgv = rootOutputFlags.argv;
223
- const separatorIndex = filteredArgv.indexOf("--");
224
- const filteredHead = separatorIndex === -1 ? filteredArgv : filteredArgv.slice(0, separatorIndex);
225
- const defaultCommand = options.compiled.defaultCommand;
226
- const rootValueFlags = defaultCommand !== void 0 ? buildFlagLookup(defaultCommand.schema.flags, options.schema.flagSettings) : void 0;
227
- if (options.schema.version !== void 0 && (includesBeforeSeparator(options.argv, "--version") || includesBeforeSeparator(options.argv, "-V"))) return {
228
- kind: "root-version",
229
- version: options.schema.version
230
- };
231
- if (options.schema.completionsFlag !== void 0) {
232
- const completionsOutcome = planCompletionsFlag(options.argv, options.schema.completionsFlag);
233
- if (completionsOutcome !== void 0) return completionsOutcome;
234
- }
235
- const headScan = scanRootHead(filteredHead, rootValueFlags, helpOwned);
236
- if (headScan.helpBeforeCommand) return {
237
- kind: "root-help",
238
- help: options.help
239
- };
240
- if (helpOwned && headScan.firstCommandToken === "help") {
241
- if (!options.compiled.commands.some((command) => command.schema.name === "help" || command.schema.aliases.includes("help"))) {
242
- const rest = filteredArgv.slice(headScan.commandTokenIndex + 1);
243
- if (rest.length === 0) return {
244
- kind: "root-help",
245
- help: options.help
246
- };
247
- return planInvocation({
248
- ...options,
249
- argv: [...rest, "--help"]
250
- });
251
- }
252
- }
253
- if (rootOutputFlags.kind === "failed" && !(helpOwned && requestsHelp(filteredArgv))) return {
254
- kind: "dispatch-error",
255
- error: rootOutputFlags.error
256
- };
257
- if (options.compiled.commands.length === 0 && defaultCommand === void 0) return {
258
- kind: "dispatch-error",
259
- error: new CLIError("No commands registered", {
260
- code: "NO_ACTION",
261
- suggest: "Add commands via .command() or .default() before calling .run()"
262
- })
263
- };
264
- if (filteredArgv.length === 0 && defaultCommand === void 0) return {
265
- kind: "root-help",
266
- help: options.help
267
- };
268
- const rootCommands = defaultCommand !== void 0 && options.schema.defaultCommandRouted ? [...options.compiled.commands, defaultCommand] : options.compiled.commands;
269
- const result = dispatch(filteredArgv, buildRootCommandMap(rootCommands), [], rootValueFlags, options.schema.flagSettings);
270
- switch (result.kind) {
271
- case "unknown": {
272
- if (defaultCommand !== void 0 && result.parentPath.length === 0) {
273
- if ((result.input !== "" ? findClosestCommand(result.input, result.candidates) : void 0) === void 0 && canDelegateUnknownRootToDefault(defaultCommand, result.input)) return buildPlannerMatchOutcome(options, defaultCommand, [defaultCommand.schema], filteredArgv);
274
- const unknownFlag = findUnknownFlagBeforePositional(filteredArgv, defaultCommand.schema.flags, options.schema.flagSettings);
275
- if (unknownFlag !== void 0) return {
276
- kind: "dispatch-error",
277
- error: new ParseError(`Unknown flag ${unknownFlag}`, {
278
- code: "UNKNOWN_FLAG",
279
- ...helpHint(options.schema.name, helpOwned)
280
- })
281
- };
282
- }
283
- if (result.input === "") {
284
- const unknownFlag = filteredArgv.find((token) => token.startsWith("-"));
285
- if (unknownFlag === void 0) return {
286
- kind: "root-help",
287
- help: options.help
288
- };
289
- return {
290
- kind: "dispatch-error",
291
- error: new ParseError(`Unknown flag ${unknownFlag}`, {
292
- code: "UNKNOWN_FLAG",
293
- ...helpHint(options.schema.name, helpOwned)
294
- })
295
- };
296
- }
297
- const suggestion = findClosestCommand(result.input, result.candidates);
298
- const scopePath = result.parentPath.length > 0 ? `${options.schema.name} ${result.parentPath.map((schema) => schema.name).join(" ")}` : options.schema.name;
299
- return {
300
- kind: "dispatch-error",
301
- error: new ParseError(`Unknown command: ${result.input}`, {
302
- code: "UNKNOWN_COMMAND",
303
- ...suggestion !== void 0 ? { suggest: `Did you mean '${suggestion}'?` } : helpHint(scopePath, helpOwned)
304
- })
305
- };
306
- }
307
- case "needs-subcommand": {
308
- const ancestorNames = result.commandPath.slice(0, -1).map((schema) => schema.name);
309
- return {
310
- kind: "needs-subcommand",
311
- command: result.command,
312
- commandPath: result.commandPath,
313
- help: {
314
- ...options.help,
315
- binName: [options.schema.name, ...ancestorNames].join(" ")
316
- }
317
- };
318
- }
319
- case "match": return buildPlannerMatchOutcome(options, result.command, result.commandPath, result.remainingArgv);
320
- }
321
- }
322
- //#endregion
323
- export { buildCommandExecutionPlan, buildRootCommandMap, mergeCommandSchema, planInvocation };
@@ -1,94 +0,0 @@
1
- import { CommandMeta, CommandSchema, Out } from "../schema/command.mjs";
2
- import { DeprecationWarning } from "../resolve/contracts.mjs";
3
- import "../resolve/index.mjs";
4
- //#region src/core/cli/plugin.d.ts
5
- /** Shared hook payload for a concrete command execution. */
6
- interface PluginCommandContext {
7
- /** Runtime command schema being executed. */
8
- readonly command: CommandSchema;
9
- /** CLI metadata for this execution. */
10
- readonly meta: CommandMeta;
11
- /** Output channel for this execution. */
12
- readonly out: Out;
13
- }
14
- /** Payload for `beforeParse`. */
15
- interface BeforeParseParams extends PluginCommandContext {
16
- /** Raw argv that will be parsed for the leaf command. */
17
- readonly argv: readonly string[];
18
- }
19
- /** Payload for hooks that observe resolved inputs. */
20
- interface ResolvedCommandParams extends PluginCommandContext {
21
- /** Fully resolved flag values. */
22
- readonly flags: Readonly<Record<string, unknown>>;
23
- /** Fully resolved argument values. */
24
- readonly args: Readonly<Record<string, unknown>>;
25
- /** Structured deprecation warnings collected during resolution. */
26
- readonly deprecations: readonly DeprecationWarning[];
27
- }
28
- /**
29
- * Individual lifecycle hooks that a plugin may implement.
30
- *
31
- * Hook order for a successful command run is:
32
- * `beforeParse` → `afterResolve` → `beforeAction` → middleware/action → `afterAction`.
33
- *
34
- * Hooks are awaited serially and run in plugin registration order at each
35
- * stage. Throwing from any hook aborts the command just like throwing from
36
- * middleware or the action handler. `afterAction` runs only after the
37
- * middleware chain and action complete successfully.
38
- */
39
- interface CLIPluginHooks {
40
- /** Called immediately before leaf-command argv is parsed. */
41
- readonly beforeParse?: (params: BeforeParseParams) => void | Promise<void>;
42
- /** Called after parse + resolve, before middleware or action execution. */
43
- readonly afterResolve?: (params: ResolvedCommandParams) => void | Promise<void>;
44
- /** Called immediately before the middleware chain and action handler run. */
45
- readonly beforeAction?: (params: ResolvedCommandParams) => void | Promise<void>;
46
- /** Called after the middleware chain and action handler complete successfully. */
47
- readonly afterAction?: (params: ResolvedCommandParams) => void | Promise<void>;
48
- }
49
- /**
50
- * Immutable plugin definition registered via `CLIBuilder.plugin()`.
51
- *
52
- * Use {@link plugin} to construct values of this shape instead of manually
53
- * assembling the object.
54
- */
55
- interface CLIPlugin {
56
- /** Optional label for diagnostics and debugging. */
57
- readonly name: string | undefined;
58
- /** Lifecycle hooks implemented by the plugin. */
59
- readonly hooks: CLIPluginHooks;
60
- }
61
- /**
62
- * Create a CLI plugin from lifecycle hooks.
63
- *
64
- * @param hooks - Lifecycle hooks to register.
65
- * @param name - Optional plugin name for diagnostics.
66
- *
67
- * @example
68
- * ```ts
69
- * import { cli, command, plugin } from '@kjanat/dreamcli';
70
- *
71
- * const deploy = command('deploy').action(({ out }) => {
72
- * out.log('deploying');
73
- * });
74
- *
75
- * const trace = plugin(
76
- * {
77
- * beforeParse: ({ argv, out }) => {
78
- * out.info(`argv: ${argv.join(' ')}`);
79
- * },
80
- * afterResolve: ({ flags, args }) => {
81
- * console.log({ flags, args });
82
- * },
83
- * },
84
- * 'trace',
85
- * );
86
- *
87
- * cli('mycli').plugin(trace).command(deploy).run();
88
- * ```
89
- *
90
- * @returns A frozen {@link CLIPlugin} definition.
91
- */
92
- declare function plugin(hooks: CLIPluginHooks, name?: string): CLIPlugin;
93
- //#endregion
94
- export { type BeforeParseParams, type CLIPlugin, type CLIPluginHooks, type PluginCommandContext, type ResolvedCommandParams, plugin };
@@ -1,41 +0,0 @@
1
- //#region src/core/cli/plugin.ts
2
- /**
3
- * Create a CLI plugin from lifecycle hooks.
4
- *
5
- * @param hooks - Lifecycle hooks to register.
6
- * @param name - Optional plugin name for diagnostics.
7
- *
8
- * @example
9
- * ```ts
10
- * import { cli, command, plugin } from '@kjanat/dreamcli';
11
- *
12
- * const deploy = command('deploy').action(({ out }) => {
13
- * out.log('deploying');
14
- * });
15
- *
16
- * const trace = plugin(
17
- * {
18
- * beforeParse: ({ argv, out }) => {
19
- * out.info(`argv: ${argv.join(' ')}`);
20
- * },
21
- * afterResolve: ({ flags, args }) => {
22
- * console.log({ flags, args });
23
- * },
24
- * },
25
- * 'trace',
26
- * );
27
- *
28
- * cli('mycli').plugin(trace).command(deploy).run();
29
- * ```
30
- *
31
- * @returns A frozen {@link CLIPlugin} definition.
32
- */
33
- function plugin(hooks, name) {
34
- const frozenHooks = Object.freeze({ ...hooks });
35
- return Object.freeze({
36
- hooks: frozenHooks,
37
- name
38
- });
39
- }
40
- //#endregion
41
- export { plugin };
@@ -1,39 +0,0 @@
1
- import { FlagSchema } from "../schema/flag.mjs";
2
- import { CommandSchema } from "../schema/command.mjs";
3
- import "../schema/index.mjs";
4
- //#region src/core/cli/propagate.d.ts
5
- /**
6
- * Collect propagated flags from a command path.
7
- *
8
- * The command path is an ordered array of {@linkcode CommandSchema} from the root
9
- * ancestor to the target command that will actually execute. Each ancestor's
10
- * flags marked `propagate: true` are accumulated. If a descendant (including
11
- * the target) defines a flag with the same name — regardless of whether the
12
- * descendant's flag has `propagate: true` — it shadows the ancestor's flag.
13
- *
14
- * The target command's own flags are **not** included in the result. This
15
- * function returns only the *inherited* propagated flags that should be merged
16
- * into the target command's flag set before resolution.
17
- *
18
- * @param commandPath - Ordered schemas from root ancestor to target (inclusive).
19
- * Must contain at least one element (the target itself). When the path has
20
- * only one element, no ancestors exist and the result is empty.
21
- *
22
- * @returns A record of propagated flag schemas keyed by flag name. Empty when
23
- * the path has no ancestors or no ancestor flags have `propagate: true`.
24
- *
25
- * @example
26
- * ```ts
27
- * // Given: root (--verbose [propagate]) → db → migrate
28
- * // Where migrate does NOT define --verbose
29
- * const inherited = collectPropagatedFlags([rootSchema, dbSchema, migrateSchema]);
30
- * // inherited = { verbose: <FlagSchema from root> }
31
- *
32
- * // If db also defines --verbose (shadowing root):
33
- * const inherited2 = collectPropagatedFlags([rootSchema, dbSchemaWithVerbose, migrateSchema]);
34
- * // inherited2 = { verbose: <FlagSchema from db> }
35
- * ```
36
- */
37
- declare function collectPropagatedFlags(commandPath: readonly CommandSchema[]): Readonly<Record<string, FlagSchema>>;
38
- //#endregion
39
- export { collectPropagatedFlags };