@kjanat/dreamcli 1.0.0 → 2.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 (217) hide show
  1. package/CHANGELOG.md +45 -6
  2. package/LICENSE +1 -1
  3. package/README.md +296 -164
  4. package/dist/core/cli/dispatch.d.mts +85 -0
  5. package/dist/core/cli/dispatch.mjs +1 -0
  6. package/dist/core/cli/index.d.mts +418 -0
  7. package/dist/core/cli/index.mjs +1 -0
  8. package/dist/core/cli/planner.d.mts +143 -0
  9. package/dist/core/cli/planner.mjs +1 -0
  10. package/dist/core/cli/plugin.d.mts +94 -0
  11. package/dist/core/cli/plugin.mjs +1 -0
  12. package/dist/core/cli/propagate.d.mts +39 -0
  13. package/dist/core/cli/propagate.mjs +1 -0
  14. package/dist/core/cli/root-help.d.mts +28 -0
  15. package/dist/core/cli/root-help.mjs +7 -0
  16. package/dist/core/cli/root-surface.d.mts +42 -0
  17. package/dist/core/cli/root-surface.mjs +1 -0
  18. package/dist/core/cli/runtime-preflight.d.mts +149 -0
  19. package/dist/core/cli/runtime-preflight.mjs +1 -0
  20. package/dist/core/completion/index.d.mts +46 -0
  21. package/dist/core/completion/index.mjs +1 -0
  22. package/dist/core/completion/shells/bash.d.mts +24 -0
  23. package/dist/core/completion/shells/bash.mjs +3 -0
  24. package/dist/core/completion/shells/fish.d.mts +20 -0
  25. package/dist/core/completion/shells/fish.mjs +2 -0
  26. package/dist/core/completion/shells/powershell.d.mts +14 -0
  27. package/dist/core/completion/shells/powershell.mjs +2 -0
  28. package/dist/core/completion/shells/shared.d.mts +139 -0
  29. package/dist/core/completion/shells/shared.mjs +1 -0
  30. package/dist/core/completion/shells/zsh.d.mts +24 -0
  31. package/dist/core/completion/shells/zsh.mjs +2 -0
  32. package/dist/core/config/index.d.mts +161 -0
  33. package/dist/core/config/index.mjs +1 -0
  34. package/dist/core/config/package-json.d.mts +68 -0
  35. package/dist/core/config/package-json.mjs +1 -0
  36. package/dist/core/errors/index.d.mts +126 -0
  37. package/dist/core/errors/index.mjs +1 -0
  38. package/dist/core/execution/index.d.mts +49 -0
  39. package/dist/core/execution/index.mjs +1 -0
  40. package/dist/core/help/index.d.mts +49 -0
  41. package/dist/core/help/index.mjs +8 -0
  42. package/dist/core/json-schema/index.d.mts +109 -0
  43. package/dist/core/json-schema/index.mjs +55 -0
  44. package/dist/core/json-schema/meta-descriptions.generated.d.mts +185 -0
  45. package/dist/core/json-schema/meta-descriptions.generated.mjs +28 -0
  46. package/dist/core/output/activity.d.mts +194 -0
  47. package/dist/core/output/activity.mjs +1 -0
  48. package/dist/core/output/contracts.d.mts +88 -0
  49. package/dist/core/output/contracts.mjs +1 -0
  50. package/dist/core/output/display-value.d.mts +19 -0
  51. package/dist/core/output/display-value.mjs +1 -0
  52. package/dist/core/output/index.d.mts +280 -0
  53. package/dist/core/output/index.mjs +2 -0
  54. package/dist/core/output/renderers.d.mts +46 -0
  55. package/dist/core/output/renderers.mjs +1 -0
  56. package/dist/core/output/writer.d.mts +40 -0
  57. package/dist/core/output/writer.mjs +1 -0
  58. package/dist/core/parse/index.d.mts +79 -0
  59. package/dist/core/parse/index.mjs +1 -0
  60. package/dist/core/prompt/index.d.mts +205 -0
  61. package/dist/core/prompt/index.mjs +6 -0
  62. package/dist/core/resolve/args.d.mts +8 -0
  63. package/dist/core/resolve/args.mjs +1 -0
  64. package/dist/core/resolve/coerce.d.mts +22 -0
  65. package/dist/core/resolve/coerce.mjs +1 -0
  66. package/dist/core/resolve/config.d.mts +10 -0
  67. package/dist/core/resolve/config.mjs +1 -0
  68. package/dist/core/resolve/contracts.d.mts +112 -0
  69. package/dist/core/resolve/errors.d.mts +11 -0
  70. package/dist/core/resolve/errors.mjs +2 -0
  71. package/dist/core/resolve/flags.d.mts +10 -0
  72. package/dist/core/resolve/flags.mjs +1 -0
  73. package/dist/core/resolve/index.d.mts +42 -0
  74. package/dist/core/resolve/index.mjs +1 -0
  75. package/dist/core/resolve/property.d.mts +47 -0
  76. package/dist/core/resolve/property.mjs +1 -0
  77. package/dist/core/schema/activity.d.mts +169 -0
  78. package/dist/core/schema/arg.d.mts +559 -0
  79. package/dist/core/schema/arg.mjs +1 -0
  80. package/dist/core/schema/command.d.mts +960 -0
  81. package/dist/core/schema/command.mjs +1 -0
  82. package/dist/core/schema/flag.d.mts +491 -0
  83. package/dist/core/schema/flag.mjs +1 -0
  84. package/dist/core/schema/index.d.mts +8 -0
  85. package/dist/core/schema/middleware.d.mts +122 -0
  86. package/dist/core/schema/middleware.mjs +1 -0
  87. package/dist/core/schema/prompt.d.mts +117 -0
  88. package/dist/core/schema/run.d.mts +171 -0
  89. package/dist/core/schema-dsl/runtime.d.mts +144 -0
  90. package/dist/core/schema-dsl/runtime.mjs +2 -0
  91. package/dist/core/schema-dsl/to-json-schema.d.mts +30 -0
  92. package/dist/core/schema-dsl/to-json-schema.mjs +1 -0
  93. package/dist/core/testkit/index.d.mts +54 -0
  94. package/dist/core/testkit/index.mjs +1 -0
  95. package/dist/index.d.mts +28 -920
  96. package/dist/index.mjs +1 -10
  97. package/dist/runtime/adapter.d.mts +212 -0
  98. package/dist/{adapter-B37d9oia.mjs → runtime/adapter.mjs} +1 -1
  99. package/dist/runtime/auto.d.mts +26 -0
  100. package/dist/runtime/auto.mjs +1 -0
  101. package/dist/runtime/bun.d.mts +28 -0
  102. package/dist/runtime/bun.mjs +1 -0
  103. package/dist/runtime/deno.d.mts +76 -0
  104. package/dist/runtime/deno.mjs +2 -0
  105. package/dist/runtime/detect.d.mts +86 -0
  106. package/dist/runtime/detect.mjs +1 -0
  107. package/dist/runtime/index.d.mts +7 -0
  108. package/dist/runtime/node.d.mts +65 -0
  109. package/dist/runtime/node.mjs +2 -0
  110. package/dist/runtime/paths.d.mts +31 -0
  111. package/dist/runtime/paths.mjs +1 -0
  112. package/dist/runtime/support.d.mts +42 -0
  113. package/dist/runtime/support.mjs +1 -0
  114. package/dist/runtime.d.mts +6 -252
  115. package/dist/runtime.mjs +1 -1
  116. package/dist/testkit.d.mts +5 -24
  117. package/dist/testkit.mjs +1 -1
  118. package/dist/version.d.mts +16 -0
  119. package/dist/version.mjs +1 -0
  120. package/dreamcli.schema.json +338 -0
  121. package/examples/basic.ts +2 -2
  122. package/examples/gh/package.json +7 -11
  123. package/examples/gh/src/commands/auth.ts +2 -2
  124. package/examples/gh/src/commands/issue.ts +4 -4
  125. package/examples/gh/src/commands/pr.ts +4 -4
  126. package/examples/gh/src/docs.ts +11 -0
  127. package/examples/gh/src/lib/auth.ts +1 -1
  128. package/examples/gh/src/main.test.ts +6 -5
  129. package/examples/gh/src/main.ts +8 -6
  130. package/examples/interactive.ts +3 -3
  131. package/examples/json-mode.ts +4 -6
  132. package/examples/middleware.ts +3 -3
  133. package/examples/multi-command.ts +3 -3
  134. package/examples/spinner-progress.ts +5 -5
  135. package/examples/testing.ts +8 -6
  136. package/package.json +70 -44
  137. package/src/core/cli/dispatch.ts +4 -0
  138. package/src/core/cli/index.ts +185 -632
  139. package/src/core/cli/planner.ts +413 -0
  140. package/src/core/cli/plugin.ts +7 -1
  141. package/src/core/cli/propagate.ts +1 -1
  142. package/src/core/cli/runtime-preflight.ts +409 -0
  143. package/src/core/completion/index.ts +15 -9
  144. package/src/core/completion/shells/bash.ts +6 -3
  145. package/src/core/completion/shells/fish.ts +245 -10
  146. package/src/core/completion/shells/powershell.ts +390 -9
  147. package/src/core/completion/shells/shared.ts +4 -4
  148. package/src/core/completion/shells/zsh.ts +12 -7
  149. package/src/core/config/index.ts +7 -4
  150. package/src/core/config/package-json.ts +6 -2
  151. package/src/core/errors/index.ts +23 -8
  152. package/src/core/execution/index.ts +270 -0
  153. package/src/core/help/index.ts +13 -15
  154. package/src/core/json-schema/index.ts +193 -7
  155. package/src/core/json-schema/meta-descriptions.generated.ts +202 -0
  156. package/src/core/output/contracts.ts +194 -0
  157. package/src/core/output/index.ts +47 -82
  158. package/src/core/output/renderers.ts +125 -0
  159. package/src/core/parse/index.ts +39 -21
  160. package/src/core/prompt/index.ts +44 -27
  161. package/src/core/resolve/args.ts +144 -0
  162. package/src/core/resolve/coerce.ts +432 -0
  163. package/src/core/resolve/config.ts +26 -0
  164. package/src/core/resolve/contracts.ts +135 -0
  165. package/src/core/resolve/errors.ts +227 -0
  166. package/src/core/resolve/flags.ts +205 -0
  167. package/src/core/resolve/index.ts +41 -1264
  168. package/src/core/resolve/property.ts +99 -0
  169. package/src/core/schema/activity.ts +3 -0
  170. package/src/core/schema/arg.ts +26 -14
  171. package/src/core/schema/command.ts +265 -38
  172. package/src/core/schema/flag.ts +120 -15
  173. package/src/core/schema/index.ts +11 -2
  174. package/src/core/schema/middleware.ts +6 -6
  175. package/src/core/schema/prompt.ts +9 -1
  176. package/src/core/schema/run.ts +25 -17
  177. package/src/core/schema-dsl/index.ts +109 -0
  178. package/src/core/schema-dsl/parse.ts +262 -0
  179. package/src/core/schema-dsl/runtime.ts +609 -0
  180. package/src/core/schema-dsl/to-json-schema.ts +102 -0
  181. package/src/core/testkit/index.ts +55 -297
  182. package/src/index.ts +10 -4
  183. package/src/runtime/adapter.ts +13 -10
  184. package/src/runtime/auto.ts +3 -3
  185. package/src/runtime/bun.ts +4 -4
  186. package/src/runtime/deno.ts +43 -29
  187. package/src/runtime/detect.ts +4 -1
  188. package/src/runtime/index.ts +1 -1
  189. package/src/runtime/node.ts +43 -21
  190. package/src/runtime/paths.ts +9 -3
  191. package/src/runtime/support.ts +20 -4
  192. package/src/runtime.ts +1 -1
  193. package/src/testkit.ts +10 -8
  194. package/dist/adapter-CCSh5juX.cjs +0 -1
  195. package/dist/adapter-DIwO-q7K.d.mts +0 -3447
  196. package/dist/adapter-DQnxxLiE.d.cts +0 -3447
  197. package/dist/auto-5cjZaF9V.mjs +0 -3
  198. package/dist/auto-B0eSgoDw.cjs +0 -3
  199. package/dist/index.cjs +0 -10
  200. package/dist/index.d.cts +0 -920
  201. package/dist/runtime.cjs +0 -1
  202. package/dist/runtime.d.cts +0 -253
  203. package/dist/testkit-CEDYPvhF.mjs +0 -14
  204. package/dist/testkit-ClIKijxC.cjs +0 -14
  205. package/dist/testkit.cjs +0 -1
  206. package/dist/testkit.d.cts +0 -25
  207. package/examples/gh/tsconfig.json +0 -37
  208. package/examples/tsconfig.json +0 -17
  209. package/src/core/cli/AGENTS.md +0 -72
  210. package/src/core/completion/AGENTS.md +0 -72
  211. package/src/core/completion/completion-test-helpers.ts +0 -48
  212. package/src/core/output/AGENTS.md +0 -69
  213. package/src/core/resolve/AGENTS.md +0 -69
  214. package/src/core/schema/AGENTS.md +0 -61
  215. package/src/core/testkit/AGENTS.md +0 -55
  216. package/src/runtime/AGENTS.md +0 -74
  217. package/src/runtime/test-helpers.ts +0 -40
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kjanat/dreamcli",
3
- "version": "1.0.0",
3
+ "version": "2.0.0",
4
4
  "description": "Schema-first, fully typed TypeScript CLI framework",
