@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,300 @@
1
+ /**
2
+ * Runtime adapter interface. Core never imports runtime-specific modules directly;
3
+ * all platform-dependent behavior flows through this contract.
4
+ *
5
+ * The adapter abstracts the minimal set of platform-dependent operations:
6
+ * argv/env access, I/O streams, TTY detection, working directory, and
7
+ * process exit. Concrete implementations exist for Node, Bun, and Deno.
8
+ *
9
+ * @module dreamcli/runtime/adapter
10
+ */
11
+
12
+ import type { WriteFn } from '#internals/core/output/index.ts';
13
+ import type { ReadFn } from '#internals/core/prompt/index.ts';
14
+
15
+ // --- Runtime adapter interface — the single platform abstraction boundary
16
+
17
+ /**
18
+ * Runtime adapter interface.
19
+ *
20
+ * Defines the minimal contract between the platform-agnostic core and
21
+ * the host runtime (Node.js, Bun, Deno). Every platform-dependent
22
+ * operation flows through this interface — the core never calls
23
+ * `process.*`, `Deno.*`, or `Bun.*` directly.
24
+ *
25
+ * Adapters are designed to be:
26
+ * - **Immutable in shape:** all properties are readonly
27
+ * - **Minimal:** only the operations the framework actually needs
28
+ * - **Testable:** easily stubbed in tests via `createTestAdapter()`
29
+ *
30
+ * @example
31
+ * ```ts
32
+ * // Production: auto-detected
33
+ * cli('mycli').run(); // uses Node/Bun/Deno adapter
34
+ *
35
+ * // Test: explicit adapter
36
+ * cli('mycli').run({ adapter: createTestAdapter({ argv: ['deploy'] }) });
37
+ * ```
38
+ */
39
+ interface RuntimeAdapter {
40
+ /** Raw argv array (including binary + script path, e.g. `['node', 'cli.js', 'deploy']`). */
41
+ readonly argv: readonly string[];
42
+
43
+ /**
44
+ * Environment variables.
45
+ * Values are `string | undefined` — mirrors Node's `process.env` semantics.
46
+ */
47
+ readonly env: Readonly<Record<string, string | undefined>>;
48
+
49
+ /** Current working directory (absolute path). */
50
+ readonly cwd: string;
51
+
52
+ /** Writer for stdout. Framework routes `out.log`/`out.info` through this. */
53
+ readonly stdout: WriteFn;
54
+
55
+ /** Writer for stderr. Framework routes `out.warn`/`out.error` through this. */
56
+ readonly stderr: WriteFn;
57
+
58
+ /**
59
+ * Line reader for stdin. Used by the prompt engine for interactive input.
60
+ *
61
+ * Returns `null` on EOF (Ctrl+D on Unix, Ctrl+Z on Windows),
62
+ * indicating the user closed the input stream (treated as cancel).
63
+ */
64
+ readonly stdin: ReadFn;
65
+
66
+ /**
67
+ * Read all of stdin as a single string (for piped data).
68
+ *
69
+ * Returns the full stdin contents when data is piped (`stdinIsTTY` is
70
+ * false), or `null` when stdin is a TTY (no piped data available).
71
+ *
72
+ * Used by the resolve chain for args with `.stdin()` configured.
73
+ * Unlike {@link stdin} (which reads one line for prompts), this
74
+ * consumes the entire stream to EOF.
75
+ *
76
+ * @returns Full stdin contents as a string, or `null` if stdin is a TTY.
77
+ */
78
+ readonly readStdin: () => Promise<string | null>;
79
+
80
+ /** Whether stdout is connected to a TTY. */
81
+ readonly isTTY: boolean;
82
+
83
+ /** Whether stdin is connected to a TTY (used for prompt gating). */
84
+ readonly stdinIsTTY: boolean;
85
+
86
+ /**
87
+ * Exit the process with the given code.
88
+ * Must not return (divergent function).
89
+ */
90
+ readonly exit: (code: number) => never;
91
+
92
+ // --- Filesystem primitives (config file discovery) ---
93
+
94
+ /**
95
+ * Read a file as UTF-8 text.
96
+ *
97
+ * Returns file contents on success, `null` if the file does not exist
98
+ * (ENOENT/NotFound). Throws on other I/O errors (permission denied,
99
+ * is-directory, etc.) — those indicate unexpected failures, not
100
+ * "try the next path".
101
+ *
102
+ * Used by config file discovery to probe multiple candidate paths.
103
+ */
104
+ readonly readFile: (path: string) => Promise<string | null>;
105
+
106
+ /**
107
+ * User home directory (absolute path).
108
+ *
109
+ * - Node/Bun: derived from `HOME` / `USERPROFILE` env
110
+ * - Deno: `Deno.env.get('HOME')` / `Deno.env.get('USERPROFILE')`
111
+ */
112
+ readonly homedir: string;
113
+
114
+ /**
115
+ * Platform-specific user configuration directory (absolute path).
116
+ *
117
+ * - Unix: `$XDG_CONFIG_HOME` or `~/.config`
118
+ * - Windows: `%APPDATA%` or `~\AppData\Roaming`
119
+ *
120
+ * Config discovery appends the app-specific subdirectory.
121
+ */
122
+ readonly configDir: string;
123
+ }
124
+
125
+ // --- Test adapter — injectable stub for testing
126
+
127
+ /**
128
+ * Options for creating a test adapter.
129
+ *
130
+ * All fields are optional — sensible defaults are applied for testing
131
+ * scenarios (empty argv, empty env, noop stdout/stderr, non-TTY, exit
132
+ * throws instead of killing the process).
133
+ */
134
+ interface TestAdapterOptions {
135
+ /** Raw argv (defaults to `['node', 'test']`). */
136
+ readonly argv?: readonly string[];
137
+
138
+ /** Environment variables (defaults to `{}`). */
139
+ readonly env?: Readonly<Record<string, string | undefined>>;
140
+
141
+ /** Working directory (defaults to `'/test'`). */
142
+ readonly cwd?: string;
143
+
144
+ /** Stdout writer (defaults to noop). */
145
+ readonly stdout?: WriteFn;
146
+
147
+ /** Stderr writer (defaults to noop). */
148
+ readonly stderr?: WriteFn;
149
+
150
+ /**
151
+ * Stdin line reader (defaults to returning `null` — immediate EOF).
152
+ *
153
+ * Use a custom `ReadFn` to simulate user input in tests.
154
+ */
155
+ readonly stdin?: ReadFn;
156
+
157
+ /**
158
+ * Piped stdin data for testing args with `.stdin()` configured.
159
+ *
160
+ * When provided and `stdinIsTTY` is `false`, `readStdin()` returns this
161
+ * string once, then `null` on subsequent reads. When absent, or when
162
+ * `stdinIsTTY` is `true`, `readStdin()` returns `null`.
163
+ *
164
+ * @example
165
+ * ```ts
166
+ * createTestAdapter({
167
+ * stdinData: '{"key": "value"}',
168
+ * })
169
+ * ```
170
+ */
171
+ readonly stdinData?: string;
172
+
173
+ /** TTY flag for stdout (defaults to `false`). */
174
+ readonly isTTY?: boolean;
175
+
176
+ /** TTY flag for stdin (defaults to `false`). */
177
+ readonly stdinIsTTY?: boolean;
178
+
179
+ /**
180
+ * Exit function (defaults to throwing `ExitError`).
181
+ * The default throw-based exit allows tests to catch the exit code.
182
+ */
183
+ readonly exit?: (code: number) => never;
184
+
185
+ // --- Filesystem stubs ---
186
+
187
+ /**
188
+ * File reader stub (defaults to returning `null` — all files not found).
189
+ *
190
+ * Supply a custom function to simulate a virtual filesystem in tests:
191
+ * ```ts
192
+ * createTestAdapter({
193
+ * readFile: (path) => Promise.resolve(
194
+ * path === '/home/test/.config/myapp/config.json'
195
+ * ? '{"region":"eu"}'
196
+ * : null
197
+ * ),
198
+ * })
199
+ * ```
200
+ */
201
+ readonly readFile?: (path: string) => Promise<string | null>;
202
+
203
+ /** Home directory (defaults to `'/home/test'`). */
204
+ readonly homedir?: string;
205
+
206
+ /** Config directory (defaults to `'/home/test/.config'`). */
207
+ readonly configDir?: string;
208
+ }
209
+
210
+ /**
211
+ * Error thrown by the default test adapter exit function.
212
+ *
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:
215
+ *
216
+ * ```ts
217
+ * try {
218
+ * await cli.run({ adapter: createTestAdapter() });
219
+ * } catch (e) {
220
+ * if (e instanceof ExitError) expect(e.code).toBe(0);
221
+ * }
222
+ * ```
223
+ */
224
+ class ExitError extends Error {
225
+ /** @override */
226
+ override readonly name = 'ExitError';
227
+
228
+ /** The exit code passed to `exit()`. */
229
+ readonly code: number;
230
+
231
+ constructor(code: number) {
232
+ super(`Process exited with code ${code}`);
233
+ this.code = code;
234
+ }
235
+ }
236
+
237
+ /** Noop writer — silently discards output. */
238
+ const noopWrite: WriteFn = () => {};
239
+
240
+ /** Noop reader — returns `null` (EOF) immediately. */
241
+ const eofRead: ReadFn = () => Promise.resolve(null);
242
+
243
+ /** Noop file reader — returns `null` (not found) for all paths. */
244
+ const noopReadFile: (path: string) => Promise<string | null> = () => Promise.resolve(null);
245
+
246
+ /**
247
+ * Create a test runtime adapter with injectable process state.
248
+ *
249
+ * Use this in `dreamcli/testkit` tests when you need to simulate argv,
250
+ * environment variables, TTY state, stdin, or config-file reads without
251
+ * touching the host process.
252
+ *
253
+ * @param options - Optional overrides for any adapter field.
254
+ * @returns A `RuntimeAdapter` suitable for test scenarios.
255
+ *
256
+ * @example
257
+ * ```ts
258
+ * const adapter = createTestAdapter({
259
+ * argv: ['node', 'cli.js', 'deploy', '--force'],
260
+ * env: { DEPLOY_REGION: 'us' },
261
+ * });
262
+ *
263
+ * const result = await cli('mycli').run({ adapter });
264
+ * ```
265
+ */
266
+ function createTestAdapter(options?: TestAdapterOptions): RuntimeAdapter {
267
+ const stdinIsTTY = options?.stdinIsTTY ?? false;
268
+ let stdinData = !stdinIsTTY ? options?.stdinData : undefined;
269
+ return {
270
+ argv: options?.argv ?? ['node', 'test'],
271
+ env: options?.env ?? {},
272
+ cwd: options?.cwd ?? '/test',
273
+ stdout: options?.stdout ?? noopWrite,
274
+ stderr: options?.stderr ?? noopWrite,
275
+ stdin: options?.stdin ?? eofRead,
276
+ readStdin: () => {
277
+ if (stdinData === undefined) {
278
+ return Promise.resolve(null);
279
+ }
280
+ const result = stdinData;
281
+ stdinData = undefined;
282
+ return Promise.resolve(result);
283
+ },
284
+ isTTY: options?.isTTY ?? false,
285
+ stdinIsTTY,
286
+ exit:
287
+ options?.exit ??
288
+ ((code: number): never => {
289
+ throw new ExitError(code);
290
+ }),
291
+ readFile: options?.readFile ?? noopReadFile,
292
+ homedir: options?.homedir ?? '/home/test',
293
+ configDir: options?.configDir ?? '/home/test/.config',
294
+ };
295
+ }
296
+
297
+ // --- Exports
298
+
299
+ export type { RuntimeAdapter, TestAdapterOptions };
300
+ export { createTestAdapter, ExitError };
@@ -0,0 +1,110 @@
1
+ /**
2
+ * Auto-detecting adapter factory.
3
+ *
4
+ * Uses {@link detectRuntime} to identify the current runtime and
5
+ * creates the appropriate {@link RuntimeAdapter}. Falls back to the
6
+ * Node adapter for unknown runtimes (safest default — most runtimes
7
+ * provide a Node-compatible `process` global).
8
+ *
9
+ * @module dreamcli/runtime/auto
10
+ */
11
+
12
+ import type { RuntimeAdapter } from './adapter.ts';
13
+ import { createBunAdapter } from './bun.ts';
14
+ import type { DenoNamespace } from './deno.ts';
15
+ import { createDenoAdapter } from './deno.ts';
16
+ import type { GlobalForDetect } from './detect.ts';
17
+ import { detectRuntime } from './detect.ts';
18
+ import { createNodeAdapter } from './node.ts';
19
+ import { assertRuntimeVersionSupported } from './support.ts';
20
+
21
+ function detectRuntimeVersion(
22
+ runtime: ReturnType<typeof detectRuntime>,
23
+ globals: GlobalForDetect,
24
+ ): string | undefined {
25
+ switch (runtime) {
26
+ case 'bun':
27
+ return globals.Bun?.version;
28
+ case 'deno':
29
+ return globals.Deno?.version?.deno;
30
+ case 'node':
31
+ return globals.process?.versions?.node;
32
+ case 'unknown':
33
+ return undefined;
34
+ default: {
35
+ const _exhaustive: never = runtime;
36
+ return _exhaustive;
37
+ }
38
+ }
39
+ }
40
+
41
+ function isDenoNamespace(value: unknown): value is DenoNamespace {
42
+ if (typeof value !== 'object' || value === null) return false;
43
+
44
+ const candidate = value as Partial<DenoNamespace>;
45
+ return (
46
+ Array.isArray(candidate.args) &&
47
+ typeof candidate.cwd === 'function' &&
48
+ typeof candidate.exit === 'function' &&
49
+ typeof candidate.readTextFile === 'function' &&
50
+ typeof candidate.env?.get === 'function' &&
51
+ typeof candidate.env.toObject === 'function' &&
52
+ typeof candidate.stdout?.writeSync === 'function' &&
53
+ typeof candidate.stdout.isTerminal === 'function' &&
54
+ typeof candidate.stderr?.writeSync === 'function' &&
55
+ typeof candidate.stdin?.isTerminal === 'function' &&
56
+ typeof candidate.stdin?.readable?.getReader === 'function'
57
+ );
58
+ }
59
+
60
+ function getInjectedDenoNamespace(globals: GlobalForDetect): DenoNamespace | undefined {
61
+ const candidate = (globals as { readonly Deno?: unknown }).Deno;
62
+ return isDenoNamespace(candidate) ? candidate : undefined;
63
+ }
64
+
65
+ // --- Auto-adapter factory
66
+
67
+ /**
68
+ * Create a runtime adapter for the current environment.
69
+ *
70
+ * Detection order follows {@link detectRuntime}: Bun → Deno → Node → unknown.
71
+ * Unknown runtimes fall back to the Node adapter because most JS runtimes
72
+ * expose a Node-compatible `process` global.
73
+ *
74
+ * @param globals - Override `globalThis` for testing. Production callers
75
+ * should omit this parameter.
76
+ * @returns A `RuntimeAdapter` for the detected runtime.
77
+ *
78
+ * @example
79
+ * ```ts
80
+ * import { cli } from 'dreamcli';
81
+ *
82
+ * // Auto-detects Node/Bun/Deno and creates the right adapter
83
+ * cli('mycli').run(); // uses createAdapter() internally
84
+ * ```
85
+ */
86
+ function createAdapter(globals?: GlobalForDetect): RuntimeAdapter {
87
+ const runtimeGlobals = globals ?? globalThis;
88
+ const runtime = detectRuntime(runtimeGlobals);
89
+ if (runtime !== 'unknown') {
90
+ assertRuntimeVersionSupported(runtime, detectRuntimeVersion(runtime, runtimeGlobals));
91
+ }
92
+
93
+ switch (runtime) {
94
+ case 'bun':
95
+ return createBunAdapter();
96
+ case 'deno':
97
+ return createDenoAdapter(getInjectedDenoNamespace(runtimeGlobals));
98
+ case 'node':
99
+ case 'unknown':
100
+ return createNodeAdapter();
101
+ default: {
102
+ const _exhaustive: never = runtime;
103
+ return _exhaustive;
104
+ }
105
+ }
106
+ }
107
+
108
+ // --- Exports
109
+
110
+ export { createAdapter };
@@ -0,0 +1,55 @@
1
+ /**
2
+ * Bun runtime adapter implementation.
3
+ *
4
+ * Bun provides a Node-compatible `process` global, so this adapter
5
+ * delegates to {@link createNodeAdapter} for all operations. The
6
+ * separate factory exists to:
7
+ *
8
+ * 1. Make runtime selection explicit when auto-detection picks Bun
9
+ * 2. Provide an extension point for Bun-specific overrides in the future
10
+ * (e.g. `Bun.write` for optimized I/O, `Bun.stdin` for streaming)
11
+ *
12
+ * @module dreamcli/runtime/bun
13
+ */
14
+
15
+ import type { RuntimeAdapter } from './adapter.ts';
16
+ import type { NodeProcess } from './node.ts';
17
+ import { createNodeAdapter } from './node.ts';
18
+ import { assertRuntimeVersionSupported } from './support.ts';
19
+
20
+ function resolveBunVersion(proc?: NodeProcess): string | undefined {
21
+ if (proc?.versions?.bun !== undefined) return proc.versions.bun;
22
+ return (globalThis as unknown as { Bun?: { version?: string } }).Bun?.version;
23
+ }
24
+
25
+ // --- Bun adapter factory
26
+
27
+ /**
28
+ * Create a runtime adapter backed by Bun's Node-compatible `process` global.
29
+ *
30
+ * Bun exposes `globalThis.process` with the same shape as Node.js, so this
31
+ * delegates entirely to {@link createNodeAdapter}. If Bun-specific optimizations
32
+ * are needed in the future (e.g. `Bun.write` for I/O), they can be layered
33
+ * here without changing the public API.
34
+ *
35
+ * @param proc - Override the process object (useful for testing the adapter itself).
36
+ * @returns A `RuntimeAdapter` backed by Bun's process state.
37
+ *
38
+ * @example
39
+ * ```ts
40
+ * import { cli } from 'dreamcli';
41
+ * import { createBunAdapter } from 'dreamcli/runtime/bun';
42
+ *
43
+ * cli('mycli')
44
+ * .command(deploy)
45
+ * .run({ adapter: createBunAdapter() });
46
+ * ```
47
+ */
48
+ function createBunAdapter(proc?: NodeProcess): RuntimeAdapter {
49
+ assertRuntimeVersionSupported('bun', resolveBunVersion(proc));
50
+ return createNodeAdapter(proc);
51
+ }
52
+
53
+ // --- Exports
54
+
55
+ export { createBunAdapter };