@kjanat/dreamcli 2.5.0 → 3.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 (89) hide show
  1. package/CHANGELOG.md +128 -1
  2. package/README.md +9 -2
  3. package/dist/core/cli/index.d.mts +109 -16
  4. package/dist/core/cli/index.mjs +1 -1
  5. package/dist/core/cli/planner.d.mts +27 -5
  6. package/dist/core/cli/planner.mjs +1 -1
  7. package/dist/core/cli/root-help.d.mts +16 -2
  8. package/dist/core/cli/root-help.mjs +3 -5
  9. package/dist/core/cli/root-surface.d.mts +18 -3
  10. package/dist/core/cli/root-surface.mjs +1 -1
  11. package/dist/core/cli/runtime-preflight.d.mts +16 -1
  12. package/dist/core/cli/runtime-preflight.mjs +1 -1
  13. package/dist/core/completion/index.d.mts +32 -1
  14. package/dist/core/completion/index.mjs +1 -1
  15. package/dist/core/completion/shells/shared.d.mts +10 -0
  16. package/dist/core/completion/shells/shared.mjs +1 -1
  17. package/dist/core/help/index.d.mts +45 -1
  18. package/dist/core/help/index.mjs +6 -6
  19. package/dist/core/json-schema/index.mjs +1 -1
  20. package/dist/core/json-schema/meta-descriptions.generated.d.mts +38 -38
  21. package/dist/core/parse/index.d.mts +15 -1
  22. package/dist/core/parse/index.mjs +1 -1
  23. package/dist/core/prompt/index.d.mts +11 -3
  24. package/dist/core/prompt/index.mjs +3 -3
  25. package/dist/core/resolve/coerce.mjs +1 -1
  26. package/dist/core/resolve/flags.mjs +1 -1
  27. package/dist/core/resolve/property.d.mts +2 -0
  28. package/dist/core/resolve/property.mjs +1 -1
  29. package/dist/core/schema/arg.d.mts +90 -10
  30. package/dist/core/schema/arg.mjs +1 -1
  31. package/dist/core/schema/command.d.mts +3 -1
  32. package/dist/core/schema/flag.d.mts +92 -2
  33. package/dist/core/schema/flag.mjs +1 -1
  34. package/dist/core/schema/index.d.mts +2 -1
  35. package/dist/core/schema/number-constraints.d.mts +96 -0
  36. package/dist/core/schema/number-constraints.mjs +1 -0
  37. package/dist/core/schema/prompt.d.mts +15 -0
  38. package/dist/core/schema/run.d.mts +4 -4
  39. package/dist/core/testkit/index.d.mts +9 -5
  40. package/dist/core/testkit/index.mjs +1 -1
  41. package/dist/index.d.mts +2 -1
  42. package/dist/index.mjs +1 -1
  43. package/dist/runtime/auto.mjs +1 -1
  44. package/dist/runtime/bun.mjs +1 -1
  45. package/dist/runtime/deno.mjs +2 -2
  46. package/dist/runtime/node.mjs +2 -2
  47. package/dist/version.mjs +1 -1
  48. package/examples/basic.ts +5 -1
  49. package/examples/gh/package.json +2 -7
  50. package/examples/pwsh-demo/package.json +1 -7
  51. package/examples/pwsh-demo/src/main.test.ts +1 -4
  52. package/examples/pwsh-demo/src/main.ts +14 -4
  53. package/examples/transport-launcher.ts +85 -0
  54. package/package.json +15 -24
  55. package/src/core/cli/dispatch.ts +7 -1
  56. package/src/core/cli/index.ts +235 -34
  57. package/src/core/cli/planner.ts +192 -23
  58. package/src/core/cli/root-help.ts +195 -105
  59. package/src/core/cli/root-surface.ts +25 -12
  60. package/src/core/cli/runtime-preflight.ts +20 -2
  61. package/src/core/completion/index.ts +50 -0
  62. package/src/core/completion/shells/powershell.ts +2 -2
  63. package/src/core/completion/shells/shared.ts +30 -3
  64. package/src/core/execution/index.ts +1 -4
  65. package/src/core/help/index.ts +57 -10
  66. package/src/core/json-schema/index.ts +23 -4
  67. package/src/core/json-schema/meta-descriptions.generated.ts +115 -98
  68. package/src/core/parse/index.ts +62 -1
  69. package/src/core/prompt/index.ts +54 -14
  70. package/src/core/resolve/coerce.ts +73 -5
  71. package/src/core/resolve/flags.ts +14 -0
  72. package/src/core/resolve/property.ts +4 -4
  73. package/src/core/schema/arg.ts +125 -3
  74. package/src/core/schema/command.ts +3 -1
  75. package/src/core/schema/flag.ts +120 -4
  76. package/src/core/schema/index.ts +5 -0
  77. package/src/core/schema/number-constraints.ts +153 -0
  78. package/src/core/schema/prompt.ts +15 -0
  79. package/src/core/schema/run.ts +4 -4
  80. package/src/core/testkit/index.ts +32 -8
  81. package/src/index.ts +2 -0
  82. package/src/runtime/auto.ts +0 -24
  83. package/src/runtime/bun.ts +0 -7
  84. package/src/runtime/deno.ts +0 -2
  85. package/src/runtime/node.ts +0 -11
  86. package/src/runtime/support.ts +1 -59
  87. package/src/schema.ts +16 -0
  88. package/dist/runtime/support.d.mts +0 -42
  89. package/dist/runtime/support.mjs +0 -1
