@kjanat/dreamcli 3.0.1 → 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 (137) hide show
  1. package/CHANGELOG.md +951 -1
  2. package/README.md +7 -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 +9 -9
  134. package/skills/cli-creation/SKILL.md +72 -16
  135. package/skills/cli-creation/references/pattern-cookbook.md +169 -11
  136. package/dist/core/resolve/property.d.mts +0 -51
  137. package/dist/core/resolve/property.mjs +0 -53
@@ -1,44 +1,290 @@
1
1
  import { CLIError } from "../errors/index.mjs";
2
- import { getFlagNegatedName } from "./flag.mjs";
2
+ import { createFlagSchema, getFlagNegatedName } from "./flag.mjs";
3
+ import { createArgSchema } from "./arg.mjs";
4
+ import { stdinConsumerReference, stdinConsumers } from "./source.mjs";
3
5
  //#region src/core/schema/command.ts
4
6
  /** Resolve an {@link ExampleCommand} to its string form for the given meta. */
5
7
  function resolveExampleCommand(command, meta) {
6
8
  return typeof command === "function" ? command(meta) : command;
7
9
  }
8
10
  /**
11
+ * Reject a flag name a plain record cannot carry.
12
+ *
13
+ * Assigning `__proto__` on an object literal sets the prototype instead of an
14
+ * entry, so both construction paths refuse the key rather than let the flag
15
+ * vanish.
16
+ *
17
+ * @param commandName - Command the flag was declared on, for the error details.
18
+ * @param name - Proposed flag name.
19
+ * @throws {@link CLIError} `INVALID_SCHEMA` when the name is `__proto__`.
20
+ *
21
+ * @internal
22
+ */
23
+ function assertUsableFlagKey(commandName, name) {
24
+ if (name !== "__proto__") return;
25
+ throw new CLIError("Flag name '__proto__' is not usable as a flag", {
26
+ code: "INVALID_SCHEMA",
27
+ details: {
28
+ command: commandName,
29
+ flag: "__proto__"
30
+ },
31
+ suggest: "Rename the flag, for example to \"proto\""
32
+ });
33
+ }
34
+ /**
35
+ * Reject a flag record whose entries a name check cannot reach.
36
+ *
37
+ * Only own enumerable keys are read. An object literal routes a bare
38
+ * `__proto__` key to the prototype setter, and a record built over another
39
+ * object hides its inherited entries, so in both cases a declared flag is
40
+ * already gone by the time {@link assertUsableFlagKey} sees a name. The
41
+ * replaced prototype is the evidence common to both. `Object.prototype` and
42
+ * `null` (an `Object.create(null)` record) carry no entries of their own and
43
+ * pass.
44
+ *
45
+ * @param commandName - Command the flags were declared on, for the error details.
46
+ * @param flags - Flag record as the caller supplied it.
47
+ * @throws {@link CLIError} `INVALID_SCHEMA` when the record's prototype is
48
+ * replaced.
49
+ *
50
+ * @internal
51
+ */
52
+ function assertUsableFlagRecord(commandName, flags) {
53
+ const prototype = Object.getPrototypeOf(flags);
54
+ if (prototype === Object.prototype || prototype === null) return;
55
+ throw new CLIError(`Command '${commandName}' flag record has a replaced prototype. A '__proto__' key sets the prototype instead of adding a flag, and an inherited flag is never read`, {
56
+ code: "INVALID_SCHEMA",
57
+ details: { command: commandName },
58
+ suggest: "Pass a plain object with no '__proto__' key, or a record built with Object.create(null)"
59
+ });
60
+ }
61
+ /**
62
+ * Reject an arg name a plain record cannot carry.
63
+ *
64
+ * Resolved args reach the handler as a record keyed by arg name, and the parser
65
+ * accumulates positionals into one, so `__proto__` would swallow the value the
66
+ * user typed and hand the handler the prototype instead.
67
+ *
68
+ * @param commandName - Command the arg was declared on, for the error details.
69
+ * @param name - Proposed arg name.
70
+ * @throws {@link CLIError} `INVALID_SCHEMA` when the name is `__proto__`.
71
+ *
72
+ * @internal
73
+ */
74
+ function assertUsableArgKey(commandName, name) {
75
+ if (name !== "__proto__") return;
76
+ throw new CLIError(`Argument name '${name}' is not usable as an argument`, {
77
+ code: "INVALID_SCHEMA",
78
+ details: {
79
+ command: commandName,
80
+ arg: name
81
+ },
82
+ suggest: "Rename the argument, for example to \"proto\""
83
+ });
84
+ }
85
+ /**
86
+ * Merge definition fields onto the {@link CommandSchema} defaults, recursively.
87
+ *
88
+ * @param definition - Command definition to normalize.
89
+ * @returns A fully populated {@link CommandSchema}.
90
+ * @throws {@link CLIError} `INVALID_SCHEMA` when a name at any depth is empty
91
+ * or contains whitespace, a flag or arg is named `__proto__` at any depth,
92
+ * or a flag record at any depth has a replaced prototype.
93
+ * @throws {@link CLIError} `INVALID_BUILDER_STATE` or `DUPLICATE_STDIN_INPUT` when
94
+ * an input breaks the positional-order or stdin invariants.
95
+ *
96
+ * @internal
97
+ */
98
+ function buildCommandSchema(definition) {
99
+ if (definition.name === "" || /\s/u.test(definition.name)) throw new CLIError("Command schema requires a non-empty name without whitespace", {
100
+ code: "INVALID_SCHEMA",
101
+ details: { name: definition.name },
102
+ suggest: "Pass a dispatch name such as { name: \"deploy\" }"
103
+ });
104
+ const flagDefinitions = definition.flags ?? {};
105
+ assertUsableFlagRecord(definition.name, flagDefinitions);
106
+ const flags = {};
107
+ for (const [name, value] of Object.entries(flagDefinitions)) {
108
+ assertUsableFlagKey(definition.name, name);
109
+ const flagSchema = createFlagSchema(value);
110
+ validateFlagStdinEntry(definition.name, name, flagSchema, flags, []);
111
+ flags[name] = flagSchema;
112
+ }
113
+ const args = [];
114
+ for (const entry of definition.args ?? []) {
115
+ const schema = createArgSchema(entry.schema);
116
+ validateArgEntry(definition.name, entry.name, schema, flags, args);
117
+ args.push({
118
+ name: entry.name,
119
+ schema
120
+ });
121
+ }
122
+ return {
123
+ name: definition.name,
124
+ description: definition.description,
125
+ aliases: definition.aliases ?? [],
126
+ hidden: definition.hidden ?? false,
127
+ examples: definition.examples ?? [],
128
+ flags,
129
+ args,
130
+ hasAction: definition.hasAction ?? false,
131
+ interactive: definition.interactive,
132
+ commands: (definition.commands ?? []).map((child) => buildCommandSchema(child))
133
+ };
134
+ }
135
+ /**
136
+ * Create a {@link CommandSchema} from a plain definition object.
137
+ *
138
+ * Most consumers should prefer {@link command | command()}, which returns a
139
+ * {@link CommandBuilder} with type inference. `createCommandSchema()` is the
140
+ * low-level escape hatch for tooling that composes schemas as data.
141
+ *
142
+ * Flags, args, and subcommands are normalized recursively, so an already-built
143
+ * schema fed back in produces a deep-equal schema.
144
+ *
145
+ * Flag spellings are checked across the whole tree, so a definition whose names,
146
+ * aliases, or negated spellings collide with each other or with a propagated
147
+ * ancestor flag is rejected here. Both flags still parse under their canonical
148
+ * names, so what a collision costs is the shared spelling. Help advertises it on
149
+ * both flags and the parser answers it with one of them.
150
+ * Args go through the same invariants {@link CommandBuilder.arg} enforces.
151
+ * These are the checks the {@link CommandBuilder} applies as flags, args, and
152
+ * subcommands are registered.
153
+ *
154
+ * @param definition - Command name plus optional flags, args, and subcommands.
155
+ * @returns A fully populated {@link CommandSchema}.
156
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` when a name at any depth is
157
+ * empty or contains whitespace, a flag or arg at any depth is named
158
+ * `__proto__`, which JavaScript cannot carry as a plain record key, or a flag
159
+ * record at any depth has a
160
+ * replaced prototype, which hides the entries a name check would read.
161
+ * @throws {CLIError} With code `'FLAG_NAME_COLLISION'` when two flags on one
162
+ * command share a spelling.
163
+ * @throws {CLIError} With code `'PROPAGATED_FLAG_COLLISION'` when a flag shadows
164
+ * a spelling propagated from an ancestor command.
165
+ * @throws {CLIError} With code `'INVALID_BUILDER_STATE'` when a positional comes
166
+ * after a variadic one, or `'DUPLICATE_STDIN_INPUT'` when two inputs on one
167
+ * command consume stdin and either is exclusive.
168
+ *
169
+ * @example
170
+ * ```ts
171
+ * const schema = createCommandSchema({
172
+ * name: 'deploy',
173
+ * description: 'Ship the build',
174
+ * flags: { force: { kind: 'boolean' } },
175
+ * args: [{ name: 'target', schema: { kind: 'string' } }],
176
+ * });
177
+ * ```
178
+ */
179
+ function createCommandSchema(definition) {
180
+ const schema = buildCommandSchema(definition);
181
+ validateCommandFlagTree(schema);
182
+ return schema;
183
+ }
184
+ /**
9
185
  * Validate a new arg entry against invariants before adding it to the command.
10
186
  *
187
+ * @param commandName - Command the arg was declared on. A definition tree reaches
188
+ * here at any depth, so every error carries it in `details`.
11
189
  * @param name - Arg name being registered.
12
190
  * @param schema - Runtime descriptor of the arg.
191
+ * @param flags - Already-registered flag schemas on this command.
13
192
  * @param args - Already-registered arg entries on this command.
14
193
  *
15
- * @throws {@link CLIError} `INVALID_BUILDER_STATE` if both `.stdin()` and `.variadic()` are set.
16
- * @throws {@link CLIError} `DUPLICATE_STDIN_ARG` if another arg already uses `.stdin()`.
194
+ * @throws {@link CLIError} `INVALID_SCHEMA` if the name is `__proto__`.
195
+ * @throws {@link CLIError} `INVALID_BUILDER_STATE` if an earlier arg is variadic.
196
+ * @throws {@link CLIError} `DUPLICATE_STDIN_INPUT` if another input already consumes stdin exclusively.
17
197
  *
18
198
  * @internal
19
199
  */
