@kjanat/dreamcli 3.0.0-rc.1 → 3.0.0-rc.11

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 (194) hide show
  1. package/CHANGELOG.md +227 -1
  2. package/dist/core/cli/dispatch.d.mts +6 -5
  3. package/dist/core/cli/dispatch.mjs +205 -1
  4. package/dist/core/cli/help-links.d.mts +0 -1
  5. package/dist/core/cli/help-links.mjs +41 -1
  6. package/dist/core/cli/index.d.mts +81 -8
  7. package/dist/core/cli/index.mjs +945 -1
  8. package/dist/core/cli/planner.d.mts +5 -1
  9. package/dist/core/cli/planner.mjs +300 -1
  10. package/dist/core/cli/plugin.d.mts +1 -1
  11. package/dist/core/cli/plugin.mjs +41 -1
  12. package/dist/core/cli/propagate.d.mts +1 -1
  13. package/dist/core/cli/propagate.mjs +57 -1
  14. package/dist/core/cli/root-help.d.mts +2 -1
  15. package/dist/core/cli/root-help.mjs +226 -4
  16. package/dist/core/cli/root-surface.d.mts +12 -1
  17. package/dist/core/cli/root-surface.mjs +28 -1
  18. package/dist/core/cli/runtime-preflight.d.mts +14 -2
  19. package/dist/core/cli/runtime-preflight.mjs +169 -1
  20. package/dist/core/completion/index.d.mts +0 -1
  21. package/dist/core/completion/index.mjs +90 -1
  22. package/dist/core/completion/shells/bash.d.mts +0 -1
  23. package/dist/core/completion/shells/bash.mjs +308 -3
  24. package/dist/core/completion/shells/fish.d.mts +0 -1
  25. package/dist/core/completion/shells/fish.mjs +162 -2
  26. package/dist/core/completion/shells/powershell.d.mts +0 -1
  27. package/dist/core/completion/shells/powershell.mjs +358 -2
  28. package/dist/core/completion/shells/shared.d.mts +13 -2
  29. package/dist/core/completion/shells/shared.mjs +176 -1
  30. package/dist/core/completion/shells/zsh.d.mts +0 -1
  31. package/dist/core/completion/shells/zsh.mjs +251 -2
  32. package/dist/core/config/index.d.mts +2 -3
  33. package/dist/core/config/index.mjs +246 -1
  34. package/dist/core/config/package-json.d.mts +27 -4
  35. package/dist/core/config/package-json.mjs +386 -3
  36. package/dist/core/errors/index.d.mts +3 -3
  37. package/dist/core/errors/index.mjs +87 -1
  38. package/dist/core/execution/index.d.mts +0 -1
  39. package/dist/core/execution/index.mjs +201 -1
  40. package/dist/core/help/ansi.d.mts +11 -5
  41. package/dist/core/help/ansi.mjs +121 -2
  42. package/dist/core/help/index.d.mts +22 -3
  43. package/dist/core/help/index.mjs +341 -7
  44. package/dist/core/help/theme.d.mts +68 -0
  45. package/dist/core/help/theme.mjs +46 -0
  46. package/dist/core/json-schema/index.d.mts +15 -2
  47. package/dist/core/json-schema/index.mjs +536 -12
  48. package/dist/core/json-schema/meta-descriptions.generated.d.mts +55 -38
  49. package/dist/core/json-schema/meta-descriptions.generated.mjs +102 -28
  50. package/dist/core/output/activity.d.mts +0 -1
  51. package/dist/core/output/activity.mjs +452 -1
  52. package/dist/core/output/bind.mjs +56 -1
  53. package/dist/core/output/contracts.d.mts +4 -5
  54. package/dist/core/output/contracts.mjs +57 -1
  55. package/dist/core/output/display-value.mjs +32 -1
  56. package/dist/core/output/index.d.mts +21 -1
  57. package/dist/core/output/index.mjs +442 -2
  58. package/dist/core/output/renderers.d.mts +0 -1
  59. package/dist/core/output/renderers.mjs +46 -1
  60. package/dist/core/output/writer.mjs +12 -1
  61. package/dist/core/parse/index.d.mts +40 -7
  62. package/dist/core/parse/index.mjs +727 -1
  63. package/dist/core/prompt/index.d.mts +1 -1
  64. package/dist/core/prompt/index.mjs +348 -6
  65. package/dist/core/resolve/args.d.mts +1 -1
  66. package/dist/core/resolve/args.mjs +105 -1
  67. package/dist/core/resolve/coerce.d.mts +1 -1
  68. package/dist/core/resolve/coerce.mjs +336 -1
  69. package/dist/core/resolve/config.mjs +19 -1
  70. package/dist/core/resolve/contracts.d.mts +9 -4
  71. package/dist/core/resolve/errors.d.mts +0 -1
  72. package/dist/core/resolve/errors.mjs +140 -2
  73. package/dist/core/resolve/flags.d.mts +7 -2
  74. package/dist/core/resolve/flags.mjs +251 -1
  75. package/dist/core/resolve/index.d.mts +2 -2
  76. package/dist/core/resolve/index.mjs +85 -1
  77. package/dist/core/resolve/property.d.mts +4 -2
  78. package/dist/core/resolve/property.mjs +53 -1
  79. package/dist/core/schema/activity.d.mts +31 -11
  80. package/dist/core/schema/arg.d.mts +3 -4
  81. package/dist/core/schema/arg.mjs +463 -1
  82. package/dist/core/schema/command.d.mts +26 -6
  83. package/dist/core/schema/command.mjs +726 -1
  84. package/dist/core/schema/flag.d.mts +485 -19
  85. package/dist/core/schema/flag.mjs +705 -1
  86. package/dist/core/schema/index.d.mts +4 -2
  87. package/dist/core/schema/middleware.d.mts +4 -3
  88. package/dist/core/schema/middleware.mjs +41 -1
  89. package/dist/core/schema/number-constraints.mjs +60 -1
  90. package/dist/core/schema/prompt.d.mts +6 -3
  91. package/dist/core/schema/run.d.mts +20 -1
  92. package/dist/core/schema/string-constraints.d.mts +97 -0
  93. package/dist/core/schema/string-constraints.mjs +69 -0
  94. package/dist/core/schema/value-parsers.d.mts +78 -0
  95. package/dist/core/schema/value-parsers.mjs +142 -0
  96. package/dist/core/schema-dsl/runtime.mjs +271 -2
  97. package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
  98. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  99. package/dist/core/testkit/index.d.mts +0 -31
  100. package/dist/core/testkit/index.mjs +83 -1
  101. package/dist/index.d.mts +11 -6
  102. package/dist/index.mjs +22 -1
  103. package/dist/runtime/adapter.d.mts +38 -2
  104. package/dist/runtime/adapter.mjs +87 -1
  105. package/dist/runtime/auto.d.mts +2 -3
  106. package/dist/runtime/auto.mjs +45 -1
  107. package/dist/runtime/deno.d.mts +24 -5
  108. package/dist/runtime/deno.mjs +262 -2
  109. package/dist/runtime/detect.mjs +45 -1
  110. package/dist/runtime/index.d.mts +3 -4
  111. package/dist/runtime/node.d.mts +8 -2
  112. package/dist/runtime/node.mjs +220 -2
  113. package/dist/runtime/paths.mjs +48 -1
  114. package/dist/runtime.d.mts +4 -4
  115. package/dist/runtime.mjs +6 -1
  116. package/dist/strings.mjs +22 -1
  117. package/dist/testkit.d.mts +1 -0
  118. package/dist/testkit.mjs +5 -1
  119. package/dist/version.d.mts +7 -3
  120. package/dist/version.mjs +7 -1
  121. package/dreamcli.schema.json +36 -7
  122. package/package.json +45 -42
  123. package/dist/runtime/bun.d.mts +0 -28
  124. package/dist/runtime/bun.mjs +0 -1
  125. package/src/core/cli/dispatch.ts +0 -355
  126. package/src/core/cli/help-links.ts +0 -82
  127. package/src/core/cli/index.ts +0 -1614
  128. package/src/core/cli/planner.ts +0 -656
  129. package/src/core/cli/plugin.ts +0 -117
  130. package/src/core/cli/propagate.ts +0 -97
  131. package/src/core/cli/root-help.ts +0 -342
  132. package/src/core/cli/root-surface.ts +0 -87
  133. package/src/core/cli/runtime-preflight.ts +0 -456
  134. package/src/core/completion/index.ts +0 -138
  135. package/src/core/completion/shells/bash.ts +0 -459
  136. package/src/core/completion/shells/fish.ts +0 -259
  137. package/src/core/completion/shells/powershell.ts +0 -439
  138. package/src/core/completion/shells/shared.ts +0 -310
  139. package/src/core/completion/shells/zsh.ts +0 -381
  140. package/src/core/config/index.ts +0 -417
  141. package/src/core/config/package-json.ts +0 -560
  142. package/src/core/errors/index.ts +0 -193
  143. package/src/core/execution/index.ts +0 -265
  144. package/src/core/help/ansi.ts +0 -144
  145. package/src/core/help/index.ts +0 -563
  146. package/src/core/json-schema/index.ts +0 -910
  147. package/src/core/json-schema/meta-descriptions.generated.ts +0 -202
  148. package/src/core/output/activity.ts +0 -575
  149. package/src/core/output/bind.ts +0 -59
  150. package/src/core/output/contracts.ts +0 -194
  151. package/src/core/output/display-value.ts +0 -48
  152. package/src/core/output/index.ts +0 -704
  153. package/src/core/output/renderers.ts +0 -125
  154. package/src/core/output/writer.ts +0 -46
  155. package/src/core/parse/index.ts +0 -742
  156. package/src/core/prompt/index.ts +0 -623
  157. package/src/core/resolve/args.ts +0 -144
  158. package/src/core/resolve/coerce.ts +0 -500
  159. package/src/core/resolve/config.ts +0 -26
  160. package/src/core/resolve/contracts.ts +0 -135
  161. package/src/core/resolve/errors.ts +0 -227
  162. package/src/core/resolve/flags.ts +0 -269
  163. package/src/core/resolve/index.ts +0 -108
  164. package/src/core/resolve/property.ts +0 -99
  165. package/src/core/schema/activity.ts +0 -240
  166. package/src/core/schema/arg.ts +0 -841
  167. package/src/core/schema/command.ts +0 -1500
  168. package/src/core/schema/flag.ts +0 -917
  169. package/src/core/schema/index.ts +0 -96
  170. package/src/core/schema/middleware.ts +0 -171
  171. package/src/core/schema/number-constraints.ts +0 -153
  172. package/src/core/schema/prompt.ts +0 -171
  173. package/src/core/schema/run.ts +0 -198
  174. package/src/core/schema-dsl/index.ts +0 -109
  175. package/src/core/schema-dsl/parse.ts +0 -262
  176. package/src/core/schema-dsl/runtime.ts +0 -609
  177. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  178. package/src/core/testkit/index.ts +0 -147
  179. package/src/index.ts +0 -181
  180. package/src/runtime/adapter.ts +0 -303
  181. package/src/runtime/auto.ts +0 -86
  182. package/src/runtime/bun.ts +0 -48
  183. package/src/runtime/deno.ts +0 -367
  184. package/src/runtime/detect.ts +0 -105
  185. package/src/runtime/index.ts +0 -21
  186. package/src/runtime/node-builtins.d.ts +0 -27
  187. package/src/runtime/node.ts +0 -289
  188. package/src/runtime/paths.ts +0 -64
  189. package/src/runtime/support.ts +0 -77
  190. package/src/runtime.ts +0 -31
  191. package/src/schema.ts +0 -16
  192. package/src/strings.ts +0 -34
  193. package/src/testkit.ts +0 -25
  194. package/src/version.ts +0 -20
