@kjanat/dreamcli 4.0.0-rc.3 → 4.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 (212) hide show
  1. package/README.md +5 -7
  2. package/dist/{runtime/adapter.d.mts → adapter-D0hbBNVB.d.mts} +2 -4
  3. package/dist/completion-D4mz6axB.mjs +6 -0
  4. package/dist/completion.d.mts +90 -0
  5. package/dist/completion.mjs +1 -0
  6. package/dist/config-B9ddC-Kb.mjs +1 -0
  7. package/dist/config.d.mts +2 -0
  8. package/dist/config.mjs +1 -0
  9. package/dist/core-Cp2w8vRq.mjs +17 -0
  10. package/dist/index-BziI2aKc.d.mts +5440 -0
  11. package/dist/index-DOfClfYR.d.mts +370 -0
  12. package/dist/index-DWsnGZlx.d.mts +831 -0
  13. package/dist/{core/cli/index.d.mts → index-DXROeDPC.d.mts} +116 -57
  14. package/dist/index-DndPmT8J.d.mts +275 -0
  15. package/dist/{core/json-schema/index.d.mts → index-DyoaS234.d.mts} +43 -34
  16. package/dist/index.d.mts +190 -41
  17. package/dist/index.mjs +1 -26
  18. package/dist/json-schema-C9SzZ7jY.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
@@ -1,285 +0,0 @@
1
- import { CLIError } from "../errors/index.mjs";
2
- import { discoverManifest, inferCliName, packageRepositoryUrl } from "./package-json.mjs";
3
- //#region src/core/config/index.ts
4
- /**
5
- * Config file discovery and loading.
6
- *
7
- * Probes a prioritised list of candidate paths, reads the first match via
8
- * {@link RuntimeAdapter.readFile}, and parses the content using an
9
- * extension-based loader (JSON built-in, others additive via {@link FormatLoader}).
10
- *
11
- * The module is pure — all I/O flows through the adapter, making it fully
12
- * testable with {@link createTestAdapter}'s virtual filesystem.
13
- *
14
- * @module dreamcli/core/config
15
- */
16
- /** @internal */
17
- function isPlainObject(value) {
18
- if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
19
- const proto = Object.getPrototypeOf(value);
20
- return proto === Object.prototype || proto === null;
21
- }
22
- /** @internal */
23
- const jsonLoader = {
24
- extensions: ["json"],
25
- parse: (content) => {
26
- const parsed = JSON.parse(content);
27
- if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("Config must be a JSON object");
28
- return parsed;
29
- }
30
- };
31
- /**
32
- * Join path segments using the separator detected from the base path.
33
- *
34
- * Avoids importing `node:path` — the base path is already platform-native
35
- * (comes from `adapter.cwd` / `adapter.configDir`), so we infer the
36
- * separator from its content.
37
- *
38
- * @internal
39
- */
40
- function joinPath(base, ...segments) {
41
- const sep = base.includes("\\") ? "\\" : "/";
42
- return [base.endsWith(sep) ? base.slice(0, -1) : base, ...segments].join(sep);
43
- }
44
- /**
45
- * List a directory and every ancestor up to the filesystem root,
46
- * nearest first. Separator is inferred from the input; POSIX (`/`) and
47
- * Windows drive roots (`C:\`) both terminate the walk.
48
- *
49
- * @internal
50
- */
51
- function ancestorDirs(base) {
52
- const sep = base.includes("\\") ? "\\" : "/";
53
- let current = base;
54
- while (current.length > 1 && current.endsWith(sep) && !current.endsWith(`:${sep}`)) current = current.slice(0, -1);
55
- const dirs = [current];
56
- while (true) {
57
- const idx = current.lastIndexOf(sep);
58
- if (idx < 0) break;
59
- let parent = current.slice(0, idx);
60
- if (parent === "") parent = sep;
61
- else if (/^[A-Za-z]:$/.test(parent)) parent = `${parent}${sep}`;
62
- if (parent === current) break;
63
- dirs.push(parent);
64
- current = parent;
65
- }
66
- return dirs;
67
- }
68
- /**
69
- * Extract the file extension (without leading dot, lowercased).
70
- * Returns empty string when no extension is present.
71
- *
72
- * @internal
73
- */
74
- function getExtension(path) {
75
- const lastDot = path.lastIndexOf(".");
76
- if (lastDot <= Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"))) return "";
77
- return path.slice(lastDot + 1).toLowerCase();
78
- }
79
- /**
80
- * Build the default config search paths for an app.
81
- *
82
- * Advanced helper used by DreamCLI's config discovery. Most apps should call
83
- * `.config()` or {@link discoverConfig} instead of constructing search paths
84
- * manually. Exported for debugging, custom discovery flows, and help text.
85
- *
86
- * Search order (first match wins):
87
- * 1. Project scope — for `baseDir` and each ancestor directory up to the
88
- * filesystem root, nearest first:
89
- * 1. `{dir}/.{appName}.json` — dotfile
90
- * 2. `{dir}/{appName}.config.json` — explicit config
91
- * 3. `{dir}/.config/{appName}.json` — project `.config/` convention
92
- * 2. User scope — `{userConfigDir}/{appName}/config.json` for each entry of
93
- * `userConfigDirs`, in order.
94
- * 3. System scope — `{systemConfigDir}/{appName}/config.json` for each entry
95
- * of `systemConfigDirs`, in order.
96
- *
97
- * When custom {@link ConfigDiscoveryOptions.loaders | loaders} are registered,
98
- * each path pattern is repeated per supported extension (JSON always first).
99
- *
100
- * @param appName - CLI application name used to derive config filenames.
101
- * @param options - Directory scopes and loaders (see {@link ConfigSearchPathOptions}).
102
- * @returns Ordered list of candidate config file paths (first match wins).
103
- *
104
- * @example
105
- * ```ts
106
- * const paths = buildConfigSearchPaths('mycli', {
107
- * baseDir: '/repo/packages/app',
108
- * userConfigDirs: ['/home/me/.config'],
109
- * systemConfigDirs: ['/etc'],
110
- * });
111
- * ```
112
- */
113
- function buildConfigSearchPaths(appName, options) {
114
- const extensions = buildExtensionList(options.loaders);
115
- const paths = [];
116
- for (const dir of ancestorDirs(options.baseDir)) {
117
- for (const ext of extensions) paths.push(joinPath(dir, `.${appName}.${ext}`));
118
- for (const ext of extensions) paths.push(joinPath(dir, `${appName}.config.${ext}`));
119
- for (const ext of extensions) paths.push(joinPath(dir, ".config", `${appName}.${ext}`));
120
- }
121
- for (const dir of options.userConfigDirs) for (const ext of extensions) paths.push(joinPath(dir, appName, `config.${ext}`));
122
- for (const dir of options.systemConfigDirs ?? []) for (const ext of extensions) paths.push(joinPath(dir, appName, `config.${ext}`));
123
- return paths;
124
- }
125
- /**
126
- * Collect unique extensions from the built-in JSON loader + any custom loaders.
127
- * JSON always comes first. Order otherwise matches loader registration order.
128
- *
129
- * @param loaders - Optional custom {@link FormatLoader}s to append after JSON.
130
- * @returns Deduplicated, lowercased extension list (JSON first).
131
- *
132
- * @internal
133
- */
134
- function buildExtensionList(loaders) {
135
- const seen = /* @__PURE__ */ new Set();
136
- const result = [];
137
- for (const ext of jsonLoader.extensions) {
138
- const lower = ext.toLowerCase();
139
- if (!seen.has(lower)) {
140
- seen.add(lower);
141
- result.push(lower);
142
- }
143
- }
144
- if (loaders !== void 0) for (const loader of loaders) for (const ext of loader.extensions) {
145
- const lower = ext.toLowerCase();
146
- if (!seen.has(lower)) {
147
- seen.add(lower);
148
- result.push(lower);
149
- }
150
- }
151
- return result;
152
- }
153
- /**
154
- * Build extension → loader lookup. Later loaders for the same extension
155
- * override earlier ones (allows user to replace the built-in JSON loader).
156
- *
157
- * @param loaders - Optional custom {@link FormatLoader}s (later entries override earlier for same extension).
158
- * @returns Map from lowercased extension to its {@link FormatLoader}.
159
- *
160
- * @internal
161
- */
162
- function buildLoaderMap(loaders) {
163
- const map = /* @__PURE__ */ new Map();
164
- for (const ext of jsonLoader.extensions) map.set(ext.toLowerCase(), jsonLoader);
165
- if (loaders !== void 0) for (const loader of loaders) for (const ext of loader.extensions) map.set(ext.toLowerCase(), loader);
166
- return map;
167
- }
168
- /**
169
- * Discover and load a config file.
170
- *
171
- * Low-level discovery helper behind `CLIBuilder.config()`. Most apps should
172
- * let the CLI runtime call this automatically; call it directly when testing
173
- * config behavior or building custom bootstrapping around {@linkcode RuntimeAdapter}.
174
- *
175
- * Pure function — all filesystem I/O flows through `adapter.readFile`.
176
- * Returns a discriminated union: `{ found: true, ... }` when a config
177
- * file was found and parsed, `{ found: false }` when no file exists.
178
- *
179
- * @throws {CLIError} code `CONFIG_NOT_FOUND` — explicit `configPath` doesn't exist
180
- * @throws {CLIError} code `CONFIG_PARSE_ERROR` — file exists but fails to parse
181
- * @throws {CLIError} code `CONFIG_UNKNOWN_FORMAT` — no loader for the file extension
182
- *
183
- * @example
184
- * ```ts
185
- * const result = await discoverConfig('mycli', adapter, {
186
- * loaders: [
187
- * configFormat(['yaml', 'yml'], Bun.YAML.parse),
188
- * configFormat(['toml'], Bun.TOML.parse),
189
- * ],
190
- * });
191
- * ```
192
- */
193
- async function discoverConfig(appName, adapter, options) {
194
- const loaderMap = buildLoaderMap(options?.loaders);
195
- const searchPaths = options?.configPath !== void 0 ? [options.configPath] : options?.searchPaths ?? buildConfigSearchPaths(appName, {
196
- baseDir: options?.baseDir ?? adapter.cwd,
197
- userConfigDirs: adapter.userConfigDirs ?? [adapter.configDir],
198
- systemConfigDirs: adapter.systemConfigDirs ?? [],
199
- ...options?.loaders !== void 0 ? { loaders: options.loaders } : {}
200
- });
201
- for (const candidatePath of searchPaths) {
202
- const content = await adapter.readFile(candidatePath);
203
- if (content === null) {
204
- if (options?.configPath !== void 0) throw new CLIError(`Config file not found: ${candidatePath}`, {
205
- code: "CONFIG_NOT_FOUND",
206
- details: { path: candidatePath },
207
- suggest: "Create the config file or remove the --config flag"
208
- });
209
- continue;
210
- }
211
- const ext = getExtension(candidatePath);
212
- const loader = loaderMap.get(ext);
213
- if (loader === void 0) throw new CLIError(`No loader registered for config format: .${ext}`, {
214
- code: "CONFIG_UNKNOWN_FORMAT",
215
- details: {
216
- path: candidatePath,
217
- extension: ext
218
- },
219
- suggest: `Supported formats: ${[...loaderMap.keys()].join(", ")}`
220
- });
221
- try {
222
- const data = loader.parse(content);
223
- if (!isPlainObject(data)) throw new Error("Config loader must return a plain object");
224
- return {
225
- found: true,
226
- path: candidatePath,
227
- data,
228
- format: ext
229
- };
230
- } catch (cause) {
231
- throw new CLIError(`Failed to parse config file: ${candidatePath}`, {
232
- code: "CONFIG_PARSE_ERROR",
233
- cause,
234
- details: {
235
- path: candidatePath,
236
- format: ext,
237
- message: cause instanceof Error ? cause.message : String(cause)
238
- },
239
- suggest: "Check the config file for syntax errors"
240
- });
241
- }
242
- }
243
- return { found: false };
244
- }
245
- /**
246
- * Create a {@link FormatLoader} from extensions and a parse function.
247
- *
248
- * Convenience factory for config loading. It avoids manually constructing the
249
- * `{ extensions, parse }` object and makes intent clearer at call sites.
250
- *
251
- * Later loaders registered for the same extension override earlier ones. Any
252
- * error thrown by `parse` is wrapped by {@link discoverConfig} as
253
- * `CONFIG_PARSE_ERROR`.
254
- *
255
- * @param extensions - File extensions this loader handles (without dot, e.g. `'yaml'`).
256
- * @param parse - Parse function: takes file content string and returns a parsed config value.
257
- * @returns A {@link FormatLoader} ready to pass to {@link ConfigDiscoveryOptions.loaders}.
258
- *
259
- * @example
260
- * ```ts
261
- * import { cli, configFormat } from '@kjanat/dreamcli';
262
- * import { parse as parseYaml } from 'yaml';
263
- * import { parse as parseTOML } from '@iarna/toml';
264
- *
265
- * const yamlPackageLoader = configFormat(['yaml', 'yml'], parseYaml);
266
- * const tomlPackageLoader = configFormat(['toml'], parseTOML);
267
- * // Or with Bun's built-in parsers:
268
- * // const yamlLoader = configFormat(['yaml', 'yml'], Bun.YAML.parse);
269
- * // const tomlLoader = configFormat(['toml'], Bun.TOML.parse);
270
- *
271
- * cli('myapp')
272
- * .config('myapp')
273
- * .configLoader(yamlLoader)
274
- * .configLoader(tomlLoader)
275
- * .run();
276
- * ```
277
- */
278
- function configFormat(extensions, parse) {
279
- return {
280
- extensions,
281
- parse
282
- };
283
- }
284
- //#endregion
285
- export { buildConfigSearchPaths, configFormat, discoverConfig, discoverManifest, inferCliName, packageRepositoryUrl };
@@ -1,179 +0,0 @@
1
- import { RuntimeAdapter } from "../../runtime/adapter.mjs";
2
- //#region src/core/config/package-json.d.ts
3
- /**
4
- * Object form of the package.json `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 package.json fields relevant to CLI metadata.
17
- *
18
- * All fields are optional — a valid package.json may omit any of them.
19
- */
20
- interface PackageJsonData {
21
- /** Package name (e.g. `@scope/mycli`). */
22
- readonly name?: string;
23
- /** Semver version string from `package.json`. */
24
- readonly version?: string;
25
- /** One-line package description. */
26
- readonly description?: string;
27
- /** Binary entry point(s) — string for single-bin, object for multi-bin. */
28
- readonly bin?: string | Readonly<Record<string, string>>;
29
- /** Project homepage URL. */
30
- readonly homepage?: string;
31
- /** Repository locator — URL/shorthand string or `{type, url, directory}` object. */
32
- readonly repository?: string | PackageRepository;
33
- }
34
- /**
35
- * The subset of {@link RuntimeAdapter} needed for package.json discovery.
36
- *
37
- * Using a narrow pick keeps the function easy to test and makes the
38
- * dependency explicit.
39
- */
40
- type PackageJsonAdapter = Pick<RuntimeAdapter, 'readFile' | 'cwd'>;
41
- /** Options for {@link discoverManifest}. */
42
- interface ManifestDiscoveryOptions {
43
- /**
44
- * Explicit directory or file path to walk up from. Defaults to
45
- * `adapter.cwd` when omitted. Pass an absolute path inside your own package
46
- * (e.g. `fileURLToPath(import.meta.url)`) for installable CLIs whose version
47
- * should reflect the CLI's own package, not the consumer's working directory.
48
- *
49
- * This low-level helper takes a resolved path **string** only. The builder
50
- * sugar `CLIBuilder.manifest({ from })` exposes the same anchor under the name
51
- * `from` and additionally accepts a `file:` URL string or `URL` instance,
52
- * normalizing it to a path first.
53
- */
54
- readonly startDir?: string;
55
- /**
56
- * Candidate manifest filenames, in per-directory priority order
57
- * (e.g. `['deno.json', 'jsr.json']`). At each directory the first existing
58
- * file that carries CLI metadata wins, so the nearest manifest directory
59
- * always takes precedence over file order. A file that parses but holds no
60
- * recognised metadata (e.g. a config-only `deno.json` with just
61
- * `tasks`/`imports`) is skipped, so a sibling `jsr.json` — or a manifest
62
- * higher up — can still be found. Defaults to `['package.json']`.
63
- *
64
- * An empty list is a deliberate no-op: with no candidates to probe, the
65
- * walk-up reads nothing and resolves to `null` (consistent with the
66
- * "returns `null` when no manifest is found" contract).
67
- */
68
- readonly files?: readonly string[];
69
- }
70
- /**
71
- * Discover the nearest manifest (`package.json`, `deno.json`, `jsr.json`, …)
72
- * by walking up from `startDir` (or `adapter.cwd` when omitted).
73
- *
74
- * Convenience helper behind `CLIBuilder.manifest()`. Most apps should let the
75
- * CLI runtime discover metadata automatically; call this directly when testing
76
- * metadata inference or embedding the behavior in custom tooling.
77
- *
78
- * Candidate files are parsed as JSON with a JSONC fallback — `package.json`,
79
- * `deno.json`, `jsr.json`, and `deno.jsonc` all qualify, including files that
80
- * carry `//` / block comments or trailing commas (common in `deno.json`). A
81
- * file that fails both parses is skipped, so discovery keeps probing.
82
- *
83
- * Returns the parsed metadata on success, `null` when no manifest is found
84
- * (not an error). Malformed JSON, non-object roots, and config-only manifests
85
- * that carry no recognised metadata (e.g. a `deno.json` with only `tasks` /
86
- * `imports`) are all skipped, so discovery keeps probing the remaining
87
- * candidate files and parent directories — the feature is a convenience, not a
88
- * hard requirement.
89
- *
90
- * @param adapter - Adapter providing `readFile` + `cwd`.
91
- * @param options - Optional anchor (`startDir`) and candidate filenames (`files`).
92
- *
93
- * @example
94
- * ```ts
95
- * import { discoverManifest } from '@kjanat/dreamcli';
96
- *
97
- * const meta = await discoverManifest(adapter, { files: ['deno.json', 'jsr.json'] });
98
- * if (meta !== null) {
99
- * console.log(meta.version); // '1.2.3'
100
- * }
101
- * ```
102
- */
103
- declare function discoverManifest(adapter: PackageJsonAdapter, options?: ManifestDiscoveryOptions): Promise<PackageJsonData | null>;
104
- /** Options for {@link packageRepositoryUrl}. */
105
- interface PackageRepositoryUrlOptions {
106
- /**
107
- * Throw a `CLIError` (code `INVALID_REPOSITORY`) instead of returning
108
- * `undefined` when the `repository` field is absent or not a recognisable
109
- * locator. With `require: true` the return type narrows to `string`, so
110
- * callers that know their manifest carries a valid repository need no
111
- * assertion — and a bad manifest fails fast with a real message instead
112
- * of propagating `undefined`.
113
- *
114
- * @defaultValue `false`
115
- */
116
- readonly require?: boolean;
117
- }
118
- /**
119
- * Resolve a package's `repository` field to a browsable `https://` URL.
120
- *
121
- * Handles the locator formats npm accepts:
122
- * - object form: `{ "type": "git", "url": "git+https://github.com/u/r.git" }`
123
- * - `https`/`git`/`ssh` URLs (`git+` prefix and `.git` suffix stripped)
124
- * - scp-style locators: `git@github.com:u/r.git`
125
- * - shorthands: `github:u/r`, `gitlab:u/r`, `bitbucket:u/r`, and bare `u/r`
126
- * (GitHub, per npm convention)
127
- *
128
- * Returns `undefined` when the field is absent or unrecognised — or, with
129
- * `{ require: true }`, throws instead and the return type is `string`.
130
- * (The narrowing cannot key off the input type alone: a present `repository`
131
- * may still be an empty string, a url-less object, or an unparseable
132
- * locator, so the `string` promise is backed by the runtime check.)
133
- *
134
- * @example
135
- * ```ts
136
- * packageRepositoryUrl({ repository: 'git+https://github.com/u/r.git' });
137
- * // 'https://github.com/u/r'
138
- *
139
- * const url: string = packageRepositoryUrl(pkg, { require: true });
140
- * // throws CLIError when pkg.repository is missing or unrecognised
141
- * ```
142
- */
143
- declare function packageRepositoryUrl(pkg: PackageJsonData, options: PackageRepositoryUrlOptions & {
144
- readonly require: true;
145
- }): string;
146
- /** Resolve a package repository URL, returning `undefined` for absent or invalid locators. */
147
- declare function packageRepositoryUrl(pkg: PackageJsonData, options?: PackageRepositoryUrlOptions): string | undefined;
148
- /**
149
- * Infer the CLI binary name from manifest data.
150
- *
151
- * Resolution order:
152
- * 1. First key of `bin` object (e.g. `{"mycli": "./dist/cli.js"}` → `"mycli"`)
153
- * 2. Package `name`, scope stripped by default (e.g. `"@scope/mycli"` → `"mycli"`);
154
- * pass `{ stripScope: false }` to keep the full scoped name
155
- * 3. `undefined` if neither exists
156
- *
157
- * Note: `bin` keys are never scoped, so `stripScope` only affects the `name`
158
- * fallback (relevant for `deno.json` / `jsr.json`, which have no `bin` field).
159
- *
160
- * @param pkg - Parsed manifest metadata.
161
- * @param options - `stripScope` (default `true`): strip a leading `@scope/`
162
- * from the `name` fallback.
163
- *
164
- * @example
165
- * ```ts
166
- * import { inferCliName } from '@kjanat/dreamcli';
167
- *
168
- * inferCliName({ bin: { mycli: './dist/cli.js' } }); // 'mycli'
169
- * inferCliName({ name: '@scope/mycli' }); // 'mycli'
170
- * inferCliName({ name: '@scope/mycli' }, { stripScope: false }); // '@scope/mycli'
171
- * inferCliName({ name: 'mycli' }); // 'mycli'
172
- * inferCliName({}); // undefined
173
- * ```
174
- */
175
- declare function inferCliName(pkg: PackageJsonData, options?: {
176
- readonly stripScope?: boolean;
177
- }): string | undefined;
178
- //#endregion
179
- export { type ManifestDiscoveryOptions, type PackageJsonAdapter, type PackageJsonData, type PackageRepository, type PackageRepositoryUrlOptions, discoverManifest, inferCliName, packageRepositoryUrl };