@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,7 +1,7 @@
1
1
  /**
2
2
  * Deno runtime adapter implementation.
3
3
  *
4
- * Bridges the platform-agnostic `RuntimeAdapter` interface to Deno's
4
+ * Bridges the platform-agnostic {@linkcode RuntimeAdapter} interface to Deno's
5
5
  * namespace APIs (`Deno.args`, `Deno.env`, `Deno.cwd()`, etc.).
6
6
  *
7
7
  * Deno requires explicit permissions for some operations. The adapter
@@ -16,7 +16,7 @@
16
16
  * No permissions are needed for `Deno.args`, `Deno.stdout`, `Deno.stderr`,
17
17
  * `Deno.stdin`, `Deno.exit()`, or TTY detection.
18
18
  *
19
- * @module dreamcli/runtime/deno
19
+ * @module @kjanat/dreamcli/runtime/deno
20
20
  */
21
21
 
22
22
  import type { WriteFn } from '#internals/core/output/index.ts';
@@ -38,6 +38,7 @@ import { assertRuntimeVersionSupported } from './support.ts';
38
38
  * an empty env object.
39
39
  */
40
40
  interface DenoNamespace {
41
+ /** Build target metadata (OS detection). */
41
42
  readonly build: {
42
43
  readonly os:
43
44
  | 'darwin'
@@ -50,6 +51,7 @@ interface DenoNamespace {
50
51
  | 'solaris'
51
52
  | 'illumos';
52
53
  };
54
+ /** Deno version info — used for minimum-version guard. */
53
55
  readonly version?: {
54
56
  readonly deno?: string;
55
57
  };
@@ -67,6 +69,7 @@ interface DenoNamespace {
67
69
  /** Current working directory (may throw if `--allow-read` is denied for cwd). */
68
70
  cwd(): string;
69
71
 
72
+ /** Standard output — synchronous byte writer with TTY detection. */
70
73
  readonly stdout: {
71
74
  /** Write raw bytes to stdout synchronously. */
72
75
  writeSync(p: Uint8Array): number;
@@ -74,11 +77,13 @@ interface DenoNamespace {
74
77
  isTerminal(): boolean;
75
78
  };
76
79
 
80
+ /** Standard error — synchronous byte writer. */
77
81
  readonly stderr: {
78
82
  /** Write raw bytes to stderr synchronously. */
79
83
  writeSync(p: Uint8Array): number;
80
84
  };
81
85
 
86
+ /** Standard input — TTY detection and readable byte stream. */
82
87
  readonly stdin: {
83
88
  /** Whether stdin is connected to a TTY. */
84
89
  isTerminal(): boolean;
@@ -143,19 +148,19 @@ function safeCwd(deno: DenoNamespace): string {
143
148
  * Create a runtime adapter backed by the Deno namespace.
144
149
  *
145
150
  * Reads `Deno.args`, `Deno.env`, `Deno.cwd()`, and wraps Deno's stream-based
146
- * I/O into the `WriteFn`/`ReadFn` functions expected by the framework.
151
+ * I/O into the {@linkcode WriteFn}/{@linkcode ReadFn} functions expected by the framework.
147
152
  *
148
153
  * Unlike Node/Bun, Deno strips the binary and script path from `Deno.args`.
149
154
  * The adapter prepends synthetic entries (`['deno', 'run']`) so the argv
150
- * shape matches the `RuntimeAdapter` contract (binary + script + user args).
155
+ * shape matches the {@linkcode RuntimeAdapter} contract (binary + script + user args).
151
156
  *
152
157
  * @param ns - Override the Deno namespace (useful for testing the adapter itself).
153
- * @returns A `RuntimeAdapter` backed by Deno's namespace APIs.
158
+ * @returns A {@linkcode RuntimeAdapter} backed by Deno's namespace APIs.
154
159
  *
155
160
  * @example
156
161
  * ```ts
157
- * import { cli } from 'dreamcli';
158
- * import { createDenoAdapter } from 'dreamcli/runtime';
162
+ * import { cli } from '@kjanat/dreamcli';
163
+ * import { createDenoAdapter } from '@kjanat/dreamcli/runtime';
159
164
  *
160
165
  * cli('mycli')
161
166
  * .command(deploy)
@@ -185,7 +190,7 @@ function createDenoAdapter(ns?: DenoNamespace): RuntimeAdapter {
185
190
  };
186
191
 
187
192
  // --- Stdin line reading ---
188
- const stdinRead: ReadFn = () => readDenoStdinLine(d);
193
+ const stdinRead = createDenoReadLine(d);
189
194
 
190
195
  // --- Filesystem ---
191
196
  const readFile = async (path: string): Promise<string | null> => {
@@ -288,32 +293,41 @@ async function readDenoStdinAll(deno: DenoNamespace, stdinIsTTY: boolean): Promi
288
293
  *
289
294
  * @internal
290
295
  */
291
- async function readDenoStdinLine(deno: DenoNamespace): Promise<string | null> {
292
- const reader = deno.stdin.readable.getReader();
296
+ function createDenoReadLine(deno: DenoNamespace): ReadFn {
293
297
  const decoder = new TextDecoder();
294
298
  let buffer = '';
299
+ let done = false;
295
300
 
296
- try {
297
- for (;;) {
298
- const { value, done } = await reader.read();
299
- if (done) {
300
- // Flush any trailing bytes held by the streaming decoder
301
- // (partial multibyte UTF-8 sequences buffered internally).
302
- buffer += decoder.decode();
303
- return buffer.length > 0 ? buffer : null;
304
- }
305
- buffer += decoder.decode(value, { stream: true });
306
- const newlineIndex = buffer.indexOf('\n');
307
- if (newlineIndex !== -1) {
308
- // Return the line without the newline character.
309
- // Remaining data after the newline is lost — this is acceptable
310
- // because each prompt reads one line at a time.
311
- return buffer.slice(0, newlineIndex).replace(/\r$/, '');
301
+ return async (): Promise<string | null> => {
302
+ const reader = deno.stdin.readable.getReader();
303
+ try {
304
+ for (;;) {
305
+ const newlineIndex = buffer.indexOf('\n');
306
+ if (newlineIndex !== -1) {
307
+ const line = buffer.slice(0, newlineIndex).replace(/\r$/, '');
308
+ buffer = buffer.slice(newlineIndex + 1);
309
+ return line;
310
+ }
311
+
312
+ if (done) {
313
+ if (buffer.length === 0) return null;
314
+ const line = buffer;
315
+ buffer = '';
316
+ return line;
317
+ }
318
+
319
+ const { value, done: readDone } = await reader.read();
320
+ if (readDone) {
321
+ buffer += decoder.decode();
322
+ done = true;
323
+ continue;
324
+ }
325
+ buffer += decoder.decode(value, { stream: true });
312
326
  }
327
+ } finally {
328
+ reader.releaseLock();
313
329
  }
314
- } finally {
315
- reader.releaseLock();
316
- }
330
+ };
317
331
  }
318
332
 
319
333
  // --- Home / config directory resolution
@@ -13,7 +13,7 @@
13
13
  * Detection order matters: Bun provides a Node-compatible `process`
14
14
  * global, so it must be checked *before* Node to avoid misidentification.
15
15
  *
16
- * @module dreamcli/runtime/detect
16
+ * @module @kjanat/dreamcli/runtime/detect
17
17
  */
18
18
 
19
19
  // --- Runtime type
@@ -57,8 +57,11 @@ const RUNTIMES: readonly ['node', 'bun', 'deno', 'unknown'] = [
57
57
  * typed just enough to distinguish runtimes safely.
58
58
  */
59
59
  interface GlobalForDetect {
60
+ /** Present when running on Bun. */
60
61
  readonly Bun?: { readonly version?: string };
62
+ /** Present when running on Deno. */
61
63
  readonly Deno?: { readonly version?: { readonly deno?: string } };
64
+ /** Present on Node.js (and Bun, which mimics it). */
62
65
  readonly process?: { readonly versions?: { readonly node?: string; readonly bun?: string } };
63
66
  }
64
67
 
@@ -6,7 +6,7 @@
6
6
  * adapters wrap platform-specific APIs (Node `process`, Deno namespace, etc.)
7
7
  * behind this uniform interface.
8
8
  *
9
- * @module dreamcli/runtime
9
+ * @module @kjanat/dreamcli/runtime
10
10
  */
11
11
 
12
12
  export type { RuntimeAdapter, TestAdapterOptions } from './adapter.ts';
@@ -1,15 +1,15 @@
1
1
  /**
2
2
  * Node.js runtime adapter implementation.
3
3
  *
4
- * Bridges the platform-agnostic `RuntimeAdapter` interface to Node.js's
4
+ * Bridges the platform-agnostic {@linkcode RuntimeAdapter} interface to Node.js's
5
5
  * `globalThis.process` object. This adapter is also compatible with Bun,
6
6
  * which provides a Node-compatible `process` global.
7
7
  *
8
8
  * The adapter reads process state once at creation time and exposes it
9
- * through the immutable `RuntimeAdapter` interface. I/O writers wrap
9
+ * through the immutable {@linkcode RuntimeAdapter} interface. I/O writers wrap
10
10
  * `process.stdout.write` and `process.stderr.write`.
11
11
  *
12
- * @module dreamcli/runtime/node
12
+ * @module @kjanat/dreamcli/runtime/node
13
13
  */
14
14
 
15
15
  import type { WriteFn } from '#internals/core/output/index.ts';
@@ -42,27 +42,35 @@ interface NodeSystemError {
42
42
  * actually reads from the global.
43
43
  */
44
44
  interface NodeProcess {
45
+ /** Raw process arguments (`[binary, script, ...userArgs]`). */
45
46
  readonly argv: readonly string[];
47
+ /** Environment variables (values are `undefined` for unset keys). */
46
48
  readonly env: Readonly<Record<string, string | undefined>>;
49
+ /** Runtime version strings — used for version-guard checks. */
47
50
  readonly versions?: {
48
51
  readonly node?: string;
49
52
  readonly bun?: string;
50
53
  };
54
+ /** Return the current working directory. */
51
55
  cwd(): string;
52
56
  /** Platform identifier (e.g. `'linux'`, `'darwin'`, `'win32'`). */
53
57
  readonly platform: string;
58
+ /** Standard input stream with TTY detection and async iteration. */
54
59
  readonly stdin: {
55
60
  readonly isTTY?: boolean;
56
61
  /** Async iterable for reading all of stdin (used by readStdin). */
57
62
  [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
58
63
  };
64
+ /** Standard output stream with TTY detection and write. */
59
65
  readonly stdout: {
60
66
  readonly isTTY?: boolean;
61
67
  write(data: string): unknown;
62
68
  };
69
+ /** Standard error stream with write. */
63
70
  readonly stderr: {
64
71
  write(data: string): unknown;
65
72
  };
73
+ /** Terminate the process with the given exit code. */
66
74
  exit(code: number): never;
67
75
  }
68
76
 
@@ -149,17 +157,17 @@ function assertProcessRuntimeSupported(proc: NodeProcess): void {
149
157
  * Create a runtime adapter backed by Node.js `process` globals.
150
158
  *
151
159
  * Reads `process.argv`, `process.env`, `process.cwd()`, and wraps
152
- * `process.stdout.write`/`process.stderr.write` as `WriteFn` functions.
160
+ * `process.stdout.write`/`process.stderr.write` as {@linkcode WriteFn} functions.
153
161
  *
154
162
  * Also works on Bun, which provides a Node-compatible `process` global.
155
163
  *
156
164
  * @param proc - Override the process object (useful for testing the adapter itself).
157
- * @returns A `RuntimeAdapter` backed by Node.js process state.
165
+ * @returns A {@linkcode RuntimeAdapter} backed by Node.js process state.
158
166
  *
159
167
  * @example
160
168
  * ```ts
161
- * import { cli } from 'dreamcli';
162
- * import { createNodeAdapter } from 'dreamcli/runtime/node';
169
+ * import { cli } from '@kjanat/dreamcli';
170
+ * import { createNodeAdapter } from '@kjanat/dreamcli/runtime/node';
163
171
  *
164
172
  * cli('mycli')
165
173
  * .command(deploy)
@@ -179,7 +187,7 @@ function createNodeAdapter(proc?: NodeProcess): RuntimeAdapter {
179
187
 
180
188
  // Stdin line reading via readline — created lazily on first call.
181
189
  // This avoids importing readline unless prompting actually occurs.
182
- const stdinRead: ReadFn = () => createNodeReadLine(p);
190
+ const stdinRead = createNodeReadLine(p);
183
191
 
184
192
  // --- Filesystem primitives for config discovery ---
185
193
 
@@ -252,24 +260,38 @@ async function readNodeStdinAll(proc: NodeProcess, stdinIsTTY: boolean): Promise
252
260
  *
253
261
  * @internal
254
262
  */
255
- async function createNodeReadLine(proc: NodeProcess): Promise<string | null> {
263
+ function createNodeReadLine(proc: NodeProcess): ReadFn {
256
264
  const iter = proc.stdin[Symbol.asyncIterator]();
257
265
  const decoder = new TextDecoder();
258
266
  let buffer = '';
259
- let result = await iter.next();
267
+ let done = false;
260
268
 
261
- while (!result.done) {
262
- buffer += decoder.decode(result.value, { stream: true });
263
- const nlIndex = buffer.indexOf('\n');
264
- if (nlIndex !== -1) {
265
- return buffer.slice(0, nlIndex).replace(/\r$/, '');
266
- }
267
- result = await iter.next();
268
- }
269
+ return async (): Promise<string | null> => {
270
+ for (;;) {
271
+ const nlIndex = buffer.indexOf('\n');
272
+ if (nlIndex !== -1) {
273
+ const line = buffer.slice(0, nlIndex).replace(/\r$/, '');
274
+ buffer = buffer.slice(nlIndex + 1);
275
+ return line;
276
+ }
277
+
278
+ if (done) {
279
+ if (buffer.length === 0) return null;
280
+ const line = buffer;
281
+ buffer = '';
282
+ return line;
283
+ }
269
284
 
270
- // Flush remaining bytes after stream end
271
- buffer += decoder.decode();
272
- return buffer.length > 0 ? buffer : null;
285
+ const result = await iter.next();
286
+ if (result.done) {
287
+ buffer += decoder.decode();
288
+ done = true;
289
+ continue;
290
+ }
291
+
292
+ buffer += decoder.decode(result.value, { stream: true });
293
+ }
294
+ };
273
295
  }
274
296
 
275
297
  // --- Exports
@@ -5,7 +5,7 @@
5
5
  * These helpers keep the fallback chain identical across runtimes while
6
6
  * letting each adapter supply its own platform detection.
7
7
  *
8
- * @module dreamcli/runtime/paths
8
+ * @module @kjanat/dreamcli/runtime/paths
9
9
  */
10
10
 
11
11
  /**
@@ -49,8 +49,14 @@ function resolveConfigDirectory(
49
49
  const normalizedHome = homedir.replace(/[\\/]+$/, '') || homedir;
50
50
  return `${normalizedHome}\\AppData\\Roaming`;
51
51
  }
52
- const normalizedHome = homedir.replace(/\/+$/, '') || homedir;
53
- return env.XDG_CONFIG_HOME || `${normalizedHome}/.config`;
52
+ const normalizedHome = homedir.replace(/\/+$/, '');
53
+ if (env.XDG_CONFIG_HOME !== undefined && env.XDG_CONFIG_HOME !== '') {
54
+ return env.XDG_CONFIG_HOME;
55
+ }
56
+ if (normalizedHome.length === 0) {
57
+ return '/.config';
58
+ }
59
+ return `${normalizedHome}/.config`;
54
60
  }
55
61
 
56
62
  export { resolveConfigDirectory, resolveHomeDirectory };
@@ -5,27 +5,39 @@
5
5
  * package engines, and docs can stay aligned.
6
6
  *
7
7
  * @internal
8
- * @module dreamcli/runtime/support
8
+ * @module @kjanat/dreamcli/runtime/support
9
9
  */
10
10
 
11
11
  type SupportedRuntime = 'node' | 'bun' | 'deno';
12
12
 
13
+ /**
14
+ * Support entry for a single runtime: version bounds, display names, and adapter mapping.
15
+ *
16
+ * @internal
17
+ */
13
18
  interface RuntimeSupportEntry {
19
+ /** Runtime identifier key. */
14
20
  readonly runtime: SupportedRuntime;
21
+ /** Human-readable name (e.g. `'Node.js'`, `'Bun'`). */
15
22
  readonly displayName: string;
23
+ /** Minimum supported version (semver, e.g. `'22.22.2'`). */
16
24
  readonly minimum: string;
25
+ /** `engines` range string for package.json (e.g. `'>=22.22.2'`). */
17
26
  readonly engineRange: string;
27
+ /** npm/JSR package name that ships this adapter. */
18
28
  readonly packageName: string;
29
+ /** Adapter factory function name (e.g. `'NodeAdapter'`). */
19
30
  readonly adapterName: string;
20
31
  }
21
32
 
33
+ /** All supported runtimes with their version bounds and adapter metadata. @internal */
22
34
  const SUPPORTED_RUNTIMES: readonly RuntimeSupportEntry[] = [
23
35
  {
24
36
  runtime: 'node',
25
37
  displayName: 'Node.js',
26
38
  minimum: '22.22.2',
27
39
  engineRange: '>=22.22.2',
28
- packageName: 'dreamcli',
40
+ packageName: '@kjanat/dreamcli',
29
41
  adapterName: 'NodeAdapter',
30
42
  },
31
43
  {
@@ -33,7 +45,7 @@ const SUPPORTED_RUNTIMES: readonly RuntimeSupportEntry[] = [
33
45
  displayName: 'Bun',
34
46
  minimum: '1.3.11',
35
47
  engineRange: '>=1.3.11',
36
- packageName: 'dreamcli',
48
+ packageName: '@kjanat/dreamcli',
37
49
  adapterName: 'BunAdapter',
38
50
  },
39
51
  {
@@ -54,6 +66,7 @@ interface ParsedVersion {
54
66
 
55
67
  const VERSION_PATTERN = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?/;
56
68
 
69
+ /** Look up the support entry for a given runtime. Throws on unknown runtime. @internal */
57
70
  function getRuntimeSupport(runtime: SupportedRuntime): RuntimeSupportEntry {
58
71
  for (const entry of SUPPORTED_RUNTIMES) {
59
72
  if (entry.runtime === runtime) return entry;
@@ -85,11 +98,13 @@ function compareVersions(left: ParsedVersion, right: ParsedVersion): number {
85
98
  return left.patch - right.patch;
86
99
  }
87
100
 
101
+ /** Format a human-readable version requirement string (e.g. `'Node.js >= 22.22.2'`). @internal */
88
102
  function formatRuntimeRequirement(runtime: SupportedRuntime): string {
89
103
  const support = getRuntimeSupport(runtime);
90
104
  return `${support.displayName} >= ${support.minimum}`;
91
105
  }
92
106
 
107
+ /** Check whether a version string meets the minimum for the given runtime. @internal */
93
108
  function isRuntimeVersionSupported(runtime: SupportedRuntime, version: string): boolean {
94
109
  const parsedVersion = parseVersion(version);
95
110
  const minimumVersion = parseVersion(getRuntimeSupport(runtime).minimum);
@@ -97,6 +112,7 @@ function isRuntimeVersionSupported(runtime: SupportedRuntime, version: string):
97
112
  return compareVersions(parsedVersion, minimumVersion) >= 0;
98
113
  }
99
114
 
115
+ /** Throw if the detected version is below the minimum. No-op when version is undefined. @internal */
100
116
  function assertRuntimeVersionSupported(
101
117
  runtime: SupportedRuntime,
102
118
  version: string | undefined,
@@ -105,7 +121,7 @@ function assertRuntimeVersionSupported(
105
121
  if (isRuntimeVersionSupported(runtime, version)) return;
106
122
 
107
123
  throw new Error(
108
- `dreamcli requires ${formatRuntimeRequirement(runtime)}. Detected ${getRuntimeSupport(runtime).displayName} ${version}.`,
124
+ `@kjanat/dreamcli requires ${formatRuntimeRequirement(runtime)}. Detected ${getRuntimeSupport(runtime).displayName} ${version}.`,
109
125
  );
110
126
  }
111
127
 
package/src/runtime.ts CHANGED
@@ -13,7 +13,7 @@
13
13
  * into a custom host, testing runtime behavior directly, or building their own
14
14
  * process/bootstrap layer.
15
15
  *
16
- * @module dreamcli/runtime
16
+ * @module @kjanat/dreamcli/runtime
17
17
  */
18
18
 
19
19
  export type {
package/src/testkit.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Test utilities for DreamCLI commands.
3
3
  *
4
- * Provides `runCommand()` — the in-process test harness — plus test doubles
4
+ * Provides {@linkcode runCommand | runCommand()} — the in-process test harness — plus test doubles
5
5
  * for output capture, prompt simulation, and runtime adaptation.
6
6
  *
7
7
  * Start here for most tests:
@@ -10,14 +10,16 @@
10
10
  * - {@link createTestPrompter} to script interactive answers
11
11
  * - {@link createTestAdapter} when you need adapter-level control
12
12
  *
13
- * @module dreamcli/testkit
13
+ * @module @kjanat/dreamcli/testkit
14
14
  */
15
15
 
16
- export type { CapturedOutput } from './core/output/index.ts';
17
- export { createCaptureOutput } from './core/output/index.ts';
18
- export type { TestAnswer, TestPrompterOptions } from './core/prompt/index.ts';
19
- export { createTestPrompter, PROMPT_CANCEL } from './core/prompt/index.ts';
16
+ export { type CapturedOutput, createCaptureOutput } from './core/output/index.ts';
17
+ export {
18
+ createTestPrompter,
19
+ PROMPT_CANCEL,
20
+ type TestAnswer,
21
+ type TestPrompterOptions,
22
+ } from './core/prompt/index.ts';
20
23
  export type { RunOptions, RunResult } from './core/testkit/index.ts';
21
24
  export { runCommand } from './core/testkit/index.ts';
22
- export type { TestAdapterOptions } from './runtime/index.ts';
23
- export { createTestAdapter } from './runtime/index.ts';
25
+ export { createTestAdapter, type TestAdapterOptions } from './runtime/index.ts';
@@ -1 +0,0 @@
1
- var e=class extends Error{name=`ExitError`;code;constructor(e){super(`Process exited with code ${e}`),this.code=e}};const t=()=>{},n=()=>Promise.resolve(null),r=()=>Promise.resolve(null);function i(i){let a=i?.stdinIsTTY??!1,o=a?void 0:i?.stdinData;return{argv:i?.argv??[`node`,`test`],env:i?.env??{},cwd:i?.cwd??`/test`,stdout:i?.stdout??t,stderr:i?.stderr??t,stdin:i?.stdin??n,readStdin:()=>{if(o===void 0)return Promise.resolve(null);let e=o;return o=void 0,Promise.resolve(e)},isTTY:i?.isTTY??!1,stdinIsTTY:a,exit:i?.exit??(t=>{throw new e(t)}),readFile:i?.readFile??r,homedir:i?.homedir??`/home/test`,configDir:i?.configDir??`/home/test/.config`}}Object.defineProperty(exports,`n`,{enumerable:!0,get:function(){return i}}),Object.defineProperty(exports,`t`,{enumerable:!0,get:function(){return e}});