@kjanat/dreamcli 4.1.0 → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/README.md +3 -1
  2. package/dist/{adapter-YM5QGi3M.d.mts → adapter-DBeedKmD.d.mts} +5 -3
  3. package/dist/{completion-CUMeOnAz.mjs → completion-Bh-qywmB.mjs} +4 -4
  4. package/dist/completion.d.mts +1 -11
  5. package/dist/completion.mjs +1 -1
  6. package/dist/config-DruA8aFV.mjs +1 -0
  7. package/dist/config.d.mts +1 -1
  8. package/dist/config.mjs +1 -1
  9. package/dist/core-B9YNSJeA.mjs +19 -0
  10. package/dist/{index-Cap0MA2V.d.mts → index-AIC5Gler.d.mts} +18 -12
  11. package/dist/{index-BziI2aKc.d.mts → index-BIMjOsR6.d.mts} +316 -53
  12. package/dist/{index-3l8uj16E.d.mts → index-BidVVmln.d.mts} +51 -11
  13. package/dist/index-D683D09G.d.mts +129 -0
  14. package/dist/{index-DWsnGZlx.d.mts → index-DpslpOVV.d.mts} +160 -154
  15. package/dist/{index-BAj2y70U.d.mts → index-hzYPRc_O.d.mts} +65 -14
  16. package/dist/{index-Cp9kt2t-.d.mts → index-jq_FJRKt.d.mts} +1 -7
  17. package/dist/index.d.mts +18 -11
  18. package/dist/index.mjs +1 -1
  19. package/dist/json-schema-DF5fXdKQ.mjs +59 -0
  20. package/dist/json-schema.d.mts +2 -2
  21. package/dist/json-schema.mjs +1 -1
  22. package/dist/package-json-fYhxDdWD.mjs +3 -0
  23. package/dist/prompt.d.mts +32 -5
  24. package/dist/prompt.mjs +1 -1
  25. package/dist/runtime.d.mts +2 -2
  26. package/dist/runtime.mjs +1 -1
  27. package/dist/session-Crtzt7LY.mjs +1 -0
  28. package/dist/terminal-DRsRn4sc.mjs +7 -0
  29. package/dist/test-prompter-BLNGCOA_.mjs +1 -0
  30. package/dist/testkit.d.mts +5 -7
  31. package/dist/testkit.mjs +1 -1
  32. package/dist/version.d.mts +1 -3
  33. package/dist/version.mjs +1 -1
  34. package/dreamcli.schema.json +155 -3
  35. package/package.json +24 -24
  36. package/skills/cli-creation/SKILL.md +1 -1
  37. package/skills/cli-creation/scripts/scaffold_cli.py +12 -4
  38. package/dist/config-CrlScpYX.mjs +0 -1
  39. package/dist/core-DvXUolc_.mjs +0 -17
  40. package/dist/json-schema-DRlrz_IV.mjs +0 -52
  41. package/dist/package-json-BgE9YjjQ.mjs +0 -3
  42. package/dist/terminal-C8KTXjv5.mjs +0 -6
  43. package/dist/test-prompter-v__jT2yG.mjs +0 -1
@@ -1,6 +1,6 @@
1
- import { A as Out, I as ResolutionProvenance, Jn as schemaBrand, Ln as HelpThemeFactory, Rn as ActivityEvent, U as Verbosity, b as CommandSchema, o as PromptEngine, y as CommandMeta } from "./index-BziI2aKc.mjs";
1
+ import { A as Out, Gn as HelpThemeFactory, I as ResolutionProvenance, K as Verbosity, Kn as ActivityEvent, b as CommandSchema, nr as schemaBrand, o as PromptEngine, sn as PathChecks, y as CommandMeta } from "./index-BIMjOsR6.mjs";
2
+ import { t as CLIError } from "./index-D683D09G.mjs";
2
3
  import { Colors } from "ansispeck";
3
- //#region src/core/cli/builtins.d.ts
4
4
  /** A built-in flag a consumer can take over. */
5
5
  type BuiltinName = 'help' | 'json' | 'quiet';
6
6
  /** Whether the root keeps a built-in or releases it to commands. */
@@ -44,138 +44,6 @@ interface Builtins {
44
44
  /** Whether the root owns `--quiet`/`-q`. */
45
45
  readonly quiet: BuiltinMode;
46
46
  }
