@kjanat/dreamcli 1.0.0 → 2.0.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 (217) hide show
  1. package/CHANGELOG.md +63 -6
  2. package/LICENSE +1 -1
  3. package/README.md +296 -164
  4. package/dist/core/cli/dispatch.d.mts +85 -0
  5. package/dist/core/cli/dispatch.mjs +1 -0
  6. package/dist/core/cli/index.d.mts +418 -0
  7. package/dist/core/cli/index.mjs +1 -0
  8. package/dist/core/cli/planner.d.mts +143 -0
  9. package/dist/core/cli/planner.mjs +1 -0
  10. package/dist/core/cli/plugin.d.mts +94 -0
  11. package/dist/core/cli/plugin.mjs +1 -0
  12. package/dist/core/cli/propagate.d.mts +39 -0
  13. package/dist/core/cli/propagate.mjs +1 -0
  14. package/dist/core/cli/root-help.d.mts +28 -0
  15. package/dist/core/cli/root-help.mjs +7 -0
  16. package/dist/core/cli/root-surface.d.mts +42 -0
  17. package/dist/core/cli/root-surface.mjs +1 -0
  18. package/dist/core/cli/runtime-preflight.d.mts +149 -0
  19. package/dist/core/cli/runtime-preflight.mjs +1 -0
  20. package/dist/core/completion/index.d.mts +46 -0
  21. package/dist/core/completion/index.mjs +1 -0
  22. package/dist/core/completion/shells/bash.d.mts +24 -0
  23. package/dist/core/completion/shells/bash.mjs +3 -0
  24. package/dist/core/completion/shells/fish.d.mts +20 -0
  25. package/dist/core/completion/shells/fish.mjs +2 -0
  26. package/dist/core/completion/shells/powershell.d.mts +14 -0
  27. package/dist/core/completion/shells/powershell.mjs +2 -0
  28. package/dist/core/completion/shells/shared.d.mts +139 -0
  29. package/dist/core/completion/shells/shared.mjs +1 -0
  30. package/dist/core/completion/shells/zsh.d.mts +24 -0
  31. package/dist/core/completion/shells/zsh.mjs +2 -0
  32. package/dist/core/config/index.d.mts +161 -0
  33. package/dist/core/config/index.mjs +1 -0
  34. package/dist/core/config/package-json.d.mts +68 -0
  35. package/dist/core/config/package-json.mjs +1 -0
  36. package/dist/core/errors/index.d.mts +126 -0
  37. package/dist/core/errors/index.mjs +1 -0
  38. package/dist/core/execution/index.d.mts +49 -0
  39. package/dist/core/execution/index.mjs +1 -0
  40. package/dist/core/help/index.d.mts +49 -0
  41. package/dist/core/help/index.mjs +8 -0
  42. package/dist/core/json-schema/index.d.mts +109 -0
  43. package/dist/core/json-schema/index.mjs +55 -0
  44. package/dist/core/json-schema/meta-descriptions.generated.d.mts +185 -0
  45. package/dist/core/json-schema/meta-descriptions.generated.mjs +28 -0
  46. package/dist/core/output/activity.d.mts +194 -0
  47. package/dist/core/output/activity.mjs +1 -0
  48. package/dist/core/output/contracts.d.mts +88 -0
  49. package/dist/core/output/contracts.mjs +1 -0
  50. package/dist/core/output/display-value.d.mts +19 -0
  51. package/dist/core/output/display-value.mjs +1 -0
  52. package/dist/core/output/index.d.mts +280 -0
  53. package/dist/core/output/index.mjs +2 -0
  54. package/dist/core/output/renderers.d.mts +46 -0
  55. package/dist/core/output/renderers.mjs +1 -0
  56. package/dist/core/output/writer.d.mts +40 -0
  57. package/dist/core/output/writer.mjs +1 -0
  58. package/dist/core/parse/index.d.mts +79 -0
  59. package/dist/core/parse/index.mjs +1 -0
  60. package/dist/core/prompt/index.d.mts +205 -0
  61. package/dist/core/prompt/index.mjs +6 -0
  62. package/dist/core/resolve/args.d.mts +8 -0
  63. package/dist/core/resolve/args.mjs +1 -0
  64. package/dist/core/resolve/coerce.d.mts +22 -0
  65. package/dist/core/resolve/coerce.mjs +1 -0
  66. package/dist/core/resolve/config.d.mts +10 -0
  67. package/dist/core/resolve/config.mjs +1 -0
  68. package/dist/core/resolve/contracts.d.mts +112 -0
  69. package/dist/core/resolve/errors.d.mts +11 -0
  70. package/dist/core/resolve/errors.mjs +2 -0
  71. package/dist/core/resolve/flags.d.mts +10 -0
  72. package/dist/core/resolve/flags.mjs +1 -0
  73. package/dist/core/resolve/index.d.mts +42 -0
  74. package/dist/core/resolve/index.mjs +1 -0
  75. package/dist/core/resolve/property.d.mts +47 -0
  76. package/dist/core/resolve/property.mjs +1 -0
  77. package/dist/core/schema/activity.d.mts +169 -0
  78. package/dist/core/schema/arg.d.mts +559 -0
  79. package/dist/core/schema/arg.mjs +1 -0
  80. package/dist/core/schema/command.d.mts +960 -0
  81. package/dist/core/schema/command.mjs +1 -0
  82. package/dist/core/schema/flag.d.mts +491 -0
  83. package/dist/core/schema/flag.mjs +1 -0
  84. package/dist/core/schema/index.d.mts +8 -0
  85. package/dist/core/schema/middleware.d.mts +122 -0
  86. package/dist/core/schema/middleware.mjs +1 -0
  87. package/dist/core/schema/prompt.d.mts +117 -0
  88. package/dist/core/schema/run.d.mts +171 -0
  89. package/dist/core/schema-dsl/runtime.d.mts +144 -0
  90. package/dist/core/schema-dsl/runtime.mjs +2 -0
  91. package/dist/core/schema-dsl/to-json-schema.d.mts +30 -0
  92. package/dist/core/schema-dsl/to-json-schema.mjs +1 -0
  93. package/dist/core/testkit/index.d.mts +54 -0
  94. package/dist/core/testkit/index.mjs +1 -0
  95. package/dist/index.d.mts +28 -920
  96. package/dist/index.mjs +1 -10
  97. package/dist/runtime/adapter.d.mts +212 -0
  98. package/dist/{adapter-B37d9oia.mjs → runtime/adapter.mjs} +1 -1
  99. package/dist/runtime/auto.d.mts +26 -0
  100. package/dist/runtime/auto.mjs +1 -0
  101. package/dist/runtime/bun.d.mts +28 -0
  102. package/dist/runtime/bun.mjs +1 -0
  103. package/dist/runtime/deno.d.mts +76 -0
  104. package/dist/runtime/deno.mjs +2 -0
  105. package/dist/runtime/detect.d.mts +86 -0
  106. package/dist/runtime/detect.mjs +1 -0
  107. package/dist/runtime/index.d.mts +7 -0
  108. package/dist/runtime/node.d.mts +65 -0
  109. package/dist/runtime/node.mjs +2 -0
  110. package/dist/runtime/paths.d.mts +31 -0
  111. package/dist/runtime/paths.mjs +1 -0
  112. package/dist/runtime/support.d.mts +42 -0
  113. package/dist/runtime/support.mjs +1 -0
  114. package/dist/runtime.d.mts +6 -252
  115. package/dist/runtime.mjs +1 -1
  116. package/dist/testkit.d.mts +5 -24
  117. package/dist/testkit.mjs +1 -1
  118. package/dist/version.d.mts +16 -0
  119. package/dist/version.mjs +1 -0
  120. package/dreamcli.schema.json +338 -0
  121. package/examples/basic.ts +2 -2
  122. package/examples/gh/package.json +7 -11
  123. package/examples/gh/src/commands/auth.ts +2 -2
  124. package/examples/gh/src/commands/issue.ts +4 -4
  125. package/examples/gh/src/commands/pr.ts +4 -4
  126. package/examples/gh/src/docs.ts +11 -0
  127. package/examples/gh/src/lib/auth.ts +1 -1
  128. package/examples/gh/src/main.test.ts +6 -5
  129. package/examples/gh/src/main.ts +8 -6
  130. package/examples/interactive.ts +3 -3
  131. package/examples/json-mode.ts +4 -6
  132. package/examples/middleware.ts +3 -3
  133. package/examples/multi-command.ts +3 -3
  134. package/examples/spinner-progress.ts +5 -5
  135. package/examples/testing.ts +8 -6
  136. package/package.json +70 -44
  137. package/src/core/cli/dispatch.ts +4 -0
  138. package/src/core/cli/index.ts +185 -632
  139. package/src/core/cli/planner.ts +413 -0
  140. package/src/core/cli/plugin.ts +7 -1
  141. package/src/core/cli/propagate.ts +1 -1
  142. package/src/core/cli/runtime-preflight.ts +409 -0
  143. package/src/core/completion/index.ts +15 -9
  144. package/src/core/completion/shells/bash.ts +6 -3
  145. package/src/core/completion/shells/fish.ts +245 -10
  146. package/src/core/completion/shells/powershell.ts +390 -9
  147. package/src/core/completion/shells/shared.ts +4 -4
  148. package/src/core/completion/shells/zsh.ts +12 -7
  149. package/src/core/config/index.ts +7 -4
  150. package/src/core/config/package-json.ts +6 -2
  151. package/src/core/errors/index.ts +23 -8
  152. package/src/core/execution/index.ts +270 -0
  153. package/src/core/help/index.ts +13 -15
  154. package/src/core/json-schema/index.ts +193 -7
  155. package/src/core/json-schema/meta-descriptions.generated.ts +202 -0
  156. package/src/core/output/contracts.ts +194 -0
  157. package/src/core/output/index.ts +47 -82
  158. package/src/core/output/renderers.ts +125 -0
  159. package/src/core/parse/index.ts +39 -21
  160. package/src/core/prompt/index.ts +44 -27
  161. package/src/core/resolve/args.ts +144 -0
  162. package/src/core/resolve/coerce.ts +432 -0
  163. package/src/core/resolve/config.ts +26 -0
  164. package/src/core/resolve/contracts.ts +135 -0
  165. package/src/core/resolve/errors.ts +227 -0
  166. package/src/core/resolve/flags.ts +205 -0
  167. package/src/core/resolve/index.ts +41 -1264
  168. package/src/core/resolve/property.ts +99 -0
  169. package/src/core/schema/activity.ts +3 -0
  170. package/src/core/schema/arg.ts +26 -14
  171. package/src/core/schema/command.ts +265 -38
  172. package/src/core/schema/flag.ts +120 -15
  173. package/src/core/schema/index.ts +11 -2
  174. package/src/core/schema/middleware.ts +6 -6
  175. package/src/core/schema/prompt.ts +9 -1
  176. package/src/core/schema/run.ts +25 -17
  177. package/src/core/schema-dsl/index.ts +109 -0
  178. package/src/core/schema-dsl/parse.ts +262 -0
  179. package/src/core/schema-dsl/runtime.ts +609 -0
  180. package/src/core/schema-dsl/to-json-schema.ts +102 -0
  181. package/src/core/testkit/index.ts +55 -297
  182. package/src/index.ts +10 -4
  183. package/src/runtime/adapter.ts +13 -10
  184. package/src/runtime/auto.ts +3 -3
  185. package/src/runtime/bun.ts +4 -4
  186. package/src/runtime/deno.ts +43 -29
  187. package/src/runtime/detect.ts +4 -1
  188. package/src/runtime/index.ts +1 -1
  189. package/src/runtime/node.ts +43 -21
  190. package/src/runtime/paths.ts +9 -3
  191. package/src/runtime/support.ts +20 -4
  192. package/src/runtime.ts +1 -1
  193. package/src/testkit.ts +10 -8
  194. package/dist/adapter-CCSh5juX.cjs +0 -1
  195. package/dist/adapter-DIwO-q7K.d.mts +0 -3447
  196. package/dist/adapter-DQnxxLiE.d.cts +0 -3447
  197. package/dist/auto-5cjZaF9V.mjs +0 -3
  198. package/dist/auto-B0eSgoDw.cjs +0 -3
  199. package/dist/index.cjs +0 -10
  200. package/dist/index.d.cts +0 -920
  201. package/dist/runtime.cjs +0 -1
  202. package/dist/runtime.d.cts +0 -253
  203. package/dist/testkit-CEDYPvhF.mjs +0 -14
  204. package/dist/testkit-ClIKijxC.cjs +0 -14
  205. package/dist/testkit.cjs +0 -1
  206. package/dist/testkit.d.cts +0 -25
  207. package/examples/gh/tsconfig.json +0 -37
  208. package/examples/tsconfig.json +0 -17
  209. package/src/core/cli/AGENTS.md +0 -72
  210. package/src/core/completion/AGENTS.md +0 -72
  211. package/src/core/completion/completion-test-helpers.ts +0 -48
  212. package/src/core/output/AGENTS.md +0 -69
  213. package/src/core/resolve/AGENTS.md +0 -69
  214. package/src/core/schema/AGENTS.md +0 -61
  215. package/src/core/testkit/AGENTS.md +0 -55
  216. package/src/runtime/AGENTS.md +0 -74
  217. package/src/runtime/test-helpers.ts +0 -40