5
5
  "keywords": [
6
6
  "cli",
@@ -18,79 +18,83 @@
18
18
  "url": "git+https://github.com/kjanat/dreamcli.git"
19
19
  },
20
20
  "license": "MIT",
21
- "author": "Kaj Kowalski <info@kajkowalski.nl> (https://github.com/kjanat)",
21
+ "author": {
22
+ "name": "Kaj Kowalski",
23
+ "email": "info@kajkowalski.nl",
24
+ "url": "https://github.com/kjanat"
25
+ },
22
26
  "type": "module",
23
27
  "imports": {
24
28
  "#dreamcli": "./src/index.ts",
25
29
  "#dreamcli/runtime": "./src/runtime.ts",
26
30
  "#dreamcli/testkit": "./src/testkit.ts",
27
- "#internals/*": "./src/*"
31
+ "#internals/*": "./src/*",
32
+ "#schema": "./dreamcli.schema.json",
33
+ "#package.json": "./package.json"
28
34
  },
29
35
  "exports": {
30
36
  ".": {
37
+ "types": "./dist/index.d.mts",
31
38
  "bun": "./src/index.ts",
32
39
  "deno": "./src/index.ts",
33
- "types": {
34
- "import": "./dist/index.d.mts",
35
- "require": "./dist/index.d.cts",
36
- "default": "./dist/index.d.cts"
37
- },
38
- "import": "./dist/index.mjs",
39
- "require": "./dist/index.cjs",
40
- "default": "./dist/index.cjs"
40
+ "default": "./dist/index.mjs"
41
41
  },
42
42
  "./runtime": {
43
+ "types": "./dist/runtime.d.mts",
43
44
  "bun": "./src/runtime.ts",
44
45
  "deno": "./src/runtime.ts",
45
- "types": {
46
- "import": "./dist/runtime.d.mts",
47
- "require": "./dist/runtime.d.cts",
48
- "default": "./dist/runtime.d.cts"
49
- },
50
- "import": "./dist/runtime.mjs",
51
- "require": "./dist/runtime.cjs",
52
- "default": "./dist/runtime.cjs"
46
+ "default": "./dist/runtime.mjs"
53
47
  },
54
48
  "./testkit": {
49
+ "types": "./dist/testkit.d.mts",
55
50
  "bun": "./src/testkit.ts",
56
51
  "deno": "./src/testkit.ts",
57
- "types": {
58
- "import": "./dist/testkit.d.mts",
59
- "require": "./dist/testkit.d.cts",
60
- "default": "./dist/testkit.d.cts"
61
- },
62
- "import": "./dist/testkit.mjs",
63
- "require": "./dist/testkit.cjs",
64
- "default": "./dist/testkit.cjs"
52
+ "default": "./dist/testkit.mjs"
65
53
  },
54
+ "./schema": "./dreamcli.schema.json",
66
55
  "./package.json": "./package.json"
67
56
  },