47
- //#endregion
48
- //#region src/core/errors/index.d.ts
49
- /**
50
- * Structured error types for DreamCLI.
51
- *
52
- * Base {@linkcode CLIError} carries stable code, exit code, suggestion, and structured
53
- * details. {@linkcode ParseError} and {@linkcode ValidationError} derive from it with
54
- * category-appropriate defaults.
55
- *
56
- * @module dreamcli/core/errors
57
- */
58
- /** Codes emitted during argv parsing. */
59
- type ParseErrorCode = 'UNKNOWN_FLAG' | 'UNKNOWN_COMMAND' | 'MISSING_VALUE' | 'INVALID_VALUE' | 'INVALID_SCHEMA' | 'DUPLICATE_FLAG' | 'UNEXPECTED_POSITIONAL';
60
- /** Codes emitted during post-parse validation / resolution. */
61
- type ValidationErrorCode = 'REQUIRED_FLAG' | 'REQUIRED_ARG' | 'MISSING_STDIN' | 'INVALID_ENUM' | 'TYPE_MISMATCH' | 'CONSTRAINT_VIOLATED';
62
- /** Any framework error code (extensible via `string & {}`). */
63
- type ErrorCode = ParseErrorCode | ValidationErrorCode | (string & {});
64
- /** Options accepted by the `CLIError` constructor. */
65
- interface CLIErrorOptions {
66
- /** Stable machine-readable identifier (e.g. `"UNKNOWN_FLAG"`). */
67
- readonly code: ErrorCode;
68
- /**
69
- * Process exit code.
70
- * @defaultValue `1`
71
- */
72
- readonly exitCode?: number;
73
- /** One-liner actionable hint shown to the user. */
74
- readonly suggest?: string;
75
- /** Arbitrary structured payload (serialised in `--json` mode). */
76
- readonly details?: Readonly<Record<string, unknown>>;
77
- /** Original error, if this wraps another. */
78
- readonly cause?: unknown;
79
- }
80
- /**
81
- * Base structured error for DreamCLI.
82
- *
83
- * Every error surfaced by the framework extends this class, ensuring a
84
- * consistent shape for rendering (TTY pretty-print, `--json`, test assertions).
85
- */
86
- declare class CLIError extends Error {
87
- /** Error class name, always `'CLIError'` for the base class. @override */
88
- readonly name: string;
89
- /** Stable machine-readable identifier. */
90
- readonly code: ErrorCode;
91
- /** Process exit code (defaults to `1`). */
92
- readonly exitCode: number;
93
- /** One-liner actionable hint. */
94
- readonly suggest: string | undefined;
95
- /** Structured payload for machine output. */
96
- readonly details: Readonly<Record<string, unknown>> | undefined;
97
- /** Create a structured CLI error from a human message and machine-readable options. */
98
- constructor(message: string, options: CLIErrorOptions);
99
- /**
100
- * Serialise to a plain object suitable for JSON output.
101
- *
102
- * `details` is projected onto JSON-representable values: bigints become
103
- * decimal digits and entries JSON cannot carry are omitted. The error
104
- * object itself keeps the runtime values.
105
- *
106
- * @sealed
107
- */
108
- toJSON(): CLIErrorJSON;
109
- }
110
- /** Shape returned by {@linkcode CLIError}.toJSON(). */
111
- interface CLIErrorJSON {
112
- /** Error class name (e.g. `'CLIError'`, `'ParseError'`). */
113
- readonly name: string;
114
- /** Stable machine-readable identifier for programmatic matching. */
115
- readonly code: ErrorCode;
116
- /** Human-readable description of what went wrong. */
117
- readonly message: string;
118
- /** Process exit code associated with this error. */
119
- readonly exitCode: number;
120
- /** Actionable hint shown to the user, when available. */
121
- readonly suggest?: string;
122
- /** Structured payload for machine consumers, when available. */
123
- readonly details?: Readonly<Record<string, unknown>>;
124
- }
125
- /** Options for {@linkcode ParseError}. Code is narrowed to parse-specific codes. */
126
- interface ParseErrorOptions extends Omit<CLIErrorOptions, 'code' | 'exitCode'> {
127
- /** Parse-category error code (e.g. `'UNKNOWN_FLAG'`, `'MISSING_VALUE'`). */
128
- readonly code: ParseErrorCode;
129
- /**
130
- * Process exit code for parse failures.
131
- * @defaultValue `2`
132
- */
133
- readonly exitCode?: number;
134
- }
135
- /**
136
- * Error thrown when argv tokenization / parsing fails.
137
- *
138
- * Exit code defaults to `2` (standard for CLI usage errors).
139
- */
140
- declare class ParseError extends CLIError {
141
- /** Always `'ParseError'`. @override */
142
- readonly name: "ParseError";
143
- /** Narrowed to parse-category codes. */
144
- readonly code: ParseErrorCode;
145
- /** Create a parse error with exit code defaulting to `2`. */
146
- constructor(message: string, options: ParseErrorOptions);
147
- }
148
- /** Options for {@linkcode ValidationError}. Code is narrowed to validation-specific codes. */
149
- interface ValidationErrorOptions extends Omit<CLIErrorOptions, 'code' | 'exitCode'> {
150
- /** Validation-category error code (e.g. `'REQUIRED_FLAG'`, `'INVALID_ENUM'`). */
151
- readonly code: ValidationErrorCode;
152
- /**
153
- * Process exit code for validation failures.
154
- * @defaultValue `2`
155
- */
156
- readonly exitCode?: number;
157
- }
158
- /**
159
- * Error thrown when resolved values fail validation constraints.
160
- *
161
- * Exit code defaults to `2` (standard for CLI usage errors).
162
- */
163
- declare class ValidationError extends CLIError {
164
- /** Always `'ValidationError'`. @override */
165
- readonly name: "ValidationError";
166
- /** Narrowed to validation-category codes. */
167
- readonly code: ValidationErrorCode;
168
- /** Create a validation error with exit code defaulting to `2`. */
169
- constructor(message: string, options: ValidationErrorOptions);
170
- }
171
- /** Narrows an unknown value to `CLIError`. */
172
- declare function isCLIError(value: unknown): value is CLIError;
173
- /** Narrows an unknown value to `ParseError`. */
174
- declare function isParseError(value: unknown): value is ParseError;
175
- /** Narrows an unknown value to `ValidationError`. */
176
- declare function isValidationError(value: unknown): value is ValidationError;
177
- //#endregion
178
- //#region src/core/parse/index.d.ts
179
47
  /**
180
48
  * Token discriminated union.
181
49
  *
@@ -289,8 +157,6 @@ interface ParseOptions {
289
157
  * ```
290
158
  */
