@kjanat/dreamcli 4.0.0-rc.3 → 4.1.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 (212) hide show
  1. package/README.md +5 -7
  2. package/dist/{runtime/adapter.d.mts → adapter-YM5QGi3M.d.mts} +4 -4
  3. package/dist/completion-CUMeOnAz.mjs +6 -0
  4. package/dist/completion.d.mts +90 -0
  5. package/dist/completion.mjs +1 -0
  6. package/dist/config-CrlScpYX.mjs +1 -0
  7. package/dist/config.d.mts +2 -0
  8. package/dist/config.mjs +1 -0
  9. package/dist/core-DvXUolc_.mjs +17 -0
  10. package/dist/{core/json-schema/index.d.mts → index-3l8uj16E.d.mts} +43 -34
  11. package/dist/{core/cli/index.d.mts → index-BAj2y70U.d.mts} +116 -57
  12. package/dist/index-BziI2aKc.d.mts +5440 -0
  13. package/dist/index-Cap0MA2V.d.mts +277 -0
  14. package/dist/index-Cp9kt2t-.d.mts +370 -0
  15. package/dist/index-DWsnGZlx.d.mts +831 -0
  16. package/dist/index.d.mts +190 -41
  17. package/dist/index.mjs +1 -26
  18. package/dist/json-schema-DRlrz_IV.mjs +52 -0
  19. package/dist/json-schema.d.mts +2 -0
  20. package/dist/json-schema.mjs +1 -0
  21. package/dist/package-json-BgE9YjjQ.mjs +3 -0
  22. package/dist/prompt.d.mts +48 -0
  23. package/dist/prompt.mjs +1 -0
  24. package/dist/rolldown-runtime-G4Kt5YOX.mjs +1 -0
  25. package/dist/runtime.d.mts +2 -6
  26. package/dist/runtime.mjs +1 -6
  27. package/dist/terminal-C8KTXjv5.mjs +6 -0
  28. package/dist/test-prompter-v__jT2yG.mjs +1 -0
  29. package/dist/testkit.d.mts +54 -6
  30. package/dist/testkit.mjs +1 -5
  31. package/dist/version.mjs +1 -7
  32. package/dreamcli.schema.json +697 -538
  33. package/package.json +29 -7
  34. package/skills/cli-creation/SKILL.md +16 -11
  35. package/CHANGELOG.md +0 -1116
  36. package/dist/core/cli/builtins.d.mts +0 -117
  37. package/dist/core/cli/builtins.mjs +0 -135
  38. package/dist/core/cli/compiled.d.mts +0 -66
  39. package/dist/core/cli/compiled.mjs +0 -76
  40. package/dist/core/cli/dispatch.d.mts +0 -115
  41. package/dist/core/cli/dispatch.mjs +0 -205
  42. package/dist/core/cli/help-links.d.mts +0 -27
  43. package/dist/core/cli/help-links.mjs +0 -41
  44. package/dist/core/cli/index.mjs +0 -1271
  45. package/dist/core/cli/planner.d.mts +0 -174
  46. package/dist/core/cli/planner.mjs +0 -323
  47. package/dist/core/cli/plugin.d.mts +0 -94
  48. package/dist/core/cli/plugin.mjs +0 -41
  49. package/dist/core/cli/propagate.d.mts +0 -39
  50. package/dist/core/cli/propagate.mjs +0 -57
  51. package/dist/core/cli/reserved-flags.d.mts +0 -19
  52. package/dist/core/cli/reserved-flags.mjs +0 -158
  53. package/dist/core/cli/root-help.d.mts +0 -53
  54. package/dist/core/cli/root-help.mjs +0 -221
  55. package/dist/core/cli/root-output-flags.d.mts +0 -74
  56. package/dist/core/cli/root-output-flags.mjs +0 -169
  57. package/dist/core/cli/root-surface.d.mts +0 -64
  58. package/dist/core/cli/root-surface.mjs +0 -28
  59. package/dist/core/cli/runtime-preflight.d.mts +0 -213
  60. package/dist/core/cli/runtime-preflight.mjs +0 -221
  61. package/dist/core/completion/index.d.mts +0 -76
  62. package/dist/core/completion/index.mjs +0 -90
  63. package/dist/core/completion/shells/bash.d.mts +0 -23
  64. package/dist/core/completion/shells/bash.mjs +0 -312
  65. package/dist/core/completion/shells/fish.d.mts +0 -19
  66. package/dist/core/completion/shells/fish.mjs +0 -164
  67. package/dist/core/completion/shells/powershell.d.mts +0 -13
  68. package/dist/core/completion/shells/powershell.mjs +0 -360
  69. package/dist/core/completion/shells/shared.d.mts +0 -164
  70. package/dist/core/completion/shells/shared.mjs +0 -147
  71. package/dist/core/completion/shells/zsh.d.mts +0 -23
  72. package/dist/core/completion/shells/zsh.mjs +0 -256
  73. package/dist/core/config/index.d.mts +0 -191
  74. package/dist/core/config/index.mjs +0 -285
  75. package/dist/core/config/package-json.d.mts +0 -179
  76. package/dist/core/config/package-json.mjs +0 -353
  77. package/dist/core/errors/index.d.mts +0 -125
  78. package/dist/core/errors/index.mjs +0 -87
  79. package/dist/core/execution/index.d.mts +0 -61
  80. package/dist/core/execution/index.mjs +0 -220
  81. package/dist/core/help/ansi.d.mts +0 -84
  82. package/dist/core/help/ansi.mjs +0 -121
  83. package/dist/core/help/index.d.mts +0 -149
  84. package/dist/core/help/index.mjs +0 -418
  85. package/dist/core/help/theme.d.mts +0 -86
  86. package/dist/core/help/theme.mjs +0 -69
  87. package/dist/core/json-schema/index.mjs +0 -1008
  88. package/dist/core/json-schema/meta-descriptions.generated.d.mts +0 -274
  89. package/dist/core/json-schema/meta-descriptions.generated.mjs +0 -136
  90. package/dist/core/output/activity.d.mts +0 -193
  91. package/dist/core/output/activity.mjs +0 -452
  92. package/dist/core/output/bind.d.mts +0 -37
  93. package/dist/core/output/bind.mjs +0 -56
  94. package/dist/core/output/contracts.d.mts +0 -82
  95. package/dist/core/output/contracts.mjs +0 -57
  96. package/dist/core/output/display-value.d.mts +0 -19
  97. package/dist/core/output/display-value.mjs +0 -32
  98. package/dist/core/output/index.d.mts +0 -344
  99. package/dist/core/output/index.mjs +0 -514
  100. package/dist/core/output/renderers.d.mts +0 -45
  101. package/dist/core/output/renderers.mjs +0 -46
  102. package/dist/core/output/writer.d.mts +0 -39
  103. package/dist/core/output/writer.mjs +0 -12
  104. package/dist/core/parse/index.d.mts +0 -178
  105. package/dist/core/parse/index.mjs +0 -850
  106. package/dist/core/parse/occurrences.d.mts +0 -90
  107. package/dist/core/parse/occurrences.mjs +0 -114
  108. package/dist/core/prompt/index.d.mts +0 -213
  109. package/dist/core/prompt/index.mjs +0 -348
  110. package/dist/core/read-flags/index.d.mts +0 -150
  111. package/dist/core/read-flags/index.mjs +0 -217
  112. package/dist/core/resolve/args.d.mts +0 -39
  113. package/dist/core/resolve/args.mjs +0 -182
  114. package/dist/core/resolve/coerce.d.mts +0 -79
  115. package/dist/core/resolve/coerce.mjs +0 -900
  116. package/dist/core/resolve/config.d.mts +0 -10
  117. package/dist/core/resolve/config.mjs +0 -19
  118. package/dist/core/resolve/contracts.d.mts +0 -146
  119. package/dist/core/resolve/errors.d.mts +0 -10
  120. package/dist/core/resolve/errors.mjs +0 -148
  121. package/dist/core/resolve/flags.d.mts +0 -74
  122. package/dist/core/resolve/flags.mjs +0 -246
  123. package/dist/core/resolve/index.d.mts +0 -44
  124. package/dist/core/resolve/index.mjs +0 -123
  125. package/dist/core/resolve/path-checks.d.mts +0 -48
  126. package/dist/core/resolve/path-checks.mjs +0 -102
  127. package/dist/core/resolve/redaction.d.mts +0 -13
  128. package/dist/core/resolve/redaction.mjs +0 -14
  129. package/dist/core/resolve/stages.d.mts +0 -86
  130. package/dist/core/resolve/stages.mjs +0 -170
  131. package/dist/core/resolve/standard.d.mts +0 -26
  132. package/dist/core/resolve/standard.mjs +0 -212
  133. package/dist/core/schema/activity.d.mts +0 -189
  134. package/dist/core/schema/arg.d.mts +0 -1461
  135. package/dist/core/schema/arg.mjs +0 -1139
  136. package/dist/core/schema/brand.d.mts +0 -17
  137. package/dist/core/schema/cardinality.d.mts +0 -302
  138. package/dist/core/schema/cardinality.mjs +0 -514
  139. package/dist/core/schema/command.d.mts +0 -1132
  140. package/dist/core/schema/command.mjs +0 -999
  141. package/dist/core/schema/flag.d.mts +0 -1495
  142. package/dist/core/schema/flag.mjs +0 -1207
  143. package/dist/core/schema/index.d.mts +0 -15
  144. package/dist/core/schema/index.mjs +0 -10
  145. package/dist/core/schema/middleware.d.mts +0 -129
  146. package/dist/core/schema/middleware.mjs +0 -41
  147. package/dist/core/schema/number-constraints.d.mts +0 -96
  148. package/dist/core/schema/number-constraints.mjs +0 -60
  149. package/dist/core/schema/prompt.d.mts +0 -135
  150. package/dist/core/schema/provenance.d.mts +0 -99
  151. package/dist/core/schema/provenance.mjs +0 -28
  152. package/dist/core/schema/run.d.mts +0 -211
  153. package/dist/core/schema/source.d.mts +0 -180
  154. package/dist/core/schema/source.mjs +0 -206
  155. package/dist/core/schema/standard.d.mts +0 -100
  156. package/dist/core/schema/standard.mjs +0 -15
  157. package/dist/core/schema/stdin.d.mts +0 -97
  158. package/dist/core/schema/stdin.mjs +0 -91
  159. package/dist/core/schema/string-constraints.d.mts +0 -108
  160. package/dist/core/schema/string-constraints.mjs +0 -86
  161. package/dist/core/schema/value-parsers.d.mts +0 -150
  162. package/dist/core/schema/value-parsers.mjs +0 -160
  163. package/dist/core/schema/value.d.mts +0 -243
  164. package/dist/core/schema/value.mjs +0 -573
  165. package/dist/core/testkit/index.d.mts +0 -63
  166. package/dist/core/testkit/index.mjs +0 -102
  167. package/dist/runtime/adapter.mjs +0 -92
  168. package/dist/runtime/auto.d.mts +0 -25
  169. package/dist/runtime/auto.mjs +0 -45
  170. package/dist/runtime/deno.d.mts +0 -99
  171. package/dist/runtime/deno.mjs +0 -265
  172. package/dist/runtime/detect.d.mts +0 -86
  173. package/dist/runtime/detect.mjs +0 -45
  174. package/dist/runtime/index.d.mts +0 -6
  175. package/dist/runtime/node.d.mts +0 -71
  176. package/dist/runtime/node.mjs +0 -228
  177. package/dist/runtime/paths.d.mts +0 -31
  178. package/dist/runtime/paths.mjs +0 -48
  179. package/dist/strings.d.mts +0 -27
  180. package/dist/strings.mjs +0 -22
  181. package/examples/basic.ts +0 -37
  182. package/examples/flag-types.ts +0 -79
  183. package/examples/gh/package.json +0 -45
  184. package/examples/gh/src/commands/auth.ts +0 -66
  185. package/examples/gh/src/commands/issue.ts +0 -120
  186. package/examples/gh/src/commands/pr.ts +0 -125
  187. package/examples/gh/src/data/issues.yaml +0 -5
  188. package/examples/gh/src/data/issues.yaml.d.ts +0 -17
  189. package/examples/gh/src/data/pull-requests.yaml +0 -7
  190. package/examples/gh/src/data/pull-requests.yaml.d.ts +0 -18
  191. package/examples/gh/src/docs.ts +0 -11
  192. package/examples/gh/src/lib/auth.ts +0 -37
  193. package/examples/gh/src/lib/utils.ts +0 -17
  194. package/examples/gh/src/main.test.ts +0 -307
  195. package/examples/gh/src/main.ts +0 -46
  196. package/examples/help-config.ts +0 -43
  197. package/examples/interactive.ts +0 -67
  198. package/examples/json-mode.ts +0 -95
  199. package/examples/middleware.ts +0 -71
  200. package/examples/multi-command.ts +0 -66
  201. package/examples/output-extras.ts +0 -46
  202. package/examples/parser-control.ts +0 -40
  203. package/examples/pwsh-demo/README.md +0 -40
  204. package/examples/pwsh-demo/package.json +0 -41
  205. package/examples/pwsh-demo/pwsh-demo.cmd +0 -3
  206. package/examples/pwsh-demo/smoke-powershell.ps1 +0 -218
  207. package/examples/pwsh-demo/src/main.test.ts +0 -45
  208. package/examples/pwsh-demo/src/main.ts +0 -140
  209. package/examples/spinner-progress.ts +0 -49
  210. package/examples/standard-schema.ts +0 -45
  211. package/examples/testing.ts +0 -147
  212. package/examples/transport-launcher.ts +0 -85
