@kjanat/dreamcli 2.5.0 → 3.0.0-rc.10

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 (202) hide show
  1. package/CHANGELOG.md +344 -1
  2. package/README.md +9 -2
  3. package/dist/core/cli/dispatch.d.mts +6 -5
  4. package/dist/core/cli/dispatch.mjs +205 -1
  5. package/dist/core/cli/help-links.d.mts +0 -1
  6. package/dist/core/cli/help-links.mjs +41 -1
  7. package/dist/core/cli/index.d.mts +185 -19
  8. package/dist/core/cli/index.mjs +945 -1
  9. package/dist/core/cli/planner.d.mts +32 -6
  10. package/dist/core/cli/planner.mjs +300 -1
  11. package/dist/core/cli/plugin.d.mts +1 -1
  12. package/dist/core/cli/plugin.mjs +41 -1
  13. package/dist/core/cli/propagate.d.mts +1 -1
  14. package/dist/core/cli/propagate.mjs +57 -1
  15. package/dist/core/cli/root-help.d.mts +18 -3
  16. package/dist/core/cli/root-help.mjs +226 -6
  17. package/dist/core/cli/root-surface.d.mts +30 -4
  18. package/dist/core/cli/root-surface.mjs +28 -1
  19. package/dist/core/cli/runtime-preflight.d.mts +30 -3
  20. package/dist/core/cli/runtime-preflight.mjs +169 -1
  21. package/dist/core/completion/index.d.mts +32 -2
  22. package/dist/core/completion/index.mjs +90 -1
  23. package/dist/core/completion/shells/bash.d.mts +0 -1
  24. package/dist/core/completion/shells/bash.mjs +308 -3
  25. package/dist/core/completion/shells/fish.d.mts +0 -1
  26. package/dist/core/completion/shells/fish.mjs +162 -2
  27. package/dist/core/completion/shells/powershell.d.mts +0 -1
  28. package/dist/core/completion/shells/powershell.mjs +358 -2
  29. package/dist/core/completion/shells/shared.d.mts +23 -2
  30. package/dist/core/completion/shells/shared.mjs +176 -1
  31. package/dist/core/completion/shells/zsh.d.mts +0 -1
  32. package/dist/core/completion/shells/zsh.mjs +251 -2
  33. package/dist/core/config/index.d.mts +2 -3
  34. package/dist/core/config/index.mjs +246 -1
  35. package/dist/core/config/package-json.d.mts +27 -4
  36. package/dist/core/config/package-json.mjs +386 -3
  37. package/dist/core/errors/index.d.mts +3 -3
  38. package/dist/core/errors/index.mjs +87 -1
  39. package/dist/core/execution/index.d.mts +0 -1
  40. package/dist/core/execution/index.mjs +201 -1
  41. package/dist/core/help/ansi.d.mts +11 -5
  42. package/dist/core/help/ansi.mjs +121 -2
  43. package/dist/core/help/index.d.mts +65 -2
  44. package/dist/core/help/index.mjs +341 -7
  45. package/dist/core/help/theme.d.mts +68 -0
  46. package/dist/core/help/theme.mjs +46 -0
  47. package/dist/core/json-schema/index.d.mts +15 -2
  48. package/dist/core/json-schema/index.mjs +536 -12
  49. package/dist/core/json-schema/meta-descriptions.generated.d.mts +22 -5
  50. package/dist/core/json-schema/meta-descriptions.generated.mjs +102 -28
  51. package/dist/core/output/activity.d.mts +0 -1
  52. package/dist/core/output/activity.mjs +452 -1
  53. package/dist/core/output/bind.mjs +56 -1
  54. package/dist/core/output/contracts.d.mts +4 -5
  55. package/dist/core/output/contracts.mjs +57 -1
  56. package/dist/core/output/display-value.mjs +32 -1
  57. package/dist/core/output/index.d.mts +21 -1
  58. package/dist/core/output/index.mjs +442 -2
  59. package/dist/core/output/renderers.d.mts +0 -1
  60. package/dist/core/output/renderers.mjs +46 -1
  61. package/dist/core/output/writer.mjs +12 -1
  62. package/dist/core/parse/index.d.mts +54 -7
  63. package/dist/core/parse/index.mjs +727 -1
  64. package/dist/core/prompt/index.d.mts +12 -4
  65. package/dist/core/prompt/index.mjs +348 -6
  66. package/dist/core/resolve/args.d.mts +1 -1
  67. package/dist/core/resolve/args.mjs +105 -1
  68. package/dist/core/resolve/coerce.d.mts +1 -1
  69. package/dist/core/resolve/coerce.mjs +336 -1
  70. package/dist/core/resolve/config.mjs +19 -1
  71. package/dist/core/resolve/contracts.d.mts +9 -4
  72. package/dist/core/resolve/errors.d.mts +0 -1
  73. package/dist/core/resolve/errors.mjs +140 -2
  74. package/dist/core/resolve/flags.d.mts +7 -2
  75. package/dist/core/resolve/flags.mjs +251 -1
  76. package/dist/core/resolve/index.d.mts +2 -2
  77. package/dist/core/resolve/index.mjs +85 -1
  78. package/dist/core/resolve/property.d.mts +6 -2
  79. package/dist/core/resolve/property.mjs +53 -1
  80. package/dist/core/schema/activity.d.mts +31 -11
  81. package/dist/core/schema/arg.d.mts +92 -13
  82. package/dist/core/schema/arg.mjs +463 -1
  83. package/dist/core/schema/command.d.mts +29 -7
  84. package/dist/core/schema/command.mjs +726 -1
  85. package/dist/core/schema/flag.d.mts +577 -21
  86. package/dist/core/schema/flag.mjs +705 -1
  87. package/dist/core/schema/index.d.mts +5 -2
  88. package/dist/core/schema/middleware.d.mts +4 -3
  89. package/dist/core/schema/middleware.mjs +41 -1
  90. package/dist/core/schema/number-constraints.d.mts +96 -0
  91. package/dist/core/schema/number-constraints.mjs +60 -0
  92. package/dist/core/schema/prompt.d.mts +21 -3
  93. package/dist/core/schema/run.d.mts +24 -5
  94. package/dist/core/schema/string-constraints.d.mts +97 -0
  95. package/dist/core/schema/string-constraints.mjs +69 -0
  96. package/dist/core/schema/value-parsers.d.mts +78 -0
  97. package/dist/core/schema/value-parsers.mjs +142 -0
  98. package/dist/core/schema-dsl/runtime.mjs +271 -2
  99. package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
  100. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  101. package/dist/core/testkit/index.d.mts +9 -36
  102. package/dist/core/testkit/index.mjs +83 -1
  103. package/dist/index.d.mts +12 -6
  104. package/dist/index.mjs +22 -1
  105. package/dist/runtime/adapter.d.mts +38 -2
  106. package/dist/runtime/adapter.mjs +87 -1
  107. package/dist/runtime/auto.d.mts +2 -3
  108. package/dist/runtime/auto.mjs +45 -1
  109. package/dist/runtime/deno.d.mts +24 -5
  110. package/dist/runtime/deno.mjs +262 -2
  111. package/dist/runtime/detect.mjs +45 -1
  112. package/dist/runtime/index.d.mts +3 -4
  113. package/dist/runtime/node.d.mts +8 -2
  114. package/dist/runtime/node.mjs +220 -2
  115. package/dist/runtime/paths.mjs +48 -1
  116. package/dist/runtime.d.mts +4 -4
  117. package/dist/runtime.mjs +6 -1
  118. package/dist/strings.mjs +22 -1
  119. package/dist/testkit.d.mts +1 -0
  120. package/dist/testkit.mjs +5 -1
  121. package/dist/version.d.mts +7 -3
  122. package/dist/version.mjs +7 -1
  123. package/dreamcli.schema.json +36 -7
  124. package/examples/basic.ts +5 -1
  125. package/examples/gh/package.json +2 -7
  126. package/examples/pwsh-demo/package.json +1 -7
  127. package/examples/pwsh-demo/src/main.test.ts +1 -4
  128. package/examples/pwsh-demo/src/main.ts +14 -4
  129. package/examples/transport-launcher.ts +85 -0
  130. package/package.json +43 -49
  131. package/dist/runtime/bun.d.mts +0 -28
  132. package/dist/runtime/bun.mjs +0 -1
  133. package/dist/runtime/support.d.mts +0 -42
  134. package/dist/runtime/support.mjs +0 -1
  135. package/src/core/cli/dispatch.ts +0 -349
  136. package/src/core/cli/help-links.ts +0 -82
  137. package/src/core/cli/index.ts +0 -1413
  138. package/src/core/cli/planner.ts +0 -487
  139. package/src/core/cli/plugin.ts +0 -117
  140. package/src/core/cli/propagate.ts +0 -97
  141. package/src/core/cli/root-help.ts +0 -252
  142. package/src/core/cli/root-surface.ts +0 -74
  143. package/src/core/cli/runtime-preflight.ts +0 -438
  144. package/src/core/completion/index.ts +0 -88
  145. package/src/core/completion/shells/bash.ts +0 -459
  146. package/src/core/completion/shells/fish.ts +0 -259
  147. package/src/core/completion/shells/powershell.ts +0 -439
  148. package/src/core/completion/shells/shared.ts +0 -283
  149. package/src/core/completion/shells/zsh.ts +0 -381
  150. package/src/core/config/index.ts +0 -417
  151. package/src/core/config/package-json.ts +0 -560
  152. package/src/core/errors/index.ts +0 -193
  153. package/src/core/execution/index.ts +0 -268
  154. package/src/core/help/ansi.ts +0 -144
  155. package/src/core/help/index.ts +0 -516
  156. package/src/core/json-schema/index.ts +0 -891
  157. package/src/core/json-schema/meta-descriptions.generated.ts +0 -185
  158. package/src/core/output/activity.ts +0 -575
  159. package/src/core/output/bind.ts +0 -59
  160. package/src/core/output/contracts.ts +0 -194
  161. package/src/core/output/display-value.ts +0 -48
  162. package/src/core/output/index.ts +0 -704
  163. package/src/core/output/renderers.ts +0 -125
  164. package/src/core/output/writer.ts +0 -46
  165. package/src/core/parse/index.ts +0 -681
  166. package/src/core/prompt/index.ts +0 -583
  167. package/src/core/resolve/args.ts +0 -144
  168. package/src/core/resolve/coerce.ts +0 -432
  169. package/src/core/resolve/config.ts +0 -26
  170. package/src/core/resolve/contracts.ts +0 -135
  171. package/src/core/resolve/errors.ts +0 -227
  172. package/src/core/resolve/flags.ts +0 -255
  173. package/src/core/resolve/index.ts +0 -108
  174. package/src/core/resolve/property.ts +0 -99
  175. package/src/core/schema/activity.ts +0 -240
  176. package/src/core/schema/arg.ts +0 -719
  177. package/src/core/schema/command.ts +0 -1498
  178. package/src/core/schema/flag.ts +0 -801
  179. package/src/core/schema/index.ts +0 -91
  180. package/src/core/schema/middleware.ts +0 -171
  181. package/src/core/schema/prompt.ts +0 -156
  182. package/src/core/schema/run.ts +0 -198
  183. package/src/core/schema-dsl/index.ts +0 -109
  184. package/src/core/schema-dsl/parse.ts +0 -262
  185. package/src/core/schema-dsl/runtime.ts +0 -609
  186. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  187. package/src/core/testkit/index.ts +0 -123
  188. package/src/index.ts +0 -179
  189. package/src/runtime/adapter.ts +0 -303
  190. package/src/runtime/auto.ts +0 -110
  191. package/src/runtime/bun.ts +0 -55
  192. package/src/runtime/deno.ts +0 -369
  193. package/src/runtime/detect.ts +0 -105
  194. package/src/runtime/index.ts +0 -21
  195. package/src/runtime/node-builtins.d.ts +0 -27
  196. package/src/runtime/node.ts +0 -300
  197. package/src/runtime/paths.ts +0 -64
  198. package/src/runtime/support.ts +0 -135
  199. package/src/runtime.ts +0 -31
  200. package/src/strings.ts +0 -34
  201. package/src/testkit.ts +0 -25
  202. package/src/version.ts +0 -20