@@ -1,10 +1,10 @@
1
1
  /**
2
2
  * Command schema builder with flag/arg composition and type accumulation.
3
3
  *
4
- * The `command()` factory returns an immutable `CommandBuilder` whose generic
5
- * parameters track accumulated flag and arg builder types. Chaining `.flag()`
6
- * and `.arg()` calls produces progressively narrower types. The `.action()`
7
- * handler receives fully typed `{ args, flags, ctx, out }`.
4
+ * The {@linkcode command} factory returns an immutable {@linkcode CommandBuilder}
5
+ * whose generic parameters track accumulated flag and arg builder types. Chaining
6
+ * `.flag()` and `.arg()` calls produces progressively narrower types. The
7
+ * `.action()` handler receives fully typed `{ args, flags, ctx, out, meta }`.
8
8
  *
9
9
  * @module dreamcli/core/schema/command
10
10
  */
@@ -58,7 +58,9 @@ type WidenDerivedContext<C extends Record<string, unknown>, Output> =
58
58
  * Both start empty (`{}`) and grow as `.flag()` / `.arg()` are called.
59
59
  */
60
60
  interface CommandConfig {
61
+ /** Accumulated flag builders keyed by flag name. */
61
62
  readonly flags: Record<string, FlagBuilder<FlagConfig>>;
63
+ /** Accumulated arg builders keyed by arg name. */
62
64
  readonly args: Record<string, ArgBuilder<ArgConfig>>;
63
65
  }
