@kjanat/dreamcli 3.0.0 → 4.0.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (147) hide show
  1. package/CHANGELOG.md +967 -1
  2. package/README.md +9 -3
  3. package/dist/core/cli/builtins.d.mts +47 -0
  4. package/dist/core/cli/builtins.mjs +135 -0
  5. package/dist/core/cli/compiled.d.mts +29 -0
  6. package/dist/core/cli/compiled.mjs +76 -0
  7. package/dist/core/cli/dispatch.d.mts +9 -85
  8. package/dist/core/cli/help-links.d.mts +2 -14
  9. package/dist/core/cli/index.d.mts +282 -101
  10. package/dist/core/cli/index.mjs +497 -264
  11. package/dist/core/cli/planner.d.mts +13 -86
  12. package/dist/core/cli/planner.mjs +47 -30
  13. package/dist/core/cli/plugin.d.mts +1 -1
  14. package/dist/core/cli/propagate.mjs +1 -1
  15. package/dist/core/cli/reserved-flags.d.mts +1 -0
  16. package/dist/core/cli/reserved-flags.mjs +158 -0
  17. package/dist/core/cli/root-help.d.mts +1 -47
  18. package/dist/core/cli/root-help.mjs +37 -47
  19. package/dist/core/cli/root-output-flags.d.mts +1 -0
  20. package/dist/core/cli/root-output-flags.mjs +169 -0
  21. package/dist/core/cli/root-surface.d.mts +1 -68
  22. package/dist/core/cli/root-surface.mjs +2 -2
  23. package/dist/core/cli/runtime-preflight.d.mts +1 -199
  24. package/dist/core/cli/runtime-preflight.mjs +67 -17
  25. package/dist/core/completion/index.d.mts +2 -2
  26. package/dist/core/completion/shells/bash.d.mts +0 -1
  27. package/dist/core/completion/shells/bash.mjs +2 -1
  28. package/dist/core/completion/shells/fish.d.mts +0 -1
  29. package/dist/core/completion/shells/fish.mjs +2 -1
  30. package/dist/core/completion/shells/powershell.d.mts +0 -1
  31. package/dist/core/completion/shells/powershell.mjs +2 -1
  32. package/dist/core/completion/shells/shared.d.mts +3 -114
  33. package/dist/core/completion/shells/shared.mjs +9 -39
  34. package/dist/core/completion/shells/zsh.d.mts +0 -1
  35. package/dist/core/completion/shells/zsh.mjs +2 -1
  36. package/dist/core/config/index.d.mts +3 -3
  37. package/dist/core/config/index.mjs +2 -2
  38. package/dist/core/config/package-json.d.mts +2 -33
  39. package/dist/core/config/package-json.mjs +1 -34
  40. package/dist/core/errors/index.d.mts +7 -7
  41. package/dist/core/execution/index.d.mts +1 -48
  42. package/dist/core/execution/index.mjs +42 -27
  43. package/dist/core/help/ansi.d.mts +0 -11
  44. package/dist/core/help/index.d.mts +3 -35
  45. package/dist/core/help/index.mjs +29 -6
  46. package/dist/core/help/theme.d.mts +1 -21
  47. package/dist/core/json-schema/index.d.mts +279 -10
  48. package/dist/core/json-schema/index.mjs +482 -237
  49. package/dist/core/json-schema/meta-descriptions.generated.d.mts +79 -7
  50. package/dist/core/json-schema/meta-descriptions.generated.mjs +40 -6
  51. package/dist/core/output/activity.d.mts +1 -193
  52. package/dist/core/output/activity.mjs +1 -1
  53. package/dist/core/output/bind.d.mts +1 -37
  54. package/dist/core/output/contracts.d.mts +7 -13
  55. package/dist/core/output/contracts.mjs +1 -1
  56. package/dist/core/output/display-value.d.mts +1 -19
  57. package/dist/core/output/index.d.mts +5 -187
  58. package/dist/core/output/index.mjs +44 -9
  59. package/dist/core/output/renderers.d.mts +1 -45
  60. package/dist/core/output/writer.d.mts +0 -1
  61. package/dist/core/parse/index.d.mts +27 -5
  62. package/dist/core/parse/index.mjs +350 -227
  63. package/dist/core/parse/occurrences.d.mts +89 -0
  64. package/dist/core/parse/occurrences.mjs +114 -0
  65. package/dist/core/prompt/index.d.mts +3 -3
  66. package/dist/core/read-flags/index.d.mts +150 -0
  67. package/dist/core/read-flags/index.mjs +217 -0
  68. package/dist/core/resolve/args.d.mts +35 -4
  69. package/dist/core/resolve/args.mjs +132 -55
  70. package/dist/core/resolve/coerce.d.mts +66 -9
  71. package/dist/core/resolve/coerce.mjs +834 -270
  72. package/dist/core/resolve/config.d.mts +1 -10
  73. package/dist/core/resolve/contracts.d.mts +67 -44
  74. package/dist/core/resolve/errors.mjs +29 -21
  75. package/dist/core/resolve/flags.d.mts +36 -9
  76. package/dist/core/resolve/flags.mjs +129 -151
  77. package/dist/core/resolve/index.d.mts +8 -6
  78. package/dist/core/resolve/index.mjs +51 -18
  79. package/dist/core/resolve/path-checks.d.mts +47 -0
  80. package/dist/core/resolve/path-checks.mjs +102 -0
  81. package/dist/core/resolve/redaction.d.mts +12 -0
  82. package/dist/core/resolve/redaction.mjs +14 -0
  83. package/dist/core/resolve/stages.d.mts +85 -0
  84. package/dist/core/resolve/stages.mjs +170 -0
  85. package/dist/core/resolve/standard.d.mts +1 -24
  86. package/dist/core/resolve/standard.mjs +141 -43
  87. package/dist/core/schema/activity.d.mts +16 -16
  88. package/dist/core/schema/arg.d.mts +849 -71
  89. package/dist/core/schema/arg.mjs +727 -54
  90. package/dist/core/schema/brand.d.mts +17 -0
  91. package/dist/core/schema/cardinality.d.mts +301 -0
  92. package/dist/core/schema/cardinality.mjs +514 -0
  93. package/dist/core/schema/command.d.mts +181 -112
  94. package/dist/core/schema/command.mjs +305 -42
  95. package/dist/core/schema/flag.d.mts +515 -173
  96. package/dist/core/schema/flag.mjs +576 -78
  97. package/dist/core/schema/index.d.mts +11 -8
  98. package/dist/core/schema/index.mjs +10 -0
  99. package/dist/core/schema/middleware.d.mts +15 -12
  100. package/dist/core/schema/number-constraints.d.mts +5 -5
  101. package/dist/core/schema/prompt.d.mts +4 -4
  102. package/dist/core/schema/provenance.d.mts +99 -0
  103. package/dist/core/schema/provenance.mjs +28 -0
  104. package/dist/core/schema/run.d.mts +21 -60
  105. package/dist/core/schema/source.d.mts +179 -0
  106. package/dist/core/schema/source.mjs +206 -0
  107. package/dist/core/schema/standard.d.mts +12 -19
  108. package/dist/core/schema/stdin.d.mts +87 -0
  109. package/dist/core/schema/stdin.mjs +91 -0
  110. package/dist/core/schema/string-constraints.d.mts +16 -5
  111. package/dist/core/schema/string-constraints.mjs +18 -1
  112. package/dist/core/schema/value-parsers.d.mts +81 -9
  113. package/dist/core/schema/value-parsers.mjs +19 -1
  114. package/dist/core/schema/value.d.mts +242 -0
  115. package/dist/core/schema/value.mjs +573 -0
  116. package/dist/core/testkit/index.d.mts +28 -3
  117. package/dist/core/testkit/index.mjs +40 -26
  118. package/dist/index.d.mts +21 -16
  119. package/dist/index.mjs +10 -6
  120. package/dist/runtime/adapter.d.mts +3 -3
  121. package/dist/runtime/deno.d.mts +3 -3
  122. package/dist/runtime/detect.d.mts +2 -2
  123. package/dist/runtime/node.d.mts +3 -3
  124. package/dist/runtime/paths.d.mts +1 -31
  125. package/dist/runtime.d.mts +4 -4
  126. package/dist/strings.d.mts +1 -16
  127. package/dist/testkit.d.mts +2 -2
  128. package/dist/testkit.mjs +1 -1
  129. package/dist/version.d.mts +0 -13
  130. package/dist/version.mjs +2 -2
  131. package/dreamcli.schema.json +368 -78
  132. package/examples/interactive.ts +6 -5
  133. package/package.json +10 -9
  134. package/skills/cli-creation/SKILL.md +196 -0
  135. package/skills/cli-creation/agents/openai.yaml +4 -0
  136. package/skills/cli-creation/assets/templates/multi-command.bun-test.ts.tpl +20 -0
  137. package/skills/cli-creation/assets/templates/multi-command.test.ts.tpl +20 -0
  138. package/skills/cli-creation/assets/templates/multi-command.ts.tpl +89 -0
  139. package/skills/cli-creation/assets/templates/single-command.bun-test.ts.tpl +29 -0
  140. package/skills/cli-creation/assets/templates/single-command.test.ts.tpl +29 -0
  141. package/skills/cli-creation/assets/templates/single-command.ts.tpl +47 -0
  142. package/skills/cli-creation/references/consumer-workflow.md +65 -0
  143. package/skills/cli-creation/references/pattern-cookbook.md +451 -0
  144. package/skills/cli-creation/references/runtime-notes.md +29 -0
  145. package/skills/cli-creation/scripts/scaffold_cli.py +360 -0
  146. package/dist/core/resolve/property.d.mts +0 -51
  147. package/dist/core/resolve/property.mjs +0 -53
