@kjanat/dreamcli 3.0.1 → 4.0.0-rc.1

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 (137) hide show
  1. package/CHANGELOG.md +951 -1
  2. package/README.md +7 -3
  3. package/dist/core/cli/builtins.d.mts +47 -0
  4. package/dist/core/cli/builtins.mjs +135 -0
  5. package/dist/core/cli/compiled.d.mts +29 -0
  6. package/dist/core/cli/compiled.mjs +76 -0
  7. package/dist/core/cli/dispatch.d.mts +9 -85
  8. package/dist/core/cli/help-links.d.mts +2 -14
  9. package/dist/core/cli/index.d.mts +282 -101
  10. package/dist/core/cli/index.mjs +497 -264
  11. package/dist/core/cli/planner.d.mts +13 -86
  12. package/dist/core/cli/planner.mjs +47 -30
  13. package/dist/core/cli/plugin.d.mts +1 -1
  14. package/dist/core/cli/propagate.mjs +1 -1
  15. package/dist/core/cli/reserved-flags.d.mts +1 -0
  16. package/dist/core/cli/reserved-flags.mjs +158 -0
  17. package/dist/core/cli/root-help.d.mts +1 -47
  18. package/dist/core/cli/root-help.mjs +37 -47
  19. package/dist/core/cli/root-output-flags.d.mts +1 -0
  20. package/dist/core/cli/root-output-flags.mjs +169 -0
  21. package/dist/core/cli/root-surface.d.mts +1 -68
  22. package/dist/core/cli/root-surface.mjs +2 -2
  23. package/dist/core/cli/runtime-preflight.d.mts +1 -199
  24. package/dist/core/cli/runtime-preflight.mjs +67 -17
  25. package/dist/core/completion/index.d.mts +2 -2
  26. package/dist/core/completion/shells/bash.d.mts +0 -1
  27. package/dist/core/completion/shells/bash.mjs +2 -1
  28. package/dist/core/completion/shells/fish.d.mts +0 -1
  29. package/dist/core/completion/shells/fish.mjs +2 -1
  30. package/dist/core/completion/shells/powershell.d.mts +0 -1
  31. package/dist/core/completion/shells/powershell.mjs +2 -1
  32. package/dist/core/completion/shells/shared.d.mts +3 -114
  33. package/dist/core/completion/shells/shared.mjs +9 -39
  34. package/dist/core/completion/shells/zsh.d.mts +0 -1
  35. package/dist/core/completion/shells/zsh.mjs +2 -1
  36. package/dist/core/config/index.d.mts +3 -3
  37. package/dist/core/config/index.mjs +2 -2
  38. package/dist/core/config/package-json.d.mts +2 -33
  39. package/dist/core/config/package-json.mjs +1 -34
  40. package/dist/core/errors/index.d.mts +7 -7
  41. package/dist/core/execution/index.d.mts +1 -48
  42. package/dist/core/execution/index.mjs +42 -27
  43. package/dist/core/help/ansi.d.mts +0 -11
  44. package/dist/core/help/index.d.mts +3 -35
  45. package/dist/core/help/index.mjs +29 -6
  46. package/dist/core/help/theme.d.mts +1 -21
  47. package/dist/core/json-schema/index.d.mts +279 -10
  48. package/dist/core/json-schema/index.mjs +482 -237
  49. package/dist/core/json-schema/meta-descriptions.generated.d.mts +79 -7
  50. package/dist/core/json-schema/meta-descriptions.generated.mjs +40 -6
  51. package/dist/core/output/activity.d.mts +1 -193
  52. package/dist/core/output/activity.mjs +1 -1
  53. package/dist/core/output/bind.d.mts +1 -37
  54. package/dist/core/output/contracts.d.mts +7 -13
  55. package/dist/core/output/contracts.mjs +1 -1
  56. package/dist/core/output/display-value.d.mts +1 -19
  57. package/dist/core/output/index.d.mts +5 -187
  58. package/dist/core/output/index.mjs +44 -9
  59. package/dist/core/output/renderers.d.mts +1 -45
  60. package/dist/core/output/writer.d.mts +0 -1
  61. package/dist/core/parse/index.d.mts +27 -5
  62. package/dist/core/parse/index.mjs +350 -227
  63. package/dist/core/parse/occurrences.d.mts +89 -0
  64. package/dist/core/parse/occurrences.mjs +114 -0
  65. package/dist/core/prompt/index.d.mts +3 -3
  66. package/dist/core/read-flags/index.d.mts +150 -0
  67. package/dist/core/read-flags/index.mjs +217 -0
  68. package/dist/core/resolve/args.d.mts +35 -4
  69. package/dist/core/resolve/args.mjs +132 -55
  70. package/dist/core/resolve/coerce.d.mts +66 -9
  71. package/dist/core/resolve/coerce.mjs +834 -270
  72. package/dist/core/resolve/config.d.mts +1 -10
  73. package/dist/core/resolve/contracts.d.mts +67 -44
  74. package/dist/core/resolve/errors.mjs +29 -21
  75. package/dist/core/resolve/flags.d.mts +36 -9
  76. package/dist/core/resolve/flags.mjs +129 -151
  77. package/dist/core/resolve/index.d.mts +8 -6
  78. package/dist/core/resolve/index.mjs +51 -18
  79. package/dist/core/resolve/path-checks.d.mts +47 -0
  80. package/dist/core/resolve/path-checks.mjs +102 -0
  81. package/dist/core/resolve/redaction.d.mts +12 -0
  82. package/dist/core/resolve/redaction.mjs +14 -0
  83. package/dist/core/resolve/stages.d.mts +85 -0
  84. package/dist/core/resolve/stages.mjs +170 -0
  85. package/dist/core/resolve/standard.d.mts +1 -24
  86. package/dist/core/resolve/standard.mjs +141 -43
  87. package/dist/core/schema/activity.d.mts +16 -16
  88. package/dist/core/schema/arg.d.mts +849 -71
  89. package/dist/core/schema/arg.mjs +727 -54
  90. package/dist/core/schema/brand.d.mts +17 -0
  91. package/dist/core/schema/cardinality.d.mts +301 -0
  92. package/dist/core/schema/cardinality.mjs +514 -0
  93. package/dist/core/schema/command.d.mts +181 -112
  94. package/dist/core/schema/command.mjs +305 -42
  95. package/dist/core/schema/flag.d.mts +515 -173
  96. package/dist/core/schema/flag.mjs +576 -78
  97. package/dist/core/schema/index.d.mts +11 -8
  98. package/dist/core/schema/index.mjs +10 -0
  99. package/dist/core/schema/middleware.d.mts +15 -12
  100. package/dist/core/schema/number-constraints.d.mts +5 -5
  101. package/dist/core/schema/prompt.d.mts +4 -4
  102. package/dist/core/schema/provenance.d.mts +99 -0
  103. package/dist/core/schema/provenance.mjs +28 -0
  104. package/dist/core/schema/run.d.mts +21 -60
  105. package/dist/core/schema/source.d.mts +179 -0
  106. package/dist/core/schema/source.mjs +206 -0
  107. package/dist/core/schema/standard.d.mts +12 -19
  108. package/dist/core/schema/stdin.d.mts +87 -0
  109. package/dist/core/schema/stdin.mjs +91 -0
  110. package/dist/core/schema/string-constraints.d.mts +16 -5
  111. package/dist/core/schema/string-constraints.mjs +18 -1
  112. package/dist/core/schema/value-parsers.d.mts +81 -9
  113. package/dist/core/schema/value-parsers.mjs +19 -1
  114. package/dist/core/schema/value.d.mts +242 -0
  115. package/dist/core/schema/value.mjs +573 -0
  116. package/dist/core/testkit/index.d.mts +28 -3
  117. package/dist/core/testkit/index.mjs +40 -26
  118. package/dist/index.d.mts +21 -16
  119. package/dist/index.mjs +10 -6
  120. package/dist/runtime/adapter.d.mts +3 -3
  121. package/dist/runtime/deno.d.mts +3 -3
  122. package/dist/runtime/detect.d.mts +2 -2
  123. package/dist/runtime/node.d.mts +3 -3
  124. package/dist/runtime/paths.d.mts +1 -31
  125. package/dist/runtime.d.mts +4 -4
  126. package/dist/strings.d.mts +1 -16
  127. package/dist/testkit.d.mts +2 -2
  128. package/dist/testkit.mjs +1 -1
  129. package/dist/version.d.mts +0 -13
  130. package/dist/version.mjs +2 -2
  131. package/dreamcli.schema.json +368 -78
  132. package/examples/interactive.ts +6 -5
  133. package/package.json +9 -9
  134. package/skills/cli-creation/SKILL.md +72 -16
  135. package/skills/cli-creation/references/pattern-cookbook.md +169 -11
  136. package/dist/core/resolve/property.d.mts +0 -51
  137. package/dist/core/resolve/property.mjs +0 -53