@@ -0,0 +1,277 @@
1
+ import { n as RuntimeAdapter } from "./adapter-YM5QGi3M.mjs";
2
+ //#region src/runtime/detect.d.ts
3
+ /**
4
+ * Auto-detects the current JavaScript runtime environment.
5
+ *
6
+ * Uses `globalThis` feature detection (version globals) to identify
7
+ * the runtime without importing platform-specific modules. This is
8
+ * the recommended approach because each runtime defines a unique
9
+ * global marker:
10
+ *
11
+ * - **Bun:** `globalThis.Bun.version` (string)
12
+ * - **Deno:** `globalThis.Deno.version` (object with `deno` key)
13
+ * - **Node:** `globalThis.process.versions.node` (string)
14
+ *
15
+ * Detection order matters: Bun provides a Node-compatible `process`
16
+ * global, so it must be checked *before* Node to avoid misidentification.
17
+ *
18
+ * @module @kjanat/dreamcli/runtime/detect
19
+ */
20
+ /**
21
+ * Known JavaScript runtime environments.
22
+ *
23
+ * - `'node'` — Node.js
24
+ * - `'bun'` — Bun
25
+ * - `'deno'` — Deno
26
+ * - `'unknown'` — Unrecognized environment
27
+ */
28
+ type Runtime = 'node' | 'bun' | 'deno' | 'unknown';
29
+ /**
30
+ * All known runtime values as a readonly tuple.
31
+ *
32
+ * Useful for validation, iteration, and exhaustiveness checks.
33
+ *
34
+ * @example
35
+ * ```ts
36
+ * if (RUNTIMES.includes(value)) {
37
+ * // value is a valid Runtime
38
+ * }
39
+ * ```
40
+ */
41
+ declare const RUNTIMES: readonly ['node', 'bun', 'deno', 'unknown'];
42
+ /**
43
+ * Minimal `globalThis` shape used for runtime detection.
44
+ *
45
+ * Each field is optional — only the present one identifies the runtime.
46
+ * Typed as `unknown` where we only need truthiness; version fields are
47
+ * typed just enough to distinguish runtimes safely.
48
+ */
49
+ interface GlobalForDetect {
50
+ /** Present when running on Bun. */
51
+ readonly Bun?: {
52
+ readonly version?: string;
53
+ };
54
+ /** Present when running on Deno. */
55
+ readonly Deno?: {
56
+ readonly version?: {
57
+ readonly deno?: string;
58
+ };
59
+ };
60
+ /** Present on Node.js (and Bun, which mimics it). */
61
+ readonly process?: {
62
+ readonly versions?: {
63
+ readonly node?: string;
64
+ readonly bun?: string;
65
+ };
66
+ };
67
+ }
68
+ /**
69
+ * Detect the current JavaScript runtime.
70
+ *
71
+ * Uses `globalThis` feature detection to identify the host runtime.
72
+ * Detection order is significant: Bun is checked before Node because
73
+ * Bun exposes a Node-compatible `process` global.
74
+ *
75
+ * @param globals - Override `globalThis` for testing. Production callers
76
+ * should omit this parameter.
77
+ * @returns The detected {@link Runtime} identifier.
78
+ *
79
+ * @example
80
+ * ```ts
81
+ * const rt = detectRuntime();
82
+ * // rt === 'node' | 'bun' | 'deno' | 'unknown'
83
+ * ```
84
+ */
85
+ declare function detectRuntime(globals?: GlobalForDetect): Runtime;
86
+ //#endregion
87
+ //#region src/runtime/auto.d.ts
88
+ /**
89
+ * Create a runtime adapter for the current environment.
90
+ *
91
+ * Detection order follows {@link detectRuntime}: Bun → Deno → Node → unknown.
92
+ * Only Deno needs a distinct adapter; Bun, Node, and unknown runtimes all use
93
+ * the Node adapter because they expose a Node-compatible `process` global.
94
+ *
95
+ * @param globals - Override `globalThis` for testing. Production callers
96
+ * should omit this parameter.
97
+ * @returns A {@linkcode RuntimeAdapter} for the detected runtime.
98
+ *
99
+ * @example
100
+ * ```ts
101
+ * import { cli } from '@kjanat/dreamcli';
102
+ *
103
+ * // Auto-detects Node/Bun/Deno and creates the right adapter
104
+ * cli('mycli').run(); // uses createAdapter() internally
105
+ * ```
106
+ */
107
+ declare function createAdapter(globals?: GlobalForDetect): RuntimeAdapter;
108
+ //#endregion
109
+ //#region src/runtime/deno.d.ts
110
+ /**
111
+ * Minimal subset of the Deno namespace needed by the adapter.
112
+ *
113
+ * We avoid `@types/deno` to keep the core runtime-agnostic at the type level.
114
+ * This interface declares only what `createDenoAdapter` actually reads.
115
+ *
116
+ * The `env` property is optional because it requires `--allow-env` permission.
117
+ * When permission is denied, the adapter catches the error and falls back to
118
+ * an empty env object.
119
+ */
120
+ interface DenoNamespace {
121
+ /** Build target metadata (OS detection). */
122
+ readonly build: {
123
+ readonly os: 'darwin' | 'linux' | 'android' | 'windows' | 'freebsd' | 'netbsd' | 'aix' | 'solaris' | 'illumos';
124
+ };
125
+ /** Deno version info — used for minimum-version guard. */
126
+ readonly version?: {
127
+ readonly deno?: string;
128
+ };
129
+ /** Raw command-line args (excludes the binary/script — Deno pre-strips them). */
130
+ readonly args: readonly string[];
131
+ /** Environment variable access (requires `--allow-env`). */
132
+ readonly env: {
133
+ /** Get a single env var. Returns `undefined` if unset or permission denied. */
134
+ get(key: string): string | undefined;
135
+ /** Get all env vars as a plain object. Throws on permission denied. */
136
+ toObject(): Record<string, string>;
137
+ };
138
+ /** Current working directory (may throw if `--allow-read` is denied for cwd). */
139
+ cwd(): string;
140
+ /** Standard output — synchronous byte writer with TTY detection. */
141
+ readonly stdout: {
142
+ /** Write raw bytes to stdout synchronously. */
143
+ writeSync(p: Uint8Array): number;
144
+ /** Whether stdout is connected to a TTY. */
145
+ isTerminal(): boolean;
146
+ };
147
+ /** Current console dimensions. */
148
+ consoleSize?(): {
149
+ readonly columns: number;
150
+ readonly rows: number;
151
+ };
152
+ /** Register a native signal listener. */
153
+ addSignalListener?(signal: 'SIGWINCH', listener: () => void): void;
154
+ /** Remove a native signal listener. */
155
+ removeSignalListener?(signal: 'SIGWINCH', listener: () => void): void;
156
+ /** Standard error — synchronous byte writer. */
157
+ readonly stderr: {
158
+ /** Write raw bytes to stderr synchronously. */
159
+ writeSync(p: Uint8Array): number;
160
+ };
161
+ /** Standard input — TTY detection and readable byte stream. */
162
+ readonly stdin: {
163
+ /** Whether stdin is connected to a TTY. */
164
+ isTerminal(): boolean;
165
+ /** Readable stream for stdin bytes. */
166
+ readonly readable: ReadableStream<Uint8Array>;
167
+ };
168
+ /** Exit the process with the given code. */
169
+ exit(code: number): never;
170
+ /** Read a file as UTF-8 text (requires `--allow-read`). */
171
+ readTextFile(path: string): Promise<string>;
172
+ /** Probe a filesystem path (requires `--allow-read`). */
173
+ stat(path: string): Promise<{
174
+ readonly isDirectory: boolean;
175
+ }>;
176
+ /** Create a directory (requires `--allow-write`). */
177
+ mkdir(path: string, options?: {
178
+ readonly recursive?: boolean;
179
+ }): Promise<void>;
180
+ }
181
+ /**
182
+ * Create a runtime adapter backed by the Deno namespace.
183
+ *
184
+ * Reads `Deno.args`, `Deno.env`, `Deno.cwd()`, and wraps Deno's stream-based
185
+ * I/O into the {@linkcode WriteFn}/{@linkcode ReadFn} functions expected by the framework.
186
+ *
187
+ * Unlike Node/Bun, Deno strips the binary and script path from `Deno.args`.
188
+ * The adapter prepends synthetic entries (`['deno', 'run']`) so the argv
189
+ * shape matches the {@linkcode RuntimeAdapter} contract (binary + script + user args).
190
+ *
191
+ * @param ns - Override the Deno namespace (useful for testing the adapter itself).
192
+ * @returns A {@linkcode RuntimeAdapter} backed by Deno's namespace APIs.
193
+ *
194
+ * @example
195
+ * ```ts
196
+ * import { cli } from '@kjanat/dreamcli';
197
+ * import { createDenoAdapter } from '@kjanat/dreamcli/runtime';
198
+ *
199
+ * cli('mycli')
200
+ * .command(deploy)
201
+ * .run({ adapter: createDenoAdapter() });
202
+ * ```
203
+ */
204
+ declare function createDenoAdapter(ns?: DenoNamespace): RuntimeAdapter;
205
+ //#endregion
206
+ //#region src/runtime/node.d.ts
207
+ /**
208
+ * Minimal subset of the Node.js `process` object needed by the adapter.
209
+ *
210
+ * We avoid importing `@types/node` to keep the core runtime-agnostic
211
+ * at the type level. This interface declares only what `createNodeAdapter`
212
+ * actually reads from the global.
213
+ */
214
+ interface NodeProcess {
215
+ /** Raw process arguments (`[binary, script, ...userArgs]`). */
216
+ readonly argv: readonly string[];
217
+ /** Environment variables (values are `undefined` for unset keys). */
218
+ readonly env: Readonly<Record<string, string | undefined>>;
219
+ /** Runtime version strings — used for version-guard checks. */
220
+ readonly versions?: {
221
+ readonly node?: string;
222
+ readonly bun?: string;
223
+ };
224
+ /** Return the current working directory. */
225
+ cwd(): string;
226
+ /** Platform identifier (e.g. `'linux'`, `'darwin'`, `'win32'`). */
227
+ readonly platform: string;
228
+ /** Standard input stream with TTY detection and async iteration. */
229
+ readonly stdin: {
230
+ readonly isTTY?: boolean;
231
+ /** Async iterable for reading all of stdin (used by readStdin). */
232
+ [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
233
+ };
234
+ /** Standard output stream with TTY detection and write. */
235
+ readonly stdout: {
236
+ readonly isTTY?: boolean;
237
+ readonly columns?: number;
238
+ readonly rows?: number;
239
+ getWindowSize?(): readonly [number, number];
240
+ on?(event: 'resize', listener: () => void): unknown;
241
+ on?(event: 'error', listener: (error: Error) => void): unknown;
242
+ off?(event: 'resize', listener: () => void): unknown;
243
+ removeListener?(event: 'resize', listener: () => void): unknown;
244
+ write(data: string, callback?: (error?: Error | null) => void): unknown;
245
+ };
246
+ /** Standard error stream with write. */
247
+ readonly stderr: {
248
+ on?(event: 'error', listener: (error: Error) => void): unknown;
249
+ write(data: string, callback?: (error?: Error | null) => void): unknown;
250
+ };
251
+ /** Terminate the process with the given exit code. */
252
+ exit(code: number): never;
253
+ }
254
+ /**
255
+ * Create a runtime adapter backed by Node.js `process` globals.
256
+ *
257
+ * Reads `process.argv`, `process.env`, `process.cwd()`, and wraps
258
+ * `process.stdout.write`/`process.stderr.write` as {@linkcode WriteFn} functions.
259
+ *
260
+ * Also works on Bun, which provides a Node-compatible `process` global.
261
+ *
262
+ * @param proc - Override the process object (useful for testing the adapter itself).
263
+ * @returns A {@linkcode RuntimeAdapter} backed by Node.js process state.
264
+ *
265
+ * @example
266
+ * ```ts
267
+ * import { cli } from '@kjanat/dreamcli';
268
+ * import { createNodeAdapter } from '@kjanat/dreamcli/runtime/node';
269
+ *
270
+ * cli('mycli')
271
+ * .command(deploy)
272
+ * .run({ adapter: createNodeAdapter() });
273
+ * ```
274
+ */
275
+ declare function createNodeAdapter(proc?: NodeProcess): RuntimeAdapter;
276
+ //#endregion
277
+ export { createAdapter as a, Runtime as c, createDenoAdapter as i, detectRuntime as l, createNodeAdapter as n, GlobalForDetect as o, DenoNamespace as r, RUNTIMES as s, NodeProcess as t };
@@ -0,0 +1,370 @@
1
+ import { n as RuntimeAdapter } from "./adapter-YM5QGi3M.mjs";
2
+ //#region src/core/config/package-json.d.ts
3
+ /**
4
+ * Object form of a manifest's `repository` field
5
+ * (e.g. `{"type":"git","url":"git+https://github.com/u/r.git"}`).
6
+ */
7
+ interface PackageRepository {
8
+ /** Version control system type (usually `'git'`). */
9
+ readonly type?: string;
10
+ /** Repository URL or locator. */
11
+ readonly url?: string;
12
+ /** Subdirectory within a monorepo where the package lives. */
13
+ readonly directory?: string;
14
+ }
15
+ /**
16
+ * Subset of manifest fields relevant to CLI metadata (`package.json`,
17
+ * `deno.json`, `jsr.json`, or preloaded data).
18
+ *
19
+ * All fields are optional — a valid manifest may omit any of them.
20
+ */
21
+ interface PackageJsonData {
22
+ /** Package name (e.g. `@scope/mycli`). */
23
+ readonly name?: string;
24
+ /** Semver version string from manifest metadata. */
25
+ readonly version?: string;
26
+ /** One-line package description. */
27
+ readonly description?: string;
28
+ /** Binary entry point(s) — string for single-bin, object for multi-bin. */
29
+ readonly bin?: string | Readonly<Record<string, string>>;
30
+ /** Project homepage URL. */
31
+ readonly homepage?: string;
32
+ /** Repository locator — URL/shorthand string or `{type, url, directory}` object. */
33
+ readonly repository?: string | PackageRepository;
34
+ }
35
+ /**
36
+ * The subset of {@link RuntimeAdapter} needed for manifest discovery.
37
+ *
38
+ * Using a narrow pick keeps the function easy to test and makes the
39
+ * dependency explicit.
40
+ */
41
+ type PackageJsonAdapter = Pick<RuntimeAdapter, 'readFile' | 'cwd'>;
42
+ /** Options for {@link discoverManifest}. */
43
+ interface ManifestDiscoveryOptions {
44
+ /**
45
+ * Explicit directory or file path to walk up from. Defaults to
46
+ * `adapter.cwd` when omitted. Pass an absolute path inside your own package
47
+ * (e.g. `fileURLToPath(import.meta.url)`) for installable CLIs whose version
48
+ * should reflect the CLI's own package, not the consumer's working directory.
49
+ *
50
+ * This low-level helper takes a resolved path **string** only. The builder
51
+ * sugar `CLIBuilder.manifest({ from })` exposes the same anchor under the name
52
+ * `from` and additionally accepts a `file:` URL string or `URL` instance,
53
+ * normalizing it to a path first.
54
+ */
55
+ readonly startDir?: string;
56
+ /**
57
+ * Candidate manifest filenames, in per-directory priority order
58
+ * (e.g. `['deno.json', 'jsr.json']`). At each directory the first existing
59
+ * file that carries CLI metadata wins, so the nearest manifest directory
60
+ * always takes precedence over file order. A file that parses but holds no
61
+ * recognised metadata (e.g. a config-only `deno.json` with just
62
+ * `tasks`/`imports`) is skipped, so a sibling `jsr.json` — or a manifest
63
+ * higher up — can still be found. Defaults to `['package.json']`.
64
+ *
65
+ * An empty list is a deliberate no-op: with no candidates to probe, the
66
+ * walk-up reads nothing and resolves to `null` (consistent with the
67
+ * "returns `null` when no manifest is found" contract).
68
+ */
69
+ readonly files?: readonly string[];
70
+ }
71
+ /**
72
+ * Discover the nearest manifest (`package.json`, `deno.json`, `jsr.json`, …)
73
+ * by walking up from `startDir` (or `adapter.cwd` when omitted).
74
+ *
75
+ * Convenience helper behind `CLIBuilder.manifest()`. Most apps should let the
76
+ * CLI runtime discover metadata automatically; call this directly when testing
77
+ * metadata inference or embedding the behavior in custom tooling.
78
+ *
79
+ * Candidate files are parsed as JSON with a JSONC fallback — `package.json`,
80
+ * `deno.json`, `jsr.json`, and `deno.jsonc` all qualify, including files that
81
+ * carry `//` / block comments or trailing commas (common in `deno.json`). A
82
+ * file that fails both parses is skipped, so discovery keeps probing.
83
+ *
84
+ * Returns the parsed metadata on success, `null` when no manifest is found
85
+ * (not an error). Malformed JSON, non-object roots, and config-only manifests
86
+ * that carry no recognised metadata (e.g. a `deno.json` with only `tasks` /
87
+ * `imports`) are all skipped, so discovery keeps probing the remaining
88
+ * candidate files and parent directories — the feature is a convenience, not a
89
+ * hard requirement.
90
+ *
91
+ * @param adapter - Adapter providing `readFile` + `cwd`.
92
+ * @param options - Optional anchor (`startDir`) and candidate filenames (`files`).
93
+ *
94
+ * @example
95
+ * ```ts
96
+ * import { discoverManifest } from '@kjanat/dreamcli/config';
97
+ *
98
+ * const meta = await discoverManifest(adapter, { files: ['deno.json', 'jsr.json'] });
99
+ * if (meta !== null) {
100
+ * console.log(meta.version); // '1.2.3'
101
+ * }
102
+ * ```
103
+ */
104
+ declare function discoverManifest(adapter: PackageJsonAdapter, options?: ManifestDiscoveryOptions): Promise<PackageJsonData | null>;
105
+ /**
106
+ * Infer the CLI binary name from manifest data.
107
+ *
108
+ * Resolution order:
109
+ * 1. First key of `bin` object (e.g. `{"mycli": "./dist/cli.js"}` → `"mycli"`)
110
+ * 2. Package `name`, scope stripped by default (e.g. `"@scope/mycli"` → `"mycli"`);
111
+ * pass `{ stripScope: false }` to keep the full scoped name
112
+ * 3. `undefined` if neither exists
113
+ *
114
+ * Note: `bin` keys are never scoped, so `stripScope` only affects the `name`
115
+ * fallback (relevant for `deno.json` / `jsr.json`, which have no `bin` field).
116
+ *
117
+ * @param pkg - Parsed manifest metadata.
118
+ * @param options - `stripScope` (default `true`): strip a leading `@scope/`
119
+ * from the `name` fallback.
120
+ *
121
+ * @example
122
+ * ```ts
123
+ * import { inferCliName } from '@kjanat/dreamcli/config';
124
+ *
125
+ * inferCliName({ bin: { mycli: './dist/cli.js' } }); // 'mycli'
126
+ * inferCliName({ name: '@scope/mycli' }); // 'mycli'
127
+ * inferCliName({ name: '@scope/mycli' }, { stripScope: false }); // '@scope/mycli'
128
+ * inferCliName({ name: 'mycli' }); // 'mycli'
129
+ * inferCliName({}); // undefined
130
+ * ```
131
+ */
132
+ declare function inferCliName(pkg: PackageJsonData, options?: {
133
+ readonly stripScope?: boolean;
134
+ }): string | undefined;
135
+ //#endregion
136
+ //#region src/core/config/repository-url.d.ts
137
+ /** Options for {@link packageRepositoryUrl}. */
138
+ interface PackageRepositoryUrlOptions {
139
+ /**
140
+ * Throw a `CLIError` (code `INVALID_REPOSITORY`) instead of returning
141
+ * `undefined` when the `repository` field is absent or not a recognisable
142
+ * locator. With `require: true` the return type narrows to `string`, so
143
+ * callers that know their manifest carries a valid repository need no
144
+ * assertion — and a bad manifest fails fast with a real message instead
145
+ * of propagating `undefined`.
146
+ *
147
+ * @defaultValue `false`
148
+ */
149
+ readonly require?: boolean;
150
+ }
151
+ /**
152
+ * Resolve a manifest's `repository` field to a browsable `https://` URL.
153
+ *
154
+ * Handles the locator formats npm accepts:
155
+ * - object form: `{ "type": "git", "url": "git+https://github.com/u/r.git" }`
156
+ * - `https`/`git`/`ssh` URLs (`git+` prefix and `.git` suffix stripped)
157
+ * - scp-style locators: `git@github.com:u/r.git`
158
+ * - shorthands: `github:u/r`, `gitlab:u/r`, `bitbucket:u/r`, and bare `u/r`
159
+ * (GitHub, per npm convention)
160
+ *
161
+ * Returns `undefined` when the field is absent or unrecognised — or, with
162
+ * `{ require: true }`, throws instead and the return type is `string`.
163
+ * (The narrowing cannot key off the input type alone: a present `repository`
164
+ * may still be an empty string, a url-less object, or an unparseable
165
+ * locator, so the `string` promise is backed by the runtime check.)
166
+ *
167
+ * @example
168
+ * ```ts
169
+ * packageRepositoryUrl({ repository: 'git+https://github.com/u/r.git' });
170
+ * // 'https://github.com/u/r'
171
+ *
172
+ * const url: string = packageRepositoryUrl(pkg, { require: true });
173
+ * // throws CLIError when pkg.repository is missing or unrecognised
174
+ * ```
175
+ */
176
+ declare function packageRepositoryUrl(pkg: PackageJsonData, options: PackageRepositoryUrlOptions & {
177
+ readonly require: true;
178
+ }): string;
179
+ /** Resolve a manifest repository URL, returning `undefined` for absent or invalid locators. */
180
+ declare function packageRepositoryUrl(pkg: PackageJsonData, options?: PackageRepositoryUrlOptions): string | undefined;
181
+ //#endregion
182
+ //#region src/core/config/index.d.ts
183
+ /**
184
+ * Format loader — parses file content into a config object.
185
+ *
186
+ * Register custom config formats by providing file extensions and a parser.
187
+ * Parsers may return any parsed value; {@link discoverConfig} validates that
188
+ * the result is a plain object before feeding it into the resolution chain.
189
+ *
190
+ * Implementations should throw on syntax or shape errors; the caller wraps
191
+ * those failures as {@link CLIError} with code `CONFIG_PARSE_ERROR`.
192
+ */
193
+ interface FormatLoader {
194
+ /** File extensions this loader handles (without leading dot, e.g. `'toml'`). */
195
+ readonly extensions: readonly string[];
196
+ /**
197
+ * Parse file content into a config value.
198
+ *
199
+ * Arrays, primitives, and `null` are allowed at this boundary so generic
200
+ * parsers like `Bun.YAML.parse` can be passed directly. Those values are
201
+ * still rejected by {@link discoverConfig}, which requires a plain object.
202
+ */
203
+ readonly parse: (content: string) => unknown;
204
+ }
205
+ /** Options for {@link discoverConfig}. */
206
+ interface ConfigDiscoveryOptions {
207
+ /**
208
+ * Explicit config file path (`--config` override).
209
+ * When provided, skips search — loads only this path.
210
+ */
211
+ readonly configPath?: string;
212
+ /**
213
+ * Additional format loaders (JSON is built-in).
214
+ * Later loaders for the same extension win (allows override).
215
+ */
216
+ readonly loaders?: readonly FormatLoader[];
217
+ /**
218
+ * Custom search paths (absolute).
219
+ * Replaces the default search paths when provided.
220
+ * Probed in order; first found wins.
221
+ */
222
+ readonly searchPaths?: readonly string[];
223
+ /**
224
+ * Directory the project-scope ancestor walk starts from.
225
+ * Anchors discovery to a location other than the process working
226
+ * directory (e.g. the directory of a file an editor integration is
227
+ * operating on).
228
+ * @defaultValue `adapter.cwd`
229
+ */
230
+ readonly baseDir?: string;
231
+ }
232
+ /** Successful config discovery — file found and parsed. */
233
+ interface ConfigFound {
234
+ /** Discriminant — `true` indicates a config file was found and parsed successfully. */
235
+ readonly found: true;
236
+ /** Absolute path to the config file that was loaded. */
237
+ readonly path: string;
238
+ /** Parsed config data. */
239
+ readonly data: Readonly<Record<string, unknown>>;
240
+ /** File extension that determined the loader (e.g. `'json'`). */
241
+ readonly format: string;
242
+ }
243
+ /** No config file found at any candidate path (not an error). */
244
+ interface ConfigNotFound {
245
+ /** Discriminant — `false` indicates no config file exists at any candidate path. */
246
+ readonly found: false;
247
+ }
248
+ /** Discriminated result of config discovery. */
249
+ type ConfigDiscoveryResult = ConfigFound | ConfigNotFound;
250
+ /** Directory scopes feeding {@link buildConfigSearchPaths}. */
251
+ interface ConfigSearchPathOptions {
252
+ /** Directory the project-scope ancestor walk starts from. */
253
+ readonly baseDir: string;
254
+ /**
255
+ * User-scope config roots, highest priority first
256
+ * (XDG / AppData, plus `~/Library/Application Support` on macOS).
257
+ */
258
+ readonly userConfigDirs: readonly string[];
259
+ /**
260
+ * System-scope config roots (`/etc` on Linux and macOS).
261
+ * @defaultValue `[]`
262
+ */
263
+ readonly systemConfigDirs?: readonly string[];
264
+ /** Custom {@link FormatLoader}s whose extensions expand the search set. */
265
+ readonly loaders?: readonly FormatLoader[];
266
+ }
267
+ /**
268
+ * Build the default config search paths for an app.
269
+ *
270
+ * Advanced helper used by DreamCLI's config discovery. Most apps should call
271
+ * `.config()` or {@link discoverConfig} instead of constructing search paths
272
+ * manually. Exported for debugging, custom discovery flows, and help text.
273
+ *
274
+ * Search order (first match wins):
275
+ * 1. Project scope — for `baseDir` and each ancestor directory up to the
276
+ * filesystem root, nearest first:
277
+ * 1. `{dir}/.{appName}.json` — dotfile
278
+ * 2. `{dir}/{appName}.config.json` — explicit config
279
+ * 3. `{dir}/.config/{appName}.json` — project `.config/` convention
280
+ * 2. User scope — `{userConfigDir}/{appName}/config.json` for each entry of
281
+ * `userConfigDirs`, in order.
282
+ * 3. System scope — `{systemConfigDir}/{appName}/config.json` for each entry
283
+ * of `systemConfigDirs`, in order.
284
+ *
285
+ * When custom {@link ConfigDiscoveryOptions.loaders | loaders} are registered,
286
+ * each path pattern is repeated per supported extension (JSON always first).
287
+ *
288
+ * @param appName - CLI application name used to derive config filenames.
289
+ * @param options - Directory scopes and loaders (see {@link ConfigSearchPathOptions}).
290
+ * @returns Ordered list of candidate config file paths (first match wins).
291
+ *
292
+ * @example
293
+ * ```ts
294
+ * const paths = buildConfigSearchPaths('mycli', {
295
+ * baseDir: '/repo/packages/app',
296
+ * userConfigDirs: ['/home/me/.config'],
297
+ * systemConfigDirs: ['/etc'],
298
+ * });
299
+ * ```
300
+ */
301
+ declare function buildConfigSearchPaths(appName: string, options: ConfigSearchPathOptions): readonly string[];
302
+ /**
303
+ * The subset of {@link RuntimeAdapter} needed for config discovery.
304
+ *
305
+ * Exported so custom hosts and tests can type the minimal adapter required by
306
+ * {@link discoverConfig} without depending on the full runtime adapter shape.
307
+ */
308
+ type ConfigAdapter = Pick<RuntimeAdapter, 'readFile' | 'cwd' | 'configDir'> & Partial<Pick<RuntimeAdapter, 'userConfigDirs' | 'systemConfigDirs'>>;
309
+ /**
310
+ * Discover and load a config file.
311
+ *
312
+ * Low-level discovery helper behind `CLIBuilder.config()`. Most apps should
313
+ * let the CLI runtime call this automatically; call it directly when testing
314
+ * config behavior or building custom bootstrapping around {@linkcode RuntimeAdapter}.
315
+ *
316
+ * Pure function — all filesystem I/O flows through `adapter.readFile`.
317
+ * Returns a discriminated union: `{ found: true, ... }` when a config
318
+ * file was found and parsed, `{ found: false }` when no file exists.
319
+ *
320
+ * @throws {CLIError} code `CONFIG_NOT_FOUND` — explicit `configPath` doesn't exist
321
+ * @throws {CLIError} code `CONFIG_PARSE_ERROR` — file exists but fails to parse
322
+ * @throws {CLIError} code `CONFIG_UNKNOWN_FORMAT` — no loader for the file extension
323
+ *
324
+ * @example
325
+ * ```ts
326
+ * const result = await discoverConfig('mycli', adapter, {
327
+ * loaders: [
328
+ * configFormat(['yaml', 'yml'], Bun.YAML.parse),
329
+ * configFormat(['toml'], Bun.TOML.parse),
330
+ * ],
331
+ * });
332
+ * ```
333
+ */
334
+ declare function discoverConfig(appName: string, adapter: ConfigAdapter, options?: ConfigDiscoveryOptions): Promise<ConfigDiscoveryResult>;
335
+ /**
336
+ * Create a {@link FormatLoader} from extensions and a parse function.
337
+ *
338
+ * Convenience factory for config loading. It avoids manually constructing the
339
+ * `{ extensions, parse }` object and makes intent clearer at call sites.
340
+ *
341
+ * Later loaders registered for the same extension override earlier ones. Any
342
+ * error thrown by `parse` is wrapped by {@link discoverConfig} as
343
+ * `CONFIG_PARSE_ERROR`.
344
+ *
345
+ * @param extensions - File extensions this loader handles (without dot, e.g. `'yaml'`).
346
+ * @param parse - Parse function: takes file content string and returns a parsed config value.
347
+ * @returns A {@link FormatLoader} ready to pass to {@link ConfigDiscoveryOptions.loaders}.
348
+ *
349
+ * @example
350
+ * ```ts
351
+ * import { cli, configFormat } from '@kjanat/dreamcli';
352
+ * import { parse as parseYaml } from 'yaml';
353
+ * import { parse as parseTOML } from '@iarna/toml';
354
+ *
355
+ * const yamlPackageLoader = configFormat(['yaml', 'yml'], parseYaml);
356
+ * const tomlPackageLoader = configFormat(['toml'], parseTOML);
357
+ * // Or with Bun's built-in parsers:
358
+ * // const yamlLoader = configFormat(['yaml', 'yml'], Bun.YAML.parse);
359
+ * // const tomlLoader = configFormat(['toml'], Bun.TOML.parse);
360
+ *
361
+ * cli('myapp')
362
+ * .config('myapp')
363
+ * .configLoader(yamlLoader)
364
+ * .configLoader(tomlLoader)
365
+ * .run();
366
+ * ```
367
+ */
368
+ declare function configFormat(extensions: readonly string[], parse: (content: string) => unknown): FormatLoader;
369
+ //#endregion
370
+ export { discoverManifest as _, ConfigNotFound as a, buildConfigSearchPaths as c, PackageRepositoryUrlOptions as d, packageRepositoryUrl as f, PackageRepository as g, PackageJsonData as h, ConfigFound as i, configFormat as l, PackageJsonAdapter as m, ConfigDiscoveryOptions as n, ConfigSearchPathOptions as o, ManifestDiscoveryOptions as p, ConfigDiscoveryResult as r, FormatLoader as s, ConfigAdapter as t, discoverConfig as u, inferCliName as v };