64
66
 
@@ -97,6 +99,8 @@ type InteractiveResult = Readonly<Record<string, PromptConfig | false | undefine
97
99
  *
98
100
  * @example
99
101
  * ```ts
102
+ * import { command, flag } from '@kjanat/dreamcli';
103
+ *
100
104
  * const deploy = command('deploy')
101
105
  * .flag('region', flag.enum(['us', 'eu', 'ap']))
102
106
  * .interactive(({ flags }) => ({
@@ -105,7 +109,9 @@ type InteractiveResult = Readonly<Record<string, PromptConfig | false | undefine
105
109
  * message: 'Select region',
106
110
  * },
107
111
  * }))
108
- * .action(({ flags }) => { ... });
112
+ * .action(({ flags, out }) => {
113
+ * out.log(`Deploying to ${flags.region}`);
114
+ * });
109
115
  * ```
110
116
  */
111
117
  type InteractiveResolver<F extends Record<string, FlagBuilder<FlagConfig>>> = (
@@ -113,10 +119,10 @@ type InteractiveResolver<F extends Record<string, FlagBuilder<FlagConfig>>> = (
113
119
  ) => InteractiveResult;
114
120
 
115
121
  /**
116
- * Type-erased interactive resolver stored on `CommandSchema`.
122
+ * Type-erased interactive resolver stored on {@linkcode CommandSchema}.
117
123
  *
118
124
  * Advanced bridge type: most consumers should use {@link InteractiveResolver}
119
- * via `command().interactive(...)` and never reference this alias directly.
125
+ * via {@linkcode command | command().interactive()} and never reference this alias directly.
120
126
  *
121
127
  * At runtime, the resolver receives `{ flags: Record<string, unknown> }`
122
128
  * and returns `Record<string, PromptConfig | falsy>`. The phantom types
@@ -244,7 +250,7 @@ interface Out {
244
250
  * handle is active, or when the handle was already stopped.
245
251
  *
246
252
  * The framework calls this automatically in `runCommand()` and
247
- * `cli.run()`. Direct users of `createOutput()` should call it
253
+ * `cli().run()`. Direct users of `createOutput()` should call it
248
254
  * themselves after the handler returns or throws.
249
255
  *
250
256
  * @example
@@ -297,10 +303,15 @@ interface ActionParams<
297
303
  A extends Record<string, ArgBuilder<ArgConfig>>,
298
304
  C extends Record<string, unknown> = Record<string, never>,
299
305
  > {
306
+ /** Fully resolved positional argument values, typed from `.arg()` definitions. */
300
307
  readonly args: Readonly<InferArgs<A>>;
308
+ /** Fully resolved flag values, typed from `.flag()` definitions. */
301
309
  readonly flags: Readonly<InferFlags<F>>;
310
+ /** Middleware/derive-provided context, typed from `.middleware()` and `.derive()` chains. */
302
311
  readonly ctx: Readonly<C>;
312
+ /** Structured output channel for stdout, stderr, JSON, tables, and spinners. */
303
313
  readonly out: Out;
314
+ /** Runtime metadata about the CLI program and current command. */
304
315
  readonly meta: CommandMeta;
305
316
  }