@@ -1,27 +1,32 @@
1
- import { ArgBuilder, ArgConfig } from "../schema/arg.mjs";
1
+ import { schemaBrand } from "../schema/brand.mjs";
2
+ import { BuiltinMode, BuiltinName, Builtins, BuiltinsConfig } from "./builtins.mjs";
3
+ import { Verbosity } from "../output/contracts.mjs";
2
4
  import { FlagBuilder, FlagConfig } from "../schema/flag.mjs";
3
- import { BeforeParseParams, CLIPlugin, CLIPluginHooks, PluginCommandContext, ResolvedCommandParams, plugin } from "./plugin.mjs";
5
+ import { ArgBuilder, ArgConfig } from "../schema/arg.mjs";
6
+ import { CommandBuilder, CommandDefinition, CommandSchema } from "../schema/command.mjs";
4
7
  import { HelpThemeFactory } from "../help/theme.mjs";
5
8
  import "../help/index.mjs";
9
+ import "../output/index.mjs";
6
10
  import { RunOptions, RunResult } from "../schema/run.mjs";
7
- import { CommandBuilder, ErasedCommand } from "../schema/command.mjs";
8
11
  import { ParseOptions } from "../parse/index.mjs";
9
- import { RuntimeAdapter } from "../../runtime/adapter.mjs";
10
- import { PackageJsonData } from "../config/package-json.mjs";
12
+ import { BeforeParseParams, CLIPlugin, CLIPluginHooks, PluginCommandContext, ResolvedCommandParams, plugin } from "./plugin.mjs";
11
13
  import { HelpLinks } from "./help-links.mjs";
