@kjanat/dreamcli 4.2.0 → 5.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/README.md +3 -1
  2. package/dist/completion-B4oRc2Ae.mjs +59 -0
  3. package/dist/completion.d.mts +11 -11
  4. package/dist/completion.mjs +1 -1
  5. package/dist/config-DSh3QJpX.mjs +1 -0
  6. package/dist/config.d.mts +11 -1
  7. package/dist/config.mjs +1 -1
  8. package/dist/core-BZx351-p.mjs +21 -0
  9. package/dist/dynamic-BK2lQF2M.mjs +1 -0
  10. package/dist/{index-C5CYWtxn.d.mts → index-CLtWJqwn.d.mts} +50 -10
  11. package/dist/{index-B6oD4_8b.d.mts → index-CuhI1Ynv.d.mts} +638 -47
  12. package/dist/{index-B3_9MlHz.d.mts → index-D683D09G.d.mts} +0 -2
  13. package/dist/{index-B_1Dmsdq.d.mts → index-DDhRLoTu.d.mts} +157 -21
  14. package/dist/{index-Cj7kXwQH.d.mts → index-DIWRV_wp.d.mts} +1 -7
  15. package/dist/{index-eF7SkQzQ.d.mts → index-Vjl2_m23.d.mts} +66 -15
  16. package/dist/{index-CaRNJH2R.d.mts → index-aTmg9yfl.d.mts} +14 -12
  17. package/dist/index.d.mts +41 -12
  18. package/dist/index.mjs +1 -1
  19. package/dist/json-schema-CYgq_hFu.mjs +59 -0
  20. package/dist/json-schema.d.mts +10 -2
  21. package/dist/json-schema.mjs +1 -1
  22. package/dist/{package-json-fYhxDdWD.mjs → package-json-hqUWeazy.mjs} +1 -1
  23. package/dist/prompt.d.mts +13 -8
  24. package/dist/prompt.mjs +1 -1
  25. package/dist/rolldown-runtime-DOYBPklu.mjs +1 -0
  26. package/dist/runtime.d.mts +20 -2
  27. package/dist/runtime.mjs +1 -1
  28. package/dist/session-BEKj0yLA.mjs +1 -0
  29. package/dist/{terminal-cbye9mKF.mjs → terminal-Dws_b5UK.mjs} +1 -1
  30. package/dist/test-prompter-euLYzWWO.mjs +1 -0
  31. package/dist/testkit.d.mts +18 -7
  32. package/dist/testkit.mjs +1 -1
  33. package/dist/version.d.mts +1 -3
  34. package/dist/version.mjs +1 -1
  35. package/dreamcli.schema.json +151 -2
  36. package/package.json +11 -11
  37. package/skills/cli-creation/SKILL.md +1 -1
  38. package/dist/adapter-DsmEc0WO.d.mts +0 -285
  39. package/dist/completion-BYhuYn2Q.mjs +0 -6
  40. package/dist/config-BgJZ-X4r.mjs +0 -1
  41. package/dist/core-B4Twhd48.mjs +0 -18
  42. package/dist/json-schema-DVyfq4bA.mjs +0 -52
  43. package/dist/rolldown-runtime-G4Kt5YOX.mjs +0 -1
  44. package/dist/session-CQsnVijE.mjs +0 -1
  45. package/dist/test-prompter-Ddkt9n5A.mjs +0 -1
@@ -1,4 +1,3 @@
1
- //#region src/core/errors/index.d.ts
2
1
  /**
3
2
  * Structured error types for DreamCLI.
4
3
  *
@@ -127,5 +126,4 @@ declare function isCLIError(value: unknown): value is CLIError;
127
126
  declare function isParseError(value: unknown): value is ParseError;
128
127
  /** Narrows an unknown value to `ValidationError`. */
129
128
  declare function isValidationError(value: unknown): value is ValidationError;
130
- //#endregion
131
129
  export { ParseError as a, ValidationError as c, isCLIError as d, isParseError as f, ErrorCode as i, ValidationErrorCode as l, CLIErrorJSON as n, ParseErrorCode as o, isValidationError as p, CLIErrorOptions as r, ParseErrorOptions as s, CLIError as t, ValidationErrorOptions as u };
@@ -1,7 +1,6 @@
1
- import { A as Out, Hn as ActivityEvent, I as ResolutionProvenance, K as Verbosity, Qn as schemaBrand, Vn as HelpThemeFactory, b as CommandSchema, o as PromptEngine, y as CommandMeta } from "./index-B6oD4_8b.mjs";
2
- import { t as CLIError } from "./index-B3_9MlHz.mjs";
1
+ import { $n as ActivityEvent, F as Out, Qn as HelpThemeFactory, T as CommandSchema, V as ResolutionProvenance, Z as Verbosity, d as PromptEngine, fn as PathChecks, lr as schemaBrand, w as CommandMeta } from "./index-CuhI1Ynv.mjs";
2
+ import { t as CLIError } from "./index-D683D09G.mjs";
3
3
  import { Colors } from "ansispeck";
4
- //#region src/core/cli/builtins.d.ts
5
4
  /** A built-in flag a consumer can take over. */
6
5
  type BuiltinName = 'help' | 'json' | 'quiet';
7
6
  /** Whether the root keeps a built-in or releases it to commands. */
@@ -45,8 +44,6 @@ interface Builtins {
45
44
  /** Whether the root owns `--quiet`/`-q`. */
46
45
  readonly quiet: BuiltinMode;
47
46
  }
48
- //#endregion
49
- //#region src/core/parse/index.d.ts
50
47
  /**
51
48
  * Token discriminated union.
52
49
  *
@@ -160,8 +157,6 @@ interface ParseOptions {
160
157
  * ```
161
158
  */
162
159
  declare function parse(schema: CommandSchema, argv: readonly string[], options?: ParseOptions): ParseResult;
163
- //#endregion
164
- //#region src/core/resolve/contracts.d.ts
165
160
  /**
166
161
  * External state the resolver may consult after parsing.
167
162
  *
@@ -189,6 +184,56 @@ interface ResolveOptions {
189
184
  * apply as-is.
190
185
  */
191
186
  readonly mkdir?: (path: string) => Promise<void>;
187
+ /**
188
+ * What happens to a declared filesystem check that cannot run because
189
+ * {@link ResolveOptions.stat} (or {@link ResolveOptions.mkdir} for `create`)
190
+ * is absent.
191
+ *
192
+ * - `'lenient'` — the check is skipped and recorded in
193
+ * {@link ResolveResult.skippedPathChecks}, so a result can still report
194
+ * that it was never exercised.
195
+ * - `'strict'` — resolution fails with a `CLIError` of code
196
+ * `'PATH_CHECK_SKIPPED'` (exit code `1`) naming every skipped input, for
197
+ * tests that must exercise each declared check.
198
+ *
199
+ * Only inputs that resolved a path value are affected: an unset optional
200
+ * path has nothing to check in production either.
201
+ *
202
+ * @defaultValue `'lenient'`
203
+ */
204
+ readonly pathChecks?: 'lenient' | 'strict';
205
+ /**
206
+ * Environment namespace prepended to every relative env binding, the count
207
+ * and templates of an indexed family included. A binding declared
208
+ * `absolute` is read as written. Diagnostics and provenance name the
209
+ * concrete variable.
210
+ *
211
+ * @defaultValue `undefined` (no namespace)
212
+ */
213
+ readonly envPrefix?: string;
214
+ }
215
+ /**
216
+ * A declared `flag.path()` / `arg.path()` check that resolution had no means
217
+ * to run.
218
+ *
219
+ * Recorded instead of raised when {@link ResolveOptions.pathChecks} is
220
+ * `'lenient'` (the default): the value resolved and the handler ran, but the
221
+ * filesystem was never consulted, so a passing result does not prove the real
222
+ * CLI would accept the same path.
223
+ */
224
+ interface SkippedPathCheck {
225
+ /** Whether the path belongs to a flag or a positional arg. */
226
+ readonly kind: 'flag' | 'arg';
227
+ /** Name of the flag or arg. */
228
+ readonly name: string;
229
+ /** The checks the schema declared (`mustExist`, `type`, `create`). */
230
+ readonly checks: PathChecks;
231
+ /**
232
+ * The capability resolution lacked: `'stat'` when no probe was supplied so
233
+ * no check ran, or `'mkdir'` when the path was missing, `create` was
234
+ * declared, and nothing could create it.
235
+ */
236
+ readonly missing: 'stat' | 'mkdir';
192
237
  }
193
238
  /** Structured deprecation notice emitted for explicitly sourced values. */