306
317
 
@@ -317,6 +328,28 @@ type ActionHandler<
317
328
  C extends Record<string, unknown> = Record<string, never>,
318
329
  > = (params: ActionParams<F, A, C>) => void | Promise<void>;
319
330
 
331
+ /**
332
+ * Type-erased action handler stored on {@linkcode CommandBuilder}.
333
+ *
334
+ * The typed {@linkcode ActionHandler} from `.action()` is cast to this
335
+ * erased form at the type-erasure boundary, keeping {@linkcode CommandBuilder}
336
+ * covariant in its generic parameters. This enables structural
337
+ * compatibility across TypeScript declaration-file boundaries where
338
+ * generic inference may fall back to constraint types.
339
+ *
340
+ * Follows the same erasure pattern as {@link ErasedDeriveHandler} and
341
+ * {@link ErasedMiddlewareHandler}.
342
+ *
343
+ * @internal
344
+ */
345
+ type ErasedActionHandler = (params: {
346
+ readonly args: Readonly<Record<string, unknown>>;
347
+ readonly flags: Readonly<Record<string, unknown>>;
348
+ readonly ctx: Readonly<Record<string, unknown>>;
349
+ readonly out: Out;
350
+ readonly meta: CommandMeta;
351
+ }) => void | Promise<void>;
352
+
320
353
  /**
321
354
  * The bag of values received by a derive handler.
322
355
  *
@@ -334,11 +367,11 @@ type DeriveParams<
334
367
  * Command-scoped typed pre-action handler.
335
368
  *
336
369
  * Derive handlers may:
337
- * - validate resolved input and throw `CLIError`
370
+ * - validate resolved input and throw {@linkcode CLIError}
338
371
  * - return `undefined` to continue without changing context
339
372
  * - return an object whose properties merge into `ctx` downstream
340
373
  *
341
- * They cannot wrap downstream execution; use `middleware()` for that.
374
+ * They cannot wrap downstream execution; use {@linkcode middleware} for that.
342
375
  */
343
376
  type DeriveHandler<
344
377
  F extends Record<string, FlagBuilder<FlagConfig>>,
