@kjanat/dreamcli 1.0.0 → 2.0.0

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 +45 -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,338 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://cdn.jsdelivr.net/npm/@kjanat/dreamcli/schema",
4
+ "title": "@kjanat/dreamcli definition schema",
5
+ "description": "Runtime descriptor for the CLI program.\n\nStores the program name, version, description, and registered commands.\\\nBuilt incrementally by CLIBuilder.",
6
+ "type": "object",
7
+ "additionalProperties": false,
8
+ "properties": {
9
+ "$schema": {
10
+ "const": "https://cdn.jsdelivr.net/npm/@kjanat/dreamcli/schema"
11
+ },
12
+ "name": {
13
+ "type": "string",
14
+ "description": "Program name (used in help text, usage lines, and completion scripts)."
15
+ },
16
+ "version": {
17
+ "type": "string",
18
+ "description": "Program version (shown by `--version`)."
19
+ },
20
+ "description": {
21
+ "type": "string",
22
+ "description": "Program description (shown in root help)."
23
+ },
24
+ "defaultCommand": {
25
+ "type": "string",
26
+ "description": "Default command dispatched when no subcommand matches.\n\nWhen set, the CLI root behaves like a hybrid command group: subcommands\ndispatch by name as usual, but empty argv or flags-only argv falls\nthrough to this command instead of showing root help.\n\nSet via the .default() builder method."
27
+ },
28
+ "commands": {
29
+ "type": "array",
30
+ "items": {
31
+ "$ref": "#/$defs/command"
32
+ },
33
+ "description": "Registered commands (type-erased for heterogeneous storage)."
34
+ }
35
+ },
36
+ "required": [
37
+ "$schema",
38
+ "name",
39
+ "commands"
40
+ ],
41
+ "$defs": {
42
+ "command": {
43
+ "type": "object",
44
+ "additionalProperties": false,
45
+ "properties": {
46
+ "name": {
47
+ "type": "string",
48
+ "description": "The command name (used for dispatch, e.g. `'deploy'`)."
49
+ },
50
+ "description": {
51
+ "type": "string",
52
+ "description": "Human-readable description for help text."
53
+ },
54
+ "aliases": {
55
+ "type": "array",
56
+ "items": {
57
+ "type": "string"
58
+ },
59
+ "description": "Alternative names for this command."
60
+ },
61
+ "hidden": {
62
+ "const": true,
63
+ "description": "Whether this command is hidden from help listings."
64
+ },
65
+ "examples": {
66
+ "type": "array",
67
+ "items": {
68
+ "$ref": "#/$defs/example"
69
+ },
70
+ "description": "Usage examples for help text."
71
+ },
72
+ "flags": {
73
+ "type": "object",
74
+ "additionalProperties": {
75
+ "$ref": "#/$defs/flag"
76
+ },
77
+ "description": "Named flag schemas, keyed by flag name."
78
+ },
79
+ "args": {
80
+ "type": "array",
81
+ "items": {
82
+ "$ref": "#/$defs/arg"
83
+ },
84
+ "description": "Ordered positional arg entries (name + schema)."
85
+ },
86
+ "commands": {
87
+ "type": "array",
88
+ "items": {
89
+ "$ref": "#/$defs/command"
90
+ },
91
+ "description": "Nested subcommand schemas (for help rendering and completion).\n\nPure data — no execution closures. Populated by `.command()` on\n`CommandBuilder`. Empty for leaf commands."
92
+ }
93
+ },
94
+ "required": [
95
+ "name",
96
+ "flags",
97
+ "args",
98
+ "commands"
99
+ ],
100
+ "description": "Runtime descriptor produced by CommandBuilder.\n\nConsumers (parser, help generator, CLI dispatcher) read this to\nunderstand the command's shape — flags, args, aliases, subcommands,\nmiddleware, and interactive resolver."
101
+ },
102
+ "flag": {
103
+ "type": "object",
104
+ "additionalProperties": false,
105
+ "properties": {
106
+ "kind": {
107
+ "enum": [
108
+ "string",
109
+ "number",
110
+ "boolean",
111
+ "enum",
112
+ "array",
113
+ "custom"
114
+ ],
115
+ "description": "What kind of value this flag accepts."
116
+ },
117
+ "presence": {
118
+ "enum": [
119
+ "optional",
120
+ "required",
121
+ "defaulted"
122
+ ],
123
+ "description": "Presence describes whether a flag value is guaranteed to exist when the\naction handler runs:\n\n- `'optional'` — not required; unresolved value follows the kind-specific\n optional fallback (`undefined` for most flags, `[]` for arrays)\n- `'required'` — must be supplied; error if missing\n- `'defaulted'` — always present (falls back to default value)"
124
+ },
125
+ "defaultValue": {
126
+ "description": "Runtime default value (if any)."
127
+ },
128
+ "aliases": {
129
+ "type": "array",
130
+ "items": {
131
+ "type": "string"
132
+ },
133
+ "description": "Short/long aliases (e.g. `[{ name: 'f', hidden: false }]` for `--force`)."
134
+ },
135
+ "envVar": {
136
+ "type": "string",
137
+ "description": "Environment variable name for v0.2+ resolution."
138
+ },
139
+ "configPath": {
140
+ "type": "string",
141
+ "description": "Dotted config path for v0.2+ resolution (e.g. `'deploy.region'`)."
142
+ },
143
+ "description": {
144
+ "type": "string",
145
+ "description": "Human-readable description for help text."
146
+ },
147
+ "enumValues": {
148
+ "type": "array",
149
+ "items": {
150
+ "type": "string"
151
+ },
152
+ "description": "Allowed literal values when `kind === 'enum'`."
153
+ },
154
+ "elementSchema": {
155
+ "$ref": "#/$defs/flag",
156
+ "description": "Element schema when `kind === 'array'`."
157
+ },
158
+ "prompt": {
159
+ "$ref": "#/$defs/prompt",
160
+ "description": "Interactive prompt configuration for v0.3+ resolution."
161
+ },
162
+ "deprecated": {
163
+ "oneOf": [
164
+ {
165
+ "type": "string"
166
+ },
167
+ {
168
+ "const": true
169
+ }
170
+ ],
171
+ "description": "Deprecation marker.\n\n- `undefined` — not deprecated (default)\n- `true` — deprecated with no migration message\n- `string` — deprecated with a reason/migration message\n\nWhen a deprecated flag is used, a warning is emitted to stderr.\nHelp text shows `[deprecated]` or `[deprecated: <reason>]`."
172
+ },
173
+ "propagate": {
174
+ "const": true,
175
+ "description": "Whether this flag propagates to subcommands in nested command trees.\n\nWhen `true`, the flag is automatically available to all descendant\ncommands. A child command that defines a flag with the same name\nshadows the propagated parent flag."
176
+ }
177
+ },
178
+ "required": [
179
+ "kind",
180
+ "presence"
181
+ ],
182
+ "description": "The runtime descriptor stored inside every FlagBuilder. Consumers (parser,\nhelp generator, resolution chain) read this to understand the flag's shape\nwithout touching generics."
183
+ },
184
+ "arg": {
185
+ "type": "object",
186
+ "additionalProperties": false,
187
+ "properties": {
188
+ "name": {
189
+ "type": "string",
190
+ "description": "A named positional argument entry in the command schema.\n\nPairs a user-facing arg name with its ArgSchema descriptor.\nThe array ordering in CommandSchema.args determines CLI position."
191
+ },
192
+ "kind": {
193
+ "enum": [
194
+ "string",
195
+ "number",
196
+ "enum",
197
+ "custom"
198
+ ],
199
+ "description": "What kind of value this arg accepts."
200
+ },
201
+ "presence": {
202
+ "enum": [
203
+ "required",
204
+ "optional",
205
+ "defaulted"
206
+ ],
207
+ "description": "Presence describes whether a positional arg is guaranteed to exist when the\naction handler runs:\n\n- `'required'` — must be supplied; error if missing (default)\n- `'optional'` — may be `undefined` if not supplied\n- `'defaulted'` — always present (falls back to default value)"
208
+ },
209
+ "variadic": {
210
+ "const": true,
211
+ "description": "Whether this arg consumes all remaining positionals."
212
+ },
213
+ "stdinMode": {
214
+ "const": true,
215
+ "description": "Whether this arg may read from stdin during resolution."
216
+ },
217
+ "defaultValue": {
218
+ "description": "Runtime default value (if any)."
219
+ },
220
+ "description": {
221
+ "type": "string",
222
+ "description": "Human-readable description for help text."
223
+ },
224
+ "envVar": {
225
+ "type": "string",
226
+ "description": "Environment variable name for env resolution.\n\nWhen set and the CLI value is absent, the resolver reads this env var\nand coerces the string to the arg's declared kind."
227
+ },
228
+ "enumValues": {
229
+ "type": "array",
230
+ "items": {
231
+ "type": "string"
232
+ },
233
+ "description": "Allowed literal values when `kind === 'enum'`."
234
+ },
235
+ "deprecated": {
236
+ "oneOf": [
237
+ {
238
+ "type": "string"
239
+ },
240
+ {
241
+ "const": true
242
+ }
243
+ ],
244
+ "description": "Deprecation marker.\n\n- `undefined` — not deprecated (default)\n- `true` — deprecated with no migration message\n- `string` — deprecated with a reason/migration message\n\nWhen a deprecated arg is used, a warning is emitted to stderr.\nHelp text shows `[deprecated]` or `[deprecated: <reason>]`."
245
+ }
246
+ },
247
+ "required": [
248
+ "name",
249
+ "kind",
250
+ "presence"
251
+ ],
252
+ "description": "The runtime descriptor stored inside every ArgBuilder. Consumers (parser,\nhelp generator) read this to understand the arg's shape without touching\ngenerics."
253
+ },
254
+ "prompt": {
255
+ "type": "object",
256
+ "additionalProperties": false,
257
+ "properties": {
258
+ "kind": {
259
+ "enum": [
260
+ "confirm",
261
+ "input",
262
+ "select",
263
+ "multiselect"
264
+ ],
265
+ "description": "The kind of interactive prompt to present.\n\n- `'confirm'` — yes/no boolean question\n- `'input'` — free-text string input\n- `'select'` — single selection from a list\n- `'multiselect'` — multiple selections from a list"
266
+ },
267
+ "message": {
268
+ "type": "string",
269
+ "description": "The question displayed to the user."
270
+ },
271
+ "placeholder": {
272
+ "type": "string",
273
+ "description": "Placeholder text shown before user types (informational only)."
274
+ },
275
+ "choices": {
276
+ "type": "array",
277
+ "items": {
278
+ "$ref": "#/$defs/choice"
279
+ },
280
+ "description": "Available choices. When omitted for `enum` flags, the enum values\nfrom the flag schema are used automatically."
281
+ },
282
+ "min": {
283
+ "type": "integer",
284
+ "description": "Minimum number of selections required."
285
+ },
286
+ "max": {
287
+ "type": "integer",
288
+ "description": "Maximum number of selections allowed."
289
+ }
290
+ },
291
+ "required": [
292
+ "kind",
293
+ "message"
294
+ ],
295
+ "description": "Discriminated union of all prompt configurations.\n\nUse the `kind` field to narrow:\n```ts\nif (config.kind === 'select') {\n config.choices // readonly SelectChoice[] | undefined\n}\n```"
296
+ },
297
+ "choice": {
298
+ "type": "object",
299
+ "additionalProperties": false,
300
+ "properties": {
301
+ "value": {
302
+ "type": "string",
303
+ "description": "The value returned when this choice is selected."
304
+ },
305
+ "label": {
306
+ "type": "string",
307
+ "description": "Display label shown to the user."
308
+ },
309
+ "description": {
310
+ "type": "string",
311
+ "description": "Optional description shown alongside the choice."
312
+ }
313
+ },
314
+ "required": [
315
+ "value"
316
+ ],
317
+ "description": "A selectable option for SelectPromptConfig and MultiselectPromptConfig prompts."
318
+ },
319
+ "example": {
320
+ "type": "object",
321
+ "additionalProperties": false,
322
+ "properties": {
323
+ "command": {
324
+ "type": "string",
325
+ "description": "The command invocation (e.g. `'deploy production --force'`)."
326
+ },
327
+ "description": {
328
+ "type": "string",
329
+ "description": "Optional description of what this example does."
330
+ }
331
+ },
332
+ "required": [
333
+ "command"
334
+ ],
335
+ "description": "A single usage example shown in help text."
336
+ }
337
+ }
338
+ }
package/examples/basic.ts CHANGED
@@ -2,7 +2,7 @@
2
2
  /**
3
3
  * Basic single-command CLI.
4
4
  *
5
- * Demonstrates: positional args, typed flags, default values, aliases.
5
+ * Demonstrates: typed positional args, typed flags, aliases, and default values.
6
6
  *
7
7
  * Usage:
8
8
  * npx tsx examples/basic.ts Alice
@@ -11,7 +11,7 @@
11
11
  * npx tsx examples/basic.ts --help
12
12
  */
