@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
@@ -0,0 +1,262 @@
1
+ /**
2
+ * Compile-time schema string parser.
3
+ *
4
+ * Parses a string literal like `"{ name: string; age: number }"` into its
5
+ * corresponding TypeScript type at compile time using template literal types
6
+ * and recursive conditional inference.
7
+ *
8
+ * The compile-time parser and the runtime parser in `runtime.ts` implement
9
+ * the same grammar — the type-level version produces TypeScript types while
10
+ * the runtime version produces an AST.
11
+ *
12
+ * @module dreamcli/core/schema-dsl/parse
13
+ */
14
+
15
+ // === Whitespace handling ===
16
+
17
+ /** Whitespace characters recognized by the parser. */
18
+ type WS = ' ' | '\n' | '\t' | '\r';
19
+
20
+ /** Strip leading whitespace. */
21
+ type TrimLeft<T extends string> = T extends `${WS}${infer R}` ? TrimLeft<R> : T;
22
+
23
+ /** Strip trailing whitespace. */
24
+ type TrimRight<T extends string> = T extends `${infer R}${WS}` ? TrimRight<R> : T;
25
+
26
+ /** Strip leading and trailing whitespace. */
27
+ type Trim<T extends string> = TrimLeft<TrimRight<T>>;
28
+
29
+ // === Character counting for bracket balancing ===
30
+
31
+ /**
32
+ * Single-pass brace depth tracker.
33
+ *
34
+ * Walks the string character by character, pushing to the depth tuple
35
+ * on `{` and popping on `}`. Returns the final depth tuple — an empty
36
+ * tuple means balanced. Returns `false` on underflow (more `}` than `{`).
37
+ *
38
+ * This replaces the Chars + Keep + length approach, which materialized
39
+ * the entire string as a character tuple. Single-pass is O(n) recursion
40
+ * depth instead of O(3n).
41
+ */
42
+ type TrackDepth<T extends string, D extends unknown[] = []> = T extends `${infer C}${infer R}`
43
+ ? C extends '{'
44
+ ? TrackDepth<R, [0, ...D]>
45
+ : C extends '}'
46
+ ? D extends [unknown, ...infer Rest]
47
+ ? TrackDepth<R, Rest>
48
+ : false
49
+ : TrackDepth<R, D>
50
+ : D;
51
+
52
+ /** True when braces are balanced (depth returns to zero without underflow). */
53
+ type Balanced<T extends string> = TrackDepth<T> extends [] ? true : false;
54
+
55
+ // === Balanced splitting ===
56
+
57
+ /**
58
+ * Naively split string T at every occurrence of delimiter D.
59
+ * Does not respect brace nesting — use {@link Rejoin} to rebalance.
60
+ */
61
+ type RawSplit<T extends string, D extends string> = T extends `${infer A}${D}${infer B}`
62
+ ? [A, ...RawSplit<B, D>]
63
+ : [T];
64
+
65
+ /**
66
+ * Walk a tuple of fragments, merging adjacent entries whose cumulative
67
+ * brace count is unbalanced. Delimiter D is reinserted when merging.
68
+ *
69
+ * This is the bracket-balancing trick that makes nested-object parsing
70
+ * practical: split greedily, then glue back together where braces don't
71
+ * match.
72
+ */
73
+ type Rejoin<T extends string[], D extends string> = T extends [
74
+ infer A extends string,
75
+ infer B extends string,
76
+ ...infer R extends string[],
77
+ ]
78
+ ? Balanced<A> extends true
79
+ ? [A, ...Rejoin<[B, ...R], D>]
80
+ : Rejoin<[`${A}${D}${B}`, ...R], D>
81
+ : T;
82
+
83
+ // === Filtering ===
84
+
85
+ /** Remove entries that are empty or whitespace-only after trimming. */
86
+ type NonEmpty<T extends string[]> = T extends [infer H extends string, ...infer R extends string[]]
87
+ ? Trim<H> extends ''
88
+ ? NonEmpty<R>
89
+ : [H, ...NonEmpty<R>]
90
+ : [];
91
+
92
+ // === Top-level pipe detection ===
93
+
94
+ /**
95
+ * True when the string contains `|` outside of `{}` nesting.
96
+ *
97
+ * Splits at `|`, rebalances with {@link Rejoin}, and checks whether
98
+ * two or more fragments remain. If `|` was only inside braces,
99
+ * rebalancing collapses them back to one fragment.
100
+ */
101
+ type HasTopLevelPipe<T extends string> =
102
+ Rejoin<RawSplit<T, '|'>, '|'> extends [string, string, ...string[]] ? true : false;
103
+
104
+ // === Flatten intersection into readable object type ===
105
+
106
+ /** Collapse an intersection of object types into a single flat object. */
107
+ type Prettify<T> = { [K in keyof T]: T[K] } & {};
108
+
109
+ // === Primitive mapping ===
110
+
111
+ /** Map a primitive type name to its TypeScript type. */
112
+ type ParsePrimitive<T extends string> = T extends 'string'
113
+ ? string
114
+ : T extends 'number'
115
+ ? number
116
+ : T extends 'integer'
117
+ ? number
118
+ : T extends 'boolean'
119
+ ? boolean
120
+ : T extends 'true'
121
+ ? true
122
+ : T extends 'false'
123
+ ? false
124
+ : T extends 'null'
125
+ ? null
126
+ : T extends 'undefined'
127
+ ? undefined
128
+ : T extends 'unknown'
129
+ ? unknown
130
+ : T extends 'never'
131
+ ? never
132
+ : never;
133
+
134
+ // === Union parsing ===
135
+
136
+ /** Parse each tuple entry as a value, producing a tuple of types. */
137
+ type ParseEach<T extends string[]> = T extends [infer H extends string, ...infer R extends string[]]
138
+ ? [ParseValue<H>, ...ParseEach<R>]
139
+ : [];
140
+
141
+ /** Collapse a tuple of types into a TypeScript union. */
142
+ type TupleToUnion<T extends unknown[]> = T extends [infer H, ...infer R]
143
+ ? H | TupleToUnion<R>
144
+ : never;
145
+
146
+ /** Split at top-level `|`, parse each branch, collapse to union. */
147
+ type ParseUnion<T extends string> = TupleToUnion<
148
+ ParseEach<NonEmpty<Rejoin<RawSplit<T, '|'>, '|'>>>
149
+ >;
150
+
151
+ // === Value parsing ===
152
+
153
+ /**
154
+ * Parse a value type: object, union, array, literal, ref, Record, or primitive.
155
+ *
156
+ * Precedence (highest to lowest):
157
+ * 1. Object — `{...}` wrapping
158
+ * 2. Union — top-level `|` (outside braces)
159
+ * 3. Array — trailing `[]` suffix
160
+ * 4. String literal — `'...'` (maps to literal string type)
161
+ * 5. Reference — `@name` (maps to `unknown` at type level; resolved at runtime)
162
+ * 6. Record — `Record<K, V>` (maps to `Record<string, V>`)
163
+ * 7. Primitive — identifier lookup
164
+ *
165
+ * Union is checked before array so `string | number[]` parses as
166
+ * `string | number[]`, not `(string | number)[]`.
167
+ */
168
+ type ParseValue<T extends string, V extends string = Trim<T>> = V extends `{${infer Content}}`
169
+ ? Prettify<ParseObject<Content>>
170
+ : HasTopLevelPipe<V> extends true
171
+ ? ParseUnion<V>
172
+ : V extends `${infer Inner}[]`
173
+ ? ParseValue<Inner>[]
174
+ : V extends `'${infer Literal}'`
175
+ ? Literal
176
+ : V extends `@${string}`
177
+ ? unknown
178
+ : V extends `Record<${string},${infer Val}>`
179
+ ? Record<string, ParseValue<Trim<Val>>>
180
+ : ParsePrimitive<V>;
181
+
182
+ // === Property parsing ===
183
+
184
+ /**
185
+ * Parse a single property string like `"name: string"` or `"age?: number"`.
186
+ *
187
+ * Matches the first `:` (leftmost), then checks whether the key ends
188
+ * with `?` to determine optionality. This avoids the trap of matching
189
+ * `?:` inside nested values.
190
+ */
191
+ type ParseProperty<T extends string> =
192
+ Trim<T> extends `${infer K}:${infer V}`
193
+ ? Trim<K> extends `${infer Key}?`
194
+ ? { [P in Trim<Key>]?: ParseValue<V> }
195
+ : { [P in Trim<K>]: ParseValue<V> }
196
+ : // biome-ignore lint/complexity/noBannedTypes: identity element for type-level intersection
197
+ {};
198
+
199
+ /** Recursively parse a tuple of property strings and intersect results. */
200
+ type ParseProperties<T extends string[]> = T extends [
201
+ infer H extends string,
202
+ ...infer R extends string[],
203
+ ]
204
+ ? ParseProperty<H> & ParseProperties<R>
205
+ : // biome-ignore lint/complexity/noBannedTypes: identity element for type-level intersection
206
+ {};
207
+
208
+ // === Object parsing ===
209
+
210
+ /**
211
+ * Split content by `;` with bracket balancing, filter empties,
212
+ * parse each property, and intersect into a single object type.
213
+ */
214
+ type ParseObject<T extends string> = Prettify<
215
+ ParseProperties<NonEmpty<Rejoin<RawSplit<T, ';'>, ';'>>>
216
+ >;
217
+
218
+ // === Entry point ===
219
+
220
+ /**
221
+ * Parse a schema string literal into its TypeScript type.
222
+ *
223
+ * Supports primitives (`string`, `number`, `boolean`, `true`, `false`,
224
+ * `null`, `undefined`, `unknown`, `never`), arrays (`T[]`), objects
225
+ * (`{ key: T; ... }`), optional properties (`key?: T`), unions
226
+ * (`T | U`), and arbitrary nesting.
227
+ *
228
+ * @example
229
+ * ```ts
230
+ * type User = Parse<'{ name: string; age: number; tags?: string[] }'>;
231
+ * // ^? { name: string; age: number; tags?: string[] | undefined }
232
+ *
233
+ * type Status = Parse<'string | true'>;
234
+ * // ^? string | true
235
+ * ```
236
+ */
237
+ type Parse<T extends string, V extends string = Trim<T>> = V extends `{${infer Content}}`
238
+ ? Prettify<ParseObject<Content>>
239
+ : ParseValue<V>;
240
+
241
+ export type {
242
+ Balanced,
243
+ HasTopLevelPipe,
244
+ NonEmpty,
245
+ Parse,
246
+ ParseEach,
247
+ ParseObject,
248
+ ParsePrimitive,
249
+ ParseProperties,
250
+ ParseProperty,
251
+ ParseUnion,
252
+ ParseValue,
253
+ Prettify,
254
+ RawSplit,
255
+ Rejoin,
256
+ TrackDepth,
257
+ Trim,
258
+ TrimLeft,
259
+ TrimRight,
260
+ TupleToUnion,
261
+ WS,
262
+ };