@kjanat/dreamcli 3.0.0 → 4.0.0-rc.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 (147) hide show
  1. package/CHANGELOG.md +967 -1
  2. package/README.md +9 -3
  3. package/dist/core/cli/builtins.d.mts +47 -0
  4. package/dist/core/cli/builtins.mjs +135 -0
  5. package/dist/core/cli/compiled.d.mts +29 -0
  6. package/dist/core/cli/compiled.mjs +76 -0
  7. package/dist/core/cli/dispatch.d.mts +9 -85
  8. package/dist/core/cli/help-links.d.mts +2 -14
  9. package/dist/core/cli/index.d.mts +282 -101
  10. package/dist/core/cli/index.mjs +497 -264
  11. package/dist/core/cli/planner.d.mts +13 -86
  12. package/dist/core/cli/planner.mjs +47 -30
  13. package/dist/core/cli/plugin.d.mts +1 -1
  14. package/dist/core/cli/propagate.mjs +1 -1
  15. package/dist/core/cli/reserved-flags.d.mts +1 -0
  16. package/dist/core/cli/reserved-flags.mjs +158 -0
  17. package/dist/core/cli/root-help.d.mts +1 -47
  18. package/dist/core/cli/root-help.mjs +37 -47
  19. package/dist/core/cli/root-output-flags.d.mts +1 -0
  20. package/dist/core/cli/root-output-flags.mjs +169 -0
  21. package/dist/core/cli/root-surface.d.mts +1 -68
  22. package/dist/core/cli/root-surface.mjs +2 -2
  23. package/dist/core/cli/runtime-preflight.d.mts +1 -199
  24. package/dist/core/cli/runtime-preflight.mjs +67 -17
  25. package/dist/core/completion/index.d.mts +2 -2
  26. package/dist/core/completion/shells/bash.d.mts +0 -1
  27. package/dist/core/completion/shells/bash.mjs +2 -1
  28. package/dist/core/completion/shells/fish.d.mts +0 -1
  29. package/dist/core/completion/shells/fish.mjs +2 -1
  30. package/dist/core/completion/shells/powershell.d.mts +0 -1
  31. package/dist/core/completion/shells/powershell.mjs +2 -1
  32. package/dist/core/completion/shells/shared.d.mts +3 -114
  33. package/dist/core/completion/shells/shared.mjs +9 -39
  34. package/dist/core/completion/shells/zsh.d.mts +0 -1
  35. package/dist/core/completion/shells/zsh.mjs +2 -1
  36. package/dist/core/config/index.d.mts +3 -3
  37. package/dist/core/config/index.mjs +2 -2
  38. package/dist/core/config/package-json.d.mts +2 -33
  39. package/dist/core/config/package-json.mjs +1 -34
  40. package/dist/core/errors/index.d.mts +7 -7
  41. package/dist/core/execution/index.d.mts +1 -48
  42. package/dist/core/execution/index.mjs +42 -27
  43. package/dist/core/help/ansi.d.mts +0 -11
  44. package/dist/core/help/index.d.mts +3 -35
  45. package/dist/core/help/index.mjs +29 -6
  46. package/dist/core/help/theme.d.mts +1 -21
  47. package/dist/core/json-schema/index.d.mts +279 -10
  48. package/dist/core/json-schema/index.mjs +482 -237
  49. package/dist/core/json-schema/meta-descriptions.generated.d.mts +79 -7
  50. package/dist/core/json-schema/meta-descriptions.generated.mjs +40 -6
  51. package/dist/core/output/activity.d.mts +1 -193
  52. package/dist/core/output/activity.mjs +1 -1
  53. package/dist/core/output/bind.d.mts +1 -37
  54. package/dist/core/output/contracts.d.mts +7 -13
  55. package/dist/core/output/contracts.mjs +1 -1
  56. package/dist/core/output/display-value.d.mts +1 -19
  57. package/dist/core/output/index.d.mts +5 -187
  58. package/dist/core/output/index.mjs +44 -9
  59. package/dist/core/output/renderers.d.mts +1 -45
  60. package/dist/core/output/writer.d.mts +0 -1
  61. package/dist/core/parse/index.d.mts +27 -5
  62. package/dist/core/parse/index.mjs +350 -227
  63. package/dist/core/parse/occurrences.d.mts +89 -0
  64. package/dist/core/parse/occurrences.mjs +114 -0
  65. package/dist/core/prompt/index.d.mts +3 -3
  66. package/dist/core/read-flags/index.d.mts +150 -0
  67. package/dist/core/read-flags/index.mjs +217 -0
  68. package/dist/core/resolve/args.d.mts +35 -4
  69. package/dist/core/resolve/args.mjs +132 -55
  70. package/dist/core/resolve/coerce.d.mts +66 -9
  71. package/dist/core/resolve/coerce.mjs +834 -270
  72. package/dist/core/resolve/config.d.mts +1 -10
  73. package/dist/core/resolve/contracts.d.mts +67 -44
  74. package/dist/core/resolve/errors.mjs +29 -21
  75. package/dist/core/resolve/flags.d.mts +36 -9
  76. package/dist/core/resolve/flags.mjs +129 -151
  77. package/dist/core/resolve/index.d.mts +8 -6
  78. package/dist/core/resolve/index.mjs +51 -18
  79. package/dist/core/resolve/path-checks.d.mts +47 -0
  80. package/dist/core/resolve/path-checks.mjs +102 -0
  81. package/dist/core/resolve/redaction.d.mts +12 -0
  82. package/dist/core/resolve/redaction.mjs +14 -0
  83. package/dist/core/resolve/stages.d.mts +85 -0
  84. package/dist/core/resolve/stages.mjs +170 -0
  85. package/dist/core/resolve/standard.d.mts +1 -24
  86. package/dist/core/resolve/standard.mjs +141 -43
  87. package/dist/core/schema/activity.d.mts +16 -16
  88. package/dist/core/schema/arg.d.mts +849 -71
  89. package/dist/core/schema/arg.mjs +727 -54
  90. package/dist/core/schema/brand.d.mts +17 -0
  91. package/dist/core/schema/cardinality.d.mts +301 -0
  92. package/dist/core/schema/cardinality.mjs +514 -0
  93. package/dist/core/schema/command.d.mts +181 -112
  94. package/dist/core/schema/command.mjs +305 -42
  95. package/dist/core/schema/flag.d.mts +515 -173
  96. package/dist/core/schema/flag.mjs +576 -78
  97. package/dist/core/schema/index.d.mts +11 -8
  98. package/dist/core/schema/index.mjs +10 -0
  99. package/dist/core/schema/middleware.d.mts +15 -12
  100. package/dist/core/schema/number-constraints.d.mts +5 -5
  101. package/dist/core/schema/prompt.d.mts +4 -4
  102. package/dist/core/schema/provenance.d.mts +99 -0
  103. package/dist/core/schema/provenance.mjs +28 -0
  104. package/dist/core/schema/run.d.mts +21 -60
  105. package/dist/core/schema/source.d.mts +179 -0
  106. package/dist/core/schema/source.mjs +206 -0
  107. package/dist/core/schema/standard.d.mts +12 -19
  108. package/dist/core/schema/stdin.d.mts +87 -0
  109. package/dist/core/schema/stdin.mjs +91 -0
  110. package/dist/core/schema/string-constraints.d.mts +16 -5
  111. package/dist/core/schema/string-constraints.mjs +18 -1
  112. package/dist/core/schema/value-parsers.d.mts +81 -9
  113. package/dist/core/schema/value-parsers.mjs +19 -1
  114. package/dist/core/schema/value.d.mts +242 -0
  115. package/dist/core/schema/value.mjs +573 -0
  116. package/dist/core/testkit/index.d.mts +28 -3
  117. package/dist/core/testkit/index.mjs +40 -26
  118. package/dist/index.d.mts +21 -16
  119. package/dist/index.mjs +10 -6
  120. package/dist/runtime/adapter.d.mts +3 -3
  121. package/dist/runtime/deno.d.mts +3 -3
  122. package/dist/runtime/detect.d.mts +2 -2
  123. package/dist/runtime/node.d.mts +3 -3
  124. package/dist/runtime/paths.d.mts +1 -31
  125. package/dist/runtime.d.mts +4 -4
  126. package/dist/strings.d.mts +1 -16
  127. package/dist/testkit.d.mts +2 -2
  128. package/dist/testkit.mjs +1 -1
  129. package/dist/version.d.mts +0 -13
  130. package/dist/version.mjs +2 -2
  131. package/dreamcli.schema.json +368 -78
  132. package/examples/interactive.ts +6 -5
  133. package/package.json +10 -9
  134. package/skills/cli-creation/SKILL.md +196 -0
  135. package/skills/cli-creation/agents/openai.yaml +4 -0
  136. package/skills/cli-creation/assets/templates/multi-command.bun-test.ts.tpl +20 -0
  137. package/skills/cli-creation/assets/templates/multi-command.test.ts.tpl +20 -0
  138. package/skills/cli-creation/assets/templates/multi-command.ts.tpl +89 -0
  139. package/skills/cli-creation/assets/templates/single-command.bun-test.ts.tpl +29 -0
  140. package/skills/cli-creation/assets/templates/single-command.test.ts.tpl +29 -0
  141. package/skills/cli-creation/assets/templates/single-command.ts.tpl +47 -0
  142. package/skills/cli-creation/references/consumer-workflow.md +65 -0
  143. package/skills/cli-creation/references/pattern-cookbook.md +451 -0
  144. package/skills/cli-creation/references/runtime-notes.md +29 -0
  145. package/skills/cli-creation/scripts/scaffold_cli.py +360 -0
  146. package/dist/core/resolve/property.d.mts +0 -51
  147. package/dist/core/resolve/property.mjs +0 -53