20
- function validateArgEntry(name, schema, args) {
21
- if (schema.stdinMode && schema.variadic) throw new CLIError(`Argument <${name}> cannot be both variadic and stdin-backed`, {
200
+ function validateArgEntry(commandName, name, schema, flags, args) {
201
+ assertUsableArgKey(commandName, name);
202
+ assertVariadicIsLast(commandName, name, args);
203
+ assertStdinExclusivity(commandName, {
204
+ kind: "arg",
205
+ name,
206
+ stdin: schema.stdin
207
+ }, flags, args);
208
+ }
209
+ /**
210
+ * Reject a positional declared after one that consumes the whole tail.
211
+ *
212
+ * A variadic arg takes every remaining positional, so anything registered after
213
+ * it can never be filled, and a second variadic arg has nothing left to collect.
214
+ *
215
+ * @param commandName - Command the arg was declared on.
216
+ * @param name - Arg name being registered.
217
+ * @param args - Already-registered arg entries on this command.
218
+ * @throws {@link CLIError} `INVALID_BUILDER_STATE` when an earlier arg is variadic.
219
+ *
220
+ * @internal
221
+ */
222
+ function assertVariadicIsLast(commandName, name, args) {
223
+ const greedy = args.find((entry) => entry.schema.variadic);
224
+ if (greedy === void 0) return;
225
+ throw new CLIError(`Argument <${name}> comes after variadic argument <${greedy.name}>, which consumes every remaining positional`, {
22
226
  code: "INVALID_BUILDER_STATE",
23
227
  details: {
228
+ command: commandName,
24
229
  arg: name,
25
- stdinMode: true,
26
- variadic: true
27
- },
28
- suggest: "Remove .stdin() or .variadic() from this argument"
29
- });
30
- if (!schema.stdinMode) return;
31
- const existing = args.find((entry) => entry.schema.stdinMode);
32
- if (existing === void 0) return;
33
- throw new CLIError(`Only one stdin argument is allowed; <${existing.name}> is already stdin-backed`, {
34
- code: "DUPLICATE_STDIN_ARG",
35
- details: {
36
- arg: name,
37
- existingArg: existing.name
230
+ variadicArg: greedy.name
38
231
  },
39
- suggest: "Keep .stdin() on a single argument per command"
232
+ suggest: `Declare <${name}> before <${greedy.name}>, or drop .variadic() from <${greedy.name}>`
40
233
  });
41
234
  }
235
+ /**
236
+ * Reject a second stdin consumer when either it or an existing one is exclusive.
237
+ *
238
+ * One command reads stdin once, so an exclusive consumer must be the only one.
239
+ * Several `{ consume: 'broadcast' }` inputs coexist and all receive the same
240
+ * buffer. The rule spans both surfaces, so a flag and an arg conflict with each
241
+ * other exactly as two args do.
242
+ *
243
+ * @param commandName - Command the input was declared on.
244
+ * @param candidate - The input being registered.
245
+ * @param flags - Already-registered flag schemas on this command.
246
+ * @param args - Already-registered arg entries on this command.
247
+ * @throws {@link CLIError} `DUPLICATE_STDIN_INPUT` on a conflict.
248
+ *
249
+ * @internal
250
+ */
251
+ function assertStdinExclusivity(commandName, candidate, flags, args) {
252
+ const stdin = candidate.stdin;
253
+ if (stdin === void 0) return;
254
+ for (const existing of stdinConsumers(flags, args)) {
255
+ if (existing.kind === candidate.kind && existing.name === candidate.name) continue;
256
+ if (stdin.consume === "broadcast" && existing.stdin.consume === "broadcast") continue;
257
+ throw new CLIError(`Only one input may consume stdin exclusively; ${stdinConsumerReference(existing)} already consumes stdin`, {
258
+ code: "DUPLICATE_STDIN_INPUT",
259
+ details: {
260
+ command: commandName,
261
+ ...candidate.kind === "flag" ? { flag: candidate.name } : { arg: candidate.name },
262
+ ...existing.kind === "flag" ? { existingFlag: existing.name } : { existingArg: existing.name }
263
+ },
264
+ suggest: "Keep .stdin() on a single input per command, or declare every stdin input with { consume: 'broadcast' }"
265
+ });
266
+ }
267
+ }
268
+ /**
269
+ * Validate a new flag against the stdin invariants before adding it.
270
+ *
271
+ * @param commandName - Command the flag was declared on.
272
+ * @param name - Flag name being registered.
273
+ * @param schema - Runtime descriptor of the flag.
274
+ * @param flags - Already-registered flag schemas on this command.
275
+ * @param args - Already-registered arg entries on this command.
276
+ * @throws {@link CLIError} `DUPLICATE_STDIN_INPUT` when another input already
277
+ * consumes stdin exclusively.
278
+ *
279
+ * @internal
280
+ */
281
+ function validateFlagStdinEntry(commandName, name, schema, flags, args) {
282
+ assertStdinExclusivity(commandName, {
283
+ kind: "flag",
284
+ name,
285
+ stdin: schema.stdin
286
+ }, flags, args);
287
+ }
42
288
  function formatFlagToken(name, kind) {
43
289
  return kind === "alias" && name.length === 1 ? `-${name}` : `--${name}`;
44
290
  }
@@ -113,11 +359,25 @@ function buildInheritedFlagsForChildren(inherited, local) {
113
359
  for (const [name, schema] of Object.entries(local)) if (schema.propagate) next[name] = schema;
114
360
  return next;
115
361
  }
362
+ /**
363
+ * Reject a command whose flags collide on any spelling, walking subcommands.
364
+ *
365
+ * @param command - Command schema to validate.
366
+ * @param inheritedFlags - Propagated ancestor flags visible at this level.
367
+ * @throws {@link CLIError} `FLAG_NAME_COLLISION` or `PROPAGATED_FLAG_COLLISION`.
368
+ *
369
+ * @internal
370
+ */
116
371
  function validateCommandFlagTree(command, inheritedFlags = {}) {
117
372
  validateLocalFlagCollisions(command.name, command.flags);
118
373
  const visibleInherited = { ...inheritedFlags };
119
374
  for (const name of Object.keys(command.flags)) delete visibleInherited[name];
120
375
  validateInheritedFlagCollisions(command.name, visibleInherited, command.flags);
376
+ const effectiveFlags = {
377
+ ...visibleInherited,
378
+ ...command.flags
379
+ };
380
+ for (const [name, schema] of Object.entries(effectiveFlags)) validateFlagStdinEntry(command.name, name, schema, effectiveFlags, command.args);
121
381
  const inheritedForChildren = buildInheritedFlagsForChildren(inheritedFlags, command.flags);
122
382
  for (const child of command.commands) validateCommandFlagTree(child, inheritedForChildren);
123
383
  }
@@ -166,16 +426,14 @@ var CommandBuilder = class CommandBuilder {
166
426
  * @internal Nested sub-command builders (type-erased for heterogeneous storage).
167
427
  *
168
428
  * Stored separately from `schema.commands` because builders carry action
169
- * handlers and phantom types needed by `eraseCommand()` in the CLI layer.
429
+ * handlers and phantom types needed by `compileCommand()` in the CLI layer.
170
430
  * `schema.commands` holds pure `CommandSchema[]` for help/completion.
171
431
  */
172
432
  _subcommands;
173
433
  /**
174
- * @internal Execution steps in registration order.
434
+ * @internal Derive and middleware steps in registration order.
175
435
  *
176
- * Distinct from `schema.middleware`: middleware handlers remain in schema
177
- * for backward compatibility, while derives stay command-local and builder-
178
- * scoped so future shared/global middleware can compose cleanly.
436
+ * The executor builds the handler chain from this list.
179
437
  */
180
438
  _executionSteps;
181
439
  /**
@@ -338,7 +596,6 @@ var CommandBuilder = class CommandBuilder {
338
596
  middleware(m) {
339
597
  return new CommandBuilder({
340
598
  ...this.schema,
341
- middleware: [...this.schema.middleware, m._handler],
342
599
  hasAction: false
343
600
  }, void 0, this._subcommands, [...this._executionSteps, {
344
601
  kind: "middleware",
@@ -513,9 +770,17 @@ var CommandBuilder = class CommandBuilder {
513
770
  * ```
514
771
  *
515
772
  * @returns The builder (for chaining).
773
+ * @throws {@link CLIError} `INVALID_SCHEMA` when the name is `__proto__`,
774
+ * which a plain record cannot carry.
775
+ * @throws {@link CLIError} `FLAG_NAME_COLLISION` when the command already
776
+ * declares this name, or the new flag's spellings collide with another
777
+ * flag's.
778
+ * @throws {@link CLIError} `PROPAGATED_FLAG_COLLISION` when a spelling
779
+ * collides with one propagated to a registered subcommand.
516
780
  */
517
781
  flag(name, builder) {
518
- if (name in this.schema.flags) throw new CLIError(`Command '${this.schema.name}' already defines flag --${name}`, {
782
+ assertUsableFlagKey(this.schema.name, name);
783
+ if (Object.hasOwn(this.schema.flags, name)) throw new CLIError(`Command '${this.schema.name}' already defines flag --${name}`, {
519
784
  code: "FLAG_NAME_COLLISION",
520
785
  details: {
521
786
  command: this.schema.name,
@@ -524,6 +789,7 @@ var CommandBuilder = class CommandBuilder {
524
789
  surfaceKind: "canonical"
525
790
  }
526
791
  });
792
+ validateFlagStdinEntry(this.schema.name, name, builder.schema, this.schema.flags, this.schema.args);
527
793
  const nextFlags = {
528
794
  ...this.schema.flags,
529
795
  [name]: builder.schema
@@ -574,9 +840,15 @@ var CommandBuilder = class CommandBuilder {
574
840
  * ```
575
841
  *
576
842
  * @returns The builder (for chaining).
843
+ * @throws {@link CLIError} `INVALID_SCHEMA` when the name is `__proto__`,
844
+ * which a plain record cannot carry.
845
+ * @throws {@link CLIError} `INVALID_BUILDER_STATE` when an earlier arg on this
846
+ * command is variadic, so this one could never be filled.
847
+ * @throws {@link CLIError} `DUPLICATE_STDIN_INPUT` when another input on this
848
+ * command already consumes stdin exclusively.
577
849
  */
578
850
  arg(name, builder) {
579
- validateArgEntry(name, builder.schema, this.schema.args);
851
+ validateArgEntry(this.schema.name, name, builder.schema, this.schema.flags, this.schema.args);
580
852
  const entry = {
581
853
  name,
582
854
  schema: builder.schema
@@ -592,7 +864,7 @@ var CommandBuilder = class CommandBuilder {
592
864
  * Register a nested subcommand on this command.
593
865
  *
594
866
  * The subcommand's builder is stored in `_subcommands` for the CLI layer's
595
- * `eraseCommand()` to traverse when building the execution tree. The
867
+ * `compileCommand()` to traverse when building the execution graph. The
596
868
  * subcommand's `CommandSchema` is also appended to `schema.commands` for
597
869
  * help rendering and completion generation.
598
870
  *
@@ -610,6 +882,9 @@ var CommandBuilder = class CommandBuilder {
610
882
  *
611
883
  * @param sub - Child {@link CommandBuilder} to nest under this command.
612
884
  * @returns The builder (for chaining).
885
+ * @throws {@link CLIError} `PROPAGATED_FLAG_COLLISION` when a spelling this
886
+ * command propagates collides with one the subcommand, or any of its own
887
+ * descendants, declares.
613
888
  */
614
889
  command(sub) {
615
890
  const nextSchema = {
@@ -693,19 +968,7 @@ var CommandBuilder = class CommandBuilder {
693
968
  * @returns A fresh {@link CommandBuilder} with empty flags, args, and context.
694
969
  */
695
970
  function command(name) {
696
- return new CommandBuilder({
697
- name,
698
- description: void 0,
699
- aliases: [],
700
- hidden: false,
701
- examples: [],
702
- flags: {},
703
- args: [],
704
- hasAction: false,
705
- interactive: void 0,
706
- middleware: [],
707
- commands: []
708
- });
971
+ return new CommandBuilder(createCommandSchema({ name }));
709
972
  }
710
973
  /**
711
974
  * Create a command builder intended for use as a command group.
@@ -733,4 +996,4 @@ function group(name) {
733
996
  return command(name);
734
997
  }
735
998
  //#endregion
736
- export { CommandBuilder, command, group, resolveExampleCommand };
999
+ export { CommandBuilder, command, createCommandSchema, group, resolveExampleCommand };