@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
@@ -2,7 +2,7 @@
2
2
  * Flag schema builder with full type inference.
3
3
  *
4
4
  * Each factory (`flag.string()`, `flag.boolean()`, etc.) returns an immutable
5
- * `FlagBuilder` whose generic parameter tracks the value type and presence
5
+ * {@linkcode FlagBuilder} whose generic parameter tracks the value type and presence
6
6
  * state. Chained modifiers (`.default()`, `.required()`, `.alias()`, …) return
7
7
  * new builders with updated type-level and runtime state.
8
8
  *
@@ -13,6 +13,9 @@ import type { PromptConfig } from './prompt.ts';
13
13
 
14
14
  // --- Type-level configuration (phantom state tracked through the chain)
15
15
 
16
+ /** All flag presence states as a runtime array. */
17
+ const FLAG_PRESENCES = ['optional', 'required', 'defaulted'] as const;
18
+
16
19
  /**
17
20
  * Presence describes whether a flag value is guaranteed to exist when the
18
21
  * action handler runs:
@@ -22,7 +25,7 @@ import type { PromptConfig } from './prompt.ts';
22
25
  * - `'required'` — must be supplied; error if missing
23
26
  * - `'defaulted'` — always present (falls back to default value)
24
27
  */
25
- type FlagPresence = 'optional' | 'required' | 'defaulted';
28
+ type FlagPresence = (typeof FLAG_PRESENCES)[number];
26
29
 
27
30
  /**
28
31
  * Fallback behavior when an optional flag resolves no value from any source.
@@ -50,7 +53,7 @@ interface FlagConfig {
50
53
  // --- Type-level helpers
51
54
 
52
55
  /**
53
- * Advanced type helper used by `FlagBuilder` modifiers to replace presence.
56
+ * Advanced type helper used by {@linkcode FlagBuilder} modifiers to replace presence.
54
57
  * Most consumers rely on inference and never reference this directly.
55
58
  */