194
239
  interface DeprecationWarning {
@@ -219,14 +264,18 @@ interface ResolveResult {
219
264
  readonly args: Readonly<Record<string, unknown>>;
220
265
  /** Deprecation notices collected during resolution (may be empty). */
221
266
  readonly deprecations: readonly DeprecationWarning[];
267
+ /**
268
+ * Declared filesystem checks that did not run because no `stat` probe (or
269
+ * no `mkdir` for `create`) was supplied. Empty when every declared check
270
+ * ran, or when no resolved value had a check to run.
271
+ */
272
+ readonly skippedPathChecks: readonly SkippedPathCheck[];
222
273
  /**
223
274
  * Which stage produced each value. Present only for inputs that resolved a
224
275
  * value, so an unset optional input has no entry.
225
276
  */
226
277
  readonly provenance: ResolutionProvenanceRecord;
227
278
  }
228
- //#endregion
229
- //#region src/core/resolve/index.d.ts
230
279
  /**
231
280
  * Resolve parsed values against a command schema.
232
281
  *
@@ -247,12 +296,21 @@ interface ResolveResult {
247
296
  * a value. Collects **all** validation errors before throwing, so the
248
297
  * user sees every missing field at once.
249
298
  *
299
+ * `flag.path()` / `arg.path()` filesystem checks run only through the injected
300
+ * {@linkcode ResolveOptions.stat} probe. A check that cannot run is recorded in
301
+ * {@linkcode ResolveResult.skippedPathChecks}, or rejected outright when
302
+ * {@linkcode ResolveOptions.pathChecks} is `'strict'`.
303
+ *
250
304
  * @param schema - The command schema defining flags and args
251
305
  * @param parsed - Raw parsed values from the parser
252
306
  * @param options - External state for the resolution chain
253
307
  * @returns Fully resolved flag and arg values
254
308
  * @throws {@linkcode ValidationError} if any required flag or arg is missing,
255
309
  * or if an env/config value fails coercion
310
+ * @throws {@linkcode CLIError} with code `'INVALID_SCHEMA'` when
311
+ * {@linkcode ResolveOptions.envPrefix} is empty or carries `=`, a brace, or NUL
312
+ * @throws {@linkcode CLIError} with code `'PATH_CHECK_SKIPPED'` when
313
+ * `pathChecks: 'strict'` and a declared filesystem check could not run
256
314
  *
257
315
  * @example
258
316
  * ```ts
@@ -263,8 +321,6 @@ interface ResolveResult {
263
321
  * ```
264
322
  */
265
323
  declare function resolve(schema: CommandSchema, parsed: ParseResult, options?: ResolveOptions): Promise<ResolveResult>;
266
- //#endregion
267
- //#region src/core/cli/plugin.d.ts
268
324
  /** Shared hook payload for a concrete command execution. */
269
325
  interface PluginCommandContext {
270
326
  /** Runtime command schema being executed. */
@@ -287,6 +343,12 @@ interface ResolvedCommandParams extends PluginCommandContext {
287
343
  readonly args: Readonly<Record<string, unknown>>;
288
344
  /** Structured deprecation warnings collected during resolution. */
289
345
  readonly deprecations: readonly DeprecationWarning[];
346
+ /**
347
+ * Declared `flag.path()` / `arg.path()` checks that could not run because
348
+ * execution supplied no `stat` probe (or no `mkdir` for `create`). Always
349
+ * empty under `CLIBuilder.run()`, which supplies the adapter's filesystem.
350
+ */
351
+ readonly skippedPathChecks: readonly SkippedPathCheck[];
290
352
  }
291
353
  /**
292
354
  * Individual lifecycle hooks that a plugin may implement.
@@ -353,8 +415,6 @@ interface CLIPlugin {
353
415
  * @returns A frozen {@link CLIPlugin} definition.
354
416
  */
355
417
  declare function plugin(hooks: CLIPluginHooks, name?: string): CLIPlugin;
356
- //#endregion
357
- //#region src/core/help/index.d.ts
358
418
  /** Options for customising help output. */
359
419
  interface HelpOptions {
360
420
  /** Maximum line width (columns). Defaults to 80. */
@@ -381,6 +441,28 @@ interface HelpOptions {
381
441
  * @defaultValue `undefined` (use `flagOrder`)
382
442
  */
383
443
  readonly sortFlags?: (a: string, b: string) => number;
444
+ /**
445
+ * Spelling of long flag names, aliases, and negations in the `Flags:` table.
446
+ *
447
+ * - `'declared'` — each spelling exactly as it was declared.
448
+ * - `'kebab'` — the kebab-case counterpart of a camelCase spelling
449
+ * (`--wasm-path` for a flag keyed `wasmPath`), while the resolved value
450
+ * keeps its declared key. A spelling stays as declared when the parser
451
+ * would not read the counterpart as the same flag form: with
452
+ * {@link HelpOptions.caseParity} off, or when another declared flag owns it.
453
+ *
454
+ * @defaultValue `'declared'`
455
+ */
456
+ readonly flagSpelling?: 'declared' | 'kebab';
457
+ /**
458
+ * Whether the parser accepts kebab↔camel counterpart spellings, so
459
+ * `flagSpelling: 'kebab'` only renders spellings the parser accepts.
460
+ * `CLIBuilder.execute()`/`.run()` and `readFlags()` thread their parser
461
+ * settings here automatically.
462
+ *
463
+ * @defaultValue `true`
464
+ */
465
+ readonly caseParity?: boolean;
384
466
  /**
385
467
  * Emit OSC 8 hyperlinks where link metadata is available (currently the
386
468
  * root-help header name/version configured via `CLIBuilder.links()`).
@@ -415,6 +497,14 @@ interface HelpOptions {
415
497
  readonly footer?: boolean;
416
498
  /** @internal Whether this usage line is being rendered as merged root/default help. */
417
499
  readonly isDefaultHelp?: boolean;
500
+ /**
501
+ * Environment namespace applied to relative env bindings in `[env: …]`
502
+ * annotations, so help names the variables resolution actually reads.
503
+ * `CLIBuilder.execute()`/`.run()` thread the CLI's `.envPrefix()` here.
504
+ *
505
+ * @defaultValue `undefined` (names render as declared)
506
+ */
507
+ readonly envPrefix?: string;
418
508
  /**
419
509
  * Gated ANSI palette used to style help output. Identity formatters mean
420
510
  * plain text. `CLIBuilder.execute()`/`.run()` thread the output channel's
@@ -466,8 +556,6 @@ interface HelpOptions {
466
556
  * ```
467
557
  */
468
558
  declare function formatHelp(schema: CommandSchema, options?: HelpOptions): string;
469
- //#endregion
470
- //#region src/core/prompt/test-prompter.d.ts
471
559
  /**
472
560
  * Sentinel value representing a cancelled/aborted prompt in the test
473
561
  * prompter's answer queue.
@@ -550,8 +638,6 @@ interface TestPrompterOptions {
550
638
  * ```
551
639
  */
552
640
  declare function createTestPrompter(answers: readonly TestAnswer[], options?: TestPrompterOptions): PromptEngine;
553
- //#endregion
554
- //#region src/core/schema/run.d.ts
555
641
  /**
556
642
  * Options accepted by `runCommand()` and internal command execution paths.
557
643
  *
@@ -611,7 +697,9 @@ interface RunOptions {
611
697
  *
612
698
  * `CLIBuilder.run()` supplies the runtime adapter's probe automatically.
613
699
  * When absent (process-free `.execute()` / `runCommand()` without an
614
- * override), path checks are skipped.
700
+ * override), path checks are skipped and each skipped input is listed in
701
+ * {@linkcode RunResult.skippedPathChecks}; set
702
+ * {@linkcode RunOptions.pathChecks} to `'strict'` to fail instead.
615
703
  */
616
704
  readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
617
705
  /**
@@ -619,9 +707,41 @@ interface RunOptions {
619
707
  * checks.
620
708
  *
621
709
  * `CLIBuilder.run()` supplies the runtime adapter's implementation
622
- * automatically. When absent, missing paths are not created.
710
+ * automatically. When absent, missing paths are not created: the existence
711
+ * rules decide instead, and the input is listed in
712
+ * {@linkcode RunResult.skippedPathChecks} with `missing: 'mkdir'`.
623
713
  */
624
714
  readonly mkdir?: (path: string) => Promise<void>;
715
+ /**
716
+ * What happens to a declared filesystem check that cannot run because
717
+ * `stat` (or `mkdir` for `create`) was not supplied.
718
+ *
719
+ * - `'lenient'` — skip the check and record it in
720
+ * {@linkcode RunResult.skippedPathChecks}; the command still runs, which
721
+ * keeps parser and action tests off the host filesystem.
722
+ * - `'strict'` — fail with a `CLIError` of code `'PATH_CHECK_SKIPPED'`
723
+ * (exit code `1`) naming every input whose check did not run, so a
724
+ * passing test proves each declared `mustExist`, `type`, and `create`
725
+ * check was exercised.
726
+ *
727
+ * Only inputs that resolved a path value count. `CLIBuilder.run()` always
728
+ * supplies the adapter's filesystem, so this matters to `.execute()` and
729
+ * `runCommand()`.
730
+ *
731
+ * @defaultValue `'lenient'`
732
+ */
733
+ readonly pathChecks?: 'lenient' | 'strict';
734
+ /**
735
+ * Environment namespace prepended to every relative `.env()` binding, the
736
+ * same way `CLIBuilder.envPrefix()` applies one CLI-wide.
737
+ *
738
+ * `.execute()` and `.run()` default it to the CLI's own prefix, and a value
739
+ * here wins. Pass it to `runCommand()` to test a command under the namespace
740
+ * its CLI declares; without it a command reads its env names as written.
741
+ *
742
+ * @defaultValue `undefined` (no namespace)
743
+ */
744
+ readonly envPrefix?: string;
625
745
  /**
626
746
  * Verbosity level for the output channel.
627
747
  * @defaultValue `'normal'`
@@ -647,6 +767,12 @@ interface RunOptions {
647
767
  * @defaultValue `false`
648
768
  */
649
769
  readonly isTTY?: boolean;
770
+ /**
771
+ * Explicitly enable or disable ANSI color, overriding automatic selection.
772
+ * Otherwise, `env.NO_COLOR` disables color and `env.FORCE_COLOR` enables it
773
+ * unless set to `'0'`. With neither set, color follows `isTTY` outside JSON mode.
774
+ */
775
+ readonly color?: boolean;
650
776
  /**
651
777
  * Help formatting options (width, binName).
652
778
  * Used when `--help` is detected.
@@ -702,6 +828,16 @@ interface RunResult {
702
828
  * unknown errors are wrapped.
703
829
  */
704
830
  readonly error: CLIError | undefined;
831
+ /**
832
+ * Declared `flag.path()` / `arg.path()` checks that did not run because no
833
+ * `stat` probe (or no `mkdir` for `create`) was supplied.
834
+ *
835
+ * Empty when every declared check ran, when no resolved value had a check
836
+ * to run, or when execution ended before resolution. A successful result
837
+ * with entries here never consulted the filesystem, so it does not prove
838
+ * the real CLI accepts the same path — pass `stat` / `mkdir`, or set
839
+ * {@linkcode RunOptions.pathChecks} to `'strict'` to make the test fail.
840
+ */
841
+ readonly skippedPathChecks: readonly SkippedPathCheck[];
705
842
  }
706
- //#endregion
707
- export { BuiltinsConfig as A, includesBeforeSeparator as C, BuiltinMode as D, tokenize as E, BuiltinName as O, Token as S, stripBeforeSeparator as T, ResolutionProvenanceRecord as _, TestPrompterOptions as a, ParseOptions as b, formatHelp as c, CLIPluginHooks as d, PluginCommandContext as f, DeprecationWarning as g, resolve as h, TestAnswer as i, Builtins as k, BeforeParseParams as l, plugin as m, RunResult as n, createTestPrompter as o, ResolvedCommandParams as p, PROMPT_CANCEL as r, HelpOptions as s, RunOptions as t, CLIPlugin as u, ResolveOptions as v, parse as w, ParseResult as x, ResolveResult as y };
843
+ export { Builtins as A, Token as C, tokenize as D, stripBeforeSeparator as E, BuiltinMode as O, ParseResult as S, parse as T, ResolutionProvenanceRecord as _, TestPrompterOptions as a, SkippedPathCheck as b, formatHelp as c, CLIPluginHooks as d, PluginCommandContext as f, DeprecationWarning as g, resolve as h, TestAnswer as i, BuiltinsConfig as j, BuiltinName as k, BeforeParseParams as l, plugin as m, RunResult as n, createTestPrompter as o, ResolvedCommandParams as p, PROMPT_CANCEL as r, HelpOptions as s, RunOptions as t, CLIPlugin as u, ResolveOptions as v, includesBeforeSeparator as w, ParseOptions as x, ResolveResult as y };
@@ -1,5 +1,4 @@
1
- import { n as RuntimeAdapter } from "./adapter-DsmEc0WO.mjs";
2
- //#region src/core/config/package-json.d.ts
1
+ import { s as RuntimeAdapter } from "./index-CuhI1Ynv.mjs";
3
2
  /**
4
3
  * Object form of a manifest's `repository` field
5
4
  * (e.g. `{"type":"git","url":"git+https://github.com/u/r.git"}`).
@@ -132,8 +131,6 @@ declare function discoverManifest(adapter: PackageJsonAdapter, options?: Manifes
132
131
  declare function inferCliName(pkg: PackageJsonData, options?: {
133
132
  readonly stripScope?: boolean;
134
133
  }): string | undefined;
135
- //#endregion
136
- //#region src/core/config/repository-url.d.ts
137
134
  /** Options for {@link packageRepositoryUrl}. */
138
135
  interface PackageRepositoryUrlOptions {
139
136
  /**
@@ -178,8 +175,6 @@ declare function packageRepositoryUrl(pkg: PackageJsonData, options: PackageRepo
178
175
  }): string;
179
176
  /** Resolve a manifest repository URL, returning `undefined` for absent or invalid locators. */
180
177
  declare function packageRepositoryUrl(pkg: PackageJsonData, options?: PackageRepositoryUrlOptions): string | undefined;
181
- //#endregion
182
- //#region src/core/config/index.d.ts
183
178
  /**
184
179
  * Format loader — parses file content into a config object.
185
180
  *
@@ -366,5 +361,4 @@ declare function discoverConfig(appName: string, adapter: ConfigAdapter, options
366
361
  * ```
367
362
  */
368
363
  declare function configFormat(extensions: readonly string[], parse: (content: string) => unknown): FormatLoader;
369
- //#endregion
370
364
  export { discoverManifest as _, ConfigNotFound as a, buildConfigSearchPaths as c, PackageRepositoryUrlOptions as d, packageRepositoryUrl as f, PackageRepository as g, PackageJsonData as h, ConfigFound as i, configFormat as l, PackageJsonAdapter as m, ConfigDiscoveryOptions as n, ConfigSearchPathOptions as o, ManifestDiscoveryOptions as p, ConfigDiscoveryResult as r, FormatLoader as s, ConfigAdapter as t, discoverConfig as u, inferCliName as v };
@@ -1,9 +1,7 @@
1
- import { C as ErasedActionHandler, E as ExecutionStep, It as FlagBuilder, J as ArgConfig, K as Verbosity, Lt as FlagConfig, Qn as schemaBrand, Vn as HelpThemeFactory, _ as CommandDefinition, b as CommandSchema, g as CommandBuilder, q as ArgBuilder } from "./index-B6oD4_8b.mjs";
2
- import { A as BuiltinsConfig, b as ParseOptions, k as Builtins, n as RunResult, t as RunOptions, u as CLIPlugin } from "./index-B_1Dmsdq.mjs";
3
- import { n as RuntimeAdapter } from "./adapter-DsmEc0WO.mjs";
4
- import { h as PackageJsonData, s as FormatLoader } from "./index-Cj7kXwQH.mjs";
1
+ import { A as Builtins, j as BuiltinsConfig, n as RunResult, t as RunOptions, u as CLIPlugin, x as ParseOptions } from "./index-DDhRLoTu.mjs";
2
+ import { h as PackageJsonData, s as FormatLoader } from "./index-DIWRV_wp.mjs";
3
+ import { $ as ArgConfig, Ht as FlagConfig, O as ErasedActionHandler, Q as ArgBuilder, Qn as HelpThemeFactory, S as CommandDefinition, T as CommandSchema, Vt as FlagBuilder, Z as Verbosity, j as ExecutionStep, lr as schemaBrand, s as RuntimeAdapter, x as CommandBuilder } from "./index-CuhI1Ynv.mjs";
5
4
  import { Colors } from "ansispeck";
6
- //#region src/core/completion/shells/shared.d.ts
7
5
  /**
8
6
  * Options for completion script generation.
9
7
  *
@@ -40,8 +38,6 @@ interface CompletionOptions {
40
38
  */
41
39
  readonly rootMode?: 'subcommands' | 'surface';
42
40
  }
43
- //#endregion
44
- //#region src/core/completion/shell.d.ts
45
41
  /**
46
42
  * Supported shell targets for completion script generation.
47
43
  *
@@ -58,8 +54,6 @@ type Shell = 'bash' | 'zsh' | 'fish' | 'powershell';
58
54
  * @see {@link Shell} for the union type matching these entries.
59
55
  */
60
56
  declare const SHELLS: Readonly<readonly ['bash', 'zsh', 'fish', 'powershell']>;
61
- //#endregion
62
- //#region src/core/cli/compiled.d.ts
63
57
  /**
64
58
  * Executable form of one registered command.
65
59
  */
@@ -84,8 +78,6 @@ interface CompiledCLI {
84
78
  /** Plugins in registration order. */
85
79
  readonly plugins: readonly CLIPlugin[];
86
80
  }
87
- //#endregion
88
- //#region src/core/cli/help-links.d.ts
89
81
  /**
90
82
  * OSC 8 hyperlink targets for the root-help header.
91
83
  *
@@ -98,8 +90,6 @@ interface HelpLinks {
98
90
  /** URL the version links to (e.g. the release tag). */
99
91
  readonly version: string | undefined;
100
92
  }
101
- //#endregion
102
- //#region src/core/cli/index.d.ts
103
93
  /**
104
94
  * Runtime descriptor for the CLI program.
105
95
  *
@@ -201,6 +191,16 @@ interface CLISchema {
201
191
  * releases its tokens to the commands.
202
192
  */
203
193
  readonly builtins: Builtins;
194
+ /**
195
+ * CLI-wide environment namespace prepended to every relative env binding
196
+ * (`undefined` when none is set). `.env('TOKEN')` reads `<envPrefix>TOKEN`;
197
+ * a binding declared with `{ absolute: true }` is read as written.
198
+ *
199
+ * Set via the {@linkcode CLIBuilder.envPrefix | .envPrefix()} builder method
200
+ * or the `envPrefix` field of {@link CLIDefinition}. Fixed when declared, so
201
+ * neither manifest name inference nor an inherited invocation name changes it.
202
+ */
203
+ readonly envPrefix: string | undefined;
204
204
  }
205
205
  /**
206
206
  * Options for {@link CLIBuilder.completions}: the generator options plus where
@@ -280,6 +280,17 @@ interface HelpConfig {
280
280
  * @defaultValue `undefined` (use `flagOrder`)
281
281
  */
282
282
  readonly sortFlags?: (a: string, b: string) => number;
283
+ /**
284
+ * Spelling of long flag names, aliases, and negations in the `Flags:` table.
285
+ *
286
+ * `'kebab'` shows `--wasm-path` for a flag keyed `wasmPath` while handlers
287
+ * keep reading `flags.wasmPath`. A spelling stays as declared when the
288
+ * parser would not accept its kebab form for the same flag, such as under
289
+ * `cli(name, { flags: { caseParity: false } })`.
290
+ *
291
+ * @defaultValue `'declared'`
292
+ */
293
+ readonly flagSpelling?: 'declared' | 'kebab';
283
294
  /**
284
295
  * Theme overrides for help output, merged over the built-in theme.
285
296
  *
@@ -466,6 +477,12 @@ interface CLIDefinition {
466
477
  * @defaultValue every built-in `'on'`
467
478
  */
468
479
  readonly builtins?: BuiltinsConfig | undefined;
480
+ /**
481
+ * CLI-wide environment namespace for relative env bindings, used verbatim
482
+ * (`'ACME_'` turns `TOKEN` into `ACME_TOKEN`).
483
+ * @defaultValue `undefined` (no namespace)
484
+ */
485
+ readonly envPrefix?: string | undefined;
469
486
  /**
470
487
  * Registered command definitions or built schemas, in registration order.
471
488
  * @defaultValue `[]`
@@ -571,7 +588,8 @@ interface RenderContextOptions {
571
588
  */
572
589
  readonly color?: boolean;
573
590
  /**
574
- * Environment variables consulted for `NO_HYPERLINKS`/`FORCE_HYPERLINKS`
591
+ * Environment variables consulted for `NO_COLOR`/`FORCE_COLOR` and
592
+ * `NO_HYPERLINKS`/`FORCE_HYPERLINKS`
575
593
  * (e.g. `process.env`).
576
594
  *
577
595
  * @defaultValue `{}`
@@ -721,6 +739,40 @@ declare class CLIBuilder {
721
739
  * `--version` or `-V` as a flag name, an alias, or a negated spelling.
722
740
  */
723
741
  version(v: string): CLIBuilder;
742
+ /**
743
+ * Namespace every relative env binding under one CLI-wide prefix.
744
+ *
745
+ * With no argument the prefix is derived from the name passed to `cli()`:
746
+ * camelCase word boundaries and each run of characters outside
747
+ * `[A-Za-z0-9]` become `_`, the result is uppercased with leading and
748
+ * trailing separators dropped, and `_` is appended (`foo-bar` and `fooBar`
749
+ * → `FOO_BAR_`). This is the rule a name-derived `.env()` follows, minus
750
+ * the trailing `_`. An explicit prefix is used verbatim. Either way it is fixed
751
+ * here, so a manifest-inferred name or an inherited invocation name (a
752
+ * symlink, an alias, `npx`) never changes the environment API.
753
+ *
754
+ * Every `.env()` binding on every command then reads the prefixed name, an
755
+ * indexed family's count and templates included, unless declared with
756
+ * `{ absolute: true }`. Precedence, coercion, and validation are unchanged;
757
+ * help, diagnostics, and `sources` name the concrete variable.
758
+ *
759
+ * @param prefix - The namespace to use verbatim, or omit it to derive one.
760
+ * @returns The builder (for chaining).
761
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` when the prefix is empty or
762
+ * carries `=`, a brace, or NUL, or when no prefix can be derived from the name.
763
+ *
764
+ * @example
765
+ * ```ts
766
+ * cli('foo')
767
+ * .envPrefix()
768
+ * .command(
769
+ * command('deploy')
770
+ * .flag('token', flag.string().env('TOKEN')) // FOO_TOKEN
771
+ * .flag('home', flag.path().env('HOME', { absolute: true })), // HOME
772
+ * );
773
+ * ```
774
+ */
775
+ envPrefix(prefix?: string): CLIBuilder;
724
776
  /**
725
777
  * Choose which built-in flags the root keeps.
726
778
  *
@@ -1231,5 +1283,4 @@ declare function cli(options: CLIOptions): CLIBuilder;
1231
1283
  * ```
1232
1284
  */
1233
1285
  declare function isMainModule(meta: ImportMeta): boolean;
1234
- //#endregion
1235
1286
  export { SHELLS as C, HelpLinks as S, CompletionOptions as T, ResolvedManifestSettings as _, CLIRunOptions as a, isMainModule as b, CompletionsFlagConfig as c, DefaultCommandOptions as d, HelpConfig as f, RenderContextOptions as g, RenderContext as h, CLIOptions as i, ConfigSettings as l, ManifestSettings as m, CLIDefinition as n, CLISchema as o, InferNameOption as p, CLIExecuteOptions as r, CompletionRegistrationOptions as s, CLIBuilder as t, ConfigSettingsDefinition as u, cli as v, Shell as w, resolveRenderContext as x, createCLISchema as y };
@@ -1,5 +1,4 @@
1
- import { n as RuntimeAdapter } from "./adapter-DsmEc0WO.mjs";
2
- //#region src/runtime/detect.d.ts
1
+ import { s as RuntimeAdapter } from "./index-CuhI1Ynv.mjs";
3
2
  /**
4
3
  * Auto-detects the current JavaScript runtime environment.
5
4
  *
@@ -83,8 +82,6 @@ interface GlobalForDetect {
83
82
  * ```
84
83
  */
85
84
  declare function detectRuntime(globals?: GlobalForDetect): Runtime;
86
- //#endregion
87
- //#region src/runtime/auto.d.ts
88
85
  /**
89
86
  * Create a runtime adapter for the current environment.
90
87
  *
@@ -105,17 +102,15 @@ declare function detectRuntime(globals?: GlobalForDetect): Runtime;
105
102
  * ```
106
103
  */
107
104
  declare function createAdapter(globals?: GlobalForDetect): RuntimeAdapter;
108
- //#endregion
109
- //#region src/runtime/deno.d.ts
110
105
  /**
111
106
  * Minimal subset of the Deno namespace needed by the adapter.
112
107
  *
113
108
  * We avoid `@types/deno` to keep the core runtime-agnostic at the type level.
114
109
  * This interface declares only what `createDenoAdapter` actually reads.
115
110
  *
116
- * The `env` property is optional because it requires `--allow-env` permission.
117
- * When permission is denied, the adapter catches the error and falls back to
118
- * an empty env object.
111
+ * Reading `env` requires `--allow-env` permission. The adapter checks
112
+ * `permissions` before reading, so a missing or scoped grant leaves the
113
+ * ungranted variables unset instead of failing or prompting.
119
114
  */
120
115
  interface DenoNamespace {
121
116
  /** Build target metadata (OS detection). */
@@ -128,6 +123,16 @@ interface DenoNamespace {
128
123
  };
129
124
  /** Raw command-line args (excludes the binary/script — Deno pre-strips them). */
130
125
  readonly args: readonly string[];
126
+ /** Permission state queries; read without prompting the user. */
127
+ readonly permissions?: {
128
+ /** Query one permission's state synchronously. */
129
+ querySync?(descriptor: {
130
+ readonly name: 'env';
131
+ readonly variable?: string;
132
+ }): {
133
+ readonly state: 'granted' | 'denied' | 'prompt';
134
+ };
135
+ };
131
136
  /** Environment variable access (requires `--allow-env`). */
132
137
  readonly env: {
133
138
  /** Get a single env var. Returns `undefined` if unset or permission denied. */
@@ -204,8 +209,6 @@ interface DenoNamespace {
204
209
  * ```
205
210
  */
206
211
  declare function createDenoAdapter(ns?: DenoNamespace): RuntimeAdapter;
207
- //#endregion
208
- //#region src/runtime/node.d.ts
209
212
  /**
210
213
  * Minimal subset of the Node.js `process` object needed by the adapter.
211
214
  *
@@ -277,5 +280,4 @@ interface NodeProcess {
277
280
  * ```
278
281
  */
279
282
  declare function createNodeAdapter(proc?: NodeProcess): RuntimeAdapter;
280
- //#endregion
281
283
  export { createAdapter as a, Runtime as c, createDenoAdapter as i, detectRuntime as l, createNodeAdapter as n, GlobalForDetect as o, DenoNamespace as r, RUNTIMES as s, NodeProcess as t };