12
14
  import { CompletionOptions } from "../completion/shells/shared.mjs";
13
15
  import { Shell } from "../completion/index.mjs";
16
+ import { RuntimeAdapter } from "../../runtime/adapter.mjs";
17
+ import { PackageJsonData } from "../config/package-json.mjs";
14
18
  import { FormatLoader } from "../config/index.mjs";
15
- import { formatRootHelp } from "./root-help.mjs";
16
19
  import { Colors } from "ansispeck";
17
20
  //#region src/core/cli/index.d.ts
18
21
  /**
19
22
  * Runtime descriptor for the CLI program.
20
23
  *
21
- * Stores the program name, version, description, and registered commands.\
22
- * Built incrementally by {@linkcode CLIBuilder}.
24
+ * Stores the program name, version, description, and registered command schemas.\
25
+ * Sealed by {@linkcode createCLISchema} and rebuilt by each {@linkcode CLIBuilder} step.
23
26
  */
24
27
  interface CLISchema {
28
+ /** Type-only seal produced by {@link createCLISchema}. */
29
+ readonly [schemaBrand]: "cli";
25
30
  /** Program name (used in help text, usage lines, and completion scripts). */
26
31
  readonly name: string;
27
32
  /**
@@ -34,18 +39,19 @@ interface CLISchema {
34
39
  readonly version: string | undefined;
35
40
  /** Program description (shown in root help). */
36
41
  readonly description: string | undefined;
37
- /** Registered commands (type-erased for heterogeneous storage). */
38
- readonly commands: readonly ErasedCommand[];
42
+ /** Schemas of the registered commands, in registration order. */
43
+ readonly commands: readonly CommandSchema[];
39
44
  /**
40
- * Default command dispatched when no subcommand matches.
45
+ * Schema of the default command dispatched when no subcommand matches.
41
46
  *
42
47
  * When set, the CLI root behaves like a hybrid command group: subcommands
43
48
  * dispatch by name as usual, but empty argv or flags-only argv falls
44
49
  * through to this command instead of showing root help.
45
50
  *
46
- * Set via the {@linkcode CLIBuilder.default | .default()} builder method.
51
+ * Set via the {@linkcode CLIBuilder.default | .default()} builder method
52
+ * or the `defaultCommand` field of {@link CLIDefinition}.
47
53
  */
48
- readonly defaultCommand: ErasedCommand | undefined;
54
+ readonly defaultCommand: CommandSchema | undefined;
49
55
  /**
50
56
  * Whether the default command is also exposed as a named top-level route.
51
57
  *
@@ -68,9 +74,7 @@ interface CLISchema {
68
74
  * nearest manifest (`package.json`, `deno.json`, `jsr.json`, …) and merges
69
75
  * metadata before dispatch.
70
76
  *
71
- * Set via the {@linkcode CLIBuilder.manifest | .manifest()} builder method
72
- * (or the {@linkcode CLIBuilder.packageJson | .packageJson()} /
73
- * {@linkcode CLIBuilder.denoJson | .denoJson()} presets).
77
+ * Set via the {@linkcode CLIBuilder.manifest | .manifest()} builder method.
74
78
  */
75
79
  readonly packageJsonSettings: ResolvedManifestSettings | undefined;
76
80
  /**
@@ -106,15 +110,21 @@ interface CLISchema {
106
110
  * Set via the `cli(name, { flags })` / `cli({ flags })` factory forms.
107
111
  */
108
112
  readonly flagSettings: ParseOptions | undefined;
109
- /** Registered CLI plugins. */
110
- readonly plugins: readonly CLIPlugin[];
113
+ /**
114
+ * Which built-in flags the root still owns.
115
+ *
116
+ * Every built-in starts `'on'`. Set via the
117
+ * {@linkcode CLIBuilder.builtins | .builtins()} builder method or the
118
+ * `builtins` field of {@link CLIDefinition}; a built-in set to `'off'`
119
+ * releases its tokens to the commands.
120
+ */
121
+ readonly builtins: Builtins;
111
122
  }
112
123
  /**
113
124
  * Configuration for the eager `--completions <shell>` flag.
114
125
  *
115
126
  * Stored in {@link CLISchema} when `.completions({ as: 'flag' })` is used.
116
127
  *
117
- * @internal
118
128
  */