291
159
  declare function parse(schema: CommandSchema, argv: readonly string[], options?: ParseOptions): ParseResult;
292
- //#endregion
293
- //#region src/core/resolve/contracts.d.ts
294
160
  /**
295
161
  * External state the resolver may consult after parsing.
296
162
  *
@@ -318,6 +184,56 @@ interface ResolveOptions {
318
184
  * apply as-is.
319
185
  */
320
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';
321
237
  }
322
238
  /** Structured deprecation notice emitted for explicitly sourced values. */
323
239
  interface DeprecationWarning {
@@ -348,14 +264,18 @@ interface ResolveResult {
348
264
  readonly args: Readonly<Record<string, unknown>>;
349
265
  /** Deprecation notices collected during resolution (may be empty). */
350
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[];
351
273
  /**
352
274
  * Which stage produced each value. Present only for inputs that resolved a
353
275
  * value, so an unset optional input has no entry.
354
276
  */
355
277
  readonly provenance: ResolutionProvenanceRecord;
356
278
  }
357
- //#endregion
358
- //#region src/core/resolve/index.d.ts
359
279
  /**
360
280
  * Resolve parsed values against a command schema.
361
281
  *
@@ -376,12 +296,21 @@ interface ResolveResult {
376
296
  * a value. Collects **all** validation errors before throwing, so the
377
297
  * user sees every missing field at once.
378
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
+ *
379
304
  * @param schema - The command schema defining flags and args
380
305
  * @param parsed - Raw parsed values from the parser
381
306
  * @param options - External state for the resolution chain
382
307
  * @returns Fully resolved flag and arg values
383
308
  * @throws {@linkcode ValidationError} if any required flag or arg is missing,
384
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
385
314
  *
386
315
  * @example
387
316
  * ```ts
@@ -392,8 +321,6 @@ interface ResolveResult {
392
321
  * ```
393
322
  */
394
323
  declare function resolve(schema: CommandSchema, parsed: ParseResult, options?: ResolveOptions): Promise<ResolveResult>;
395
- //#endregion
396
- //#region src/core/cli/plugin.d.ts
397
324
  /** Shared hook payload for a concrete command execution. */
398
325
  interface PluginCommandContext {
399
326
  /** Runtime command schema being executed. */
@@ -416,6 +343,12 @@ interface ResolvedCommandParams extends PluginCommandContext {
416
343
  readonly args: Readonly<Record<string, unknown>>;
417
344
  /** Structured deprecation warnings collected during resolution. */
418
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[];
419
352
  }
420
353
  /**
421
354
  * Individual lifecycle hooks that a plugin may implement.
@@ -482,8 +415,6 @@ interface CLIPlugin {
482
415
  * @returns A frozen {@link CLIPlugin} definition.
483
416
  */
484
417
  declare function plugin(hooks: CLIPluginHooks, name?: string): CLIPlugin;
485
- //#endregion
486
- //#region src/core/help/index.d.ts
487
418
  /** Options for customising help output. */
488
419
  interface HelpOptions {
489
420
  /** Maximum line width (columns). Defaults to 80. */
@@ -510,6 +441,28 @@ interface HelpOptions {
510
441
  * @defaultValue `undefined` (use `flagOrder`)
511
442
  */
512
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;
513
466
  /**
514
467
  * Emit OSC 8 hyperlinks where link metadata is available (currently the
515
468
  * root-help header name/version configured via `CLIBuilder.links()`).
@@ -544,6 +497,14 @@ interface HelpOptions {
544
497
  readonly footer?: boolean;
545
498
  /** @internal Whether this usage line is being rendered as merged root/default help. */
546
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;
547
508
  /**
548
509
  * Gated ANSI palette used to style help output. Identity formatters mean
549
510
  * plain text. `CLIBuilder.execute()`/`.run()` thread the output channel's
@@ -595,8 +556,6 @@ interface HelpOptions {
595
556
  * ```
596
557
  */
597
558
  declare function formatHelp(schema: CommandSchema, options?: HelpOptions): string;
598
- //#endregion
599
- //#region src/core/prompt/test-prompter.d.ts
600
559
  /**
601
560
  * Sentinel value representing a cancelled/aborted prompt in the test
602
561
  * prompter's answer queue.
@@ -616,10 +575,10 @@ declare const PROMPT_CANCEL: unique symbol;
616
575
  /**
617
576
  * A queued answer consumed by {@link createTestPrompter}.
618
577
  *
619
- * The test prompter returns these values exactly as provided; it does not
620
- * coerce them. The one exception mirrors the terminal prompter: a string answer
621
- * to an `input` prompt is run through the prompt's `validate` function, and a
622
- * failing answer is rejected as a cancellation (see {@link createTestPrompter}).
578
+ * The test prompter leaves malformed non-string values intact for resolver
579
+ * error tests. Text answers use the same whitespace, empty-answer, default,
580
+ * and validation policy as the terminal prompter. Passwords retry invalid
581
+ * answers; ordinary input retains its cancellation fallback (see {@link createTestPrompter}).
623
582
  * The normal resolution pipeline performs any later type coercion, so tests can
624
583
  * supply values in the same shapes real prompts would yield:
625
584
  *
@@ -658,6 +617,11 @@ interface TestPrompterOptions {
658
617
  * is rejected as a cancellation (`{ answered: false }`) — mirroring the terminal
659
618
  * prompter exhausting its retries — so prompt validation is integration-testable
660
619
  * via {@linkcode runCommand} rather than silently accepted as the resolved value.
620
+ * Password prompts instead consume further queued answers on validation failure,
621
+ * and reject with `PROMPT_INVALID` after ten invalid attempts. Input prompts
622
+ * also retry empty answers when `empty: 'retry'`; ordinary validator failures
623
+ * retain their cancellation fallback. `PROMPT_CANCEL`
624
+ * remains a distinct user cancellation.
661
625
  *
662
626
  * @param answers - Ordered queue of answers. Use `PROMPT_CANCEL` for
663
627
  * cancellation.
@@ -674,8 +638,6 @@ interface TestPrompterOptions {
674
638
  * ```
675
639
  */
676
640
  declare function createTestPrompter(answers: readonly TestAnswer[], options?: TestPrompterOptions): PromptEngine;
677
- //#endregion
678
- //#region src/core/schema/run.d.ts
679
641
  /**
680
642
  * Options accepted by `runCommand()` and internal command execution paths.
681
643
  *
@@ -735,7 +697,9 @@ interface RunOptions {
735
697
  *
736
698
  * `CLIBuilder.run()` supplies the runtime adapter's probe automatically.
737
699
  * When absent (process-free `.execute()` / `runCommand()` without an
738
- * 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.
739
703
  */
740
704
  readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
741
705
  /**
@@ -743,9 +707,41 @@ interface RunOptions {
743
707
  * checks.
744
708
  *
745
709
  * `CLIBuilder.run()` supplies the runtime adapter's implementation
746
- * 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'`.
747
713
  */
748
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;
749
745
  /**
750
746
  * Verbosity level for the output channel.
751
747
  * @defaultValue `'normal'`
@@ -826,6 +822,16 @@ interface RunResult {
826
822
  * unknown errors are wrapped.
827
823
  */
828
824
  readonly error: CLIError | undefined;
825
+ /**
826
+ * Declared `flag.path()` / `arg.path()` checks that did not run because no
827
+ * `stat` probe (or no `mkdir` for `create`) was supplied.
828
+ *
829
+ * Empty when every declared check ran, when no resolved value had a check
830
+ * to run, or when execution ended before resolution. A successful result
831
+ * with entries here never consulted the filesystem, so it does not prove
832
+ * the real CLI accepts the same path — pass `stat` / `mkdir`, or set
833
+ * {@linkcode RunOptions.pathChecks} to `'strict'` to make the test fail.
834
+ */
835
+ readonly skippedPathChecks: readonly SkippedPathCheck[];
829
836
  }
830
- //#endregion
831
- export { ErrorCode as A, BuiltinMode as B, includesBeforeSeparator as C, CLIError as D, tokenize as E, ValidationErrorCode as F, Builtins as H, ValidationErrorOptions as I, isCLIError as L, ParseErrorCode as M, ParseErrorOptions as N, CLIErrorJSON as O, ValidationError as P, isParseError as R, Token as S, stripBeforeSeparator as T, BuiltinsConfig as U, BuiltinName as V, 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, ParseError as j, CLIErrorOptions 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, isValidationError as z };
837
+ 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,9 +1,8 @@
1
- import { C as ErasedActionHandler, E as ExecutionStep, G as ArgConfig, Jn as schemaBrand, Ln as HelpThemeFactory, Nt as FlagBuilder, Pt as FlagConfig, U as Verbosity, W as ArgBuilder, _ as CommandDefinition, b as CommandSchema, g as CommandBuilder } from "./index-BziI2aKc.mjs";
2
- import { H as Builtins, U as BuiltinsConfig, b as ParseOptions, n as RunResult, t as RunOptions, u as CLIPlugin } from "./index-DWsnGZlx.mjs";
3
- import { n as RuntimeAdapter } from "./adapter-YM5QGi3M.mjs";
4
- import { h as PackageJsonData, s as FormatLoader } from "./index-Cp9kt2t-.mjs";
1
+ import { C as ErasedActionHandler, E as ExecutionStep, Gn as HelpThemeFactory, It as FlagBuilder, J as ArgConfig, K as Verbosity, Lt as FlagConfig, _ as CommandDefinition, b as CommandSchema, g as CommandBuilder, nr as schemaBrand, q as ArgBuilder } from "./index-BIMjOsR6.mjs";
2
+ import { A as Builtins, j as BuiltinsConfig, n as RunResult, t as RunOptions, u as CLIPlugin, x as ParseOptions } from "./index-DpslpOVV.mjs";
3
+ import { n as RuntimeAdapter } from "./adapter-DBeedKmD.mjs";
4
+ import { h as PackageJsonData, s as FormatLoader } from "./index-jq_FJRKt.mjs";
5
5
  import { Colors } from "ansispeck";
6
- //#region src/core/completion/shells/shared.d.ts
7
6
  /**
8
7
  * Options for completion script generation.
9
8
  *
@@ -40,8 +39,6 @@ interface CompletionOptions {
40
39
  */
41
40
  readonly rootMode?: 'subcommands' | 'surface';
42
41
  }
43
- //#endregion
44
- //#region src/core/completion/shell.d.ts
45
42
  /**
46
43
  * Supported shell targets for completion script generation.
47
44
  *
@@ -58,8 +55,6 @@ type Shell = 'bash' | 'zsh' | 'fish' | 'powershell';
58
55
  * @see {@link Shell} for the union type matching these entries.
59
56
  */
60
57
  declare const SHELLS: Readonly<readonly ['bash', 'zsh', 'fish', 'powershell']>;
61
- //#endregion
62
- //#region src/core/cli/compiled.d.ts
63
58
  /**
64
59
  * Executable form of one registered command.
65
60
  */
@@ -84,8 +79,6 @@ interface CompiledCLI {
84
79
  /** Plugins in registration order. */
85
80
  readonly plugins: readonly CLIPlugin[];
86
81
  }
87
- //#endregion
88
- //#region src/core/cli/help-links.d.ts
89
82
  /**
90
83
  * OSC 8 hyperlink targets for the root-help header.
91
84
  *
@@ -98,8 +91,6 @@ interface HelpLinks {
98
91
  /** URL the version links to (e.g. the release tag). */
99
92
  readonly version: string | undefined;
100
93
  }
101
- //#endregion
102
- //#region src/core/cli/index.d.ts
103
94
  /**
104
95
  * Runtime descriptor for the CLI program.
105
96
  *
@@ -201,6 +192,16 @@ interface CLISchema {
201
192
  * releases its tokens to the commands.
202
193
  */
203
194
  readonly builtins: Builtins;
195
+ /**
196
+ * CLI-wide environment namespace prepended to every relative env binding
197
+ * (`undefined` when none is set). `.env('TOKEN')` reads `<envPrefix>TOKEN`;
198
+ * a binding declared with `{ absolute: true }` is read as written.
199
+ *
200
+ * Set via the {@linkcode CLIBuilder.envPrefix | .envPrefix()} builder method
201
+ * or the `envPrefix` field of {@link CLIDefinition}. Fixed when declared, so
202
+ * neither manifest name inference nor an inherited invocation name changes it.
203
+ */
204
+ readonly envPrefix: string | undefined;
204
205
  }
