@kjanat/dreamcli 4.0.0-rc.3 → 4.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 (212) hide show
  1. package/README.md +5 -7
  2. package/dist/{runtime/adapter.d.mts → adapter-D0hbBNVB.d.mts} +2 -4
  3. package/dist/completion-D4mz6axB.mjs +6 -0
  4. package/dist/completion.d.mts +90 -0
  5. package/dist/completion.mjs +1 -0
  6. package/dist/config-B9ddC-Kb.mjs +1 -0
  7. package/dist/config.d.mts +2 -0
  8. package/dist/config.mjs +1 -0
  9. package/dist/core-Cp2w8vRq.mjs +17 -0
  10. package/dist/index-BziI2aKc.d.mts +5440 -0
  11. package/dist/index-DOfClfYR.d.mts +370 -0
  12. package/dist/index-DWsnGZlx.d.mts +831 -0
  13. package/dist/{core/cli/index.d.mts → index-DXROeDPC.d.mts} +116 -57
  14. package/dist/index-DndPmT8J.d.mts +275 -0
  15. package/dist/{core/json-schema/index.d.mts → index-DyoaS234.d.mts} +43 -34
  16. package/dist/index.d.mts +190 -41
  17. package/dist/index.mjs +1 -26
  18. package/dist/json-schema-C9SzZ7jY.mjs +52 -0
  19. package/dist/json-schema.d.mts +2 -0
  20. package/dist/json-schema.mjs +1 -0
  21. package/dist/package-json-BgE9YjjQ.mjs +3 -0
  22. package/dist/prompt.d.mts +48 -0
  23. package/dist/prompt.mjs +1 -0
  24. package/dist/rolldown-runtime-G4Kt5YOX.mjs +1 -0
  25. package/dist/runtime.d.mts +2 -6
  26. package/dist/runtime.mjs +1 -6
  27. package/dist/terminal-C8KTXjv5.mjs +6 -0
  28. package/dist/test-prompter-v__jT2yG.mjs +1 -0
  29. package/dist/testkit.d.mts +54 -6
  30. package/dist/testkit.mjs +1 -5
  31. package/dist/version.mjs +1 -7
  32. package/dreamcli.schema.json +697 -538
  33. package/package.json +29 -7
  34. package/skills/cli-creation/SKILL.md +16 -11
  35. package/CHANGELOG.md +0 -1116
  36. package/dist/core/cli/builtins.d.mts +0 -117
  37. package/dist/core/cli/builtins.mjs +0 -135
  38. package/dist/core/cli/compiled.d.mts +0 -66
  39. package/dist/core/cli/compiled.mjs +0 -76
  40. package/dist/core/cli/dispatch.d.mts +0 -115
  41. package/dist/core/cli/dispatch.mjs +0 -205
  42. package/dist/core/cli/help-links.d.mts +0 -27
  43. package/dist/core/cli/help-links.mjs +0 -41
  44. package/dist/core/cli/index.mjs +0 -1271
  45. package/dist/core/cli/planner.d.mts +0 -174
  46. package/dist/core/cli/planner.mjs +0 -323
  47. package/dist/core/cli/plugin.d.mts +0 -94
  48. package/dist/core/cli/plugin.mjs +0 -41
  49. package/dist/core/cli/propagate.d.mts +0 -39
  50. package/dist/core/cli/propagate.mjs +0 -57
  51. package/dist/core/cli/reserved-flags.d.mts +0 -19
  52. package/dist/core/cli/reserved-flags.mjs +0 -158
  53. package/dist/core/cli/root-help.d.mts +0 -53
  54. package/dist/core/cli/root-help.mjs +0 -221
  55. package/dist/core/cli/root-output-flags.d.mts +0 -74
  56. package/dist/core/cli/root-output-flags.mjs +0 -169
  57. package/dist/core/cli/root-surface.d.mts +0 -64
  58. package/dist/core/cli/root-surface.mjs +0 -28
  59. package/dist/core/cli/runtime-preflight.d.mts +0 -213
  60. package/dist/core/cli/runtime-preflight.mjs +0 -221
  61. package/dist/core/completion/index.d.mts +0 -76
  62. package/dist/core/completion/index.mjs +0 -90
  63. package/dist/core/completion/shells/bash.d.mts +0 -23
  64. package/dist/core/completion/shells/bash.mjs +0 -312
  65. package/dist/core/completion/shells/fish.d.mts +0 -19
  66. package/dist/core/completion/shells/fish.mjs +0 -164
  67. package/dist/core/completion/shells/powershell.d.mts +0 -13
  68. package/dist/core/completion/shells/powershell.mjs +0 -360
  69. package/dist/core/completion/shells/shared.d.mts +0 -164
  70. package/dist/core/completion/shells/shared.mjs +0 -147
  71. package/dist/core/completion/shells/zsh.d.mts +0 -23
  72. package/dist/core/completion/shells/zsh.mjs +0 -256
  73. package/dist/core/config/index.d.mts +0 -191
  74. package/dist/core/config/index.mjs +0 -285
  75. package/dist/core/config/package-json.d.mts +0 -179
  76. package/dist/core/config/package-json.mjs +0 -353
  77. package/dist/core/errors/index.d.mts +0 -125
  78. package/dist/core/errors/index.mjs +0 -87
  79. package/dist/core/execution/index.d.mts +0 -61
  80. package/dist/core/execution/index.mjs +0 -220
  81. package/dist/core/help/ansi.d.mts +0 -84
  82. package/dist/core/help/ansi.mjs +0 -121
  83. package/dist/core/help/index.d.mts +0 -149
  84. package/dist/core/help/index.mjs +0 -418
  85. package/dist/core/help/theme.d.mts +0 -86
  86. package/dist/core/help/theme.mjs +0 -69
  87. package/dist/core/json-schema/index.mjs +0 -1008
  88. package/dist/core/json-schema/meta-descriptions.generated.d.mts +0 -274
  89. package/dist/core/json-schema/meta-descriptions.generated.mjs +0 -136
  90. package/dist/core/output/activity.d.mts +0 -193
  91. package/dist/core/output/activity.mjs +0 -452
  92. package/dist/core/output/bind.d.mts +0 -37
  93. package/dist/core/output/bind.mjs +0 -56
  94. package/dist/core/output/contracts.d.mts +0 -82
  95. package/dist/core/output/contracts.mjs +0 -57
  96. package/dist/core/output/display-value.d.mts +0 -19
  97. package/dist/core/output/display-value.mjs +0 -32
  98. package/dist/core/output/index.d.mts +0 -344
  99. package/dist/core/output/index.mjs +0 -514
  100. package/dist/core/output/renderers.d.mts +0 -45
  101. package/dist/core/output/renderers.mjs +0 -46
  102. package/dist/core/output/writer.d.mts +0 -39
  103. package/dist/core/output/writer.mjs +0 -12
  104. package/dist/core/parse/index.d.mts +0 -178
  105. package/dist/core/parse/index.mjs +0 -850
  106. package/dist/core/parse/occurrences.d.mts +0 -90
  107. package/dist/core/parse/occurrences.mjs +0 -114
  108. package/dist/core/prompt/index.d.mts +0 -213
  109. package/dist/core/prompt/index.mjs +0 -348
  110. package/dist/core/read-flags/index.d.mts +0 -150
  111. package/dist/core/read-flags/index.mjs +0 -217
  112. package/dist/core/resolve/args.d.mts +0 -39
  113. package/dist/core/resolve/args.mjs +0 -182
  114. package/dist/core/resolve/coerce.d.mts +0 -79
  115. package/dist/core/resolve/coerce.mjs +0 -900
  116. package/dist/core/resolve/config.d.mts +0 -10
  117. package/dist/core/resolve/config.mjs +0 -19
  118. package/dist/core/resolve/contracts.d.mts +0 -146
  119. package/dist/core/resolve/errors.d.mts +0 -10
  120. package/dist/core/resolve/errors.mjs +0 -148
  121. package/dist/core/resolve/flags.d.mts +0 -74
  122. package/dist/core/resolve/flags.mjs +0 -246
  123. package/dist/core/resolve/index.d.mts +0 -44
  124. package/dist/core/resolve/index.mjs +0 -123
  125. package/dist/core/resolve/path-checks.d.mts +0 -48
  126. package/dist/core/resolve/path-checks.mjs +0 -102
  127. package/dist/core/resolve/redaction.d.mts +0 -13
  128. package/dist/core/resolve/redaction.mjs +0 -14
  129. package/dist/core/resolve/stages.d.mts +0 -86
  130. package/dist/core/resolve/stages.mjs +0 -170
  131. package/dist/core/resolve/standard.d.mts +0 -26
  132. package/dist/core/resolve/standard.mjs +0 -212
  133. package/dist/core/schema/activity.d.mts +0 -189
  134. package/dist/core/schema/arg.d.mts +0 -1461
  135. package/dist/core/schema/arg.mjs +0 -1139
  136. package/dist/core/schema/brand.d.mts +0 -17
  137. package/dist/core/schema/cardinality.d.mts +0 -302
  138. package/dist/core/schema/cardinality.mjs +0 -514
  139. package/dist/core/schema/command.d.mts +0 -1132
  140. package/dist/core/schema/command.mjs +0 -999
  141. package/dist/core/schema/flag.d.mts +0 -1495
  142. package/dist/core/schema/flag.mjs +0 -1207
  143. package/dist/core/schema/index.d.mts +0 -15
  144. package/dist/core/schema/index.mjs +0 -10
  145. package/dist/core/schema/middleware.d.mts +0 -129
  146. package/dist/core/schema/middleware.mjs +0 -41
  147. package/dist/core/schema/number-constraints.d.mts +0 -96
  148. package/dist/core/schema/number-constraints.mjs +0 -60
  149. package/dist/core/schema/prompt.d.mts +0 -135
  150. package/dist/core/schema/provenance.d.mts +0 -99
  151. package/dist/core/schema/provenance.mjs +0 -28
  152. package/dist/core/schema/run.d.mts +0 -211
  153. package/dist/core/schema/source.d.mts +0 -180
  154. package/dist/core/schema/source.mjs +0 -206
  155. package/dist/core/schema/standard.d.mts +0 -100
  156. package/dist/core/schema/standard.mjs +0 -15
  157. package/dist/core/schema/stdin.d.mts +0 -97
  158. package/dist/core/schema/stdin.mjs +0 -91
  159. package/dist/core/schema/string-constraints.d.mts +0 -108
  160. package/dist/core/schema/string-constraints.mjs +0 -86
  161. package/dist/core/schema/value-parsers.d.mts +0 -150
  162. package/dist/core/schema/value-parsers.mjs +0 -160
  163. package/dist/core/schema/value.d.mts +0 -243
  164. package/dist/core/schema/value.mjs +0 -573
  165. package/dist/core/testkit/index.d.mts +0 -63
  166. package/dist/core/testkit/index.mjs +0 -102
  167. package/dist/runtime/adapter.mjs +0 -92
  168. package/dist/runtime/auto.d.mts +0 -25
  169. package/dist/runtime/auto.mjs +0 -45
  170. package/dist/runtime/deno.d.mts +0 -99
  171. package/dist/runtime/deno.mjs +0 -265
  172. package/dist/runtime/detect.d.mts +0 -86
  173. package/dist/runtime/detect.mjs +0 -45
  174. package/dist/runtime/index.d.mts +0 -6
  175. package/dist/runtime/node.d.mts +0 -71
  176. package/dist/runtime/node.mjs +0 -228
  177. package/dist/runtime/paths.d.mts +0 -31
  178. package/dist/runtime/paths.mjs +0 -48
  179. package/dist/strings.d.mts +0 -27
  180. package/dist/strings.mjs +0 -22
  181. package/examples/basic.ts +0 -37
  182. package/examples/flag-types.ts +0 -79
  183. package/examples/gh/package.json +0 -45
  184. package/examples/gh/src/commands/auth.ts +0 -66
  185. package/examples/gh/src/commands/issue.ts +0 -120
  186. package/examples/gh/src/commands/pr.ts +0 -125
  187. package/examples/gh/src/data/issues.yaml +0 -5
  188. package/examples/gh/src/data/issues.yaml.d.ts +0 -17
  189. package/examples/gh/src/data/pull-requests.yaml +0 -7
  190. package/examples/gh/src/data/pull-requests.yaml.d.ts +0 -18
  191. package/examples/gh/src/docs.ts +0 -11
  192. package/examples/gh/src/lib/auth.ts +0 -37
  193. package/examples/gh/src/lib/utils.ts +0 -17
  194. package/examples/gh/src/main.test.ts +0 -307
  195. package/examples/gh/src/main.ts +0 -46
  196. package/examples/help-config.ts +0 -43
  197. package/examples/interactive.ts +0 -67
  198. package/examples/json-mode.ts +0 -95
  199. package/examples/middleware.ts +0 -71
  200. package/examples/multi-command.ts +0 -66
  201. package/examples/output-extras.ts +0 -46
  202. package/examples/parser-control.ts +0 -40
  203. package/examples/pwsh-demo/README.md +0 -40
  204. package/examples/pwsh-demo/package.json +0 -41
  205. package/examples/pwsh-demo/pwsh-demo.cmd +0 -3
  206. package/examples/pwsh-demo/smoke-powershell.ps1 +0 -218
  207. package/examples/pwsh-demo/src/main.test.ts +0 -45
  208. package/examples/pwsh-demo/src/main.ts +0 -140
  209. package/examples/spinner-progress.ts +0 -49
  210. package/examples/standard-schema.ts +0 -45
  211. package/examples/testing.ts +0 -147
  212. package/examples/transport-launcher.ts +0 -85