@@ -1,61 +1,28 @@
1
1
  import { OutputPolicy } from "../output/contracts.mjs";
2
- import { CLIPlugin } from "./plugin.mjs";
2
+ import { CommandMeta, CommandSchema } from "../schema/command.mjs";
3
3
  import { CLIError } from "../errors/index.mjs";
4
4
  import { HelpOptions } from "../help/index.mjs";
5
- import { CommandMeta, CommandSchema, ErasedCommand } from "../schema/command.mjs";
6
- import { ParseOptions } from "../parse/index.mjs";
7
- import { CompletionOptions } from "../completion/shells/shared.mjs";
8
- import { Shell } from "../completion/index.mjs";
5
+ import { CLIPlugin } from "./plugin.mjs";
6
+ import { CompiledCommand } from "./compiled.mjs";
9
7
  //#region src/core/cli/planner.d.ts
10
- /**
11
- * Structural subset of CLISchema used by the planner.
12
- *
13
- * Decouples invocation planning from the full CLIBuilder surface so the
14
- * planner can be tested and reasoned about without constructing a real CLI.
15
- * @internal
16
- */
17
- interface PlannerSchemaLike {
18
- /** CLI program name used in help text and error messages. */
19
- readonly name: string;
20
- /** Declared version string; `undefined` disables `--version` interception. */
21
- readonly version: string | undefined;
22
- /** Registered top-level commands available for dispatch. */
23
- readonly commands: readonly ErasedCommand[];
24
- /** Fallback command when no subcommand token matches. */
25
- readonly defaultCommand: ErasedCommand | 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
- /** Plugins forwarded into every matched execution plan. */
39
- readonly plugins: readonly CLIPlugin[];
40
- }
41
8
  /** Root-level help interception outcome. */