@@ -0,0 +1,451 @@
1
+ # Pattern Cookbook
2
+
3
+ Copy-ready snippets for DreamCLI 4.0. Every snippet type-checks against the
4
+ published types.
5
+
6
+ ## Values
7
+
8
+ ### Precedence chain
9
+
10
+ ```ts
11
+ flag
12
+ .enum(['us', 'eu', 'ap'])
13
+ .stdin()
14
+ .env('DEPLOY_REGION')
15
+ .config('deploy.region')
16
+ .prompt({ kind: 'select', message: 'Which region?' })
17
+ .default('us');
18
+
19
+ arg
20
+ .enum(['us', 'eu', 'ap'])
21
+ .stdin()
22
+ .env('DEPLOY_REGION')
23
+ .config('deploy.region')
24
+ .prompt({ kind: 'select', message: 'Which region?' })
25
+ .default('us');
26
+ ```
27
+
28
+ Resolution order is fixed: CLI argv, stdin, env, config, prompt, default, and
29
+ both flags and positionals walk it. Declare the sources a value may come from;
30
+ never merge them by hand in the action.
31
+
32
+ ### Reading piped stdin
33
+
34
+ ```ts
35
+ flag.string().stdin(); // `--body -` or an absent flag reads the pipe
36
+ arg.string().stdin(); // `-` or an omitted slot reads the pipe
37
+ flag.string().stdin({ when: 'dash' }); // only an explicit `-`
38
+ arg.string().stdin({ when: 'missing' }); // only an omitted slot; `-` stays literal
39
+ flag.string().stdin({ consume: 'broadcast' }); // shares the buffer with other inputs
40
+ flag.string().stdin({ trim: true }); // drops one trailing line terminator
41
+ ```
42
+
43
+ Available on every flag kind but `count`, which counts occurrences rather than
44
+ reading a value and throws `INVALID_SCHEMA`, and on every arg kind. A `-` stays
45
+ CLI-sourced and outranks every later stage; an absent input takes the stdin
46
+ stage, which sits ahead of env. One command has one exclusive stdin consumer,
47
+ and a second `.stdin()` input of either surface throws `DUPLICATE_STDIN_INPUT`
48
+ unless every one of them passes `{ consume: 'broadcast' }`.
49
+
50
+ A `string` input keeps the buffer byte for byte, so `echo hi | mycli` gives
51
+ `'hi\n'`; every other kind drops one trailing line terminator before decoding.
52
+ `{ trim: true }` drops it for a `string` too, which is what a piped path wants:
53
+
54
+ ```ts
55
+ arg.path({ mustExist: true }).stdin({ trim: true });
56
+ // echo ./dist | mycli clean → the check runs against './dist'
57
+ ```
58
+
59
+ It applies to a single value. A collection's terminators separate its elements,
60
+ so `.split({ stdin })` decides those.
61
+
62
+ A collection reads the buffer as elements and splices them where a `-`
63
+ occurrence sits. A `-` typed beside other occurrences with nothing piped fails
64
+ with `MISSING_STDIN`, rather than shortening the collection;
65
+ occurrences of nothing but `-`, and a scalar `-`, fall through to the later
66
+ sources instead. A stdin-enabled input can never receive a literal `-` as its
67
+ value, since the token names the source; `{ when: 'missing' }` is the one
68
+ binding that leaves it literal.
69
+
70
+ ### Rich flag types
71
+
72
+ ```ts
73
+ flag.url({ protocols: ['https'] }); // URL
74
+ flag.path({ type: 'directory', create: true }); // string, mkdir -p when missing
75
+ flag.date({ min: new Date('2020-01-01') }); // Date, strict ISO-8601
76
+ flag.duration(); // number (ms) — '30s', '1h30m', '250ms'
77
+ flag.bytes(); // number — '512mb', '1.5gb'
78
+ flag.count().alias('v'); // number — -vvv is 3
79
+ flag.keyValue(); // Record<string, string> — repeated KEY=VALUE
80
+ ```
81
+
82
+ Prefer these over `flag.string()` plus hand-rolled parsing: they validate at
83
+ every source, feed help placeholders, and land in the exported JSON Schema.
84
+
85
+ `flag.path()` checks run through the runtime adapter after resolution. In
86
+ process-free execution pass `stat` (and `mkdir` for `create`) via run options,
87
+ or the checks are skipped.
88
+
89
+ ### Rich arg types
90
+
91
+ ```ts
92
+ arg.url({ protocols: ['https'] }); // URL
93
+ arg.path({ mustExist: true }); // string, checked after resolution
94
+ arg.date({ min: new Date('2020-01-01') }); // Date, strict ISO-8601
95
+ arg.duration(); // number (ms)
96
+ arg.bytes(); // number
97
+ arg.url().variadic(); // URL[], each value validated
98
+ ```
99
+
100
+ Same option objects, parsers, and error codes as the flag kinds above. Required
101
+ by default; add `.optional()` or `.default()` to change that. `arg.path()` needs
102
+ the same `stat`/`mkdir` injection as `flag.path()`, and a variadic path arg
103
+ checks every value it collects.
104
+
105
+ There is no `arg.array()` (use `.variadic()`) and no `arg.count()`, which counts
106
+ flag occurrences. `arg.boolean()` and `arg.keyValue()` do exist:
107
+ `arg.boolean()` consumes an explicit `true`/`false` token, and
108
+ `arg.keyValue(element)` consumes `KEY=VALUE` tokens into a record, taking the
109
+ same kind of element builder as `flag.keyValue(element)`. `.stdin()`,
110
+ `.env()`, `.config()`, and `.prompt()` are all available on an argument,
111
+ `.variadic()` included: a `-` among the tail tokens splices the decoded buffer
112
+ in at that position, so `printf 'x\ny\n' | mycli build a - b` collects
113
+ `['a', 'x', 'y', 'b']`, and an empty tail takes the whole buffer.
114
+ Prompts are unavailable on key-value arguments, and count flags cannot read
115
+ stdin.
116
+
117
+ A variadic argument is the last positional a command can declare. Registering
118
+ another one behind it throws `INVALID_BUILDER_STATE` on both construction
119
+ paths, since it could never be filled.
120
+
121
+ ### Constraints instead of hand-written validation
122
+
123
+ ```ts
124
+ flag.number({ int: true, min: 1, max: 65535 }); // port
125
+ flag.string({ nonEmpty: true, pattern: /^[a-z][a-z0-9-]*$/ }); // slug
126
+ flag.number().finite(false); // opt back into Infinity
127
+ arg.string({ nonEmpty: true, pattern: /^[a-z][a-z0-9-]*$/ }); // same on positionals
128
+ arg.number().int().min(1); // chainable, same as flag
129
+ ```
130
+
131
+ Constraints are enforced on CLI parse (`INVALID_VALUE`) and on
132
+ env/config/prompt/stdin resolution (`CONSTRAINT_VIOLATED`), both exit code 2.
133
+ A `.default()` value is checked against them where the chain declares it, and a
134
+ violation throws `INVALID_DEFAULT`, whichever order the chain is written in.
135
+ `finite` defaults to `true`, so `Infinity` is rejected unless you opt out:
136
+
137
+ ```ts
138
+ flag.string({ minLength: 3 }).default('ab'); // INVALID_DEFAULT
139
+ flag.string().default('ab').minLength(3); // same verdict
140
+ flag.number({ finite: false }).default(Number.POSITIVE_INFINITY); // fine
141
+ ```
142
+
143
+ Asynchronous validators and `flag.path()` / `arg.path()` filesystem checks stay
144
+ at resolution time, so a default goes through those when the command runs.
145
+
146
+ ### Standard Schema validation
147
+
148
+ ```ts
149
+ import { z } from 'zod';
150
+
151
+ flag.custom(z.coerce.number().int().positive());
152
+ ```
153
+
154
+ Any Standard Schema v1 validator works (Zod, Valibot, ArkType) with the output
155
+ type inferred. Validation runs after source resolution, so every source is
156
+ checked identically.
157
+
158
+ On a collection, where the validator sits decides what it sees:
159
+
160
+ ```ts
161
+ flag.array(flag.string().standard(slug)); // each element: --tag[1] failed validation: …
162
+ flag.array(flag.string()).standard(nonEmptyList); // the finished array
163
+ arg.string().standard(slug).variadic(); // each element
164
+ arg.string().variadic().standard(nonEmptyList); // the finished array
165
+ ```
166
+
167
+ On an argument the position in the chain is what decides it, because
168
+ `.variadic()` is what makes the argument aggregate.
169
+
170
+ ### Collections
171
+
172
+ ```ts
173
+ flag
174
+ .array(flag.enum(['us', 'eu', 'ap']))
175
+ .separator(',')
176
+ .unique();
177
+
178
+ flag.keyValue().duplicateKeys('error'); // -e A=1 -e A=2 fails
179
+ arg.keyValue().variadic(); // mycli render a=1 b=2 → { a: '1', b: '2' }
180
+ arg.keyValue(arg.number().int()).variadic(); // mycli scale web=3 → { web: 3 }
181
+ ```
182
+
183
+ `--region us,eu --region ap` and repetition both work. Put flag-level modifiers
184
+ (`.env()`, `.default()`) on the array, never on the element, which is a compile
185
+ error.
186
+
187
+ On the arg surface these four are collection modifiers, so each states the shape
188
+ it needs and the compiler refuses it elsewhere. `.separator()` and `.split()`
189
+ want a variadic argument or `arg.keyValue()`, `.unique()` a variadic argument of
190
+ a list kind, and `.duplicateKeys()` `arg.keyValue()`. `createArgSchema()` throws
191
+ `INVALID_SCHEMA` on the same combinations.
192
+
193
+ Each source decodes under its own policy, and a CLI separator is not inherited:
194
+
195
+ ```ts
196
+ flag.array(flag.string()).split({ cli: ',', env: 'json', stdin: 'lines' }).env('TAGS').stdin();
197
+ // --tag a,b → ['a', 'b']
198
+ // TAGS='["a","b"]' → ['a', 'b']
199
+ // printf 'a\nb\n' | … → ['a', 'b']
200
+ ```
201
+
202
+ Defaults without `.split()`: whole CLI tokens, comma-delimited env values,
203
+ line-delimited stdin, native arrays and objects from config. A `-` occurrence
204
+ splices the decoded buffer in at that position.
205
+
206
+ ## Parser behavior
207
+
208
+ ### Negatable booleans
209
+
210
+ ```ts
211
+ flag.boolean().default(true).negatable(); // --sandbox / --no-sandbox
212
+ ```
213
+
214
+ One logical flag with two spellings; help renders `--[no-]sandbox`. The negated
215
+ spelling is presence-only (`--no-sandbox=false` errors).
216
+
217
+ ### Duplicate policy
218
+
219
+ ```ts
220
+ flag.enum(['session', 'worktree']).duplicates('error');
221
+ ```
222
+
223
+ Config-style flags should reject repeats rather than silently taking the last
224
+ value. `'error'` throws `ParseError` code `DUPLICATE_FLAG`; `'first'` keeps the
225
+ first. Counted per logical flag, including aliases and negated spellings.
226
+
227
+ ### Cross-flag rules
228
+
229
+ ```ts
230
+ command('serve')
231
+ .flag('port', flag.number({ int: true }))
232
+ .flag('socket', flag.string())
233
+ .derive(({ flags }) => {
234
+ if (flags.port !== undefined && flags.socket !== undefined) {
235
+ throw new CLIError('--port and --socket are mutually exclusive', {
236
+ code: 'INVALID_FLAG_COMBINATION',
237
+ });
238
+ }
239
+ return { mode: flags.socket !== undefined ? 'socket' : 'tcp' } as const;
240
+ })
241
+ .action(({ ctx }) => {
242
+ ctx.mode; // typed, available to the action
243
+ });
244
+ ```
245
+
246
+ `.derive()` runs after resolution and before the action. It is the home for
247
+ rules DreamCLI cannot express declaratively, and its return value widens `ctx`.
248
+
249
+ ### Explicit versus defaulted
250
+
251
+ ```ts
252
+ import { command, flag, wasExplicit } from '@kjanat/dreamcli';
253
+
254
+ command('serve')
255
+ .flag('port', flag.number({ int: true }).env('PORT').default(3000))
256
+ .derive(({ flags, sources }) => {
257
+ if (flags.port !== undefined && sources.flags.port?.stage === 'env') {
258
+ // the environment supplied it, not the command line
259
+ }
260
+ return { overridden: wasExplicit(sources.flags.port) };
261
+ })
262
+ .action(({ ctx }) => {
263
+ ctx.overridden; // boolean
264
+ });
265
+ ```
266
+
267
+ `sources` is keyed like `flags` and `args`, and each entry names the stage that
268
+ produced the value: `cli`, `stdin`, `env` with its `envVar`, `config` with its
269
+ `configPath`, `prompt`, or `default`. An explicit `-` reports
270
+ `{ stage: 'cli', via: 'stdin', trigger: 'dash' }`, so a piped value is
271
+ distinguishable from a typed one. `wasExplicit()` is the predicate for
272
+ "anything but the default", which is what a mutually-exclusive rule or an
273
+ explicit-wins merge needs. Never drop `.default()` to detect this: that also
274
+ drops `defaultValue` from `--help --json` and the exported schema.
275
+
276
+ ## Output
277
+
278
+ ### Channels
279
+
280
+ ```ts
281
+ .action(({ out }) => {
282
+ out.log('primary result'); // stdout (stderr in --json)
283
+ out.status('working on it'); // stderr, hidden by --quiet
284
+ out.warn('deprecated flag used');// stderr, always shown
285
+ out.error('could not reach api');// stderr, always shown
286
+ });
287
+ ```
288
+
289
+ Keep stdout free of progress chatter so pipes stay clean. `--quiet`/`-q` is a
290
+ global flag; it silences `status` and `info` but never warnings or errors.
291
+
292
+ ### JSON mode branching
293
+
294
+ ```ts
295
+ .action(({ out }) => {
296
+ const data = { service: 'api', healthy: true };
297
+
298
+ if (out.jsonMode) {
299
+ out.json(data);
300
+ return;
301
+ }
302
+
303
+ out.log('Service api is healthy');
304
+ });
305
+ ```
306
+
307
+ Never mix human text into stdout in the same branch as `out.json()`.
308
+
309
+ ### Tables
310
+
311
+ ```ts
312
+ out.table(rows, [
313
+ { key: 'name', header: 'Service' },
314
+ { key: 'status', header: 'Status' },
315
+ ]);
316
+ ```
317
+
318
+ Text table for humans, array for `--json`. Columns are optional
319
+ (`out.table(rows)` infers them); pass `{ format: 'text', stream: 'stderr' }` to
320
+ force a human table alongside JSON stdout.
321
+
322
+ ### Colors and hyperlinks
323
+
324
+ ```ts
325
+ .action(({ out }) => {
326
+ out.log(out.color.green('✔ done'));
327
+ if (out.isHyperlinkSupported) out.log(osc8('https://example.com', 'docs'));
328
+ });
329
+ ```
330
+
331
+ Every `out.color` formatter is an identity function when color is off (piped,
332
+ `NO_COLOR`, `--json`), so no branching is needed. Hyperlinks garble piped
333
+ output, so gate them on `out.isHyperlinkSupported`.
334
+
335
+ ### Exit code without an error
336
+
337
+ ```ts
338
+ .action(({ out }) => {
339
+ out.log('3 of 5 checks failed');
340
+ out.setExitCode(1);
341
+ });
342
+ ```
343
+
344
+ For check/status commands: keeps normal output, avoids an error payload in
345
+ `--json`, still signals scripts.
346
+
347
+ ### Structured errors
348
+
349
+ ```ts
350
+ throw new CLIError('Deployment target not found', {
351
+ code: 'NOT_FOUND',
352
+ exitCode: 1,
353
+ suggest: 'Run: mycli deploy --help',
354
+ details: { requested: name },
355
+ });
356
+ ```
357
+
358
+ Serializes cleanly in `--json` mode and prints a suggestion line otherwise.
359
+
360
+ ## Surface
361
+
362
+ ### Help configuration
363
+
364
+ ```ts
365
+ cli('mycli').help({
366
+ flagOrder: 'declaration', // or a sortFlags comparator
367
+ theme: (c) => ({ sectionTitle: c.magenta }),
368
+ footer: false,
369
+ });
370
+ ```
371
+
372
+ The theme factory receives the gated palette and never runs when color is off,
373
+ so a custom theme cannot leak escapes into piped output.
374
+
375
+ ### Examples that know the program name
376
+
377
+ ```ts
378
+ command('deploy').example(({ name }) => `${name} deploy production --force`, 'Force a deploy');
379
+ ```
380
+
381
+ The builder form resolves at render time, so examples stay truthful under
382
+ symlinks, `inheritName`, and `npx` versus a global install.
383
+
384
+ ### Default command
385
+
386
+ ```ts
387
+ cli('mycli').default(serve); // root surface only: `mycli --port 80`
388
+ cli('mycli').default(serve, { route: true }); // also `mycli serve`
389
+ ```
390
+
391
+ A plain `.default()` is the root surface and is not routable by name; the token
392
+ would be read as its first positional.
393
+
394
+ ### Completions
395
+
396
+ ```ts
397
+ cli('mycli').completions(); // mycli completions <shell>
398
+ cli('mycli').completions({ as: 'flag' }); // mycli --completions (shell auto-detected)
399
+ ```
400
+
401
+ ### Config discovery
402
+
403
+ ```ts
404
+ cli('mycli')
405
+ .config('mycli')
406
+ .configLoader(configFormat(['yaml', 'yml'], parseYaml));
407
+ ```
408
+
409
+ Discovery probes project scope (cwd and every ancestor: `.mycli.json`,
410
+ `mycli.config.json`, `.config/mycli.json`), then user scope (XDG/AppData, plus
411
+ `~/Library/Application Support` on macOS), then `/etc`. First match wins; files
412
+ are never merged. `--config <path>` overrides everything.
413
+
414
+ ## Testing
415
+
416
+ ### In-process command test
417
+
418
+ ```ts
419
+ import { runCommand } from '@kjanat/dreamcli/testkit';
420
+
421
+ const result = await runCommand(deploy, ['production', '--force']);
422
+ expect(result.exitCode).toBe(0);
423
+ expect(result.stdout).toEqual(['Deploying production to us\n']);
424
+ ```
425
+
426
+ Prefer `runCommand()` over subprocess tests: faster, deterministic, and it
427
+ captures stdout/stderr as arrays of written chunks — assert trailing newlines.
428
+
429
+ ### Injecting the environment
430
+
431
+ ```ts
432
+ await runCommand(deploy, ['--json'], {
433
+ env: { DEPLOY_REGION: 'eu' },
434
+ config: { deploy: { region: 'ap' } },
435
+ stdinData: 'piped\n', // bytes a `.stdin()` input reads; `null` for nothing piped
436
+ answers: ['production'], // queued prompt answers
437
+ stat: async (p) => (p === '/data' ? 'directory' : null),
438
+ });
439
+ ```
440
+
441
+ Prompts are skipped in non-interactive contexts, so queue `answers` when a test
442
+ exercises one. Without `stat`, `flag.path()` checks are skipped entirely.
443
+ `stdinData` feeds `.stdin()` flags and args alike, so a test never has to spawn
444
+ a pipe.
445
+
446
+ ### Asserting JSON output
447
+
448
+ ```ts
449
+ const result = await runCommand(status, ['--json']);
450
+ expect(JSON.parse(result.stdout.join(''))).toEqual({ healthy: true });
451
+ ```
@@ -0,0 +1,29 @@
1
+ # Runtime Notes
2
+
3
+ ## Bun-first commands
4
+
5
+ - Run CLI entrypoint: `bun mycli.ts --help`
6
+ - Run tests: `bun test mycli.test.ts`
7
+
8
+ The scaffolder prints path-aware run commands; use those exact printed paths when `--out` is not `.`.
9
+ The scaffolder auto-detects test style:
10
+
11
+ - Bun project + no detected Vitest usage: generate `bun:test` template.
12
+ - Otherwise: generate Vitest template.
13
+ - Package manager detection checks lockfiles (including `pnpm-*.yaml/.yml`) and manifest `packageManager` entries in `package.json`, `package.json5`, and `package.yaml/.yml`.
14
+
15
+ If Vitest template is generated inside a Bun project, `bun test` still runs those tests in this workflow.
16
+
17
+ ## npm/Node alternative
18
+
19
+ - Run CLI entrypoint: `npx tsx mycli.ts --help`
20
+ - Run tests: `npx vitest run mycli.test.ts`
21
+
22
+ ## Deno alternative
23
+
24
+ - Run CLI entrypoint: `deno run -A mycli.ts --help`
25
+ - Run tests: use Bun/Node test tooling unless the project already has Deno test wiring.
26
+
27
+ ## Prompt behavior
28
+
29
+ DreamCLI skips prompts in non-interactive contexts (CI/piped input). When tests depend on prompts, inject answers with `runCommand(..., { answers: [...] })`.