13
13
 
14
- import { arg, cli, command, flag } from 'dreamcli';
14
+ import { arg, cli, command, flag } from '@kjanat/dreamcli';
15
15
 
16
16
  const greet = command('greet')
17
17
  .description('Greet someone')
@@ -11,21 +11,20 @@
11
11
  "type": "module",
12
12
  "module": "src/main.ts",
13
13
  "bin": {
14
- "gh": "src/main.ts",
15
- "gh-dist": "dist/main.js"
14
+ "gh": "src/main.ts"
16
15
  },
17
16
  "files": [
18
- "dist",
19
- "src"
17
+ "src",
18
+ "!src/**/*.test.ts"
20
19
  ],
21
20
  "scripts": {
22
21
  "bd": "bun run build",
23
- "build": "bun build src/main.ts --install --outdir=dist --format=esm --target=node --external dreamcli",
22
+ "build": "bun build src/main.ts --install --outdir=dist --format=esm --target=node --external @kjanat/dreamcli",
24
23
  "test": "bun test",
25
24
  "typecheck": "tsc --noEmit"
26
25
  },
27
26
  "dependencies": {
28
- "dreamcli": "link:dreamcli"
27
+ "@kjanat/dreamcli": "link:@kjanat/dreamcli"
29
28
  },
30
29
  "devDependencies": {
31
30
  "@types/bun": "catalog:",
@@ -36,13 +35,10 @@
36
35
  "bun": ">=1.3.11"
37
36
  },