@@ -1,560 +0,0 @@
1
- /**
2
- * Package.json auto-discovery via directory walk-up.
3
- *
4
- * Walks up from `adapter.cwd` to find the nearest `package.json`, parses
5
- * it, and extracts metadata (name, version, description, bin). All I/O
6
- * flows through the adapter — fully testable with virtual filesystems.
7
- *
8
- * @module dreamcli/core/config/package-json
9
- */
10
-
11
- import type { RuntimeAdapter } from '#internals/runtime/adapter.ts';
12
- import { SLASH, stripTrailing } from '#internals/strings.ts';
13
-
14
- // --- Narrowing helpers
15
-
16
- /** Type guard: narrows `unknown` to a plain (non-array) object. */
17
- function isPlainObject(value: unknown): value is Record<string, unknown> {
18
- return typeof value === 'object' && value !== null && !Array.isArray(value);
19
- }
20
-
21
- // --- Types
22
-
23
- /**
24
- * Object form of the package.json `repository` field
25
- * (e.g. `{"type":"git","url":"git+https://github.com/u/r.git"}`).
26
- */
27
- interface PackageRepository {
28
- /** Version control system type (usually `'git'`). */
29
- readonly type?: string;
30
- /** Repository URL or locator. */
31
- readonly url?: string;
32
- /** Subdirectory within a monorepo where the package lives. */
33
- readonly directory?: string;
34
- }
35
-
36
- /**
37
- * Subset of package.json fields relevant to CLI metadata.
38
- *
39
- * All fields are optional — a valid package.json may omit any of them.
40
- */
41
- interface PackageJsonData {
42
- /** Package name (e.g. `@scope/mycli`). */
43
- readonly name?: string;
44
- /** Semver version string from `package.json`. */
45
- readonly version?: string;
46
- /** One-line package description. */
47
- readonly description?: string;
48
- /** Binary entry point(s) — string for single-bin, object for multi-bin. */
49
- readonly bin?: string | Readonly<Record<string, string>>;
50
- /** Project homepage URL. */
51
- readonly homepage?: string;
52
- /** Repository locator — URL/shorthand string or `{type, url, directory}` object. */
53
- readonly repository?: string | PackageRepository;
54
- }
55
-
56
- /**
57
- * The subset of {@link RuntimeAdapter} needed for package.json discovery.
58
- *
59
- * Using a narrow pick keeps the function easy to test and makes the
60
- * dependency explicit.
61
- */
62
- type PackageJsonAdapter = Pick<RuntimeAdapter, 'readFile' | 'cwd'>;
63
-
64
- // --- Path utilities
65
-
66
- /**
67
- * Compute the parent directory of a path using the separator detected
68
- * from the path itself.
69
- *
70
- * Returns `undefined` when the path is already the root (e.g. `/` or `C:\`).
71
- * Pure string manipulation — no filesystem access.
72
- *
73
- * @internal
74
- */
75
- function parentDir(path: string): string | undefined {
76
- // Handle mixed separators (common on Windows) by finding the last of either.
77
- const fwdIdx = path.lastIndexOf('/');
78
- const bkIdx = path.lastIndexOf('\\');
79
- const idx = Math.max(fwdIdx, bkIdx);
80
- // Derive separator from whichever was found last (for drive root construction).
81
- const sep = bkIdx > fwdIdx ? '\\' : '/';
82
- // Already at root (Unix `/` or Windows `C:\`)
83
- if (idx < 0) return undefined;
84
- if (idx === 0) return path.length > 1 ? sep : undefined;
85
- const parent = path.slice(0, idx);
86
- // Windows drive root: `C:` → `C:\`, but already AT drive root → stop
87
- if (parent.length === 2 && parent[1] === ':') {
88
- const driveRoot = `${parent}${sep}`;
89
- return driveRoot === path ? undefined : driveRoot;
90
- }
91
- return parent;
92
- }
93
-
94
- /**
95
- * Join a base path with a filename segment.
96
- *
97
- * @internal
98
- */
99
- function joinPath(base: string, segment: string): string {
100
- const sep = base.includes('\\') ? '\\' : '/';
101
- return base.endsWith(sep) ? `${base}${segment}` : `${base}${sep}${segment}`;
102
- }
103
-
104
- // --- discoverManifest
105
-
106
- /** Default manifest filenames probed when none are supplied. @internal */
107
- const DEFAULT_MANIFEST_FILES: readonly string[] = ['package.json'];
108
-
109
- /** Options for {@link discoverManifest}. */
110
- interface ManifestDiscoveryOptions {
111
- /**
112
- * Explicit directory or file path to walk up from. Defaults to
113
- * `adapter.cwd` when omitted. Pass an absolute path inside your own package
114
- * (e.g. `fileURLToPath(import.meta.url)`) for installable CLIs whose version
115
- * should reflect the CLI's own package, not the consumer's working directory.
116
- *
117
- * This low-level helper takes a resolved path **string** only. The builder
118
- * sugar `CLIBuilder.manifest({ from })` exposes the same anchor under the name
119
- * `from` and additionally accepts a `file:` URL string or `URL` instance,
120
- * normalizing it to a path first.
121
- */
122
- readonly startDir?: string;
123
- /**
124
- * Candidate manifest filenames, in per-directory priority order
125
- * (e.g. `['deno.json', 'jsr.json']`). At each directory the first existing
126
- * file that carries CLI metadata wins, so the nearest manifest directory
127
- * always takes precedence over file order. A file that parses but holds no
128
- * recognised metadata (e.g. a config-only `deno.json` with just
129
- * `tasks`/`imports`) is skipped, so a sibling `jsr.json` — or a manifest
130
- * higher up — can still be found. Defaults to `['package.json']`.
131
- *
132
- * An empty list is a deliberate no-op: with no candidates to probe, the
133
- * walk-up reads nothing and resolves to `null` (consistent with the
134
- * "returns `null` when no manifest is found" contract).
135
- */
136
- readonly files?: readonly string[];
137
- }
138
-
139
- /**
140
- * Whether parsed manifest data carries any CLI-relevant metadata.
141
- *
142
- * {@link parsePackageJson} returns an empty object for a config-only manifest
143
- * (e.g. a `deno.json` holding only `tasks` / `imports` / `compilerOptions`).
144
- * Treating that empty result as a discovery hit would shadow a sibling
145
- * `jsr.json` and halt the walk-up, silently dropping real metadata. Discovery
146
- * therefore only accepts a manifest that actually carries at least one
147
- * recognised field.
148
- *
149
- * @internal
150
- */
151
- function manifestHasMetadata(data: PackageJsonData): boolean {
152
- return (
153
- data.name !== undefined ||
154
- data.version !== undefined ||
155
- data.description !== undefined ||
156
- data.bin !== undefined ||
157
- data.homepage !== undefined ||
158
- data.repository !== undefined
159
- );
160
- }
161
-
162
- /**
163
- * Discover the nearest manifest (`package.json`, `deno.json`, `jsr.json`, …)
164
- * by walking up from `startDir` (or `adapter.cwd` when omitted).
165
- *
166
- * Convenience helper behind `CLIBuilder.manifest()`. Most apps should let the
167
- * CLI runtime discover metadata automatically; call this directly when testing
168
- * metadata inference or embedding the behavior in custom tooling.
169
- *
170
- * Candidate files are parsed as JSON with a JSONC fallback — `package.json`,
171
- * `deno.json`, `jsr.json`, and `deno.jsonc` all qualify, including files that
172
- * carry `//` / block comments or trailing commas (common in `deno.json`). A
173
- * file that fails both parses is skipped, so discovery keeps probing.
174
- *
175
- * Returns the parsed metadata on success, `null` when no manifest is found
176
- * (not an error). Malformed JSON, non-object roots, and config-only manifests
177
- * that carry no recognised metadata (e.g. a `deno.json` with only `tasks` /
178
- * `imports`) are all skipped, so discovery keeps probing the remaining
179
- * candidate files and parent directories — the feature is a convenience, not a
180
- * hard requirement.
181
- *
182
- * @param adapter - Adapter providing `readFile` + `cwd`.
183
- * @param options - Optional anchor (`startDir`) and candidate filenames (`files`).
184
- *
185
- * @example
186
- * ```ts
187
- * import { discoverManifest } from '@kjanat/dreamcli';
188
- *
189
- * const meta = await discoverManifest(adapter, { files: ['deno.json', 'jsr.json'] });
190
- * if (meta !== null) {
191
- * console.log(meta.version); // '1.2.3'
192
- * }
193
- * ```
194
- */
195
- async function discoverManifest(
196
- adapter: PackageJsonAdapter,
197
- options: ManifestDiscoveryOptions = {},
198
- ): Promise<PackageJsonData | null> {
199
- const files = options.files ?? DEFAULT_MANIFEST_FILES;
200
- let dir: string | undefined = options.startDir ?? adapter.cwd;
201
-
202
- while (dir !== undefined) {
203
- for (const file of files) {
204
- let content: string | null = null;
205
- try {
206
- content = await adapter.readFile(joinPath(dir, file));
207
- } catch {
208
- // Adapter may throw on permission errors, is-directory, or other
209
- // syscall failures — skip this file and keep probing.
210
- }
211
- if (content !== null) {
212
- const parsed = parsePackageJson(content);
213
- if (parsed !== null && manifestHasMetadata(parsed)) {
214
- return parsed;
215
- }
216
- }
217
- }
218
- dir = parentDir(dir);
219
- }
220
-
221
- return null;
222
- }
223
-
224
- // --- discoverPackageJson
225
-
226
- /**
227
- * Discover the nearest `package.json` by walking up from `startDir` (or
228
- * `adapter.cwd` when omitted).
229
- *
230
- * @deprecated Use {@link discoverManifest} with `{ files: ['package.json'] }`
231
- * (the default), which also supports `deno.json` / `jsr.json`.
232
- *
233
- * Behavior note (changed by the manifest generalization): a parseable but
234
- * metadata-less `package.json` — `{}`, or one carrying only non-metadata fields
235
- * such as `dependencies` / `scripts` / `type` — is no longer treated as a
236
- * discovery hit. Previously such a file halted the walk-up and resolved to `{}`;
237
- * now it is skipped and the walk-up CONTINUES to parent directories. In a
238
- * monorepo this means a metadata-less leaf `package.json` no longer shadows an
239
- * ancestor manifest, so an ancestor's `version` can surface where the old
240
- * behavior returned `{}`. Pass pre-loaded `data` (or use {@link discoverManifest}
241
- * with an explicit `startDir`) when you need to pin discovery to one directory.
242
- *
243
- * @param adapter - Adapter providing `readFile` + `cwd`.
244
- * @param startDir - Optional explicit directory or file path to walk up from.
245
- *
246
- * @example
247
- * ```ts
248
- * import { discoverPackageJson } from '@kjanat/dreamcli';
249
- *
250
- * const pkg = await discoverPackageJson(adapter);
251
- * if (pkg !== null) {
252
- * console.log(pkg.version); // '1.2.3'
253
- * }
254
- * ```
255
- */
256
- async function discoverPackageJson(
257
- adapter: PackageJsonAdapter,
258
- startDir?: string,
259
- ): Promise<PackageJsonData | null> {
260
- return discoverManifest(adapter, startDir !== undefined ? { startDir } : {});
261
- }
262
-
263
- // --- stripJsonc
264
-
265
- /** Whitespace characters JSON treats as insignificant. @internal */
266
- function isJsonWhitespace(ch: string): boolean {
267
- return ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r';
268
- }
269
-
270
- /**
271
- * Strip JSONC extensions (line/block comments and trailing commas) so the result
272
- * is plain JSON. String-aware: comment markers and commas inside string literals
273
- * are preserved verbatim, so a `"https://…"` URL or a `"/* …"` value survives
274
- * untouched. Runtime-agnostic — no dependencies, plain string scanning.
275
- *
276
- * Only invoked as a fallback when strict `JSON.parse` fails, so valid JSON never
277
- * passes through here.
278
- *
279
- * @internal
280
- */
281
- function stripJsonc(input: string): string {
282
- // Pass 1 — drop comments outside of strings.
283
- let decommented = '';
284
- let inString = false;
285
- let escaped = false;
286
- for (let i = 0; i < input.length; i += 1) {
287
- const ch = input[i] ?? '';
288
- if (inString) {
289
- decommented += ch;
290
- if (escaped) escaped = false;
291
- else if (ch === '\\') escaped = true;
292
- else if (ch === '"') inString = false;
293
- continue;
294
- }
295
- if (ch === '"') {
296
- inString = true;
297
- decommented += ch;
298
- continue;
299
- }
300
- if (ch === '/' && input[i + 1] === '/') {
301
- i += 2;
302
- while (i < input.length && input[i] !== '\n') i += 1;
303
- i -= 1; // let the loop's increment land on (and re-emit) the newline
304
- continue;
305
- }
306
- if (ch === '/' && input[i + 1] === '*') {
307
- i += 2;
308
- while (i < input.length && !(input[i] === '*' && input[i + 1] === '/')) i += 1;
309
- i += 1; // skip the '*'; the loop increment skips the closing '/'
310
- continue;
311
- }
312
- decommented += ch;
313
- }
314
-
315
- // Pass 2 — drop commas immediately before a closing `}` or `]`.
316
- let result = '';
317
- inString = false;
318
- escaped = false;
319
- for (let i = 0; i < decommented.length; i += 1) {
320
- const ch = decommented[i] ?? '';
321
- if (inString) {
322
- result += ch;
323
- if (escaped) escaped = false;
324
- else if (ch === '\\') escaped = true;
325
- else if (ch === '"') inString = false;
326
- continue;
327
- }
328
- if (ch === '"') {
329
- inString = true;
330
- result += ch;
331
- continue;
332
- }
333
- if (ch === ',') {
334
- let j = i + 1;
335
- while (j < decommented.length && isJsonWhitespace(decommented[j] ?? '')) j += 1;
336
- const next = decommented[j];
337
- if (next === '}' || next === ']') {
338
- continue; // trailing comma — omit it
339
- }
340
- }
341
- result += ch;
342
- }
343
- return result;
344
- }
345
-
346
- // --- parsePackageJson
347
-
348
- /**
349
- * Parse a manifest content string into {@link PackageJsonData}.
350
- *
351
- * Strict JSON is parsed directly; on failure, a JSONC fallback strips comments
352
- * and trailing commas (common in `deno.json`) and retries. Returns `null` for
353
- * content that is neither valid JSON nor JSONC, or whose root is not an object.
354
- *
355
- * @internal
356
- */
357
- function parsePackageJson(content: string): PackageJsonData | null {
358
- let parsed: unknown;
359
- try {
360
- parsed = JSON.parse(content);
361
- } catch {
362
- // Tolerate JSONC: deno.json is parsed as JSONC by Deno and real files
363
- // routinely carry comments / trailing commas. Retry after stripping them.
364
- try {
365
- parsed = JSON.parse(stripJsonc(content));
366
- } catch {
367
- return null;
368
- }
369
- }
370
- try {
371
- if (!isPlainObject(parsed)) {
372
- return null;
373
- }
374
- const name = typeof parsed['name'] === 'string' ? parsed['name'] : undefined;
375
- const version = typeof parsed['version'] === 'string' ? parsed['version'] : undefined;
376
- const description =
377
- typeof parsed['description'] === 'string' ? parsed['description'] : undefined;
378
- const bin = parseBinField(parsed['bin']);
379
- const homepage = typeof parsed['homepage'] === 'string' ? parsed['homepage'] : undefined;
380
- const repository = parseRepositoryField(parsed['repository']);
381
- return {
382
- ...(name !== undefined ? { name } : {}),
383
- ...(version !== undefined ? { version } : {}),
384
- ...(description !== undefined ? { description } : {}),
385
- ...(bin !== undefined ? { bin } : {}),
386
- ...(homepage !== undefined ? { homepage } : {}),
387
- ...(repository !== undefined ? { repository } : {}),
388
- };
389
- } catch {
390
- return null;
391
- }
392
- }
393
-
394
- /**
395
- * Parse the `bin` field from package.json.
396
- *
397
- * Accepts either a string (`"bin": "./dist/cli.js"`) or an object
398
- * (`"bin": { "mycli": "./dist/cli.js" }`). Returns `undefined` for
399
- * anything else.
400
- *
401
- * @internal
402
- */
403
- function parseBinField(value: unknown): string | Readonly<Record<string, string>> | undefined {
404
- if (typeof value === 'string') return value;
405
- if (!isPlainObject(value)) return undefined;
406
- const result: Record<string, string> = {};
407
- for (const [k, v] of Object.entries(value)) {
408
- if (typeof v !== 'string') return undefined;
409
- result[k] = v;
410
- }
411
- return result;
412
- }
413
-
414
- /**
415
- * Parse the `repository` field from package.json.
416
- *
417
- * Accepts either a locator string (`"repository": "github:u/r"`) or an
418
- * object (`"repository": { "type": "git", "url": "..." }`). Returns
419
- * `undefined` for anything else.
420
- *
421
- * @internal
422
- */
423
- function parseRepositoryField(value: unknown): string | PackageRepository | undefined {
424
- if (typeof value === 'string') return value;
425
- if (!isPlainObject(value)) return undefined;
426
- const type = typeof value['type'] === 'string' ? value['type'] : undefined;
427
- const url = typeof value['url'] === 'string' ? value['url'] : undefined;
428
- const directory = typeof value['directory'] === 'string' ? value['directory'] : undefined;
429
- if (type === undefined && url === undefined && directory === undefined) return undefined;
430
- return {
431
- ...(type !== undefined ? { type } : {}),
432
- ...(url !== undefined ? { url } : {}),
433
- ...(directory !== undefined ? { directory } : {}),
434
- };
435
- }
436
-
437
- // --- packageRepositoryUrl
438
-
439
- /** Browsable base URLs for npm repository shorthand prefixes. @internal */
440
- const SHORTHAND_HOSTS: Readonly<Record<string, string>> = {
441
- github: 'https://github.com',
442
- gitlab: 'https://gitlab.com',
443
- bitbucket: 'https://bitbucket.org',
444
- };
445
-
446
- /** Strip a trailing `.git` suffix from a repository path. @internal */
447
- function stripGitSuffix(path: string): string {
448
- return path.endsWith('.git') ? path.slice(0, -'.git'.length) : path;
449
- }
450
-
451
- /**
452
- * Resolve a package's `repository` field to a browsable `https://` URL.
453
- *
454
- * Handles the locator formats npm accepts:
455
- * - object form: `{ "type": "git", "url": "git+https://github.com/u/r.git" }`
456
- * - `https`/`git`/`ssh` URLs (`git+` prefix and `.git` suffix stripped)
457
- * - scp-style locators: `git@github.com:u/r.git`
458
- * - shorthands: `github:u/r`, `gitlab:u/r`, `bitbucket:u/r`, and bare `u/r`
459
- * (GitHub, per npm convention)
460
- *
461
- * Returns `undefined` when the field is absent or unrecognised.
462
- *
463
- * @example
464
- * ```ts
465
- * packageRepositoryUrl({ repository: 'git+https://github.com/u/r.git' });
466
- * // 'https://github.com/u/r'
467
- * ```
468
- */
469
- function packageRepositoryUrl(pkg: PackageJsonData): string | undefined {
470
- const raw = typeof pkg.repository === 'string' ? pkg.repository : pkg.repository?.url;
471
- if (raw === undefined) return undefined;
472
-
473
- let locator = raw.trim();
474
- if (locator.length === 0) return undefined;
475
-
476
- // npm shorthands: `github:u/r`, `gitlab:u/r`, `bitbucket:u/r`
477
- const shorthand = /^(github|gitlab|bitbucket):([^/]+\/[^/]+)$/.exec(locator);
478
- if (shorthand !== null && shorthand[1] !== undefined && shorthand[2] !== undefined) {
479
- const host = SHORTHAND_HOSTS[shorthand[1]];
480
- if (host !== undefined) {
481
- return `${host}/${stripGitSuffix(shorthand[2])}`;
482
- }
483
- }
484
-
485
- // Bare `u/r` implies GitHub (npm convention)
486
- if (/^[\w.-]+\/[\w.-]+$/.test(locator)) {
487
- return `https://github.com/${stripGitSuffix(locator)}`;
488
- }
489
-
490
- if (locator.startsWith('git+')) {
491
- locator = locator.slice('git+'.length);
492
- }
493
-
494
- // scp-style locator: `git@github.com:u/r.git`
495
- const scp = /^git@([^:/]+):(.+)$/.exec(locator);
496
- if (scp !== null && scp[1] !== undefined && scp[2] !== undefined) {
497
- return `https://${scp[1]}/${stripGitSuffix(stripTrailing(scp[2], [SLASH]))}`;
498
- }
499
-
500
- if (!/^(?:https?|git|ssh):\/\//.test(locator)) return undefined;
501
- try {
502
- const url = new URL(locator);
503
- const path = stripGitSuffix(stripTrailing(url.pathname, [SLASH]));
504
- return `https://${url.hostname}${path}`;
505
- } catch {
506
- return undefined;
507
- }
508
- }
509
-
510
- // --- inferCliName
511
-
512
- /**
513
- * Infer the CLI binary name from manifest data.
514
- *
515
- * Resolution order:
516
- * 1. First key of `bin` object (e.g. `{"mycli": "./dist/cli.js"}` → `"mycli"`)
517
- * 2. Package `name`, scope stripped by default (e.g. `"@scope/mycli"` → `"mycli"`);
518
- * pass `{ stripScope: false }` to keep the full scoped name
519
- * 3. `undefined` if neither exists
520
- *
521
- * Note: `bin` keys are never scoped, so `stripScope` only affects the `name`
522
- * fallback (relevant for `deno.json` / `jsr.json`, which have no `bin` field).
523
- *
524
- * @param pkg - Parsed manifest metadata.
525
- * @param options - `stripScope` (default `true`): strip a leading `@scope/`
526
- * from the `name` fallback.
527
- *
528
- * @example
529
- * ```ts
530
- * import { inferCliName } from '@kjanat/dreamcli';
531
- *
532
- * inferCliName({ bin: { mycli: './dist/cli.js' } }); // 'mycli'
533
- * inferCliName({ name: '@scope/mycli' }); // 'mycli'
534
- * inferCliName({ name: '@scope/mycli' }, { stripScope: false }); // '@scope/mycli'
535
- * inferCliName({ name: 'mycli' }); // 'mycli'
536
- * inferCliName({}); // undefined
537
- * ```
538
- */
539
- function inferCliName(
540
- pkg: PackageJsonData,
541
- options: { readonly stripScope?: boolean } = {},
542
- ): string | undefined {
543
- // Prefer bin key name (never scoped).
544
- if (typeof pkg.bin === 'object') {
545
- const keys = Object.keys(pkg.bin);
546
- if (keys.length > 0 && keys[0] !== undefined) return keys[0];
547
- }
548
- // Fall back to package name, optionally stripped of scope.
549
- if (pkg.name !== undefined) {
550
- if (options.stripScope === false) return pkg.name;
551
- const slashIdx = pkg.name.indexOf('/');
552
- return slashIdx >= 0 ? pkg.name.slice(slashIdx + 1) : pkg.name;
553
- }
554
- return undefined;
555
- }
556
-
557
- // --- Exports
558
-
559
- export type { ManifestDiscoveryOptions, PackageJsonAdapter, PackageJsonData, PackageRepository };
560
- export { discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl };