@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,9 +1,11 @@
1
+ import { schemaBrand } from "./brand.mjs";
2
+ import { Verbosity } from "../output/contracts.mjs";
1
3
  import { ProgressHandle, ProgressOptions, SpinnerHandle, SpinnerOptions, TableColumn, TableOptions } from "./activity.mjs";
2
- import { ArgBuilder, ArgConfig, ArgSchema, InferArgs } from "./arg.mjs";
3
4
  import { PromptConfig } from "./prompt.mjs";
4
- import { FlagBuilder, FlagConfig, FlagSchema, InferFlags } from "./flag.mjs";
5
+ import { FlagBuilder, FlagConfig, FlagDefinition, FlagSchema, InferFlags } from "./flag.mjs";
6
+ import { ArgBuilder, ArgConfig, ArgDefinition, ArgSchema, InferArgs } from "./arg.mjs";
5
7
  import { ErasedMiddlewareHandler, Middleware } from "./middleware.mjs";
6
- import { RunOptions, RunResult } from "./run.mjs";
8
+ import { InputSources } from "./provenance.mjs";
7
9
  import { Colors } from "ansispeck";
8
10
  //#region src/core/schema/command.d.ts
9
11
  /**
@@ -26,18 +28,6 @@ type WidenContext<C extends Record<string, unknown>, Output extends Record<strin
26
28
  * using the same first-call replacement rules as middleware.
27
29
  */
28
30
  type WidenDerivedContext<C extends Record<string, unknown>, Output> = Awaited<Output> extends Record<string, unknown> ? WidenContext<C, Awaited<Output>> : C;
29
- /**
30
- * Compile-time state carried through the command builder chain.
31
- *
32
- * `F` accumulates named flag builders; `A` accumulates named arg builders.
33
- * Both start empty (`{}`) and grow as `.flag()` / `.arg()` are called.
34
- */
35
- interface CommandConfig {
36
- /** Accumulated flag builders keyed by flag name. */
37
- readonly flags: Record<string, FlagBuilder<FlagConfig>>;
38
- /** Accumulated arg builders keyed by arg name. */
39
- readonly args: Record<string, ArgBuilder<ArgConfig>>;
40
- }
41
31
  /**
42
32
  * Parameters received by the interactive resolver function.
43
33
  *
@@ -58,7 +48,7 @@ interface InteractiveParams<F extends Record<string, FlagBuilder<FlagConfig>>> {
58
48
  * Only flag names that need prompting should have truthy values.
59
49
  * Flags not mentioned are handled by their per-flag `.prompt()` config.
60
50
  */
61
- type InteractiveResult = Readonly<Record<string, PromptConfig | false | undefined | null | 0 | ''>>;
51
+ type InteractiveResult = Readonly<Record<string, PromptConfig | false | undefined | null | 0 | "">>;
62
52
  /**
63
53
  * Interactive resolver function for command-level prompt control.
64
54
  *
@@ -94,8 +84,6 @@ type InteractiveResolver<F extends Record<string, FlagBuilder<FlagConfig>>> = (p
94
84
  * At runtime, the resolver receives `{ flags: Record<string, unknown> }`
95
85
  * and returns `Record<string, PromptConfig | falsy>`. The phantom types
96
86
  * from `CommandBuilder<F, A>` are erased.
97
- *
98
- * @internal
99
87
  */
