@kjanat/dreamcli 2.5.0 → 3.0.0-rc.10

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 (202) hide show
  1. package/CHANGELOG.md +344 -1
  2. package/README.md +9 -2
  3. package/dist/core/cli/dispatch.d.mts +6 -5
  4. package/dist/core/cli/dispatch.mjs +205 -1
  5. package/dist/core/cli/help-links.d.mts +0 -1
  6. package/dist/core/cli/help-links.mjs +41 -1
  7. package/dist/core/cli/index.d.mts +185 -19
  8. package/dist/core/cli/index.mjs +945 -1
  9. package/dist/core/cli/planner.d.mts +32 -6
  10. package/dist/core/cli/planner.mjs +300 -1
  11. package/dist/core/cli/plugin.d.mts +1 -1
  12. package/dist/core/cli/plugin.mjs +41 -1
  13. package/dist/core/cli/propagate.d.mts +1 -1
  14. package/dist/core/cli/propagate.mjs +57 -1
  15. package/dist/core/cli/root-help.d.mts +18 -3
  16. package/dist/core/cli/root-help.mjs +226 -6
  17. package/dist/core/cli/root-surface.d.mts +30 -4
  18. package/dist/core/cli/root-surface.mjs +28 -1
  19. package/dist/core/cli/runtime-preflight.d.mts +30 -3
  20. package/dist/core/cli/runtime-preflight.mjs +169 -1
  21. package/dist/core/completion/index.d.mts +32 -2
  22. package/dist/core/completion/index.mjs +90 -1
  23. package/dist/core/completion/shells/bash.d.mts +0 -1
  24. package/dist/core/completion/shells/bash.mjs +308 -3
  25. package/dist/core/completion/shells/fish.d.mts +0 -1
  26. package/dist/core/completion/shells/fish.mjs +162 -2
  27. package/dist/core/completion/shells/powershell.d.mts +0 -1
  28. package/dist/core/completion/shells/powershell.mjs +358 -2
  29. package/dist/core/completion/shells/shared.d.mts +23 -2
  30. package/dist/core/completion/shells/shared.mjs +176 -1
  31. package/dist/core/completion/shells/zsh.d.mts +0 -1
  32. package/dist/core/completion/shells/zsh.mjs +251 -2
  33. package/dist/core/config/index.d.mts +2 -3
  34. package/dist/core/config/index.mjs +246 -1
  35. package/dist/core/config/package-json.d.mts +27 -4
  36. package/dist/core/config/package-json.mjs +386 -3
  37. package/dist/core/errors/index.d.mts +3 -3
  38. package/dist/core/errors/index.mjs +87 -1
  39. package/dist/core/execution/index.d.mts +0 -1
  40. package/dist/core/execution/index.mjs +201 -1
  41. package/dist/core/help/ansi.d.mts +11 -5
  42. package/dist/core/help/ansi.mjs +121 -2
  43. package/dist/core/help/index.d.mts +65 -2
  44. package/dist/core/help/index.mjs +341 -7
  45. package/dist/core/help/theme.d.mts +68 -0
  46. package/dist/core/help/theme.mjs +46 -0
  47. package/dist/core/json-schema/index.d.mts +15 -2
  48. package/dist/core/json-schema/index.mjs +536 -12
  49. package/dist/core/json-schema/meta-descriptions.generated.d.mts +22 -5
  50. package/dist/core/json-schema/meta-descriptions.generated.mjs +102 -28
  51. package/dist/core/output/activity.d.mts +0 -1
  52. package/dist/core/output/activity.mjs +452 -1
  53. package/dist/core/output/bind.mjs +56 -1
  54. package/dist/core/output/contracts.d.mts +4 -5
  55. package/dist/core/output/contracts.mjs +57 -1
  56. package/dist/core/output/display-value.mjs +32 -1
  57. package/dist/core/output/index.d.mts +21 -1
  58. package/dist/core/output/index.mjs +442 -2
  59. package/dist/core/output/renderers.d.mts +0 -1
  60. package/dist/core/output/renderers.mjs +46 -1
  61. package/dist/core/output/writer.mjs +12 -1
  62. package/dist/core/parse/index.d.mts +54 -7
  63. package/dist/core/parse/index.mjs +727 -1
  64. package/dist/core/prompt/index.d.mts +12 -4
  65. package/dist/core/prompt/index.mjs +348 -6
  66. package/dist/core/resolve/args.d.mts +1 -1
  67. package/dist/core/resolve/args.mjs +105 -1
  68. package/dist/core/resolve/coerce.d.mts +1 -1
  69. package/dist/core/resolve/coerce.mjs +336 -1
  70. package/dist/core/resolve/config.mjs +19 -1
  71. package/dist/core/resolve/contracts.d.mts +9 -4
  72. package/dist/core/resolve/errors.d.mts +0 -1
  73. package/dist/core/resolve/errors.mjs +140 -2
  74. package/dist/core/resolve/flags.d.mts +7 -2
  75. package/dist/core/resolve/flags.mjs +251 -1
  76. package/dist/core/resolve/index.d.mts +2 -2
  77. package/dist/core/resolve/index.mjs +85 -1
  78. package/dist/core/resolve/property.d.mts +6 -2
  79. package/dist/core/resolve/property.mjs +53 -1
  80. package/dist/core/schema/activity.d.mts +31 -11
  81. package/dist/core/schema/arg.d.mts +92 -13
  82. package/dist/core/schema/arg.mjs +463 -1
  83. package/dist/core/schema/command.d.mts +29 -7
  84. package/dist/core/schema/command.mjs +726 -1
  85. package/dist/core/schema/flag.d.mts +577 -21
  86. package/dist/core/schema/flag.mjs +705 -1
  87. package/dist/core/schema/index.d.mts +5 -2
  88. package/dist/core/schema/middleware.d.mts +4 -3
  89. package/dist/core/schema/middleware.mjs +41 -1
  90. package/dist/core/schema/number-constraints.d.mts +96 -0
  91. package/dist/core/schema/number-constraints.mjs +60 -0
  92. package/dist/core/schema/prompt.d.mts +21 -3
  93. package/dist/core/schema/run.d.mts +24 -5
  94. package/dist/core/schema/string-constraints.d.mts +97 -0
  95. package/dist/core/schema/string-constraints.mjs +69 -0
  96. package/dist/core/schema/value-parsers.d.mts +78 -0
  97. package/dist/core/schema/value-parsers.mjs +142 -0
  98. package/dist/core/schema-dsl/runtime.mjs +271 -2
  99. package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
  100. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  101. package/dist/core/testkit/index.d.mts +9 -36
  102. package/dist/core/testkit/index.mjs +83 -1
  103. package/dist/index.d.mts +12 -6
  104. package/dist/index.mjs +22 -1
  105. package/dist/runtime/adapter.d.mts +38 -2
  106. package/dist/runtime/adapter.mjs +87 -1
  107. package/dist/runtime/auto.d.mts +2 -3
  108. package/dist/runtime/auto.mjs +45 -1
  109. package/dist/runtime/deno.d.mts +24 -5
  110. package/dist/runtime/deno.mjs +262 -2
  111. package/dist/runtime/detect.mjs +45 -1
  112. package/dist/runtime/index.d.mts +3 -4
  113. package/dist/runtime/node.d.mts +8 -2
  114. package/dist/runtime/node.mjs +220 -2
  115. package/dist/runtime/paths.mjs +48 -1
  116. package/dist/runtime.d.mts +4 -4
  117. package/dist/runtime.mjs +6 -1
  118. package/dist/strings.mjs +22 -1
  119. package/dist/testkit.d.mts +1 -0
  120. package/dist/testkit.mjs +5 -1
  121. package/dist/version.d.mts +7 -3
  122. package/dist/version.mjs +7 -1
  123. package/dreamcli.schema.json +36 -7
  124. package/examples/basic.ts +5 -1
  125. package/examples/gh/package.json +2 -7
  126. package/examples/pwsh-demo/package.json +1 -7
  127. package/examples/pwsh-demo/src/main.test.ts +1 -4
  128. package/examples/pwsh-demo/src/main.ts +14 -4
  129. package/examples/transport-launcher.ts +85 -0
  130. package/package.json +43 -49
  131. package/dist/runtime/bun.d.mts +0 -28
  132. package/dist/runtime/bun.mjs +0 -1
  133. package/dist/runtime/support.d.mts +0 -42
  134. package/dist/runtime/support.mjs +0 -1
  135. package/src/core/cli/dispatch.ts +0 -349
  136. package/src/core/cli/help-links.ts +0 -82
  137. package/src/core/cli/index.ts +0 -1413
  138. package/src/core/cli/planner.ts +0 -487
  139. package/src/core/cli/plugin.ts +0 -117
  140. package/src/core/cli/propagate.ts +0 -97
  141. package/src/core/cli/root-help.ts +0 -252
  142. package/src/core/cli/root-surface.ts +0 -74
  143. package/src/core/cli/runtime-preflight.ts +0 -438
  144. package/src/core/completion/index.ts +0 -88
  145. package/src/core/completion/shells/bash.ts +0 -459
  146. package/src/core/completion/shells/fish.ts +0 -259
  147. package/src/core/completion/shells/powershell.ts +0 -439
  148. package/src/core/completion/shells/shared.ts +0 -283
  149. package/src/core/completion/shells/zsh.ts +0 -381
  150. package/src/core/config/index.ts +0 -417
  151. package/src/core/config/package-json.ts +0 -560
  152. package/src/core/errors/index.ts +0 -193
  153. package/src/core/execution/index.ts +0 -268
  154. package/src/core/help/ansi.ts +0 -144
  155. package/src/core/help/index.ts +0 -516
  156. package/src/core/json-schema/index.ts +0 -891
  157. package/src/core/json-schema/meta-descriptions.generated.ts +0 -185
  158. package/src/core/output/activity.ts +0 -575
  159. package/src/core/output/bind.ts +0 -59
  160. package/src/core/output/contracts.ts +0 -194
  161. package/src/core/output/display-value.ts +0 -48
  162. package/src/core/output/index.ts +0 -704
  163. package/src/core/output/renderers.ts +0 -125
  164. package/src/core/output/writer.ts +0 -46
  165. package/src/core/parse/index.ts +0 -681
  166. package/src/core/prompt/index.ts +0 -583
  167. package/src/core/resolve/args.ts +0 -144
  168. package/src/core/resolve/coerce.ts +0 -432
  169. package/src/core/resolve/config.ts +0 -26
  170. package/src/core/resolve/contracts.ts +0 -135
  171. package/src/core/resolve/errors.ts +0 -227
  172. package/src/core/resolve/flags.ts +0 -255
  173. package/src/core/resolve/index.ts +0 -108
  174. package/src/core/resolve/property.ts +0 -99
  175. package/src/core/schema/activity.ts +0 -240
  176. package/src/core/schema/arg.ts +0 -719
  177. package/src/core/schema/command.ts +0 -1498
  178. package/src/core/schema/flag.ts +0 -801
  179. package/src/core/schema/index.ts +0 -91
  180. package/src/core/schema/middleware.ts +0 -171
  181. package/src/core/schema/prompt.ts +0 -156
  182. package/src/core/schema/run.ts +0 -198
  183. package/src/core/schema-dsl/index.ts +0 -109
  184. package/src/core/schema-dsl/parse.ts +0 -262
  185. package/src/core/schema-dsl/runtime.ts +0 -609
  186. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  187. package/src/core/testkit/index.ts +0 -123
  188. package/src/index.ts +0 -179
  189. package/src/runtime/adapter.ts +0 -303
  190. package/src/runtime/auto.ts +0 -110
  191. package/src/runtime/bun.ts +0 -55
  192. package/src/runtime/deno.ts +0 -369
  193. package/src/runtime/detect.ts +0 -105
  194. package/src/runtime/index.ts +0 -21
  195. package/src/runtime/node-builtins.d.ts +0 -27
  196. package/src/runtime/node.ts +0 -300
  197. package/src/runtime/paths.ts +0 -64
  198. package/src/runtime/support.ts +0 -135
  199. package/src/runtime.ts +0 -31
  200. package/src/strings.ts +0 -34
  201. package/src/testkit.ts +0 -25
  202. package/src/version.ts +0 -20
