@kjanat/dreamcli 0.0.0 → 1.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 (101) hide show
  1. package/CHANGELOG.md +667 -0
  2. package/LICENSE +22 -0
  3. package/README.md +370 -0
  4. package/dist/adapter-B37d9oia.mjs +1 -0
  5. package/dist/adapter-CCSh5juX.cjs +1 -0
  6. package/dist/adapter-DIwO-q7K.d.mts +3447 -0
  7. package/dist/adapter-DQnxxLiE.d.cts +3447 -0
  8. package/dist/auto-5cjZaF9V.mjs +3 -0
  9. package/dist/auto-B0eSgoDw.cjs +3 -0
  10. package/dist/index.cjs +10 -0
  11. package/dist/index.d.cts +920 -0
  12. package/dist/index.d.mts +920 -0
  13. package/dist/index.mjs +10 -0
  14. package/dist/runtime.cjs +1 -0
  15. package/dist/runtime.d.cts +253 -0
  16. package/dist/runtime.d.mts +253 -0
  17. package/dist/runtime.mjs +1 -0
  18. package/dist/testkit-CEDYPvhF.mjs +14 -0
  19. package/dist/testkit-ClIKijxC.cjs +14 -0
  20. package/dist/testkit.cjs +1 -0
  21. package/dist/testkit.d.cts +25 -0
  22. package/dist/testkit.d.mts +25 -0
  23. package/dist/testkit.mjs +1 -0
  24. package/examples/basic.ts +33 -0
  25. package/examples/gh/package.json +48 -0
  26. package/examples/gh/src/commands/auth.ts +66 -0
  27. package/examples/gh/src/commands/issue.ts +120 -0
  28. package/examples/gh/src/commands/pr.ts +125 -0
  29. package/examples/gh/src/data/issues.yaml +5 -0
  30. package/examples/gh/src/data/issues.yaml.d.ts +17 -0
  31. package/examples/gh/src/data/pull-requests.yaml +7 -0
  32. package/examples/gh/src/data/pull-requests.yaml.d.ts +18 -0
  33. package/examples/gh/src/lib/auth.ts +37 -0
  34. package/examples/gh/src/lib/utils.ts +17 -0
  35. package/examples/gh/src/main.test.ts +306 -0
  36. package/examples/gh/src/main.ts +38 -0
  37. package/examples/gh/tsconfig.json +37 -0
  38. package/examples/interactive.ts +66 -0
  39. package/examples/json-mode.ts +93 -0
  40. package/examples/middleware.ts +71 -0
  41. package/examples/multi-command.ts +66 -0
  42. package/examples/spinner-progress.ts +49 -0
  43. package/examples/testing.ts +145 -0
  44. package/examples/tsconfig.json +17 -0
  45. package/package.json +123 -2
  46. package/src/core/cli/AGENTS.md +72 -0
  47. package/src/core/cli/dispatch.ts +282 -0
  48. package/src/core/cli/index.ts +1425 -0
  49. package/src/core/cli/plugin.ts +111 -0
  50. package/src/core/cli/propagate.ts +97 -0
  51. package/src/core/cli/root-help.ts +269 -0
  52. package/src/core/cli/root-surface.ts +74 -0
  53. package/src/core/completion/AGENTS.md +72 -0
  54. package/src/core/completion/completion-test-helpers.ts +48 -0
  55. package/src/core/completion/index.ts +82 -0
  56. package/src/core/completion/shells/bash.ts +456 -0
  57. package/src/core/completion/shells/fish.ts +24 -0
  58. package/src/core/completion/shells/powershell.ts +24 -0
  59. package/src/core/completion/shells/shared.ts +283 -0
  60. package/src/core/completion/shells/zsh.ts +376 -0
  61. package/src/core/config/index.ts +404 -0
  62. package/src/core/config/package-json.ts +216 -0
  63. package/src/core/errors/index.ts +178 -0
  64. package/src/core/help/index.ts +559 -0
  65. package/src/core/json-schema/index.ts +705 -0
  66. package/src/core/output/AGENTS.md +69 -0
  67. package/src/core/output/activity.ts +568 -0
  68. package/src/core/output/display-value.ts +48 -0
  69. package/src/core/output/index.ts +704 -0
  70. package/src/core/output/writer.ts +46 -0
  71. package/src/core/parse/index.ts +643 -0
  72. package/src/core/prompt/index.ts +566 -0
  73. package/src/core/resolve/AGENTS.md +69 -0
  74. package/src/core/resolve/index.ts +1331 -0
  75. package/src/core/schema/AGENTS.md +61 -0
  76. package/src/core/schema/activity.ts +237 -0
  77. package/src/core/schema/arg.ts +707 -0
  78. package/src/core/schema/command.ts +1263 -0
  79. package/src/core/schema/flag.ts +651 -0
  80. package/src/core/schema/index.ts +82 -0
  81. package/src/core/schema/middleware.ts +171 -0
  82. package/src/core/schema/prompt.ts +148 -0
  83. package/src/core/schema/run.ts +187 -0
  84. package/src/core/testkit/AGENTS.md +55 -0
  85. package/src/core/testkit/index.ts +365 -0
  86. package/src/index.ts +164 -0
  87. package/src/runtime/AGENTS.md +74 -0
  88. package/src/runtime/adapter.ts +300 -0
  89. package/src/runtime/auto.ts +110 -0
  90. package/src/runtime/bun.ts +55 -0
  91. package/src/runtime/deno.ts +355 -0
  92. package/src/runtime/detect.ts +102 -0
  93. package/src/runtime/index.ts +21 -0
  94. package/src/runtime/node-builtins.d.ts +23 -0
  95. package/src/runtime/node.ts +278 -0
  96. package/src/runtime/paths.ts +56 -0
  97. package/src/runtime/support.ts +119 -0
  98. package/src/runtime/test-helpers.ts +40 -0
  99. package/src/runtime.ts +31 -0
  100. package/src/testkit.ts +23 -0
  101. package/src/version.ts +20 -0
