@kjanat/dreamcli 1.0.0 → 2.0.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 (217) hide show
  1. package/CHANGELOG.md +63 -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
@@ -1,72 +0,0 @@
1
- # completion — Shell completion script generation
2
-
3
- Split into per-shell generators under `shells/`. Barrel `index.ts` re-exports public API and
4
- dispatches via `generateCompletion()`.
5
-
6
- ## FILES
7
-
8
- | File | Lines | Purpose |
9
- | ---------------------- | ----: | -------------------------------------------------------- |
10
- | `index.ts` | 80 | Barrel — `Shell` type, `SHELLS` constant, dispatch |
11
- | `shells/shared.ts` | 160 | `CommandNode`, `walkCommandTree`, escaping, `versionTag` |
12
- | `shells/bash.ts` | 275 | `generateBashCompletion()` + all bash helpers |
13
- | `shells/zsh.ts` | 280 | `generateZshCompletion()` + all zsh helpers |
14
- | `shells/fish.ts` | 25 | Stub — throws `UNSUPPORTED_OPERATION` |
15
- | `shells/powershell.ts` | 25 | Stub — throws `UNSUPPORTED_OPERATION` |
16
-
17
- ## PUBLIC API
18
-
19
- | Symbol | Exported from | Role |
20
- | -------------------------- | ------------- | ------------------------------------------------ |
21
- | `generateCompletion()` | `index.ts` | Shell-agnostic dispatch → per-shell generators |
22
- | `generateBashCompletion()` | `index.ts` | Bash completion script from command tree |
23
- | `generateZshCompletion()` | `index.ts` | Zsh completion script from command tree |
24
- | `SHELLS` | `index.ts` | `readonly ['bash', 'zsh', 'fish', 'powershell']` |
25
- | `CompletionOptions` | `index.ts` | Options type (re-exported from `shared.ts`) |
26
- | `Shell` | `index.ts` | Union type of supported shells |
27
-
28
- ## ARCHITECTURE
29
-
30
- 1. Walk command tree → `CommandNode[]` (shared infrastructure in `shells/shared.ts`)
31
- 2. Per-shell generator receives `CLISchema` + `CompletionOptions`, calls `walkCommandTree()`
32
- 3. Emit shell-specific functions (one per command node)
33
- 4. Bash: `complete -F` with `compgen`; Zsh: `_arguments` + `_describe`
34
-
35
- Handles nested command groups: `mycli db migrate` generates completions for each depth level.
36
-
37
- ## INTERNAL HELPERS (all `@internal`)
38
-
39
- ### `shells/shared.ts`
40
-
41
- - `versionTag()` — build-time version string for script headers
42
- - `CommandNode` — flattened tree node with propagated flag context
43
- - `walkCommandTree()` — depth-first command tree walker
44
- - `sanitizeShellIdentifier()`, `quoteShellArg()` — shell escaping
45
-
46
- ### `shells/bash.ts`
47
-
48
- - `emitBashPathDetection`, `quoteShellCasePattern` — subcommand path detection
49
- - `escapeForSingleQuote`, `escapeBashDollarQuote` — bash string escaping
50
- - `formatBashEnumCompletion` — COMPREPLY for enum values
51
- - `collectFlagWords`, `collectEnumCasesFromFlags`, `EnumCase` — flag extraction
52
-
53
- ### `shells/zsh.ts`
54
-
55
- - `emitZshGroupFunction`, `emitZshLeafFunction` — helper function emitters
56
- - `escapeZshDescription`, `escapeZshEnumValue` — zsh string escaping
57
- - `buildZshFlagSpecsFromFlags`, `buildZshFlagSpecs` — `_arguments` spec builders
58
-
59
- ## GOTCHAS
60
-
61
- - `shells/shared.ts` imports `cli/propagate.ts` directly (`@internal` file, not through cli barrel)
62
- — needs `collectPropagatedFlags()` for flag inheritance in nested commands
63
- - `biome-ignore noTemplateCurlyInString` in `shells/bash.ts` — emitting bash `${words[i]}` syntax
64
- - Fish and PowerShell stubs throw `CLIError` with code `UNSUPPORTED_OPERATION`
65
- - `CompletionOptions` lives in `shells/shared.ts`, re-exported through `index.ts`
66
-
67
- ## TEST FILES (2)
68
-
69
- | File | Tests |
70
- | ----------------------- | ----------------------------------------------------------- |
71
- | `completion.test.ts` | ~1690 lines — largest test file; bash + zsh output matching |
72
- | (cli-completion-e2e.ts) | Lives in `cli/` — end-to-end completion via CLI builder |
@@ -1,48 +0,0 @@
1
- /**
2
- * Shared test helpers for extracting structure from generated completion scripts.
3
- *
4
- * @module dreamcli/core/completion/completion-test-helpers
5
- * @internal
6
- */
7
-
8
- /**
9
- * @internal
10
- * Extract the root-level completion words from a bash completion script.
11
- *
12
- * Finds the last `compgen -W '...' -- "$cur"` block and returns the
13
- * space-separated words as an array.
14
- *
15
- * @param script - The full generated bash completion script.
16
- * @returns The root-level completion words.
17
- */
18
- function extractBashRootWords(script: string): readonly string[] {
19
- const matches = [...script.matchAll(/compgen -W '([^']*)' -- "\$cur"/g)];
20
- const words = matches[matches.length - 1]?.[1];
21
- if (words === undefined) {
22
- throw new Error('Could not find root bash completion words');
23
- }
24
- return words.split(' ').filter(Boolean);
25
- }
26
-
27
- /**
28
- * @internal
29
- * Extract the body of the root zsh completion function from a zsh
30
- * completion script.
31
- *
32
- * @param script - The full generated zsh completion script.
33
- * @param funcName - The function name to locate (e.g. `'_mycli'`).
34
- * @returns The function body (from signature through closing brace).
35
- */
36
- function extractZshRootFunction(script: string, funcName: string): string {
37
- const start = script.indexOf(`${funcName}() {`);
38
- if (start === -1) {
39
- throw new Error(`Could not find zsh root function '${funcName}'`);
40
- }
41
- const end = script.indexOf(`\n}\n\n${funcName} "$@"`, start);
42
- if (end === -1) {
43
- throw new Error(`Could not find end of zsh root function '${funcName}'`);
44
- }
45
- return script.slice(start, end + 2);
46
- }
47
-
48
- export { extractBashRootWords, extractZshRootFunction };
@@ -1,69 +0,0 @@
1
- # output — OutputChannel, spinner/progress, TTY rendering
2
-
3
- Three files: `writer.ts` (leaf, ~30 lines), `activity.ts` (handle classes, ~581 lines), `index.ts`
4
- (OutputChannel + factories, ~570 lines).
5
-
6
- Dependency graph (no cycles): `writer.ts` ← `activity.ts` ← `index.ts` → `writer.ts`.
7
-
8
- ## KEY TYPES
9
-
10
- | Symbol | Visibility | Role |
11
- | ----------------------- | ----------- | ------------------------------------------------ |
12
- | `createOutput()` | **Public** | Factory → `Out` interface (mode-dispatched) |
13
- | `createCaptureOutput()` | **Public** | Factory → `Out` + `CapturedOutput` (for testkit) |
14
- | `OutputChannel` | `@internal` | Concrete class implementing `Out` |
15
- | `CaptureOutputChannel` | `@internal` | Subclass capturing output + activity events |
16
-
17
- ## OUTPUT MODES
18
-
19
- | Mode | `out.log` | `out.json` | Spinner/Progress |
20
- | ------- | ---------- | ---------- | ---------------- |
21
- | Normal | → stdout | → stdout | TTY handles |
22
- | JSON | → stderr | → stdout | Noop handles |
23
- | Quiet | suppressed | → stdout | Noop handles |
24
- | Non-TTY | → stdout | → stdout | Static handles |
25
- | Capture | → array | → array | Capture handles |
26
-
27
- ## ACTIVITY HANDLES
28
-
29
- Four handle tiers per activity type (spinner + progress):
30
-
31
- | Handle class | When used | Behavior |
32
- | ---------------------- | ---------- | --------------------------------------------- |
33
- | `noopSpinnerHandle` | JSON/quiet | Silent, all methods no-op |
34
- | `StaticSpinnerHandle` | non-TTY | Writes start/succeed/fail as plain text lines |
35
- | `TTYSpinnerHandle` | TTY | Braille animation, cursor control, erase line |
36
- | `CaptureSpinnerHandle` | testkit | Records `ActivityEvent[]` for assertions |
37
-
38
- Same pattern for `*ProgressHandle` (bar rendering, percentage, indeterminate pulse).
39
-
40
- Active handle tracking: only one spinner/progress at a time per `OutputChannel`. Starting a new one
41
- implicitly stops the previous. `stopActive()` public method for explicit cleanup.
42
-
43
- All activity handle output (static and TTY) routes to **stderr** — stdout reserved for data.
44
-
45
- ## AMBIENT DECLARATIONS
46
-
47
- `setInterval`/`clearInterval` declared as ambient functions in `activity.ts` (not from
48
- `@types/node`) — zero-dep library targeting ES2022 without DOM or Node lib typings.
49
-
50
- ## TEST FILES (6)
51
-
52
- | File | Tests | Focus |
53
- | ---------------------------------- | ----: | ----------------------------------------------------- |
54
- | `output.test.ts` | 49 | Core OutputChannel: log/warn/error, modes |
55
- | `output-tty.test.ts` | 20 | TTY-specific rendering, color, formatting |
56
- | `output-table.test.ts` | 16 | Table output in various modes |
57
- | `output-spinner.test.ts` | 45 | Spinner handles: noop/static/TTY/capture, fake timers |
58
- | `output-progress.test.ts` | 40 | Progress handles: noop/static/TTY/capture, fake timer |
59
- | `output-activity-dispatch.test.ts` | 32 | OutputChannel wiring: mode dispatch, overlap, testkit |
60
-
61
- ## GOTCHAS
62
-
63
- - Imports `schema/activity.ts` directly for activity types, `schema/command.ts` for `Out` — bypasses
64
- barrel to avoid circular dep
65
- - `writer.ts` is a leaf: `WriteFn` type + `writeLine` helper. Shared by `index.ts` and `activity.ts`
66
- - Terminal escape sequences (`HIDE_CURSOR`, `ERASE_LINE`, etc.) are `@internal` constants in
67
- `activity.ts`
68
- - Spinner/progress tests use `vi.useFakeTimers()` inline with `try/finally`
69
- - `ActivityEvent` has 10 variants (including `progress:increment` distinct from `progress:update`)
@@ -1,69 +0,0 @@
1
- # resolve — Flag/arg value resolution chain
2
-
3
- Single file: `index.ts` — largest in the codebase (~940 lines).
4
-
5
- ## RESOLUTION ORDER
6
-
7
- ```
8
- CLI argv → environment variable → config file → interactive prompt → default value
9
- ```
10
-
11
- Each source tried in order; first non-undefined wins. Missing required values with no source trigger
12
- `ValidationError`.
13
-
14
- ## KEY FUNCTIONS
15
-
16
- | Function | Role |
17
- | --------------------- | ------------------------------------------------------------ |
18
- | `resolve()` | Main entry — orchestrates full resolution for a command |
19
- | `resolveFlags()` | All flags: CLI → env → config → prompt → default |
20
- | `resolveArgs()` | All args: parsed → default → required validation |
21
- | `coerceValue()` | Unified raw value → flag's declared kind (env/config/prompt) |
22
- | `resolveConfigPath()` | Dotted path lookup in config object |
23
-
24
- ## TWO-PASS ARCHITECTURE
25
-
26
- 1. **Pass 1** (all flags): CLI → env → config. Collect partial values.
27
- 2. **Interactive resolver call**: If command has `.interactive()`, invoke with partial flags.
28
- 3. **Pass 2** (unresolved flags): prompt → default → required validation.
29
-
30
- Without interactive resolver, single-pass (per-flag prompts used directly).
31
-
32
- ## COERCION PATTERN
33
-
34
- Single unified `coerceValue()` function with a `CoerceSource` discriminated union
35
- (`{ kind: 'env'; envVar } | { kind: 'config'; configPath } | { kind: 'prompt' }`) parameterizing
36
- source-specific behavior: string leniency, boolean truthy/falsy sets ('y'/'n' for prompt), array
37
- trim-on-split (prompt only), and error message templates.
38
-
39
- Returns two-state `CoerceResult` (`{ ok: true; value } | { ok: false; error: ValidationError }`).
40
- The prompt caller wraps this in a three-state `PromptResolveResult` at its own call site.
41
-
42
- Helpers: `sourceLabel()` (error message fragment), `sourceDetails()` (error detail keys),
43
- `coercionError()` (builds ValidationError with source context).
44
-
45
- ## ERROR AGGREGATION
46
-
47
- `resolveFlags()` and `resolveArgs()` collect all errors into an array, then throw a single
48
- aggregated `ValidationError` via `throwAggregatedErrors()`. Users see all validation messages at
49
- once.
50
-
51
- ## TEST FILES (7, aspect-split)
52
-
53
- | File | Tests |
54
- | ----------------------------- | ------------------------------------------ |
55
- | `resolve.test.ts` | Core resolution logic, precedence rules |
56
- | `resolve-errors.test.ts` | Validation errors, missing required values |
57
- | `resolve-env.test.ts` | Environment variable resolution + coercion |
58
- | `resolve-config.test.ts` | Config file resolution + dotted paths |
59
- | `resolve-prompt.test.ts` | Prompt-based resolution |
60
- | `resolve-interactive.test.ts` | Two-pass interactive mode (full flow) |
61
- | `resolve-integration.test.ts` | Cross-concern integration |
62
-
63
- ## GOTCHAS
64
-
65
- - ~940 lines — reduced from ~1.1k by unifying three coercion functions into one
66
- - `ResolveOptions` injects everything: env, config, prompter, answers — never touches `process`
67
- directly
68
- - Imports `schema/prompt.ts` directly (not through barrel) — circular dep avoidance
69
- - `DeprecationWarning` structs collected during resolution for deprecated flag/arg usage
@@ -1,61 +0,0 @@
1
- # schema — Command/Flag/Arg/Middleware builders + prompt config types
2
-
3
- Only multi-file module in `core/`. All others use single `index.ts`.
4
-
5
- ## FILES
6
-
7
- | File | Lines | Purpose |
8
- | --------------- | ----: | ----------------------------------------------------------------------------------------------------------------------------------- |
9
- | `command.ts` | 784 | `CommandBuilder<F, A, C>` — fluent builder + `Out` interface + command schema |
10
- | `activity.ts` | 150 | Activity types — `Fallback`, `SpinnerHandle`, `ProgressHandle`, `SpinnerOptions`, `ProgressOptions`, `ActivityEvent`, `TableColumn` |
11
- | `flag.ts` | 455 | `FlagBuilder` — `flag.string()`, `.boolean()`, `.number()`, `.count()`, `.enum()`, `.custom()` |
12
- | `arg.ts` | 341 | `ArgBuilder` — `arg.string()`, `.number()`, `.enum()` |
13
- | `middleware.ts` | 164 | `middleware<Output>(handler)` factory — phantom-branded `Middleware<Output>` type |
14
- | `prompt.ts` | 70 | Prompt config types — `PromptConfig` discriminated union (4 kinds) |
15
- | `run.ts` | 47 | `RunResult` — structured execution result (canonical definition, re-exported by testkit) |
16
- | `index.ts` | 80 | Barrel — re-exports all public symbols |
17
-
18
- ## TYPE SYSTEM PATTERNS
19
-
20
- - **`F` accumulator**: `{} & Record<name, InferFlag<...>>` grows per `.flag()` call
21
- - **`A` accumulator**: same pattern for `.arg()`
22
- - **`C` accumulator**: `Record<string, never>` replaced entirely on first `.middleware()`, then
23
- intersection-grown via `WidenContext<C, Output>`
24
- - **`{}` as identity element**: `biome-ignore noBannedTypes` on `CommandBuilder` class generic
25
- defaults — justified, do not "fix"
26
- - **Phantom brand**: `Middleware<Output>` carries type info at compile time, erased at runtime.
27
- `_output` property is phantom — compile-time only. Same for `_value` on FlagBuilder/ArgBuilder.
28
- - **Type erasure**: `eraseBuilder()` / `eraseCommand()` centralize `as unknown as` casts for
29
- heterogeneous subcommand storage. These are the justified `as` cast sites.
30
-
31
- ## `command.ts` TYPE DENSITY
32
-
33
- 21+ type/interface exports split across `command.ts` and `activity.ts`:
34
-
35
- - **Activity types** (`activity.ts`): `ActivityEvent` (10-variant DU), `SpinnerHandle`,
36
- `ProgressHandle`, `SpinnerOptions`, `ProgressOptions`, `Fallback`, `TableColumn`
37
- - **Output interface** (`command.ts`): `Out` (~110 lines JSDoc + signatures) — imports activity
38
- types from `./activity.ts`
39
- - **Command schema** (`command.ts`): `CommandSchema`, `ErasedCommand`, `ActionHandler`,
40
- `ActionParams`, `InteractiveResolver`, `CommandExample`, etc.
41
-
42
- Activity types live in `activity.ts` (still in schema/, not in output/) because `Out` needs them in
43
- `CommandBuilder.action()` signature. `command.ts` imports them from `./activity.ts`.
44
-
45
- ## ADDING A FLAG TYPE
46
-
47
- 1. Add variant to `FlagKind` union in `flag.ts`
48
- 2. Add factory method on `FlagBuilder`
49
- 3. Update `InferFlag` conditional type
50
- 4. Wire through `resolve/` (add coercion case in the unified `coerceValue()` function)
51
- 5. Add tests in `flag.test.ts` + `resolve.test.ts`
52
-
53
- ## GOTCHAS
54
-
55
- - `.middleware()` drops current handler (type signature changes) — intentional, forces
56
- re-registration after middleware addition
57
- - Prompt types consumed directly by `core/prompt/` and `core/resolve/` (bypasses barrel to avoid
58
- circular dep through `schema → prompt → schema` path)
59
- - `deprecated()` modifier on both FlagBuilder and ArgBuilder — collects `DeprecationWarning` structs
60
- during resolution
61
- - Prompt types in `prompt.ts` re-exported through `flag.ts`, not through `prompt.ts` in the barrel
@@ -1,55 +0,0 @@
1
- # testkit — In-process test harness (public API)
2
-
3
- Not just test utilities — first-class module exported from the package. Testkit symbols are
4
- re-exported from the `dreamcli/testkit` subpath (curating barrel at `src/testkit.ts`). This internal
5
- `core/testkit/` module is unchanged.
6
-
7
- ## CORE API
8
-
9
- **`runCommand(cmd, argv, options?): Promise<RunResult>`**
10
-
11
- Complete execution pipeline in-process: argv → parse → resolve → middleware chain → action handler →
12
- captured output. Calls `out.stopActive()` in `finally` to clean up leaked spinner/progress timers.
13
-
14
- **`RunResult`** (defined in `schema/run.ts`, re-exported here):
15
- `{ exitCode, stdout: string[], stderr: string[], activity: ActivityEvent[], error? }`
16
-
17
- **`RunOptions`** — the injectable testing seam:
18
-
19
- | Option | Purpose |
20
- | ----------- | ------------------------------------------------- |
21
- | `env` | `Record<string, string>` — replaces `process.env` |
22
- | `config` | JSON config object |
23
- | `answers` | `Record<string, TestAnswer>` — prompt responses |
24
- | `prompter` | Full `PromptEngine` override |
25
- | `verbosity` | `'normal' \| 'quiet'` |
26
- | `jsonMode` | boolean — enable JSON output |
27
- | `isTTY` | boolean — simulate TTY |
28
- | `help` | `HelpOptions` — help formatting (width, binName) |
29
-
30
- ## TEST FILES (7)
31
-
32
- | File | Tests |
33
- | -------------------------------- | --------------------------------------------- |
34
- | `testkit.test.ts` | Core `runCommand()` behavior |
35
- | `testkit-json.test.ts` | JSON mode output |
36
- | `testkit-tty.test.ts` | TTY detection + behavior |
37
- | `testkit-prompt.test.ts` | Prompt resolution via answers |
38
- | `testkit-nesting.test.ts` | Nested command dispatch via testkit |
39
- | `output-e2e.test.ts` | Full pipeline: output modes x verbosity x CLI |
40
- | `middleware-context-e2e.test.ts` | Middleware composition + context typing |
41
-
42
- ## ASSERTIONS
43
-
44
- - Output arrays include trailing `\n` — assert `['Hello\n']` not `['Hello']`
45
- - JSON output: `JSON.parse(result.stdout[0] ?? '')` then `toEqual`
46
- - Error checking: `result.error?.code` for structured errors
47
- - Activity events: `result.activity` array of `ActivityEvent` discriminated unions
48
- - Type testing: `expectTypeOf(ctx).toEqualTypeOf<Readonly<...>>()` in middleware E2E
49
-
50
- ## GOTCHAS
51
-
52
- - `mergedSchema` field on `RunOptions` is `@internal` — used by CLI dispatch layer only
53
- - `CaptureOutputChannel` (from output/) wired here for output + activity capture
54
- - `formatRootHelp()` (in `cli/root-help.ts`) re-exported as `@internal` for CLI-level help rendering
55
- - Direct imports: `schema/command.ts`, `schema/flag.ts`, `schema/arg.ts` (not through barrel)
@@ -1,74 +0,0 @@
1
- # runtime — Platform abstraction layer
2
-
3
- Multi-file module. Not truly independent of core — imports `WriteFn` from `core/output/` and
4
- `ReadFn` from `core/prompt/`.
5
-
6
- Runtime symbols re-exported from `dreamcli/runtime` subpath (`src/runtime.ts`): `RuntimeAdapter`,
7
- adapter factories, `ExitError`, detection. `createTestAdapter`/`TestAdapterOptions` are testkit-only
8
- (exported from `dreamcli/testkit`, not `dreamcli/runtime`).
9
-
10
- ## FILES
11
-
12
- | File | Status | Lines | Purpose |
13
- | -------------------- | ---------- | ----: | ------------------------------------------------------------------- |
14
- | `adapter.ts` | **Active** | 120 | `RuntimeAdapter` interface — process/env/IO abstraction |
15
- | `auto.ts` | **Active** | 64 | `createAdapter()` — auto-detecting adapter factory |
16
- | `node.ts` | **Active** | 230 | `createNodeAdapter()` — Node.js implementation |
17
- | `bun.ts` | **Active** | 20 | `createBunAdapter()` — delegates to Node adapter |
18
- | `deno.ts` | **Active** | 318 | `createDenoAdapter()` — Deno namespace implementation |
19
- | `detect.ts` | **Active** | 90 | `detectRuntime()` — Bun/Deno/Node feature detection |
20
- | `node-builtins.d.ts` | Types | 45 | `@internal` — ambient decls for `node:readline`, `node:fs/promises` |
21
- | `index.ts` | Barrel | 30 | Re-exports `RuntimeAdapter`, adapters, `ExitError` |
22
-
23
- ## `RuntimeAdapter` INTERFACE
24
-
25
- ```
26
- argv: string[]
27
- env: Record<string, string | undefined>
28
- cwd: string
29
- stdout: WriteFn
30
- stderr: WriteFn
31
- stdin: ReadFn
32
- exit(code: number): never
33
- isTTY: boolean
34
- stdinIsTTY: boolean
35
- homedir(): string
36
- configDir(appName: string): string
37
- readFile(path: string): Promise<string>
38
- joinPath(...segments: string[]): string
39
- ```
40
-
41
- ## ADDING A NEW PLATFORM
42
-
43
- 1. Implement `RuntimeAdapter` in `{platform}.ts`
44
- 2. Add factory `create{Platform}Adapter()` to barrel
45
- 3. Add detection case in `detect.ts`
46
- 4. Wire auto-detection in `auto.ts`
47
- 5. Re-export from `src/runtime.ts`
48
-
49
- ## TEST FILES (5)
50
-
51
- | File | Tests |
52
- | ----------------- | --------------------------------------------------------- |
53
- | `runtime.test.ts` | Node adapter, test adapter, `ExitError`, adapter contract |
54
- | `detect.test.ts` | Runtime detection logic (globalThis feature probing) |
55
- | `bun.test.ts` | Bun adapter delegation |
56
- | `deno.test.ts` | Deno adapter (mock namespace, permission handling, stdin) |
57
- | `auto.test.ts` | Auto-detecting adapter factory |
58
-
59
- ## GOTCHAS
60
-
61
- - `globalThis as unknown as GlobalForDetect` in `detect.ts` — runtime boundary, justified cast
62
- - `node.ts` has 7 `@internal` symbols: `NodeProcess`, `NodeSystemError`, `getNodeProcess`,
63
- `isNodeSystemError`, `createNodeReadLine`, `resolveHomedir`, `resolveConfigDir`
64
- - `createTestAdapter()` exported from `dreamcli/testkit` only, not `dreamcli/runtime`
65
- - `ExitError` thrown by `adapter.exit()` — caught by CLI dispatch layer
66
- - Empty-string env var fallbacks treated as unset in `node.ts`
67
- - Win32 paths: `resolveConfigDir` strips trailing separator, `resolveHomedir` has
68
- `HOMEDRIVE`+`HOMEPATH` fallback
69
- - `deno.ts` has 7 `@internal` symbols: `DenoNamespace`, `isDenoErrorNamed`, `safeEnvToObject`,
70
- `safeCwd`, `getDenoNamespace`, `readDenoStdinLine`, `resolveDenoHomedir`, `resolveDenoConfigDir`
71
- - Deno.args pre-strips binary/script — adapter prepends synthetic `['deno', 'run']` for argv parity
72
- - Permission-safe: env/cwd catch `PermissionDenied`, readFile returns null for both `NotFound` and
73
- `PermissionDenied`
74
- - Deno/web globals used by `deno.ts` come from `deno.jsonc` (`lib: ["deno.ns", "deno.shared_globals"]`)
@@ -1,40 +0,0 @@
1
- /**
2
- * Shared test helpers for runtime adapter tests.
3
- *
4
- * @internal — test-only, not exported from any public barrel.
5
- * @module dreamcli/runtime/test-helpers
6
- */
7
-
8
- import { vi } from 'vitest';
9
-
10
- /**
11
- * Create a minimal mock Deno namespace for adapter tests.
12
- *
13
- * Tests that exercise the Deno adapter path through `createAdapter()`
14
- * can pass this namespace via the injected `globals` parameter instead
15
- * of mutating `globalThis.Deno`.
16
- *
17
- * @returns A mock Deno namespace with stubbed I/O, env, and exit.
18
- */
19
- export function createMockDenoNamespace() {
20
- return {
21
- build: { os: 'linux' as const },
22
- args: [],
23
- env: { get: () => undefined, toObject: () => ({}) },
24
- cwd: () => '/deno/mock',
25
- stdout: { writeSync: vi.fn(() => 0), isTerminal: () => false },
26
- stderr: { writeSync: vi.fn(() => 0) },
27
- stdin: {
28
- isTerminal: () => false,
29
- readable: {
30
- getReader: () => ({
31
- read: () => Promise.resolve({ done: true, value: undefined }),
32
- releaseLock: () => {},
33
- }),
34
- },
35
- },
36
- exit: vi.fn() as unknown as (code: number) => never,
37
- readTextFile: () => Promise.reject(Object.assign(new Error('not found'), { name: 'NotFound' })),
38
- version: { deno: '2.6.0' },
39
- };
40
- }