@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,53 +1,25 @@
1
1
  /**
2
2
  * Test harness: command.run() with injected state, output capture.
3
3
  *
4
- * Provides `runCommand()` — the core execution pipeline that parses argv,
5
- * resolves values (CLI → env → config → default), creates an output channel,
6
- * and invokes the action handler. Returns a structured `RunResult` with
7
- * exitCode and captured output.
4
+ * Provides {@linkcode runCommand()} — the in-process test harness wrapper over DreamCLI's
5
+ * shared executor.\
6
+ * It wires capture output and standalone command metadata,
7
+ * then returns a structured {@linkcode RunResult} with exitCode and captured output.
8
8
  *
9
- * `CommandBuilder.run()` delegates to `runCommand()`, making commands
10
- * testable without touching process state.
9
+ * This keeps command tests process-free without testkit owning the canonical pipeline:
11
10
  *
11
+ * ```text
12
+ * parse -> resolve -> execute
13
+ * ```
12
14
  * @module dreamcli/core/testkit
13
15
  */
14
16
 
15
- import type {
16
- BeforeParseParams,
17
- CLIPlugin,
18
- ResolvedCommandParams,
19
- } from '#internals/core/cli/plugin.ts';
20
- import { CLIError } from '#internals/core/errors/index.ts';
21
- import { formatHelp } from '#internals/core/help/index.ts';
17
+ import { buildRunResult, executeCommand } from '#internals/core/execution/index.ts';
22
18
  import type { CapturedOutput } from '#internals/core/output/index.ts';
23
19
  import { createCaptureOutput } from '#internals/core/output/index.ts';
24
- import { parse } from '#internals/core/parse/index.ts';
25
- import { createTestPrompter } from '#internals/core/prompt/index.ts';
26
- import type { DeprecationWarning, ResolveOptions } from '#internals/core/resolve/index.ts';
27
- import { resolve } from '#internals/core/resolve/index.ts';
28
- import type { ArgBuilder, ArgConfig } from '#internals/core/schema/arg.ts';
29
- import type { CommandBuilder, CommandMeta, Out } from '#internals/core/schema/command.ts';
30
- import type { FlagBuilder, FlagConfig } from '#internals/core/schema/flag.ts';
20
+ import type { CommandMeta, Out, RunnableCommand } from '#internals/core/schema/command.ts';
31
21
  import type { RunOptions, RunResult } from '#internals/core/schema/run.ts';
32
22
 
33
- // --- Internal types
34
-
35
- /**
36
- * The runtime shape of action handler params — unbranded.
37
- *
38
- * This is what `ActionParams<F, A>` looks like after type erasure.
39
- * Used at the phantom-type boundary in `invokeHandler`.
40
- *
41
- * @internal
42
- */
43
- interface HandlerParams {
44
- readonly flags: Readonly<Record<string, unknown>>;
45
- readonly args: Readonly<Record<string, unknown>>;
46
- readonly ctx: Readonly<Record<string, unknown>>;
47
- readonly out: Out;
48
- readonly meta: CommandMeta;
49
- }
50
-
51
23
  // RunOptions and RunResult are defined in schema/run.ts so the execution
52
24
  // contract is shared by schema, CLI dispatch, and testkit. Re-exported here
53
25
  // for public testkit continuity.