68
57
  "files": [
69
- "README.md",
70
- "LICENSE",
71
58
  "CHANGELOG.md",
72
- "package.json",
59
+ "LICENSE",
60
+ "README.md",
73
61
  "dist",
62
+ "dreamcli.schema.json",
74
63
  "examples",
64
+ "!examples/.cache",
65
+ "package.json",
75
66
  "src",
76
- "!src/**/*.test.ts"
67
+ "!src/**/*.test.ts",
68
+ "!src/**/*test-helpers.ts",
69
+ "!**/AGENTS.md"
77
70
  ],
78
71
  "workspaces": [
79
- ".",
80
- "examples/*"
72
+ "./examples/*"
81
73
  ],
82
74
  "scripts": {
83
- "bd": "bun run build",
75
+ "bd": "bunx --bun tsdown",
84
76
  "build": "bunx --bun tsdown",
85
- "ci": "bun typecheck && bun lint && bun run test && bun bd",
86
- "docs:build": "vitepress build docs",
87
- "docs:dev": "vitepress dev docs",
88
- "docs:preview": "vitepress preview docs",
77
+ "build:watch": "bunx --bun tsdown --watch",
78
+ "ci": "bun typecheck && bun lint && bun run format:check && bun run meta-descriptions:check && bun run test && bun run docs:build && bun bd",
79
+ "coverage": "vitest run --coverage",
80
+ "dev": "bunx --bun tsdown --logLevel silent --watch & bunx --bun vitepress@next dev docs --host --port ${PORT:-5173} & wait",
81
+ "docs:build": "bunx --bun vitepress@next build docs",
82
+ "docs:dev": "bunx --bun vitepress@next dev docs",
83
+ "docs:preview": "bunx --bun vitepress@next preview docs",
89
84
  "fmt": "dprint fmt",
90
85
  "format": "dprint fmt",
91
86
  "format:check": "dprint check",
87
+ "gh-project": "bun scripts/gh-project.ts",
88
+ "gh-project:finish": "bun gh-project finish",
89
+ "gh-project:list": "bun gh-project list",
90
+ "gh-project:set": "bun gh-project set",
91
+ "gh-project:start": "bun gh-project start",
92
+ "gh-project:sync": "bun gh-project sync",
93
+ "knip": "knip",
92
94
  "lint": "biome lint",
93
95
  "lint:fix": "biome lint --fix",
96
+ "meta-descriptions": "bun --bun scripts/build-meta-descriptions.ts",
97
+ "meta-descriptions:check": "bun --bun scripts/build-meta-descriptions.ts --check",
94
98
  "prepack": "bunx --bun tsdown --logLevel silent",
95
99
  "test": "vitest run",
96
100
  "test:watch": "vitest",
@@ -99,37 +103,59 @@
99
103
  "upgrade": "bun update --latest && bun add -D vitepress@next"
100
104
  },