@@ -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,6 +1,6 @@
1
1
  {
2
2
  "name": "@kjanat/dreamcli",
3
- "version": "2.5.0",
3
+ "version": "3.0.0-rc.10",
4
4
  "description": "Schema-first, fully typed TypeScript CLI framework",
5
5
  "keywords": [
6
6
  "dreamcli",
@@ -8,7 +8,8 @@
8
8
  "typescript",
9
9
  "framework",
10
10
  "schema-first",
11
- "command-line"
11
+ "command-line",
12
+ "ansispeck"
12
13
  ],
13
14
  "homepage": "https://dreamcli.kjanat.dev",
14
15
  "bugs": {
@@ -36,42 +37,32 @@
36
37
  "exports": {
37
38
  ".": {
38
39
  "types": "./dist/index.d.mts",
39
- "bun": "./src/index.ts",
40
- "deno": "./src/index.ts",
41
40
  "default": "./dist/index.mjs"
42
41
  },
43
42
  "./runtime": {
44
43
  "types": "./dist/runtime.d.mts",
45
- "bun": "./src/runtime.ts",
46
- "deno": "./src/runtime.ts",
47
44
  "default": "./dist/runtime.mjs"
48
45
  },
49
46
  "./testkit": {
50
47
  "types": "./dist/testkit.d.mts",
51
- "bun": "./src/testkit.ts",
52
- "deno": "./src/testkit.ts",
53
48
  "default": "./dist/testkit.mjs"
54
49
  },
55
- "./schema": "./dreamcli.schema.json",
56
- "./package.json": "./package.json"
50
+ "./version": {
51
+ "types": "./dist/version.d.mts",
52
+ "default": "./dist/version.mjs"
53
+ },
54
+ "./package.json": "./package.json",
55
+ "./schema": "./dreamcli.schema.json"
57
56
  },
58
57
  "files": [
59
58
  "CHANGELOG.md",
60
- "LICENSE",
61
- "README.md",
62
59
  "dist",
63
60
  "dreamcli.schema.json",
64
61
  "examples",
65
- "!examples/.cache",
66
- "package.json",
67
- "src",
68
- "!src/**/*.test.ts",
69
- "!src/**/*test-helpers.ts",
62
+ "!**/.cache",
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",
@@ -84,8 +75,9 @@
84
75
  "docs:dev": "bun --bun vitepress dev docs --host --port ${PORT:-5173}",
85
76
  "docs:preview": "bun --bun vitepress preview docs",
86
77
  "docs:upload": "wrangler versions upload",
87
- "fmt": "dprint fmt",
78
+ "fmt": "run -s lint:fix fmt:dprint",
88
79
  "fmt:autofix": "dprint fmt --allow-no-files --excludes .github",
80
+ "fmt:dprint": "dprint fmt",
89
81
  "fmt:update": "dprint config update --yes --recursive",
90
82
  "format": "dprint fmt",
91
83
  "format:check": "dprint check",
@@ -96,9 +88,9 @@
96
88
  "gh-project:start": "bun gh-project start",
97
89
  "gh-project:sync": "bun gh-project sync",
98
90
  "knip": "knip",
99
- "lint": "biome lint",
91
+ "lint": "biome check",
100
92
  "lint:autofix": "biome check --skip-parse-errors --no-errors-on-unmatched --changed --write",
101
- "lint:fix": "biome lint --fix",
93
+ "lint:fix": "biome check --fix",
102
94
  "meta-descriptions": "bun --bun scripts/build-meta-descriptions.ts",
103
95
  "meta-descriptions:check": "bun --bun scripts/build-meta-descriptions.ts --check",
104
96
  "prepack": "bun --bun tsdown --logLevel silent",
@@ -109,39 +101,41 @@
109
101
  "test:gh": "run --dir examples/gh test",
110
102
  "test:node": "npx -y vitest run",
111
103
  "test:watch": "vitest",
112
- "typecheck": "tsgo --noEmit",
104
+ "typecheck": "bunx @typescript/native --noEmit",
113
105
  "typecheck:gh": "run --dir examples/gh typecheck",
114
- "typecheck:tsc": "tsc --noEmit",
115
106
  "upgrade": "bun update --latest && bun add -D vitepress@next",
116
107
  "version:check": "bun scripts/check-version-sync.ts"
117
108
  },
118
109
  "overrides": {
119
110
  "vitepress": "next"
120
111
  },
112
+ "dependencies": {
113
+ "ansispeck": "^0.2.0"
114
+ },
121
115
  "devDependencies": {
122
- "@arethetypeswrong/core": "^0.18.4",
123
- "@biomejs/biome": "^2.5.1",
116
+ "@arethetypeswrong/core": "^0.18.5",
117
+ "@biomejs/biome": "<=2.5.2 || >=2.5.4",
124
118
  "@iarna/toml": "^2.2.5",
125
- "@shikijs/transformers": "^4.2.0",
126
- "@shikijs/vitepress-twoslash": "^4.2.0",
119
+ "@shikijs/transformers": "^4.3.1",
120
+ "@shikijs/vitepress-twoslash": "^4.3.1",
127
121
  "@types/bun": "^1.3.14",
128
122
  "@types/deno": "^2.7.0",
129
- "@types/node": ">=22.0.0, <23.0.0",
130
- "@typescript/native-preview": "^7.0.0-dev",
131
- "@vitest/coverage-v8": "^4.1.9",
132
- "dprint": "^0.54.0",
123
+ "@types/node": ">=26.1.1",
124
+ "@typescript/native": "npm:typescript@^7",
125
+ "@vitest/coverage-v8": "^4.1.10",
126
+ "dprint": "^0.55.1",
133
127
  "floating-vue": "^5.2.2",
134
- "knip": "^6.18.0",
135
- "mermaid": "^11.15.0",
128
+ "knip": "^6.25.0",
129
+ "mermaid": "^11.16.0",
136
130
  "publint": "^0.3.21",
137
- "runner-run": "0.14.0",
138
- "tsdown": "^0.22.3",
139
- "typedoc": "^0.28.19",
140
- "typescript": "^6.0.3",
141
- "vite": "^8.1.0",
142
- "vitepress": "^2.0.0-alpha.17",
143
- "vitest": "^4.1.9",
144
- "wrangler": "^4.104.0",
131
+ "runner-run": "0.19.1",
132
+ "tsdown": "^0.22.4",
133
+ "typedoc": "^0.28.20",
134
+ "typescript": ">=6,<7",
135
+ "vite": "^8.1.4",
136
+ "vitepress": "^2.0.0-alpha.18",
137
+ "vitest": "^4.1.10",
138
+ "wrangler": "^4.110.0",
145
139
  "yaml": "^2.9.0"
146
140
  },
147
141
  "packageManager": "bun@1.3.14",
@@ -161,16 +155,16 @@
161
155
  }
162
156
  },