205
206
  /**
206
207
  * Options for {@link CLIBuilder.completions}: the generator options plus where
@@ -280,6 +281,17 @@ interface HelpConfig {
280
281
  * @defaultValue `undefined` (use `flagOrder`)
281
282
  */
282
283
  readonly sortFlags?: (a: string, b: string) => number;
284
+ /**
285
+ * Spelling of long flag names, aliases, and negations in the `Flags:` table.
286
+ *
287
+ * `'kebab'` shows `--wasm-path` for a flag keyed `wasmPath` while handlers
288
+ * keep reading `flags.wasmPath`. A spelling stays as declared when the
289
+ * parser would not accept its kebab form for the same flag, such as under
290
+ * `cli(name, { flags: { caseParity: false } })`.
291
+ *
292
+ * @defaultValue `'declared'`
293
+ */
294
+ readonly flagSpelling?: 'declared' | 'kebab';
283
295
  /**
284
296
  * Theme overrides for help output, merged over the built-in theme.
285
297
  *
@@ -466,6 +478,12 @@ interface CLIDefinition {
466
478
  * @defaultValue every built-in `'on'`
467
479
  */
468
480
  readonly builtins?: BuiltinsConfig | undefined;
481
+ /**
482
+ * CLI-wide environment namespace for relative env bindings, used verbatim
483
+ * (`'ACME_'` turns `TOKEN` into `ACME_TOKEN`).
484
+ * @defaultValue `undefined` (no namespace)
485
+ */
486
+ readonly envPrefix?: string | undefined;
469
487
  /**
470
488
  * Registered command definitions or built schemas, in registration order.
471
489
  * @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-YM5QGi3M.mjs";
2
- //#region src/core/config/package-json.d.ts
1
+ import { n as RuntimeAdapter } from "./adapter-DBeedKmD.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 };