38
37
  "devEngines": {
39
- "packageManager": {
40
- "name": "bun",
41
- "version": ">=1.3.11"
42
- },
43
38
  "runtime": {
44
39
  "name": "bun",
45
- "version": ">=1.3.11"
40
+ "version": ">=1.3.11",
41
+ "onFail": "error"
46
42
  }
47
43
  }
48
44
  }
@@ -4,9 +4,9 @@
4
4
  * @module
5
5
  */
6
6
 
7
- import { command, group } from 'dreamcli';
7
+ import { command, group } from '@kjanat/dreamcli';
8
8
 
9
- import { redactToken, requireAuth, tokenFlag } from '$gh/lib/auth.ts';
9
+ import { redactToken, requireAuth, tokenFlag } from '../lib/auth.ts';
10
10
 
11
11
  const authLogin = command('login')
12
12
  .description('Authenticate with GitHub')
@@ -4,11 +4,11 @@
4
4
  * @module
5
5
  */
6
6
 
7
- import { arg, CLIError, flag, group } from 'dreamcli';
7
+ import { arg, CLIError, flag, group } from '@kjanat/dreamcli';
8
8
 
9
- import issues from '$gh/data/issues.yaml' with { type: 'yaml' };
10
- import { authedCommand } from '$gh/lib/auth.ts';
11
- import { normalizeLimit } from '$gh/lib/utils.ts';
9
+ import issues from '../data/issues.yaml' with { type: 'yaml' };
10
+ import { authedCommand } from '../lib/auth.ts';
11
+ import { normalizeLimit } from '../lib/utils.ts';
12
12
 