100
88
  type ErasedInteractiveResolver = (params: {
101
89
  readonly flags: Readonly<Record<string, unknown>>;
@@ -106,8 +94,14 @@ type ErasedInteractiveResolver = (params: {
106
94
  * Provides structured methods for stdout/stderr, JSON output,
107
95
  * spinners, progress bars, and tables. The real implementation lives in
108
96
  * `src/core/output/`; this interface defines the shape that handlers consume.
97
+ *
98
+ * `Out` is a framework-created, non-exhaustive value: obtain instances from
99
+ * action parameters, `createOutput()`, or `createCaptureOutput()` — do not
100
+ * implement it. New readonly members may be added in minor releases.
109
101
  */
110
102
  interface Out {
103
+ /** Framework-construction seal. Obtain `Out` values from DreamCLI; do not implement this interface. */
104
+ readonly [outBrand]: never;
111
105
  /** Write to stdout (normal output). */
112
106
  log(message: string): void;
113
107
  /** Informational (may be suppressed in quiet mode). */
@@ -148,6 +142,17 @@ interface Out {
148
142
  * expected.
149
143
  */
150
144
  readonly jsonMode: boolean;
145
+ /**
146
+ * Active output verbosity for this command execution.
147
+ *
148
+ * Root `--quiet`/`-q` resolves to `'quiet'`. Most handlers should emit
149
+ * informational output through {@linkcode Out.info | info()},
150
+ * {@linkcode Out.status | status()}, {@linkcode Out.spinner | spinner()},
151
+ * or {@linkcode Out.progress | progress()} and let the channel suppress it
152
+ * automatically. Read this property only when custom rendering or expensive
153
+ * optional work genuinely depends on the active verbosity.
154
+ */
155
+ readonly verbosity: Verbosity;
151
156
  /**
152
157
  * Whether stdout is connected to a TTY (terminal).
153
158
  *
@@ -215,8 +220,8 @@ interface Out {
215
220
  /**
216
221
  * Create a spinner for indeterminate progress feedback.
217
222
  *
218
- * Returns a handle for lifecycle control. In non-TTY/jsonMode,
219
- * returns a no-op handle (or static fallback if configured).
223
+ * Returns a no-op handle in quiet or JSON mode. Otherwise, non-TTY output
224
+ * uses a no-op handle or the configured static fallback.
220
225
  *
221
226
  * @param text - Initial spinner text.
222
227
  * @param options - Fallback strategy for non-TTY environments.
@@ -226,7 +231,7 @@ interface Out {
226
231
  /**
227
232
  * Create a progress bar for measured work.
228
233
  *
229
- * Returns a handle for updating progress. Pass `total` for
234
+ * Returns a no-op handle in quiet or JSON mode. Otherwise, pass `total` for
230
235
  * determinate mode (percentage bar); omit for indeterminate (pulsing).
231
236
  *
232
237
  * @param options - Progress configuration (total, label, fallback).
@@ -283,11 +288,12 @@ interface CommandMeta {
283
288
  /**
284
289
  * The bag of values received by an action handler.
285
290
  *
286
- * - `args` — fully resolved positional arguments
287
- * - `flags` — fully resolved flags
288
- * - `ctx` — derive/middleware-provided context
289
- * - `out` — output channel
290
- * - `meta` — CLI program metadata (name, bin, version, command)
291
+ * - `args`: fully resolved positional arguments
292
+ * - `flags`: fully resolved flags
293
+ * - `sources`: which stage produced each of those values
294
+ * - `ctx`: derive/middleware-provided context
295
+ * - `out`: output channel
296
+ * - `meta`: CLI program metadata (name, bin, version, command)
291
297
  *
292
298
  * The `C` parameter defaults to `Record<string, never>`, making `ctx`
293
299
  * property access a type error until derive or middleware extends it.
@@ -297,6 +303,13 @@ interface ActionParams<F extends Record<string, FlagBuilder<FlagConfig>>, A exte
297
303
  readonly args: Readonly<InferArgs<A>>;
298
304
  /** Fully resolved flag values, typed from `.flag()` definitions. */
299
305
  readonly flags: Readonly<InferFlags<F>>;
306
+ /**
307
+ * Where each resolved value came from, keyed like `flags` and `args`.
308
+ *
309
+ * An input that resolved no value has no record. {@link wasExplicit} answers
310
+ * the explicit-versus-defaulted question; read `stage` for the rest.
311
+ */
312
+ readonly sources: InputSources<F, A>;
300
313
  /** Middleware/derive-provided context, typed from `.middleware()` and `.derive()` chains. */
301
314
  readonly ctx: Readonly<C>;
302
315
  /** Structured output channel for stdout, stderr, JSON, tables, and spinners. */
@@ -323,22 +336,26 @@ type ActionHandler<F extends Record<string, FlagBuilder<FlagConfig>>, A extends
323
336
  *
324
337
  * Follows the same erasure pattern as {@link ErasedDeriveHandler} and
325
338
  * {@link ErasedMiddlewareHandler}.
326
- *
327
- * @internal
328
339
  */
329
340
  type ErasedActionHandler = (params: {
330
341
  readonly args: Readonly<Record<string, unknown>>;
331
342
  readonly flags: Readonly<Record<string, unknown>>;
343
+ readonly sources: ErasedInputSources;
332
344
  readonly ctx: Readonly<Record<string, unknown>>;
333
345
  readonly out: Out;
334
346
  readonly meta: CommandMeta;
335
347
  }) => void | Promise<void>;
348
+ /**
349
+ * The provenance bag as the execution seam carries it, before a handler's own
350
+ * flag and arg names type it.
351
+ */
352
+ type ErasedInputSources = InputSources<Readonly<Record<string, unknown>>, Readonly<Record<string, unknown>>>;
336
353
  /**
337
354
  * The bag of values received by a derive handler.
338
355
  *
339
356
  * Identical to {@link ActionParams}: derives run after full resolution and
340
- * before the action handler, with typed args/flags/current context plus `out`
341
- * and `meta`.
357
+ * before the action handler, with typed args, flags, provenance, and current
358
+ * context plus `out` and `meta`.
342
359
  */
343
360
  type DeriveParams<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown> = Record<string, never>> = ActionParams<F, A, C>;
344
361
  /**
@@ -355,12 +372,11 @@ type DeriveParams<F extends Record<string, FlagBuilder<FlagConfig>>, A extends R
355
372
  type DeriveHandler<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown> = Record<string, never>, Output extends Record<string, unknown> | undefined = undefined> = (params: DeriveParams<F, A, C>) => Output | Promise<Output> | void | Promise<void>;
356
373
  /**
357
374
  * Type-erased derive handler stored on the command builder.
358
- *
359
- * @internal
360
375
  */
361
376
  type ErasedDeriveHandler = (params: {
362
377
  readonly args: Readonly<Record<string, unknown>>;
363
378
  readonly flags: Readonly<Record<string, unknown>>;
379
+ readonly sources: ErasedInputSources;
364
380
  readonly ctx: Readonly<Record<string, unknown>>;
365
381
  readonly out: Out;
366
382
  readonly meta: CommandMeta;
@@ -368,14 +384,12 @@ type ErasedDeriveHandler = (params: {
368
384
  /**
369
385
  * Internal execution step union preserving registration order across
370
386
  * {@linkcode CommandBuilder.derive | derive()} and {@linkcode CommandBuilder.middleware | middleware()}.
371
- *
372
- * @internal
373
387
  */
374
388
  type ExecutionStep = {
375
- readonly kind: 'derive';
389
+ readonly kind: "derive";
376
390
  readonly handler: ErasedDeriveHandler;
377
391
  } | {
378
- readonly kind: 'middleware';
392
+ readonly kind: "middleware";
379
393
  readonly handler: ErasedMiddlewareHandler;
380
394
  };
381
395
  /**
@@ -410,9 +424,11 @@ declare function resolveExampleCommand(command: ExampleCommand, meta: ExampleMet
410
424
  *
411
425
  * Consumers (parser, help generator, CLI dispatcher) read this to
412
426
  * understand the command's shape — flags, args, aliases, subcommands,
413
- * middleware, and interactive resolver.
427
+ * and interactive resolver.
414
428
  */
415
429
  interface CommandSchema {
430
+ /** Type-only seal produced by {@link createCommandSchema}. */
431
+ readonly [schemaBrand]: "command";
416
432
  /** The command name (used for dispatch, e.g. `'deploy'`). */
417
433
  readonly name: string;
418
434
  /** Human-readable description for help text. */
@@ -440,15 +456,6 @@ interface CommandSchema {
440
456
  * @see InteractiveResolver
441
457
  */
442
458
  readonly interactive: ErasedInteractiveResolver | undefined;
443
- /**
444
- * Middleware handlers to run before the action handler.
445
- *
446
- * Executed in registration order — first middleware registered runs
447
- * first and calls `next()` to proceed to subsequent middleware,
448
- * ending with the action handler. Context accumulates via intersection
449
- * at the type level and via object spread at runtime.
450
- */
451
- readonly middleware: readonly ErasedMiddlewareHandler[];
452
459
  /**
453
460
  * Nested subcommand schemas (for help rendering and completion).
454
461
  *
@@ -470,52 +477,125 @@ interface CommandArgEntry {
470
477
  readonly schema: ArgSchema;
471
478
  }
472
479
  /**
473
- * A type-erased command entry for heterogeneous command storage.
474
- *
475
- * Advanced/internal bridge type: most consumers should work with
476
- * {@link CommandBuilder} and never reference `ErasedCommand` directly.
477
- *
478
- * Commands registered via `CLIBuilder.command()` have heterogeneous `F`, `A`,
479
- * and `C` type parameters. At the dispatch level we only need the runtime
480
- * schema (for name/alias matching and help) and the ability to delegate to
481
- * `runCommand()`. This interface captures exactly that contract.
480
+ * A named positional argument entry accepted by {@link createCommandSchema}.
482
481
  *
483
- * The `_execute` function closes over the original typed {@linkcode CommandBuilder},
484
- * preserving full type safety inside the closure while presenting a
485
- * uniform interface to the dispatcher.
486
- *
487
- * Defined here (rather than in the CLI layer) so both {@linkcode CommandBuilder} and
488
- * `CLIBuilder` can reference it without circular imports.
482
+ * The schema may be an {@link ArgDefinition} or an already-built {@link ArgSchema}.
483
+ */
484
+ interface CommandArgEntryDefinition {
485
+ /** User-facing argument name (shown in help as `<name>`). */
486
+ readonly name: string;
487
+ /** Arg definition or an already-built schema. */
488
+ readonly schema: ArgDefinition | ArgSchema;
489
+ }
490
+ /**
491
+ * Input shape accepted by {@link createCommandSchema}.
489
492
  *
490
- * @internal
493
+ * Every field except `name` is optional. Flags, args, and subcommands accept
494
+ * either definitions or already-built schemas.
491
495
  */
492
- interface ErasedCommand {
493
- /** Runtime schema for name matching and help rendering. */
494
- readonly schema: CommandSchema;
496
+ interface CommandDefinition {
497
+ /** The command name used for dispatch. */
498
+ readonly name: string;
495
499
  /**
496
- * Nested subcommands (name/alias → erased child).
497
- *
498
- * Built recursively by `eraseCommand()` in the CLI layer.
499
- * Empty map for leaf commands. The dispatch layer uses this for
500
- * recursive command tree traversal.
501
- *
502
- * @internal
500
+ * Human-readable description for help text.
501
+ * @defaultValue `undefined`
502
+ */
503
+ readonly description?: string | undefined;
504
+ /**
505
+ * Alternative names for this command.
506
+ * @defaultValue `[]`
503
507
  */
504
- readonly subcommands: ReadonlyMap<string, ErasedCommand>;
505
- /** Original command builder captured at the type-erasure boundary. */
506
- readonly _command?: AnyCommandBuilder;
507
- /** Execute this command against argv. Closes over the typed CommandBuilder. */
508
- readonly _execute: (argv: readonly string[], options?: RunOptions) => Promise<RunResult>;
508
+ readonly aliases?: readonly string[] | undefined;
509
+ /**
510
+ * Whether this command is hidden from help listings.
511
+ * @defaultValue `false`
512
+ */
513
+ readonly hidden?: boolean | undefined;
514
+ /**
515
+ * Usage examples for help text.
516
+ * @defaultValue `[]`
517
+ */
518
+ readonly examples?: readonly CommandExample[] | undefined;
519
+ /**
520
+ * Flag definitions or built schemas, keyed by flag name.
521
+ * @defaultValue `{}`
522
+ */
523
+ readonly flags?: Readonly<Record<string, FlagDefinition | FlagSchema>> | undefined;
524
+ /**
525
+ * Ordered positional arg entries.
526
+ * @defaultValue `[]`
527
+ */
528
+ readonly args?: readonly CommandArgEntryDefinition[] | undefined;
529
+ /**
530
+ * Whether an action handler has been registered.
531
+ * @defaultValue `false`
532
+ */
533
+ readonly hasAction?: boolean | undefined;
534
+ /**
535
+ * Command-level interactive resolver.
536
+ * @defaultValue `undefined`
537
+ */
538
+ readonly interactive?: ErasedInteractiveResolver | undefined;
539
+ /**
540
+ * Nested subcommand definitions or built schemas.
541
+ * @defaultValue `[]`
542
+ */
543
+ readonly commands?: readonly (CommandDefinition | CommandSchema)[] | undefined;
509
544
  }
510
545
  /**
511
- * Structural subset of {@linkcode CommandBuilder} consumed by the execution pipeline.
546
+ * Create a {@link CommandSchema} from a plain definition object.
547
+ *
548
+ * Most consumers should prefer {@link command | command()}, which returns a
549
+ * {@link CommandBuilder} with type inference. `createCommandSchema()` is the
550
+ * low-level escape hatch for tooling that composes schemas as data.
551
+ *
552
+ * Flags, args, and subcommands are normalized recursively, so an already-built
553
+ * schema fed back in produces a deep-equal schema.
554
+ *
555
+ * Flag spellings are checked across the whole tree, so a definition whose names,
556
+ * aliases, or negated spellings collide with each other or with a propagated
557
+ * ancestor flag is rejected here. Both flags still parse under their canonical
558
+ * names, so what a collision costs is the shared spelling. Help advertises it on
559
+ * both flags and the parser answers it with one of them.
560
+ * Args go through the same invariants {@link CommandBuilder.arg} enforces.
561
+ * These are the checks the {@link CommandBuilder} applies as flags, args, and
562
+ * subcommands are registered.
563
+ *
564
+ * @param definition - Command name plus optional flags, args, and subcommands.
565
+ * @returns A fully populated {@link CommandSchema}.
566
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` when a name at any depth is
567
+ * empty or contains whitespace, a flag or arg at any depth is named
568
+ * `__proto__`, which JavaScript cannot carry as a plain record key, or a flag
569
+ * record at any depth has a
570
+ * replaced prototype, which hides the entries a name check would read.
571
+ * @throws {CLIError} With code `'FLAG_NAME_COLLISION'` when two flags on one
572
+ * command share a spelling.
573
+ * @throws {CLIError} With code `'PROPAGATED_FLAG_COLLISION'` when a flag shadows
574
+ * a spelling propagated from an ancestor command.
575
+ * @throws {CLIError} With code `'INVALID_BUILDER_STATE'` when a positional comes
576
+ * after a variadic one, or `'DUPLICATE_STDIN_INPUT'` when two inputs on one
577
+ * command consume stdin and either is exclusive.
578
+ *
579
+ * @example
580
+ * ```ts
581
+ * const schema = createCommandSchema({
582
+ * name: 'deploy',
583
+ * description: 'Ship the build',
584
+ * flags: { force: { kind: 'boolean' } },
585
+ * args: [{ name: 'target', schema: { kind: 'string' } }],
586
+ * });
587
+ * ```
588
+ */
589
+ declare function createCommandSchema(definition: CommandDefinition): CommandSchema;
590
+ /**
591
+ * Structural subset of {@linkcode CommandBuilder} accepted by `runCommand()`.
512
592
  *
513
593
  * Avoids generic type parameters so any `CommandBuilder<F, A, C>` satisfies
514
594
  * this interface structurally — no variance constraints, no inference needed.
515
- * Used by `runCommand()` and the shared executor to accept commands without
516
- * requiring TypeScript to resolve {@linkcode CommandBuilder}'s full generic signature.
595
+ * The testkit reads `handler` and `_executionSteps` off it and hands them to
596
+ * the shared executor, so TypeScript never has to resolve
597
+ * {@linkcode CommandBuilder}'s full generic signature.
517
598
  *
518
- * @internal
519
599
  */
520
600
  interface RunnableCommand {
521
601
  readonly schema: CommandSchema;
@@ -529,10 +609,9 @@ interface RunnableCommand {
529
609
  * custom tooling that mirrors the framework's type-erasure boundary.
530
610
  *
531
611
  * Uses widest possible generic bounds so any `CommandBuilder<F, A, C>` is
532
- * assignable. The CLI layer's `eraseCommand()` traverses these to build
533
- * the execution tree.
612
+ * assignable. The CLI layer's `compileCommand()` traverses these to build
613
+ * the execution graph.
534
614
  *
535
- * @internal
536
615
  */
537
616
  type AnyCommandBuilder = CommandBuilder<Record<string, FlagBuilder<FlagConfig>>, Record<string, ArgBuilder<ArgConfig>>, Record<string, unknown>>;
538
617
  /**
@@ -562,32 +641,6 @@ type AnyCommandBuilder = CommandBuilder<Record<string, FlagBuilder<FlagConfig>>,
562
641
  * ```
563
642
  */
564
643
  declare class CommandBuilder<F extends Record<string, FlagBuilder<FlagConfig>> = {}, A extends Record<string, ArgBuilder<ArgConfig>> = {}, C extends Record<string, unknown> = Record<string, never>> {
565
- /** @internal Runtime schema descriptor. */
566
- readonly schema: CommandSchema;
567
- /** @internal The action handler, if registered (type-erased for covariance). */
568
- readonly handler: ErasedActionHandler | undefined;
569
- /**
570
- * @internal Nested sub-command builders (type-erased for heterogeneous storage).
571
- *
572
- * Stored separately from `schema.commands` because builders carry action
573
- * handlers and phantom types needed by `eraseCommand()` in the CLI layer.
574
- * `schema.commands` holds pure `CommandSchema[]` for help/completion.
575
- */
576
- readonly _subcommands: readonly AnyCommandBuilder[];
577
- /**
578
- * @internal Execution steps in registration order.
579
- *
580
- * Distinct from `schema.middleware`: middleware handlers remain in schema
581
- * for backward compatibility, while derives stay command-local and builder-
582
- * scoped so future shared/global middleware can compose cleanly.
583
- */
584
- readonly _executionSteps: readonly ExecutionStep[];
585
- /** @internal Phantom brand for accumulated flag builder types. No runtime value. */
586
- readonly _flags: F;
587
- /** @internal Phantom brand for accumulated arg builder types. No runtime value. */
588
- readonly _args: A;
589
- /** @internal Phantom brand for accumulated context type. No runtime value. */
590
- readonly _ctx: C;
591
644
  /**
592
645
  * Create a command builder from a pre-built schema descriptor.
593
646
  *
@@ -870,6 +923,13 @@ declare class CommandBuilder<F extends Record<string, FlagBuilder<FlagConfig>> =
870
923
  * ```
871
924
  *
872
925
  * @returns The builder (for chaining).
926
+ * @throws {@link CLIError} `INVALID_SCHEMA` when the name is `__proto__`,
927
+ * which a plain record cannot carry.
928
+ * @throws {@link CLIError} `FLAG_NAME_COLLISION` when the command already
929
+ * declares this name, or the new flag's spellings collide with another
930
+ * flag's.
931
+ * @throws {@link CLIError} `PROPAGATED_FLAG_COLLISION` when a spelling
932
+ * collides with one propagated to a registered subcommand.
873
933
  */
874
934
  flag<N extends string, B extends FlagBuilder<FlagConfig>>(name: N & Exclude<N, keyof F>, builder: B): CommandBuilder<F & Record<N, B>, A, C>;
875
935
  /**
@@ -910,13 +970,19 @@ declare class CommandBuilder<F extends Record<string, FlagBuilder<FlagConfig>> =
910
970
  * ```
911
971
  *
912
972
  * @returns The builder (for chaining).
973
+ * @throws {@link CLIError} `INVALID_SCHEMA` when the name is `__proto__`,
974
+ * which a plain record cannot carry.
975
+ * @throws {@link CLIError} `INVALID_BUILDER_STATE` when an earlier arg on this
976
+ * command is variadic, so this one could never be filled.
977
+ * @throws {@link CLIError} `DUPLICATE_STDIN_INPUT` when another input on this
978
+ * command already consumes stdin exclusively.
913
979
  */
914
980
  arg<N extends string, B extends ArgBuilder<ArgConfig>>(name: N & Exclude<N, keyof A>, builder: B): CommandBuilder<F, A & Record<N, B>, C>;
915
981
  /**
916
982
  * Register a nested subcommand on this command.
917
983
  *
918
984
  * The subcommand's builder is stored in `_subcommands` for the CLI layer's
919
- * `eraseCommand()` to traverse when building the execution tree. The
985
+ * `compileCommand()` to traverse when building the execution graph. The
920
986
  * subcommand's `CommandSchema` is also appended to `schema.commands` for
921
987
  * help rendering and completion generation.
922
988
  *
@@ -934,6 +1000,9 @@ declare class CommandBuilder<F extends Record<string, FlagBuilder<FlagConfig>> =
934
1000
  *
935
1001
  * @param sub - Child {@link CommandBuilder} to nest under this command.
936
1002
  * @returns The builder (for chaining).
1003
+ * @throws {@link CLIError} `PROPAGATED_FLAG_COLLISION` when a spelling this
1004
+ * command propagates collides with one the subcommand, or any of its own
1005
+ * descendants, declares.
937
1006
  */
938
1007
  command<F2 extends Record<string, FlagBuilder<FlagConfig>>, A2 extends Record<string, ArgBuilder<ArgConfig>>, C2 extends Record<string, unknown>>(sub: CommandBuilder<F2, A2, C2>): CommandBuilder<F, A, C>;
939
1008
  /**
@@ -1029,4 +1098,4 @@ declare function command(name: string): CommandBuilder;
1029
1098
  */
1030
1099
  declare function group(name: string): CommandBuilder;
1031
1100
  //#endregion
1032
- export { type ActionHandler, type ActionParams, type AnyCommandBuilder, type CommandArgEntry, CommandBuilder, type CommandConfig, type CommandExample, type CommandMeta, type CommandSchema, type DeriveHandler, type DeriveParams, type ErasedActionHandler, type ErasedCommand, type ErasedDeriveHandler, type ErasedInteractiveResolver, type ExampleCommand, type ExampleMeta, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type Out, type RunnableCommand, type WidenContext, type WidenDerivedContext, command, group, resolveExampleCommand };
1101
+ export { type ActionHandler, type ActionParams, type AnyCommandBuilder, type CommandArgEntry, type CommandArgEntryDefinition, CommandBuilder, type CommandDefinition, type CommandExample, type CommandMeta, type CommandSchema, type DeriveHandler, type DeriveParams, type ErasedActionHandler, type ErasedDeriveHandler, type ErasedInputSources, type ErasedInteractiveResolver, type ExampleCommand, type ExampleMeta, type ExecutionStep, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type Out, type RunnableCommand, type WidenContext, type WidenDerivedContext, command, createCommandSchema, group, resolveExampleCommand };