@@ -365,7 +398,7 @@ type ErasedDeriveHandler = (params: {
365
398
 
366
399
  /**
367
400
  * Internal execution step union preserving registration order across
368
- * `derive()` and `middleware()`.
401
+ * {@linkcode CommandBuilder.derive | derive()} and {@linkcode CommandBuilder.middleware | middleware()}.
369
402
  *
370
403
  * @internal
371
404
  */
@@ -449,7 +482,9 @@ interface CommandSchema {
449
482
  * The array ordering in {@link CommandSchema.args} determines CLI position.
450
483
  */
451
484
  interface CommandArgEntry {
485
+ /** User-facing argument name (shown in help as `<name>`). */
452
486
  readonly name: string;
487
+ /** Runtime descriptor controlling parsing, presence, and coercion. */
453
488
  readonly schema: ArgSchema;
454
489
  }
455
490
 
@@ -493,6 +528,156 @@ function validateArgEntry(name: string, schema: ArgSchema, args: readonly Comman
493
528
  );
494
529
  }
495
530
 
531
+ // --- Flag collision validation
532
+
533
+ type FlagFormKind = 'canonical' | 'alias';
534
+
535
+ interface FlagForm {
536
+ readonly owner: string;
537
+ readonly name: string;
538
+ readonly kind: FlagFormKind;
539
+ readonly hidden: boolean;
540
+ }
541
+
542
+ function formatFlagToken(name: string, kind: FlagFormKind): string {
543
+ return kind === 'alias' && name.length === 1 ? `-${name}` : `--${name}`;
544
+ }
545
+
546
+ function describeFlagForm(form: FlagForm): string {
547
+ if (form.kind === 'canonical') {
548
+ return `canonical flag ${formatFlagToken(form.name, form.kind)}`;
549
+ }
550
+
551
+ const aliasType = form.name.length === 1 ? 'short alias' : 'long alias';
552
+ return `${form.hidden ? 'hidden ' : ''}${aliasType} ${formatFlagToken(form.name, form.kind)}`;
553
+ }
554
+
555
+ function listFlagForms(name: string, schema: FlagSchema): readonly FlagForm[] {
556
+ return [
557
+ {
558
+ owner: name,
559
+ name,
560
+ kind: 'canonical',
561
+ hidden: false,
562
+ },
563
+ ...schema.aliases.map((alias) => ({
564
+ owner: name,
565
+ name: alias.name,
566
+ kind: 'alias' as const,
567
+ hidden: alias.hidden,
568
+ })),
569
+ ];
570
+ }
571
+
572
+ function throwFlagCollisionError(
573
+ commandName: string,
574
+ form: FlagForm,
575
+ existing: FlagForm,
576
+ options?: { inherited?: boolean },
577
+ ): never {
578
+ const inherited = options?.inherited ?? false;
579
+ const existingOwner = `flag ${formatFlagToken(existing.owner, 'canonical')}`;
580
+ const subject = `Command '${commandName}' ${existingOwner}`;
581
+
582
+ throw new CLIError(
583
+ inherited
584
+ ? `${subject} propagates ${describeFlagForm(existing)}, which collides with ${describeFlagForm(form)} on flag ${formatFlagToken(form.owner, 'canonical')}`
585
+ : `Command '${commandName}' flag ${formatFlagToken(form.owner, 'canonical')} ${describeFlagForm(form)} collides with ${describeFlagForm(existing)} on ${existingOwner}`,
586
+ {
587
+ code: inherited ? 'PROPAGATED_FLAG_COLLISION' : 'FLAG_NAME_COLLISION',
588
+ details: {
589
+ command: commandName,
590
+ flag: form.owner,
591
+ surface: form.name,
592
+ surfaceKind: form.kind,
593
+ hidden: form.hidden,
594
+ existingFlag: existing.owner,
595
+ existingSurface: existing.name,
596
+ existingSurfaceKind: existing.kind,
597
+ existingHidden: existing.hidden,
598
+ inherited,
599
+ },
600
+ },
601
+ );
602
+ }
603
+
604
+ function validateLocalFlagCollisions(
605
+ commandName: string,
606
+ flags: Readonly<Record<string, FlagSchema>>,
607
+ ): void {
608
+ const seen = new Map<string, FlagForm>();
609
+
610
+ for (const [name, schema] of Object.entries(flags)) {
611
+ for (const form of listFlagForms(name, schema)) {
612
+ const existing = seen.get(form.name);
613
+ if (existing !== undefined) {
614
+ throwFlagCollisionError(commandName, form, existing);
615
+ }
616
+ seen.set(form.name, form);
617
+ }
618
+ }
619
+ }
620
+
621
+ function validateInheritedFlagCollisions(
622
+ commandName: string,
623
+ inherited: Readonly<Record<string, FlagSchema>>,
624
+ local: Readonly<Record<string, FlagSchema>>,
625
+ ): void {
626
+ const inheritedForms = new Map<string, FlagForm>();
627
+
628
+ for (const [name, schema] of Object.entries(inherited)) {
629
+ for (const form of listFlagForms(name, schema)) {
630
+ inheritedForms.set(form.name, form);
631
+ }
632
+ }
633
+
634
+ for (const [name, schema] of Object.entries(local)) {
635
+ for (const form of listFlagForms(name, schema)) {
636
+ const existing = inheritedForms.get(form.name);
637
+ if (existing !== undefined) {
638
+ throwFlagCollisionError(commandName, form, existing, { inherited: true });
639
+ }
640
+ }
641
+ }
642
+ }
643
+
644
+ function buildInheritedFlagsForChildren(
645
+ inherited: Readonly<Record<string, FlagSchema>>,
646
+ local: Readonly<Record<string, FlagSchema>>,
647
+ ): Readonly<Record<string, FlagSchema>> {
648
+ const next: Record<string, FlagSchema> = { ...inherited };
649
+
650
+ for (const name of Object.keys(local)) {
651
+ delete next[name];
652
+ }
653
+
654
+ for (const [name, schema] of Object.entries(local)) {
655
+ if (schema.propagate) {
656
+ next[name] = schema;
657
+ }
658
+ }
659
+
660
+ return next;
661
+ }
662
+
663
+ function validateCommandFlagTree(
664
+ command: CommandSchema,
665
+ inheritedFlags: Readonly<Record<string, FlagSchema>> = {},
666
+ ): void {
667
+ validateLocalFlagCollisions(command.name, command.flags);
668
+
669
+ const visibleInherited: Record<string, FlagSchema> = { ...inheritedFlags };
670
+ for (const name of Object.keys(command.flags)) {
671
+ delete visibleInherited[name];
672
+ }
673
+ validateInheritedFlagCollisions(command.name, visibleInherited, command.flags);
674
+
675
+ const inheritedForChildren = buildInheritedFlagsForChildren(inheritedFlags, command.flags);
676
+ for (const child of command.commands) {
677
+ validateCommandFlagTree(child, inheritedForChildren);
678
+ }
679
+ }
680
+
496
681
  // --- Type-erased command interface (shared between schema and CLI layers)
497
682
 
498
683
  /**
@@ -506,11 +691,11 @@ function validateArgEntry(name: string, schema: ArgSchema, args: readonly Comman
506
691
  * schema (for name/alias matching and help) and the ability to delegate to
507
692
  * `runCommand()`. This interface captures exactly that contract.
508
693
  *
509
- * The `_execute` function closes over the original typed `CommandBuilder`,
694
+ * The `_execute` function closes over the original typed {@linkcode CommandBuilder},
510
695
  * preserving full type safety inside the closure while presenting a
511
696
  * uniform interface to the dispatcher.
512
697
  *
513
- * Defined here (rather than in the CLI layer) so both `CommandBuilder` and
698
+ * Defined here (rather than in the CLI layer) so both {@linkcode CommandBuilder} and
514
699
  * `CLIBuilder` can reference it without circular imports.
515
700
  *
516
701
  * @internal
@@ -528,10 +713,28 @@ interface ErasedCommand {
528
713
  * @internal
529
714
  */
530
715
  readonly subcommands: ReadonlyMap<string, ErasedCommand>;
716
+ /** Original command builder captured at the type-erasure boundary. */
717
+ readonly _command?: AnyCommandBuilder;
531
718
  /** Execute this command against argv. Closes over the typed CommandBuilder. */
532
719
  readonly _execute: (argv: readonly string[], options?: RunOptions) => Promise<RunResult>;
533
720
  }
534
721
 
722
+ /**
723
+ * Structural subset of {@linkcode CommandBuilder} consumed by the execution pipeline.
724
+ *
725
+ * Avoids generic type parameters so any `CommandBuilder<F, A, C>` satisfies
726
+ * this interface structurally — no variance constraints, no inference needed.
727
+ * Used by `runCommand()` and the shared executor to accept commands without
728
+ * requiring TypeScript to resolve {@linkcode CommandBuilder}'s full generic signature.
729
+ *
730
+ * @internal
731
+ */
732
+ interface RunnableCommand {
733
+ readonly schema: CommandSchema;
734
+ readonly handler: ErasedActionHandler | undefined;
735
+ readonly _executionSteps: readonly ExecutionStep[];
736
+ }
737
+
535
738
  // --- Type-erased builder alias (for heterogeneous subcommand storage)
536
739
 
537
740
  /**
@@ -605,8 +808,8 @@ class CommandBuilder<
605
808
  /** @internal Runtime schema descriptor. */
606
809
  readonly schema: CommandSchema;
607
810
 
608
- /** @internal The action handler, if registered. */
609
- readonly handler: ActionHandler<F, A, C> | undefined;
811
+ /** @internal The action handler, if registered (type-erased for covariance). */
812
+ readonly handler: ErasedActionHandler | undefined;
610
813
 
611
814
  /**
612
815
  * @internal Nested sub-command builders (type-erased for heterogeneous storage).
@@ -626,15 +829,16 @@ class CommandBuilder<
626
829
  */
627
830
  readonly _executionSteps: readonly ExecutionStep[];
628
831
 
629
- /**
630
- * @internal Type brands — exist only in the type system (`declare`
631
- * produces no runtime property). Used for type inference.
632
- */
832
+ /** @internal Phantom brand for accumulated flag builder types. No runtime value. */
633
833
  declare readonly _flags: F;
834
+ /** @internal Phantom brand for accumulated arg builder types. No runtime value. */
634
835
  declare readonly _args: A;
836
+ /** @internal Phantom brand for accumulated context type. No runtime value. */
635
837
  declare readonly _ctx: C;
636
838
 
637
839
  /**
840
+ * Create a command builder from a pre-built schema descriptor.
841
+ *
638
842
  * @param schema - Runtime command descriptor.
639
843
  * @param handler - Action handler, if registered.
640
844
  * @param subcommands - Nested sub-command builders (type-erased).
@@ -642,7 +846,7 @@ class CommandBuilder<
642
846
  */
643
847
  constructor(
644
848
  schema: CommandSchema,
645
- handler?: ActionHandler<F, A, C>,
849
+ handler?: ErasedActionHandler,
646
850
  subcommands?: readonly AnyCommandBuilder[],
647
851
  executionSteps?: readonly ExecutionStep[],
648
852
  ) {
@@ -661,7 +865,7 @@ class CommandBuilder<
661
865
  * resolved flag values. It returns a prompt schema for flags that need
662
866
  * interactive input based on the current state.
663
867
  *
664
- * For flags the resolver returns a `PromptConfig`, that config is used
868
+ * For flags the resolver returns a {@linkcode PromptConfig}, that config is used
665
869
  * instead of any per-flag `.prompt()` config. For flags returned as falsy
666
870
  * (or not mentioned), per-flag `.prompt()` configs are used as fallback.
667
871
  *
@@ -710,7 +914,7 @@ class CommandBuilder<
710
914
  * - return an object to merge additional properties into `ctx`
711
915
  *
712
916
  * Unlike middleware, derive cannot wrap downstream execution and does not
713
- * use `next()`. Use `middleware()` for timing, logging, retries, cleanup,
917
+ * use `next()`. Use {@linkcode middleware} for timing, logging, retries, cleanup,
714
918
  * or error-boundary patterns.
715
919
  *
716
920
  * Adding derive drops the current handler (like `.flag()`, `.arg()`, and
@@ -761,7 +965,7 @@ class CommandBuilder<
761
965
  * Register middleware to run before the action handler.
762
966
  *
763
967
  * Middleware executes in registration order. Each middleware receives
764
- * `{ args, flags, ctx, out, next }` and must call `next(additions)`
968
+ * `{ args, flags, ctx, out, meta, next }` and must call `next(additions)`
765
969
  * to continue the chain. Context additions are merged and become
766
970
  * typed downstream.
767
971
  *
@@ -771,7 +975,7 @@ class CommandBuilder<
771
975
  *
772
976
  * @example
773
977
  * ```ts
774
- * import { CLIError, command, middleware } from 'dreamcli';
978
+ * import { CLIError, command, middleware } from '@kjanat/dreamcli';
775
979
  *
776
980
  * interface User {
777
981
  * id: string;
@@ -810,7 +1014,8 @@ class CommandBuilder<
810
1014
  * });
811
1015
  * ```
812
1016
  *
813
- * @param m - {@link Middleware} instance created via `middleware()`.
1017
+ * @param m - {@link Middleware} instance created via {@linkcode middleware | middleware()}.
1018
+ * Middleware handlers receive `{ args, flags, ctx, out, meta, next }`.
814
1019
  * @returns The builder (for chaining).
815
1020
  */
816
1021
  middleware<Output extends Record<string, unknown>>(
@@ -979,8 +1184,8 @@ class CommandBuilder<
979
1184
  * bindings, and description. See {@link FlagBuilder} for available modifiers.
980
1185
  *
981
1186
  * @param name - Flag name (used as `--name` on CLI and `flags.*` in handler).
982
- * @param builder - Configured `FlagBuilder` from `flag.string()`, `flag.boolean()`,
983
- * `flag.number()`, `flag.enum()`, `flag.array()`, or `flag.custom()`.
1187
+ * @param builder - Configured {@linkcode FlagBuilder} from {@linkcode flag | flag.string()},
1188
+ * `flag.boolean()`, `flag.number()`, `flag.enum()`, `flag.array()`, or `flag.custom()`.
984
1189
  *
985
1190
  * @example
986
1191
  * ```ts
@@ -1014,9 +1219,18 @@ class CommandBuilder<
1014
1219
  name: N & Exclude<N, keyof F>,
1015
1220
  builder: B,
1016
1221
  ): CommandBuilder<F & Record<N, B>, A, C> {
1222
+ if (name in this.schema.flags) {
1223
+ throw new CLIError(`Command '${this.schema.name}' already defines flag --${name}`, {
1224
+ code: 'FLAG_NAME_COLLISION',
1225
+ details: { command: this.schema.name, flag: name, surface: name, surfaceKind: 'canonical' },
1226
+ });
1227
+ }
1228
+
1017
1229
  const nextFlags = { ...this.schema.flags, [name]: builder.schema };
1230
+ const nextSchema = { ...this.schema, flags: nextFlags, hasAction: false };
1231
+ validateCommandFlagTree(nextSchema);
1018
1232
  return new CommandBuilder(
1019
- { ...this.schema, flags: nextFlags, hasAction: false },
1233
+ nextSchema,
1020
1234
  // handler is intentionally dropped — adding a flag invalidates
1021
1235
  // the previous handler's type signature
1022
1236
  undefined,
@@ -1039,7 +1253,7 @@ class CommandBuilder<
1039
1253
  * description. See {@link ArgBuilder} for available modifiers.
1040
1254
  *
1041
1255
  * @param name - Positional arg name (used in help text and `args.*`).
1042
- * @param builder - Configured `ArgBuilder` from `arg.string()`, `arg.number()`,
1256
+ * @param builder - Configured {@linkcode ArgBuilder} from `arg.string()`, `arg.number()`,
1043
1257
  * or `arg.custom()`.
1044
1258
  *
1045
1259
  * @example
@@ -1113,11 +1327,13 @@ class CommandBuilder<
1113
1327
  A2 extends Record<string, ArgBuilder<ArgConfig>>,
1114
1328
  C2 extends Record<string, unknown>,
1115
1329
  >(sub: CommandBuilder<F2, A2, C2>): CommandBuilder<F, A, C> {
1330
+ const nextSchema = {
1331
+ ...this.schema,
1332
+ commands: [...this.schema.commands, sub.schema],
1333
+ };
1334
+ validateCommandFlagTree(nextSchema);
1116
1335
  return new CommandBuilder(
1117
- {
1118
- ...this.schema,
1119
- commands: [...this.schema.commands, sub.schema],
1120
- },
1336
+ nextSchema,
1121
1337
  this.handler,
1122
1338
  [...this._subcommands, eraseBuilder(sub)],
1123
1339
  this._executionSteps,
@@ -1129,7 +1345,7 @@ class CommandBuilder<
1129
1345
  /**
1130
1346
  * Register the action handler for this command.
1131
1347
  *
1132
- * The handler receives fully typed `{ args, flags, ctx, out }` derived
1348
+ * The handler receives fully typed `{ args, flags, ctx, out, meta }` derived
1133
1349
  * from the accumulated `.flag()`, `.arg()`, `.derive()`, and `.middleware()`
1134
1350
  * definitions.
1135
1351
  *
@@ -1139,38 +1355,43 @@ class CommandBuilder<
1139
1355
  * @param handler - Function receiving `ActionParams<F, A, C>`.
1140
1356
  *
1141
1357
  * @example
1358
+ * ```ts
1142
1359
  * // Minimal
1143
1360
  * command('greet')
1144
1361
  * .arg('name', arg.string())
1145
1362
  * .action(({ args, out }) => {
1146
1363
  * out.log(`Hello, ${args.name}!`);
1147
1364
  * });
1365
+ * ```
1148
1366
  *
1149
1367
  * @example
1150
- * // Full params — flags, args, context, output
1368
+ * ```ts
1369
+ * // Full params — flags, args, context, output, metadata
1151
1370
  * command('deploy')
1152
1371
  * .arg('target', arg.string().env('DEPLOY_TARGET'))
1153
1372
  * .flag('force', flag.boolean().alias('f'))
1154
1373
  * .flag('region', flag.enum(['us', 'eu', 'ap']).env('REGION'))
1155
1374
  * .middleware(auth)
1156
- * .action(async ({ args, flags, ctx, out }) => {
1375
+ * .action(async ({ args, flags, ctx, out, meta }) => {
1157
1376
  * args.target; // string
1158
1377
  * flags.force; // boolean
1159
1378
  * flags.region; // 'us' | 'eu' | 'ap' | undefined
1160
1379
  * ctx.user; // User (from auth middleware)
1380
+ * meta.command; // string
1161
1381
  *
1162
1382
  * const spinner = out.spinner('Deploying...');
1163
1383
  * await deploy(args.target, { force: flags.force });
1164
1384
  * spinner.stop();
1165
1385
  * out.log('Done');
1166
1386
  * });
1387
+ * ```
1167
1388
  *
1168
1389
  * @returns The builder (for chaining).
1169
1390
  */
1170
1391
  action(handler: ActionHandler<F, A, C>): CommandBuilder<F, A, C> {
1171
1392
  return new CommandBuilder(
1172
1393
  { ...this.schema, hasAction: true },
1173
- handler,
1394
+ handler as unknown as ErasedActionHandler,
1174
1395
  this._subcommands,
1175
1396
  this._executionSteps,
1176
1397
  );
@@ -1186,6 +1407,8 @@ class CommandBuilder<
1186
1407
  *
1187
1408
  * @example
1188
1409
  * ```ts
1410
+ * import { arg, command, flag } from '@kjanat/dreamcli';
1411
+ *
1189
1412
  * const greet = command('greet')
1190
1413
  * .arg('name', arg.string())
1191
1414
  * .flag('loud', flag.boolean())
@@ -1216,7 +1439,7 @@ function command(name: string): CommandBuilder {
1216
1439
  /**
1217
1440
  * Create a command builder intended for use as a command group.
1218
1441
  *
1219
- * Semantically identical to `command()` — a group is simply a command that
1442
+ * Semantically identical to {@linkcode command | command()} — a group is simply a command that
1220
1443
  * has subcommands registered via `.command()`. The separate factory
1221
1444
  * communicates intent: groups organise subcommands, leaf commands have actions.
1222
1445
  *
@@ -1252,6 +1475,7 @@ export type {
1252
1475
  CommandSchema,
1253
1476
  DeriveHandler,
1254
1477
  DeriveParams,
1478
+ ErasedActionHandler,
1255
1479
  ErasedCommand,
1256
1480
  ErasedDeriveHandler,
1257
1481
  ErasedInteractiveResolver,
@@ -1259,5 +1483,8 @@ export type {
1259
1483
  InteractiveResolver,
1260
1484
  InteractiveResult,
1261
1485
  Out,
1486
+ RunnableCommand,
1487
+ WidenContext,
1488
+ WidenDerivedContext,
1262
1489
  };
1263
1490
  export { CommandBuilder, command, group };