@@ -1,2 +1,2 @@
1
- import{resolveConfigDirectory as e,resolveHomeDirectory as t}from"./paths.mjs";import{assertRuntimeVersionSupported as n}from"./support.mjs";function r(){return globalThis.process}function i(e){return typeof e!=`object`||!e||!(`code`in e)?!1:typeof e.code==`string`}function a(e,n){return t(e,n===`win32`)}function o(t,n,r){return e(t,n===`win32`,r)}function s(e){if(e.versions?.bun!==void 0){n(`bun`,e.versions.bun);return}n(`node`,e.versions?.node)}function c(e){let t=e??r();s(t);let n=e=>{t.stdout.write(e)},c=e=>{t.stderr.write(e)},d=u(t),f=async e=>{let t=await import(`node:fs/promises`);try{return await t.readFile(e,`utf8`)}catch(e){if(i(e)&&e.code===`ENOENT`)return null;throw e}},p=a(t.env,t.platform),m=o(t.env,t.platform,p),h=t.stdin.isTTY===!0;return{argv:t.argv,env:t.env,cwd:t.cwd(),stdout:n,stderr:c,stdin:d,readStdin:()=>l(t,h),isTTY:t.stdout.isTTY===!0,stdinIsTTY:h,exit:e=>t.exit(e),readFile:f,homedir:p,configDir:m}}async function l(e,t){if(t)return null;let n=[],r=new TextDecoder;for await(let t of e.stdin)n.push(r.decode(t,{stream:!0}));return n.push(r.decode()),n.join(``)}function u(e){let t=e.stdin[Symbol.asyncIterator](),n=new TextDecoder,r=``,i=!1;return async()=>{for(;;){let e=r.indexOf(`
2
- `);if(e!==-1){let t=r.slice(0,e).replace(/\r$/,``);return r=r.slice(e+1),t}if(i){if(r.length===0)return null;let e=r;return r=``,e}let a=await t.next();if(a.done){r+=n.decode(),i=!0;continue}r+=n.decode(a.value,{stream:!0})}}}export{c as createNodeAdapter};
1
+ import{resolveConfigDirectory as e,resolveHomeDirectory as t}from"./paths.mjs";function n(){return globalThis.process}function r(e){return typeof e!=`object`||!e||!(`code`in e)?!1:typeof e.code==`string`}function i(e,n){return t(e,n===`win32`)}function a(t,n,r){return e(t,n===`win32`,r)}function o(e){let t=e??n(),o=e=>{t.stdout.write(e)},l=e=>{t.stderr.write(e)},u=c(t),d=async e=>{let t=await import(`node:fs/promises`);try{return await t.readFile(e,`utf8`)}catch(e){if(r(e)&&e.code===`ENOENT`)return null;throw e}},f=i(t.env,t.platform),p=a(t.env,t.platform,f),m=t.stdin.isTTY===!0;return{argv:t.argv,env:t.env,cwd:t.cwd(),stdout:o,stderr:l,stdin:u,readStdin:()=>s(t,m),isTTY:t.stdout.isTTY===!0,stdinIsTTY:m,exit:e=>t.exit(e),readFile:d,homedir:f,configDir:p}}async function s(e,t){if(t)return null;let n=[],r=new TextDecoder;for await(let t of e.stdin)n.push(r.decode(t,{stream:!0}));return n.push(r.decode()),n.join(``)}function c(e){let t=e.stdin[Symbol.asyncIterator](),n=new TextDecoder,r=``,i=!1;return async()=>{for(;;){let e=r.indexOf(`
2
+ `);if(e!==-1){let t=r.slice(0,e).replace(/\r$/,``);return r=r.slice(e+1),t}if(i){if(r.length===0)return null;let e=r;return r=``,e}let a=await t.next();if(a.done){r+=n.decode(),i=!0;continue}r+=n.decode(a.value,{stream:!0})}}}export{o as createNodeAdapter};
package/dist/version.mjs CHANGED
@@ -1 +1 @@
1
- const e=`2.5.0`,t=`6d9491b`;export{t as DREAMCLI_REVISION,e as DREAMCLI_VERSION};
1
+ const e=`3.0.0-rc.1`,t=`c3bcd04`;export{t as DREAMCLI_REVISION,e as DREAMCLI_VERSION};
package/examples/basic.ts CHANGED
@@ -24,7 +24,11 @@ const greet = command('greet')
24
24
  // args.name: string — required positional
