@kjanat/dreamcli 5.0.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 (42) hide show
  1. package/dist/completion-B4oRc2Ae.mjs +59 -0
  2. package/dist/completion.d.mts +11 -1
  3. package/dist/completion.mjs +1 -1
  4. package/dist/config-DSh3QJpX.mjs +1 -0
  5. package/dist/config.d.mts +11 -1
  6. package/dist/config.mjs +1 -1
  7. package/dist/core-BZx351-p.mjs +21 -0
  8. package/dist/dynamic-BK2lQF2M.mjs +1 -0
  9. package/dist/{index-BidVVmln.d.mts → index-CLtWJqwn.d.mts} +8 -5
  10. package/dist/{index-BIMjOsR6.d.mts → index-CuhI1Ynv.d.mts} +394 -4
  11. package/dist/{index-DpslpOVV.d.mts → index-DDhRLoTu.d.mts} +7 -1
  12. package/dist/{index-jq_FJRKt.d.mts → index-DIWRV_wp.d.mts} +1 -1
  13. package/dist/{index-hzYPRc_O.d.mts → index-Vjl2_m23.d.mts} +5 -5
  14. package/dist/{index-AIC5Gler.d.mts → index-aTmg9yfl.d.mts} +1 -1
  15. package/dist/index.d.mts +30 -7
  16. package/dist/index.mjs +1 -1
  17. package/dist/json-schema-CYgq_hFu.mjs +59 -0
  18. package/dist/json-schema.d.mts +9 -1
  19. package/dist/json-schema.mjs +1 -1
  20. package/dist/{package-json-fYhxDdWD.mjs → package-json-hqUWeazy.mjs} +1 -1
  21. package/dist/prompt.d.mts +12 -1
  22. package/dist/prompt.mjs +1 -1
  23. package/dist/rolldown-runtime-DOYBPklu.mjs +1 -0
  24. package/dist/runtime.d.mts +20 -2
  25. package/dist/runtime.mjs +1 -1
  26. package/dist/session-BEKj0yLA.mjs +1 -0
  27. package/dist/{terminal-DRsRn4sc.mjs → terminal-Dws_b5UK.mjs} +1 -1
  28. package/dist/test-prompter-euLYzWWO.mjs +1 -0
  29. package/dist/testkit.d.mts +17 -4
  30. package/dist/testkit.mjs +1 -1
  31. package/dist/version.mjs +1 -1
  32. package/dreamcli.schema.json +11 -0
  33. package/package.json +7 -7
  34. package/skills/cli-creation/SKILL.md +1 -1
  35. package/dist/adapter-DBeedKmD.d.mts +0 -283
  36. package/dist/completion-Bh-qywmB.mjs +0 -6
  37. package/dist/config-DruA8aFV.mjs +0 -1
  38. package/dist/core-B9YNSJeA.mjs +0 -19
  39. package/dist/json-schema-DF5fXdKQ.mjs +0 -59
  40. package/dist/rolldown-runtime-G4Kt5YOX.mjs +0 -1
  41. package/dist/session-Crtzt7LY.mjs +0 -1
  42. package/dist/test-prompter-BLNGCOA_.mjs +0 -1
@@ -30,6 +30,8 @@ declare const schemaBrand: unique symbol;
30
30
  type Fallback = 'silent' | 'static';
31
31
  /** Options for {@link Out.spinner}. */
32
32
  interface SpinnerOptions {
33
+ /** Render alongside other concurrent activities instead of replacing them. */
34
+ readonly concurrent?: boolean;
33
35
  /**
34
36
  * Fallback strategy when `!isTTY` or `jsonMode`.
35
37
  * @defaultValue `'silent'`
@@ -57,12 +59,14 @@ interface SpinnerHandle {
57
59
  * @returns The resolved value of the wrapped promise.
58
60
  */
59
61
  wrap<T>(promise: Promise<T>, options?: {
60
- readonly succeed?: string;
61
- readonly fail?: string;
62
+ readonly succeed?: string | ((value: T) => string);
63
+ readonly fail?: string | ((error: unknown) => string);
62
64
  }): Promise<T>;
63
65
  }
64
66
  /** Options for {@link Out.progress}. */
