@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,147 +0,0 @@
1
- #!/usr/bin/env bun
2
- /**
3
- * Testing examples using @kjanat/dreamcli/testkit.
4
- *
5
- * Demonstrates: `runCommand()`, prompt answers, env/config injection, output
6
- * assertions, middleware context, and activity assertions.
7
- *
8
- * This file is structured as a Vitest test suite — run with
9
- * `bun test examples/testing.ts`.
10
- *
11
- * Usage:
12
- * bun test examples/testing.ts
13
- */
14
-
15
- import { arg, command, flag, middleware } from '@kjanat/dreamcli';
16
- import { createTestPrompter, PROMPT_CANCEL, runCommand } from '@kjanat/dreamcli/testkit';
17
- import { describe, expect, it } from 'vitest';
18
-
19
- // --- Command under test ---
20
-
21
- const deploy = command('deploy')
22
- .description('Deploy to an environment')
23
- .arg('target', arg.string().describe('Deploy target'))
24
- .flag(
25
- 'region',
26
- flag
27
- .enum(['us', 'eu', 'ap'])
28
- .env('DEPLOY_REGION')
29
- .config('deploy.region')
30
- .prompt({ kind: 'select', message: 'Which region?' })
31
- .describe('Target region'),
32
- )
33
- .flag('force', flag.boolean().alias('f'))
34
- .action(({ args, flags, out }) => {
35
- if (!flags.force) {
36
- out.warn('Use --force to skip confirmation');
37
- }
38
- out.log(`Deploying ${args.target} to ${flags.region}`);
39
- });
40
-
41
- // --- Tests ---
42
-
43
- describe('deploy command', () => {
44
- it('deploys with explicit flags', async () => {
45
- const result = await runCommand(deploy, ['production', '--region', 'eu', '--force']);
46
-
47
- expect(result.exitCode).toBe(0);
48
- expect(result.stdout).toEqual(['Deploying production to eu\n']);
49
- expect(result.stderr).toEqual([]);
50
- });
51
-
52
- it('resolves region from environment variable', async () => {
53
- const result = await runCommand(deploy, ['staging', '--force'], {
54
- env: { DEPLOY_REGION: 'ap' },
55
- });
56
-
57
- expect(result.exitCode).toBe(0);
58
- expect(result.stdout).toEqual(['Deploying staging to ap\n']);
59
- });
60
-
61
- it('resolves region from config file', async () => {
62
- const result = await runCommand(deploy, ['staging', '--force'], {
63
- config: { deploy: { region: 'eu' } },
64
- });
65
-
66
- expect(result.exitCode).toBe(0);
67
- expect(result.stdout).toEqual(['Deploying staging to eu\n']);
68
- });
69
-
70
- it('prompts for region when not provided', async () => {
71
- const result = await runCommand(deploy, ['staging', '--force'], {
72
- answers: ['us'],
73
- });
74
-
75
- expect(result.exitCode).toBe(0);
76
- expect(result.stdout).toEqual(['Deploying staging to us\n']);
77
- });
78
-
79
- it('handles prompt cancellation', async () => {
80
- const result = await runCommand(deploy, ['staging'], {
81
- prompter: createTestPrompter([PROMPT_CANCEL]),
82
- });
83
-
84
- expect(result.exitCode).not.toBe(0);
85
- });
86
-
87
- it('shows warning when --force is not set', async () => {
88
- const result = await runCommand(deploy, ['production', '--region', 'us']);
89
-
90
- expect(result.exitCode).toBe(0);
91
- expect(result.stderr).toEqual(['Use --force to skip confirmation\n']);
92
- expect(result.stdout).toEqual(['Deploying production to us\n']);
93
- });
94
-
95
- it('renders help text', async () => {
96
- const result = await runCommand(deploy, ['--help']);
97
-
98
- expect(result.exitCode).toBe(0);
99
- expect(result.stdout.join('')).toContain('Deploy to an environment');
100
- expect(result.stdout.join('')).toContain('--region');
101
- });
102
- });
103
-
104
- // --- Middleware testing ---
105
-
106
- const auth = middleware<{ user: string }>(async ({ next }) => {
107
- return next({ user: 'alice' });
108
- });
109
-
110
- const guarded = command('secret')
111
- .description('Protected command')
112
- .middleware(auth)
113
- .action(({ ctx, out }) => {
114
- out.log(`Hello, ${ctx.user}`);
115
- });
116
-
117
- describe('middleware context', () => {
118
- it('passes context from middleware to action', async () => {
119
- const result = await runCommand(guarded, []);
120
-
121
- expect(result.exitCode).toBe(0);
122
- expect(result.stdout).toEqual(['Hello, alice\n']);
123
- });
124
- });
125
-
126
- // --- Spinner/progress activity events ---
127
-
128
- const build = command('build')
129
- .description('Build something')
130
- .action(({ out }) => {
131
- const spinner = out.spinner('Building...');
132
- spinner.succeed('Done');
133
- });
134
-
135
- describe('activity events', () => {
136
- it('captures spinner lifecycle in activity array', async () => {
137
- const result = await runCommand(build, []);
138
-
139
- expect(result.exitCode).toBe(0);
140
- expect(result.activity).toContainEqual(
141
- expect.objectContaining({ type: 'spinner:start', text: 'Building...' }),
142
- );
143
- expect(result.activity).toContainEqual(
144
- expect.objectContaining({ type: 'spinner:succeed', text: 'Done' }),
145
- );
146
- });
147
- });
@@ -1,85 +0,0 @@
1
- #!/usr/bin/env bun
2
- /**
3
- * Single-transport launcher (language-server style).
4
- *
5
- * A launcher that must be started over exactly one transport. dreamcli has no
6
- * native "mutually exclusive" / "exactly one of" modifier, so the rule is
7
- * expressed in `.derive()` — the resolution-time hook that runs after flags
8
- * resolve and before the action. The derived, fully typed `Transport` is then
9
- * handed to `.action()` through `ctx`.
10
- *
11
- * Demonstrates: an "exactly one of" rule via `.derive()` throwing `CLIError`,
12
- * declarative numeric constraints (`flag.number({ int: true, min: 1, max: 65535 })`),
13
- * a kebab-case flag name accessed with bracket notation (`flags['node-ipc']`),
14
- * and passing a typed result to the action through derived context.
15
- *
16
- * Usage:
17
- * npx tsx examples/transport-launcher.ts --stdio
18
- * npx tsx examples/transport-launcher.ts --node-ipc
19
- * npx tsx examples/transport-launcher.ts --socket 6009
20
- * npx tsx examples/transport-launcher.ts # error: pick exactly one
21
- * npx tsx examples/transport-launcher.ts --stdio --node-ipc # error: only one
22
- * npx tsx examples/transport-launcher.ts --help
23
- */
24
-
25
- import { CLIError, cli, command, flag } from '@kjanat/dreamcli';
26
-
27
- // One resolved transport — illegal states are unrepresentable.
28
- type Transport =
29
- | { readonly kind: 'stdio' }
30
- | { readonly kind: 'node-ipc' }
31
- | { readonly kind: 'socket'; readonly port: number };
32
-
33
- const launcher = command('lsp-server')
34
- .description('Launch the language server over exactly one transport')
35
- .flag('stdio', flag.boolean().describe('Use the stdio transport'))
36
- .flag('node-ipc', flag.boolean().describe('Use the Node IPC transport'))
37
- .flag(
38
- 'socket',
39
- flag.number({ int: true, min: 1, max: 65535 }).describe('Use a TCP socket on <port>'),
40
- )
41
- // `.derive()` runs after resolution and before the action — the idiomatic
42
- // place for a constraint dreamcli does not express declaratively.
43
- .derive(({ flags }): { transport: Transport } => {
44
- const selected: Transport[] = [];
45
- if (flags.stdio) selected.push({ kind: 'stdio' });
46
- // Kebab-case flag names stay kebab in the handler: bracket access, no camelCasing.
47
- if (flags['node-ipc']) selected.push({ kind: 'node-ipc' });
48
- // Port shape (integer, 1-65535) is already enforced declaratively by
49
- // the flag's numeric constraints before `.derive()` runs.
50
- if (flags.socket !== undefined) {
51
- selected.push({ kind: 'socket', port: flags.socket });
52
- }
53
-
54
- const [transport, ...rest] = selected;
55
- if (transport === undefined) {
56
- throw new CLIError('No transport selected.', {
57
- code: 'NO_TRANSPORT',
58
- suggest: 'Pass exactly one of --stdio, --node-ipc, or --socket <port>',
59
- });
60
- }
61
- if (rest.length > 0) {
62
- throw new CLIError('Choose exactly one transport flag.', {
63
- code: 'TOO_MANY_TRANSPORTS',
64
- suggest: 'Use only one of --stdio, --node-ipc, or --socket <port>',
65
- });
66
- }
67
-
68
- return { transport };
69
- })
70
- .action(({ ctx, out }) => {
71
- // ctx.transport: Transport — fully typed, ready to hand to the server.
72
- switch (ctx.transport.kind) {
73
- case 'stdio':
74
- out.log('Starting language server over stdio');
75
- break;
76
- case 'node-ipc':
77
- out.log('Starting language server over node-ipc');
78
- break;
79
- case 'socket':
80
- out.log(`Starting language server over socket :${ctx.transport.port}`);
81
- break;
82
- }
83
- });
84
-
85
- void cli('lsp-server').default(launcher).run();