101
105
  "devDependencies": {
102
- "@arethetypeswrong/cli": "^0.18.2",
103
106
  "@arethetypeswrong/core": "^0.18.2",
104
107
  "@biomejs/biome": "^2.4.10",
105
108
  "@iarna/toml": "^2.2.5",
106
- "@types/bun": "catalog:",
109
+ "@shikijs/transformers": "^4.0.2",
110
+ "@shikijs/vitepress-twoslash": "^4.0.2",
111
+ "@types/bun": "^1.3.0",
107
112
  "@types/deno": "^2.5.0",
108
113
  "@types/node": ">=22.0.0, <23.0.0",
109
- "@typescript/native-preview": "^7.0.0-dev.20260401.1",
114
+ "@typescript/native-preview": "^7.0.0-dev.20260406.1",
110
115
  "@vitest/coverage-v8": "^4.1.2",
111
- "dprint": "^0.53.1",
116
+ "dprint": "^0.53.2",
117
+ "floating-vue": "^5.2.2",
118
+ "knip": "^6.3.0",
112
119
  "mermaid": "^11.14.0",
113
120
  "publint": "^0.3.18",
114
121
  "tsdown": "^0.21.7",
115
- "typescript": "catalog:",
122
+ "typedoc": "^0.28.18",
123
+ "typescript": "^6.0.2",
116
124
  "vitepress": "^2.0.0-alpha.17",
117
- "vitepress-plugin-mermaid": "^2.0.17",
118
125
  "vitest": "^4.1.2",
126
+ "wrangler": "^4.80.0",
119
127
  "yaml": "^2.8.3"
120
128
  },