25
25
  // flags.loud: boolean — defaults to false (all booleans do)
26
26
  // flags.times: number — defaults to 1 (never undefined)
27
- for (let i = 0; i < flags.times; i++) {
27
+ const repeatCount = Number.isFinite(flags.times)
28
+ ? Math.max(0, Math.min(100, Math.floor(flags.times)))
29
+ : 1;
30
+
31
+ for (let i = 0; i < repeatCount; i++) {
28
32
  const msg = `Hello, ${args.name}!`;
29
33
  out.log(flags.loud ? msg.toUpperCase() : msg);
30
34
  }
@@ -10,13 +10,8 @@
10
10
  },
11
11
  "type": "module",
12
12
  "module": "src/main.ts",
13
- "bin": {
14
- "gh": "src/main.ts"
15
- },
16
- "files": [
17
- "src",
18
- "!src/**/*.test.ts"
19
- ],
13
+ "bin": "src/main.ts",
14
+ "files": ["src", "!src/**/*.test.ts"],
20
15
  "scripts": {
21
16
  "bd": "bun run build",
22
17
  "build": "bun build src/main.ts --install --outdir=dist --format=esm --target=node --external @kjanat/dreamcli",
@@ -13,13 +13,7 @@
13
13
  "bin": {
14
14
  "pwsh-demo": "src/main.ts"
15
15
  },
16
- "files": [
17
- "src",
18
- "README.md",
19
- "smoke-powershell.ps1",
20
- "pwsh-demo.cmd",
21
- "!src/**/*.test.ts"
22
- ],
16
+ "files": ["src", "README.md", "smoke-powershell.ps1", "pwsh-demo.cmd", "!src/**/*.test.ts"],
23
17
  "scripts": {
24
18
  "build": "bun build src/main.ts --install --outdir=dist --format=esm --target=node --external @kjanat/dreamcli",
25
19
  "smoke:powershell": "pwsh -NoLogo -NoProfile -ExecutionPolicy Bypass -File ./smoke-powershell.ps1",
@@ -40,9 +40,6 @@ describe('pwsh-demo example', () => {
40
40
  const result = await pwshDemo.execute(['bravo', '--profile', 'ops', '--shell', 'cmd']);
41
41
 
42
42
  expect(result.exitCode).toBe(0);
43
- expect(result.stdout).toEqual([
44
- 'Opening bravo with ops profile in cmd\n',
45
- 'Format: table\n',
46
- ]);
43
+ expect(result.stdout).toEqual(['Opening bravo with ops profile in cmd\n', 'Format: table\n']);
47
44
  });
48
45
  });
@@ -35,7 +35,9 @@ const open = command('open')
35
35
  .flag('format', flag.enum(['table', 'json', 'yaml']).alias('f').describe('Output format'))
36
36
  .flag('verbose', flag.boolean().alias('v').describe('Verbose logging'))
37
37
  .action(({ args, flags, out }) => {
38
- out.log(`Opening ${args.workspace} with ${flags.profile ?? 'default'} profile in ${flags.shell}`);
38
+ out.log(
39
+ `Opening ${args.workspace} with ${flags.profile ?? 'default'} profile in ${flags.shell}`,
40
+ );
39
41
  out.log(`Format: ${flags.format ?? 'table'}`);
40
42
  if (flags.verbose) out.log('Verbose output enabled');
41
43
  });