163
157
  "volta": {
164
- "node": "26.3.1",
165
- "npm": "11.17.0"
158
+ "node": "26.4.0",
159
+ "npm": "11.18.0"
166
160
  },
167
161
  "publishConfig": {
168
- "access": "public",
169
- "provenance": true
162
+ "access": "public"
170
163
  },
171
164
  "catalog": {
172
165
  "@types/bun": "^1.3.14",
173
- "@types/node": ">=22.0.0, <23.0.0",
174
- "typescript": "^6.0.3"
166
+ "@types/node": ">=26.1.1",
167
+ "@typescript/native": "npm:typescript@^7",
168
+ "typescript": ">=6,<7"
175
169
  }
176
170
  }
@@ -1,28 +0,0 @@
1
- import { RuntimeAdapter } from "./adapter.mjs";
2
- import { NodeProcess } from "./node.mjs";
3
-
4
- //#region src/runtime/bun.d.ts
5
- /**
6
- * Create a runtime adapter backed by Bun's Node-compatible `process` global.
7
- *
8
- * Bun exposes `globalThis.process` with the same shape as Node.js, so this
9
- * delegates entirely to {@link createNodeAdapter}. If Bun-specific optimizations
10
- * are needed in the future (e.g. `Bun.write` for I/O), they can be layered
11
- * here without changing the public API.
12
- *
13
- * @param proc - Override the process object (useful for testing the adapter itself).
14
- * @returns A {@linkcode RuntimeAdapter} backed by Bun's process state.
15
- *
16
- * @example
17
- * ```ts
18
- * import { cli } from '@kjanat/dreamcli';
19
- * import { createBunAdapter } from '@kjanat/dreamcli/runtime';
20
- *
21
- * cli('mycli')
22
- * .command(deploy)
23
- * .run({ adapter: createBunAdapter() });
24
- * ```
25
- */
26
- declare function createBunAdapter(proc?: NodeProcess): RuntimeAdapter;
27
- //#endregion
28
- export { createBunAdapter };
@@ -1 +0,0 @@
1
- import{assertRuntimeVersionSupported as e}from"./support.mjs";import{createNodeAdapter as t}from"./node.mjs";function n(e){return e?.versions?.bun===void 0?globalThis.Bun?.version:e.versions.bun}function r(r){return e(`bun`,n(r)),t(r)}export{r as createBunAdapter};
@@ -1,42 +0,0 @@
1
- //#region src/runtime/support.d.ts
2
- /**
3
- * Runtime compatibility matrix and version guard helpers.
4
- *
5
- * Keeps the supported runtime story in one place so adapter guards,
6
- * package engines, and docs can stay aligned.
7
- *
8
- * @internal
9
- * @module @kjanat/dreamcli/runtime/support
10
- */
11
- type SupportedRuntime = 'node' | 'bun' | 'deno';
12
- /**
13
- * Support entry for a single runtime: version bounds, display names, and adapter mapping.
14
- *
15
- * @internal
16
- */
17
- interface RuntimeSupportEntry {
18
- /** Runtime identifier key. */
19
- readonly runtime: SupportedRuntime;
20
- /** Human-readable name (e.g. `'Node.js'`, `'Bun'`). */
21
- readonly displayName: string;
22
- /** Minimum supported version (semver, e.g. `'22.22.2'`). */
23
- readonly minimum: string;
24
- /** `engines` range string for package.json (e.g. `'>=22.22.2'`). */
25
- readonly engineRange: string;
26
- /** npm/JSR package name that ships this adapter. */
27
- readonly packageName: string;
28
- /** Adapter factory function name (e.g. `'NodeAdapter'`). */
29
- readonly adapterName: string;
30
- }
31
- /** All supported runtimes with their version bounds and adapter metadata. @internal */
32
- declare const SUPPORTED_RUNTIMES: readonly RuntimeSupportEntry[];
33
- /** Look up the support entry for a given runtime. Throws on unknown runtime. @internal */
34
- declare function getRuntimeSupport(runtime: SupportedRuntime): RuntimeSupportEntry;
35
- /** Format a human-readable version requirement string (e.g. `'Node.js >= 22.22.2'`). @internal */
36
- declare function formatRuntimeRequirement(runtime: SupportedRuntime): string;
37
- /** Check whether a version string meets the minimum for the given runtime. @internal */
38
- declare function isRuntimeVersionSupported(runtime: SupportedRuntime, version: string): boolean;
39
- /** Throw if the detected version is below the minimum. No-op when version is undefined. @internal */
40
- declare function assertRuntimeVersionSupported(runtime: SupportedRuntime, version: string | undefined): void;
41
- //#endregion
42
- export { type RuntimeSupportEntry, SUPPORTED_RUNTIMES, type SupportedRuntime, assertRuntimeVersionSupported, formatRuntimeRequirement, getRuntimeSupport, isRuntimeVersionSupported };
@@ -1 +0,0 @@
1
- const e=[{runtime:`node`,displayName:`Node.js`,minimum:`22.22.2`,engineRange:`>=22.22.2`,packageName:`@kjanat/dreamcli`,adapterName:`NodeAdapter`},{runtime:`bun`,displayName:`Bun`,minimum:`1.3`,engineRange:`>=1.3`,packageName:`@kjanat/dreamcli`,adapterName:`BunAdapter`},{runtime:`deno`,displayName:`Deno`,minimum:`2.6.0`,engineRange:`>=2.6.0`,packageName:`@kjanat/dreamcli`,adapterName:`DenoAdapter`}],t=/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/;function n(t){for(let n of e)if(n.runtime===t)return n;throw Error(`Unknown supported runtime '${t}'`)}function r(e){let n=t.exec(e);if(n===null)return;let r=Number.parseInt(n[1]??``,10),i=n[2],a=i===void 0?0:Number.parseInt(i,10),o=n[3],s=o===void 0?0:Number.parseInt(o,10);if(!(Number.isNaN(r)||Number.isNaN(a)||Number.isNaN(s)))return{major:r,minor:a,patch:s}}function i(e,t){return e.major===t.major?e.minor===t.minor?e.patch-t.patch:e.minor-t.minor:e.major-t.major}function a(e){let t=n(e);return`${t.displayName} >= ${t.minimum}`}function o(e,t){let a=r(t),o=r(n(e).minimum);return a===void 0||o===void 0?!1:i(a,o)>=0}function s(e,t){if(t!==void 0&&!o(e,t))throw Error(`@kjanat/dreamcli requires ${a(e)}. Detected ${n(e).displayName} ${t}.`)}export{s as assertRuntimeVersionSupported};
@@ -1,349 +0,0 @@
1
- /**
2
- * Recursive command dispatch for nested command trees.
3
- *
4
- * Walks argv segments, matching command names at each level of the tree.
5
- * Returns a discriminated union describing the dispatch outcome: a matched
6
- * command with its ancestor path, a group that needs a subcommand, or an
7
- * unknown command with suggestion candidates.
8
- *
9
- * @module dreamcli/core/cli/dispatch
10
- * @internal
11
- */
12
-
13
- import { buildFlagLookup, flagExpectsValue } from '#internals/core/parse/index.ts';
14
- import type { CommandSchema, ErasedCommand } from '#internals/core/schema/command.ts';
15
- import type { FlagSchema } from '#internals/core/schema/flag.ts';
16
-
17
- /**
18
- * Flag lookup (name/alias → `[canonicalName, schema]`) used to make the
19
- * command-name scan aware of value-flag arity. Built from the flags valid at
20
- * the current dispatch level via {@link buildFlagLookup}.
21
- *
22
- * @internal
23
- */
24
- type ValueFlagLookup = ReadonlyMap<string, readonly [name: string, schema: FlagSchema]>;
25
-
26
- // --- Dispatch result types (discriminated union)
27
-
28
- /** Successful dispatch — target command found with argv path. */
29
- interface DispatchMatch {
30
- /** Discriminant — a command name in argv matched a registered command. */
31
- readonly kind: 'match';
32
- /** The matched (target) command. */
33
- readonly command: ErasedCommand;
34
- /** Root → target (inclusive). Used for `collectPropagatedFlags()`. */
35
- readonly commandPath: readonly CommandSchema[];
36
- /** argv after consuming command name segments. */
37
- readonly remainingArgv: readonly string[];
38
- }
39
-
40
- /** Target has subcommands but no handler and no subcommand was specified/matched. */
41
- interface DispatchNeedsSubcommand {
42
- /** Discriminant — command group reached without a subcommand or handler. */
43
- readonly kind: 'needs-subcommand';
44
- /** The group command that needs a subcommand. */
45
- readonly command: ErasedCommand;
46
- /** Root → group (inclusive). */
47
- readonly commandPath: readonly CommandSchema[];
48
- }
49
-
50
- /** Unknown command name at this dispatch level. */
51
- interface DispatchUnknown {
52
- /** Discriminant — no registered command matched the input token. */
53
- readonly kind: 'unknown';
54
- /** The unrecognised input token. Empty string when no token present. */
55
- readonly input: string;
56
- /** Commands available at the level where matching failed. */
57
- readonly candidates: readonly ErasedCommand[];
58
- /** Ancestor path up to (but not including) the unknown level. */
59
- readonly parentPath: readonly CommandSchema[];
60
- }
61
-
62
- /** Discriminated result of recursive command dispatch. */
63
- type DispatchResult = DispatchMatch | DispatchNeedsSubcommand | DispatchUnknown;
64
-
65
- // --- Recursive dispatch
66
-
67
- /**
68
- * Recursively walk argv, consuming command name segments from the front.
69
- *
70
- * At each level, the first non-flag token is tested as a command name
71
- * against the provided command map. If matched and the matched command
72
- * has subcommands, dispatch recurses into the child level with the
73
- * remaining argv.
74
- *
75
- * Ambiguity resolution for commands that have both an action handler AND
76
- * subcommands (e.g. `git remote` lists remotes, `git remote add` dispatches):
77
- * - If the next token matches a subcommand → descend
78
- * - If the next token is unknown and the command has a handler → match here
79
- * - If the next token is unknown and no handler → propagate unknown error
80
- * - If no next token and command has a handler → match here
81
- * - If no next token and no handler → needs-subcommand
82
- *
83
- * @param argv - Remaining argv tokens (command names + flags + args).
84
- * @param commands - Command map at the current tree level.
85
- * @param ancestorPath - Schema path from root to current level (exclusive).
86
- * @param valueFlags - Lookup of flags valid at this level, used so a
87
- * space-separated value-flag's value (`--region eu`) is not mistaken for a
88
- * command name. Empty by default (arity-unaware, legacy behaviour).
89
- * @returns Discriminated dispatch result.
90
- *
91
- * @internal
92
- */
93
- function dispatch(
94
- argv: readonly string[],
95
- commands: ReadonlyMap<string, ErasedCommand>,
96
- ancestorPath: readonly CommandSchema[] = [],
97
- valueFlags: ValueFlagLookup = new Map(),
98
- ): DispatchResult {
99
- // Find first non-flag token (potential command name).
100
- // Flags may appear before the command name (e.g. `--verbose db migrate`).
101
- // `--` terminates flag scanning — the next token is treated as a command name.
102
- // Value-flags in space-separated form (`--region eu`, `-r eu`) consume the
103
- // following token as their value, so it must be skipped rather than matched
104
- // as a command name (see #25).
105
- let cmdIdx = -1;
106
- for (let i = 0; i < argv.length; i++) {
107
- const token = argv[i];
108
- if (token === undefined) continue;
109
- if (token === '--') {
110
- // End-of-flags marker: next token (if any) is the command name.
111
- if (i + 1 < argv.length) cmdIdx = i + 1;
112
- break;
113
- }
114
- if (token.startsWith('-')) {
115
- if (consumesFollowingToken(token, valueFlags)) i++; // skip the flag's value
116
- continue;
117
- }
118
- cmdIdx = i;
119
- break;
120
- }
121
-
122
- if (cmdIdx === -1) {
123
- // No command name token found — only flags or empty argv.
124
- return {
125
- kind: 'unknown',
126
- input: '',
127
- candidates: uniqueCommands(commands),
128
- parentPath: ancestorPath,
129
- };
130
- }
131
-
132
- const cmdName = argv[cmdIdx];
133
- if (cmdName === undefined) {
134
- return {
135
- kind: 'unknown',
136
- input: '',
137
- candidates: uniqueCommands(commands),
138
- parentPath: ancestorPath,
139
- };
140
- }
141
-
142
- const matched = commands.get(cmdName);
143
- if (matched === undefined) {
144
- return {
145
- kind: 'unknown',
146
- input: cmdName,
147
- candidates: uniqueCommands(commands),
148
- parentPath: ancestorPath,
149
- };
150
- }
151
-
152
- // Remove command name token from argv, preserving order.
153
- const remaining = [...argv.slice(0, cmdIdx), ...argv.slice(cmdIdx + 1)];
154
- const currentPath = [...ancestorPath, matched.schema];
155
-
156
- // If command has subcommands, try to descend. The matched command's own
157
- // flags govern arity at the child level (e.g. `db --config x migrate`).
158
- if (matched.subcommands.size > 0) {
159
- const subResult = dispatch(
160
- remaining,
161
- matched.subcommands,
162
- currentPath,
163
- buildFlagLookup(matched.schema.flags),
164
- );
165
-
166
- switch (subResult.kind) {
167
- case 'match':
168
- // Successfully found deeper target.
169
- return subResult;
170
-
171
- case 'unknown':
172
- if (subResult.input === '') {
173
- // No subcommand specified.
174
- if (matched.schema.hasAction) {
175
- return {
176
- kind: 'match',
177
- command: matched,
178
- commandPath: currentPath,
179
- remainingArgv: remaining,
180
- };
181
- }
182
- return { kind: 'needs-subcommand', command: matched, commandPath: currentPath };
183
- }
184
-
185
- // Unknown token — might be a positional arg for this command.
186
- if (matched.schema.hasAction) {
187
- return {
188
- kind: 'match',
189
- command: matched,
190
- commandPath: currentPath,
191
- remainingArgv: remaining,
192
- };
193
- }
194
- // No handler — propagate the unknown error.
195
- return subResult;
196
-
197
- case 'needs-subcommand':
198
- // Propagate from deeper level.
199
- return subResult;
200
-
201
- default: {
202
- // Exhaustiveness guard — ensures all DispatchResult variants are handled.
203
- const _exhaustive: never = subResult;
204
- return _exhaustive;
205
- }
206
- }
207
- }
208
-
209
- // Leaf command (no subcommands).
210
- return {
211
- kind: 'match',
212
- command: matched,
213
- commandPath: currentPath,
214
- remainingArgv: remaining,
215
- };
216
- }
217
-
218
- // --- Flag-arity awareness
219
-
220
- /**
221
- * Whether a flag token consumes the following argv token as its value.
222
- *
223
- * Mirrors the parser's value-consumption rules (`parseLongFlag` /
224
- * `parseShortFlags`) so the command-name scan skips exactly the tokens the
225
- * parser would treat as flag values:
226
- * - `--flag value` → consumes when `--flag` is a known value-flag.
227
- * - `--flag=value` → self-contained, consumes nothing.
228
- * - `-abc value` → consumes only when the trailing short flag is a value-flag;
229
- * an earlier value-flag char takes the rest of the group as an inline value.
230
- *
231
- * Unknown flags conservatively consume nothing (the parser reports them later).
232
- *
233
- * @internal
234
- */
235
- function consumesFollowingToken(token: string, valueFlags: ValueFlagLookup): boolean {
236
- if (token.startsWith('--')) {
237
- if (token.includes('=')) return false;
238
- const entry = valueFlags.get(token.slice(2));
239
- return entry !== undefined && flagExpectsValue(entry[1]);
240
- }
241
-
242
- // Short flag group (`-abc`). A value attaches to the trailing flag only; an
243
- // earlier value-flag char swallows the remaining chars as an inline value.
244
- const chars = token.slice(1);
245
- for (let i = 0; i < chars.length; i++) {
246
- const entry = valueFlags.get(chars.charAt(i));
247
- if (entry === undefined) return false;
248
- if (!flagExpectsValue(entry[1])) continue;
249
- return i === chars.length - 1;
250
- }
251
- return false;
252
- }
253
-
254
- // --- "Did you mean?" suggestion
255
-
256
- /**
257
- * Levenshtein distance between two strings.
258
- * @internal
259
- */
260
- function levenshtein(a: string, b: string): number {
261
- const m = a.length;
262
- const n = b.length;
263
-
264
- // Flat (m+1)×(n+1) matrix — fully initialised, no sparse access.
265
- // Two-row rolling buffer: only the previous and current rows are needed.
266
- const w = n + 1;
267
- let prev = new Uint16Array(w);
268
- let curr = new Uint16Array(w);
269
-
270
- // Base row: distance from empty string to b[0..j]
271
- for (let j = 0; j <= n; j++) prev[j] = j;
272
-
273
- for (let i = 1; i <= m; i++) {
274
- curr[0] = i;
275
- for (let j = 1; j <= n; j++) {
276
- const cost = a.charAt(i - 1) === b.charAt(j - 1) ? 0 : 1;
277
- // All indices are in-bounds: j ∈ [1,n], j-1 ∈ [0,n-1], both < w.
278
- // prev/curr are dense Uint16Arrays of length w — no holes.
279
- const del = prev[j] ?? 0;
280
- const ins = curr[j - 1] ?? 0;
281
- const sub = prev[j - 1] ?? 0;
282
- curr[j] = Math.min(del + 1, ins + 1, sub + cost);
283
- }
284
- [prev, curr] = [curr, prev];
285
- }
286
-
287
- // After the loop, `prev` holds the last computed row (swapped at loop end).
288
- return prev[n] ?? Math.max(m, n);
289
- }
290
-
291
- /**
292
- * Find the closest command name match for a "did you mean?" suggestion.
293
- *
294
- * Searches command names and aliases. Returns `undefined` if no
295
- * sufficiently close match exists (threshold: 3).
296
- *
297
- * @internal
298
- */
299
- function findClosestCommand(input: string, commands: readonly ErasedCommand[]): string | undefined {
300
- const MAX_DISTANCE = 3;
301
- let bestName: string | undefined;
302
- let bestDist = MAX_DISTANCE + 1;
303
-
304
- for (const cmd of commands) {
305
- // Check main name
306
- const nameDist = levenshtein(input, cmd.schema.name);
307
- if (nameDist < bestDist) {
308
- bestDist = nameDist;
309
- bestName = cmd.schema.name;
310
- }
311
- // Check aliases
312
- for (const alias of cmd.schema.aliases) {
313
- const aliasDist = levenshtein(input, alias);
314
- if (aliasDist < bestDist) {
315
- bestDist = aliasDist;
316
- bestName = cmd.schema.name; // suggest canonical name
317
- }
318
- }
319
- }
320
-
321
- return bestDist <= MAX_DISTANCE ? bestName : undefined;
322
- }
323
-
324
- // --- Helpers
325
-
326
- /**
327
- * Deduplicate commands from a name+alias map.
328
- *
329
- * A map keyed by name *and* alias contains duplicate entries for aliased
330
- * commands. This returns unique commands (by schema identity).
331
- *
332
- * @internal
333
- */
334
- function uniqueCommands(commands: ReadonlyMap<string, ErasedCommand>): readonly ErasedCommand[] {
335
- const seen = new Set<ErasedCommand>();
336
- const result: ErasedCommand[] = [];
337
- for (const cmd of commands.values()) {
338
- if (!seen.has(cmd)) {
339
- seen.add(cmd);
340
- result.push(cmd);
341
- }
342
- }
343
- return result;
344
- }
345
-
346
- // --- Exports
347
-
348
- export type { DispatchMatch, DispatchNeedsSubcommand, DispatchResult, DispatchUnknown, ValueFlagLookup };
349
- export { consumesFollowingToken, dispatch, findClosestCommand, levenshtein, uniqueCommands };