65
67
  interface ProgressOptions {
68
+ /** Render alongside other concurrent activities instead of replacing them. */
69
+ readonly concurrent?: boolean;
66
70
  /**
67
71
  * Total units of work. When provided, the bar shows a determinate
68
72
  * percentage. When omitted, the bar pulses in indeterminate mode.
@@ -246,6 +250,29 @@ type HelpDescription = string | ((theme: HelpTheme) => string);
246
250
  * unconditionally, gating is the framework's job.
247
251
  */
248
252
  type HelpThemeFactory = (colors: Colors) => Partial<HelpTheme>;
253
+ /**
254
+ * Runtime value completion callbacks.
255
+ *
256
+ * @module dreamcli/core/schema/completion
257
+ */
258
+ /** The input and partial command line being completed. */
259
+ interface CompletionContext {
260
+ /** The value prefix typed before the cursor. */
261
+ readonly prefix: string;
262
+ /** Canonical command names, excluding the executable. Empty for a default command. */
263
+ readonly commandPath: readonly string[];
264
+ /** The input whose value is being completed. */
265
+ readonly input: {
266
+ readonly kind: 'flag' | 'arg';
267
+ readonly name: string;
268
+ };
269
+ /** Arguments before the cursor, including the current partial token. */
270
+ readonly argv: readonly string[];
271
+ /** Environment supplied to this execution. */
272
+ readonly env: Readonly<Record<string, string | undefined>>;
273
+ }
274
+ /** Return complete candidate values. DreamCLI filters them by prefix. */
275
+ type CompletionHandler = (context: CompletionContext) => readonly string[] | Promise<readonly string[]>;
249
276
  /**
250
277
  * An indexed env family whose entries are single values.
251
278
  *
@@ -643,6 +670,8 @@ declare const STDIN_CONSUMES: readonly ["exclusive", "broadcast"];
643
670
  type StdinConsume = (typeof STDIN_CONSUMES)[number];
644
671
  /** The normalized stdin axis of a flag or an arg. */
645
672
  interface StdinBinding {
673
+ /** False when this input has no command-line form. Omitted means true. */
674
+ readonly argv?: false;
646
675
  /** When this input reads the stdin stream. */
647
676
  readonly when: StdinWhen;
648
677
  /** Whether this input consumes the stream alone. */
@@ -652,6 +681,13 @@ interface StdinBinding {
652
681
  }
653
682
  /** Stdin settings accepted by `.stdin()` and by the schema definitions. */
654
683
  interface StdinOptions {
684
+ /**
685
+ * Accept this input on the command line. Set false to omit its flag spellings
686
+ * or positional slot from parsing, help, and completion. Other sources still apply.
687
+ * Cannot be combined with `when: 'dash'`.
688
+ * @defaultValue `true`
689
+ */
690
+ readonly argv?: boolean | undefined;
655
691
  /**
656
692
  * When this input reads the stdin stream.
657
693
  * @defaultValue `'dash-or-missing'`
@@ -1013,6 +1049,8 @@ type DuplicatePolicy = 'last' | 'first' | 'error';
1013
1049
  interface FlagSchema<K extends FlagKind = FlagKind> {
1014
1050
  /** Type-only seal produced by {@link createFlagSchema}. */
1015
1051
  readonly [schemaBrand]: 'flag';
1052
+ /** Callback used to complete this input's values. */
1053
+ readonly completion?: CompletionHandler | undefined;
1016
1054
  /** What kind of value this flag accepts. */
1017
1055
  readonly kind: K;
1018
1056
  /** Current presence state. */
@@ -1175,6 +1213,8 @@ interface FlagSchema<K extends FlagKind = FlagKind> {
1175
1213
  }
1176
1214
  /** Definition fields accepted by every flag kind. */
1177
1215
  interface FlagDefinitionBase {
1216
+ /** Callback used to complete this input's values. */
1217
+ readonly completion?: CompletionHandler | undefined;
1178
1218
  /**
1179
1219
  * Presence state.
1180
1220
  * @defaultValue `'optional'`
@@ -1500,6 +1540,17 @@ declare class FlagBuilder<C extends FlagConfig> {
1500
1540
  * @param schema - Runtime descriptor seeding this builder's state.
1501
1541
  */
1502
1542
  constructor(schema: FlagSchema);
1543
+ /**
1544
+ * Compute value candidates when the user requests shell completion.
1545
+ *
1546
+ * The callback runs without the command action, middleware, prompts, or
1547
+ * config discovery. Return complete values; DreamCLI filters by prefix.
1548
+ * Candidates containing control characters are omitted.
1549
+ *
1550
+ * @param handler - Callback receiving the input and partial command line.
1551
+ * @returns A new builder with the completion callback.
1552
+ */
1553
+ complete(handler: CompletionHandler): FlagBuilder<WithoutElementEligibility<C>>;
1503
1554
  /**
1504
1555
  * Provide a default value. The flag becomes "always present" — handlers
1505
1556
  * will never see `undefined`.
@@ -2641,6 +2692,8 @@ type ArgParseFn<T> = (raw: string) => T;
2641
2692
  interface ArgSchema<K extends ArgKind = ArgKind> {
2642
2693
  /** Type-only seal produced by {@link createArgSchema}. */
2643
2694
  readonly [schemaBrand]: 'arg';
2695
+ /** Callback used to complete this input's values. */
2696
+ readonly completion?: CompletionHandler | undefined;
2644
2697
  /** What kind of value this arg accepts. */
2645
2698
  readonly kind: K;
2646
2699
  /** Current presence state. */
@@ -2805,6 +2858,8 @@ interface ArgSchema<K extends ArgKind = ArgKind> {
2805
2858
  }
2806
2859
  /** Definition fields accepted by every arg kind. */
2807
2860
  interface ArgDefinitionBase {
2861
+ /** Callback used to complete this input's values. */
2862
+ readonly completion?: CompletionHandler | undefined;
2808
2863
  /**
2809
2864
  * Presence state.
2810
2865
  * @defaultValue `'required'`
@@ -3100,6 +3155,17 @@ declare class ArgBuilder<C extends ArgConfig> {
3100
3155
  * @param schema - Runtime descriptor for this positional argument.
3101
3156
  */
3102
3157
  constructor(schema: ArgSchema);
3158
+ /**
3159
+ * Compute value candidates when the user requests shell completion.
3160
+ *
3161
+ * The callback runs without the command action, middleware, prompts, or
3162
+ * config discovery. Return complete values; DreamCLI filters by prefix.
3163
+ * Candidates containing control characters are omitted.
3164
+ *
3165
+ * @param handler - Callback receiving the input and partial command line.
3166
+ * @returns A new builder with the completion callback.
3167
+ */
3168
+ complete(handler: CompletionHandler): ArgBuilder<WithoutArgElementEligibility<C>>;
3103
3169
  /**
3104
3170
  * Mark the arg as required (this is the default for positional args).
3105
3171
  * Produces an error if no value resolves from any configured source
@@ -4755,6 +4821,8 @@ interface CommandSchema {
4755
4821
  readonly name: string;
4756
4822
  /** Human-readable description for help text. */
4757
4823
  readonly description: string | undefined;
4824
+ /** Longer explanation shown only in this command's help, with paragraphs wrapped to its width. */
4825
+ readonly details?: HelpDescription | undefined;
4758
4826
  /** Alternative names for this command. */
4759
4827
  readonly aliases: readonly string[];
4760
4828
  /** Whether this command is hidden from help listings. */
@@ -4823,6 +4891,8 @@ interface CommandDefinition {
4823
4891
  * @defaultValue `undefined`
4824
4892
  */
4825
4893
  readonly description?: string | undefined;
4894
+ /** Longer explanation shown only in this command's help. */
4895
+ readonly details?: HelpDescription | undefined;
4826
4896
  /**
4827
4897
  * Alternative names for this command.
4828
4898
  * @defaultValue `[]`
@@ -4921,6 +4991,10 @@ declare function createCommandSchema(definition: CommandDefinition): CommandSche
4921
4991
  *
4922
4992
  */
4923
4993
  type AnyCommandBuilder = CommandBuilder<Record<string, FlagBuilder<FlagConfig>>, Record<string, ArgBuilder<ArgConfig>>, Record<string, unknown>>;
4994
+ /** Retain declared flag names for duplicate checks alongside an index signature. */
4995
+ type KnownFlags<F> = { [K in keyof F as string extends K ? never : number extends K ? never : K]: F[K]; };
4996
+ /** Generated names can carry any registered builder, while declared names keep their types. */
4997
+ type MergeFlags<F extends Record<string, FlagBuilder<FlagConfig>>, R extends Record<string, FlagBuilder<FlagConfig>>> = string extends keyof F | keyof R ? KnownFlags<F> & KnownFlags<R> & Record<string, F[keyof F] | R[keyof R]> : F & R;
4924
4998
  /**
4925
4999
  * Immutable command schema builder.
4926
5000
  *
@@ -5133,6 +5207,16 @@ declare class CommandBuilder<F extends Record<string, FlagBuilder<FlagConfig>> =
5133
5207
  * @returns The builder (for chaining).
5134
5208
  */
5135
5209
  description(text: string): CommandBuilder<F, A, C>;
5210
+ /**
5211
+ * Add a longer explanation to this command's help.
5212
+ *
5213
+ * Paragraphs wrap to the help width. Parent command listings use only
5214
+ * `.description()`. A function receives the current help description theme.
5215
+ *
5216
+ * @param text - Literal text or a function that styles the explanation.
5217
+ * @returns A new builder with the explanation.
5218
+ */
5219
+ details(text: HelpDescription): CommandBuilder<F, A, C>;
5136
5220
  /**
5137
5221
  * Add an alternative name for this command.
5138
5222
  *
@@ -5262,7 +5346,26 @@ declare class CommandBuilder<F extends Record<string, FlagBuilder<FlagConfig>> =
5262
5346
  * @throws {@link CLIError} `PROPAGATED_FLAG_COLLISION` when a spelling
5263
5347
  * collides with one propagated to a registered subcommand.
5264
5348
  */
5265
- flag<N extends string, B extends FlagBuilder<FlagConfig>>(name: N & Exclude<N, keyof F>, builder: B): CommandBuilder<F & Record<N, B>, A, C>;
5349
+ flag<N extends string, B extends FlagBuilder<FlagConfig>>(name: N & Exclude<N, keyof KnownFlags<F>>, builder: B): CommandBuilder<MergeFlags<F, Record<N, B>>, A, C>;
5350
+ /**
5351
+ * Register a record of flags, preserving each key and inferred value type.
5352
+ *
5353
+ * Names and aliases must not collide with existing flags or other entries.
5354
+ * Literal names are checked by the compiler. Generated names are checked
5355
+ * at runtime, and their values include the registered flag value types.
5356
+ * Adding flags clears any previously registered action, like `.flag()`.
5357
+ *
5358
+ * @param record - Named flag builders to add to this command.
5359
+ * @returns A new builder with the added flags.
5360
+ *
5361
+ * @example
5362
+ * ```ts
5363
+ * command('serve')
5364
+ * .flags({ port: flag.number().default(3000), host: flag.string() })
5365
+ * .action(({ flags }) => { flags.port; flags.host; });
5366
+ * ```
5367
+ */
5368
+ flags<const R extends Record<string, FlagBuilder<FlagConfig>>>(record: R & { [K in (keyof KnownFlags<R> & keyof KnownFlags<F>) | Extract<keyof R, symbol>]: never; }): CommandBuilder<MergeFlags<F, R>, A, C>;
5266
5369
  /**
5267
5370
  * Register a named positional argument on this command.
5268
5371
  *
@@ -5528,6 +5631,287 @@ type ReadFn = () => Promise<string | null>;
5528
5631
  * @throws Error if select/multiselect has no choices and no enum values
5529
5632
  */
5530
5633
  declare function resolvePromptConfig(config: PromptConfig, enumValues: readonly string[] | undefined): ResolvedPromptConfig;
5634
+ /**
5635
+ * Runtime adapter interface.
5636
+ *
5637
+ * Defines the minimal contract between the platform-agnostic core and
5638
+ * the host runtime (Node.js, Bun, Deno). Every platform-dependent
5639
+ * operation flows through this interface — the core never calls
5640
+ * `process.*`, `Deno.*`, or `Bun.*` directly.
5641
+ *
5642
+ * Adapters are designed to be:
5643
+ * - **Immutable in shape:** all properties are readonly
5644
+ * - **Minimal:** only the operations the framework actually needs
5645
+ * - **Testable:** easily stubbed in tests via {@linkcode createTestAdapter | createTestAdapter()}
5646
+ *
5647
+ * @example
5648
+ * ```ts
5649
+ * // Production: auto-detected
5650
+ * cli('mycli').run(); // uses Node/Bun/Deno adapter
5651
+ *
5652
+ * // Test: explicit adapter
5653
+ * cli('mycli').run({ adapter: createTestAdapter({ argv: ['deploy'] }) });
5654
+ * ```
5655
+ */
5656
+ interface RuntimeAdapter {
5657
+ /** Raw argv array (including binary + script path, e.g. `['node', 'cli.js', 'deploy']`). */
5658
+ readonly argv: readonly string[];
5659
+ /**
5660
+ * Environment variables.
5661
+ * Values are `string | undefined` — mirrors Node's `process.env` semantics.
5662
+ */
5663
+ readonly env: Readonly<Record<string, string | undefined>>;
5664
+ /** Current working directory (absolute path). */
5665
+ readonly cwd: string;
5666
+ /** Writer for stdout. Framework routes `out.log`/`out.info` through this. */
5667
+ readonly stdout: WriteFn;
5668
+ /** Writer for stderr. Framework routes `out.warn`/`out.error` through this. */
5669
+ readonly stderr: WriteFn;
5670
+ /** Wait for pending output writes to settle, rejecting with a recorded output failure. */
5671
+ readonly flush?: () => Promise<void>;
5672
+ /**
5673
+ * Line reader for stdin. Used by the prompt engine for interactive input.
5674
+ *
5675
+ * Returns `null` on EOF (Ctrl+D on Unix, Ctrl+Z on Windows),
5676
+ * indicating the user closed the input stream (treated as cancel).
5677
+ */
5678
+ readonly stdin: ReadFn;
5679
+ /** Hidden terminal input. Absent when echo suppression is unsupported. */
5680
+ readonly readSecret?: ReadFn;
5681
+ /**
5682
+ * Read all of stdin as a single string (for piped data).
5683
+ *
5684
+ * Returns the full stdin contents when data is piped (`stdinIsTTY` is
5685
+ * false), or `null` when stdin is a TTY (no piped data available).
5686
+ *
5687
+ * Used by the resolve chain for args with `.stdin()` configured.
5688
+ * Unlike {@link stdin} (which reads one line for prompts), this
5689
+ * consumes the entire stream to EOF.
5690
+ *
5691
+ * @returns Full stdin contents as a string, or `null` if stdin is a TTY.
5692
+ */
5693
+ readonly readStdin: () => Promise<string | null>;
5694
+ /** Whether stdout is connected to a TTY. */
5695
+ readonly isTTY: boolean;
5696
+ /** Whether stdin is connected to a TTY (used for prompt gating). */
5697
+ readonly stdinIsTTY: boolean;
5698
+ /** Read current terminal dimensions for stdout, if available. */
5699
+ readonly getTerminalSize: () => TerminalSize | undefined;
5700
+ /** Subscribe to terminal resize events when the runtime supports them. */
5701
+ readonly onTerminalResize: (listener: () => void) => (() => void) | undefined;
5702
+ /**
5703
+ * Exit the process with the given code.
5704
+ * Must not return (divergent function).
5705
+ */
5706
+ readonly exit: (code: number) => never;
5707
+ /**
5708
+ * Read a file as UTF-8 text.
5709
+ *
5710
+ * Returns file contents on success, `null` if the file does not exist
5711
+ * (ENOENT/NotFound). Throws on other I/O errors (permission denied,
5712
+ * is-directory, etc.) — those indicate unexpected failures, not
5713
+ * "try the next path".
5714
+ *
5715
+ * Used by config file discovery to probe multiple candidate paths.
5716
+ */
5717
+ readonly readFile: (path: string) => Promise<string | null>;
5718
+ /**
5719
+ * Probe what exists at a filesystem path.
5720
+ *
5721
+ * Returns `'file'` or `'directory'` for existing paths (other kinds such
5722
+ * as sockets report `'file'`), or `null` when nothing exists there.
5723
+ *
5724
+ * Used by `flag.path()` existence/type checks after resolution.
5725
+ */
5726
+ readonly stat: (path: string) => Promise<'file' | 'directory' | null>;
5727
+ /**
5728
+ * Create a directory, including missing parents.
5729
+ *
5730
+ * Succeeds when the directory already exists. Throws on other I/O errors
5731
+ * (permission denied, existing file at the path, etc.).
5732
+ *
5733
+ * Used by `flag.path()` `create` checks after resolution.
5734
+ */
5735
+ readonly mkdir: (path: string) => Promise<void>;
5736
+ /**
5737
+ * User home directory (absolute path).
5738
+ *
5739
+ * - Node/Bun: derived from `HOME` / `USERPROFILE` env
5740
+ * - Deno: `Deno.env.get('HOME')` / `Deno.env.get('USERPROFILE')`
5741
+ */
5742
+ readonly homedir: string;
5743
+ /**
5744
+ * Platform-specific user configuration directory (absolute path).
5745
+ *
5746
+ * - Unix: `$XDG_CONFIG_HOME` or `~/.config`
5747
+ * - Windows: `%APPDATA%` or `~\AppData\Roaming`
5748
+ *
5749
+ * Config discovery appends the app-specific subdirectory.
5750
+ */
5751
+ readonly configDir: string;
5752
+ /**
5753
+ * User-scope config roots for discovery, highest priority first.
5754
+ *
5755
+ * - Unix: `[configDir]`
5756
+ * - macOS: `[configDir, ~/Library/Application Support]`
5757
+ * - Windows: `[configDir]`
5758
+ *
5759
+ * When absent, discovery falls back to `[configDir]`.
5760
+ */
5761
+ readonly userConfigDirs?: readonly string[];
5762
+ /**
5763
+ * System-scope config roots for discovery (`['/etc']` on Linux and
5764
+ * macOS, `[]` on Windows). When absent, discovery probes none.
5765
+ */
5766
+ readonly systemConfigDirs?: readonly string[];
5767
+ }
5768
+ /** Current terminal dimensions in columns and rows. */
5769
+ interface TerminalSize {
5770
+ /** Terminal width in columns. */
5771
+ readonly columns: number;
5772
+ /** Terminal height in rows. */
5773
+ readonly rows: number;
5774
+ }
5775
+ /**
5776
+ * Options for creating a test adapter.
5777
+ *
5778
+ * All fields are optional — sensible defaults are applied for testing
5779
+ * scenarios (empty argv, empty env, noop stdout/stderr, non-TTY, exit
5780
+ * throws instead of killing the process).
5781
+ */
5782
+ interface TestAdapterOptions {
5783
+ /** Raw argv (defaults to `['node', 'test']`). */
5784
+ readonly argv?: readonly string[];
5785
+ /** Environment variables (defaults to `{}`). */
5786
+ readonly env?: Readonly<Record<string, string | undefined>>;
5787
+ /** Working directory (defaults to `'/test'`). */
5788
+ readonly cwd?: string;
5789
+ /** Stdout writer (defaults to noop). */
5790
+ readonly stdout?: WriteFn;
5791
+ /** Stderr writer (defaults to noop). */
5792
+ readonly stderr?: WriteFn;
5793
+ /**
5794
+ * Stdin line reader (defaults to returning `null` — immediate EOF).
5795
+ *
5796
+ * Use a custom {@linkcode ReadFn} to simulate user input in tests.
5797
+ */
5798
+ readonly stdin?: ReadFn;
5799
+ /** Hidden reader stub; omitted adapters report unsupported hidden input. */
5800
+ readonly readSecret?: ReadFn;
5801
+ /**
5802
+ * Piped stdin data for testing args with `.stdin()` configured.
5803
+ *
5804
+ * When provided and `stdinIsTTY` is `false`, `readStdin()` returns this
5805
+ * string once, then `null` on subsequent reads. When absent, or when
5806
+ * `stdinIsTTY` is `true`, `readStdin()` returns `null`.
5807
+ *
5808
+ * @example
5809
+ * ```ts
5810
+ * createTestAdapter({
5811
+ * stdinData: '{"key": "value"}',
5812
+ * })
5813
+ * ```
5814
+ */
5815
+ readonly stdinData?: string;
5816
+ /** TTY flag for stdout (defaults to `false`). */
5817
+ readonly isTTY?: boolean;
5818
+ /** TTY flag for stdin (defaults to `false`). */
5819
+ readonly stdinIsTTY?: boolean;
5820
+ /** Terminal dimensions returned by `getTerminalSize()`. */
5821
+ readonly terminalSize?: TerminalSize;
5822
+ /** Resize subscription hook returned by `onTerminalResize()`. */
5823
+ readonly onTerminalResize?: (listener: () => void) => (() => void) | undefined;
5824
+ /**
5825
+ * Exit function (defaults to throwing {@linkcode ExitError}).
5826
+ * The default throw-based exit allows tests to catch the exit code.
5827
+ */
5828
+ readonly exit?: (code: number) => never;
5829
+ /**
5830
+ * File reader stub (defaults to returning `null` — all files not found).
5831
+ *
5832
+ * Supply a custom function to simulate a virtual filesystem in tests:
5833
+ * ```ts
5834
+ * createTestAdapter({
5835
+ * readFile: (path) => Promise.resolve(
5836
+ * path === '/home/test/.config/myapp/config.json'
5837
+ * ? '{"region":"eu"}'
5838
+ * : null
5839
+ * ),
5840
+ * })
5841
+ * ```
5842
+ */
5843
+ readonly readFile?: (path: string) => Promise<string | null>;
5844
+ /**
5845
+ * Filesystem probe stub for `flag.path()` checks (defaults to returning
5846
+ * `null` — nothing exists).
5847
+ *
5848
+ * Supply a custom function to simulate a virtual filesystem in tests:
5849
+ * ```ts
5850
+ * createTestAdapter({
5851
+ * stat: (path) => Promise.resolve(path === '/data' ? 'directory' : null),
5852
+ * })
5853
+ * ```
5854
+ */
5855
+ readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
5856
+ /**
5857
+ * Directory creation stub for `flag.path()` `create` checks (defaults to
5858
+ * a noop that resolves without creating anything).
5859
+ */
5860
+ readonly mkdir?: (path: string) => Promise<void>;
5861
+ /** Home directory (defaults to `'/home/test'`). */
5862
+ readonly homedir?: string;
5863
+ /** Config directory (defaults to `'/home/test/.config'`). */
5864
+ readonly configDir?: string;
5865
+ /** User-scope config roots for discovery (defaults to `[configDir]`). */
5866
+ readonly userConfigDirs?: readonly string[];
5867
+ /** System-scope config roots for discovery (defaults to `[]`). */
5868
+ readonly systemConfigDirs?: readonly string[];
5869
+ }
5870
+ /**
5871
+ * Error thrown by adapter implementations that model process exit as an
5872
+ * exception instead of terminating immediately.
5873
+ *
5874
+ * Runtime and CLI dispatch layers can catch this to perform real process
5875
+ * termination, while tests can assert on exit codes without killing the
5876
+ * runner:
5877
+ *
5878
+ * ```ts
5879
+ * try {
5880
+ * await cli.run({ adapter: createTestAdapter() });
5881
+ * } catch (e) {
5882
+ * if (e instanceof ExitError) expect(e.code).toBe(0);
5883
+ * }
5884
+ * ```
5885
+ */
5886
+ declare class ExitError extends Error {
5887
+ /** Error name — always `'ExitError'` for `instanceof` checks. */
5888
+ readonly name = "ExitError";
5889
+ /** The exit code passed to `exit()`. */
5890
+ readonly code: number;
5891
+ /** Create an ExitError for the given process exit code. */
5892
+ constructor(code: number);
5893
+ }
5894
+ /**
5895
+ * Create a test runtime adapter with injectable process state.
5896
+ *
5897
+ * Use this in `@kjanat/dreamcli/testkit` tests when you need to simulate argv,
5898
+ * environment variables, TTY state, stdin, or config-file reads without
5899
+ * touching the host process.
5900
+ *
5901
+ * @param options - Optional overrides for any adapter field.
5902
+ * @returns A {@linkcode RuntimeAdapter} suitable for test scenarios.
5903
+ *
5904
+ * @example
5905
+ * ```ts
5906
+ * const adapter = createTestAdapter({
5907
+ * argv: ['node', 'cli.js', 'deploy', '--force'],
5908
+ * env: { DEPLOY_REGION: 'us' },
5909
+ * });
5910
+ *
5911
+ * const result = await cli('mycli').run({ adapter });
5912
+ * ```
5913
+ */
5914
+ declare function createTestAdapter(options?: TestAdapterOptions): RuntimeAdapter;
5531
5915
  /**
5532
5916
  * Minimal I/O seam — the only write primitive the output module depends on.
5533
5917
  *
@@ -5581,6 +5965,12 @@ interface OutputOptions {
5581
5965
  * Defaults to `false` (safe default — non-TTY until proven otherwise).
5582
5966
  */
5583
5967
  readonly isTTY?: boolean;
5968
+ /**
5969
+ * Read the terminal's current dimensions before concurrent activity redraws.
5970
+ * `.run()` supplies the runtime adapter's getter. Without usable dimensions,
5971
+ * concurrent activities emit static start and completion messages.
5972
+ */
5973
+ readonly getTerminalSize?: () => TerminalSize | undefined;
5584
5974
  /**
5585
5975
  * Verbosity level.
5586
5976
  * - `'normal'` (default) — emit all messages
@@ -5700,4 +6090,4 @@ interface CapturedOutput {
5700
6090
  * ```
5701
6091
  */
5702
6092
  declare function createCaptureOutput(options?: Omit<OutputOptions, 'stdout' | 'stderr'>): [out: Out, captured: CapturedOutput];
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 };
6093
+ export { ArgConfig as $, ActivityEvent as $n, InferFlag as $t, ExampleMeta as A, StandardSchemaV1SuccessResult as An, SplitFormat as At, InputSources as B, SelectChoice as Bn, EnumFlagDefinition as Bt, CommandExample as C, StandardSchemaV1 as Cn, arg as Ct, DeriveParams as D, StandardSchemaV1PathSegment as Dn, SPLIT_FORMATS as Dt, DeriveHandler as E, StandardSchemaV1Options as En, DuplicateKeys as Et, Out as F, PasswordPromptConfig as Fn, BooleanFlagDefinition as Ft, MiddlewareHandler as G, IndexedEnvBinding as Gn, FlagDefinitionByKind as Gt, SourcesOf as H, NumberConstraintViolation as Hn, FlagConfig as Ht, command as I, PromptConfig as In, CountFlagDefinition as It, Ask as J, CompletionContext as Jn, FlagKind as Jt, MiddlewareParams as K, IndexedRecordEnvBinding as Kn, FlagDefinitionOverrides as Kt, createCommandSchema as L, PromptConfigBase as Ln, CustomFlagDefinition as Lt, InteractiveParams as M, ConfirmPromptConfig as Mn, SplitPolicy as Mt, InteractiveResolver as N, InputPromptConfig as Nn, SplitSetting as Nt, ErasedActionHandler as O, StandardSchemaV1Props as On, SourceSplitBinding as Ot, InteractiveResult as P, MultiselectPromptConfig as Pn, ArrayFlagDefinition as Pt, ArgBuilder as Q, HelpThemeFactory as Qn, FlagSchema as Qt, group as R, PromptKind as Rn, DefaultValueOptions as Rt, CommandDefinition as S, InferStandardOutput as Sn, WithoutArgElementEligibility as St, CommandSchema as T, StandardSchemaV1Issue as Tn, DUPLICATE_KEYS as Tt, wasExplicit as U, NumberConstraints as Un, FlagDefinition as Ut, ResolutionProvenance as V, SelectPromptConfig as Vn, FlagBuilder as Vt, Middleware as W, EnvOptions as Wn, FlagDefinitionBase as Wt, prompt as X, HelpDescription as Xn, FlagParseFn as Xt, InferPrompt as Y, CompletionHandler as Yn, FlagNegation as Yt, Verbosity as Z, HelpTheme as Zn, FlagPresence as Zt, ActionHandler as _, StdinBinding as _n, ResolvedArgValue as _t, WriteFn as a, StringFlagDefinition as an, TableColumn as ar, ArgFactory as at, CommandArgEntryDefinition as b, StdinWhen as bn, WithArgPresence as bt, TerminalSize as c, createFlagSchema as cn, TableStream as cr, ArgPresence as ct, PromptEngine as d, DateFlagOptions as dn, CustomArgDefinition as dt, InferFlags as en, Fallback as er, ArgDefaultValue as et, ReadFn as f, PathChecks as fn, EnumArgDefinition as ft, resolvePromptConfig as g, StringConstraints as gn, NumberArgDefinition as gt, ResolvedSelectPromptConfig as h, StringConstraintViolation as hn, KeyValueArgDefinition as ht, createOutput as i, StringElementConfig as in, SpinnerOptions as ir, ArgDefinitionOverrides as it, ExecutionStep as j, StandardSchemaV1Types as jn, SplitOptions as jt, ExampleCommand as k, StandardSchemaV1Result as kn, SplitBinding as kt, TestAdapterOptions as l, flag as ln, schemaBrand as lr, ArgSchema as lt, ResolvedPromptConfig as m, UrlFlagOptions as mn, InferArgs as mt, OutputOptions as n, NumberFlagDefinition as nn, ProgressOptions as nr, ArgDefinitionBase as nt, ExitError as o, WithPresence as on, TableFormat as or, ArgKind as ot, ResolvedMultiselectPromptConfig as p, PathFlagOptions as pn, InferArg as pt, middleware as q, IndexedValueEnvBinding as qn, FlagFactory as qt, createCaptureOutput as r, ResolvedValue as rn, SpinnerHandle as rr, ArgDefinitionByKind as rt, RuntimeAdapter as s, WithoutElementEligibility as sn, TableOptions as sr, ArgParseFn as st, CapturedOutput as t, KeyValueFlagDefinition as tn, ProgressHandle as tr, ArgDefinition as tt, createTestAdapter as u, getFlagNegatedName as un, BooleanArgDefinition as ut, ActionParams as v, StdinConsume as vn, StringArgDefinition as vt, CommandMeta as w, StandardSchemaV1FailureResult as wn, createArgSchema as wt, CommandBuilder as x, InferStandardInput as xn, WithVariadic as xt, CommandArgEntry as y, StdinOptions as yn, StringArgElementConfig as yt, resolveExampleCommand as z, PromptResult as zn, DuplicatePolicy as zt };
@@ -1,4 +1,4 @@
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";
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
2
  import { t as CLIError } from "./index-D683D09G.mjs";
3
3
  import { Colors } from "ansispeck";
4
4
  /** A built-in flag a consumer can take over. */
@@ -767,6 +767,12 @@ interface RunOptions {
767
767
  * @defaultValue `false`
768
768
  */
769
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;
770
776
  /**
771
777
  * Help formatting options (width, binName).
772
778
  * Used when `--help` is detected.
@@ -1,4 +1,4 @@
1
- import { n as RuntimeAdapter } from "./adapter-DBeedKmD.mjs";
1
+ import { s as RuntimeAdapter } from "./index-CuhI1Ynv.mjs";
2
2
  /**
3
3
  * Object form of a manifest's `repository` field
4
4
  * (e.g. `{"type":"git","url":"git+https://github.com/u/r.git"}`).
@@ -1,7 +1,6 @@
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";
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
5
  /**
7
6
  * Options for completion script generation.
@@ -589,7 +588,8 @@ interface RenderContextOptions {
589
588
  */
590
589
  readonly color?: boolean;
591
590
  /**
592
- * Environment variables consulted for `NO_HYPERLINKS`/`FORCE_HYPERLINKS`
591
+ * Environment variables consulted for `NO_COLOR`/`FORCE_COLOR` and
592
+ * `NO_HYPERLINKS`/`FORCE_HYPERLINKS`
593
593
  * (e.g. `process.env`).
594
594
  *
595
595
  * @defaultValue `{}`
@@ -1,4 +1,4 @@
1
- import { n as RuntimeAdapter } from "./adapter-DBeedKmD.mjs";
1
+ import { s as RuntimeAdapter } from "./index-CuhI1Ynv.mjs";
2
2
  /**
3
3
  * Auto-detects the current JavaScript runtime environment.
4
4
  *