56
59
  type WithPresence<C extends FlagConfig, P extends FlagPresence> = {
@@ -76,7 +79,7 @@ type ResolvedValue<C extends FlagConfig> = C['presence'] extends 'optional'
76
79
  : C['valueType'] | undefined
77
80
  : C['valueType'];
78
81
 
79
- /** Extract the resolved value type from a `FlagBuilder`. */
82
+ /** Extract the resolved value type from a {@linkcode FlagBuilder}. */
80
83
  type InferFlag<B> = B extends FlagBuilder<infer C extends FlagConfig> ? ResolvedValue<C> : never;
81
84
 
82
85
  /** Extract resolved value types from a record of builders. */
@@ -86,8 +89,11 @@ type InferFlags<T extends Record<string, FlagBuilder<FlagConfig>>> = {
86
89
 
87
90
  // --- Runtime schema data
88
91
 
92
+ /** All flag kind discriminators as a runtime array. */
93
+ const FLAG_KINDS = ['string', 'number', 'boolean', 'enum', 'array', 'custom'] as const;
94
+
89
95
  /** Discriminator for the kind of value a flag accepts. */
90
- type FlagKind = 'string' | 'number' | 'boolean' | 'enum' | 'array' | 'custom';
96
+ type FlagKind = (typeof FLAG_KINDS)[number];
91
97
 
92
98
  /**
93
99
  * Custom parse function for `flag.custom()`.
@@ -97,8 +103,16 @@ type FlagKind = 'string' | 'number' | 'boolean' | 'enum' | 'array' | 'custom';
97
103
  */
98
104
  type FlagParseFn<T> = (raw: unknown) => T;
99
105
 
106
+ /** Runtime descriptor for a flag alias. */
107
+ interface FlagAlias {
108
+ /** Alias name without `-` / `--` prefix. */
109
+ readonly name: string;
110
+ /** Whether the alias is parser-only and hidden from user-facing surfaces. */
111
+ readonly hidden: boolean;
112
+ }
113
+
100
114
  /**
101
- * The runtime descriptor stored inside every `FlagBuilder`. Consumers (parser,
115
+ * The runtime descriptor stored inside every {@linkcode FlagBuilder}. Consumers (parser,
102
116
  * help generator, resolution chain) read this to understand the flag's shape
103
117
  * without touching generics.
104
118
  */
@@ -109,8 +123,8 @@ interface FlagSchema {
109
123
  readonly presence: FlagPresence;
110
124
  /** Runtime default value (if any). */
111
125
  readonly defaultValue: unknown;
112
- /** Short/long aliases (e.g. `['f']` for `--force`). */
113
- readonly aliases: readonly string[];
126
+ /** Short/long aliases (e.g. `[{ name: 'f', hidden: false }]` for `--force`). */
127
+ readonly aliases: readonly FlagAlias[];
114
128
  /** Environment variable name for v0.2+ resolution. */
115
129
  readonly envVar: string | undefined;
116
130
  /** Dotted config path for v0.2+ resolution (e.g. `'deploy.region'`). */
@@ -148,6 +162,70 @@ interface FlagSchema {
148
162
  readonly propagate: boolean;
149
163
  }
150
164
 
165
+ /**
166
+ * Low-level overrides accepted by {@link createSchema}.
167
+ *
168
+ * `aliases` accepts both legacy string input and structured {@link FlagAlias}
169
+ * objects so tests and internal fixtures can be migrated incrementally.
170
+ */
171
+ type FlagSchemaOverrides = Omit<Partial<FlagSchema>, 'aliases'> & {
172
+ readonly aliases?: readonly (string | FlagAlias)[];
173
+ };
174
+
175
+ /**
176
+ * Normalise an alias input into a full {@link FlagAlias} object.
177
+ *
178
+ * @param alias - Raw alias name or structured alias object.
179
+ * @returns Normalised alias record.
180
+ */
181
+ function normalizeFlagAlias(alias: string | FlagAlias): FlagAlias {
182
+ if (typeof alias === 'string') {
183
+ return { name: alias, hidden: false };
184
+ }
185
+
186
+ return {
187
+ name: alias.name,
188
+ hidden: alias.hidden,
189
+ };
190
+ }
191
+
192
+ /**
193
+ * Normalise alias input into immutable alias records.
194
+ *
195
+ * @param aliases - Alias input values.
196
+ * @returns Normalised alias objects.
197
+ */
198
+ function normalizeFlagAliases(aliases: readonly (string | FlagAlias)[]): readonly FlagAlias[] {
199
+ return aliases.map(normalizeFlagAlias);
200
+ }
201
+
202
+ /**
203
+ * List alias names for a flag schema.
204
+ *
205
+ * @param schema - Flag schema whose aliases should be listed.
206
+ * @param options - Visibility and length filtering.
207
+ * @returns Alias names in registration order.
208
+ */
209
+ function getFlagAliasNames(
210
+ schema: FlagSchema,
211
+ options?: {
212
+ readonly includeHidden?: boolean;
213
+ readonly kind?: 'all' | 'short' | 'long';
214
+ },
215
+ ): readonly string[] {
216
+ const includeHidden = options?.includeHidden ?? false;
217
+ const kind = options?.kind ?? 'all';
218
+
219
+ return schema.aliases
220
+ .filter((alias) => includeHidden || !alias.hidden)
221
+ .filter((alias) => {
222
+ if (kind === 'short') return alias.name.length === 1;
223
+ if (kind === 'long') return alias.name.length > 1;
224
+ return true;
225
+ })
226
+ .map((alias) => alias.name);
227
+ }
228
+
151
229
  /**
152
230
  * Create a raw {@link FlagSchema} object with sensible defaults.
153
231
  *
@@ -172,12 +250,15 @@ interface FlagSchema {
172
250
  * });
173
251
  * ```
174
252
  */
175
- function createSchema(kind: FlagKind, overrides?: Partial<FlagSchema>): FlagSchema {
253
+ function createSchema(kind: FlagKind, overrides?: FlagSchemaOverrides): FlagSchema {
254
+ const aliases =
255
+ overrides?.aliases !== undefined ? normalizeFlagAliases(overrides.aliases) : ([] as const);
256
+ const { aliases: _ignoredAliases, ...rest } = overrides ?? {};
257
+
176
258
  return {
177
259
  kind,
178
260
  presence: 'optional',
179
261
  defaultValue: undefined,
180
- aliases: [],
181
262
  envVar: undefined,
182
263
  configPath: undefined,
183
264
  description: undefined,
@@ -187,7 +268,8 @@ function createSchema(kind: FlagKind, overrides?: Partial<FlagSchema>): FlagSche
187
268
  parseFn: undefined,
188
269
  deprecated: undefined,
189
270
  propagate: false,
190
- ...overrides,
271
+ ...rest,
272
+ aliases,
191
273
  };
192
274
  }
193
275
 
@@ -215,11 +297,13 @@ class FlagBuilder<C extends FlagConfig> {
215
297
 
216
298
  /**
217
299
  * @internal Type brand — exists only in the type system (`declare`
218
- * produces no runtime property). Used by `InferFlag` / `InferFlags`.
300
+ * produces no runtime property). Used by {@linkcode InferFlag} / {@linkcode InferFlags}.
219
301
  */
220
302
  declare readonly _config: C;
221
303
 
222
304
  /**
305
+ * Create a flag builder from a pre-built schema descriptor.
306
+ *
223
307
  * @param schema - Runtime descriptor seeding this builder's state.
224
308
  */
225
309
  constructor(schema: FlagSchema) {
@@ -284,6 +368,8 @@ class FlagBuilder<C extends FlagConfig> {
284
368
  * alternative long name).
285
369
  *
286
370
  * @param name - Single-char short alias or alternative long name.
371
+ * @param options - Optional alias metadata. Hidden aliases remain parseable
372
+ * but are omitted from help, completions, and suggestions.
287
373
  * @returns The builder (for chaining).
288
374
  *
289
375
  * @example
@@ -294,10 +380,16 @@ class FlagBuilder<C extends FlagConfig> {
294
380
  * // $ mycli build --verbose → verbose = true
295
381
  * ```
296
382
  */
297
- alias(name: string): FlagBuilder<C> {
383
+ alias(name: string, options?: { hidden?: boolean }): FlagBuilder<C> {
298
384
  return new FlagBuilder({
299
385
  ...this.schema,
300
- aliases: [...this.schema.aliases, name],
386
+ aliases: [
387
+ ...this.schema.aliases,
388
+ {
389
+ name,
390
+ hidden: options?.hidden ?? false,
391
+ },
392
+ ],
301
393
  });
302
394
  }
303
395
 
@@ -636,16 +728,29 @@ export type {
636
728
  SelectChoice,
637
729
  SelectPromptConfig,
638
730
  } from './prompt.ts';
731
+ export { PROMPT_KINDS } from './prompt.ts';
639
732
  export type {
733
+ FlagAlias,
640
734
  FlagConfig,
641
735
  FlagFactory,
642
736
  FlagKind,
643
737
  FlagParseFn,
644
738
  FlagPresence,
645
739
  FlagSchema,
740
+ FlagSchemaOverrides,
646
741
  InferFlag,
647
742
  InferFlags,
743
+ OptionalFallback,
648
744
  ResolvedValue,
649
745
  WithPresence,
650
746
  };
651
- export { createSchema, FlagBuilder, flag };
747
+ export {
748
+ createSchema,
749
+ FLAG_KINDS,
750
+ FLAG_PRESENCES,
751
+ FlagBuilder,
752
+ flag,
753
+ getFlagAliasNames,
754
+ normalizeFlagAlias,
755
+ normalizeFlagAliases,
756
+ };
@@ -29,7 +29,7 @@ export type {
29
29
  WithArgPresence,
30
30
  WithVariadic,
31
31
  } from './arg.ts';
32
- export { ArgBuilder, arg, createArgSchema } from './arg.ts';
32
+ export { ARG_KINDS, ARG_PRESENCES, ArgBuilder, arg, createArgSchema } from './arg.ts';
33
33
  export type {
34
34
  ActionHandler,
35
35
  ActionParams,
@@ -52,12 +52,14 @@ export type {
52
52
  export { CommandBuilder, command, group } from './command.ts';
53
53
  export type {
54
54
  ConfirmPromptConfig,
55
+ FlagAlias,
55
56
  FlagConfig,
56
57
  FlagFactory,
57
58
  FlagKind,
58
59
  FlagParseFn,
59
60
  FlagPresence,
60
61
  FlagSchema,
62
+ FlagSchemaOverrides,
61
63
  InferFlag,
62
64
  InferFlags,
63
65
  InputPromptConfig,
@@ -71,7 +73,14 @@ export type {
71
73
  SelectPromptConfig,
72
74
  WithPresence,
73
75
  } from './flag.ts';
74
- export { createSchema, FlagBuilder, flag } from './flag.ts';
76
+ export {
77
+ createSchema,
78
+ FLAG_KINDS,
79
+ FLAG_PRESENCES,
80
+ FlagBuilder,
81
+ flag,
82
+ PROMPT_KINDS,
83
+ } from './flag.ts';
75
84
  export type {
76
85
  ErasedMiddlewareHandler,
77
86
  Middleware,
@@ -6,7 +6,7 @@
6
6
  * - Short-circuit by throwing `CLIError` (or not calling `next`)
7
7
  * - Wrap downstream execution (timing, logging) by awaiting `next()`
8
8
  *
9
- * The `Middleware<Output>` type uses a phantom generic to track what
9
+ * The {@linkcode Middleware} type uses a phantom generic to track what
10
10
  * context properties this middleware adds. At runtime, middleware is
11
11
  * type-erased — the phantom type is only used for compile-time inference
12
12
  * when `.middleware()` is chained on `CommandBuilder`.
@@ -52,7 +52,7 @@ interface MiddlewareParams {
52
52
  * Type-erased middleware handler stored on `CommandSchema`.
53
53
  *
54
54
  * At runtime, all middleware handlers have this signature. The phantom
55
- * `Output` type on `Middleware<O>` is erased.
55
+ * `Output` type on {@linkcode Middleware} is erased.
56
56
  *
57
57
  * @internal
58
58
  */
@@ -62,7 +62,7 @@ type ErasedMiddlewareHandler = (params: MiddlewareParams) => void | Promise<void
62
62
  * Middleware handler function with typed `next()` parameter.
63
63
  *
64
64
  * The `Output` generic constrains what properties must be passed to
65
- * `next()`, ensuring type-safe context additions at the call site.
65
+ * {@linkcode MiddlewareParams.next | next()}, ensuring type-safe context additions at the call site.
66
66
  */
67
67
  type MiddlewareHandler<Output extends Record<string, unknown>> = (params: {
68
68
  readonly args: Readonly<Record<string, unknown>>;
@@ -91,7 +91,7 @@ interface MiddlewareImpl {
91
91
  * compile time. The `_output` brand is phantom — it exists only in the
92
92
  * type system for inference, not at runtime.
93
93
  *
94
- * Created via the `middleware()` factory. Attached to commands via
94
+ * Created via the {@linkcode middleware} factory. Attached to commands via
95
95
  * `CommandBuilder.middleware()`.
96
96
  *
97
97
  * @example
@@ -118,10 +118,10 @@ type Middleware<Output extends Record<string, unknown>> = MiddlewareImpl & {
118
118
  * Middleware runs before the action handler and can add typed context,
119
119
  * short-circuit execution, or wrap downstream processing.
120
120
  *
121
- * @param handler - Function receiving `{ args, flags, ctx, out, next }`.
121
+ * @param handler - Function receiving `{ args, flags, ctx, out, meta, next }`.
122
122
  * Call `next(additions)` to continue the chain with added context.
123
123
  * Omitting the `next()` call short-circuits (e.g., for auth guards).
124
- * @returns Middleware to attach via `CommandBuilder.middleware()`.
124
+ * @returns {@linkcode Middleware} to attach via `CommandBuilder.middleware()`.
125
125
  *
126
126
  * @example
127
127
  * ```ts
@@ -11,6 +11,9 @@
11
11
 
12
12
  // --- Prompt kind discriminator
13
13
 
14
+ /** All prompt kind discriminators as a runtime array. */
15
+ const PROMPT_KINDS = ['confirm', 'input', 'select', 'multiselect'] as const;
16
+
14
17
  /**
15
18
  * The kind of interactive prompt to present.
16
19
  *
@@ -19,7 +22,7 @@
19
22
  * - `'select'` — single selection from a list
20
23
  * - `'multiselect'` — multiple selections from a list
21
24
  */
22
- type PromptKind = 'confirm' | 'input' | 'select' | 'multiselect';
25
+ type PromptKind = (typeof PROMPT_KINDS)[number];
23
26
 
24
27
  // --- Per-kind prompt configuration (discriminated union)
25
28
 
@@ -31,11 +34,13 @@ interface PromptConfigBase {
31
34
 
32
35
  /** Yes/no confirmation prompt — maps to `boolean` flags. Part of {@link PromptConfig}. */
33
36
  interface ConfirmPromptConfig extends PromptConfigBase {
37
+ /** Discriminator identifying this as a yes/no confirmation prompt. */
34
38
  readonly kind: 'confirm';
35
39
  }
36
40
 
37
41
  /** Free-text input prompt — maps to `string` and `number` flags. Part of {@link PromptConfig}. */
38
42
  interface InputPromptConfig extends PromptConfigBase {
43
+ /** Discriminator identifying this as a free-text input prompt. */
39
44
  readonly kind: 'input';
40
45
  /** Placeholder text shown before user types (informational only). */
41
46
  readonly placeholder?: string;
@@ -48,6 +53,7 @@ interface InputPromptConfig extends PromptConfigBase {
48
53
 
49
54
  /** Single-selection prompt — maps to `enum` flags or any flag with {@link SelectChoice choices}. Part of {@link PromptConfig}. */
50
55
  interface SelectPromptConfig extends PromptConfigBase {
56
+ /** Discriminator identifying this as a single-selection prompt. */
51
57
  readonly kind: 'select';
52
58
  /**
53
59
  * Available choices. When omitted for `enum` flags, the enum values
@@ -61,6 +67,7 @@ interface SelectPromptConfig extends PromptConfigBase {
61
67
  * Returns an array of selected {@link SelectChoice} values. Part of {@link PromptConfig}.
62
68
  */
63
69
  interface MultiselectPromptConfig extends PromptConfigBase {
70
+ /** Discriminator identifying this as a multi-selection prompt. */
64
71
  readonly kind: 'multiselect';
65
72
  /**
66
73
  * Available choices. When omitted for `array` flags with enum elements,
@@ -146,3 +153,4 @@ export type {
146
153
  SelectChoice,
147
154
  SelectPromptConfig,
148
155
  };
156
+ export { PROMPT_KINDS };
@@ -17,13 +17,13 @@ import type { ActivityEvent } from './activity.ts';
17
17
  import type { CommandMeta, CommandSchema, Out } from './command.ts';
18
18
 
19
19
  /**
20
- * Options accepted by `commandBuilder.run()` and `runCommand()`.
20
+ * Options accepted by `runCommand()` and internal command execution paths.
21
21
  *
22
22
  * Every field is optional — sensible defaults are applied. This is the
23
- * primary execution seam: inject env, config, prompt I/O, and dispatch-layer
24
- * metadata without touching process state.
23
+ * primary process-free execution seam: inject env, config, prompt I/O, and
24
+ * dispatch-layer metadata without touching process state.
25
25
  */
26
- interface RunOptions {
26
+ export interface RunOptions {
27
27
  /**
28
28
  * Environment variables for flag resolution.
29
29
  *
@@ -82,8 +82,8 @@ interface RunOptions {
82
82
  * Enable JSON output mode.
83
83
  *
84
84
  * When `true`, `log` and `info` messages are redirected to stderr
85
- * so that stdout is reserved exclusively for structured `json()` output.
86
- * Errors are also rendered as JSON to stderr.
85
+ * so that stdout is reserved exclusively for structured {@linkcode Out.json | json()} output.
86
+ * Framework-rendered errors are emitted as structured JSON to stdout.
87
87
  *
88
88
  * @defaultValue `false`
89
89
  */
@@ -92,7 +92,7 @@ interface RunOptions {
92
92
  /**
93
93
  * Whether stdout is connected to a TTY.
94
94
  *
95
- * Handlers can check `out.isTTY` to decide whether to emit decorative
95
+ * Handlers can check {@linkcode Out.isTTY | out.isTTY} to decide whether to emit decorative
96
96
  * output (spinners, progress bars, ANSI codes). Defaults to `false`
97
97
  * (safe default for tests — non-TTY until proven otherwise).
98
98
  *
@@ -103,7 +103,7 @@ interface RunOptions {
103
103
  /**
104
104
  * Output channel override used by live CLI execution.
105
105
  *
106
- * @internal — `run()` passes a real output channel so activity renders to
106
+ * @internal — `CLIBuilder.run()` passes a real output channel so activity renders to
107
107
  * the terminal instead of being captured.
108
108
  */
109
109
  readonly out?: Out;
@@ -112,7 +112,7 @@ interface RunOptions {
112
112
  * Capture buffers override paired with `out`.
113
113
  *
114
114
  * @internal — when omitted, `runCommand()` creates empty buffers for the
115
- * returned `RunResult` while writing directly to the provided `out`.
115
+ * returned {@linkcode RunResult} while writing directly to the provided `out`.
116
116
  */
117
117
  readonly captured?: CapturedOutput;
118
118
 
@@ -153,12 +153,22 @@ interface RunOptions {
153
153
  }
154
154
 
155
155
  /**
156
- * Structured result from running a command.
156
+ * Structured result from {@linkcode runCommand}.
157
157
  *
158
- * Contains the exit code, captured stdout/stderr output, and an `error`
159
- * field that is `undefined` on success and populated on failure.
158
+ * Contains the exit code, captured stdout/stderr output, recorded
159
+ * {@linkcode ActivityEvent | activity events}, and an `error` field
160
+ * that is `undefined` on success and a {@linkcode CLIError} on failure.
161
+ *
162
+ * @example
163
+ * ```ts
164
+ * const result = await runCommand(greetCmd, ['World']);
165
+ *
166
+ * expect(result.exitCode).toBe(0);
167
+ * expect(result.stdout).toContain('Hello, World!');
168
+ * expect(result.error).toBeUndefined();
169
+ * ```
160
170
  */
161
- interface RunResult {
171
+ export interface RunResult {
162
172
  /** Process exit code. 0 = success. */
163
173
  readonly exitCode: number;
164
174
 
@@ -172,16 +182,14 @@ interface RunResult {
172
182
  * Captured spinner and progress lifecycle events.
173
183
  *
174
184
  * Recorded separately from stdout/stderr — handlers that call
175
- * `out.spinner()` or `out.progress()` produce events here, enabling
185
+ * {@linkcode Out.spinner | out.spinner()} or {@linkcode Out.progress | out.progress()} produce events here, enabling
176
186
  * targeted assertions on activity lifecycle without parsing text.
177
187
  */
178
188
  readonly activity: readonly ActivityEvent[];
179
189
 
180
190
  /**
181
191
  * The error that caused a non-zero exit, or `undefined` on success.
182
- * `CLIError` instances are preserved; unknown errors are wrapped.
192
+ * {@linkcode CLIError} instances are preserved; unknown errors are wrapped.
183
193
  */
184
194
  readonly error: CLIError | undefined;
185
195
  }
186
-
187
- export type { RunOptions, RunResult };
@@ -0,0 +1,109 @@
1
+ /**
2
+ * Schema DSL — single-source schema definitions with compile-time types
3
+ * and runtime AST.
4
+ *
5
+ * Define a schema once as a string literal. At compile time, the string is
6
+ * parsed into a TypeScript type via {@link Parse}. At runtime, the same
7
+ * string is parsed into an AST ({@link SchemaNode}) for validation,
8
+ * JSON Schema generation, and introspection.
9
+ *
10
+ * ```ts
11
+ * const user = schema('{ name: string; age: number; tags?: string[] }');
12
+ *
13
+ * // Compile-time: inferred as { name: string; age: number; tags?: string[] }
14
+ * const data = user.parse(jsonInput);
15
+ * data.name; // string
16
+ * data.age; // number
17
+ * ```
18
+ *
19
+ * @module dreamcli/core/schema-dsl
20
+ */
21
+
22
+ import type { Parse } from './parse.ts';
23
+ import type { SchemaNode } from './runtime.ts';
24
+ import { parseSchema, validateNode } from './runtime.ts';
25
+
26
+ // === Schema definition ===
27
+
28
+ /** The result of calling {@link schema}. Bundles source, AST, guard, and parse. */
29
+ interface SchemaDefinition<T extends string> {
30
+ /** The original source string. */
31
+ readonly source: T;
32
+ /** Runtime AST parsed from the source. */
33
+ readonly ast: SchemaNode;
34
+ /**
35
+ * Type guard — returns `true` if `input` matches the schema.
36
+ * Narrows the type to `Parse<T>` in the true branch.
37
+ */
38
+ guard(input: unknown): input is Parse<T>;
39
+ /**
40
+ * Parse and validate — returns the narrowed value or throws.
41
+ * @throws {TypeError} if the input does not match the schema.
42
+ */
43
+ parse(input: unknown): Parse<T>;
44
+ }
45
+
46
+ /**
47
+ * Define a schema from a string literal.
48
+ *
49
+ * @param source - Schema string (e.g. `"{ name: string; age: number }"`).
50
+ * @returns A {@link SchemaDefinition} with compile-time types and runtime validation.
51
+ *
52
+ * @example
53
+ * ```ts
54
+ * const user = schema('{ name: string; age: number; admin?: boolean }');
55
+ *
56
+ * // Type guard
57
+ * if (user.guard(input)) {
58
+ * input.name; // string
59
+ * }
60
+ *
61
+ * // Parse or throw
62
+ * const data = user.parse(input);
63
+ * data.age; // number
64
+ * ```
65
+ */
66
+ function schema<T extends string>(source: T): SchemaDefinition<T> {
67
+ const ast = parseSchema(source);
68
+
69
+ function guard(input: unknown): input is Parse<T> {
70
+ return validateNode(ast, input);
71
+ }
72
+
73
+ function parse(input: unknown): Parse<T> {
74
+ if (!guard(input)) {
75
+ throw new TypeError(`Value does not match schema: ${source}`);
76
+ }
77
+ return input;
78
+ }
79
+
80
+ return { source, ast, guard, parse };
81
+ }
82
+
83
+ // === Re-exports ===
84
+
85
+ export type { Parse } from './parse.ts';
86
+ export type {
87
+ ArrayNode,
88
+ BooleanNode,
89
+ IntegerNode,
90
+ LiteralFalseNode,
91
+ LiteralNullNode,
92
+ LiteralStringNode,
93
+ LiteralTrueNode,
94
+ LiteralUndefinedNode,
95
+ NeverNode,
96
+ NumberNode,
97
+ ObjectNode,
98
+ PropertyNode,
99
+ RecordNode,
100
+ RefNode,
101
+ SchemaNode,
102
+ StringNode,
103
+ UnionNode,
104
+ UnknownNode,
105
+ } from './runtime.ts';
106
+ export { parseSchema, validateNode } from './runtime.ts';
107
+ export { nodeToJsonSchema } from './to-json-schema.ts';
108
+ export type { SchemaDefinition };
109
+ export { schema };