@@ -57,27 +29,25 @@ interface HandlerParams {
57
29
  /**
58
30
  * Run a command builder against the given argv with injected options.
59
31
  *
60
- * This is the core execution pipeline:
61
- * 1. Detect `--help` / `-h` → print help text, exit 0
62
- * 2. Parse argv against the command schema
63
- * 3. Resolve values (CLI → env → config → default)
64
- * 4. Create a capture output channel
65
- * 5. Run derive/middleware/action execution steps
66
- * 6. Return structured result
32
+ * This is the testkit wrapper around the shared executor:
33
+ * 1. Create or reuse capture output
34
+ * 2. Build standalone schema/meta defaults when CLI dispatch did not
35
+ * 3. Delegate parse -> resolve -> execute to the shared executor
36
+ * 4. Return the structured result with captured buffers
67
37
  *
68
- * All errors are caught and converted to structured `RunResult`s with
69
- * appropriate exit codes. The function never throws.
38
+ * Errors are normalized by the shared executor into structured {@linkcode RunResult}s
39
+ * with appropriate exit codes. The function never throws.
70
40
  *
71
41
  * @param cmd - The command builder (must have an action handler)
72
42
  * @param argv - Raw argv strings (NOT including the command name itself)
73
43
  * @param options - Injectable runtime state
74
44
  * @returns Structured run result with exit code and captured output
75
45
  */
76
- async function runCommand<
77
- F extends Record<string, FlagBuilder<FlagConfig>>,
78
- A extends Record<string, ArgBuilder<ArgConfig>>,
79
- C extends Record<string, unknown> = Record<string, never>,
80
- >(cmd: CommandBuilder<F, A, C>, argv: readonly string[], options?: RunOptions): Promise<RunResult> {
46
+ async function runCommand(
47
+ cmd: RunnableCommand,
48
+ argv: readonly string[],
49
+ options?: RunOptions,
50
+ ): Promise<RunResult> {
81
51
  let out: Out;
82
52
  let captured: CapturedOutput;
83
53
  if (options?.out !== undefined) {
@@ -104,262 +74,50 @@ async function runCommand<
104
74
  command: schema.name,
105
75
  };
106
76
 
107
- // -- Help detection -------------------------------------------------------
108
- if (argv.includes('--help') || argv.includes('-h')) {
109
- const helpText = formatHelp(schema, options?.help);
110
- out.log(helpText);
111
- return buildResult(0, captured, undefined);
112
- }
113
-
114
- // -- No action handler → error -------------------------------------------
115
- if (!cmd.handler) {
116
- const err = new CLIError(`Command '${cmd.schema.name}' has no action handler`, {
117
- code: 'NO_ACTION',
118
- suggest: `Add an .action() handler to the '${cmd.schema.name}' command`,
119
- });
120
- out.error(err.message);
121
- return buildResult(1, captured, err);
122
- }
123
-
124
- try {
125
- await runBeforeParseHooks(options?.plugins, {
126
- argv,
127
- command: schema,
128
- meta,
129
- out,
130
- });
77
+ const result = await executeCommand({
78
+ command: cmd,
79
+ argv,
80
+ out,
81
+ schema,
82
+ meta,
83
+ ...(options !== undefined ? { options } : {}),
84
+ });
131
85
 
132
- // -- Parse ---------------------------------------------------------------
133
- const parsed = parse(schema, argv);
134
-
135
- // -- Resolve -------------------------------------------------------------
136
- // Determine the prompt engine: explicit prompter takes precedence,
137
- // then answers convenience shortcut, then nothing (prompts skipped).
138
- const effectivePrompter =
139
- options?.prompter ??
140
- (options?.answers !== undefined ? createTestPrompter(options.answers) : undefined);
141
- const resolveOptions: ResolveOptions = {
142
- ...(options?.stdinData !== undefined ? { stdinData: options.stdinData } : {}),
143
- ...(options?.env !== undefined ? { env: options.env } : {}),
144
- ...(options?.config !== undefined ? { config: options.config } : {}),
145
- ...(effectivePrompter !== undefined ? { prompter: effectivePrompter } : {}),
146
- };
147
- const resolved = await resolve(schema, parsed, resolveOptions);
148
- const resolvedParams: ResolvedCommandParams = {
149
- args: resolved.args,
150
- flags: resolved.flags,
151
- deprecations: resolved.deprecations,
152
- command: schema,
153
- meta,
154
- out,
155
- };
156
-
157
- await runResolvedHooks(options?.plugins, 'afterResolve', resolvedParams);
158
-
159
- // -- Deprecation warnings ------------------------------------------------
160
- for (const d of resolved.deprecations) {
161
- out.warn(formatDeprecation(d));
162
- }
163
-
164
- // -- Execute middleware chain + handler -----------------------------------
165
- // The resolver guarantees that resolved.flags and resolved.args match
166
- // the shape declared by the command's flag/arg builders. The phantom
167
- // types on CommandBuilder<F, A> are erased at runtime — the handler
168
- // is just a function accepting a plain object. `executeWithMiddleware`
169
- // runs the middleware chain then invokes the handler at the end.
170
- await runResolvedHooks(options?.plugins, 'beforeAction', resolvedParams);
171
- await executeWithExecutionSteps(cmd, resolved.flags, resolved.args, out, meta);
172
- await runResolvedHooks(options?.plugins, 'afterAction', resolvedParams);
173
-
174
- return buildResult(0, captured, undefined);
175
- } catch (err: unknown) {
176
- if (err instanceof CLIError) {
177
- if (options?.jsonMode === true) {
178
- out.json({ error: err.toJSON() });
179
- } else {
180
- out.error(err.message);
181
- if (err.suggest !== undefined) {
182
- out.error(`Suggestion: ${err.suggest}`);
183
- }
184
- }
185
- return buildResult(err.exitCode, captured, err);
186
- }
187
-
188
- // Unknown error — wrap and exit 1
189
- const message = err instanceof Error ? err.message : String(err);
190
- const wrapped = new CLIError(`Unexpected error: ${message}`, {
191
- code: 'UNEXPECTED_ERROR',
192
- cause: err,
193
- });
194
- if (options?.jsonMode === true) {
195
- out.json({ error: wrapped.toJSON() });
196
- } else {
197
- out.error(wrapped.message);
198
- }
199
- return buildResult(1, captured, wrapped);
200
- } finally {
201
- // Clean up any active spinner/progress timer that the handler
202
- // failed to stop (e.g. unhandled exception before terminal method).
203
- out.stopActive();
204
- }
86
+ return buildRunResult(result, captured);
205
87
  }
206
88
 
207
- type ResolvedHookName = Exclude<keyof CLIPlugin['hooks'], 'beforeParse'>;
208
-
209
- /**
210
- * @internal
211
- */
212
- async function runBeforeParseHooks(
213
- plugins: readonly CLIPlugin[] | undefined,
214
- params: BeforeParseParams,
215
- ): Promise<void> {
216
- if (plugins === undefined) return;
217
- for (const current of plugins) {
218
- const hook = current.hooks.beforeParse;
219
- if (hook !== undefined) await hook(params);
220
- }
221
- }
222
-
223
- /**
224
- * @internal
225
- */
226
- async function runResolvedHooks(
227
- plugins: readonly CLIPlugin[] | undefined,
228
- hookName: ResolvedHookName,
229
- params: ResolvedCommandParams,
230
- ): Promise<void> {
231
- if (plugins === undefined) return;
232
- for (const current of plugins) {
233
- const hook = current.hooks[hookName];
234
- if (hook !== undefined) await hook(params);
235
- }
236
- }
237
-
238
- // --- Helpers
89
+ // --- Exports
239
90
 
240
91
  /**
241
- * Execute the derive/middleware chain followed by the action handler.
242
- *
243
- * Builds a continuation chain from the registered execution steps, preserving
244
- * registration order across `derive()` and `middleware()`.
245
- *
246
- * - Derive steps run once, may validate/throw, and optionally return context
247
- * additions merged into `ctx`.
248
- * - Middleware steps can wrap downstream execution via `next(additions)`.
249
- * - The terminal step invokes the action handler with the final accumulated ctx.
92
+ * Options for {@linkcode runCommand} — process-free command execution.
250
93
  *
251
- * This is the sole point where we bridge the phantom-type gap. The
252
- * parse→resolve pipeline guarantees the runtime values match the schema;
253
- * the phantom types guarantee the handler expects that schema.
94
+ * Every field is optional. Inject env, config, prompt answers, and
95
+ * output capture without touching process state.
254
96
  *
255
- * @internal
97
+ * @example
98
+ * ```ts
99
+ * const result = await runCommand(cmd, ['--verbose'], {
100
+ * env: { LOG_LEVEL: 'debug' },
101
+ * config: { theme: 'dark' },
102
+ * });
103
+ * ```
256
104
  */
257
- async function executeWithExecutionSteps<
258
- F extends Record<string, FlagBuilder<FlagConfig>>,
259
- A extends Record<string, ArgBuilder<ArgConfig>>,
260
- C extends Record<string, unknown>,
261
- >(
262
- cmd: CommandBuilder<F, A, C>,
263
- flags: Readonly<Record<string, unknown>>,
264
- args: Readonly<Record<string, unknown>>,
265
- out: Out,
266
- meta: CommandMeta,
267
- ): Promise<void> {
268
- const steps = cmd._executionSteps;
269
- const handler = cmd.handler;
270
- if (handler === undefined) {
271
- throw new CLIError(`Command '${cmd.schema.name}' has no action handler`, {
272
- code: 'NO_ACTION',
273
- suggest: `Add an .action() handler to the '${cmd.schema.name}' command`,
274
- });
275
- }
276
-
277
- // Terminal action — receives the final accumulated context.
278
- type ChainFn = (ctx: Readonly<Record<string, unknown>>) => Promise<void>;
279
-
280
- let chain: ChainFn = async (ctx) => {
281
- const params: HandlerParams = { flags, args, ctx, out, meta };
282
- // Phantom-type erasure: handler is (params: object) => void | Promise<void> at runtime.
283
- await (handler as (p: HandlerParams) => void | Promise<void>)(params);
284
- };
285
-
286
- // Wrap from back to front so registration order is preserved.
287
- for (let i = steps.length - 1; i >= 0; i--) {
288
- const step = steps[i];
289
- if (step === undefined) continue; // satisfy noUncheckedIndexedAccess
290
- const downstream = chain; // capture for closure
291
- switch (step.kind) {
292
- case 'derive':
293
- chain = async (ctx) => {
294
- const additions = await step.handler({ args, flags, ctx, out, meta });
295
- if (additions === undefined) {
296
- await downstream(ctx);
297
- return;
298
- }
299
- if (typeof additions !== 'object' || additions === null || Array.isArray(additions)) {
300
- throw new CLIError('derive() must return an object or undefined', {
301
- code: 'INVALID_BUILDER_STATE',
302
- suggest:
303
- 'Return an object to add context, or return nothing for validation-only derive handlers',
304
- });
305
- }
306
- await downstream({ ...ctx, ...additions });
307
- };
308
- break;
309
- case 'middleware':
310
- chain = async (ctx) => {
311
- await step.handler({
312
- args,
313
- flags,
314
- ctx,
315
- out,
316
- meta,
317
- next: async (additions) => {
318
- await downstream({ ...ctx, ...additions });
319
- },
320
- });
321
- };
322
- break;
323
- }
324
- }
325
-
326
- // Start with empty context — middleware builds it up.
327
- await chain({});
328
- }
329
-
330
- /** Build a `RunResult` from parts. */
331
- function buildResult(
332
- exitCode: number,
333
- captured: CapturedOutput,
334
- error: CLIError | undefined,
335
- ): RunResult {
336
- return {
337
- exitCode,
338
- stdout: captured.stdout,
339
- stderr: captured.stderr,
340
- activity: captured.activity,
341
- error,
342
- };
343
- }
344
-
345
- // --- Deprecation formatting (presentation layer — not resolve's responsibility)
346
-
347
105
  /**
348
- * Format a structured deprecation warning for human-readable stderr output.
106
+ * Structured result from {@linkcode runCommand}.
349
107
  *
350
- * This is a **consumer-side** formatting function — the resolve layer returns
351
- * structured `DeprecationWarning` data; consumers decide how to render it.
108
+ * Contains the exit code, captured stdout/stderr output, recorded
109
+ * {@linkcode ActivityEvent | activity events}, and an `error` field
110
+ * that is `undefined` on success and a {@linkcode CLIError} on failure.
352
111
  *
353
- * @internal
112
+ * @example
113
+ * ```ts
114
+ * const result = await runCommand(greetCmd, ['World']);
115
+ *
116
+ * expect(result.exitCode).toBe(0);
117
+ * expect(result.stdout).toContain('Hello, World!');
118
+ * expect(result.error).toBeUndefined();
119
+ * ```
354
120
  */
355
- function formatDeprecation(d: DeprecationWarning): string {
356
- const entity = d.kind === 'flag' ? `flag --${d.name}` : `argument <${d.name}>`;
357
- return typeof d.message === 'string'
358
- ? `Warning: ${entity} is deprecated: ${d.message}`
359
- : `Warning: ${entity} is deprecated`;
360
- }
361
-
362
- // --- Exports
363
-
364
121
  export type { RunOptions, RunResult };
122
+
365
123
  export { runCommand };
package/src/index.ts CHANGED
@@ -12,10 +12,10 @@
12
12
  * not the typical starting point for application code.
13
13
  *
14
14
  * Test utilities (runCommand, createCaptureOutput, createTestPrompter, etc.)
15
- * are available from `dreamcli/testkit`. Runtime adapters (createAdapter,
16
- * RuntimeAdapter, etc.) are available from `dreamcli/runtime`.
15
+ * are available from `@kjanat/dreamcli/testkit`. Runtime adapters (createAdapter,
16
+ * RuntimeAdapter, etc.) are available from `@kjanat/dreamcli/runtime`.
17
17
  *
18
- * @module dreamcli
18
+ * @module @kjanat/dreamcli
19
19
  */
20
20
 
21
21
  export type {
@@ -35,6 +35,8 @@ export type { CompletionOptions, Shell } from './core/completion/index.ts';
35
35
  export {
36
36
  generateBashCompletion,
37
37
  generateCompletion,
38
+ generateFishCompletion,
39
+ generatePowerShellCompletion,
38
40
  generateZshCompletion,
39
41
  SHELLS,
40
42
  } from './core/completion/index.ts';
@@ -75,7 +77,11 @@ export {
75
77
  export type { HelpOptions } from './core/help/index.ts';
76
78
  export { formatHelp } from './core/help/index.ts';
77
79
  export type { JsonSchemaOptions } from './core/json-schema/index.ts';
78
- export { generateInputSchema, generateSchema } from './core/json-schema/index.ts';
80
+ export {
81
+ definitionMetaSchema,
82
+ generateInputSchema,
83
+ generateSchema,
84
+ } from './core/json-schema/index.ts';
79
85
  export type { OutputOptions, Verbosity, WriteFn } from './core/output/index.ts';
80
86
  export { createOutput } from './core/output/index.ts';
81
87
  export type { ParseResult, Token } from './core/parse/index.ts';
@@ -6,7 +6,7 @@
6
6
  * argv/env access, I/O streams, TTY detection, working directory, and
7
7
  * process exit. Concrete implementations exist for Node, Bun, and Deno.
8
8
  *
9
- * @module dreamcli/runtime/adapter
9
+ * @module @kjanat/dreamcli/runtime/adapter
10
10
  */
11
11
 
12
12
  import type { WriteFn } from '#internals/core/output/index.ts';
@@ -25,7 +25,7 @@ import type { ReadFn } from '#internals/core/prompt/index.ts';
25
25
  * Adapters are designed to be:
26
26
  * - **Immutable in shape:** all properties are readonly
27
27
  * - **Minimal:** only the operations the framework actually needs
28
- * - **Testable:** easily stubbed in tests via `createTestAdapter()`
28
+ * - **Testable:** easily stubbed in tests via {@linkcode createTestAdapter | createTestAdapter()}
29
29
  *
30
30
  * @example
31
31
  * ```ts
@@ -150,7 +150,7 @@ interface TestAdapterOptions {
150
150
  /**
151
151
  * Stdin line reader (defaults to returning `null` — immediate EOF).
152
152
  *
153
- * Use a custom `ReadFn` to simulate user input in tests.
153
+ * Use a custom {@linkcode ReadFn} to simulate user input in tests.
154
154
  */
155
155
  readonly stdin?: ReadFn;
156
156
 
@@ -177,7 +177,7 @@ interface TestAdapterOptions {
177
177
  readonly stdinIsTTY?: boolean;
178
178
 
179
179
  /**
180
- * Exit function (defaults to throwing `ExitError`).
180
+ * Exit function (defaults to throwing {@linkcode ExitError}).
181
181
  * The default throw-based exit allows tests to catch the exit code.
182
182
  */
183
183
  readonly exit?: (code: number) => never;
@@ -208,10 +208,12 @@ interface TestAdapterOptions {
208
208
  }
209
209
 
210
210
  /**
211
- * Error thrown by the default test adapter exit function.
211
+ * Error thrown by adapter implementations that model process exit as an
212
+ * exception instead of terminating immediately.
212
213
  *
213
- * In tests, `process.exit` would kill the test runner. Instead, the test
214
- * adapter throws this error, allowing tests to assert on exit codes:
214
+ * Runtime and CLI dispatch layers can catch this to perform real process
215
+ * termination, while tests can assert on exit codes without killing the
216
+ * runner:
215
217
  *
216
218
  * ```ts
217
219
  * try {
@@ -222,12 +224,13 @@ interface TestAdapterOptions {
222
224
  * ```
223
225
  */
224
226
  class ExitError extends Error {
225
- /** @override */
227
+ /** Error name — always `'ExitError'` for `instanceof` checks. */
226
228
  override readonly name = 'ExitError';
227
229
 
228
230
  /** The exit code passed to `exit()`. */
229
231
  readonly code: number;
230
232
 
233
+ /** Create an ExitError for the given process exit code. */
231
234
  constructor(code: number) {
232
235
  super(`Process exited with code ${code}`);
233
236
  this.code = code;
@@ -246,12 +249,12 @@ const noopReadFile: (path: string) => Promise<string | null> = () => Promise.res
246
249
  /**
247
250
  * Create a test runtime adapter with injectable process state.
248
251
  *
249
- * Use this in `dreamcli/testkit` tests when you need to simulate argv,
252
+ * Use this in `@kjanat/dreamcli/testkit` tests when you need to simulate argv,
250
253
  * environment variables, TTY state, stdin, or config-file reads without
251
254
  * touching the host process.
252
255
  *
253
256
  * @param options - Optional overrides for any adapter field.
254
- * @returns A `RuntimeAdapter` suitable for test scenarios.
257
+ * @returns A {@linkcode RuntimeAdapter} suitable for test scenarios.
255
258
  *
256
259
  * @example
257
260
  * ```ts
@@ -6,7 +6,7 @@
6
6
  * Node adapter for unknown runtimes (safest default — most runtimes
7
7
  * provide a Node-compatible `process` global).
8
8
  *
9
- * @module dreamcli/runtime/auto
9
+ * @module @kjanat/dreamcli/runtime/auto
10
10
  */
11
11
 
12
12
  import type { RuntimeAdapter } from './adapter.ts';
@@ -73,11 +73,11 @@ function getInjectedDenoNamespace(globals: GlobalForDetect): DenoNamespace | und
73
73
  *
74
74
  * @param globals - Override `globalThis` for testing. Production callers
75
75
  * should omit this parameter.
76
- * @returns A `RuntimeAdapter` for the detected runtime.
76
+ * @returns A {@linkcode RuntimeAdapter} for the detected runtime.
77
77
  *
78
78
  * @example
79
79
  * ```ts
80
- * import { cli } from 'dreamcli';
80
+ * import { cli } from '@kjanat/dreamcli';
81
81
  *
82
82
  * // Auto-detects Node/Bun/Deno and creates the right adapter
83
83
  * cli('mycli').run(); // uses createAdapter() internally
@@ -9,7 +9,7 @@
9
9
  * 2. Provide an extension point for Bun-specific overrides in the future
10
10
  * (e.g. `Bun.write` for optimized I/O, `Bun.stdin` for streaming)
11
11
  *
12
- * @module dreamcli/runtime/bun
12
+ * @module @kjanat/dreamcli/runtime/bun
13
13
  */
14
14
 
15
15
  import type { RuntimeAdapter } from './adapter.ts';
@@ -33,12 +33,12 @@ function resolveBunVersion(proc?: NodeProcess): string | undefined {
33
33
  * here without changing the public API.
34
34
  *
35
35
  * @param proc - Override the process object (useful for testing the adapter itself).
36
- * @returns A `RuntimeAdapter` backed by Bun's process state.
36
+ * @returns A {@linkcode RuntimeAdapter} backed by Bun's process state.
37
37
  *
38
38
  * @example
39
39
  * ```ts
40
- * import { cli } from 'dreamcli';
41
- * import { createBunAdapter } from 'dreamcli/runtime/bun';
40
+ * import { cli } from '@kjanat/dreamcli';
41
+ * import { createBunAdapter } from '@kjanat/dreamcli/runtime';
42
42
  *
43
43
  * cli('mycli')
44
44
  * .command(deploy)