@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,196 @@
1
+ ---
2
+ name: cli-creation
3
+ description: Build consumer-facing DreamCLI CLIs from scratch with Bun-first workflows and typed patterns. Use when asked to scaffold or implement a new @kjanat/dreamcli command-line app, add commands/flags/args/prompts/output/testing, or create starter files/tests for DreamCLI users.
4
+ ---
5
+
6
+ # CLI Creation
7
+
8
+ ## Overview
9
+
10
+ Create runnable DreamCLI starter CLIs and extend them with typed command
11
+ patterns. This skill covers user-facing app code built **on** DreamCLI, not
12
+ DreamCLI framework internals.
13
+
14
+ Targets DreamCLI 4.0. Version 3 removed the DSL, made the default command the
15
+ root surface, and added a large typed-flag surface. Version 4 gave both
16
+ factories the same sources, so `.stdin()`, `.env()`, `.config()`, and
17
+ `.prompt()` are available on flags and positionals alike. Snippets below assume
18
+ both.
19
+
20
+ ## Quick Start
21
+
22
+ 1. Choose a starter mode:
23
+ - `single`: one root command (`cli(name).default(command)`).
24
+ - `multi`: grouped command surface (`group('...').command(...)`).
25
+ 2. Generate starter files:
26
+ - `python scripts/scaffold_cli.py --name mycli --mode single --out .`
27
+ - Tests are generated by default; add `--no-test` only when explicitly requested.
28
+ - Test template is auto-detected: Bun without Vitest uses `bun:test`; otherwise Vitest.
29
+ 3. Run and validate generated files:
30
+ - Use the printed path from the scaffolder output, for example `bun ./mycli.ts --help`.
31
+ - Run the generated test unless `--no-test` was used.
32
+ 4. Extend behavior with references:
33
+ - `references/pattern-cookbook.md` — copy-ready, type-checked snippets.
34
+ - `references/consumer-workflow.md` — request to validated CLI.
35
+ - `references/runtime-notes.md` — Bun/Node/Deno execution.
36
+
37
+ ## Looking Things Up
38
+
39
+ Prefer these over recalling API shapes from memory; they reflect the installed
40
+ or published version rather than training data.
41
+
42
+ **The API, offline-ish, no repo needed.** If `deno` is on the system this works
43
+ regardless of whether the project installed from npm or JSR:
44
+
45
+ ```bash
46
+ deno doc jsr:@kjanat/dreamcli 2>/dev/null # full public API (~4k lines)
47
+ deno doc jsr:@kjanat/dreamcli/testkit 2>/dev/null # subpath: testkit, runtime, schema, version
48
+ deno doc --json jsr:@kjanat/dreamcli 2>/dev/null # machine-readable, for scripted lookups
49
+ deno doc --filter=CLIBuilder jsr:@kjanat/dreamcli 2>/dev/null # one symbol
50
+ ```
51
+
52
+ `2>/dev/null` matters: deno writes download and type-check progress to stderr,
53
+ which otherwise swamps the documentation output.
54
+
55
+ Pin a version with `jsr:@kjanat/dreamcli@4.0.0-rc.1` when the project is not on
56
+ latest. `--filter` takes a declaration name; it prints nothing for a name that
57
+ does not exist, which is itself a useful signal.
58
+
59
+ **The docs site, as markdown.** Every page is authored markdown served under
60
+ `/raw/`, and any page URL returns markdown under content negotiation:
61
+
62
+ ```bash
63
+ curl -s https://dreamcli.kjanat.dev/llms.txt # index of every page, one line each
64
+ curl -s https://dreamcli.kjanat.dev/llms-full.txt # every page concatenated (~250 kB)
65
+ curl -s https://dreamcli.kjanat.dev/raw/guide/flags # one page, authored markdown
66
+ curl -sH 'Accept: text/markdown' https://dreamcli.kjanat.dev/guide/flags
67
+ ```
68
+
69
+ Start from `llms.txt` to find the right page, then fetch that page rather than
70
+ pulling `llms-full.txt` into context.
71
+
72
+ ## Grounding Sources
73
+
74
+ Paths are relative to the dreamcli repository root.
75
+
76
+ - `examples/basic.ts` — single-command defaults.
77
+ - `examples/multi-command.ts` — grouped-command defaults.
78
+ - `examples/testing.ts` — `runCommand()` patterns.
79
+ - `examples/flag-types.ts` — the v3 typed-flag family.
80
+ - `examples/parser-control.ts` — negation, duplicates, spelling parity.
81
+ - `examples/output-extras.ts` — colors, hyperlinks, `setExitCode`.
82
+ - `examples/standard-schema.ts` — Standard Schema validation.
83
+ - `examples/help-config.ts` — help themes, flag order, routable default.
84
+ - `examples/gh/` — a full multi-command app used as a walkthrough.
85
+ - `docs/guide/getting-started.md` — baseline consumer narrative.
86
+ - `docs/guide/walkthrough.md` — end-to-end CLI composition.
87
+ - `docs/guide/upgrading-v3.md` — what changed from 2.x, for migrations.
88
+
89
+ ## Workflow Decision Tree
90
+
91
+ - Simple one-command utility → `--mode single`.
92
+ - Nested command groups (git/gh style) → `--mode multi`.
93
+ - Tests wanted from the start → do nothing, they are scaffolded by default.
94
+ - Tests explicitly unwanted → add `--no-test`.
95
+ - npm/tsx or Deno instructions → keep generated code unchanged and give the
96
+ runtime alternatives from `references/runtime-notes.md`.
97
+ - Migrating an existing 2.x CLI → read `docs/guide/upgrading-v3.md` first; the
98
+ default-command and `finite` changes silently alter behavior.
99
+
100
+ ## Extend the Starter
101
+
102
+ **Values.** Prefer a purpose-built kind over `flag.string()` / `arg.string()`
103
+ plus parsing. Both factories carry `string()`, `number()`, `boolean()`,
104
+ `enum(...)`, `custom(...)`, `keyValue()`, `url()`, `path()`, `date()`,
105
+ `duration()`, and `bytes()`. `flag` additionally carries `array()` and
106
+ `count()`; the arg form of `flag.array()` is `.variadic()`. Express validation
107
+ declaratively with constraints (`{ int, min, max }`, `{ nonEmpty, pattern }`,
108
+ chainable on both builders) or a Standard Schema passed to `.standard()` or to
109
+ `flag.custom()` / `arg.custom()`, not with hand-written checks in the action.
110
+
111
+ **Defaults.** A `.default()` value is validated where the chain declares it, so
112
+ a default that violates its own constraints, validator, or collection shape
113
+ throws `INVALID_DEFAULT` at build time. A collection default takes the shape the
114
+ input resolves to: an array for `flag.array()` and a variadic arg, a record for
115
+ `keyValue()`, a non-negative integer for `flag.count()`.
116
+
117
+ **Collections.** `flag.array()`, `flag.keyValue()`, `arg.keyValue()`, and
118
+ `.variadic()` aggregate from every source under one set of rules. Each source
119
+ decodes under its own policy, set by `.split({ cli, env, stdin })`: whole CLI
120
+ tokens by default, comma-delimited env values, line-delimited stdin, and native
121
+ arrays and objects from config. `.separator()` sets the CLI policy alone and is
122
+ no longer inherited by env or config. `.unique()` dedupes a list, and
123
+ `.duplicateKeys('last' | 'first' | 'error')` decides a repeated key on every
124
+ source, naming the source that carried it. A validator on the element builder
125
+ checks each element; one on the collection builder checks the finished value.
126
+ On the arg surface, `.separator()` and `.split()` require `.variadic()` or
127
+ `arg.keyValue()`, `.unique()` requires a variadic list, and `.duplicateKeys()`
128
+ requires `arg.keyValue()`. The compiler refuses every other shape and
129
+ `createArgSchema()` throws `INVALID_SCHEMA`.
130
+
131
+ **Argument order.** A variadic argument takes every remaining positional, so it
132
+ is the last one a command can declare. Anything registered behind it throws
133
+ `INVALID_BUILDER_STATE`.
134
+
135
+ **Sources.** Both factories declare the same sources. Chain `.stdin()`,
136
+ `.env()`, `.config()`, `.prompt()`, `.default()` on a flag or an argument and
137
+ let one resolution order (argv, stdin, env, config, prompt, default) do the
138
+ work. Count and key-value flags and key-value arguments are not promptable.
139
+ `.stdin()` takes `{ when, consume, trim }`; one command has one exclusive
140
+ stdin consumer unless every stdin input passes `{ consume: 'broadcast' }`. A `-`
141
+ occurrence on a collection splices the decoded buffer in at that position, so
142
+ `--tag before --tag - --tag after` over `a\nb\n` gives
143
+ `['before', 'a', 'b', 'after']`, and a variadic argument reads its tail the same
144
+ way. A `-` typed beside other occurrences with nothing piped fails with
145
+ `MISSING_STDIN`; a lone `-`, and a scalar `-`, fall through instead.
146
+ `{ trim: true }` drops one trailing line terminator from a single value, which
147
+ is what `arg.path({ mustExist: true }).stdin({ trim: true })` wants. Help names
148
+ each binding: `[stdin]`, `[stdin: '-']`, or `[stdin: when omitted]`. Stdin is
149
+ available to scalar, array, key-value, and variadic inputs; count flags cannot
150
+ read it, and key-value arguments cannot prompt.
151
+
152
+ **Provenance.** A handler receives `sources` beside `flags` and `args`, keyed
153
+ the same way, holding the stage that produced each value (`cli`, `stdin`, `env`
154
+ with its `envVar`, `config` with its `configPath`, `prompt`, `default`).
155
+ `wasExplicit(sources.flags.x)` is the predicate for "supplied rather than
156
+ defaulted"; never drop `.default()` to detect that, since it also drops
157
+ `defaultValue` from the exported schema.
158
+
159
+ **Cross-flag rules.** Put them in `.derive()`, which runs after resolution and
160
+ before the action, and return derived state to widen `ctx`.
161
+
162
+ **Diagnostics.** Values resolved through stdin, env, config, or a prompt are
163
+ redacted in validation messages and omit `details.value`; this includes stdin
164
+ selected by an explicit `-`. Only a literal CLI value is shown. The framework
165
+ cannot redact text your own code writes: a `flag.custom()` parse function's
166
+ thrown message and a Standard Schema issue message are shown verbatim, so write
167
+ them to describe the expectation rather than to interpolate the value.
168
+
169
+ **Output.** `out.log()` for results, `out.status()` for progress notes (stderr,
170
+ suppressed by `--quiet`), `out.table()` for lists, `out.json()` behind
171
+ `out.jsonMode`, `out.color`/`osc8()` for styling, `out.setExitCode()` when a
172
+ command must report normally but exit non-zero.
173
+
174
+ **Testing.** `runCommand()` from `@kjanat/dreamcli/testkit`, with `answers` for
175
+ prompts and `stat`/`mkdir` when `flag.path()` or `arg.path()` checks must run.
176
+ Assert output including trailing newlines.
177
+
178
+ ## Resource Map
179
+
180
+ - `scripts/scaffold_cli.py` — generate Bun-first starter files and tests.
181
+ - `assets/templates/*.tpl` — source templates used by the scaffolder.
182
+ - `references/pattern-cookbook.md` — snippets by topic; all type-checked.
183
+ - `references/consumer-workflow.md` — end-to-end flow from request to validation.
184
+ - `references/runtime-notes.md` — runtime and package-manager execution guidance.
185
+
186
+ ## Guardrails
187
+
188
+ - Do not modify DreamCLI core internals for consumer-app requests.
189
+ - Keep generated imports on `@kjanat/dreamcli` and `@kjanat/dreamcli/testkit`;
190
+ never reach into `#internals/*` or `dist/`.
191
+ - Preserve the typed resolution flow: argv, stdin, env, config, prompt, default.
192
+ - Keep stdout machine-clean: progress and status go to stderr via `out.status()`,
193
+ never interleaved with `out.json()`.
194
+ - `.default(cmd)` is the root surface and is not routable by name; add
195
+ `{ route: true }` when a user expects `mycli <name>` to work too.
196
+ - Prefer Bun commands first; include npm/tsx and Deno alternatives when asked.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "CLI Creation"
3
+ short_description: "Build typed DreamCLI consumer CLIs quickly"
4
+ default_prompt: "Use $cli-creation to scaffold a Bun-first DreamCLI CLI with tests."
@@ -0,0 +1,20 @@
1
+ import { partyStart } from '__ENTRY_FILE__';
2
+ import { runCommand } from '@kjanat/dreamcli/testkit';
3
+ import { describe, expect, it } from 'bun:test';
4
+
5
+ describe('party start command', () => {
6
+ it('applies sparkle middleware when --sparkle is set', async () => {
7
+ const result = await runCommand(partyStart, ['--theme', 'midnight', '--sparkle']);
8
+
9
+ expect(result.exitCode).toBe(0);
10
+ expect(result.stdout).toEqual(['✨ Party started with midnight theme! ✨\n']);
11
+ expect(result.stderr).toEqual([]);
12
+ });
13
+
14
+ it('renders help text', async () => {
15
+ const result = await runCommand(partyStart, ['--help']);
16
+
17
+ expect(result.exitCode).toBe(0);
18
+ expect(result.stdout.join('')).toContain('Start the pony party');
19
+ });
20
+ });
@@ -0,0 +1,20 @@
1
+ import { partyStart } from '__ENTRY_FILE__';
2
+ import { runCommand } from '@kjanat/dreamcli/testkit';
3
+ import { describe, expect, it } from 'vitest';
4
+
5
+ describe('party start command', () => {
6
+ it('applies sparkle middleware when --sparkle is set', async () => {
7
+ const result = await runCommand(partyStart, ['--theme', 'midnight', '--sparkle']);
8
+
9
+ expect(result.exitCode).toBe(0);
10
+ expect(result.stdout).toEqual(['✨ Party started with midnight theme! ✨\n']);
11
+ expect(result.stderr).toEqual([]);
12
+ });
13
+
14
+ it('renders help text', async () => {
15
+ const result = await runCommand(partyStart, ['--help']);
16
+
17
+ expect(result.exitCode).toBe(0);
18
+ expect(result.stdout.join('')).toContain('Start the pony party');
19
+ });
20
+ });
@@ -0,0 +1,89 @@
1
+ #!/usr/bin/env bun
2
+ /**
3
+ * __CLI_NAME__ - multi-command DreamCLI starter (pony party edition).
4
+ *
5
+ * Bun:
6
+ * bun __CLI_NAME__.ts snack cupcake --count 3
7
+ * bun __CLI_NAME__.ts story "rainbow heist" --mood legendary --sparkle
8
+ * bun __CLI_NAME__.ts party start --theme midnight
9
+ * bun __CLI_NAME__.ts --help
10
+ *
11
+ * npm/tsx:
12
+ * npx tsx __CLI_NAME__.ts party playlist --genre chaos
13
+ *
14
+ * Deno:
15
+ * deno run -A __CLI_NAME__.ts snack donut --count 2
16
+ */
17
+
18
+ import { arg, cli, command, flag, group, middleware } from '@kjanat/dreamcli';
19
+
20
+ const sparkle = middleware<{ sparkle: (message: string) => string }>(async ({ flags, next }) => {
21
+ const sparkleEnabled = flags.sparkle === true;
22
+ return next({
23
+ sparkle: (message: string) => (sparkleEnabled ? `✨ ${message} ✨` : message),
24
+ });
25
+ });
26
+
27
+ const sparkleFlag = () => flag.boolean().alias('s').env('SPARKLE').describe('Add extra sparkle');
28
+
29
+ export const snack = command('snack')
30
+ .description('Serve snacks to the crew')
31
+ .arg('treat', arg.string().default('cupcake').describe('Snack to serve'))
32
+ .flag('count', flag.number().default(1).alias('c').describe('How many snacks'))
33
+ .flag('sparkle', sparkleFlag())
34
+ .middleware(sparkle)
35
+ .action(({ args, flags, ctx, out }) => {
36
+ const { treat } = args;
37
+ const { count } = flags;
38
+ out.log(ctx.sparkle(`Serving ${count} ${treat}(s)!`));
39
+ });
40
+
41
+ export const story = command('story')
42
+ .description('Tell a dramatic story')
43
+ .arg('topic', arg.string().default('the great cupcake rescue').describe('Story topic'))
44
+ .flag('mood', flag.enum(['calm', 'chaos', 'legendary'])
45
+ .prompt({ kind: 'select', message: 'Set the mood!' })
46
+ .default('calm').describe('Story mood'))
47
+ .flag('sparkle', sparkleFlag())
48
+ .middleware(sparkle)
49
+ .action(({ args, flags, ctx, out }) => {
50
+ const { topic } = args;
51
+ const { mood } = flags;
52
+ out.log(ctx.sparkle(`Story time: ${topic} (${mood})`));
53
+ out.log(ctx.sparkle('Dramatic glitter intensifies'));
54
+ });
55
+
56
+ export const partyStart = command('start')
57
+ .description('Start the pony party')
58
+ .flag('theme', flag.enum(['rainbow', 'midnight', 'glitter']).default('rainbow').describe('Party theme'))
59
+ .flag('sparkle', sparkleFlag())
60
+ .middleware(sparkle)
61
+ .action(({ flags, ctx, out }) => {
62
+ out.log(ctx.sparkle(`Party started with ${flags.theme} theme!`));
63
+ });
64
+
65
+ export const partyPlaylist = command('playlist')
66
+ .description('Pick a party playlist vibe')
67
+ .flag('genre', flag.enum(['pop', 'ballad', 'chaos']).default('pop').describe('Playlist genre'))
68
+ .flag('sparkle', sparkleFlag())
69
+ .middleware(sparkle)
70
+ .action(({ flags, ctx, out }) => {
71
+ out.log(ctx.sparkle(`Now playing: ${flags.genre}`));
72
+ });
73
+
74
+ export const party = group('party')
75
+ .description('Party controls')
76
+ .command(partyStart)
77
+ .command(partyPlaylist);
78
+
79
+ export const app = cli('__CLI_NAME__')
80
+ .version('0.1.0')
81
+ .description('Fun DreamCLI starter app')
82
+ .command(snack)
83
+ .command(story)
84
+ .command(party)
85
+ .completions();
86
+
87
+ if (import.meta.main) {
88
+ app.run();
89
+ }
@@ -0,0 +1,29 @@
1
+ import { hello } from '__ENTRY_FILE__';
2
+ import { runCommand } from '@kjanat/dreamcli/testkit';
3
+ import { describe, expect, it } from 'bun:test';
4
+
5
+ describe('hello command', () => {
6
+ it('prints sparkly greeting when --sparkle is set', async () => {
7
+ const result = await runCommand(hello, ['Twilight', '--sparkle', '--times', '2']);
8
+
9
+ expect(result.exitCode).toBe(0);
10
+ expect(result.stdout).toEqual(['✨ Hello, Twilight! ✨\n', '✨ Hello, Twilight! ✨\n']);
11
+ // out.status() writes to stderr so stdout stays pipe-clean.
12
+ expect(result.stderr).toEqual(['Greeted Twilight 2 time(s)\n']);
13
+ });
14
+
15
+ it('suppresses status output with --quiet', async () => {
16
+ const result = await runCommand(hello, ['Twilight', '--quiet']);
17
+
18
+ expect(result.exitCode).toBe(0);
19
+ expect(result.stdout).toEqual(['Hello, Twilight!\n']);
20
+ expect(result.stderr).toEqual([]);
21
+ });
22
+
23
+ it('renders help text', async () => {
24
+ const result = await runCommand(hello, ['--help']);
25
+
26
+ expect(result.exitCode).toBe(0);
27
+ expect(result.stdout.join('')).toContain('Say hello with optional sparkle');
28
+ });
29
+ });
@@ -0,0 +1,29 @@
1
+ import { hello } from '__ENTRY_FILE__';
2
+ import { runCommand } from '@kjanat/dreamcli/testkit';
3
+ import { describe, expect, it } from 'vitest';
4
+
5
+ describe('hello command', () => {
6
+ it('prints sparkly greeting when --sparkle is set', async () => {
7
+ const result = await runCommand(hello, ['Twilight', '--sparkle', '--times', '2']);
8
+
9
+ expect(result.exitCode).toBe(0);
10
+ expect(result.stdout).toEqual(['✨ Hello, Twilight! ✨\n', '✨ Hello, Twilight! ✨\n']);
11
+ // out.status() writes to stderr so stdout stays pipe-clean.
12
+ expect(result.stderr).toEqual(['Greeted Twilight 2 time(s)\n']);
13
+ });
14
+
15
+ it('suppresses status output with --quiet', async () => {
16
+ const result = await runCommand(hello, ['Twilight', '--quiet']);
17
+
18
+ expect(result.exitCode).toBe(0);
19
+ expect(result.stdout).toEqual(['Hello, Twilight!\n']);
20
+ expect(result.stderr).toEqual([]);
21
+ });
22
+
23
+ it('renders help text', async () => {
24
+ const result = await runCommand(hello, ['--help']);
25
+
26
+ expect(result.exitCode).toBe(0);
27
+ expect(result.stdout.join('')).toContain('Say hello with optional sparkle');
28
+ });
29
+ });
@@ -0,0 +1,47 @@
1
+ #!/usr/bin/env bun
2
+ /**
3
+ * __CLI_NAME__ - hello-world DreamCLI starter.
4
+ *
5
+ * Bun:
6
+ * bun __CLI_NAME__.ts
7
+ * bun __CLI_NAME__.ts Twilight --sparkle --times 2
8
+ * bun __CLI_NAME__.ts --help
9
+ *
10
+ * npm/tsx:
11
+ * npx tsx __CLI_NAME__.ts Twilight --sparkle --times 2
12
+ *
13
+ * Deno:
14
+ * deno run -A __CLI_NAME__.ts Twilight --sparkle --times 2
15
+ */
16
+
17
+ import { arg, cli, command, flag, middleware } from '@kjanat/dreamcli';
18
+
19
+ const sparkle = middleware<{ sparkle: (message: string) => string }>(async ({ flags, next }) => {
20
+ const sparkleEnabled = flags.sparkle === true;
21
+ return next({
22
+ sparkle: (message: string) => (sparkleEnabled ? `✨ ${message} ✨` : message),
23
+ });
24
+ });
25
+
26
+ export const hello = command('hello')
27
+ .description('Say hello with optional sparkle')
28
+ .example(({ name }) => `${name} Twilight --sparkle --times 2`, 'Sparkly double greeting')
29
+ .arg('name', arg.string().default('World').describe('Who to greet'))
30
+ .flag('sparkle', flag.boolean().alias('s').env('SPARKLE').describe('Add sparkles'))
31
+ // Constraints are enforced at every source, so the action needs no clamping.
32
+ .flag('times', flag.number({ int: true, min: 0, max: 100 }).default(1).alias('n').describe('Repeat count'))
33
+ .middleware(sparkle)
34
+ .action(({ args, flags, ctx, out }) => {
35
+ for (let i = 0; i < flags.times; i++) {
36
+ out.log(ctx.sparkle(`Hello, ${args.name}!`));
37
+ }
38
+
39
+ // stderr, and silenced by --quiet: keeps stdout pipe-clean.
40
+ out.status(`Greeted ${args.name} ${flags.times} time(s)`);
41
+ });
42
+
43
+ export const app = cli('__CLI_NAME__').default(hello);
44
+
45
+ if (import.meta.main) {
46
+ app.run();
47
+ }
@@ -0,0 +1,65 @@
1
+ # Consumer Workflow
2
+
3
+ ## Goal
4
+
5
+ Build a consumer-facing CLI app with DreamCLI 3.x, starting from a working
6
+ template and ending with validated behavior.
7
+
8
+ ## Inputs to confirm
9
+
10
+ - CLI name (`--name`).
11
+ - Surface shape (`single` or `multi`).
12
+ - Whether tests should be skipped (`--no-test`).
13
+ - Runtime the user runs on (Bun, npm/tsx, Deno).
14
+ - Whether the CLI needs machine-readable output, config files, or prompts —
15
+ each adds declarations to the schema rather than code to the action.
16
+
17
+ ## Implementation flow
18
+
19
+ 1. Scaffold starter files.
20
+
21
+ ```bash
22
+ python scripts/scaffold_cli.py --name mycli --mode single --out .
23
+ ```
24
+
25
+ The scaffolder detects the package manager and Vitest usage to choose either
26
+ a `bun:test` or Vitest starter test template.
27
+
28
+ 2. Shape the command surface.
29
+
30
+ - `.description(...)` on every command; it is what `--help` shows.
31
+ - Function-form `.example()` so examples print the real program name.
32
+ - Typed `.arg(...)` and `.flag(...)` declarations before any logic.
33
+ - A single root command belongs in `.default(cmd)`; add `{ route: true }`
34
+ only if `mycli <name>` should also work.
35
+
36
+ 3. Declare where values come from.
37
+
38
+ - `.env('...')`, `.config('...')`, `.prompt(...)`, `.default(...)`.
39
+ - Constraints (`{ int: true, min: 1 }`, `{ nonEmpty: true }`) or a Standard
40
+ Schema in `flag.custom(...)` instead of validation code in the action.
41
+ - Cross-flag rules go in `.derive()`, not the action.
42
+
43
+ 4. Choose output behavior deliberately.
44
+
45
+ - `out.log()` for the result a user pipes.
46
+ - `out.status()` for progress notes — stderr, silenced by `--quiet`.
47
+ - `out.table()` for list-shaped data.
48
+ - `out.json(data)` behind `if (out.jsonMode)`, never mixed with prose.
49
+ - `out.setExitCode(code)` for check/status commands that must still print.
50
+
51
+ 5. Validate behavior.
52
+
53
+ ```bash
54
+ bun ./mycli.ts --help
55
+ bun ./mycli.ts --json | jq . # stdout must parse
56
+ bun test ./mycli.test.ts
57
+ ```
58
+
59
+ ## Done criteria
60
+
61
+ - `--help` renders expected command, flag, and example text.
62
+ - Happy-path execution exits `0`; failure paths exit non-zero with a `suggest`.
63
+ - `--json` stdout parses on its own — no human text, no progress lines.
64
+ - `--quiet` silences status output without hiding warnings or errors.
65
+ - Generated or custom tests pass, including trailing-newline assertions.