42
9
  interface RootHelpOutcome {
43
10
  /** Discriminant — argv matched `--help` / `-h` before any command. */
44
- readonly kind: 'root-help';
11
+ readonly kind: "root-help";
45
12
  /** Help options to render root-level usage. */
46
13
  readonly help: HelpOptions;
47
14
  }
48
15
  /** Root-level version interception outcome. */
49
16
  interface RootVersionOutcome {
50
17
  /** Discriminant — argv matched `--version` / `-V` and schema declares a version. */
51
- readonly kind: 'root-version';
18
+ readonly kind: "root-version";
52
19
  /** Resolved version string to render. */
53
20
  readonly version: string;
54
21
  }
55
22
  /** Root-level `--completions [shell]` interception outcome. */
56
23
  interface RootCompletionsOutcome {
57
24
  /** Discriminant — argv matched the eager `--completions [shell]` flag. */
58
- readonly kind: 'root-completions';
25
+ readonly kind: "root-completions";
59
26
  /**
60
27
  * Resolved, validated target shell, or `undefined` when the flag was given
61
28
  * without a value and the shell should be auto-detected from the environment.
@@ -67,14 +34,14 @@ interface RootCompletionsOutcome {
67
34
  /** CLI-level dispatch failure before command execution starts. */
68
35
  interface DispatchErrorOutcome {
69
36
  /** Discriminant — dispatch could not resolve a command from argv. */
70
- readonly kind: 'dispatch-error';
37
+ readonly kind: "dispatch-error";
71
38
  /** Structured error with suggestion text for the caller to render. */
72
39
  readonly error: CLIError;
73
40
  }
74
41
  /** Successful planner handoff to the shared command execution path. */
75
42
  interface PlannerMatchOutcome {
76
43
  /** Discriminant — dispatch found a matching command for argv. */
77
- readonly kind: 'match';
44
+ readonly kind: "match";
78
45
  /** Fully resolved execution plan ready for the executor pipeline. */
79
46
  readonly plan: CommandExecutionPlan;
80
47
  }
@@ -92,8 +59,8 @@ type DispatchOutcome = RootHelpOutcome | RootVersionOutcome | RootCompletionsOut
92
59
  * propagated ancestor flags are collected and child definitions shadow them.
93
60
  */
94
61
  interface CommandExecutionPlan {
95
- /** Type-erased command instance that owns the handler. */
96
- readonly command: ErasedCommand;
62
+ /** Compiled command node that owns the handler and execution steps. */
63
+ readonly command: CompiledCommand;
97
64
  /** Command schema with propagated ancestor flags merged in. */
98
65
  readonly mergedSchema: CommandSchema;
99
66
  /** Remaining argv tokens after command dispatch consumed the command path. */
@@ -108,7 +75,7 @@ interface CommandExecutionPlan {
108
75
  readonly help: HelpOptions | undefined;
109
76
  }
110
77
  interface BuildCommandExecutionPlanOptions {
111
- readonly command: ErasedCommand;
78
+ readonly command: CompiledCommand;
112
79
  readonly commandPath: readonly CommandSchema[];
113
80
  readonly argv: readonly string[];
114
81
  readonly meta: CommandMeta;
@@ -116,54 +83,14 @@ interface BuildCommandExecutionPlanOptions {
116
83
  readonly output: OutputPolicy;
117
84
  readonly help: HelpOptions | undefined;
118
85
  }
119
- /**
120
- * Dispatch resolved a group command that requires a subcommand selection.
121
- *
122
- * The caller should render subcommand-level help for the matched group.
123
- * @internal
124
- */
125
- interface NeedsSubcommandOutcome {
126
- /** Discriminant — group command matched but no leaf subcommand was selected. */
127
- readonly kind: 'needs-subcommand';
128
- /** The group command that was matched. */
129
- readonly command: ErasedCommand;
130
- /** Full ancestor path from root to this group, used for propagated flag collection. */
131
- readonly commandPath: readonly CommandSchema[];
132
- /** Help options scoped to the group command's bin path. */
133
- readonly help: HelpOptions;
134
- }
135
- /** Full planner result including the `needs-subcommand` variant used by CLIBuilder. @internal */
136
- type InvocationPlan = DispatchOutcome | NeedsSubcommandOutcome;
137
- /** Options bag for {@linkcode planInvocation}. @internal */
138
- interface PlanInvocationOptions {
139
- /** CLI schema subset driving dispatch decisions. */
140
- readonly schema: PlannerSchemaLike;
141
- /** Raw argv tokens (typically `adapter.argv.slice(2)`). */
142
- readonly argv: readonly string[];
143
- /** Root-level help configuration for rendering. */
144
- readonly help: HelpOptions;
145
- /** Output policy propagated into matched execution plans. */
146
- readonly output: OutputPolicy;
147
- }
148
- /** Build a name+alias lookup map for top-level commands. @internal */
149
- declare function buildRootCommandMap(commands: readonly ErasedCommand[]): ReadonlyMap<string, ErasedCommand>;
150
86
  /**
151
87
  * Merge propagated ancestor flags into the matched command schema.
152
88
  *
153
89
  * Child flag definitions win when names collide, matching current CLI
154
90
  * dispatch semantics and the future planner contract.
155
91
  */
156
- declare function mergeCommandSchema(command: ErasedCommand, commandPath: readonly CommandSchema[]): CommandSchema;
92
+ declare function mergeCommandSchema(command: CompiledCommand, commandPath: readonly CommandSchema[]): CommandSchema;
157
93
  /** Build the planner handoff for a matched command invocation. */
158
94
  declare function buildCommandExecutionPlan(options: BuildCommandExecutionPlanOptions): CommandExecutionPlan;
159
- /**
160
- * Decide what to do with an argv invocation before any command executes.
161
- *
162
- * Handles root interception (`--help`, `--version`, `--completions <shell>`,
163
- * bare `help` token), dispatches into the command tree, falls back to the
164
- * default command, and produces structured errors for unknown commands/flags.
165
- * @internal
166
- */
167
- declare function planInvocation(options: PlanInvocationOptions): InvocationPlan;
168
95
  //#endregion
169
- 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 };
96
+ export { type CommandExecutionPlan, type DispatchErrorOutcome, type DispatchOutcome, type OutputPolicy, type PlannerMatchOutcome, type RootCompletionsOutcome, type RootHelpOutcome, type RootVersionOutcome, buildCommandExecutionPlan, mergeCommandSchema };
@@ -1,8 +1,10 @@
1
1
  import { CLIError, ParseError } from "../errors/index.mjs";
2
- import { buildFlagLookup, flagExpectsValue, includesBeforeSeparator } from "../parse/index.mjs";
2
+ import { buildFlagLookup, flagExpectsValue, includesBeforeSeparator, requestsHelp } from "../parse/index.mjs";
3
+ import { builtinEnabled } from "./builtins.mjs";
3
4
  import { collectPropagatedFlags } from "./propagate.mjs";
4
5
  import { normalizeShell } from "../completion/index.mjs";
5
6
  import { dispatch, findClosestCommand } from "./dispatch.mjs";
7
+ import { readRootOutputFlags } from "./root-output-flags.mjs";
6
8
  //#region src/core/cli/planner.ts
7
9
  function buildMeta(schema, helpOptions, commandName) {
8
10
  return {
@@ -58,17 +60,17 @@ function buildCommandExecutionPlan(options) {
58
60
  help: options.help
59
61
  };
60
62
  }
61
- function buildPlannerMatchOutcome(schema, command, commandPath, argv, help, output) {
63
+ function buildPlannerMatchOutcome(options, command, commandPath, argv) {
62
64
  return {
63
65
  kind: "match",
64
66
  plan: buildCommandExecutionPlan({
65
67
  command,
66
68
  commandPath,
67
69
  argv,
68
- meta: buildMeta(schema, help, command.schema.name),
69
- plugins: schema.plugins,
70
- output,
71
- help
70
+ meta: buildMeta(options.schema, options.help, command.schema.name),
71
+ plugins: options.compiled.plugins,
72
+ output: options.output,
73
+ help: options.help
72
74
  })
73
75
  };
74
76
  }
@@ -110,11 +112,11 @@ function findUnknownFlagBeforePositional(argv, flags, parseOptions) {
110
112
  *
111
113
  * @internal
112
114
  */
113
- function scanRootHead(head, valueFlags) {
115
+ function scanRootHead(head, valueFlags, helpOwned) {
114
116
  for (let index = 0; index < head.length; index++) {
115
117
  const token = head[index];
116
118
  if (token === void 0) continue;
117
- if (token === "--help" || token === "-h") return {
119
+ if (helpOwned && (token === "--help" || token === "-h")) return {
118
120
  helpBeforeCommand: true,
119
121
  firstCommandToken: void 0,
120
122
  commandTokenIndex: -1
@@ -146,6 +148,22 @@ function scanRootHead(head, valueFlags) {
146
148
  };
147
149
  }
148
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
+ /**
149
167
  * Detect and resolve the eager `--completions [shell]` flag before dispatch.
150
168
  *
151
169
  * Accepts `--completions <shell>` and `--completions=<shell>`. When no value is
@@ -190,12 +208,6 @@ function planCompletionsFlag(argv, config) {
190
208
  };
191
209
  }
192
210
  }
193
- /** Root-level output flags stripped before dispatch (never part of a command schema). */
194
- const ROOT_OUTPUT_FLAGS = /* @__PURE__ */ new Set([
195
- "--json",
196
- "--quiet",
197
- "-q"
198
- ]);
199
211
  /**
200
212
  * Decide what to do with an argv invocation before any command executes.
201
213
  *
@@ -205,12 +217,12 @@ const ROOT_OUTPUT_FLAGS = /* @__PURE__ */ new Set([
205
217
  * @internal
206
218
  */
207
219
  function planInvocation(options) {
208
- const separatorIndex = options.argv.indexOf("--");
209
- const head = separatorIndex === -1 ? options.argv : options.argv.slice(0, separatorIndex);
210
- const tail = separatorIndex === -1 ? [] : options.argv.slice(separatorIndex);
211
- const filteredHead = head.some((arg) => ROOT_OUTPUT_FLAGS.has(arg)) ? head.filter((arg) => !ROOT_OUTPUT_FLAGS.has(arg)) : head;
212
- const filteredArgv = separatorIndex === -1 ? filteredHead : [...filteredHead, ...tail];
213
- const defaultCommand = options.schema.defaultCommand;
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;
214
226
  const rootValueFlags = defaultCommand !== void 0 ? buildFlagLookup(defaultCommand.schema.flags, options.schema.flagSettings) : void 0;
215
227
  if (options.schema.version !== void 0 && (includesBeforeSeparator(options.argv, "--version") || includesBeforeSeparator(options.argv, "-V"))) return {
216
228
  kind: "root-version",
@@ -220,13 +232,13 @@ function planInvocation(options) {
220
232
  const completionsOutcome = planCompletionsFlag(options.argv, options.schema.completionsFlag);
221
233
  if (completionsOutcome !== void 0) return completionsOutcome;
222
234
  }
223
- const headScan = scanRootHead(filteredHead, rootValueFlags);
235
+ const headScan = scanRootHead(filteredHead, rootValueFlags, helpOwned);
224
236
  if (headScan.helpBeforeCommand) return {
225
237
  kind: "root-help",
226
238
  help: options.help
227
239
  };
228
- if (headScan.firstCommandToken === "help") {
229
- if (!options.schema.commands.some((command) => command.schema.name === "help" || command.schema.aliases.includes("help"))) {
240
+ if (helpOwned && headScan.firstCommandToken === "help") {
241
+ if (!options.compiled.commands.some((command) => command.schema.name === "help" || command.schema.aliases.includes("help"))) {
230
242
  const rest = filteredArgv.slice(headScan.commandTokenIndex + 1);
231
243
  if (rest.length === 0) return {
232
244
  kind: "root-help",
@@ -238,7 +250,11 @@ function planInvocation(options) {
238
250
  });
239
251
  }
240
252
  }
241
- if (options.schema.commands.length === 0 && defaultCommand === void 0) return {
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 {
242
258
  kind: "dispatch-error",
243
259
  error: new CLIError("No commands registered", {
244
260
  code: "NO_ACTION",
@@ -249,17 +265,18 @@ function planInvocation(options) {
249
265
  kind: "root-help",
250
266
  help: options.help
251
267
  };
252
- const result = dispatch(filteredArgv, buildRootCommandMap(defaultCommand !== void 0 && options.schema.defaultCommandRouted ? [...options.schema.commands, defaultCommand] : options.schema.commands), [], rootValueFlags, options.schema.flagSettings);
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);
253
270
  switch (result.kind) {
254
271
  case "unknown": {
255
272
  if (defaultCommand !== void 0 && result.parentPath.length === 0) {
256
- if ((result.input !== "" ? findClosestCommand(result.input, result.candidates) : void 0) === void 0 && canDelegateUnknownRootToDefault(defaultCommand, result.input)) return buildPlannerMatchOutcome(options.schema, defaultCommand, [defaultCommand.schema], filteredArgv, options.help, options.output);
273
+ if ((result.input !== "" ? findClosestCommand(result.input, result.candidates) : void 0) === void 0 && canDelegateUnknownRootToDefault(defaultCommand, result.input)) return buildPlannerMatchOutcome(options, defaultCommand, [defaultCommand.schema], filteredArgv);
257
274
  const unknownFlag = findUnknownFlagBeforePositional(filteredArgv, defaultCommand.schema.flags, options.schema.flagSettings);
258
275
  if (unknownFlag !== void 0) return {
259
276
  kind: "dispatch-error",
260
277
  error: new ParseError(`Unknown flag ${unknownFlag}`, {
261
278
  code: "UNKNOWN_FLAG",
262
- suggest: `Run '${options.schema.name} --help' for available commands`
279
+ ...helpHint(options.schema.name, helpOwned)
263
280
  })
264
281
  };
265
282
  }
@@ -273,7 +290,7 @@ function planInvocation(options) {
273
290
  kind: "dispatch-error",
274
291
  error: new ParseError(`Unknown flag ${unknownFlag}`, {
275
292
  code: "UNKNOWN_FLAG",
276
- suggest: `Run '${options.schema.name} --help' for available commands`
293
+ ...helpHint(options.schema.name, helpOwned)
277
294
  })
278
295
  };
279
296
  }
@@ -283,7 +300,7 @@ function planInvocation(options) {
283
300
  kind: "dispatch-error",
284
301
  error: new ParseError(`Unknown command: ${result.input}`, {
285
302
  code: "UNKNOWN_COMMAND",
286
- suggest: suggestion !== void 0 ? `Did you mean '${suggestion}'?` : `Run '${scopePath} --help' for available commands`
303
+ ...suggestion !== void 0 ? { suggest: `Did you mean '${suggestion}'?` } : helpHint(scopePath, helpOwned)
287
304
  })
288
305
  };
289
306
  }
@@ -299,7 +316,7 @@ function planInvocation(options) {
299
316
  }
300
317
  };
301
318
  }
302
- case "match": return buildPlannerMatchOutcome(options.schema, result.command, result.commandPath, result.remainingArgv, options.help, options.output);
319
+ case "match": return buildPlannerMatchOutcome(options, result.command, result.commandPath, result.remainingArgv);
303
320
  }
304
321
  }
305
322
  //#endregion
@@ -1,6 +1,6 @@
1
+ import { CommandMeta, CommandSchema, Out } from "../schema/command.mjs";
1
2
  import { DeprecationWarning } from "../resolve/contracts.mjs";
2
3
  import "../resolve/index.mjs";
3
- import { CommandMeta, CommandSchema, Out } from "../schema/command.mjs";
4
4
  //#region src/core/cli/plugin.d.ts
5
5
  /** Shared hook payload for a concrete command execution. */
6
6
  interface PluginCommandContext {
@@ -41,7 +41,7 @@ function collectPropagatedFlags(commandPath) {
41
41
  let shadowedByDescendant = false;
42
42
  for (let j = i + 1; j < commandPath.length - 1; j++) {
43
43
  const descendant = commandPath[j];
44
- if (descendant !== void 0 && name in descendant.flags) {
44
+ if (descendant !== void 0 && Object.hasOwn(descendant.flags, name)) {
45
45
  shadowedByDescendant = true;
46
46
  break;
47
47
  }
@@ -0,0 +1 @@
1
+ export {}
@@ -0,0 +1,158 @@
1
+ import { CLIError } from "../errors/index.mjs";
2
+ import { getFlagAliasNames, getFlagNegatedName } from "../schema/flag.mjs";
3
+ import { BUILTIN_NAMES, builtinEnabled, builtinSpelling, builtinTokens } from "./builtins.mjs";
4
+ //#region src/core/cli/reserved-flags.ts
5
+ /**
6
+ * Build-time guard for command flags the CLI root already owns.
7
+ *
8
+ * `--json`, `--quiet`/`-q` and `--help`/`-h` never reach a command handler, and
9
+ * `--version`/`-V` joins them once the CLI declares a version. A command flag
10
+ * spelled the same way can never be set, so registering one throws
11
+ * {@linkcode CLIError} `RESERVED_FLAG` here rather than building a CLI whose
12
+ * flag silently stays at its default (#84).
13
+ *
14
+ * A built-in released through `.builtins({ <name>: 'off' })` drops out of the
15
+ * reserved set, which is what makes the flag declarable (#86).
16
+ *
17
+ * @module dreamcli/core/cli/reserved-flags
18
+ * @internal
19
+ */
20
+ /** Remedy for a reserved token whose only fix is a different spelling. */
21
+ const RENAME = "Rename the flag";
22
+ /** Why the root never hands a command the tokens it strips from argv. */
23
+ const STRIPPED = "The root strips that token before dispatch";
24
+ /** Why a command never receives `--help`, in either interception path. */
25
+ const HELP_INTERCEPTED = "A help request renders before flags are parsed";
26
+ /** Why a command never receives `--version`. */
27
+ const VERSION_INTERCEPTED = "The root intercepts that token before dispatch";
28
+ /** Extra clause offered for `--quiet`, which has a framework equivalent. */
29
+ const STATUS_ALTERNATIVE = "use out.status() for output that root --quiet suppresses";
30
+ /** Offer the `.builtins()` opt-out alongside renaming. */
31
+ function releaseRemedy(name, ...alternatives) {
32
+ return [
33
+ RENAME,
34
+ ...alternatives,
35
+ `release the built-in with .builtins({ ${name}: 'off' }) before registering the command`
36
+ ].join(", or ");
37
+ }
38
+ /** Why the root owns each built-in's tokens. */
39
+ const BUILTIN_EFFECTS = {
40
+ help: HELP_INTERCEPTED,
41
+ json: STRIPPED,
42
+ quiet: STRIPPED
43
+ };
44
+ /** How a collision with each built-in is fixed. */
45
+ const BUILTIN_REMEDIES = {
46
+ help: releaseRemedy("help"),
47
+ json: releaseRemedy("json"),
48
+ quiet: releaseRemedy("quiet", STATUS_ALTERNATIVE)
49
+ };
50
+ /** Reservation for `--version`/`-V`, active once the CLI declares a version. */
51
+ const VERSION_RESERVED = {
52
+ rootSpelling: "--version",
53
+ effect: VERSION_INTERCEPTED,
54
+ remedy: RENAME
55
+ };
56
+ /** Tokens the root owns only once a version is configured. */
57
+ const VERSION_TOKENS = ["version", "V"];
58
+ /**
59
+ * The tokens a CLI's commands may not spell.
60
+ *
61
+ * Built from the shared built-in spelling table, so the reserved set and the spellings
62
+ * the root actually reads cannot drift, and a released built-in is absent here
63
+ * by construction.
64
+ */
65
+ function reservedTokens(version, builtins) {
66
+ const reserved = /* @__PURE__ */ new Map();
67
+ for (const name of BUILTIN_NAMES) {
68
+ if (!builtinEnabled(builtins, name)) continue;
69
+ const entry = {
70
+ rootSpelling: builtinSpelling(name),
71
+ effect: BUILTIN_EFFECTS[name],
72
+ remedy: BUILTIN_REMEDIES[name]
73
+ };
74
+ for (const token of builtinTokens(name)) reserved.set(token, entry);
75
+ }
76
+ if (version !== void 0) for (const token of VERSION_TOKENS) reserved.set(token, VERSION_RESERVED);
77
+ return reserved;
78
+ }
79
+ /** Render a bare token the way argv spells it. */
80
+ function spellingOf(token) {
81
+ return token.length === 1 ? `-${token}` : `--${token}`;
82
+ }
83
+ /** Every spelling one flag answers to, paired with the declaration it came from. */
84
+ function flagSpellings(flagName, flagSchema) {
85
+ const spellings = [[flagName, "name"]];
86
+ for (const alias of getFlagAliasNames(flagSchema, { includeHidden: true })) spellings.push([alias, "alias"]);
87
+ const negated = getFlagNegatedName(flagName, flagSchema);
88
+ if (negated !== void 0) spellings.push([negated, "negation"]);
89
+ return spellings;
90
+ }
91
+ /**
92
+ * Find the first flag in a command tree whose spelling is reserved.
93
+ *
94
+ * @param schema - Command to walk, including its nested subcommands.
95
+ * @param reserved - Reserved tokens for the current CLI configuration.
96
+ * @returns The collision, or `undefined` when the tree is clean.
97
+ *
98
+ * @internal
99
+ */
100
+ function findReservedCollision(schema, reserved) {
101
+ for (const [flagName, flagSchema] of Object.entries(schema.flags)) for (const [token, origin] of flagSpellings(flagName, flagSchema)) {
102
+ const match = reserved.get(token);
103
+ if (match === void 0) continue;
104
+ return {
105
+ commandName: schema.name,
106
+ flagName,
107
+ spelling: spellingOf(token),
108
+ origin,
109
+ reserved: match
110
+ };
111
+ }
112
+ for (const child of schema.commands) {
113
+ const nested = findReservedCollision(child, reserved);
114
+ if (nested !== void 0) return nested;
115
+ }
116
+ }
117
+ /** Describe the colliding declaration the way the error opens. */
118
+ function subjectOf(collision) {
119
+ switch (collision.origin) {
120
+ case "name": return `defines a '${collision.spelling}' flag`;
121
+ case "alias": return `defines a '${collision.spelling}' alias on flag '${collision.flagName}'`;
122
+ case "negation": return `defines a '${collision.spelling}' negated spelling on flag '${collision.flagName}'`;
123
+ }
124
+ }
125
+ /** Build the `RESERVED_FLAG` error for a collision. */
126
+ function reservedFlagError(collision) {
127
+ return new CLIError(`Command '${collision.commandName}' ${subjectOf(collision)}, which is reserved by the root '${collision.reserved.rootSpelling}' flag. ${collision.reserved.effect}, so the command can never receive it`, {
128
+ code: "RESERVED_FLAG",
129
+ details: {
130
+ command: collision.commandName,
131
+ flag: collision.flagName
132
+ },
133
+ suggest: collision.reserved.remedy
134
+ });
135
+ }
136
+ /**
137
+ * Reject command trees declaring a flag the CLI root already owns.
138
+ *
139
+ * @param version - The CLI's declared version; `undefined` leaves
140
+ * `--version`/`-V` available to commands.
141
+ * @param commands - Command trees to walk. `undefined` entries are skipped so
142
+ * callers can pass an absent default command directly.
143
+ * @param builtins - Built-in state; a released built-in reserves nothing.
144
+ * `undefined` keeps every built-in on.
145
+ * @throws {@linkcode CLIError} `RESERVED_FLAG` for the first collision found.
146
+ *
147
+ * @internal
148
+ */
149
+ function assertNoReservedFlagCollisions(version, commands, builtins) {
150
+ const reserved = reservedTokens(version, builtins);
151
+ for (const schema of commands) {
152
+ if (schema === void 0) continue;
153
+ const collision = findReservedCollision(schema, reserved);
154
+ if (collision !== void 0) throw reservedFlagError(collision);
155
+ }
156
+ }
157
+ //#endregion
158
+ export { assertNoReservedFlagCollisions };
@@ -1,47 +1 @@
1
- import { HelpOptions } from "../help/index.mjs";
2
- import { CommandSchema } from "../schema/command.mjs";
3
- //#region src/core/cli/root-help.d.ts
4
- /** Structural subset of `CLISchema` — avoids circular imports through the barrel. */
5
- interface CLISchemaLike {
6
- readonly name: string;
7
- readonly version: string | undefined;
8
- readonly description: string | undefined;
9
- readonly commands: ReadonlyArray<{
10
- readonly schema: CommandSchema;
11
- }>;
12
- readonly defaultCommand: {
13
- readonly schema: CommandSchema;
14
- } | undefined;
15
- /** Whether the default is also a named route — listed in `Commands:` when so. */
16
- readonly defaultCommandRouted?: boolean | undefined;
17
- readonly helpLinks?: {
18
- readonly name: string | undefined;
19
- readonly version: string | undefined;
20
- } | undefined;
21
- readonly completionsFlag?: {
22
- readonly shells: readonly string[];
23
- } | undefined;
24
- /**
25
- * Config discovery settings. Only its presence is read — defined means
26
- * `.config()` enabled the built-in `--config <path>` flag, so root help
27
- * advertises it in `Global options:`.
28
- */
29
- readonly configSettings?: {
30
- readonly appName: string;
31
- } | undefined;
32
- }
33
- /**
34
- * Generate root-level help text for the CLI program.
35
- *
36
- * Shows program name, version, description, usage line, and available
37
- * subcommands. The default command is the CLI's root *surface*: its arguments
38
- * and flags are rendered inline (unless `inlineDefault` is `false`) and it is
39
- * omitted from the `Commands:` list unless `showDefaultInCommands` is set. When
40
- * `.completions({ as: 'flag' })` is active, the eager `--completions <shell>`
41
- * flag is advertised in the `Flags:` section.
42
- *
43
- * @internal
44
- */
45
- declare function formatRootHelp(schema: CLISchemaLike, options?: HelpOptions): string;
46
- //#endregion
47
- export { formatRootHelp };
1
+ export {}