13
13
  const issueLabelChoices = Array.from(new Set(issues.flatMap((issue) => issue.labels)))
14
14
  .sort()
@@ -4,11 +4,11 @@
4
4
  * @module
5
5
  */
6
6
 
7
- import { arg, CLIError, flag, group } from 'dreamcli';
7
+ import { arg, CLIError, flag, group } from '@kjanat/dreamcli';
8
8
 
9
- import pullRequests from '$gh/data/pull-requests.yaml' with { type: 'yaml' };
10
- import { authedCommand } from '$gh/lib/auth.ts';
11
- import { normalizeLimit, sleep } from '$gh/lib/utils.ts';
9
+ import pullRequests from '../data/pull-requests.yaml' with { type: 'yaml' };
10
+ import { authedCommand } from '../lib/auth.ts';
11
+ import { normalizeLimit, sleep } from '../lib/utils.ts';
12
12
 
13
13
  const prList = authedCommand('list')
14
14
  .description('List pull requests')
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Docs-facing exports for walkthrough Twoslash snippets.
3
+ *
4
+ * Keeps guide imports stable while reusing real command definitions.
5
+ *
6
+ * @module
7
+ */
8
+
9
+ export { authLogin, authStatus } from './commands/auth.ts';
10
+ export { issueList, issueTriage } from './commands/issue.ts';
11
+ export { prCreate, prList, prView } from './commands/pr.ts';
@@ -4,7 +4,7 @@
4
4
  * @module