119
129
  interface CompletionsFlagConfig {
120
130
  /** Shell targets the flag accepts (mirrors {@link SHELLS}). */
@@ -164,7 +174,7 @@ interface HelpConfig {
164
174
  *
165
175
  * @defaultValue `'alphabetical'`
166
176
  */
167
- readonly flagOrder?: 'alphabetical' | 'declaration';
177
+ readonly flagOrder?: "alphabetical" | "declaration";
168
178
  /**
169
179
  * Custom comparator over flag long names for the `Flags:` table. When set,
170
180
  * it wins over {@link HelpConfig.flagOrder}.
@@ -191,6 +201,8 @@ interface HelpConfig {
191
201
  * {@link discoverConfig} before dispatching to a command.
192
202
  */
193
203
  interface ConfigSettings {
204
+ /** Type-only seal produced by {@link createCLISchema}. */
205
+ readonly [schemaBrand]: "config";
194
206
  /**
195
207
  * Application name used to build config search paths.
196
208
  *
@@ -212,10 +224,9 @@ interface ConfigSettings {
212
224
  *
213
225
  * Note: the schema FIELD name (`packageJsonSettings`) keeps its `packageJson`
214
226
  * prefix for backward compatibility — renaming it would break consumers reading
215
- * `app.schema.packageJsonSettings`. The type itself is now generically named
216
- * (it holds discovery config for any manifest — `package.json`, `deno.json`,
217
- * `jsr.json`); the legacy {@link PackageJsonSettings} alias remains exported for
218
- * backward compatibility.
227
+ * `app.schema.packageJsonSettings`. The type itself is generically named (it
228
+ * holds discovery config for any manifest — `package.json`, `deno.json`,
229
+ * `jsr.json`).
219
230
  */
220
231
  interface ResolvedManifestSettings {
221
232
  /**
@@ -249,7 +260,7 @@ interface ResolvedManifestSettings {
249
260
  readonly from: string | undefined;
250
261
  /**
251
262
  * Candidate manifest filenames, in per-directory priority order
252
- * (e.g. `['deno.json', 'deno.jsonc', 'jsr.json']` for `.denoJson()`).
263
+ * (e.g. `['deno.json', 'deno.jsonc', 'jsr.json']` for a Deno CLI).
253
264
  */
254
265
  readonly files: readonly string[];
255
266
  /**
@@ -265,26 +276,159 @@ interface ResolvedManifestSettings {
265
276
  readonly data: PackageJsonData | undefined;
266
277
  }
267
278
  /**
268
- * Resolved manifest discovery settings stored in {@link CLISchema}.
279
+ * Input shape for {@link CLISchema.configSettings}, accepted by
280
+ * {@link createCLISchema}.
269
281
  *
270
- * @deprecated Renamed to {@link ResolvedManifestSettings}. The stored shape
271
- * holds generic manifest discovery config (`package.json`, `deno.json`,
272
- * `jsr.json`), not just `package.json`; the misleading name is kept only for
273
- * backward compatibility.
282
+ * Mirrors {@link ConfigSettings} with `loaders` optional.
274
283
  */
275
- type PackageJsonSettings = ResolvedManifestSettings;
284
+ interface ConfigSettingsDefinition {
285
+ /** Application name used to build config search paths. */
286
+ readonly appName: string;
287
+ /**
288
+ * Additional format loaders beyond the built-in JSON loader.
289
+ * @defaultValue `undefined`
290
+ */
291
+ readonly loaders?: readonly FormatLoader[] | undefined;
292
+ }
276
293
  /**
277
- * Options for {@linkcode CLIBuilder.execute | .execute()} and {@linkcode CLIBuilder.run | .run()}.
294
+ * Input shape accepted by {@link createCLISchema}.
278
295
  *
279
- * Derives from {@linkcode RunOptions} while excluding command-execution internals
280
- * (`meta`, `mergedSchema`) and adding the CLI-level runtime adapter.
296
+ * Every field except `name` is optional. Commands accept either
297
+ * {@link CommandDefinition | definitions} or already-built
298
+ * {@link CommandSchema | schemas}. Plugins are execution state and have no
299
+ * definition field.
281
300
  */
282
- interface CLIRunOptions extends Omit<RunOptions, 'meta' | 'mergedSchema'> {
301
+ interface CLIDefinition {
302
+ /** Program name used in help text, usage lines, and completion scripts. */
303
+ readonly name: string;
304
+ /**
305
+ * Whether `.run()` should replace `name` with the invoked program name.
306
+ * @defaultValue `false`
307
+ */
308
+ readonly inheritName?: boolean | undefined;
309
+ /**
310
+ * Program version shown by `--version`.
311
+ * @defaultValue `undefined`
312
+ */
313
+ readonly version?: string | undefined;
314
+ /**
315
+ * Program description shown in root help.
316
+ * @defaultValue `undefined`
317
+ */
318
+ readonly description?: string | undefined;
319
+ /**
320
+ * Whether the default command is also exposed as a named top-level route.
321
+ * @defaultValue `false`
322
+ */
323
+ readonly defaultCommandRouted?: boolean | undefined;
324
+ /**
325
+ * Config discovery settings, as a definition or an already-built value.
326
+ * @defaultValue `undefined`
327
+ */
328
+ readonly configSettings?: ConfigSettingsDefinition | ConfigSettings | undefined;
329
+ /**
330
+ * Manifest auto-discovery settings.
331
+ * @defaultValue `undefined`
332
+ */
333
+ readonly packageJsonSettings?: ResolvedManifestSettings | undefined;
334
+ /**
335
+ * OSC 8 hyperlink targets for the root-help header.
336
+ * @defaultValue `undefined`
337
+ */
338
+ readonly helpLinks?: HelpLinks | undefined;
339
+ /**
340
+ * Whether built-in `.completions()` registration is active.
341
+ * @defaultValue `false`
342
+ */
343
+ readonly hasBuiltInCompletions?: boolean | undefined;
344
+ /**
345
+ * Eager `--completions <shell>` flag configuration.
346
+ * @defaultValue `undefined`
347
+ */
348
+ readonly completionsFlag?: CompletionsFlagConfig | undefined;
349
+ /**
350
+ * Consumer-configured root-help defaults.
351
+ * @defaultValue `undefined`
352
+ */
353
+ readonly helpConfig?: HelpConfig | undefined;
354
+ /**
355
+ * Flag-parsing behavior settings.
356
+ * @defaultValue `undefined`
357
+ */
358
+ readonly flagSettings?: ParseOptions | undefined;
359
+ /**
360
+ * Which built-in flags the root keeps.
361
+ * @defaultValue every built-in `'on'`
362
+ */
363
+ readonly builtins?: BuiltinsConfig | undefined;
364
+ /**
365
+ * Registered command definitions or built schemas, in registration order.
366
+ * @defaultValue `[]`
367
+ */
368
+ readonly commands?: readonly (CommandDefinition | CommandSchema)[] | undefined;
369
+ /**
370
+ * Default command dispatched when no subcommand matches.
371
+ * @defaultValue `undefined`
372
+ */
373
+ readonly defaultCommand?: CommandDefinition | CommandSchema | undefined;
374
+ }
375
+ /**
376
+ * Create a {@link CLISchema} from a plain definition object.
377
+ *
378
+ * Most consumers should prefer {@link cli | cli()}, which returns a
379
+ * {@link CLIBuilder} carrying the execution graph. `createCLISchema()` builds a
380
+ * description only: it normalizes commands recursively through
381
+ * {@link createCommandSchema}, so handlers and execution steps are not part of
382
+ * the result and the schema cannot be executed.
383
+ *
384
+ * Feeding a built schema back in produces a deep-equal schema.
385
+ *
386
+ * @param definition - Program name plus optional metadata and commands.
387
+ * @returns A fully populated {@link CLISchema}.
388
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` when the program name is
389
+ * empty, a `builtins` entry is neither `'on'` nor `'off'`, a command name at
390
+ * any depth is empty, a flag or arg at any depth is named `__proto__`, or a
391
+ * flag record at any depth has a replaced prototype.
392
+ * @throws {CLIError} With code `'FLAG_NAME_COLLISION'` when two flags on one
393
+ * command share a spelling, at any depth of the command tree.
394
+ * @throws {CLIError} With code `'PROPAGATED_FLAG_COLLISION'` when a command flag
395
+ * shadows a spelling propagated from an ancestor command.
396
+ * @throws {CLIError} With code `'INVALID_BUILDER_STATE'` when a positional comes
397
+ * after a variadic one, or `'DUPLICATE_STDIN_INPUT'` when two inputs on one
398
+ * command consume stdin and either is exclusive.
399
+ * @throws {CLIError} With code `'RESERVED_FLAG'` when a command spells a flag
400
+ * the same way as a root-owned flag (`--json`, `--quiet`/`-q`, `--help`/`-h`,
401
+ * `--version`/`-V` once `version` is set, and `--completions` once
402
+ * `completionsFlag` is set), by name, alias, or negated spelling. A built-in
403
+ * set to `'off'` in `builtins` is not reserved.
404
+ *
405
+ * @example
406
+ * ```ts
407
+ * const schema = createCLISchema({
408
+ * name: 'mycli',
409
+ * version: '1.0.0',
410
+ * commands: [{ name: 'deploy', flags: { force: { kind: 'boolean' } } }],
411
+ * });
412
+ * ```
413
+ */
414
+ declare function createCLISchema(definition: CLIDefinition): CLISchema;
415
+ /**
416
+ * Options for {@linkcode CLIBuilder.execute | .execute()}, the process-free
417
+ * execution surface.
418
+ *
419
+ * Derives from {@linkcode RunOptions} with every input injected explicitly.
420
+ */
421
+ interface CLIExecuteOptions extends RunOptions {}
422
+ /**
423
+ * Options for {@linkcode CLIBuilder.run | .run()}.
424
+ *
425
+ * Derives from {@linkcode CLIExecuteOptions}, adding the CLI-level runtime adapter.
426
+ */
427
+ interface CLIRunOptions extends CLIExecuteOptions {
283
428
  /**
284
429
  * Runtime adapter providing platform-specific I/O, argv, env, etc.
285
430
  *
286
- * When provided to `.run()`, replaces the default Node adapter.
287
- * Ignored by `.execute()` (which is process-free by design).
431
+ * Replaces the default Node adapter.
288
432
  */
289
433
  readonly adapter?: RuntimeAdapter;
290
434
  }
@@ -301,11 +445,20 @@ interface RenderContextOptions {
301
445
  */
302
446
  readonly isTTY?: boolean;
303
447
  /**
304
- * Force JSON mode on regardless of argv.
448
+ * JSON mode when argv carries no root `--json`. An explicit `--json=false`
449
+ * in argv wins over this.
305
450
  *
306
451
  * @defaultValue detected from a pre-separator `--json` in `argv`
307
452
  */
308
453
  readonly jsonMode?: boolean;
454
+ /**
455
+ * Output verbosity when argv carries no root `--quiet`/`-q`. An explicit
456
+ * `--quiet=false` in argv wins over this.
457
+ *
458
+ * @defaultValue detected from a pre-separator `--quiet`/`-q` in `argv`,
459
+ * otherwise `'normal'`
460
+ */
461
+ readonly verbosity?: Verbosity;
309
462
  /**
310
463
  * Explicitly enable or disable colors, winning over the auto-gate.
311
464
  *
@@ -319,14 +472,30 @@ interface RenderContextOptions {
319
472
  * @defaultValue `{}`
320
473
  */
321
474
  readonly env?: Readonly<Record<string, string | undefined>>;
475
+ /**
476
+ * Which built-in flags the CLI still owns, matching its
477
+ * {@linkcode CLIBuilder.builtins | .builtins()} call. A built-in set to
478
+ * `'off'` is not read out of `argv` here either.
479
+ *
480
+ * @defaultValue every built-in `'on'`
481
+ */
482
+ readonly builtins?: BuiltinsConfig;
322
483
  }
323
484
  /**
324
485
  * The output decisions the framework will make for a given argv, resolved
325
486
  * before `.run()`.
487
+ *
488
+ * `RenderContext` is a framework-created, non-exhaustive value: obtain
489
+ * instances from {@linkcode resolveRenderContext} — do not implement it. New
490
+ * readonly members may be added in minor releases.
326
491
  */
327
492
  interface RenderContext {
493
+ /** Framework-construction seal. Obtain values from `resolveRenderContext()`; do not implement this interface. */
494
+ readonly [renderContextBrand]: never;
328
495
  /** Whether a pre-separator `--json` puts the run in JSON mode. */
329
496
  readonly jsonMode: boolean;
497
+ /** Active verbosity after pre-separator `--quiet`/`-q` detection. */
498
+ readonly verbosity: Verbosity;
330
499
  /** The TTY status the output channel will carry. */
331
500
  readonly isTTY: boolean;
332
501
  /**
@@ -415,17 +584,60 @@ interface DefaultCommandOptions {
415
584
  * ```
416
585
  */
417
586
  declare class CLIBuilder {
418
- /** @internal Runtime schema descriptor. */
419
- readonly schema: CLISchema;
420
- /** Build a CLIBuilder from a pre-constructed schema descriptor. */
421
- constructor(schema: CLISchema);
587
+ private constructor();
422
588
  /**
423
589
  * Set the program version (shown by `--version`).
424
590
  *
591
+ * Declaring a version also reserves `--version`/`-V` on every registered
592
+ * command, so this rejects a command that already declares either spelling.
593
+ *
425
594
  * @param v - Semantic version string.
426
595
  * @returns The builder (for chaining).
596
+ * @throws {@link CLIError} `RESERVED_FLAG` when a registered command spells
597
+ * `--version` or `-V` as a flag name, an alias, or a negated spelling.
427
598
  */
428
599
  version(v: string): CLIBuilder;
600
+ /**
601
+ * Choose which built-in flags the root keeps.
602
+ *
603
+ * `--help`/`-h`, `--json`, and `--quiet`/`-q` are root-owned by default and
604
+ * never reach a command handler. Setting one to `'off'` releases every
605
+ * spelling it answers to: the root stops reading it out of argv, root help
606
+ * stops advertising it under `Global options:`, and a command may declare it
607
+ * as an ordinary flag. `RunOptions.jsonMode` and `RunOptions.verbosity`
608
+ * keep working either way, since only argv-driven activation is disabled.
609
+ *
610
+ * `version` and `completions` are absent by design, since `.version()` and
611
+ * `.completions()` are opt-in and a CLI declines those by omission.
612
+ *
613
+ * Call multiple times to set built-ins incrementally; the last mode given for
614
+ * a built-in wins. Turning one back `'on'` re-checks every registered command
615
+ * for a collision. Call this **before** registering the commands that declare
616
+ * a released flag, since `.command()` rejects the flag while the root still
617
+ * owns the token.
618
+ *
619
+ * @param config - Built-in modes to apply over the current state.
620
+ * @returns The builder (for chaining).
621
+ * @throws {@link CLIError} `INVALID_SCHEMA` when a value is neither `'on'` nor `'off'`.
622
+ * @throws {@link CLIError} `RESERVED_FLAG` when a registered command already
623
+ * declares a flag spelled like a built-in this call keeps or restores.
624
+ * @see {@link BuiltinsConfig} for the accepted keys and modes.
625
+ * @see https://dreamcli.kjanat.dev/guide/output#taking-a-built-in-over
626
+ *
627
+ * @example
628
+ * ```ts
629
+ * // `--json` names the document the command validates.
630
+ * cli('schematool')
631
+ * .builtins({ json: 'off' })
632
+ * .default(
633
+ * command('validate')
634
+ * .flag('json', flag.string().describe('Document to validate'))
635
+ * .action(({ flags, out }) => out.log(flags.json)),
636
+ * )
637
+ * .run();
638
+ * ```
639
+ */
640
+ builtins(config: BuiltinsConfig): CLIBuilder;
429
641
  /**
430
642
  * Set the program description (shown in root help).
431
643
  *
@@ -578,6 +790,9 @@ declare class CLIBuilder {
578
790
  * or a settings-shaped object falls through to the settings overload.
579
791
  *
580
792
  * @param data - Pre-loaded manifest metadata.
793
+ * @throws {@link CLIError} `RESERVED_FLAG` when the data carries a version and
794
+ * a registered command spells `--version` or `-V` as a flag name, an alias,
795
+ * or a negated spelling.
581
796
  *
582
797
  * @example
583
798
  * ```ts
@@ -606,6 +821,13 @@ declare class CLIBuilder {
606
821
  *
607
822
  * Has no effect in `.execute()` (filesystem-free) — use the data overload.
608
823
  *
824
+ * A discovered version lands at `.run()` time, past every build-time check, so
825
+ * the `RESERVED_FLAG` guard re-runs there. A registered command that spells
826
+ * `--version` or `-V` as a flag name, an alias, or a negated spelling then fails
827
+ * startup, writing the error and its suggestion to stderr (a JSON error envelope
828
+ * on stdout under `--json`) and exiting with the error's exit code instead of
829
+ * throwing.
830
+ *
609
831
  * @param settings - Optional settings:
610
832
  * - `files`: candidate manifest filenames in priority order
611
833
  * (default `['package.json']`).
@@ -631,60 +853,20 @@ declare class CLIBuilder {
631
853
  * ```
632
854
  */
633
855
  manifest(settings?: ManifestSettings): CLIBuilder;
634
- /**
635
- * Discover metadata from `package.json` (preset for {@link CLIBuilder.manifest}).
636
- *
637
- * @deprecated Use {@link CLIBuilder.manifest} — `.manifest()` defaults to
638
- * `package.json` and also supports `deno.json` / `jsr.json` via `files`.
639
- *
640
- * @param data - Pre-loaded `package.json` metadata.
641
- */
642
- packageJson(data: PackageJsonData): CLIBuilder;
643
- /**
644
- * Discover metadata from `package.json` (preset for {@link CLIBuilder.manifest}).
645
- *
646
- * @deprecated Use {@link CLIBuilder.manifest}.
647
- *
648
- * @param settings - `inferName` / `from` (see {@link CLIBuilder.manifest}).
649
- */
650
- packageJson(settings?: ManifestPresetSettings): CLIBuilder;
651
- /**
652
- * Discover metadata from `deno.json`, `deno.jsonc`, then `jsr.json` (preset for
653
- * {@link CLIBuilder.manifest}).
654
- *
655
- * @deprecated Use `.manifest({ files: ['deno.json', 'deno.jsonc', 'jsr.json'] })`.
656
- *
657
- * @param data - Pre-loaded `deno.json` / `jsr.json` metadata.
658
- */
659
- denoJson(data: PackageJsonData): CLIBuilder;
660
- /**
661
- * Discover metadata from `deno.json`, `deno.jsonc`, then `jsr.json` (preset for
662
- * {@link CLIBuilder.manifest}).
663
- *
664
- * @deprecated Use `.manifest({ files: ['deno.json', 'deno.jsonc', 'jsr.json'] })`.
665
- *
666
- * @param settings - `inferName` / `from` (see {@link CLIBuilder.manifest}).
667
- * `deno.json` / `jsr.json` have no `bin` field, so `inferName` resolves
668
- * from `name`; pass `{ scope: 'keep' }` to retain a leading `@scope/`.
669
- *
670
- * @example
671
- * ```ts
672
- * cli('mycli')
673
- * .denoJson({ from: import.meta.url })
674
- * .command(deploy)
675
- * .run();
676
- * ```
677
- */
678
- denoJson(settings?: ManifestPresetSettings): CLIBuilder;
679
856
  /**
680
857
  * Register a command with the CLI program.
681
858
  *
682
- * The command's type parameters are erased for heterogeneous storage.
683
- * Type safety is preserved inside the closure that delegates to
684
- * {@linkcode runCommand | runCommand()}.
859
+ * The command's schema joins {@link CLISchema.commands}; its handler and
860
+ * subcommand tree are compiled into the builder's execution graph.
685
861
  *
686
862
  * @param cmd - {@link CommandBuilder} to register.
687
863
  * @returns The builder (for chaining).
864
+ * @throws {@link CLIError} `RESERVED_FLAG` when the command, or one of its
865
+ * nested subcommands, spells a root-owned flag (`--json`, `--quiet`/`-q`,
866
+ * `--help`/`-h`, and `--version`/`-V` once
867
+ * {@link CLIBuilder.version | .version()} is set) as a flag name, an alias,
868
+ * or a negated spelling. A built-in released through
869
+ * {@link CLIBuilder.builtins | .builtins()} is not reserved.
688
870
  */
689
871
  command<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown>>(cmd: CommandBuilder<F, A, C>): CLIBuilder;
690
872
  /**
@@ -735,6 +917,12 @@ declare class CLIBuilder {
735
917
  * @param options - Default-command options. `{ route: true }` also exposes
736
918
  * the command under its own name (see {@link DefaultCommandOptions}).
737
919
  * @returns The builder (for chaining).
920
+ * @throws {@link CLIError} `RESERVED_FLAG` when the command, or one of its
921
+ * nested subcommands, spells a root-owned flag (`--json`, `--quiet`/`-q`,
922
+ * `--help`/`-h`, and `--version`/`-V` once
923
+ * {@link CLIBuilder.version | .version()} is set) as a flag name, an alias,
924
+ * or a negated spelling. A built-in released through
925
+ * {@link CLIBuilder.builtins | .builtins()} is not reserved.
738
926
  */
739
927
  default<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown>>(cmd: CommandBuilder<F, A, C>, options?: DefaultCommandOptions): CLIBuilder;
740
928
  /**
@@ -793,7 +981,7 @@ declare class CLIBuilder {
793
981
  * @param options - Injectable runtime state.
794
982
  * @returns Structured result with exit code and captured output.
795
983
  */
796
- execute(argv: readonly string[], options?: CLIRunOptions): Promise<RunResult>;
984
+ execute(argv: readonly string[], options?: CLIExecuteOptions): Promise<RunResult>;
797
985
  /**
798
986
  * Run the CLI program as a production entry point.
799
987
  *
@@ -824,7 +1012,7 @@ declare class CLIBuilder {
824
1012
  * options object can never silently enable inference (use `true` for that).
825
1013
  */
826
1014
  type InferNameOption = boolean | {
827
- readonly scope: 'keep' | 'strip';
1015
+ readonly scope: "keep" | "strip";
828
1016
  };
829
1017
  /** Discovery settings accepted by {@link CLIBuilder.manifest}. */
830
1018
  interface ManifestSettings {
@@ -846,13 +1034,6 @@ interface ManifestSettings {
846
1034
  */
847
1035
  readonly files?: readonly string[];
848
1036
  }
849
- /**
850
- * Discovery settings for the `.packageJson()` / `.denoJson()` presets (no `files`).
851
- *
852
- * @deprecated Both presets are deprecated; use {@link ManifestSettings} with
853
- * {@link CLIBuilder.manifest}.
854
- */
855
- type ManifestPresetSettings = Omit<ManifestSettings, 'files'>;
856
1037
  /**
857
1038
  * Options for the `cli({...})` factory form.
858
1039
  *
@@ -905,7 +1086,7 @@ interface CLIOptions {
905
1086
  * .run();
906
1087
  * ```
907
1088
  */
908
- declare function cli(name: string, options?: Omit<CLIOptions, 'name'>): CLIBuilder;
1089
+ declare function cli(name: string, options?: Omit<CLIOptions, "name">): CLIBuilder;
909
1090
  /** Create a new CLI program builder from an options object. */
910
1091
  declare function cli(options: CLIOptions): CLIBuilder;
911
1092
  /**
@@ -927,4 +1108,4 @@ declare function cli(options: CLIOptions): CLIBuilder;
927
1108
  */
928
1109
  declare function isMainModule(meta: ImportMeta): boolean;
929
1110
  //#endregion
930
- export { type BeforeParseParams, CLIBuilder, type CLIOptions, type CLIPlugin, type CLIPluginHooks, type CLIRunOptions, type CLISchema, type CompletionsFlagConfig, type ConfigSettings, type DefaultCommandOptions, type HelpConfig, type HelpLinks, type InferNameOption, type ManifestPresetSettings, type ManifestSettings, type PackageJsonSettings, type PluginCommandContext, type RenderContext, type RenderContextOptions, type ResolvedCommandParams, type ResolvedManifestSettings, cli, formatRootHelp, isMainModule, plugin, resolveRenderContext };
1111
+ export { type BeforeParseParams, type BuiltinMode, type BuiltinName, type Builtins, type BuiltinsConfig, CLIBuilder, type CLIDefinition, type CLIExecuteOptions, type CLIOptions, type CLIPlugin, type CLIPluginHooks, type CLIRunOptions, type CLISchema, type CompletionsFlagConfig, type ConfigSettings, type ConfigSettingsDefinition, type DefaultCommandOptions, type HelpConfig, type HelpLinks, type InferNameOption, type ManifestSettings, type PluginCommandContext, type RenderContext, type RenderContextOptions, type ResolvedCommandParams, type ResolvedManifestSettings, cli, createCLISchema, isMainModule, plugin, resolveRenderContext };