@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,353 +0,0 @@
1
- import { CLIError } from "../errors/index.mjs";
2
- import { stripTrailing } from "../../strings.mjs";
3
- //#region src/core/config/package-json.ts
4
- /**
5
- * Package.json auto-discovery via directory walk-up.
6
- *
7
- * Walks up from `adapter.cwd` to find the nearest `package.json`, parses
8
- * it, and extracts metadata (name, version, description, bin). All I/O
9
- * flows through the adapter — fully testable with virtual filesystems.
10
- *
11
- * @module dreamcli/core/config/package-json
12
- */
13
- /** Type guard: narrows `unknown` to a plain (non-array) object. */
14
- function isPlainObject(value) {
15
- return typeof value === "object" && value !== null && !Array.isArray(value);
16
- }
17
- /**
18
- * Compute the parent directory of a path using the separator detected
19
- * from the path itself.
20
- *
21
- * Returns `undefined` when the path is already the root (e.g. `/` or `C:\`).
22
- * Pure string manipulation — no filesystem access.
23
- *
24
- * @internal
25
- */
26
- function parentDir(path) {
27
- const fwdIdx = path.lastIndexOf("/");
28
- const bkIdx = path.lastIndexOf("\\");
29
- const idx = Math.max(fwdIdx, bkIdx);
30
- const sep = bkIdx > fwdIdx ? "\\" : "/";
31
- if (idx < 0) return void 0;
32
- if (idx === 0) return path.length > 1 ? sep : void 0;
33
- const parent = path.slice(0, idx);
34
- if (parent.length === 2 && parent[1] === ":") {
35
- const driveRoot = `${parent}${sep}`;
36
- return driveRoot === path ? void 0 : driveRoot;
37
- }
38
- return parent;
39
- }
40
- /**
41
- * Join a base path with a filename segment.
42
- *
43
- * @internal
44
- */
45
- function joinPath(base, segment) {
46
- const sep = base.includes("\\") ? "\\" : "/";
47
- return base.endsWith(sep) ? `${base}${segment}` : `${base}${sep}${segment}`;
48
- }
49
- /** Default manifest filenames probed when none are supplied. @internal */
50
- const DEFAULT_MANIFEST_FILES = ["package.json"];
51
- /**
52
- * Whether parsed manifest data carries any CLI-relevant metadata.
53
- *
54
- * {@link parsePackageJson} returns an empty object for a config-only manifest
55
- * (e.g. a `deno.json` holding only `tasks` / `imports` / `compilerOptions`).
56
- * Treating that empty result as a discovery hit would shadow a sibling
57
- * `jsr.json` and halt the walk-up, silently dropping real metadata. Discovery
58
- * therefore only accepts a manifest that actually carries at least one
59
- * recognised field.
60
- *
61
- * @internal
62
- */
63
- function manifestHasMetadata(data) {
64
- return data.name !== void 0 || data.version !== void 0 || data.description !== void 0 || data.bin !== void 0 || data.homepage !== void 0 || data.repository !== void 0;
65
- }
66
- /**
67
- * Discover the nearest manifest (`package.json`, `deno.json`, `jsr.json`, …)
68
- * by walking up from `startDir` (or `adapter.cwd` when omitted).
69
- *
70
- * Convenience helper behind `CLIBuilder.manifest()`. Most apps should let the
71
- * CLI runtime discover metadata automatically; call this directly when testing
72
- * metadata inference or embedding the behavior in custom tooling.
73
- *
74
- * Candidate files are parsed as JSON with a JSONC fallback — `package.json`,
75
- * `deno.json`, `jsr.json`, and `deno.jsonc` all qualify, including files that
76
- * carry `//` / block comments or trailing commas (common in `deno.json`). A
77
- * file that fails both parses is skipped, so discovery keeps probing.
78
- *
79
- * Returns the parsed metadata on success, `null` when no manifest is found
80
- * (not an error). Malformed JSON, non-object roots, and config-only manifests
81
- * that carry no recognised metadata (e.g. a `deno.json` with only `tasks` /
82
- * `imports`) are all skipped, so discovery keeps probing the remaining
83
- * candidate files and parent directories — the feature is a convenience, not a
84
- * hard requirement.
85
- *
86
- * @param adapter - Adapter providing `readFile` + `cwd`.
87
- * @param options - Optional anchor (`startDir`) and candidate filenames (`files`).
88
- *
89
- * @example
90
- * ```ts
91
- * import { discoverManifest } from '@kjanat/dreamcli';
92
- *
93
- * const meta = await discoverManifest(adapter, { files: ['deno.json', 'jsr.json'] });
94
- * if (meta !== null) {
95
- * console.log(meta.version); // '1.2.3'
96
- * }
97
- * ```
98
- */
99
- async function discoverManifest(adapter, options = {}) {
100
- const files = options.files ?? DEFAULT_MANIFEST_FILES;
101
- let dir = options.startDir ?? adapter.cwd;
102
- while (dir !== void 0) {
103
- for (const file of files) {
104
- let content = null;
105
- try {
106
- content = await adapter.readFile(joinPath(dir, file));
107
- } catch {}
108
- if (content !== null) {
109
- const parsed = parsePackageJson(content);
110
- if (parsed !== null && manifestHasMetadata(parsed)) return parsed;
111
- }
112
- }
113
- dir = parentDir(dir);
114
- }
115
- return null;
116
- }
117
- /** Whitespace characters JSON treats as insignificant. @internal */
118
- function isJsonWhitespace(ch) {
119
- return ch === " " || ch === " " || ch === "\n" || ch === "\r";
120
- }
121
- /**
122
- * Strip JSONC extensions (line/block comments and trailing commas) so the result
123
- * is plain JSON. String-aware: comment markers and commas inside string literals
124
- * are preserved verbatim, so a `"https://…"` URL or a `"/* …"` value survives
125
- * untouched. Runtime-agnostic — no dependencies, plain string scanning.
126
- *
127
- * Only invoked as a fallback when strict `JSON.parse` fails, so valid JSON never
128
- * passes through here.
129
- *
130
- * @internal
131
- */
132
- function stripJsonc(input) {
133
- let decommented = "";
134
- let inString = false;
135
- let escaped = false;
136
- for (let i = 0; i < input.length; i += 1) {
137
- const ch = input[i] ?? "";
138
- if (inString) {
139
- decommented += ch;
140
- if (escaped) escaped = false;
141
- else if (ch === "\\") escaped = true;
142
- else if (ch === "\"") inString = false;
143
- continue;
144
- }
145
- if (ch === "\"") {
146
- inString = true;
147
- decommented += ch;
148
- continue;
149
- }
150
- if (ch === "/" && input[i + 1] === "/") {
151
- i += 2;
152
- while (i < input.length && input[i] !== "\n") i += 1;
153
- i -= 1;
154
- continue;
155
- }
156
- if (ch === "/" && input[i + 1] === "*") {
157
- i += 2;
158
- while (i < input.length && !(input[i] === "*" && input[i + 1] === "/")) i += 1;
159
- i += 1;
160
- continue;
161
- }
162
- decommented += ch;
163
- }
164
- let result = "";
165
- inString = false;
166
- escaped = false;
167
- for (let i = 0; i < decommented.length; i += 1) {
168
- const ch = decommented[i] ?? "";
169
- if (inString) {
170
- result += ch;
171
- if (escaped) escaped = false;
172
- else if (ch === "\\") escaped = true;
173
- else if (ch === "\"") inString = false;
174
- continue;
175
- }
176
- if (ch === "\"") {
177
- inString = true;
178
- result += ch;
179
- continue;
180
- }
181
- if (ch === ",") {
182
- let j = i + 1;
183
- while (j < decommented.length && isJsonWhitespace(decommented[j] ?? "")) j += 1;
184
- const next = decommented[j];
185
- if (next === "}" || next === "]") continue;
186
- }
187
- result += ch;
188
- }
189
- return result;
190
- }
191
- /**
192
- * Parse a manifest content string into {@link PackageJsonData}.
193
- *
194
- * Strict JSON is parsed directly; on failure, a JSONC fallback strips comments
195
- * and trailing commas (common in `deno.json`) and retries. Returns `null` for
196
- * content that is neither valid JSON nor JSONC, or whose root is not an object.
197
- *
198
- * @internal
199
- */
200
- function parsePackageJson(content) {
201
- let parsed;
202
- try {
203
- parsed = JSON.parse(content);
204
- } catch {
205
- try {
206
- parsed = JSON.parse(stripJsonc(content));
207
- } catch {
208
- return null;
209
- }
210
- }
211
- try {
212
- if (!isPlainObject(parsed)) return null;
213
- const name = typeof parsed["name"] === "string" ? parsed["name"] : void 0;
214
- const version = typeof parsed["version"] === "string" ? parsed["version"] : void 0;
215
- const description = typeof parsed["description"] === "string" ? parsed["description"] : void 0;
216
- const bin = parseBinField(parsed["bin"]);
217
- const homepage = typeof parsed["homepage"] === "string" ? parsed["homepage"] : void 0;
218
- const repository = parseRepositoryField(parsed["repository"]);
219
- return {
220
- ...name !== void 0 ? { name } : {},
221
- ...version !== void 0 ? { version } : {},
222
- ...description !== void 0 ? { description } : {},
223
- ...bin !== void 0 ? { bin } : {},
224
- ...homepage !== void 0 ? { homepage } : {},
225
- ...repository !== void 0 ? { repository } : {}
226
- };
227
- } catch {
228
- return null;
229
- }
230
- }
231
- /**
232
- * Parse the `bin` field from package.json.
233
- *
234
- * Accepts either a string (`"bin": "./dist/cli.js"`) or an object
235
- * (`"bin": { "mycli": "./dist/cli.js" }`). Returns `undefined` for
236
- * anything else.
237
- *
238
- * @internal
239
- */
240
- function parseBinField(value) {
241
- if (typeof value === "string") return value;
242
- if (!isPlainObject(value)) return void 0;
243
- const result = {};
244
- for (const [k, v] of Object.entries(value)) {
245
- if (typeof v !== "string") return void 0;
246
- result[k] = v;
247
- }
248
- return result;
249
- }
250
- /**
251
- * Parse the `repository` field from package.json.
252
- *
253
- * Accepts either a locator string (`"repository": "github:u/r"`) or an
254
- * object (`"repository": { "type": "git", "url": "..." }`). Returns
255
- * `undefined` for anything else.
256
- *
257
- * @internal
258
- */
259
- function parseRepositoryField(value) {
260
- if (typeof value === "string") return value;
261
- if (!isPlainObject(value)) return void 0;
262
- const type = typeof value["type"] === "string" ? value["type"] : void 0;
263
- const url = typeof value["url"] === "string" ? value["url"] : void 0;
264
- const directory = typeof value["directory"] === "string" ? value["directory"] : void 0;
265
- if (type === void 0 && url === void 0 && directory === void 0) return void 0;
266
- return {
267
- ...type !== void 0 ? { type } : {},
268
- ...url !== void 0 ? { url } : {},
269
- ...directory !== void 0 ? { directory } : {}
270
- };
271
- }
272
- /** Browsable base URLs for npm repository shorthand prefixes. @internal */
273
- const SHORTHAND_HOSTS = {
274
- github: "https://github.com",
275
- gitlab: "https://gitlab.com",
276
- bitbucket: "https://bitbucket.org"
277
- };
278
- /** Strip a trailing `.git` suffix from a repository path. @internal */
279
- function stripGitSuffix(path) {
280
- return path.endsWith(".git") ? path.slice(0, -4) : path;
281
- }
282
- function packageRepositoryUrl(pkg, options) {
283
- const url = resolveRepositoryUrl(pkg);
284
- if (url === void 0 && options?.require === true) throw new CLIError(pkg.repository === void 0 ? "package.json has no 'repository' field" : `package.json 'repository' is not a recognisable locator: ${JSON.stringify(pkg.repository)}`, {
285
- code: "INVALID_REPOSITORY",
286
- suggest: "Set 'repository' to a supported locator (e.g. 'github:user/repo' or 'git+https://github.com/user/repo.git'), or drop { require: true } and handle undefined"
287
- });
288
- return url;
289
- }
290
- /** Locator normalization behind {@link packageRepositoryUrl}. @internal */
291
- function resolveRepositoryUrl(pkg) {
292
- const raw = typeof pkg.repository === "string" ? pkg.repository : pkg.repository?.url;
293
- if (raw === void 0) return void 0;
294
- let locator = raw.trim();
295
- if (locator.length === 0) return void 0;
296
- const shorthand = /^(github|gitlab|bitbucket):([^/]+\/[^/]+)$/.exec(locator);
297
- if (shorthand !== null && shorthand[1] !== void 0 && shorthand[2] !== void 0) {
298
- const host = SHORTHAND_HOSTS[shorthand[1]];
299
- if (host !== void 0) return `${host}/${stripGitSuffix(shorthand[2])}`;
300
- }
301
- if (/^[\w.-]+\/[\w.-]+$/.test(locator)) return `https://github.com/${stripGitSuffix(locator)}`;
302
- if (locator.startsWith("git+")) locator = locator.slice(4);
303
- const scp = /^git@([^:/]+):(.+)$/.exec(locator);
304
- if (scp !== null && scp[1] !== void 0 && scp[2] !== void 0) return `https://${scp[1]}/${stripGitSuffix(stripTrailing(scp[2], [47]))}`;
305
- if (!/^(?:https?|git|ssh):\/\//.test(locator)) return void 0;
306
- try {
307
- const url = new URL(locator);
308
- const path = stripGitSuffix(stripTrailing(url.pathname, [47]));
309
- return `https://${url.hostname}${path}`;
310
- } catch {
311
- return;
312
- }
313
- }
314
- /**
315
- * Infer the CLI binary name from manifest data.
316
- *
317
- * Resolution order:
318
- * 1. First key of `bin` object (e.g. `{"mycli": "./dist/cli.js"}` → `"mycli"`)
319
- * 2. Package `name`, scope stripped by default (e.g. `"@scope/mycli"` → `"mycli"`);
320
- * pass `{ stripScope: false }` to keep the full scoped name
321
- * 3. `undefined` if neither exists
322
- *
323
- * Note: `bin` keys are never scoped, so `stripScope` only affects the `name`
324
- * fallback (relevant for `deno.json` / `jsr.json`, which have no `bin` field).
325
- *
326
- * @param pkg - Parsed manifest metadata.
327
- * @param options - `stripScope` (default `true`): strip a leading `@scope/`
328
- * from the `name` fallback.
329
- *
330
- * @example
331
- * ```ts
332
- * import { inferCliName } from '@kjanat/dreamcli';
333
- *
334
- * inferCliName({ bin: { mycli: './dist/cli.js' } }); // 'mycli'
335
- * inferCliName({ name: '@scope/mycli' }); // 'mycli'
336
- * inferCliName({ name: '@scope/mycli' }, { stripScope: false }); // '@scope/mycli'
337
- * inferCliName({ name: 'mycli' }); // 'mycli'
338
- * inferCliName({}); // undefined
339
- * ```
340
- */
341
- function inferCliName(pkg, options = {}) {
342
- if (typeof pkg.bin === "object") {
343
- const keys = Object.keys(pkg.bin);
344
- if (keys.length > 0 && keys[0] !== void 0) return keys[0];
345
- }
346
- if (pkg.name !== void 0) {
347
- if (options.stripScope === false) return pkg.name;
348
- const slashIdx = pkg.name.indexOf("/");
349
- return slashIdx >= 0 ? pkg.name.slice(slashIdx + 1) : pkg.name;
350
- }
351
- }
352
- //#endregion
353
- export { discoverManifest, inferCliName, packageRepositoryUrl };
@@ -1,125 +0,0 @@
1
- //#region src/core/errors/index.d.ts
2
- /**
3
- * Structured error types for DreamCLI.
4
- *
5
- * Base {@linkcode CLIError} carries stable code, exit code, suggestion, and structured
6
- * details. {@linkcode ParseError} and {@linkcode ValidationError} derive from it with
7
- * category-appropriate defaults.
8
- *
9
- * @module dreamcli/core/errors
10
- */
11
- /** Codes emitted during argv parsing. */
12
- export type ParseErrorCode = 'UNKNOWN_FLAG' | 'UNKNOWN_COMMAND' | 'MISSING_VALUE' | 'INVALID_VALUE' | 'INVALID_SCHEMA' | 'DUPLICATE_FLAG' | 'UNEXPECTED_POSITIONAL';
13
- /** Codes emitted during post-parse validation / resolution. */
14
- export type ValidationErrorCode = 'REQUIRED_FLAG' | 'REQUIRED_ARG' | 'MISSING_STDIN' | 'INVALID_ENUM' | 'TYPE_MISMATCH' | 'CONSTRAINT_VIOLATED';
15
- /** Any framework error code (extensible via `string & {}`). */
16
- export type ErrorCode = ParseErrorCode | ValidationErrorCode | (string & {});
17
- /** Options accepted by the `CLIError` constructor. */
18
- export interface CLIErrorOptions {
19
- /** Stable machine-readable identifier (e.g. `"UNKNOWN_FLAG"`). */
20
- readonly code: ErrorCode;
21
- /**
22
- * Process exit code.
23
- * @defaultValue `1`
24
- */
25
- readonly exitCode?: number;
26
- /** One-liner actionable hint shown to the user. */
27
- readonly suggest?: string;
28
- /** Arbitrary structured payload (serialised in `--json` mode). */
29
- readonly details?: Readonly<Record<string, unknown>>;
30
- /** Original error, if this wraps another. */
31
- readonly cause?: unknown;
32
- }
33
- /**
34
- * Base structured error for DreamCLI.
35
- *
36
- * Every error surfaced by the framework extends this class, ensuring a
37
- * consistent shape for rendering (TTY pretty-print, `--json`, test assertions).
38
- */
39
- export declare class CLIError extends Error {
40
- /** Error class name, always `'CLIError'` for the base class. @override */
41
- readonly name: string;
42
- /** Stable machine-readable identifier. */
43
- readonly code: ErrorCode;
44
- /** Process exit code (defaults to `1`). */
45
- readonly exitCode: number;
46
- /** One-liner actionable hint. */
47
- readonly suggest: string | undefined;
48
- /** Structured payload for machine output. */
49
- readonly details: Readonly<Record<string, unknown>> | undefined;
50
- /** Create a structured CLI error from a human message and machine-readable options. */
51
- constructor(message: string, options: CLIErrorOptions);
52
- /**
53
- * Serialise to a plain object suitable for JSON output.
54
- * @sealed
55
- */
56
- toJSON(): CLIErrorJSON;
57
- }
58
- /** Shape returned by {@linkcode CLIError}.toJSON(). */
59
- export interface CLIErrorJSON {
60
- /** Error class name (e.g. `'CLIError'`, `'ParseError'`). */
61
- readonly name: string;
62
- /** Stable machine-readable identifier for programmatic matching. */
63
- readonly code: ErrorCode;
64
- /** Human-readable description of what went wrong. */
65
- readonly message: string;
66
- /** Process exit code associated with this error. */
67
- readonly exitCode: number;
68
- /** Actionable hint shown to the user, when available. */
69
- readonly suggest?: string;
70
- /** Structured payload for machine consumers, when available. */
71
- readonly details?: Readonly<Record<string, unknown>>;
72
- }
73
- /** Options for {@linkcode ParseError}. Code is narrowed to parse-specific codes. */
74
- export interface ParseErrorOptions extends Omit<CLIErrorOptions, 'code' | 'exitCode'> {
75
- /** Parse-category error code (e.g. `'UNKNOWN_FLAG'`, `'MISSING_VALUE'`). */
76
- readonly code: ParseErrorCode;
77
- /**
78
- * Process exit code for parse failures.
79
- * @defaultValue `2`
80
- */
81
- readonly exitCode?: number;
82
- }
83
- /**
84
- * Error thrown when argv tokenization / parsing fails.
85
- *
86
- * Exit code defaults to `2` (standard for CLI usage errors).
87
- */
88
- export declare class ParseError extends CLIError {
89
- /** Always `'ParseError'`. @override */
90
- readonly name: "ParseError";
91
- /** Narrowed to parse-category codes. */
92
- readonly code: ParseErrorCode;
93
- /** Create a parse error with exit code defaulting to `2`. */
94
- constructor(message: string, options: ParseErrorOptions);
95
- }
96
- /** Options for {@linkcode ValidationError}. Code is narrowed to validation-specific codes. */
97
- export interface ValidationErrorOptions extends Omit<CLIErrorOptions, 'code' | 'exitCode'> {
98
- /** Validation-category error code (e.g. `'REQUIRED_FLAG'`, `'INVALID_ENUM'`). */
99
- readonly code: ValidationErrorCode;
100
- /**
101
- * Process exit code for validation failures.
102
- * @defaultValue `2`
103
- */
104
- readonly exitCode?: number;
105
- }
106
- /**
107
- * Error thrown when resolved values fail validation constraints.
108
- *
109
- * Exit code defaults to `2` (standard for CLI usage errors).
110
- */
111
- export declare class ValidationError extends CLIError {
112
- /** Always `'ValidationError'`. @override */
113
- readonly name: "ValidationError";
114
- /** Narrowed to validation-category codes. */
115
- readonly code: ValidationErrorCode;
116
- /** Create a validation error with exit code defaulting to `2`. */
117
- constructor(message: string, options: ValidationErrorOptions);
118
- }
119
- /** Narrows an unknown value to `CLIError`. */
120
- export declare function isCLIError(value: unknown): value is CLIError;
121
- /** Narrows an unknown value to `ParseError`. */
122
- export declare function isParseError(value: unknown): value is ParseError;
123
- /** Narrows an unknown value to `ValidationError`. */
124
- export declare function isValidationError(value: unknown): value is ValidationError;
125
- //#endregion
@@ -1,87 +0,0 @@
1
- //#region src/core/errors/index.ts
2
- /**
3
- * Base structured error for DreamCLI.
4
- *
5
- * Every error surfaced by the framework extends this class, ensuring a
6
- * consistent shape for rendering (TTY pretty-print, `--json`, test assertions).
7
- */
8
- var CLIError = class extends Error {
9
- /** Error class name, always `'CLIError'` for the base class. @override */
10
- name = "CLIError";
11
- /** Stable machine-readable identifier. */
12
- code;
13
- /** Process exit code (defaults to `1`). */
14
- exitCode;
15
- /** One-liner actionable hint. */
16
- suggest;
17
- /** Structured payload for machine output. */
18
- details;
19
- /** Create a structured CLI error from a human message and machine-readable options. */
20
- constructor(message, options) {
21
- super(message, options.cause !== void 0 ? { cause: options.cause } : void 0);
22
- this.code = options.code;
23
- this.exitCode = options.exitCode ?? 1;
24
- this.suggest = options.suggest;
25
- this.details = options.details;
26
- }
27
- /**
28
- * Serialise to a plain object suitable for JSON output.
29
- * @sealed
30
- */
31
- toJSON() {
32
- return {
33
- name: this.name,
34
- code: this.code,
35
- message: this.message,
36
- exitCode: this.exitCode,
37
- ...this.suggest !== void 0 && { suggest: this.suggest },
38
- ...this.details !== void 0 && { details: this.details }
39
- };
40
- }
41
- };
42
- /**
43
- * Error thrown when argv tokenization / parsing fails.
44
- *
45
- * Exit code defaults to `2` (standard for CLI usage errors).
46
- */
47
- var ParseError = class extends CLIError {
48
- /** Always `'ParseError'`. @override */
49
- name = "ParseError";
50
- /** Create a parse error with exit code defaulting to `2`. */
51
- constructor(message, options) {
52
- super(message, {
53
- ...options,
54
- exitCode: options.exitCode ?? 2
55
- });
56
- }
57
- };
58
- /**
59
- * Error thrown when resolved values fail validation constraints.
60
- *
61
- * Exit code defaults to `2` (standard for CLI usage errors).
62
- */
63
- var ValidationError = class extends CLIError {
64
- /** Always `'ValidationError'`. @override */
65
- name = "ValidationError";
66
- /** Create a validation error with exit code defaulting to `2`. */
67
- constructor(message, options) {
68
- super(message, {
69
- ...options,
70
- exitCode: options.exitCode ?? 2
71
- });
72
- }
73
- };
74
- /** Narrows an unknown value to `CLIError`. */
75
- function isCLIError(value) {
76
- return value instanceof CLIError;
77
- }
78
- /** Narrows an unknown value to `ParseError`. */
79
- function isParseError(value) {
80
- return value instanceof ParseError;
81
- }
82
- /** Narrows an unknown value to `ValidationError`. */
83
- function isValidationError(value) {
84
- return value instanceof ValidationError;
85
- }
86
- //#endregion
87
- export { CLIError, ParseError, ValidationError, isCLIError, isParseError, isValidationError };
@@ -1,61 +0,0 @@
1
- import { CLIError } from "../errors/index.mjs";
2
- import { CommandMeta, CommandSchema, ErasedActionHandler, ExecutionStep, Out } from "../schema/command.mjs";
3
- import { CapturedOutput } from "../output/index.mjs";
4
- import { InternalRunOptions, RunResult } from "../schema/run.mjs";
5
- //#region src/core/execution/index.d.ts
6
- /**
7
- * The executable half of a command: what to run, and what wraps it.
8
- *
9
- * The schema travels on the request instead, already merged with propagated
10
- * ancestor flags.
11
- * @internal
12
- */
13
- interface ExecutableCommand {
14
- /** Action handler, `undefined` when the command declares none. */
15
- readonly handler: ErasedActionHandler | undefined;
16
- /** Derive and middleware steps in registration order. */
17
- readonly steps: readonly ExecutionStep[];
18
- }
19
- /**
20
- * Explicit executor input for a single command invocation.
21
- * @internal
22
- */
23
- interface CommandExecutionRequest {
24
- /** The handler and execution steps to run. */
25
- readonly command: ExecutableCommand;
26
- /** Raw argument tokens to parse (excluding the program name). */
27
- readonly argv: readonly string[];
28
- /** Output channel for handler and error rendering. */
29
- readonly out: Out;
30
- /** Frozen schema definition (flags, args, metadata) for parsing and resolution. */
31
- readonly schema: CommandSchema;
32
- /** Runtime metadata (binary name, version) propagated to the handler. */
33
- readonly meta: CommandMeta;
34
- /** Optional overrides for env, config, prompter, plugins, and JSON mode. */
35
- readonly options?: InternalRunOptions;
36
- }
37
- /**
38
- * Minimal executor result before output buffers are assembled into `RunResult`.
39
- * @internal
40
- */
41
- interface CommandExecutionResult {
42
- /** Process exit code (`0` on success, error-specific otherwise). */
43
- readonly exitCode: number;
44
- /** The structured error if the command failed, `undefined` on success. */
45
- readonly error: CLIError | undefined;
46
- }
47
- /**
48
- * Run the full parse -> resolve -> plugin -> handler pipeline for one command.
49
- *
50
- * Handles `--help` short-circuit, plugin lifecycle hooks, deprecation warnings,
51
- * and error wrapping. Both CLI dispatch and testkit `runCommand` converge here.
52
- * @internal
53
- */
54
- declare function executeCommand(request: CommandExecutionRequest): Promise<CommandExecutionResult>;
55
- /**
56
- * Assemble a {@linkcode CommandExecutionResult} and captured output buffers into a public `RunResult`.
57
- * @internal
58
- */
59
- declare function buildRunResult(result: CommandExecutionResult, captured: CapturedOutput): RunResult;
60
- //#endregion
61
- export { type CommandExecutionRequest, type CommandExecutionResult, type ExecutableCommand, buildRunResult, executeCommand };