5
5
  */
6
6
 
7
- import { CLIError, command, flag } from 'dreamcli';
7
+ import { CLIError, command, flag } from '@kjanat/dreamcli';
8
8
 
9
9
  export function tokenFlag(description = 'GitHub token') {
10
10
  return flag.string().env('GH_TOKEN').describe(description);
@@ -3,15 +3,16 @@
3
3
  *
4
4
  * @module
5
5
  */
6
+ /// <reference types="bun" />
6
7
 
7
8
  import { describe, expect, it } from 'bun:test';
8
9
 
9
- import { runCommand } from 'dreamcli/testkit';
10
+ import { runCommand } from '@kjanat/dreamcli/testkit';
10
11
 
11
- import { authLogin, authStatus } from '$gh/commands/auth.ts';
12
- import { issueList, issueTriage } from '$gh/commands/issue.ts';
13
- import { prCreate, prList, prView } from '$gh/commands/pr.ts';
14
- import { normalizeLimit, sleep } from '$gh/lib/utils.ts';
12
+ import { authLogin, authStatus } from './commands/auth.ts';
13
+ import { issueList, issueTriage } from './commands/issue.ts';
14
+ import { prCreate, prList, prView } from './commands/pr.ts';
15
+ import { normalizeLimit, sleep } from './lib/utils.ts';
15
16
 
16
17
  const token = 'ghp_test_token_1234';
17
18
 
@@ -16,11 +16,13 @@
16
16
  * @module
17
17
  */
18
18
 
19
- import { type CLIBuilder, cli } from 'dreamcli';
19
+ // oxlint-disable-next-line no-unused-vars -- for CLIBuilder type in JSDoc
20
+ import type { CLIBuilder } from '@kjanat/dreamcli';
21
+ import { cli } from '@kjanat/dreamcli';
20
22
 
21
- import { auth } from '$gh/commands/auth.ts';
22
- import { issue } from '$gh/commands/issue.ts';
23
- import { pr } from '$gh/commands/pr.ts';
23
+ import { auth } from './commands/auth.ts';
24
+ import { issue } from './commands/issue.ts';
25
+ import { pr } from './commands/pr.ts';
24
26
 
25
27
  /**
26
28
  * Create the example CLI and register commands.
@@ -30,9 +32,9 @@ import { pr } from '$gh/commands/pr.ts';
30
32
  *
31
33
  * Command registration order determines the order shown in `--help`.
32
34
  */
33
- const gh = cli('gh').packageJson();
35
+ export const gh = cli('gh').packageJson().command(auth).command(pr).command(issue).completions();
34
36
 
35
37
  // Run the CLI if this file is executed directly (e.g. `bun src/main.ts ...`).
36
38
  if (import.meta.main) {
37
- void gh.command(auth).command(pr).command(issue).completions().run();
39
+ gh.run();
38
40
  }
@@ -2,8 +2,8 @@
2
2
  /**
3
3
  * Interactive prompts with config file fallback.
4
4
  *
5
- * Demonstrates: per-flag .prompt(), command-level .interactive(),
6
- * .env(), .config(), resolution chain (CLI → env → config → prompt → default).
5
+ * Demonstrates: per-flag `.prompt()`, `.env()`, `.config()`, and the full
6
+ * resolution chain (CLI → env → config → prompt → default).
7
7
  *
8
8
  * The resolution chain means:
9
9
  * 1. Explicit CLI flag wins: --region eu
@@ -19,7 +19,7 @@
19
19
  * echo '{}' | npx tsx examples/interactive.ts # non-interactive: uses defaults / errors
20
20
  */
21
21
 
22
- import { arg, cli, command, flag } from 'dreamcli';
22
+ import { arg, cli, command, flag } from '@kjanat/dreamcli';
23
23
 
24
24
  const deploy = command('deploy')
25
25
  .description('Deploy to an environment')
@@ -2,21 +2,19 @@
2
2
  /**
3
3
  * Mixed machine-readable JSON and human-readable side-channel output.
4
4
  *
5
- * Demonstrates: always-on `out.json()` machine output to stdout,
6
- * human-readable stderr side channels via `out.table(..., { format: 'text',
7
- * stream: 'stderr' })` / `out.error()`, plus `--json` for CLI-managed JSON
8
- * behavior such as structured errors.
5
+ * Demonstrates: machine-readable `out.json()` stdout, human-readable stderr
6
+ * side channels, and `--json` for CLI-managed structured errors.
9
7
  *
10
8
  * Usage:
11
9
  * npx tsx examples/json-mode.ts list # JSON stdout + plain stderr side channel
12
10
  * npx tsx examples/json-mode.ts list --format table # JSON stdout + table stderr side channel
13
11
  * npx tsx examples/json-mode.ts list --json # same success output; CLI-managed errors stay JSON-safe
14
12
  * npx tsx examples/json-mode.ts show web-api
15
- * npx tsx examples/json-mode.ts show nonexistent # structured error
13
+ * npx tsx examples/json-mode.ts show nonexistent # structured error
16
14
  * npx tsx examples/json-mode.ts show nonexistent --json # JSON error
17
15
  */
18
16
 
19
- import { arg, CLIError, cli, command, flag } from 'dreamcli';
17
+ import { arg, CLIError, cli, command, flag } from '@kjanat/dreamcli';
20
18
 
21
19
  // --- Sample data ---
22
20
 
@@ -2,15 +2,15 @@
2
2
  /**
3
3
  * Middleware patterns: auth guard, request timing, error handling.
4
4
  *
5
- * Demonstrates: middleware() with typed context, context accumulation,
6
- * short-circuit on error, wrap-around timing.
5
+ * Demonstrates: typed middleware context, auth guards, short-circuiting, and
6
+ * wrap-around timing.
7
7
  *
8
8
  * Usage:
9
9
  * npx tsx examples/middleware.ts deploy production
10
10
  * npx tsx examples/middleware.ts deploy production --verbose
11
11
  */
12
12
 
13
- import { arg, CLIError, cli, command, flag, middleware } from 'dreamcli';
13
+ import { arg, CLIError, cli, command, flag, middleware } from '@kjanat/dreamcli';
14
14
 
15
15
  // --- Auth middleware — adds `user` to context ---
16
16
 
@@ -2,8 +2,8 @@
2
2
  /**
3
3
  * Multi-command CLI with nested command groups (git-like).
4
4
  *
5
- * Demonstrates: cli(), command(), group(), subcommand nesting,
6
- * version, env binding, flag propagation.
5
+ * Demonstrates: top-level commands, nested groups, version metadata, and
6
+ * env-backed flags.
7
7
  *
8
8
  * Usage:
9
9
  * npx tsx examples/multi-command.ts deploy production --force
@@ -16,7 +16,7 @@
16
16
  * npx tsx examples/multi-command.ts --version
17
17
  */
18
18
 
19
- import { arg, cli, command, flag, group } from 'dreamcli';
19
+ import { arg, cli, command, flag, group } from '@kjanat/dreamcli';
20
20
 
21
21
  // --- Top-level commands ---
22
22
 
@@ -2,16 +2,16 @@
2
2
  /**
3
3
  * Spinner and progress bar usage.
4
4
  *
5
- * Demonstrates: out.spinner(), out.progress(), auto-disable in
6
- * non-TTY / --json mode, spinner.wrap() convenience.
5
+ * Demonstrates: `out.spinner()`, `out.progress()`, `spinner.wrap()`, and
6
+ * automatic suppression in non-TTY or `--json` mode.
7
7
  *
8
8
  * Usage:
9
9
  * npx tsx examples/spinner-progress.ts
10
- * npx tsx examples/spinner-progress.ts --json # spinners suppressed, JSON output
11
- * echo | npx tsx examples/spinner-progress.ts # non-TTY: spinners silent
10
+ * npx tsx examples/spinner-progress.ts --json # spinners suppressed, JSON output
11
+ * echo | npx tsx examples/spinner-progress.ts # non-TTY: spinners silent
12
12
  */
13
13
 
14
- import { cli, command, flag } from 'dreamcli';
14
+ import { cli, command, flag } from '@kjanat/dreamcli';
15
15
 
16
16
  function sleep(ms: number): Promise<void> {
17
17
  return new Promise((resolve) => setTimeout(resolve, ms));
@@ -1,17 +1,19 @@
1
1
  #!/usr/bin/env bun
2
2
  /**
3
- * Testing examples using dreamcli/testkit.
3
+ * Testing examples using @kjanat/dreamcli/testkit.
4
4
  *
5
- * Demonstrates: runCommand(), prompt answers, env/config injection,
6
- * activity event assertions. This file is structured as a vitest
7
- * test suite — run with `bun test examples/testing.ts`.
5
+ * Demonstrates: `runCommand()`, prompt answers, env/config injection, output
6
+ * assertions, middleware context, and activity assertions.
7
+ *
8
+ * This file is structured as a Vitest test suite — run with
9
+ * `bun test examples/testing.ts`.
8
10
  *
9
11
  * Usage:
10
12
  * bun test examples/testing.ts
11
13
  */
12
14
 
13
- import { arg, command, flag, middleware } from 'dreamcli';
14
- import { createTestPrompter, PROMPT_CANCEL, runCommand } from 'dreamcli/testkit';
15
+ import { arg, command, flag, middleware } from '@kjanat/dreamcli';
16
+ import { createTestPrompter, PROMPT_CANCEL, runCommand } from '@kjanat/dreamcli/testkit';
15
17
  import { describe, expect, it } from 'vitest';
16
18
 
17
19
  // --- Command under test ---