129
+ "optionalDependencies": {
130
+ "vite": "^8"
131
+ },
121
132
  "packageManager": "bun@1.3.11",
122
133
  "engines": {
123
134
  "bun": ">=1.3.11",
124
135
  "deno": ">=2.6.0",
125
136
  "node": ">=22.22.2"
126
137
  },
138
+ "devEngines": {
139
+ "packageManager": {
140
+ "name": "bun",
141
+ "onFail": "warn"
142
+ },
143
+ "runtime": {
144
+ "name": "bun",
145
+ "onFail": "ignore"
146
+ }
147
+ },
127
148
  "volta": {
128
149
  "node": "25.8.2",
129
150
  "npm": "11.12.1"
130
151
  },
152
+ "publishConfig": {
153
+ "access": "public",
154
+ "provenance": true
155
+ },
131
156
  "catalog": {
132
157
  "@types/bun": "^1.3.0",
158
+ "@types/node": ">=22.0.0, <23.0.0",
133
159
  "typescript": "^6.0.2"
134
160
  }
135
161
  }
@@ -16,6 +16,7 @@ import type { CommandSchema, ErasedCommand } from '#internals/core/schema/comman
16
16
 
17
17
  /** Successful dispatch — target command found with argv path. */
18
18
  interface DispatchMatch {
19
+ /** Discriminant — a command name in argv matched a registered command. */
19
20
  readonly kind: 'match';
20
21
  /** The matched (target) command. */
21
22
  readonly command: ErasedCommand;
@@ -27,6 +28,7 @@ interface DispatchMatch {
27
28
 
28
29
  /** Target has subcommands but no handler and no subcommand was specified/matched. */
29
30
  interface DispatchNeedsSubcommand {
31
+ /** Discriminant — command group reached without a subcommand or handler. */
30
32
  readonly kind: 'needs-subcommand';
31
33
  /** The group command that needs a subcommand. */
32
34
  readonly command: ErasedCommand;
@@ -36,6 +38,7 @@ interface DispatchNeedsSubcommand {
36
38
 
37
39
  /** Unknown command name at this dispatch level. */
38
40
  interface DispatchUnknown {
41
+ /** Discriminant — no registered command matched the input token. */
39
42
  readonly kind: 'unknown';
40
43
  /** The unrecognised input token. Empty string when no token present. */
41
44
  readonly input: string;
@@ -45,6 +48,7 @@ interface DispatchUnknown {
45
48
  readonly parentPath: readonly CommandSchema[];
46
49
  }
47
50
 
51
+ /** Discriminated result of recursive command dispatch. */
48
52
  type DispatchResult = DispatchMatch | DispatchNeedsSubcommand | DispatchUnknown;
49
53
 
50
54
  // --- Recursive dispatch