@kjanat/dreamcli 2.4.1 → 2.5.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.
@@ -187,18 +187,22 @@ interface CLISchema {
187
187
  */
188
188
  readonly configSettings: ConfigSettings | undefined;
189
189
  /**
190
- * Package.json auto-discovery settings. When defined, `.run()` discovers
191
- * the nearest `package.json` and merges metadata before dispatch.
190
+ * Manifest auto-discovery settings. When defined, `.run()` discovers the
191
+ * nearest manifest (`package.json`, `deno.json`, `jsr.json`, …) and merges
192
+ * metadata before dispatch.
192
193
  *
193
- * Set via the {@linkcode CLIBuilder.packageJson | .packageJson()} builder method.
194
+ * Set via the {@linkcode CLIBuilder.manifest | .manifest()} builder method
195
+ * (or the {@linkcode CLIBuilder.packageJson | .packageJson()} /
196
+ * {@linkcode CLIBuilder.denoJson | .denoJson()} presets).
194
197
  */
195
- readonly packageJsonSettings: PackageJsonSettings | undefined;
198
+ readonly packageJsonSettings: ResolvedManifestSettings | undefined;
196
199
  /**
197
200
  * OSC 8 hyperlink targets for the root-help header (name/version).
198
201
  *
199
202
  * Set via the {@linkcode CLIBuilder.links | .links()} builder method.
200
- * Fields left `undefined` are derived from package.json metadata
201
- * (`repository` / `homepage`) when `.packageJson()` is active.
203
+ * Fields left `undefined` are derived from manifest metadata
204
+ * (`repository` / `homepage`) when manifest discovery ({@linkcode
205
+ * CLIBuilder.manifest | .manifest()}) is active.
202
206
  */
203
207
  readonly helpLinks: HelpLinks | undefined;
204
208
  /** Whether built-in `.completions()` command registration is active. */
@@ -229,14 +233,22 @@ interface ConfigSettings {
229
233
  }
230
234
 
231
235
  /**
232
- * Package.json auto-discovery settings.
236
+ * Manifest auto-discovery settings — the resolved/normalized shape stored in
237
+ * the schema.
233
238
  *
234
239
  * Stored in {@link CLISchema} and consumed by `CLIBuilder.run()` to
235
- * call {@link discoverPackageJson} before dispatching to a command.
240
+ * call {@link discoverManifest} before dispatching to a command.
241
+ *
242
+ * Note: the schema FIELD name (`packageJsonSettings`) keeps its `packageJson`
243
+ * prefix for backward compatibility — renaming it would break consumers reading
244
+ * `app.schema.packageJsonSettings`. The type itself is now generically named
245
+ * (it holds discovery config for any manifest — `package.json`, `deno.json`,
246
+ * `jsr.json`); the legacy {@link PackageJsonSettings} alias remains exported for
247
+ * backward compatibility.
236
248
  */
237
- interface PackageJsonSettings {
249
+ interface ResolvedManifestSettings {
238
250
  /**
239
- * Infer CLI name from package.json `bin` keys or `name` field.
251
+ * Infer CLI name from manifest `bin` keys or `name` field.
240
252
  *
241
253
  * When `true`, the discovered name replaces the `cli(name)` value.
242
254
  * Explicit `.version()`/`.description()` calls still take precedence
@@ -245,15 +257,30 @@ interface PackageJsonSettings {
245
257
  * @defaultValue `false`
246
258
  */
247
259
  readonly inferName: boolean;
260
+ /**
261
+ * Strip a leading `@scope/` from the inferred `name` fallback.
262
+ *
263
+ * Only consulted when {@link ResolvedManifestSettings.inferName | `inferName`}
264
+ * is `true` and the name comes from the manifest `name` field (not a `bin`
265
+ * key, which is never scoped).
266
+ *
267
+ * @defaultValue `true`
268
+ */
269
+ readonly stripScope: boolean;
248
270
  /**
249
271
  * Explicit filesystem anchor for discovery; overrides `adapter.cwd`.
250
272
  *
251
- * Resolved to a string path before storage. When set, `discoverPackageJson`
273
+ * Resolved to a string path before storage. When set, `discoverManifest`
252
274
  * walks up from here instead of the runtime cwd. Required for installable
253
275
  * CLIs whose version should reflect THEIR OWN package, not the consumer's
254
276
  * working directory.
255
277
  */
256
278
  readonly from: string | undefined;
279
+ /**
280
+ * Candidate manifest filenames, in per-directory priority order
281
+ * (e.g. `['deno.json', 'deno.jsonc', 'jsr.json']` for `.denoJson()`).
282
+ */
283
+ readonly files: readonly string[];
257
284
  /**
258
285
  * Pre-loaded data; skips filesystem discovery, uses values verbatim.
259
286
  *
@@ -261,12 +288,22 @@ interface PackageJsonSettings {
261
288
  * ```ts
262
289
  * import pkg from './package.json' with { type: 'json' };
263
290
  *
264
- * cli('mycli').packageJson(pkg);
291
+ * cli('mycli').manifest(pkg);
265
292
  * ```
266
293
  */
267
294
  readonly data: PackageJsonData | undefined;
268
295
  }
269
296
 
297
+ /**
298
+ * Resolved manifest discovery settings stored in {@link CLISchema}.
299
+ *
300
+ * @deprecated Renamed to {@link ResolvedManifestSettings}. The stored shape
301
+ * holds generic manifest discovery config (`package.json`, `deno.json`,
302
+ * `jsr.json`), not just `package.json`; the misleading name is kept only for
303
+ * backward compatibility.
304
+ */
305
+ type PackageJsonSettings = ResolvedManifestSettings;
306
+
270
307
  // --- Options for execute/run
271
308
 
272
309
  /**
@@ -390,21 +427,21 @@ class CLIBuilder {
390
427
  * `options.help.hyperlinks`), and only in the header — usage lines, the
391
428
  * `--help` hint, the commands table, and completion scripts stay plain.
392
429
  *
393
- * URLs not provided here are derived from package.json metadata when
394
- * `.packageJson()` is active (works with both filesystem discovery and
430
+ * URLs not provided here are derived from manifest metadata when
431
+ * `.manifest()` is active (works with both filesystem discovery and
395
432
  * pre-loaded data):
396
433
  * - **name** → normalized `repository` URL, falling back to `homepage`
397
434
  * - **version** → forge release tag (`{repo}/releases/tag/v{version}` on
398
435
  * GitHub, `{repo}/-/releases/v{version}` on GitLab)
399
436
  *
400
- * @param links - Explicit URLs; omit to derive everything from package.json.
437
+ * @param links - Explicit URLs; omit to derive everything from the manifest.
401
438
  * @returns The builder (for chaining).
402
439
  *
403
440
  * @example
404
441
  * ```ts
405
- * // Derive both links from package.json repository/homepage:
442
+ * // Derive both links from the manifest repository/homepage:
406
443
  * cli('mycli')
407
- * .packageJson()
444
+ * .manifest()
408
445
  * .links()
409
446
  * .run();
410
447
  *
@@ -515,106 +552,130 @@ class CLIBuilder {
515
552
  }
516
553
 
517
554
  /**
518
- * Enable package.json metadata from pre-loaded data.
519
- *
520
- * Pass an already-imported `package.json` to skip filesystem discovery
521
- * entirely — useful for bundled or installable CLIs where the version
522
- * should be locked at build time. The data's `version`/`description` are
523
- * merged into the CLI schema immediately, so this form works in **both**
524
- * `.run()` and `.execute()` (the filesystem-free path). Explicit
525
- * `.version()`/`.description()` calls still take precedence, and the data
526
- * form does not infer the CLI name.
555
+ * Enable manifest metadata from pre-loaded data.
556
+ *
557
+ * Pass an already-imported manifest (`package.json`, `deno.json`, `jsr.json`)
558
+ * to skip filesystem discovery entirely — useful for bundled or installable
559
+ * CLIs where the version should be locked at build time. The data's
560
+ * `version`/`description` are merged into the CLI schema immediately, so this
561
+ * form works in **both** `.run()` and `.execute()` (the filesystem-free path).
562
+ * Explicit `.version()`/`.description()` calls still take precedence, and the
563
+ * data form does not infer the CLI name — `inferName` / `{ scope }` are
564
+ * available only on the discovery (settings) form. For a pre-loaded manifest
565
+ * whose scoped `name` should drive the CLI name, set the name explicitly via
566
+ * `cli(name)` (or call {@link inferCliName} on the data yourself).
527
567
  *
528
568
  * Detected by field shape: an object carrying at least one of
529
- * `name`/`version`/`description`/`bin`. An empty `{}` or a settings-shaped
530
- * object falls through to the settings overload.
569
+ * `name`/`version`/`description`/`bin`/`homepage`/`repository`. An empty `{}`
570
+ * or a settings-shaped object falls through to the settings overload.
531
571
  *
532
- * @param data - Pre-loaded `package.json` metadata.
572
+ * @param data - Pre-loaded manifest metadata.
533
573
  *
534
574
  * @example
535
575
  * ```ts
536
- * import pkg from './package.json' with { type: 'json' };
576
+ * import denoCfg from './deno.json' with { type: 'json' };
537
577
  *
538
578
  * // No filesystem; works in .run() AND .execute():
539
579
  * cli('mycli')
540
- * .packageJson(pkg)
580
+ * .manifest(denoCfg)
541
581
  * .command(deploy)
542
582
  * .run();
543
583
  * ```
544
584
  */
545
- packageJson(data: PackageJsonData): CLIBuilder;
585
+ manifest(data: PackageJsonData): CLIBuilder;
546
586
  /**
547
- * Enable automatic package.json metadata discovery.
587
+ * Enable automatic manifest metadata discovery.
588
+ *
589
+ * When enabled, `.run()` walks up from `cwd` (or {@link ManifestSettings.from})
590
+ * to find the nearest manifest among {@link ManifestSettings.files} and merges
591
+ * its `version`/`description` into the CLI schema. Explicit `.version()` /
592
+ * `.description()` calls always take precedence.
548
593
  *
549
- * When enabled, `.run()` walks up from `cwd` to find the nearest
550
- * `package.json` and merges its `version` and `description` fields
551
- * into the CLI schema. Explicit `.version()` and `.description()`
552
- * calls always take precedence over discovered values.
594
+ * Files are parsed as JSON with a JSONC fallback — `package.json`, `deno.json`,
595
+ * `jsr.json`, and `deno.jsonc` all qualify, including files with `//` / block
596
+ * comments or trailing commas. A file that fails both parses is skipped
597
+ * (discovery keeps walking).
553
598
  *
554
- * Has no effect in `.execute()` (which is filesystem-free by design) —
555
- * use the {@link CLIBuilder.packageJson | data overload} for that.
599
+ * Has no effect in `.execute()` (filesystem-free) — use the data overload.
556
600
  *
557
601
  * @param settings - Optional settings:
558
- * - `inferName`: also infer the CLI name from `bin` keys or `name` field.
559
- * - `from`: anchor discovery to a specific file/URL/path instead of `cwd`.
560
- * Pass `import.meta.url` for installable CLIs that need to report
561
- * THEIR OWN version (not the consumer's project version). Accepts
562
- * string paths, `file:` URL strings, or `URL` instances.
602
+ * - `files`: candidate manifest filenames in priority order
603
+ * (default `['package.json']`).
604
+ * - `inferName`: infer the CLI name from `bin` keys or `name`. Pass
605
+ * `{ scope: 'keep' }` to keep a leading `@scope/` (stripped by default).
606
+ * - `from`: anchor discovery to a file/URL/path instead of `cwd`. Pass
607
+ * `import.meta.url` for installable CLIs that must report THEIR OWN
608
+ * version. Accepts string paths, `file:` URL strings, or `URL` instances.
563
609
  *
564
610
  * @example
565
611
  * ```ts
566
- * // Auto-fill version + description from nearest package.json:
612
+ * // Deno CLI: discover OUR deno.json (then jsr.json), keep the scope in name:
567
613
  * cli('mycli')
568
- * .packageJson()
614
+ * .manifest({
615
+ * files: ['deno.json', 'jsr.json'],
616
+ * from: import.meta.url,
617
+ * inferName: { scope: 'keep' },
618
+ * })
569
619
  * .command(deploy)
570
620
  * .run();
621
+ * ```
622
+ */
623
+ manifest(settings?: ManifestSettings): CLIBuilder;
624
+ manifest(input?: PackageJsonData | ManifestSettings): CLIBuilder {
625
+ return new CLIBuilder(buildManifestSchema(this.schema, input, DEFAULT_MANIFEST_FILES, false));
626
+ }
627
+
628
+ /**
629
+ * Discover metadata from `package.json` (preset for {@link CLIBuilder.manifest}).
571
630
  *
572
- * // Also infer CLI name from bin key / package name:
573
- * cli('mycli')
574
- * .packageJson({ inferName: true })
575
- * .command(deploy)
576
- * .run();
631
+ * @deprecated Use {@link CLIBuilder.manifest} — `.manifest()` defaults to
632
+ * `package.json` and also supports `deno.json` / `jsr.json` via `files`.
577
633
  *
578
- * // Installable CLI; discover OUR package.json, not the consumer's:
579
- * cli('mycli')
580
- * .packageJson({ from: import.meta.url })
581
- * .command(deploy)
582
- * .run();
634
+ * @param data - Pre-loaded `package.json` metadata.
635
+ */
636
+ packageJson(data: PackageJsonData): CLIBuilder;
637
+ /**
638
+ * Discover metadata from `package.json` (preset for {@link CLIBuilder.manifest}).
639
+ *
640
+ * @deprecated Use {@link CLIBuilder.manifest}.
641
+ *
642
+ * @param settings - `inferName` / `from` (see {@link CLIBuilder.manifest}).
643
+ */
644
+ packageJson(settings?: ManifestPresetSettings): CLIBuilder;
645
+ packageJson(input?: PackageJsonData | ManifestPresetSettings): CLIBuilder {
646
+ return new CLIBuilder(buildManifestSchema(this.schema, input, DEFAULT_MANIFEST_FILES, true));
647
+ }
648
+
649
+ /**
650
+ * Discover metadata from `deno.json`, `deno.jsonc`, then `jsr.json` (preset for
651
+ * {@link CLIBuilder.manifest}).
652
+ *
653
+ * @deprecated Use `.manifest({ files: ['deno.json', 'deno.jsonc', 'jsr.json'] })`.
654
+ *
655
+ * @param data - Pre-loaded `deno.json` / `jsr.json` metadata.
656
+ */
657
+ denoJson(data: PackageJsonData): CLIBuilder;
658
+ /**
659
+ * Discover metadata from `deno.json`, `deno.jsonc`, then `jsr.json` (preset for
660
+ * {@link CLIBuilder.manifest}).
661
+ *
662
+ * @deprecated Use `.manifest({ files: ['deno.json', 'deno.jsonc', 'jsr.json'] })`.
583
663
  *
584
- * // Explicit values always win:
664
+ * @param settings - `inferName` / `from` (see {@link CLIBuilder.manifest}).
665
+ * `deno.json` / `jsr.json` have no `bin` field, so `inferName` resolves
666
+ * from `name`; pass `{ scope: 'keep' }` to retain a leading `@scope/`.
667
+ *
668
+ * @example
669
+ * ```ts
585
670
  * cli('mycli')
586
- * .packageJson()
587
- * .version('2.0.0-beta') // wins over package.json
671
+ * .denoJson({ from: import.meta.url })
672
+ * .command(deploy)
588
673
  * .run();
589
674
  * ```
590
675
  */
591
- packageJson(settings?: { readonly inferName?: boolean; readonly from?: string | URL }): CLIBuilder;
592
- packageJson(
593
- input?: PackageJsonData | { readonly inferName?: boolean; readonly from?: string | URL },
594
- ): CLIBuilder {
595
- if (isPackageJsonData(input)) {
596
- // Merge data into schema immediately so `.execute()` (which skips
597
- // runtime preflight) still picks up version/description. Explicit
598
- // `.version()`/`.description()` calls win, matching settings semantics.
599
- return new CLIBuilder({
600
- ...this.schema,
601
- ...(this.schema.version === undefined && input.version !== undefined
602
- ? { version: input.version }
603
- : {}),
604
- ...(this.schema.description === undefined && input.description !== undefined
605
- ? { description: input.description }
606
- : {}),
607
- packageJsonSettings: { inferName: false, from: undefined, data: input },
608
- });
609
- }
610
- return new CLIBuilder({
611
- ...this.schema,
612
- packageJsonSettings: {
613
- inferName: input?.inferName ?? false,
614
- from: normalizeFromSetting(input?.from),
615
- data: undefined,
616
- },
617
- });
676
+ denoJson(settings?: ManifestPresetSettings): CLIBuilder;
677
+ denoJson(input?: PackageJsonData | ManifestPresetSettings): CLIBuilder {
678
+ return new CLIBuilder(buildManifestSchema(this.schema, input, DENO_MANIFEST_FILES, true));
618
679
  }
619
680
 
620
681
  // -- Command registration ------------------------------------------------
@@ -1069,10 +1130,124 @@ function resolveHelpLinksSchema(schema: CLISchema): CLISchema {
1069
1130
  };
1070
1131
  }
1071
1132
 
1133
+ // --- manifest discovery settings
1134
+
1135
+ /** Default manifest filenames for `.manifest()` / `.packageJson()`. @internal */
1136
+ const DEFAULT_MANIFEST_FILES: readonly string[] = ['package.json'];
1137
+
1138
+ /** Manifest filenames for the `.denoJson()` preset, in priority order. @internal */
1139
+ const DENO_MANIFEST_FILES: readonly string[] = ['deno.json', 'deno.jsonc', 'jsr.json'];
1140
+
1141
+ /**
1142
+ * CLI-name inference control for {@link ManifestSettings.inferName}.
1143
+ *
1144
+ * - `false` (or omitted): do not infer the name.
1145
+ * - `true`: infer, stripping a leading `@scope/` from the `name` fallback.
1146
+ * - `{ scope: 'keep' }`: infer, keeping the full scoped name.
1147
+ * - `{ scope: 'strip' }`: infer, stripping the scope (explicit form of `true`).
1148
+ *
1149
+ * `scope` is required in the object form: an empty `{}` is rejected so that an
1150
+ * options object can never silently enable inference (use `true` for that).
1151
+ */
1152
+ type InferNameOption = boolean | { readonly scope: 'keep' | 'strip' };
1153
+
1154
+ /** Discovery settings accepted by {@link CLIBuilder.manifest}. */
1155
+ interface ManifestSettings {
1156
+ /** Infer the CLI name from `bin` keys or `name`. @defaultValue `false` */
1157
+ readonly inferName?: InferNameOption;
1158
+ /** Anchor discovery to a file/URL/path instead of `cwd`. */
1159
+ readonly from?: string | URL;
1160
+ /**
1161
+ * Candidate manifest filenames in priority order — NOT npm's `files` publish
1162
+ * globs. Discovery probes each name per directory and takes the first that
1163
+ * parses.
1164
+ *
1165
+ * @defaultValue `['package.json']`
1166
+ */
1167
+ readonly files?: readonly string[];
1168
+ }
1169
+
1170
+ /**
1171
+ * Discovery settings for the `.packageJson()` / `.denoJson()` presets (no `files`).
1172
+ *
1173
+ * @deprecated Both presets are deprecated; use {@link ManifestSettings} with
1174
+ * {@link CLIBuilder.manifest}.
1175
+ */
1176
+ type ManifestPresetSettings = Omit<ManifestSettings, 'files'>;
1177
+
1178
+ /**
1179
+ * Normalise an {@link InferNameOption} into the flat `{ inferName, stripScope }`
1180
+ * pair stored in {@link ResolvedManifestSettings}.
1181
+ *
1182
+ * @internal
1183
+ */
1184
+ function normalizeInferName(option: InferNameOption | undefined): {
1185
+ readonly inferName: boolean;
1186
+ readonly stripScope: boolean;
1187
+ } {
1188
+ if (option === undefined || option === false) return { inferName: false, stripScope: true };
1189
+ if (option === true) return { inferName: true, stripScope: true };
1190
+ return { inferName: true, stripScope: option.scope !== 'keep' };
1191
+ }
1192
+
1193
+ /**
1194
+ * Build the next {@link CLISchema} for a manifest builder method.
1195
+ *
1196
+ * Shared by {@link CLIBuilder.manifest}, {@link CLIBuilder.packageJson}, and
1197
+ * {@link CLIBuilder.denoJson}. The data overload (detected via field shape)
1198
+ * merges `version`/`description` immediately so `.execute()` sees them; the
1199
+ * settings overload stores discovery config for runtime preflight.
1200
+ *
1201
+ * @internal
1202
+ */
1203
+ function buildManifestSchema(
1204
+ schema: CLISchema,
1205
+ input: PackageJsonData | ManifestSettings | undefined,
1206
+ defaultFiles: readonly string[],
1207
+ pinFiles: boolean,
1208
+ ): CLISchema {
1209
+ if (isPackageJsonData(input)) {
1210
+ // Merge data into schema immediately so `.execute()` (which skips runtime
1211
+ // preflight) still picks up version/description. Explicit
1212
+ // `.version()`/`.description()` calls win, matching settings semantics.
1213
+ return {
1214
+ ...schema,
1215
+ ...(schema.version === undefined && input.version !== undefined
1216
+ ? { version: input.version }
1217
+ : {}),
1218
+ ...(schema.description === undefined && input.description !== undefined
1219
+ ? { description: input.description }
1220
+ : {}),
1221
+ packageJsonSettings: {
1222
+ inferName: false,
1223
+ stripScope: true,
1224
+ from: undefined,
1225
+ files: defaultFiles,
1226
+ data: input,
1227
+ },
1228
+ };
1229
+ }
1230
+ const { inferName, stripScope } = normalizeInferName(input?.inferName);
1231
+ // Presets (`pinFiles`) always use their fixed list: the `Omit<…,'files'>` guard
1232
+ // only stops fresh literals at compile time, so a `ManifestSettings`-typed
1233
+ // variable could otherwise leak `files` through the data-overload dispatch gap.
1234
+ const files = pinFiles ? defaultFiles : (input?.files ?? defaultFiles);
1235
+ return {
1236
+ ...schema,
1237
+ packageJsonSettings: {
1238
+ inferName,
1239
+ stripScope,
1240
+ from: normalizeFromSetting(input?.from),
1241
+ files,
1242
+ data: undefined,
1243
+ },
1244
+ };
1245
+ }
1246
+
1072
1247
  // --- packageJson.from normalisation
1073
1248
 
1074
1249
  /**
1075
- * Coerce a {@link PackageJsonSettings.from | `packageJson.from`} input
1250
+ * Coerce a {@link ResolvedManifestSettings.from | `manifest.from`} input
1076
1251
  * (string path, `file:` URL string, or {@link URL} instance) to a plain
1077
1252
  * filesystem path string. `undefined` passes through unchanged.
1078
1253
  *
@@ -1114,6 +1289,19 @@ function normalizeFromSetting(from: string | URL | undefined): string | undefine
1114
1289
  * `bin`, `homepage`, or `repository`). An empty `{}` or a settings-shaped
1115
1290
  * object (`inferName` / `from`) falls through to the settings overload.
1116
1291
  *
1292
+ * npm's `files` field (publish globs) is intentionally NOT recognised here, so
1293
+ * an object whose only key is `files` routes to the settings overload — where
1294
+ * `files` means candidate manifest filenames, never publish globs. Manifests
1295
+ * that publish a CLI carry `name`/`version`, so those route to the data overload
1296
+ * as expected.
1297
+ *
1298
+ * Edge case: a metadata-less manifest (e.g. a versionless private-root
1299
+ * `package.json` carrying only `files`/`private`) routes to settings, so its
1300
+ * `files` would be read as candidate filenames and the object is not stored as
1301
+ * data. This is harmless in practice — a metadata-less manifest contributes no
1302
+ * `version`/`description` either way — but it means a pre-loaded object must
1303
+ * carry real metadata to be honoured as data.
1304
+ *
1117
1305
  * @internal
1118
1306
  */
1119
1307
  function isPackageJsonData(value: unknown): value is PackageJsonData {
@@ -1211,5 +1399,15 @@ export type {
1211
1399
  PluginCommandContext,
1212
1400
  ResolvedCommandParams,
1213
1401
  } from './plugin.ts';
1214
- export type { CLIOptions, CLIRunOptions, CLISchema, ConfigSettings, PackageJsonSettings };
1402
+ export type {
1403
+ CLIOptions,
1404
+ CLIRunOptions,
1405
+ CLISchema,
1406
+ ConfigSettings,
1407
+ InferNameOption,
1408
+ ManifestPresetSettings,
1409
+ ManifestSettings,
1410
+ PackageJsonSettings,
1411
+ ResolvedManifestSettings,
1412
+ };
1215
1413
  export { CLIBuilder, cli, formatRootHelp, plugin };
@@ -12,7 +12,7 @@
12
12
  import type { FormatLoader } from '#internals/core/config/index.ts';
13
13
  import { discoverConfig } from '#internals/core/config/index.ts';
14
14
  import type { PackageJsonData } from '#internals/core/config/package-json.ts';
15
- import { discoverPackageJson, inferCliName } from '#internals/core/config/package-json.ts';
15
+ import { discoverManifest, inferCliName } from '#internals/core/config/package-json.ts';
16
16
  import { CLIError, ParseError } from '#internals/core/errors/index.ts';
17
17
  import type { Verbosity } from '#internals/core/output/index.ts';
18
18
  import { parse } from '#internals/core/parse/index.ts';
@@ -33,12 +33,23 @@ interface RuntimeConfigSettings {
33
33
  readonly loaders: readonly FormatLoader[] | undefined;
34
34
  }
35
35
 
36
- /** Package.json discovery settings extracted from CLISchema. @internal */
37
- interface RuntimePackageJsonSettings {
38
- /** Whether to infer the CLI binary name from `package.json` `bin` field. */
36
+ /**
37
+ * Manifest discovery settings extracted from CLISchema for preflight use.
38
+ *
39
+ * Mirrors the public `ResolvedManifestSettings` shape (consumed structurally),
40
+ * named with the `Runtime` prefix to match its {@link RuntimeConfigSettings}
41
+ * sibling and avoid colliding with the exported public type.
42
+ * @internal
43
+ */
44
+ interface RuntimeManifestSettings {
45
+ /** Whether to infer the CLI binary name from `bin` keys or `name`. */
39
46
  readonly inferName: boolean;
47
+ /** Strip a leading `@scope/` from the inferred `name` fallback. */
48
+ readonly stripScope: boolean;
40
49
  /** Explicit anchor (resolved path) for discovery; `undefined` falls back to `adapter.cwd`. */
41
50
  readonly from: string | undefined;
51
+ /** Candidate manifest filenames in priority order. */
52
+ readonly files: readonly string[];
42
53
  /** Pre-loaded data; when set, discovery is skipped entirely. */
43
54
  readonly data: PackageJsonData | undefined;
44
55
  }
@@ -66,7 +77,7 @@ interface RuntimePreflightSchemaLike {
66
77
  /** Config file discovery settings; `undefined` disables config loading. */
67
78
  readonly configSettings: RuntimeConfigSettings | undefined;
68
79
  /** Package.json discovery settings; `undefined` disables package.json inference. */
69
- readonly packageJsonSettings: RuntimePackageJsonSettings | undefined;
80
+ readonly packageJsonSettings: RuntimeManifestSettings | undefined;
70
81
  /** Root-help header link targets; `undefined` fields may be derived from package.json. */
71
82
  readonly helpLinks: HelpLinks | undefined;
72
83
  /** Whether `.completions()` registered the built-in completions command. */
@@ -287,10 +298,16 @@ async function applyPackageJsonDiscovery(
287
298
  ? await (async (): Promise<RuntimePreflightSchemaLike> => {
288
299
  // Pre-loaded data short-circuits filesystem discovery entirely.
289
300
  const pkg =
290
- packageJsonSettings.data ?? (await discoverPackageJson(adapter, packageJsonSettings.from));
301
+ packageJsonSettings.data ??
302
+ (await discoverManifest(adapter, {
303
+ ...(packageJsonSettings.from !== undefined ? { startDir: packageJsonSettings.from } : {}),
304
+ files: packageJsonSettings.files,
305
+ }));
291
306
  if (pkg === null) return schema;
292
307
 
293
- const inferredName = packageJsonSettings.inferName ? inferCliName(pkg) : undefined;
308
+ const inferredName = packageJsonSettings.inferName
309
+ ? inferCliName(pkg, { stripScope: packageJsonSettings.stripScope })
310
+ : undefined;
294
311
  return {
295
312
  ...schema,
296
313
  ...(schema.version === undefined && pkg.version !== undefined
@@ -394,8 +394,18 @@ function configFormat(
394
394
 
395
395
  // --- Exports
396
396
 
397
- export type { PackageJsonAdapter, PackageJsonData, PackageRepository } from './package-json.ts';
398
- export { discoverPackageJson, inferCliName, packageRepositoryUrl } from './package-json.ts';
397
+ export type {
398
+ ManifestDiscoveryOptions,
399
+ PackageJsonAdapter,
400
+ PackageJsonData,
401
+ PackageRepository,
402
+ } from './package-json.ts';
403
+ export {
404
+ discoverManifest,
405
+ discoverPackageJson,
406
+ inferCliName,
407
+ packageRepositoryUrl,
408
+ } from './package-json.ts';
399
409
  export type {
400
410
  ConfigAdapter,
401
411
  ConfigDiscoveryOptions,