@@ -1,307 +0,0 @@
1
- /**
2
- * Smoke tests for the walkthrough `gh` example.
3
- *
4
- * @module
5
- */
6
- /// <reference types="bun" />
7
-
8
- import { describe, expect, it } from 'bun:test';
9
-
10
- import { runCommand } from '@kjanat/dreamcli/testkit';
11
-
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';
16
-
17
- const token = 'ghp_test_token_1234';
18
-
19
- // === auth login
20
-
21
- describe('gh example — auth login', () => {
22
- it('logs the redacted token in human mode', async () => {
23
- const result = await runCommand(authLogin, [], {
24
- env: { GH_TOKEN: token },
25
- });
26
-
27
- expect(result.exitCode).toBe(0);
28
- expect(result.stdout).toEqual([
29
- 'Logged in with token ghp_test...1234\n',
30
- 'Token would be saved to ~/.config/gh/config.json\n',
31
- ]);
32
- });
33
-
34
- it('returns structured JSON in json mode', async () => {
35
- const result = await runCommand(authLogin, [], {
36
- env: { GH_TOKEN: token },
37
- jsonMode: true,
38
- });
39
-
40
- expect(result.exitCode).toBe(0);
41
- expect(JSON.parse(result.stdout[0] ?? '')).toEqual({
42
- host: 'github.com',
43
- token: 'ghp_test...1234',
44
- storedAt: '~/.config/gh/config.json',
45
- });
46
- });
47
- });
48
-
49
- // === auth status
50
-
51
- describe('gh example — auth status', () => {
52
- it('resolves GH_TOKEN through the command schema', async () => {
53
- const result = await runCommand(authStatus, [], {
54
- env: { GH_TOKEN: token },
55
- });
56
-
57
- expect(result.exitCode).toBe(0);
58
- expect(result.stdout).toEqual(['github.com\n', 'Logged in with token ghp_test...1234\n']);
59
- });
60
-
61
- it('warns when no token resolves', async () => {
62
- const result = await runCommand(authStatus, []);
63
-
64
- expect(result.exitCode).toBe(0);
65
- expect(result.stderr).toEqual(['Not logged in. Run `gh auth login`.\n']);
66
- });
67
-
68
- it('returns structured JSON in json mode', async () => {
69
- const result = await runCommand(authStatus, [], {
70
- env: { GH_TOKEN: token },
71
- jsonMode: true,
72
- });
73
-
74
- expect(result.exitCode).toBe(0);
75
- expect(JSON.parse(result.stdout[0] ?? '')).toEqual({
76
- authenticated: true,
77
- host: 'github.com',
78
- token: 'ghp_test...1234',
79
- });
80
- });
81
- });
82
-
83
- // === pr list
84
-
85
- describe('gh example — pr list', () => {
86
- it('filters pull requests and emits JSON rows', async () => {
87
- const result = await runCommand(prList, ['--label', 'bug', '--limit', '2'], {
88
- env: { GH_TOKEN: token },
89
- jsonMode: true,
90
- });
91
-
92
- expect(result.exitCode).toBe(0);
93
- expect(JSON.parse(result.stdout[0] ?? '')).toEqual([
94
- { '#': 137, title: 'Fix date parsing in Safari', state: 'open', author: 'dave' },
95
- { '#': 141, title: 'Fix OAuth redirect loop', state: 'open', author: 'bob' },
96
- ]);
97
- });
98
-
99
- it('requires authentication before listing', async () => {
100
- const result = await runCommand(prList, []);
101
-
102
- expect(result.exitCode).toBe(1);
103
- expect(result.error?.code).toBe('AUTH_REQUIRED');
104
- expect(result.stderr.join('')).toContain('Authentication required');
105
- });
106
- });
107
-
108
- // === pr view
109
-
110
- describe('gh example — pr view', () => {
111
- it('renders the human summary by default', async () => {
112
- const result = await runCommand(prView, ['142'], {
113
- env: { GH_TOKEN: token },
114
- });
115
-
116
- expect(result.exitCode).toBe(0);
117
- expect(result.stdout).toEqual([
118
- '#142 Add dark mode toggle\nState: open Author: alice Draft: false\nLabels: enhancement, ui\n',
119
- ]);
120
- });
121
-
122
- it('renders only JSON in json mode', async () => {
123
- const result = await runCommand(prView, ['142'], {
124
- env: { GH_TOKEN: token },
125
- jsonMode: true,
126
- });
127
-
128
- expect(result.exitCode).toBe(0);
129
- expect(result.stderr).toEqual([]);
130
- expect(JSON.parse(result.stdout[0] ?? '')).toEqual({
131
- number: 142,
132
- title: 'Add dark mode toggle',
133
- state: 'open',
134
- author: 'alice',
135
- labels: ['enhancement', 'ui'],
136
- draft: false,
137
- });
138
- });
139
-
140
- it('returns a structured not-found error', async () => {
141
- const result = await runCommand(prView, ['999'], {
142
- env: { GH_TOKEN: token },
143
- });
144
-
145
- expect(result.exitCode).toBe(1);
146
- expect(result.error?.code).toBe('NOT_FOUND');
147
- expect(result.stderr.join('')).toContain('Pull request #999 not found');
148
- });
149
- });
150
-
151
- // === pr create
152
-
153
- describe('gh example — pr create', () => {
154
- it('creates a draft pull request in human mode', async () => {
155
- const result = await runCommand(
156
- prCreate,
157
- ['--title', 'Fix login', '--body', 'Correct callback URL', '--draft'],
158
- {
159
- env: { GH_TOKEN: token },
160
- },
161
- );
162
-
163
- expect(result.exitCode).toBe(0);
164
- expect(result.stdout).toEqual([
165
- '#143 Fix login\n',
166
- 'Marked as draft\n',
167
- 'https://github.com/you/repo/pull/143\n',
168
- ]);
169
- expect(result.activity).toEqual([
170
- { type: 'spinner:start', text: 'Creating pull request...' },
171
- { type: 'spinner:succeed', text: 'Pull request created' },
172
- ]);
173
- });
174
-
175
- it('emits only JSON in json mode', async () => {
176
- const result = await runCommand(
177
- prCreate,
178
- ['--title', 'Fix login', '--body', 'Correct callback URL'],
179
- {
180
- env: { GH_TOKEN: token },
181
- jsonMode: true,
182
- },
183
- );
184
-
185
- expect(result.exitCode).toBe(0);
186
- expect(result.stderr).toEqual([]);
187
- expect(JSON.parse(result.stdout[0] ?? '')).toEqual({
188
- number: 143,
189
- title: 'Fix login',
190
- url: 'https://github.com/you/repo/pull/143',
191
- });
192
- });
193
- });
194
-
195
- // === issue list
196
-
197
- describe('gh example — issue list', () => {
198
- it('applies the state filter before rendering', async () => {
199
- const result = await runCommand(issueList, ['--state', 'closed'], {
200
- env: { GH_TOKEN: token },
201
- jsonMode: true,
202
- });
203
-
204
- expect(result.exitCode).toBe(0);
205
- expect(JSON.parse(result.stdout[0] ?? '')).toEqual([
206
- { '#': 87, title: 'Typo in README', state: 'closed', author: 'grace' },
207
- ]);
208
- });
209
-
210
- it('filters issues and emits JSON rows', async () => {
211
- const result = await runCommand(issueList, ['--state', 'all', '--label', 'bug'], {
212
- env: { GH_TOKEN: token },
213
- jsonMode: true,
214
- });
215
-
216
- expect(result.exitCode).toBe(0);
217
- expect(JSON.parse(result.stdout[0] ?? '')).toEqual([
218
- { '#': 86, title: 'Dark mode colors wrong', state: 'open', author: 'alice' },
219
- { '#': 89, title: 'Login fails on Firefox', state: 'open', author: 'eve' },
220
- ]);
221
- });
222
- });
223
-
224
- // === issue triage
225
-
226
- describe('gh example — issue triage', () => {
227
- it('guides backlog triage with conditional prompts', async () => {
228
- const result = await runCommand(issueTriage, ['89', '--decision', 'backlog'], {
229
- env: { GH_TOKEN: token },
230
- answers: [['bug', 'ui']],
231
- });
232
-
233
- expect(result.exitCode).toBe(0);
234
- expect(result.stdout).toEqual([
235
- '#89 Login fails on Firefox\n',
236
- 'Status: open (backlog)\n',
237
- 'Labels: bug, ui\n',
238
- ]);
239
- });
240
-
241
- it('switches to the close branch and returns structured JSON', async () => {
242
- const result = await runCommand(issueTriage, ['89', '--decision', 'close'], {
243
- env: { GH_TOKEN: token },
244
- answers: [true],
245
- jsonMode: true,
246
- });
247
-
248
- expect(result.exitCode).toBe(0);
249
- expect(result.stderr).toEqual([]);
250
- expect(JSON.parse(result.stdout[0] ?? '')).toEqual({
251
- number: 89,
252
- title: 'Login fails on Firefox',
253
- decision: 'close',
254
- state: 'closed',
255
- labels: ['bug'],
256
- commented: true,
257
- });
258
- });
259
-
260
- it('shows the close branch in human mode', async () => {
261
- const result = await runCommand(issueTriage, ['89', '--decision', 'close'], {
262
- env: { GH_TOKEN: token },
263
- answers: [true],
264
- });
265
-
266
- expect(result.exitCode).toBe(0);
267
- expect(result.stdout).toEqual([
268
- '#89 Login fails on Firefox\n',
269
- 'Status: closed\n',
270
- 'Would post a follow-up comment\n',
271
- ]);
272
- });
273
-
274
- it('fails non-interactively when the required decision is missing', async () => {
275
- const result = await runCommand(issueTriage, ['89'], {
276
- env: { GH_TOKEN: token },
277
- });
278
-
279
- expect(result.exitCode).toBe(2);
280
- expect(result.error?.code).toBe('REQUIRED_FLAG');
281
- expect(result.stderr.join('')).toContain('Missing required flag --decision');
282
- });
283
-
284
- it('returns a structured not-found error', async () => {
285
- const result = await runCommand(issueTriage, ['999', '--decision', 'backlog'], {
286
- env: { GH_TOKEN: token },
287
- });
288
-
289
- expect(result.exitCode).toBe(1);
290
- expect(result.error?.code).toBe('NOT_FOUND');
291
- expect(result.stderr.join('')).toContain('Issue #999 not found');
292
- });
293
- });
294
-
295
- // === utils
296
-
297
- describe('gh example — utils', () => {
298
- it('normalizes numeric limits', () => {
299
- expect(normalizeLimit(4.8)).toBe(4);
300
- expect(normalizeLimit(0)).toBe(1);
301
- expect(normalizeLimit(Number.POSITIVE_INFINITY)).toBe(10);
302
- });
303
-
304
- it('sleep resolves', async () => {
305
- expect(await sleep(0)).toBeUndefined();
306
- });
307
- });
@@ -1,46 +0,0 @@
1
- #!/usr/bin/env bun
2
- // oxlint-disable no-unused-vars | CLIBuilder is used for type inference of the JSDoc comments
3
- // deno-lint-ignore-file no-unused-vars
4
- /**
5
- * Walkthrough example package entrypoint for a miniature `gh` clone.
6
- *
7
- * Usage:
8
- * GH_TOKEN=ghp_abc123 bun --cwd=examples/gh src/main.ts pr list
9
- * GH_TOKEN=ghp_abc123 bun --cwd=examples/gh src/main.ts pr list --state all --json
10
- * GH_TOKEN=ghp_abc123 bun --cwd=examples/gh src/main.ts pr view 142
11
- * GH_TOKEN=ghp_abc123 bun --cwd=examples/gh src/main.ts pr create
12
- * GH_TOKEN=ghp_abc123 bun --cwd=examples/gh src/main.ts issue list --label bug
13
- * GH_TOKEN=ghp_abc123 bun --cwd=examples/gh src/main.ts issue triage 89
14
- * bun --cwd=examples/gh src/main.ts auth login
15
- * bun --cwd=examples/gh src/main.ts auth status
16
- * bun --cwd=examples/gh src/main.ts --help
17
- *
18
- * @module
19
- */
20
-
21
- import type { CLIBuilder } from '@kjanat/dreamcli';
22
- import { cli } from '@kjanat/dreamcli';
23
-
24
- import { auth } from './commands/auth.ts';
25
- import { issue } from './commands/issue.ts';
26
- import { pr } from './commands/pr.ts';
27
-
28
- /**
29
- * Create the example CLI and register commands.
30
- *
31
- * {@linkcode CLIBuilder.manifest | manifest()} fills `version` and `description` from this package's manifest.\
32
- * The CLI name still comes from `cli('gh')` unless `manifest({ inferName: true })` is used.
33
- *
34
- * Command registration order determines the order shown in `--help`.
35
- */
36
- export const gh = cli('gh')
37
- .manifest({ from: import.meta, files: ['package.json'] })
38
- .command(auth)
39
- .command(pr)
40
- .command(issue)
41
- .completions();
42
-
43
- // Run the CLI if this file is executed directly (e.g. `bun src/main.ts ...`).
44
- if (import.meta.main) {
45
- gh.run();
46
- }
@@ -1,43 +0,0 @@
1
- #!/usr/bin/env bun
2
- /**
3
- * Help rendering configuration.
4
- *
5
- * Demonstrates: `.help()` theming, `flagOrder: 'declaration'`, a routable
6
- * default command (`.default(cmd, { route: true })`), and footer control.
7
- *
8
- * Usage:
9
- * npx tsx examples/help-config.ts --help # themed, declaration-ordered
10
- * npx tsx examples/help-config.ts build --help # default command by name
11
- * npx tsx examples/help-config.ts --help --json # definition document instead of text
12
- */
13
-
14
- import { arg, cli, command, flag } from '@kjanat/dreamcli';
15
-
16
- const build = command('build')
17
- .description('Build the project')
18
- .example(({ name }) => `${name} build src/ --minify`, 'Minified build')
19
- .arg('entry', arg.string().default('src/').describe('Entry directory'))
20
- // Declaration order is preserved in help via `flagOrder` below, so put
21
- // the flags users reach for first at the top.
22
- .flag('minify', flag.boolean().describe('Minify output'))
23
- .flag('sourcemap', flag.boolean().describe('Emit sourcemaps'))
24
- .flag('watch', flag.boolean().alias('w').describe('Rebuild on change'))
25
- .action(({ args, flags, out }) => {
26
- out.log(`building ${args.entry} minify=${flags.minify} watch=${flags.watch}`);
27
- });
28
-
29
- void cli('builder')
30
- .version('1.0.0')
31
- .description('A build tool with configured help')
32
- .help({
33
- // 'declaration' keeps .flag() call order; default is 'alphabetical'.
34
- flagOrder: 'declaration',
35
- // Theme factory receives the gated palette — never invoked when color
36
- // is off, so custom themes cannot leak escapes into piped output.
37
- theme: (c) => ({ sectionTitle: c.magenta }),
38
- footer: false,
39
- })
40
- // route: true lists the default under Commands (tagged `(default)`) and
41
- // makes `builder build …` route by name alongside the bare `builder …`.
42
- .default(build, { route: true })
43
- .run();
@@ -1,67 +0,0 @@
1
- #!/usr/bin/env bun
2
- /**
3
- * Interactive prompts with config file fallback.
4
- *
5
- * Demonstrates: per-flag `.prompt()`, `.env()`, `.config()`, and the full
6
- * resolution chain (CLI → stdin → env → config → prompt → default).
7
- *
8
- * The resolution chain means:
9
- * 1. Explicit CLI flag wins: --region eu
10
- * 2. Then piped stdin: only for an input declaring `.stdin()`
11
- * 3. Then environment variable: DEPLOY_REGION=eu
12
- * 4. Then config file value: { "deploy": { "region": "eu" } }
13
- * 5. Then interactive prompt: prompts user to select
14
- * 6. Then default value: "us"
15
- *
16
- * Usage:
17
- * npx tsx examples/interactive.ts # prompts for everything
18
- * npx tsx examples/interactive.ts --region eu # skips region prompt
19
- * DEPLOY_REGION=ap npx tsx examples/interactive.ts # env resolves region
20
- * echo '{}' | npx tsx examples/interactive.ts # non-interactive: uses defaults / errors
21
- */
22
-
23
- import { arg, cli, command, flag } from '@kjanat/dreamcli';
24
-
25
- const deploy = command('deploy')
26
- .description('Deploy to an environment')
27
- .arg('target', arg.string().describe('Deploy target').default('staging'))
28
- .flag(
29
- 'region',
30
- flag
31
- .enum(['us', 'eu', 'ap'])
32
- .env('DEPLOY_REGION')
33
- .config('deploy.region')
34
- .prompt({ kind: 'select', message: 'Which region?' })
35
- .default('us')
36
- .describe('Target region'),
37
- )
38
- .flag(
39
- 'confirm',
40
- flag
41
- .boolean()
42
- .prompt({ kind: 'confirm', message: 'Proceed with deployment?' })
43
- .describe('Confirm deployment'),
44
- )
45
- .flag(
46
- 'tag',
47
- flag
48
- .string()
49
- .prompt({ kind: 'input', message: 'Release tag (e.g. v1.2.3):' })
50
- .describe('Release tag'),
51
- )
52
- .action(({ args, flags, out }) => {
53
- // All flags are resolved by the time action runs.
54
- // flags.region: "us" | "eu" | "ap" — guaranteed by prompt/default
55
- // flags.confirm: boolean
56
- // flags.tag: string | undefined — only if user provided one
57
- if (!flags.confirm) {
58
- out.warn('Deployment cancelled');
59
- return;
60
- }
61
- out.log(`Deploying ${args.target} to ${flags.region}`);
62
- if (flags.tag !== undefined) {
63
- out.log(`Tagged: ${flags.tag}`);
64
- }
65
- });
66
-
67
- void cli('deploy').default(deploy).run();
@@ -1,95 +0,0 @@
1
- #!/usr/bin/env bun
2
- /**
3
- * Mixed machine-readable JSON and human-readable side-channel output.
4
- *
5
- * Demonstrates: machine-readable `out.json()` stdout, `out.status()` stderr
6
- * side channels suppressible with `--quiet`, and `--json` for CLI-managed
7
- * structured errors.
8
- *
9
- * Usage:
10
- * npx tsx examples/json-mode.ts list # JSON stdout + plain stderr side channel
11
- * npx tsx examples/json-mode.ts list --format table # JSON stdout + table stderr side channel
12
- * npx tsx examples/json-mode.ts list --quiet # JSON stdout only, status lines suppressed
13
- * npx tsx examples/json-mode.ts list --json # same success output; CLI-managed errors stay JSON-safe
14
- * npx tsx examples/json-mode.ts show web-api
15
- * npx tsx examples/json-mode.ts show nonexistent # structured error
16
- * npx tsx examples/json-mode.ts show nonexistent --json # JSON error
17
- */
18
-
19
- import { arg, CLIError, cli, command, flag } from '@kjanat/dreamcli';
20
-
21
- // --- Sample data ---
22
-
23
- type Service = {
24
- readonly name: string;
25
- readonly status: 'healthy' | 'degraded' | 'down';
26
- readonly uptime: number;
27
- };
28
-
29
- const services: readonly Service[] = [
30
- { name: 'web-api', status: 'healthy', uptime: 99.9 },
31
- { name: 'worker', status: 'degraded', uptime: 95.2 },
32
- { name: 'database', status: 'healthy', uptime: 99.99 },
33
- { name: 'cache', status: 'down', uptime: 0 },
34
- ];
35
-
36
- // --- Commands ---
37
-
38
- const list = command('list')
39
- .description('List all services')
40
- .flag(
41
- 'format',
42
- flag.enum(['table', 'plain']).default('plain').alias('f').describe('Output format'),
43
- )
44
- .action(({ flags, out }) => {
45
- // This example always emits machine-readable JSON to stdout. `--json`
46
- // still matters for DreamCLI-managed output such as structured errors.
47
- out.json(services);
48
-
49
- if (flags.format === 'table') {
50
- out.table(
51
- services,
52
- [
53
- { key: 'name', header: 'Service' },
54
- { key: 'status', header: 'Status' },
55
- { key: 'uptime', header: 'Uptime %' },
56
- ],
57
- { format: 'text', stream: 'stderr' },
58
- );
59
- } else {
60
- // `out.status()` writes to stderr (stdout stays pipeable JSON) and
61
- // is suppressed under `--quiet`, unlike `out.error()`.
62
- for (const s of services) {
63
- out.status(`${s.name}: ${s.status} (${s.uptime}%)`);
64
- }
65
- }
66
- });
67
-
68
- const show = command('show')
69
- .description('Show details for a service')
70
- .arg('name', arg.string().describe('Service name'))
71
- .action(({ args, out }) => {
72
- const service = services.find((s) => s.name === args.name);
73
-
74
- if (!service) {
75
- // CLIError with details serializes cleanly in --json mode.
76
- throw new CLIError(`Service '${args.name}' not found`, {
77
- code: 'NOT_FOUND',
78
- exitCode: 1,
79
- suggest: `Available: ${services.map((s) => s.name).join(', ')}`,
80
- details: { requested: args.name, available: services.map((s) => s.name) },
81
- });
82
- }
83
-
84
- out.json(service);
85
- out.status(`${service.name}: ${service.status} (uptime ${service.uptime}%)`);
86
- });
87
-
88
- // --- CLI with --json support ---
89
-
90
- void cli('services')
91
- .version('1.0.0')
92
- .description('Service status dashboard')
93
- .command(list)
94
- .command(show)
95
- .run();
@@ -1,71 +0,0 @@
1
- #!/usr/bin/env bun
2
- /**
3
- * Middleware patterns: auth guard, request timing, error handling.
4
- *
5
- * Demonstrates: typed middleware context, auth guards, short-circuiting, and
6
- * wrap-around timing.
7
- *
8
- * Usage:
9
- * npx tsx examples/middleware.ts deploy production
10
- * npx tsx examples/middleware.ts deploy production --verbose
11
- */
12
-
13
- import { arg, CLIError, cli, command, flag, middleware } from '@kjanat/dreamcli';
14
-
15
- // --- Auth middleware — adds `user` to context ---
16
-
17
- interface User {
18
- readonly id: string;
19
- readonly name: string;
20
- readonly role: 'admin' | 'user';
21
- }
22
-
23
- async function getAuthenticatedUser(): Promise<User | null> {
24
- // In real code, read a token from env/config/keychain and return null when missing.
25
- return { id: 'u-1', name: 'Alice', role: 'admin' };
26
- }
27
-
28
- const auth = middleware<{ user: User }>(async ({ next }) => {
29
- const user = await getAuthenticatedUser();
30
-
31
- if (!user) {
32
- // Short-circuits the chain — action never runs.
33
- throw new CLIError('Not authenticated', {
34
- code: 'AUTH_REQUIRED',
35
- suggest: 'Run `myapp login` first',
36
- exitCode: 2,
37
- });
38
- }
39
-
40
- return next({ user });
41
- });
42
-
43
- // --- Timing middleware — wraps the downstream chain ---
44
-
45
- const timing = middleware<{ startTime: number }>(async ({ out, next }) => {
46
- const start = performance.now();
47
- await next({ startTime: start });
48
-
49
- // Code after `next()` runs after the action completes (onion model).
50
- const elapsed = (performance.now() - start).toFixed(0);
51
- out.status(`Completed in ${elapsed}ms`);
52
- });
53
-
54
- // --- Command using both middlewares ---
55
-
56
- const deploy = command('deploy')
57
- .description('Deploy to an environment')
58
- .arg('target', arg.string().describe('Deploy target'))
59
- .flag('verbose', flag.boolean().alias('v').describe('Verbose output'))
60
- .middleware(auth)
61
- .middleware(timing)
62
- .action(({ args, flags, ctx, out }) => {
63
- // ctx.user and ctx.startTime are typed via middleware chain.
64
- out.log(`[${ctx.user.role}] ${ctx.user.name} deploying ${args.target}`);
65
- if (flags.verbose) {
66
- out.info(`User ID: ${ctx.user.id}`);
67
- out.info(`Started at: ${ctx.startTime.toFixed(0)}ms`);
68
- }
69
- });
70
-
71
- void cli('myapp').default(deploy).run();
@@ -1,66 +0,0 @@
1
- #!/usr/bin/env bun
2
- /**
3
- * Multi-command CLI with nested command groups (git-like).
4
- *
5
- * Demonstrates: top-level commands, nested groups, version metadata, and
6
- * env-backed flags.
7
- *
8
- * Usage:
9
- * npx tsx examples/multi-command.ts deploy production --force
10
- * npx tsx examples/multi-command.ts deploy production --region eu
11
- * DEPLOY_REGION=ap npx tsx examples/multi-command.ts deploy production
12
- * npx tsx examples/multi-command.ts db migrate --steps 3
13
- * npx tsx examples/multi-command.ts db seed
14
- * npx tsx examples/multi-command.ts login --token abc123
15
- * npx tsx examples/multi-command.ts --help
16
- * npx tsx examples/multi-command.ts --version
17
- */
18
-
19
- import { arg, cli, command, flag, group } from '@kjanat/dreamcli';
20
-
21
- // --- Top-level commands ---
22
-
23
- const deploy = command('deploy')
24
- .description('Deploy to an environment')
25
- .arg('target', arg.string().describe('Deploy target (e.g. production, staging)'))
26
- .flag('force', flag.boolean().alias('f').describe('Skip confirmation'))
27
- .flag('region', flag.enum(['us', 'eu', 'ap']).env('DEPLOY_REGION').describe('Target region'))
28
- .action(({ args, flags, out }) => {
29
- out.log(`Deploying ${args.target} to ${flags.region ?? 'default region'}`);
30
- if (flags.force) out.log('(forced)');
31
- });
32
-
33
- const login = command('login')
34
- .description('Authenticate with the service')
35
- .flag('token', flag.string().describe('Auth token'))
36
- .action(({ flags, out }) => {
37
- out.log(`Logged in with token: ${flags.token ?? 'interactive'}`);
38
- });
39
-
40
- // --- Nested command group (myapp db migrate, myapp db seed) ---
41
-
42
- const migrate = command('migrate')
43
- .description('Run database migrations')
44
- .flag('steps', flag.number().alias('s').describe('Number of migration steps'))
45
- .action(({ flags, out }) => {
46
- out.log(`Migrating ${flags.steps !== undefined ? `${flags.steps} steps` : 'all pending'}`);
47
- });
48
-
49
- const seed = command('seed')
50
- .description('Seed the database')
51
- .flag('env', flag.enum(['dev', 'test']).default('dev').describe('Seed environment'))
52
- .action(({ flags, out }) => {
53
- out.log(`Seeding ${flags.env} database`);
54
- });
55
-
56
- const db = group('db').description('Database operations').command(migrate).command(seed);
57
-
58
- // --- Wire it all up ---
59
-
60
- void cli('myapp')
61
- .version('1.0.0')
62
- .description('Example multi-command CLI')
63
- .command(deploy)
64
- .command(login)
65
- .command(db)
66
- .run();