@kjanat/dreamcli 4.2.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 (36) hide show
  1. package/README.md +3 -1
  2. package/dist/{adapter-DsmEc0WO.d.mts → adapter-DBeedKmD.d.mts} +1 -3
  3. package/dist/{completion-BYhuYn2Q.mjs → completion-Bh-qywmB.mjs} +1 -1
  4. package/dist/completion.d.mts +1 -11
  5. package/dist/completion.mjs +1 -1
  6. package/dist/{config-BgJZ-X4r.mjs → config-DruA8aFV.mjs} +1 -1
  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-CaRNJH2R.d.mts → index-AIC5Gler.d.mts} +14 -12
  11. package/dist/{index-B6oD4_8b.d.mts → index-BIMjOsR6.d.mts} +245 -44
  12. package/dist/{index-C5CYWtxn.d.mts → index-BidVVmln.d.mts} +45 -8
  13. package/dist/{index-B3_9MlHz.d.mts → index-D683D09G.d.mts} +0 -2
  14. package/dist/{index-B_1Dmsdq.d.mts → index-DpslpOVV.d.mts} +151 -21
  15. package/dist/{index-eF7SkQzQ.d.mts → index-hzYPRc_O.d.mts} +65 -14
  16. package/dist/{index-Cj7kXwQH.d.mts → index-jq_FJRKt.d.mts} +1 -7
  17. package/dist/index.d.mts +18 -12
  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/prompt.d.mts +2 -8
  23. package/dist/prompt.mjs +1 -1
  24. package/dist/runtime.d.mts +2 -2
  25. package/dist/runtime.mjs +1 -1
  26. package/dist/{session-CQsnVijE.mjs → session-Crtzt7LY.mjs} +1 -1
  27. package/dist/{terminal-cbye9mKF.mjs → terminal-DRsRn4sc.mjs} +1 -1
  28. package/dist/{test-prompter-Ddkt9n5A.mjs → test-prompter-BLNGCOA_.mjs} +1 -1
  29. package/dist/testkit.d.mts +5 -7
  30. package/dist/testkit.mjs +1 -1
  31. package/dist/version.d.mts +1 -3
  32. package/dist/version.mjs +1 -1
  33. package/dreamcli.schema.json +140 -2
  34. package/package.json +9 -9
  35. package/dist/core-B4Twhd48.mjs +0 -18
  36. package/dist/json-schema-DVyfq4bA.mjs +0 -52
@@ -1,5 +1,4 @@
1
1
  import { Colors, Formatter } from "ansispeck";
2
- //#region src/core/schema/brand.d.ts
3
2
  /**
4
3
  * Type-only seal for framework-normalized schema values.
5
4
  *
@@ -12,8 +11,6 @@ import { Colors, Formatter } from "ansispeck";
12
11
  * @module dreamcli/core/schema/brand
13
12
  */
14
13
  declare const schemaBrand: unique symbol;
15
- //#endregion
16
- //#region src/core/schema/activity.d.ts
17
14
  /**
18
15
  * Activity types — spinner and progress bar handles, options, events.
19
16
  *
@@ -200,8 +197,6 @@ interface TableOptionsText {
200
197
  }
201
198
  /** Per-call rendering options for {@link Out.table}. */
202
199
  type TableOptions = TableOptionsAuto | TableOptionsJson | TableOptionsText;
203
- //#endregion
204
- //#region src/core/help/theme.d.ts
205
200
  /**
206
201
  * Semantic styling roles for help output.
207
202
  *
@@ -251,8 +246,72 @@ type HelpDescription = string | ((theme: HelpTheme) => string);
251
246
  * unconditionally, gating is the framework's job.
252
247
  */
253
248
  type HelpThemeFactory = (colors: Colors) => Partial<HelpTheme>;
254
- //#endregion
255
- //#region src/core/schema/number-constraints.d.ts
249
+ /**
250
+ * An indexed env family whose entries are single values.
251
+ *
252
+ * ```text
253
+ * SERVER_COUNT=2 SERVER_0=a.example.com SERVER_1=b.example.com
254
+ * ```
255
+ *
256
+ * reads as `['a.example.com', 'b.example.com']`.
257
+ */
258
+ interface IndexedValueEnvBinding {
259
+ /**
260
+ * Variable holding how many entries the family declares, as a canonical
261
+ * non-negative integer. When it is unset the env source supplies nothing;
262
+ * `0` supplies an explicit empty list.
263
+ */
264
+ readonly count: string;
265
+ /** Variable template for one entry, with `{index}` standing for the zero-based index. */
266
+ readonly value: string;
267
+ /** Not available on a value family; see {@link IndexedRecordEnvBinding}. */
268
+ readonly fields?: never;
269
+ }
270
+ /**
271
+ * An indexed env family whose entries are records, one variable per field.
272
+ *
273
+ * ```text
274
+ * CONFIG_COUNT=1 CONFIG_KEY_0=user.name CONFIG_VALUE_0=Kaj
275
+ * ```
276
+ *
277
+ * with `fields: { key: 'CONFIG_KEY_{index}', value: 'CONFIG_VALUE_{index}' }`
278
+ * reads as `[{ key: 'user.name', value: 'Kaj' }]`.
279
+ */
280
+ interface IndexedRecordEnvBinding {
281
+ /**
282
+ * Variable holding how many entries the family declares, as a canonical
283
+ * non-negative integer. When it is unset the env source supplies nothing;
284
+ * `0` supplies an explicit empty list.
285
+ */
286
+ readonly count: string;
287
+ /**
288
+ * One variable template per record field, each with `{index}` standing for
289
+ * the zero-based index. Every field is required for every declared entry.
290
+ */
291
+ readonly fields: Readonly<Record<string, string>>;
292
+ /** Not available on a record family; see {@link IndexedValueEnvBinding}. */
293
+ readonly value?: never;
294
+ }
295
+ /**
296
+ * A numbered family of environment variables read as one input's env source.
297
+ *
298
+ * Pass it to `.env()` in place of a variable name. The count variable decides
299
+ * whether the env stage supplied a value at all, and how many entries it owns;
300
+ * a declared entry with a missing member is an error, never a fallback to a
301
+ * later source.
302
+ */
303
+ type IndexedEnvBinding = IndexedValueEnvBinding | IndexedRecordEnvBinding;
304
+ /** Options accepted by `.env()` beside the variable name or indexed binding. */
305
+ interface EnvOptions {
306
+ /**
307
+ * Read the name exactly as written, ignoring the CLI-wide namespace set by
308
+ * `CLIBuilder.envPrefix()`. Use it for variables the CLI does not own, such
309
+ * as `HOME`, `CI`, or a credential another tool exports.
310
+ *
311
+ * @defaultValue `false` (the name is relative to the CLI namespace)
312
+ */
313
+ readonly absolute?: boolean;
314
+ }
256
315
  /**
257
316
  * Numeric constraints for number-valued flags and args.
258
317
  *
@@ -309,8 +368,6 @@ type NumberConstraintViolation = {
309
368
  readonly kind: 'max';
310
369
  readonly bound: number;
311
370
  };
312
- //#endregion
313
- //#region src/core/schema/prompt.d.ts
314
371
  /**
315
372
  * Prompt type definitions for interactive flag resolution.
316
373
  *
@@ -461,8 +518,6 @@ type PromptResult = {
461
518
  /** Retry exhaustion; omitted for cancellation or EOF. */