@@ -0,0 +1,365 @@
1
+ /**
2
+ * Test harness: command.run() with injected state, output capture.
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.
8
+ *
9
+ * `CommandBuilder.run()` delegates to `runCommand()`, making commands
10
+ * testable without touching process state.
11
+ *
12
+ * @module dreamcli/core/testkit
13
+ */
14
+
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';
22
+ import type { CapturedOutput } from '#internals/core/output/index.ts';
23
+ 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';
31
+ import type { RunOptions, RunResult } from '#internals/core/schema/run.ts';
32
+
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
+ // RunOptions and RunResult are defined in schema/run.ts so the execution
52
+ // contract is shared by schema, CLI dispatch, and testkit. Re-exported here
53
+ // for public testkit continuity.
54
+
55
+ // --- Core execution pipeline
56
+
57
+ /**
58
+ * Run a command builder against the given argv with injected options.
59
+ *
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
67
+ *
68
+ * All errors are caught and converted to structured `RunResult`s with
69
+ * appropriate exit codes. The function never throws.
70
+ *
71
+ * @param cmd - The command builder (must have an action handler)
72
+ * @param argv - Raw argv strings (NOT including the command name itself)
73
+ * @param options - Injectable runtime state
74
+ * @returns Structured run result with exit code and captured output
75
+ */
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> {
81
+ let out: Out;
82
+ let captured: CapturedOutput;
83
+ if (options?.out !== undefined) {
84
+ out = options.out;
85
+ captured = options.captured ?? { stdout: [], stderr: [], activity: [] };
86
+ } else {
87
+ const captureOptions = {
88
+ ...(options?.verbosity !== undefined ? { verbosity: options.verbosity } : {}),
89
+ ...(options?.jsonMode !== undefined ? { jsonMode: options.jsonMode } : {}),
90
+ ...(options?.isTTY !== undefined ? { isTTY: options.isTTY } : {}),
91
+ };
92
+ [out, captured] = createCaptureOutput(
93
+ Object.keys(captureOptions).length > 0 ? captureOptions : undefined,
94
+ );
95
+ }
96
+
97
+ // Use merged schema (with propagated flags) when provided by dispatch layer,
98
+ // otherwise fall back to the command's own schema.
99
+ const schema = options?.mergedSchema ?? cmd.schema;
100
+ const meta: CommandMeta = options?.meta ?? {
101
+ name: schema.name,
102
+ bin: options?.help?.binName ?? schema.name,
103
+ version: undefined,
104
+ command: schema.name,
105
+ };
106
+
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
+ });
131
+
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
+ }
205
+ }
206
+
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
239
+
240
+ /**
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.
250
+ *
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.
254
+ *
255
+ * @internal
256
+ */
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
+ /**
348
+ * Format a structured deprecation warning for human-readable stderr output.
349
+ *
350
+ * This is a **consumer-side** formatting function — the resolve layer returns
351
+ * structured `DeprecationWarning` data; consumers decide how to render it.
352
+ *
353
+ * @internal
354
+ */
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
+ export type { RunOptions, RunResult };
365
+ export { runCommand };
package/src/index.ts ADDED
@@ -0,0 +1,164 @@
1
+ /**
2
+ * DreamCLI — Schema-first, fully typed TypeScript CLI framework.
3
+ *
4
+ * Start here for most applications:
5
+ * - {@link cli} to define a program
6
+ * - {@link command} to define commands and groups
7
+ * - {@link flag} and {@link arg} to describe inputs
8
+ *
9
+ * This root entrypoint also re-exports lower-level building blocks such as
10
+ * parsing, resolution, config discovery, and help formatting. Those are useful
11
+ * for advanced integrations, custom tooling, or focused tests, but they are
12
+ * not the typical starting point for application code.
13
+ *
14
+ * Test utilities (runCommand, createCaptureOutput, createTestPrompter, etc.)
15
+ * are available from `dreamcli/testkit`. Runtime adapters (createAdapter,
16
+ * RuntimeAdapter, etc.) are available from `dreamcli/runtime`.
17
+ *
18
+ * @module dreamcli
19
+ */
20
+
21
+ export type {
22
+ BeforeParseParams,
23
+ CLIOptions,
24
+ CLIPlugin,
25
+ CLIPluginHooks,
26
+ CLIRunOptions,
27
+ CLISchema,
28
+ ConfigSettings,
29
+ PackageJsonSettings,
30
+ PluginCommandContext,
31
+ ResolvedCommandParams,
32
+ } from './core/cli/index.ts';
33
+ export { CLIBuilder, cli, plugin } from './core/cli/index.ts';
34
+ export type { CompletionOptions, Shell } from './core/completion/index.ts';
35
+ export {
36
+ generateBashCompletion,
37
+ generateCompletion,
38
+ generateZshCompletion,
39
+ SHELLS,
40
+ } from './core/completion/index.ts';
41
+ export type {
42
+ ConfigAdapter,
43
+ ConfigDiscoveryOptions,
44
+ ConfigDiscoveryResult,
45
+ ConfigFound,
46
+ ConfigNotFound,
47
+ FormatLoader,
48
+ PackageJsonAdapter,
49
+ PackageJsonData,
50
+ } from './core/config/index.ts';
51
+ export {
52
+ buildConfigSearchPaths,
53
+ configFormat,
54
+ discoverConfig,
55
+ discoverPackageJson,
56
+ inferCliName,
57
+ } from './core/config/index.ts';
58
+ export type {
59
+ CLIErrorJSON,
60
+ CLIErrorOptions,
61
+ ErrorCode,
62
+ ParseErrorCode,
63
+ ParseErrorOptions,
64
+ ValidationErrorCode,
65
+ ValidationErrorOptions,
66
+ } from './core/errors/index.ts';
67
+ export {
68
+ CLIError,
69
+ isCLIError,
70
+ isParseError,
71
+ isValidationError,
72
+ ParseError,
73
+ ValidationError,
74
+ } from './core/errors/index.ts';
75
+ export type { HelpOptions } from './core/help/index.ts';
76
+ export { formatHelp } from './core/help/index.ts';
77
+ export type { JsonSchemaOptions } from './core/json-schema/index.ts';
78
+ export { generateInputSchema, generateSchema } from './core/json-schema/index.ts';
79
+ export type { OutputOptions, Verbosity, WriteFn } from './core/output/index.ts';
80
+ export { createOutput } from './core/output/index.ts';
81
+ export type { ParseResult, Token } from './core/parse/index.ts';
82
+ export { parse, tokenize } from './core/parse/index.ts';
83
+ export type {
84
+ PromptEngine,
85
+ ReadFn,
86
+ ResolvedMultiselectPromptConfig,
87
+ ResolvedPromptConfig,
88
+ ResolvedSelectPromptConfig,
89
+ } from './core/prompt/index.ts';
90
+ export { createTerminalPrompter, resolvePromptConfig } from './core/prompt/index.ts';
91
+ export type { DeprecationWarning, ResolveOptions, ResolveResult } from './core/resolve/index.ts';
92
+ export { resolve } from './core/resolve/index.ts';
93
+ export type {
94
+ ActionHandler,
95
+ ActionParams,
96
+ ActivityEvent,
97
+ AnyCommandBuilder,
98
+ ArgConfig,
99
+ ArgFactory,
100
+ ArgKind,
101
+ ArgParseFn,
102
+ ArgPresence,
103
+ ArgSchema,
104
+ CommandArgEntry,
105
+ CommandConfig,
106
+ CommandExample,
107
+ CommandMeta,
108
+ CommandSchema,
109
+ ConfirmPromptConfig,
110
+ DeriveHandler,
111
+ DeriveParams,
112
+ Fallback,
113
+ FlagConfig,
114
+ FlagFactory,
115
+ FlagKind,
116
+ FlagParseFn,
117
+ FlagPresence,
118
+ FlagSchema,
119
+ InferArg,
120
+ InferArgs,
121
+ InferFlag,
122
+ InferFlags,
123
+ InputPromptConfig,
124
+ InteractiveParams,
125
+ InteractiveResolver,
126
+ InteractiveResult,
127
+ Middleware,
128
+ MiddlewareHandler,
129
+ MiddlewareParams,
130
+ MultiselectPromptConfig,
131
+ Out,
132
+ ProgressHandle,
133
+ ProgressOptions,
134
+ PromptConfig,
135
+ PromptConfigBase,
136
+ PromptKind,
137
+ PromptResult,
138
+ ResolvedArgValue,
139
+ ResolvedValue,
140
+ RunResult,
141
+ SelectChoice,
142
+ SelectPromptConfig,
143
+ SpinnerHandle,
144
+ SpinnerOptions,
145
+ TableColumn,
146
+ TableFormat,
147
+ TableOptions,
148
+ TableStream,
149
+ WithArgPresence,
150
+ WithPresence,
151
+ WithVariadic,
152
+ } from './core/schema/index.ts';
153
+ export {
154
+ ArgBuilder,
155
+ arg,
156
+ CommandBuilder,
157
+ command,
158
+ createArgSchema,
159
+ createSchema,
160
+ FlagBuilder,
161
+ flag,
162
+ group,
163
+ middleware,
164
+ } from './core/schema/index.ts';
@@ -0,0 +1,74 @@
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"]`)