@@ -1,108 +0,0 @@
1
- /**
2
- * Resolution chain: CLI -> env -> config -> prompt -> default.
3
- *
4
- * v0.1 implemented: **CLI parsed value -> default value**.
5
- * v0.2 adds: **env variable resolution** and **config object resolution**
6
- * between CLI and default.
7
- * v0.3 adds: **prompt resolution** between config and default.
8
- *
9
- * The resolver takes raw {@linkcode ParseResult} (from the parser) and a
10
- * {@linkcode CommandSchema}, applies the resolution chain, and validates
11
- * that all required flags/args are present. On success it returns a
12
- * {@linkcode ResolveResult} with fully resolved values; on failure it throws
13
- * {@linkcode ValidationError}.
14
- *
15
- * @module dreamcli/core/resolve
16
- */
17
-
18
- import { isValidationError, type ValidationError } from '#internals/core/errors/index.ts';
19
- import type { ParseResult } from '#internals/core/parse/index.ts';
20
- import type { CommandSchema } from '#internals/core/schema/index.ts';
21
- import { resolveArgs } from './args.ts';
22
- import type { DeprecationWarning, ResolveOptions, ResolveResult } from './contracts.ts';
23
- import { collectValidationErrors, isNonEmpty, throwAggregatedErrors } from './errors.ts';
24
- import { resolveFlags } from './flags.ts';
25
-
26
- /**
27
- * Resolve parsed values against a command schema.
28
- *
29
- * Low-level API: most applications should rely on `cli().run()`, `.execute()`,
30
- * or `runCommand()`, which already call {@linkcode resolve} at the right time.
31
- * Reach for this function when testing precedence rules directly or building
32
- * custom execution flows around {@linkcode CommandSchema}.
33
- *
34
- * Resolution order:
35
- * 1. CLI parsed value (from {@linkcode ParseResult})
36
- * 2. Env variable (from {@linkcode ResolveOptions.env}, if flag declares `envVar`)
37
- * 3. Config value (from {@linkcode ResolveOptions.config}, if flag declares `configPath`)
38
- * 4. Prompt (from {@linkcode ResolveOptions.prompter}, if flag declares `prompt`)
39
- * 5. Default value (from schema)
40
- *
41
- * After resolution, validates that all required flags and args have
42
- * a value. Collects **all** validation errors before throwing, so the
43
- * user sees every missing field at once.
44
- *
45
- * @param schema - The command schema defining flags and args
46
- * @param parsed - Raw parsed values from the parser
47
- * @param options - External state for the resolution chain
48
- * @returns Fully resolved flag and arg values
49
- * @throws {@linkcode ValidationError} if any required flag or arg is missing,
50
- * or if an env/config value fails coercion
51
- *
52
- * @example
53
- * ```ts
54
- * const parsed = parse(deploy.schema, ['production']);
55
- * const resolved = await resolve(deploy.schema, parsed, {
56
- * env: { DEPLOY_REGION: 'eu' },
57
- * });
58
- * ```
59
- */
60
- async function resolve(
61
- schema: CommandSchema,
62
- parsed: ParseResult,
63
- options?: ResolveOptions,
64
- ): Promise<ResolveResult> {
65
- const stdinData = options?.stdinData;
66
- const env = options?.env ?? {};
67
- const config = options?.config ?? {};
68
- const prompter = options?.prompter;
69
- const deprecations: DeprecationWarning[] = [];
70
- let flags: Readonly<Record<string, unknown>> = {};
71
- let args: Readonly<Record<string, unknown>> = {};
72
- const errors: ValidationError[] = [];
73
-
74
- try {
75
- flags = await resolveFlags(
76
- schema.flags,
77
- parsed.flags,
78
- env,
79
- config,
80
- prompter,
81
- schema.interactive,
82
- deprecations,
83
- );
84
- } catch (error) {
85
- if (!isValidationError(error)) {
86
- throw error;
87
- }
88
- errors.push(...collectValidationErrors(error));
89
- }
90
-
91
- try {
92
- args = resolveArgs(schema.args, parsed.args, stdinData, env, deprecations);
93
- } catch (error) {
94
- if (!isValidationError(error)) {
95
- throw error;
96
- }
97
- errors.push(...collectValidationErrors(error));
98
- }
99
-
100
- if (isNonEmpty(errors)) {
101
- throwAggregatedErrors(errors);
102
- }
103
-
104
- return { flags, args, deprecations };
105
- }
106
-
107
- export type { DeprecationWarning, ResolveOptions, ResolveResult };
108
- export { resolve };
@@ -1,99 +0,0 @@
1
- /**
2
- * Internal shared property-model helpers for resolver coercion.
3
- *
4
- * This seam is intentionally narrow: flags and args share coercion-compatible
5
- * kinds, but they do not share precedence order, fallback rules, or
6
- * required-value validation.
7
- *
8
- * @module dreamcli/core/resolve/property
9
- * @internal
10
- */
11
-
12
- import type { ArgSchema, FlagSchema } from '#internals/core/schema/index.ts';
13
-
14
- /** Flag/arg kinds that share a common coercion path. */
15
- const SHARED_PROPERTY_MODEL_KINDS = ['string', 'number', 'enum', 'custom'] as const;
16
-
17
- /** Union of kind discriminants that participate in shared coercion. */
18
- type SharedPropertyKind = (typeof SHARED_PROPERTY_MODEL_KINDS)[number];
19
-
20
- /** Minimal coercion-relevant slice of a flag or arg schema, discriminated by kind. */
21
- type SharedPropertySchema =
22
- | { readonly kind: 'string' }
23
- | { readonly kind: 'number' }
24
- | { readonly kind: 'enum'; readonly enumValues: readonly string[] | undefined }
25
- | { readonly kind: 'custom'; readonly parseFn?: (raw: unknown) => unknown };
26
-
27
- /** Contract asserting which concerns are shared vs. kept separate between flags and args. */
28
- interface SharedPropertyModelContract {
29
- /** Only coercion logic is shared; resolution orchestration is not. */
30
- readonly scope: 'coercion';
31
- /** The kind discriminants that participate in shared coercion. */
32
- readonly sharedKinds: readonly SharedPropertyKind[];
33
- /** Flag and arg precedence chains remain independent. */
34
- readonly keepsFlagAndArgPrecedenceSeparate: true;
35
- /** Fallback-on-coercion-error rules remain independent. */
36
- readonly keepsFallbackRulesSeparate: true;
37
- /** Required-value validation remains independent. */
38
- readonly keepsRequiredValueRulesSeparate: true;
39
- }
40
-
41
- /** Runtime-accessible contract instance for property model tests. */
42
- const sharedPropertyModelContract = {
43
- scope: 'coercion',
44
- sharedKinds: SHARED_PROPERTY_MODEL_KINDS,
45
- keepsFlagAndArgPrecedenceSeparate: true,
46
- keepsFallbackRulesSeparate: true,
47
- keepsRequiredValueRulesSeparate: true,
48
- } satisfies SharedPropertyModelContract;
49
-
50
- /** Extract the shared coercion slice from a flag schema, or `undefined` for boolean/array (handled separately). */
51
- function toSharedFlagPropertySchema(schema: FlagSchema): SharedPropertySchema | undefined {
52
- switch (schema.kind) {
53
- case 'string':
54
- return { kind: 'string' };
55
- case 'number':
56
- return { kind: 'number' };
57
- case 'enum':
58
- return { kind: 'enum', enumValues: schema.enumValues };
59
- case 'custom':
60
- return schema.parseFn === undefined
61
- ? { kind: 'custom' }
62
- : { kind: 'custom', parseFn: schema.parseFn };
63
- case 'boolean':
64
- case 'array':
65
- return undefined;
66
- }
67
- }
68
-
69
- /** Extract the shared coercion slice from an arg schema (all arg kinds are shared). */
70
- function toSharedArgPropertySchema(schema: ArgSchema): SharedPropertySchema {
71
- switch (schema.kind) {
72
- case 'string':
73
- return { kind: 'string' };
74
- case 'number':
75
- return { kind: 'number' };
76
- case 'enum':
77
- return { kind: 'enum', enumValues: schema.enumValues };
78
- case 'custom': {
79
- if (schema.parseFn === undefined) {
80
- return { kind: 'custom' };
81
- }
82
-
83
- const parseFn = schema.parseFn;
84
-
85
- return {
86
- kind: 'custom',
87
- parseFn: (raw: unknown): unknown => parseFn(typeof raw === 'string' ? raw : String(raw)),
88
- };
89
- }
90
- }
91
- }
92
-
93
- export type { SharedPropertyKind, SharedPropertyModelContract, SharedPropertySchema };
94
- export {
95
- SHARED_PROPERTY_MODEL_KINDS,
96
- sharedPropertyModelContract,
97
- toSharedArgPropertySchema,
98
- toSharedFlagPropertySchema,
99
- };
@@ -1,240 +0,0 @@
1
- /**
2
- * Activity types — spinner and progress bar handles, options, events.
3
- *
4
- * These types define the contract for `Out.spinner()` and `Out.progress()`
5
- * lifecycle management. Implementations live in `core/output/activity.ts`.
6
- *
7
- * @module dreamcli/core/schema/activity
8
- */
9
-
10
- // --- Fallback strategy
11
-
12
- /**
13
- * Non-TTY fallback strategy for spinners and progress bars.
14
- *
15
- * - `'silent'` — no output at all (default). Ideal for CI where decorative
16
- * output is noise.
17
- * - `'static'` — emit plain text via `out.log()` / `out.error()` at
18
- * lifecycle boundaries (start, succeed, fail). No animation.
19
- */
20
- type Fallback = 'silent' | 'static';
21
-
22
- // --- Spinner
23
-
24
- /** Options for {@link Out.spinner}. */
25
- interface SpinnerOptions {
26
- /**
27
- * Fallback strategy when `!isTTY` or `jsonMode`.
28
- * @defaultValue `'silent'`
29
- */
30
- readonly fallback?: Fallback;
31
- }
32
-
33
- /**
34
- * Handle returned by {@link Out.spinner} for lifecycle control.
35
- *
36
- * Terminal methods (`succeed`, `fail`, `stop`) are idempotent — calling any
37
- * of them after the handle is already stopped is a no-op, not an error.
38
- */
39
- interface SpinnerHandle {
40
- /** Update the spinner text (no-op if stopped). */
41
- update(text: string): void;
42
- /** Stop with a success symbol and optional final text. */
43
- succeed(text?: string): void;
44
- /** Stop with a failure symbol and optional final text. */
45
- fail(text?: string): void;
46
- /** Stop the spinner without a status symbol. */
47
- stop(): void;
48
- /**
49
- * Wrap a promise: auto-succeed on resolve, auto-fail on reject.
50
- *
51
- * @returns The resolved value of the wrapped promise.
52
- */
53
- wrap<T>(
54
- promise: Promise<T>,
55
- options?: {
56
- readonly succeed?: string;
57
- readonly fail?: string;
58
- },
59
- ): Promise<T>;
60
- }
61
-
62
- // --- Progress
63
-
64
- /** Options for {@link Out.progress}. */
65
- interface ProgressOptions {
66
- /**
67
- * Total units of work. When provided, the bar shows a determinate
68
- * percentage. When omitted, the bar pulses in indeterminate mode.
69
- */
70
- readonly total?: number;
71
- /** Label displayed alongside the progress bar. */
72
- readonly label?: string;
73
- /**
74
- * Fallback strategy when `!isTTY` or `jsonMode`.
75
- * @defaultValue `'silent'`
76
- */
77
- readonly fallback?: Fallback;
78
- }
79
-
80
- /**
81
- * Handle returned by {@link Out.progress} for lifecycle control.
82
- *
83
- * Terminal methods (`done`, `fail`) are idempotent — calling any
84
- * of them after the handle is already stopped is a no-op.
85
- */
86
- interface ProgressHandle {
87
- /** Advance progress by `n` units (default 1). */
88
- increment(n?: number): void;
89
- /** Set progress to an absolute value. */
90
- update(value: number): void;
91
- /** Mark progress as complete with an optional final message. */
92
- done(text?: string): void;
93
- /** Mark progress as failed with an optional final message. */
94
- fail(text?: string): void;
95
- }
96
-
97
- // --- Activity events
98
-
99
- /**
100
- * Discriminated union of spinner and progress lifecycle events.
101
- *
102
- * Captured by testkit in {@link RunResult.activity} for assertion
103
- * without polluting stdout/stderr arrays.
104
- */
105
- type ActivityEvent =
106
- | {
107
- /** Spinner created and started. */
108
- readonly type: 'spinner:start';
109
- /** Initial spinner text. */
110
- readonly text: string;
111
- }
112
- | {
113
- /** Spinner text changed. */
114
- readonly type: 'spinner:update';
115
- /** Updated spinner text. */
116
- readonly text: string;
117
- }
118
- | {
119
- /** Spinner completed successfully. */
120
- readonly type: 'spinner:succeed';
121
- /** Success message. */
122
- readonly text: string;
123
- }
124
- | {
125
- /** Spinner stopped with an error. */
126
- readonly type: 'spinner:fail';
127
- /** Failure message. */
128
- readonly text: string;
129
- }
130
- | {
131
- /** Spinner stopped without a final status. */
132
- readonly type: 'spinner:stop';
133
- }
134
- | {
135
- /** Progress bar created and started. */
136
- readonly type: 'progress:start';
137
- /** Bar label. */
138
- readonly label: string;
139
- /** Known total, or `undefined` for indeterminate. */
140
- readonly total: number | undefined;
141
- }
142
- | {
143
- /** Progress bar advanced. */
144
- readonly type: 'progress:increment';
145
- /** Amount advanced. */
146
- readonly delta: number;
147
- }
148
- | {
149
- /** Progress bar set to an absolute value. */
150
- readonly type: 'progress:update';
151
- /** New absolute value. */
152
- readonly value: number;
153
- }
154
- | {
155
- /** Progress bar completed. */
156
- readonly type: 'progress:done';
157
- /** Completion message, if any. */
158
- readonly text: string | undefined;
159
- }
160
- | {
161
- /** Progress bar stopped with an error. */
162
- readonly type: 'progress:fail';
163
- /** Failure message, if any. */
164
- readonly text: string | undefined;
165
- };
166
-
167
- // --- Table column descriptor
168
-
169
- /**
170
- * Describes a single column in table output.
171
- *
172
- * @typeParam T - The row object type (inferred from the rows array).
173
- */
174
- interface TableColumn<T extends Record<string, unknown>> {
175
- /** Property key on the row objects to display in this column. */
176
- readonly key: keyof T & string;
177
- /**
178
- * Header label for the column.
179
- * @defaultValue the {@link TableColumn.key | key} value
180
- */
181
- readonly header?: string;
182
- }
183
-
184
- /** Render format override for {@link Out.table}. */
185
- type TableFormat = 'auto' | 'text' | 'json';
186
-
187
- /** Output stream override for text table rendering. */
188
- type TableStream = 'stdout' | 'stderr';
189
-
190
- /**
191
- * Per-call table output options.
192
- *
193
- * `format: 'auto'` preserves the current mode-dependent behavior.
194
- * `format: 'json'` always emits a JSON array to stdout.
195
- * `format: 'text'` always renders a human-readable table; when `stream` is
196
- * omitted, text defaults to stdout in normal mode and stderr in jsonMode.
197
- */
198
- /** Preserve the mode-dependent default — text tables in normal mode, JSON in `jsonMode`. */
199
- interface TableOptionsAuto {
200
- /**
201
- * Follow the current output mode (text in normal, JSON in jsonMode).
202
- * @defaultValue `'auto'`
203
- */
204
- readonly format?: 'auto';
205
- }
206
-
207
- /** Force JSON array output to stdout regardless of output mode. */
208
- interface TableOptionsJson {
209
- /** Always emit a JSON array to stdout. */
210
- readonly format: 'json';
211
- }
212
-
213
- /** Force human-readable text table output, optionally routed to a specific {@link TableStream}. */
214
- interface TableOptionsText {
215
- /** Always render a human-readable text table. */
216
- readonly format: 'text';
217
- /** Target stream for text output. Falls back to stdout (stderr in jsonMode). */
218
- readonly stream?: TableStream;
219
- }
220
-
221
- /** Per-call rendering options for {@link Out.table}. */
222
- type TableOptions = TableOptionsAuto | TableOptionsJson | TableOptionsText;
223
-
224
- // --- Exports
225
-
226
- export type {
227
- ActivityEvent,
228
- Fallback,
229
- ProgressHandle,
230
- ProgressOptions,
231
- SpinnerHandle,
232
- SpinnerOptions,
233
- TableColumn,
234
- TableFormat,
235
- TableOptions,
236
- TableOptionsAuto,
237
- TableOptionsJson,
238
- TableOptionsText,
239
- TableStream,
240
- };