@@ -55,7 +57,9 @@ const deploy = command('deploy')
55
57
  .flag('approval', flag.enum(['manual', 'auto']).describe('Approval mode'))
56
58
  .flag('dryRun', flag.boolean().alias('d').describe('Preview the rollout without applying it'))
57
59
  .action(({ args, flags, out }) => {
58
- out.log(`Deploying ${args.target} to ${flags.region ?? 'us'} with ${flags.strategy ?? 'rolling'}`);
60
+ out.log(
61
+ `Deploying ${args.target} to ${flags.region ?? 'us'} with ${flags.strategy ?? 'rolling'}`,
62
+ );
59
63
  out.log(`Approval: ${flags.approval ?? 'manual'}`);
60
64
  if (flags.dryRun) out.log('Dry run only');
61
65
  });
@@ -82,7 +86,10 @@ const configSet = command('set')
82
86
  .description('Write a saved setting')
83
87
  .arg('key', arg.enum(['theme', 'region', 'profile']).describe('Setting to write'))
84
88
  .arg('value', arg.string().describe('New value'))
85
- .flag('scope', flag.enum(['user', 'workspace']).alias('s').default('user').describe('Config scope'))
89
+ .flag(
90
+ 'scope',
91
+ flag.enum(['user', 'workspace']).alias('s').default('user').describe('Config scope'),
92
+ )
86
93
  .action(({ args, flags, out }) => {
87
94
  out.log(`Saved ${args.key}=${args.value} to ${flags.scope} scope`);
88
95
  });
@@ -107,7 +114,10 @@ const debugDump = command('debug-dump')
107
114
  .hidden()
108
115
  .flag(
109
116
  'section',
110
- flag.enum(['schema', 'completions', 'runtime']).default('schema').describe('Section to inspect'),
117
+ flag
118
+ .enum(['schema', 'completions', 'runtime'])
119
+ .default('schema')
120
+ .describe('Section to inspect'),
111
121
  )