462
519
  readonly reason?: 'invalid';
463
520
  };
464
- //#endregion
465
- //#region src/core/schema/standard.d.ts
466
521
  /**
467
522
  * The Standard Schema v1 interface, vendored as types only.
468
523
  *
@@ -553,8 +608,6 @@ type StandardSchemaV1Types<Input = unknown, Output = Input> = StandardSchemaV1.T
553
608
  type InferStandardInput<Schema extends StandardSchemaV1> = StandardSchemaV1.InferInput<Schema>;
554
609
  /** Flat alias for {@link StandardSchemaV1.InferOutput}. */
555
610
  type InferStandardOutput<Schema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<Schema>;
556
- //#endregion
557
- //#region src/core/schema/stdin.d.ts
558
611
  /**
559
612
  * The stdin binding shared by the `flag` and `arg` factories.
560
613
  *
@@ -618,8 +671,6 @@ interface StdinOptions {
618
671
  */
619
672
  readonly trim?: boolean | undefined;
620
673
  }
621
- //#endregion
622
- //#region src/core/schema/string-constraints.d.ts
623
674
  /**
624
675
  * String constraints for string-valued flags.
625
676
  *
@@ -679,8 +730,6 @@ type StringConstraintViolation = {
679
730
  readonly kind: 'pattern';
680
731
  readonly pattern: string;
681
732
  };
682
- //#endregion
683
- //#region src/core/schema/value-parsers.d.ts
684
733
  /**
685
734
  * Value-level machinery behind the sugar factories on both `flag` and `arg`
686
735
  * (`url()`, `path()`, `date()`, `duration()`, `bytes()`).
@@ -774,8 +823,6 @@ interface PathChecks {
774
823
  /** Create the directory (recursively) when nothing exists at the path. */
775
824
  readonly create: boolean;
776
825
  }
777
- //#endregion
778
- //#region src/core/schema/flag.d.ts
779
826
  /** All flag presence states as a runtime array. */
780
827
  declare const FLAG_PRESENCES: readonly ["optional", "required", "defaulted"];
781
828
  /**
@@ -988,6 +1035,26 @@ interface FlagSchema<K extends FlagKind = FlagKind> {
988
1035
  readonly stdin: StdinBinding | undefined;
989
1036
  /** Environment variable name for v0.2+ resolution. */
990
1037
  readonly envVar: string | undefined;
1038
+ /**
1039
+ * Indexed environment family read as the env source, set by `.env()` with an
1040
+ * {@link IndexedEnvBinding} (`undefined` otherwise). A flag declares at most
1041
+ * one env source, so this and {@link FlagSchema.envVar} are never both set.
1042
+ */
1043
+ readonly envIndexed: IndexedEnvBinding | undefined;
1044
+ /**
1045
+ * Whether the env source is read exactly as written, outside the CLI-wide
1046
+ * namespace set by `CLIBuilder.envPrefix()` (set by `.env(…, { absolute:
1047
+ * true })`). Applies to {@link FlagSchema.envVar} and
1048
+ * {@link FlagSchema.envIndexed} alike.
1049
+ *
1050
+ * @defaultValue `false`
1051
+ */
1052
+ readonly envAbsolute: boolean;
1053
+ /**
1054
+ * Whether `.env()` was called without a name. Registration on a command
1055
+ * replaces it with the derived {@link FlagSchema.envVar}.
1056
+ */
1057
+ readonly envFromName: boolean;
991
1058
  /** Dotted config path for v0.2+ resolution (e.g. `'deploy.region'`). */
992
1059
  readonly configPath: string | undefined;
993
1060
  /** Human-readable description for help text. */