112
122
  .action(({ flags, out }) => {
113
123
  out.log(JSON.stringify({ section: flags.section, hidden: true }, null, 2));
@@ -0,0 +1,85 @@
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`, a
12
+ * kebab-case flag name accessed with bracket notation (`flags['node-ipc']`), and
13
+ * passing a typed result to the action through derived context.
14
+ *
15
+ * Usage:
16
+ * npx tsx examples/transport-launcher.ts --stdio
17
+ * npx tsx examples/transport-launcher.ts --node-ipc
18
+ * npx tsx examples/transport-launcher.ts --socket 6009
19
+ * npx tsx examples/transport-launcher.ts # error: pick exactly one
20
+ * npx tsx examples/transport-launcher.ts --stdio --node-ipc # error: only one
21
+ * npx tsx examples/transport-launcher.ts --help
22
+ */
23
+
24
+ import { CLIError, cli, command, flag } from '@kjanat/dreamcli';
25
+
26
+ // One resolved transport — illegal states are unrepresentable.
27
+ type Transport =
28
+ | { readonly kind: 'stdio' }
29
+ | { readonly kind: 'node-ipc' }
30
+ | { readonly kind: 'socket'; readonly port: number };
31
+
32
+ const launcher = command('lsp-server')
33
+ .description('Launch the language server over exactly one transport')
34
+ .flag('stdio', flag.boolean().describe('Use the stdio transport'))
35
+ .flag('node-ipc', flag.boolean().describe('Use the Node IPC transport'))
36
+ .flag('socket', flag.number().describe('Use a TCP socket on <port>'))
37
+ // `.derive()` runs after resolution and before the action — the idiomatic
38
+ // place for a constraint dreamcli does not express declaratively.
39
+ .derive(({ flags }): { transport: Transport } => {
40
+ const selected: Transport[] = [];
41
+ if (flags.stdio) selected.push({ kind: 'stdio' });
42
+ // Kebab-case flag names stay kebab in the handler: bracket access, no camelCasing.
43
+ if (flags['node-ipc']) selected.push({ kind: 'node-ipc' });
44
+ if (flags.socket !== undefined) {
45
+ if (!Number.isInteger(flags.socket)) {
46
+ throw new CLIError(`--socket expects an integer port (got ${flags.socket}).`, {
47
+ code: 'INVALID_SOCKET_PORT',
48
+ suggest: 'Pass a whole number, e.g. --socket 6009',
49
+ });
50
+ }
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();
package/package.json CHANGED
@@ -1,15 +1,8 @@
1
1
  {
2
2
  "name": "@kjanat/dreamcli",
3
- "version": "2.5.0",
3
+ "version": "3.0.0-rc.1",
4
4
  "description": "Schema-first, fully typed TypeScript CLI framework",
5
- "keywords": [
6
- "dreamcli",
7
- "cli",
8
- "typescript",
9
- "framework",
10
- "schema-first",
11
- "command-line"
12
- ],
5
+ "keywords": ["dreamcli", "cli", "typescript", "framework", "schema-first", "command-line"],
13
6
  "homepage": "https://dreamcli.kjanat.dev",
14
7
  "bugs": {
15
8
  "url": "https://github.com/kjanat/dreamcli/issues"
@@ -69,9 +62,7 @@
69
62
  "!src/**/*test-helpers.ts",
70
63
  "!**/AGENTS.md"
71
64
  ],
72
- "workspaces": [
73
- "./examples/*"
74
- ],
65
+ "workspaces": ["./examples/*"],
75
66
  "scripts": {
76
67
  "bd": "run build",
77
68
  "build": "bun --bun tsdown",
@@ -122,26 +113,26 @@
122
113
  "@arethetypeswrong/core": "^0.18.4",
123
114
  "@biomejs/biome": "^2.5.1",
124
115
  "@iarna/toml": "^2.2.5",
125
- "@shikijs/transformers": "^4.2.0",
126
- "@shikijs/vitepress-twoslash": "^4.2.0",
116
+ "@shikijs/transformers": "^4.3.0",
117
+ "@shikijs/vitepress-twoslash": "^4.3.0",
127
118
  "@types/bun": "^1.3.14",
128
119
  "@types/deno": "^2.7.0",
129
- "@types/node": ">=22.0.0, <23.0.0",
130
- "@typescript/native-preview": "^7.0.0-dev",
120
+ "@types/node": ">=26.0.1",
121
+ "@typescript/native-preview": "^7.0.0-dev.20260629.1",
131
122
  "@vitest/coverage-v8": "^4.1.9",
132
- "dprint": "^0.54.0",
123
+ "dprint": "^0.55.1",
133
124
  "floating-vue": "^5.2.2",
134
- "knip": "^6.18.0",
135
- "mermaid": "^11.15.0",
125
+ "knip": "^6.23.0",
126
+ "mermaid": "^11.16.0",
136
127
  "publint": "^0.3.21",
137
- "runner-run": "0.14.0",
128
+ "runner-run": "0.15.0",
138
129
  "tsdown": "^0.22.3",
139
130
  "typedoc": "^0.28.19",
140
131
  "typescript": "^6.0.3",
141
132
  "vite": "^8.1.0",
142
133
  "vitepress": "^2.0.0-alpha.17",
143
134
  "vitest": "^4.1.9",
144
- "wrangler": "^4.104.0",
135
+ "wrangler": "^4.105.0",
145
136
  "yaml": "^2.9.0"
146
137
  },
147
138
  "packageManager": "bun@1.3.14",
@@ -161,8 +152,8 @@
161
152
  }
162
153
  },
163
154
  "volta": {
164
- "node": "26.3.1",
165
- "npm": "11.17.0"
155
+ "node": "26.4.0",
156
+ "npm": "11.18.0"
166
157
  },
167
158
  "publishConfig": {
168
159
  "access": "public",
@@ -170,7 +161,7 @@
170
161
  },
171
162
  "catalog": {
172
163
  "@types/bun": "^1.3.14",
173
- "@types/node": ">=22.0.0, <23.0.0",
164
+ "@types/node": ">=26.0.1",
174
165
  "typescript": "^6.0.3"
175
166
  }
176
167
  }
@@ -345,5 +345,11 @@ function uniqueCommands(commands: ReadonlyMap<string, ErasedCommand>): readonly
345
345
 
346
346
  // --- Exports
347
347
 
348
- export type { DispatchMatch, DispatchNeedsSubcommand, DispatchResult, DispatchUnknown, ValueFlagLookup };
348
+ export type {
349
+ DispatchMatch,
350
+ DispatchNeedsSubcommand,
351
+ DispatchResult,
352
+ DispatchUnknown,
353
+ ValueFlagLookup,
354
+ };
349
355
  export { consumesFollowingToken, dispatch, findClosestCommand, levenshtein, uniqueCommands };