@@ -1144,6 +1211,23 @@ interface FlagDefinitionBase {
1144
1211
  * @defaultValue `undefined`
1145
1212
  */
1146
1213
  readonly envVar?: string | undefined;
1214
+ /**
1215
+ * Indexed environment family read as the env source, in place of
1216
+ * {@link FlagDefinitionBase.envVar}. Requires kind `'array'` or `'custom'`.
1217
+ * @defaultValue `undefined`
1218
+ */
1219
+ readonly envIndexed?: IndexedEnvBinding | undefined;
1220
+ /**
1221
+ * Read the env source exactly as written, outside the CLI-wide namespace.
1222
+ * Requires `envVar` or `envIndexed`.
1223
+ * @defaultValue `false`
1224
+ */
1225
+ readonly envAbsolute?: boolean | undefined;
1226
+ /**
1227
+ * Derive `envVar` from the registered name.
1228
+ * @defaultValue `false`
1229
+ */
1230
+ readonly envFromName?: boolean | undefined;
1147
1231
  /**
1148
1232
  * Dotted config path for config resolution (e.g. `'deploy.region'`).
1149
1233
  * @defaultValue `undefined`
@@ -1490,7 +1574,12 @@ declare class FlagBuilder<C extends FlagConfig> {
1490
1574
  * The env value is read after CLI and stdin, and before config, the prompt,
1491
1575
  * and the default: CLI → stdin → **env** → config → prompt → default.
1492
1576
  *
1577
+ * Under a CLI-wide namespace (`CLIBuilder.envPrefix()`) the name is relative:
1578
+ * `.env('TOKEN')` in `cli('foo').envPrefix()` reads `FOO_TOKEN`. Pass
1579
+ * `{ absolute: true }` to read the name exactly as written.
1580
+ *
1493
1581
  * @param varName - Environment variable name (e.g. `'PORT'`).
1582
+ * @param options - Whether the name ignores the CLI namespace.
1494
1583
  * @returns The builder (for chaining).
1495
1584
  *
1496
1585
  * @example
@@ -1499,9 +1588,57 @@ declare class FlagBuilder<C extends FlagConfig> {
1499
1588
  *
1500
1589
  * // $ API_KEY=sk-123 mycli request → apiKey = 'sk-123'
1501
1590
  * // $ mycli request --api-key sk-456 → apiKey = 'sk-456' (CLI wins)
1591
+ *
1592
+ * flag.path().env('HOME', { absolute: true }) // never namespaced
1502
1593
  * ```
1503
1594
  */
1504
- env(varName: string): FlagBuilder<WithoutElementEligibility<C>>;
1595
+ env(varName: string, options?: EnvOptions): FlagBuilder<WithoutElementEligibility<C>>;
1596
+ /**
1597
+ * Bind to an indexed family of environment variables, read as one env source.
1598
+ *
1599
+ * The count variable owns indices `0..count-1`; `{index}` in each template
1600
+ * expands to the zero-based index. An unset count means the env source
1601
+ * supplied nothing, so resolution continues to config, the prompt, and the
1602
+ * default. A set count claims the flag: `0` resolves an empty list, and a
1603
+ * malformed count or a missing member is an error, never a fallback.
1604
+ *
1605
+ * A `value` family reads a list of strings, so it suits `flag.array()` (each
1606
+ * entry decoded by the element) and `flag.custom()` (handed the whole list).
1607
+ * A `fields` family reads a list of records, one variable per field, so it
1608
+ * suits `flag.array(flag.custom(...))` and `flag.custom()`.
1609
+ *
1610
+ * Under a CLI-wide namespace the count and every template are relative, the
1611
+ * same as a single name; `{ absolute: true }` reads them as written.
1612
+ *
1613
+ * @param binding - The count variable plus a `value` template or `fields` templates.
1614
+ * @param options - Whether the names ignore the CLI namespace.
1615
+ * @returns The builder (for chaining).
1616
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on a malformed template or a
1617
+ * flag kind that cannot hold a list.
1618
+ *
1619
+ * @example
1620
+ * ```ts
1621
+ * flag.array(flag.string()).env({ count: 'SERVER_COUNT', value: 'SERVER_{index}' })
1622
+ * // SERVER_COUNT=2 SERVER_0=a SERVER_1=b → ['a', 'b']
1623
+ *
1624
+ * flag.custom(gitConfigEntries).env({
1625
+ * count: 'GIT_CONFIG_COUNT',
1626
+ * fields: { key: 'GIT_CONFIG_KEY_{index}', value: 'GIT_CONFIG_VALUE_{index}' },
1627
+ * })
1628
+ * // GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=user.name GIT_CONFIG_VALUE_0=Kaj
1629
+ * // → gitConfigEntries receives [{ key: 'user.name', value: 'Kaj' }]
1630
+ * ```
1631
+ */
1632
+ env(binding: IndexedEnvBinding, options?: EnvOptions): FlagBuilder<WithoutElementEligibility<C>>;
1633
+ /**
1634
+ * Bind to an environment variable derived from this input's registered
1635
+ * name (`api-token` and `apiToken` → `API_TOKEN`), relative to the CLI
1636
+ * namespace unless `{ absolute: true }`.
1637
+ *
1638
+ * @param options - Whether the derived name ignores the CLI namespace.
1639
+ * @returns The builder (for chaining).
1640
+ */
1641
+ env(options?: EnvOptions): FlagBuilder<WithoutElementEligibility<C>>;
1505
1642
  /**
1506
1643
  * Let this flag read its value from piped stdin.
1507
1644
  *
@@ -2272,8 +2409,6 @@ interface FlagFactory {
2272
2409
  * {@link FlagBuilder} with full type inference and safe modifier chaining.
2273
2410
  */
2274
2411
  declare const flag: FlagFactory;
2275
- //#endregion
2276
- //#region src/core/schema/cardinality.d.ts
2277
2412
  /** All split formats as a runtime array. */
2278
2413
  declare const SPLIT_FORMATS: readonly ["whole", "delimiter", "lines", "json"];
2279
2414
  /** How one source's text decodes into collection elements. */
@@ -2359,8 +2494,6 @@ declare const DUPLICATE_KEYS: readonly ["first", "last", "error"];
2359
2494
  * @defaultValue `'last'`
2360
2495
  */
2361
2496
  type DuplicateKeys = (typeof DUPLICATE_KEYS)[number];
2362
- //#endregion
2363
- //#region src/core/schema/arg.d.ts
2364
2497
  /** All arg presence states as a runtime array. */
2365
2498
  declare const ARG_PRESENCES: readonly ["required", "optional", "defaulted"];
2366
2499
  /**
@@ -2539,6 +2672,28 @@ interface ArgSchema<K extends ArgKind = ArgKind> {
2539
2672
  * @see {@link ArgBuilder.env} for the builder method.
2540
2673
  */
2541
2674
  readonly envVar: string | undefined;
2675
+ /**
2676
+ * Indexed environment family read as the env source, set by `.env()` with an
2677
+ * {@link IndexedEnvBinding} (`undefined` otherwise). An arg declares at most
2678
+ * one env source, so this and {@link ArgSchema.envVar} are never both set.
2679
+ *
2680
+ * @see {@link ArgBuilder.env} for the builder method.
2681
+ */
2682
+ readonly envIndexed: IndexedEnvBinding | undefined;
2683
+ /**
2684
+ * Whether the env source is read exactly as written, outside the CLI-wide
2685
+ * namespace set by `CLIBuilder.envPrefix()` (set by `.env(…, { absolute:
2686
+ * true })`). Applies to {@link ArgSchema.envVar} and
2687
+ * {@link ArgSchema.envIndexed} alike.
2688
+ *
2689
+ * @defaultValue `false`
2690
+ */
2691
+ readonly envAbsolute: boolean;
2692
+ /**
2693
+ * Whether `.env()` was called without a name. Registration on a command
2694
+ * replaces it with the derived {@link ArgSchema.envVar}.
2695
+ */
2696
+ readonly envFromName: boolean;
2542
2697
  /**
2543
2698
  * Dotted config path for config resolution (e.g. `'deploy.region'`).
2544
2699
  *
@@ -2691,6 +2846,24 @@ interface ArgDefinitionBase {
2691
2846
  * @defaultValue `undefined`
2692
2847
  */
2693
2848
  readonly envVar?: string | undefined;
2849
+ /**
2850
+ * Indexed environment family read as the env source, in place of
2851
+ * {@link ArgDefinitionBase.envVar}. Requires a variadic arg, or a custom arg
2852
+ * without a string parse function.
2853
+ * @defaultValue `undefined`
2854
+ */
2855
+ readonly envIndexed?: IndexedEnvBinding | undefined;
2856
+ /**
2857
+ * Read the env source exactly as written, outside the CLI-wide namespace.
2858
+ * Requires `envVar` or `envIndexed`.
2859
+ * @defaultValue `false`
2860
+ */
2861
+ readonly envAbsolute?: boolean | undefined;
2862
+ /**
2863
+ * Derive `envVar` from the registered name.
2864
+ * @defaultValue `false`
2865
+ */
2866
+ readonly envFromName?: boolean | undefined;
2694
2867
  /**
2695
2868
  * Dotted config path for config resolution (e.g. `'deploy.region'`).
2696
2869
  * @defaultValue `undefined`
@@ -3191,7 +3364,12 @@ declare class ArgBuilder<C extends ArgConfig> {
3191
3364
  *
3192
3365
  * Help output shows `[env: VAR]` next to the arg description.
3193
3366
  *
3367
+ * Under a CLI-wide namespace (`CLIBuilder.envPrefix()`) the name is relative:
3368
+ * `.env('TARGET')` in `cli('foo').envPrefix()` reads `FOO_TARGET`. Pass
3369
+ * `{ absolute: true }` to read the name exactly as written.
3370
+ *
3194
3371
  * @param varName - Environment variable name (e.g. `'DEPLOY_TARGET'`).
3372
+ * @param options - Whether the name ignores the CLI namespace.
3195
3373
  * @returns The builder (for chaining).
3196
3374
  *
3197
3375
  * @example
@@ -3205,7 +3383,34 @@ declare class ArgBuilder<C extends ArgConfig> {
3205
3383
  * });
3206
3384
  * ```
3207
3385
  */
3208
- env(varName: string): ArgBuilder<WithoutArgElementEligibility<C>>;
3386
+ env(varName: string, options?: EnvOptions): ArgBuilder<WithoutArgElementEligibility<C>>;
3387
+ /**
3388
+ * Bind to an indexed family of environment variables, read as one env
3389
+ * source; see `FlagBuilder.env()` for the count and template rules. A
3390
+ * `value` family needs a variadic arg (call `.variadic()` first), and a
3391
+ * `fields` family a Standard Schema `arg.custom()`.
3392
+ *
3393
+ * @param binding - The count variable plus a `value` template or `fields` templates.
3394
+ * @param options - Whether the names ignore the CLI namespace.
3395
+ * @returns The builder (for chaining).
3396
+ * @throws {CLIError} With code `'INVALID_SCHEMA'` on a malformed template or an
3397
+ * arg that cannot hold a list.
3398
+ *
3399
+ * @example
3400
+ * ```ts
3401
+ * arg.string().variadic().env({ count: 'FILE_COUNT', value: 'FILE_{index}' })
3402
+ * ```
3403
+ */
3404
+ env(binding: IndexedEnvBinding, options?: EnvOptions): ArgBuilder<WithoutArgElementEligibility<C>>;
3405
+ /**
3406
+ * Bind to an environment variable derived from this input's registered
3407
+ * name (`api-token` and `apiToken` → `API_TOKEN`), relative to the CLI
3408
+ * namespace unless `{ absolute: true }`.
3409
+ *
3410
+ * @param options - Whether the derived name ignores the CLI namespace.
3411
+ * @returns The builder (for chaining).
3412
+ */
3413
+ env(options?: EnvOptions): ArgBuilder<WithoutArgElementEligibility<C>>;
3209
3414
  /**
3210
3415
  * Bind to a dotted config path.
3211
3416
  *
@@ -3840,14 +4045,10 @@ interface ArgFactory {
3840
4045
  * ```
3841
4046
  */
3842
4047
  declare const arg: ArgFactory;
3843
- //#endregion
3844
- //#region src/core/output/contracts.d.ts
3845
4048
  /** Ordered output verbosity levels owned by the output policy layer. */
3846
4049
  declare const OUTPUT_VERBOSITY_LEVELS: readonly ["normal", "quiet"];
3847
4050
  /** Stable text verbosity labels. */
3848
4051
  type Verbosity = (typeof OUTPUT_VERBOSITY_LEVELS)[number];
3849
- //#endregion
3850
- //#region src/core/prompt/definitions.d.ts
3851
4052
  /** Infer an answer, preserving literal choice values. */
3852
4053
  type InferPrompt<C extends PromptConfig> = C extends ConfirmPromptConfig ? boolean : C extends {
3853
4054
  readonly kind: 'multiselect';
@@ -3879,8 +4080,6 @@ declare const prompt: {
3879
4080
  kind: 'multiselect';
3880
4081
  };
3881
4082
  };
3882
- //#endregion
3883
- //#region src/core/schema/middleware.d.ts
3884
4083
  /**
3885
4084
  * Parameters received by a middleware function at runtime.
3886
4085
  *
@@ -4010,8 +4209,6 @@ type Middleware<Output extends Record<string, unknown>> = MiddlewareImpl & {
4010
4209
  * ```
4011
4210
  */
4012
4211
  declare function middleware<Output extends Record<string, unknown>>(handler: MiddlewareHandler<Output>): Middleware<Output>;
4013
- //#endregion
4014
- //#region src/core/schema/provenance.d.ts
4015
4212
  /**
4016
4213
  * Where a resolved value came from.
4017
4214
  *
@@ -4030,13 +4227,21 @@ declare function middleware<Output extends Record<string, unknown>>(handler: Mid
4030
4227
  * 'dash' }`; an absent input takes the fallback stage between CLI and env and
4031
4228
  * reports `{ stage: 'stdin', via: 'stdin', trigger: 'fallback' }`.
4032
4229
  *
4230
+ * The `'env'` stage is two records the same way. A variable bound by name
4231
+ * reports `{ stage: 'env', envVar }`, the one concrete variable that supplied
4232
+ * the value. An indexed family bound with an `IndexedEnvBinding` reports
4233
+ * `{ stage: 'env', via: 'indexed', count, envVars }`: the count variable that
4234
+ * claimed the input and every member variable read, in entry order and, within
4235
+ * an entry, in field order. `envVars` is empty when the count is `0`. Test
4236
+ * `'envVar' in source` (or `source.via`) before reading either shape's fields.
4237
+ *
4033
4238
  * @example
4034
4239
  * ```ts
4035
4240
  * command('deploy')
4036
4241
  * .flag('region', flag.string().env('REGION').default('us'))
4037
4242
  * .action(({ sources }) => {
4038
4243
  * const region = sources.flags.region;
4039
- * if (region?.stage === 'env') console.log(`from ${region.envVar}`);
4244
+ * if (region?.stage === 'env' && 'envVar' in region) console.log(`from ${region.envVar}`);
4040
4245
  * });
4041
4246
  * ```
4042
4247
  */
@@ -4053,6 +4258,11 @@ type ResolutionProvenance = {
4053
4258
  } | {
4054
4259
  readonly stage: 'env';
4055
4260
  readonly envVar: string;
4261
+ } | {
4262
+ readonly stage: 'env';
4263
+ readonly via: 'indexed';
4264
+ readonly count: string;
4265
+ readonly envVars: readonly string[];
4056
4266
  } | {
4057
4267
  readonly stage: 'config';
4058
4268
  readonly configPath: string;
@@ -4108,8 +4318,6 @@ interface InputSources<F, A> {
4108
4318
  * ```
4109
4319
  */
4110
4320
  declare function wasExplicit(source: ResolutionProvenance | undefined): boolean;
4111
- //#endregion
4112
- //#region src/core/schema/command.d.ts
4113
4321
  /**
4114
4322
  * Widen the context type when adding middleware.
4115
4323
  *
@@ -5220,8 +5428,6 @@ declare function command(name: string): CommandBuilder;
5220
5428
  * @returns A fresh {@link CommandBuilder} with empty flags, args, and context.
5221
5429
  */
5222
5430
  declare function group(name: string): CommandBuilder;
5223
- //#endregion
5224
- //#region src/core/prompt/index.d.ts
5225
5431
  /**
5226
5432
  * A select prompt config with choices guaranteed non-empty.
5227
5433
  *
@@ -5322,8 +5528,6 @@ type ReadFn = () => Promise<string | null>;
5322
5528
  * @throws Error if select/multiselect has no choices and no enum values
5323
5529
  */
5324
5530
  declare function resolvePromptConfig(config: PromptConfig, enumValues: readonly string[] | undefined): ResolvedPromptConfig;
5325
- //#endregion
5326
- //#region src/core/output/writer.d.ts
5327
5531
  /**
5328
5532
  * Minimal I/O seam — the only write primitive the output module depends on.
5329
5533
  *
@@ -5353,8 +5557,6 @@ declare function resolvePromptConfig(config: PromptConfig, enumValues: readonly
5353
5557
  * ```
5354
5558
  */
5355
5559
  type WriteFn = (data: string) => void;
5356
- //#endregion
5357
- //#region src/core/output/index.d.ts
5358
5560
  /**
5359
5561
  * Configuration for creating an output channel.
5360
5562
  *
@@ -5498,5 +5700,4 @@ interface CapturedOutput {
5498
5700
  * ```
5499
5701
  */
5500
5702
  declare function createCaptureOutput(options?: Omit<OutputOptions, 'stdout' | 'stderr'>): [out: Out, captured: CapturedOutput];
5501
- //#endregion
5502
- export { ArgDefinitionOverrides as $, StringElementConfig as $t, Out as A, PasswordPromptConfig as An, BooleanFlagDefinition as At, MiddlewareHandler as B, HelpTheme as Bn, FlagDefinitionByKind as Bt, ErasedActionHandler as C, StandardSchemaV1Props as Cn, SourceSplitBinding as Ct, InteractiveParams as D, ConfirmPromptConfig as Dn, SplitPolicy as Dt, ExecutionStep as E, StandardSchemaV1Types as En, SplitOptions as Et, InputSources as F, SelectChoice as Fn, EnumFlagDefinition as Ft, prompt as G, ProgressOptions as Gn, FlagParseFn as Gt, middleware as H, ActivityEvent as Hn, FlagFactory as Ht, ResolutionProvenance as I, SelectPromptConfig as In, FlagBuilder as It, ArgConfig as J, TableColumn as Jn, InferFlag as Jt, Verbosity as K, SpinnerHandle as Kn, FlagPresence as Kt, SourcesOf as L, NumberConstraintViolation as Ln, FlagConfig as Lt, createCommandSchema as M, PromptConfigBase as Mn, CustomFlagDefinition as Mt, group as N, PromptKind as Nn, DefaultValueOptions as Nt, InteractiveResolver as O, InputPromptConfig as On, SplitSetting as Ot, resolveExampleCommand as P, PromptResult as Pn, DuplicatePolicy as Pt, ArgDefinitionByKind as Q, schemaBrand as Qn, ResolvedValue as Qt, wasExplicit as R, NumberConstraints as Rn, FlagDefinition as Rt, DeriveParams as S, StandardSchemaV1PathSegment as Sn, SPLIT_FORMATS as St, ExampleMeta as T, StandardSchemaV1SuccessResult as Tn, SplitFormat as Tt, Ask as U, Fallback as Un, FlagKind as Ut, MiddlewareParams as V, HelpThemeFactory as Vn, FlagDefinitionOverrides as Vt, InferPrompt as W, ProgressHandle as Wn, FlagNegation as Wt, ArgDefinition as X, TableOptions as Xn, KeyValueFlagDefinition as Xt, ArgDefaultValue as Y, TableFormat as Yn, InferFlags as Yt, ArgDefinitionBase as Z, TableStream as Zn, NumberFlagDefinition as Zt, CommandDefinition as _, InferStandardOutput as _n, WithoutArgElementEligibility as _t, WriteFn as a, getFlagNegatedName as an, BooleanArgDefinition as at, CommandSchema as b, StandardSchemaV1Issue as bn, DUPLICATE_KEYS as bt, ResolvedMultiselectPromptConfig as c, PathFlagOptions as cn, InferArg as ct, resolvePromptConfig as d, StringConstraints as dn, NumberArgDefinition as dt, StringFlagDefinition as en, ArgFactory as et, ActionHandler as f, StdinBinding as fn, ResolvedArgValue as ft, CommandBuilder as g, InferStandardInput as gn, WithVariadic as gt, CommandArgEntryDefinition as h, StdinWhen as hn, WithArgPresence as ht, createOutput as i, flag as in, ArgSchema as it, command as j, PromptConfig as jn, CountFlagDefinition as jt, InteractiveResult as k, MultiselectPromptConfig as kn, ArrayFlagDefinition as kt, ResolvedPromptConfig as l, UrlFlagOptions as ln, InferArgs as lt, CommandArgEntry as m, StdinOptions as mn, StringArgElementConfig as mt, OutputOptions as n, WithoutElementEligibility as nn, ArgParseFn as nt, PromptEngine as o, DateFlagOptions as on, CustomArgDefinition as ot, ActionParams as p, StdinConsume as pn, StringArgDefinition as pt, ArgBuilder as q, SpinnerOptions as qn, FlagSchema as qt, createCaptureOutput as r, createFlagSchema as rn, ArgPresence as rt, ReadFn as s, PathChecks as sn, EnumArgDefinition as st, CapturedOutput as t, WithPresence as tn, ArgKind as tt, ResolvedSelectPromptConfig as u, StringConstraintViolation as un, KeyValueArgDefinition as ut, CommandExample as v, StandardSchemaV1 as vn, arg as vt, ExampleCommand as w, StandardSchemaV1Result as wn, SplitBinding as wt, DeriveHandler as x, StandardSchemaV1Options as xn, DuplicateKeys as xt, CommandMeta as y, StandardSchemaV1FailureResult as yn, createArgSchema as yt, Middleware as z, HelpDescription as zn, FlagDefinitionBase as zt };
5703
+ export { ArgDefinitionOverrides as $, TableFormat as $n, StringElementConfig as $t, Out as A, PasswordPromptConfig as An, BooleanFlagDefinition as At, MiddlewareHandler as B, IndexedEnvBinding as Bn, FlagDefinitionByKind as Bt, ErasedActionHandler as C, StandardSchemaV1Props as Cn, SourceSplitBinding as Ct, InteractiveParams as D, ConfirmPromptConfig as Dn, SplitPolicy as Dt, ExecutionStep as E, StandardSchemaV1Types as En, SplitOptions as Et, InputSources as F, SelectChoice as Fn, EnumFlagDefinition as Ft, prompt as G, HelpThemeFactory as Gn, FlagParseFn as Gt, middleware as H, IndexedValueEnvBinding as Hn, FlagFactory as Ht, ResolutionProvenance as I, SelectPromptConfig as In, FlagBuilder as It, ArgConfig as J, ProgressHandle as Jn, InferFlag as Jt, Verbosity as K, ActivityEvent as Kn, FlagPresence as Kt, SourcesOf as L, NumberConstraintViolation as Ln, FlagConfig as Lt, createCommandSchema as M, PromptConfigBase as Mn, CustomFlagDefinition as Mt, group as N, PromptKind as Nn, DefaultValueOptions as Nt, InteractiveResolver as O, InputPromptConfig as On, SplitSetting as Ot, resolveExampleCommand as P, PromptResult as Pn, DuplicatePolicy as Pt, ArgDefinitionByKind as Q, TableColumn as Qn, ResolvedValue as Qt, wasExplicit as R, NumberConstraints as Rn, FlagDefinition as Rt, DeriveParams as S, StandardSchemaV1PathSegment as Sn, SPLIT_FORMATS as St, ExampleMeta as T, StandardSchemaV1SuccessResult as Tn, SplitFormat as Tt, Ask as U, HelpDescription as Un, FlagKind as Ut, MiddlewareParams as V, IndexedRecordEnvBinding as Vn, FlagDefinitionOverrides as Vt, InferPrompt as W, HelpTheme as Wn, FlagNegation as Wt, ArgDefinition as X, SpinnerHandle as Xn, KeyValueFlagDefinition as Xt, ArgDefaultValue as Y, ProgressOptions as Yn, InferFlags as Yt, ArgDefinitionBase as Z, SpinnerOptions as Zn, NumberFlagDefinition as Zt, CommandDefinition as _, InferStandardOutput as _n, WithoutArgElementEligibility as _t, WriteFn as a, getFlagNegatedName as an, BooleanArgDefinition as at, CommandSchema as b, StandardSchemaV1Issue as bn, DUPLICATE_KEYS as bt, ResolvedMultiselectPromptConfig as c, PathFlagOptions as cn, InferArg as ct, resolvePromptConfig as d, StringConstraints as dn, NumberArgDefinition as dt, StringFlagDefinition as en, TableOptions as er, ArgFactory as et, ActionHandler as f, StdinBinding as fn, ResolvedArgValue as ft, CommandBuilder as g, InferStandardInput as gn, WithVariadic as gt, CommandArgEntryDefinition as h, StdinWhen as hn, WithArgPresence as ht, createOutput as i, flag as in, ArgSchema as it, command as j, PromptConfig as jn, CountFlagDefinition as jt, InteractiveResult as k, MultiselectPromptConfig as kn, ArrayFlagDefinition as kt, ResolvedPromptConfig as l, UrlFlagOptions as ln, InferArgs as lt, CommandArgEntry as m, StdinOptions as mn, StringArgElementConfig as mt, OutputOptions as n, WithoutElementEligibility as nn, schemaBrand as nr, ArgParseFn as nt, PromptEngine as o, DateFlagOptions as on, CustomArgDefinition as ot, ActionParams as p, StdinConsume as pn, StringArgDefinition as pt, ArgBuilder as q, Fallback as qn, FlagSchema as qt, createCaptureOutput as r, createFlagSchema as rn, ArgPresence as rt, ReadFn as s, PathChecks as sn, EnumArgDefinition as st, CapturedOutput as t, WithPresence as tn, TableStream as tr, ArgKind as tt, ResolvedSelectPromptConfig as u, StringConstraintViolation as un, KeyValueArgDefinition as ut, CommandExample as v, StandardSchemaV1 as vn, arg as vt, ExampleCommand as w, StandardSchemaV1Result as wn, SplitBinding as wt, DeriveHandler as x, StandardSchemaV1Options as xn, DuplicateKeys as xt, CommandMeta as y, StandardSchemaV1FailureResult as yn, createArgSchema as yt, Middleware as z, EnvOptions as zn, FlagDefinitionBase as zt };
@@ -1,7 +1,6 @@
1
- import { Kt as FlagPresence, Nn as PromptKind, Pt as DuplicatePolicy, Rn as NumberConstraints, T as ExampleMeta, Ut as FlagKind, b as CommandSchema, rt as ArgPresence, tt as ArgKind, xt as DuplicateKeys } from "./index-B6oD4_8b.mjs";
2
- import "./index-B_1Dmsdq.mjs";
3
- import { o as CLISchema } from "./index-eF7SkQzQ.mjs";
4
- //#region src/core/json-schema/constants.d.ts
1
+ import { Kt as FlagPresence, Nn as PromptKind, Pt as DuplicatePolicy, Rn as NumberConstraints, T as ExampleMeta, Ut as FlagKind, b as CommandSchema, rt as ArgPresence, tt as ArgKind, xt as DuplicateKeys } from "./index-BIMjOsR6.mjs";
2
+ import "./index-DpslpOVV.mjs";
3
+ import { o as CLISchema } from "./index-hzYPRc_O.mjs";
5
4
  /**
6
5
  * Identifiers of the definition document format.
7
6
  *
@@ -24,8 +23,6 @@ declare const DEFINITION_SCHEMA_URL = "https://dreamcli.kjanat.dev/schemas/defin
24
23
  * and `generateCommandSchema()` from `@kjanat/dreamcli/json-schema`.
25
24
  */
26
25
  declare const DEFINITION_SCHEMA_VERSION = 1;
27
- //#endregion
28
- //#region src/core/json-schema/index.d.ts
29
26
  /**
30
27
  * Options for JSON Schema generation.
31
28
  *
@@ -56,6 +53,17 @@ interface JsonSchemaOptions {
56
53
  * @defaultValue `true`
57
54
  */
58
55
  readonly includePrompts?: boolean;
56
+ /**
57
+ * CLI-wide env namespace recorded on the document, so a reader can tell
58
+ * `envVar: 'TOKEN'` that reads `FOO_TOKEN` from one that reads `TOKEN`.
59
+ *
60
+ * {@link generateSchema} defaults it to the CLI schema's own `envPrefix`.
61
+ * {@link generateCommandSchema} has no CLI to read it from, so pass the
62
+ * namespace the command runs under; `--help --json` does this itself.
63
+ *
64
+ * @defaultValue the CLI's `envPrefix` for {@link generateSchema}, none otherwise
65
+ */
66
+ readonly envPrefix?: string;
59
67
  }
60
68
  /**
61
69
  * A usage example inside a definition document.
@@ -143,6 +151,21 @@ type FlagStringConstraintsFragmentV1 = {
143
151
  readonly flags: string;
144
152
  };
145
153
  };
154
+ /**
155
+ * Indexed environment family of a flag or arg fragment, in place of `envVar`.
156
+ *
157
+ * `count` names the variable holding the number of entries. A `value` family
158
+ * reads one variable per entry; a `fields` family reads one variable per record
159
+ * field, in the order written. Every template carries `{index}`, which expands
160
+ * to the zero-based entry index.
161
+ */
162
+ type EnvIndexedFragmentV1 = {
163
+ readonly count: string;
164
+ readonly value: string;
165
+ } | {
166
+ readonly count: string;
167
+ readonly fields: Readonly<Record<string, string>>;
168
+ };
146
169
  /** Filesystem expectations of a flag or arg fragment. */
147
170
  type FlagPathChecksFragmentV1 = {
148
171
  readonly mustExist: boolean;
@@ -157,6 +180,8 @@ type FlagElementFragmentV1 = {
157
180
  readonly aliases?: readonly string[];
158
181
  readonly stdin?: StdinBindingFragmentV1;
159
182
  readonly envVar?: string;
183
+ readonly envIndexed?: EnvIndexedFragmentV1;
184
+ readonly envAbsolute?: true;
160
185
  readonly configPath?: string;
161
186
  readonly description?: string;
162
187
  readonly enumValues?: readonly string[];
@@ -218,6 +243,8 @@ type ArgDefinitionFragmentV1 = {
218
243
  readonly sensitive?: true;
219
244
  readonly description?: string;
220
245
  readonly envVar?: string;
246
+ readonly envIndexed?: EnvIndexedFragmentV1;
247
+ readonly envAbsolute?: true;
221
248
  readonly configPath?: string;
222
249
  readonly enumValues?: readonly string[];
223
250
  readonly elementSchema?: ArgElementFragmentV1;
@@ -268,6 +295,12 @@ type DefinitionDocumentV1 = {
268
295
  readonly name: string;
269
296
  readonly version?: string;
270
297
  readonly description?: string;
298
+ /**
299
+ * CLI-wide env namespace. Each relative `envVar`, and each count and
300
+ * template of a relative `envIndexed`, reads with this prefix prepended; a
301
+ * fragment marked `envAbsolute` reads its names as written.
302
+ */
303
+ readonly envPrefix?: string;
271
304
  readonly defaultCommand?: CommandDefinitionFragmentV1;
272
305
  readonly commands: readonly CommandDefinitionFragmentV1[];
273
306
  };
@@ -281,6 +314,11 @@ type DefinitionDocumentV1 = {
281
314
  type CommandDefinitionDocumentV1 = CommandDefinitionFragmentV1 & {
282
315
  /** Definition document format version. */
283
316
  readonly schemaVersion: 1;
317
+ /**
318
+ * CLI-wide env namespace the command runs under, read the same way as
319
+ * {@link DefinitionDocumentV1.envPrefix}.
320
+ */
321
+ readonly envPrefix?: string;
284
322
  };
285
323
  /** The current whole-CLI definition document. */
286
324
  type DefinitionDocument = DefinitionDocumentV1;
@@ -398,5 +436,4 @@ declare function generateInputSchema(schema: CLISchema | CommandSchema, options?
398
436
  * ```
399
437
  */
400
438
  declare const definitionMetaSchema: Record<string, unknown>;
401
- //#endregion
402
- export { definitionMetaSchema as C, DEFINITION_SCHEMA_URL as D, generateSchema as E, DEFINITION_SCHEMA_VERSION as O, StdinBindingFragmentV1 as S, generateInputSchema as T, JsonSchemaOptions as _, CommandDefinitionFragmentV1 as a, SourceSplitFragmentV1 as b, ExampleDefinitionFragmentV1 as c, FlagNegationFragmentV1 as d, FlagPathChecksFragmentV1 as f, InputSchemaProperty as g, InputSchemaDocument as h, CommandDefinitionDocumentV1 as i, FlagDefinitionFragmentV1 as l, InputSchemaBranch as m, ArgElementFragmentV1 as n, DefinitionDocument as o, FlagStringConstraintsFragmentV1 as p, CommandDefinitionDocument as r, DefinitionDocumentV1 as s, ArgDefinitionFragmentV1 as t, FlagElementFragmentV1 as u, PromptChoiceFragmentV1 as v, generateCommandSchema as w, SplitPolicyFragmentV1 as x, PromptDefinitionFragmentV1 as y };
439
+ export { StdinBindingFragmentV1 as C, generateSchema as D, generateInputSchema as E, DEFINITION_SCHEMA_URL as O, SplitPolicyFragmentV1 as S, generateCommandSchema as T, InputSchemaProperty as _, CommandDefinitionFragmentV1 as a, PromptDefinitionFragmentV1 as b, EnvIndexedFragmentV1 as c, FlagElementFragmentV1 as d, FlagNegationFragmentV1 as f, InputSchemaDocument as g, InputSchemaBranch as h, CommandDefinitionDocumentV1 as i, DEFINITION_SCHEMA_VERSION as k, ExampleDefinitionFragmentV1 as l, FlagStringConstraintsFragmentV1 as m, ArgElementFragmentV1 as n, DefinitionDocument as o, FlagPathChecksFragmentV1 as p, CommandDefinitionDocument as r, DefinitionDocumentV1 as s, ArgDefinitionFragmentV1 as t, FlagDefinitionFragmentV1 as u, JsonSchemaOptions as v, definitionMetaSchema as w, SourceSplitFragmentV1 as x, PromptChoiceFragmentV1 as y };
@@ -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 };