@kjanat/dreamcli 3.0.0-rc.1 → 3.0.0-rc.3

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 (137) hide show
  1. package/CHANGELOG.md +37 -1
  2. package/dist/core/cli/dispatch.mjs +214 -1
  3. package/dist/core/cli/help-links.mjs +41 -1
  4. package/dist/core/cli/index.mjs +901 -1
  5. package/dist/core/cli/planner.mjs +300 -1
  6. package/dist/core/cli/plugin.mjs +41 -1
  7. package/dist/core/cli/propagate.mjs +57 -1
  8. package/dist/core/cli/root-help.mjs +208 -4
  9. package/dist/core/cli/root-surface.mjs +27 -1
  10. package/dist/core/cli/runtime-preflight.mjs +168 -1
  11. package/dist/core/completion/index.mjs +90 -1
  12. package/dist/core/completion/shells/bash.mjs +304 -3
  13. package/dist/core/completion/shells/fish.mjs +159 -2
  14. package/dist/core/completion/shells/powershell.mjs +353 -2
  15. package/dist/core/completion/shells/shared.mjs +154 -1
  16. package/dist/core/completion/shells/zsh.mjs +244 -2
  17. package/dist/core/config/index.mjs +246 -1
  18. package/dist/core/config/package-json.mjs +385 -3
  19. package/dist/core/errors/index.mjs +87 -1
  20. package/dist/core/execution/index.mjs +189 -1
  21. package/dist/core/help/ansi.mjs +122 -2
  22. package/dist/core/help/index.mjs +329 -7
  23. package/dist/core/json-schema/index.mjs +487 -9
  24. package/dist/core/json-schema/meta-descriptions.generated.mjs +93 -28
  25. package/dist/core/output/activity.mjs +452 -1
  26. package/dist/core/output/bind.mjs +56 -1
  27. package/dist/core/output/contracts.mjs +57 -1
  28. package/dist/core/output/display-value.mjs +32 -1
  29. package/dist/core/output/index.d.mts +21 -0
  30. package/dist/core/output/index.mjs +442 -2
  31. package/dist/core/output/renderers.mjs +46 -1
  32. package/dist/core/output/writer.mjs +12 -1
  33. package/dist/core/parse/index.mjs +555 -1
  34. package/dist/core/prompt/index.d.mts +0 -1
  35. package/dist/core/prompt/index.mjs +348 -6
  36. package/dist/core/resolve/args.mjs +105 -1
  37. package/dist/core/resolve/coerce.mjs +279 -1
  38. package/dist/core/resolve/config.mjs +19 -1
  39. package/dist/core/resolve/errors.mjs +140 -2
  40. package/dist/core/resolve/flags.mjs +196 -1
  41. package/dist/core/resolve/index.mjs +85 -1
  42. package/dist/core/resolve/property.d.mts +0 -1
  43. package/dist/core/resolve/property.mjs +45 -1
  44. package/dist/core/schema/arg.mjs +463 -1
  45. package/dist/core/schema/command.d.mts +18 -0
  46. package/dist/core/schema/command.mjs +712 -1
  47. package/dist/core/schema/flag.mjs +453 -1
  48. package/dist/core/schema/middleware.mjs +41 -1
  49. package/dist/core/schema/number-constraints.mjs +60 -1
  50. package/dist/core/schema-dsl/runtime.mjs +271 -2
  51. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  52. package/dist/core/testkit/index.mjs +83 -1
  53. package/dist/index.d.mts +2 -1
  54. package/dist/index.mjs +22 -1
  55. package/dist/runtime/adapter.mjs +82 -1
  56. package/dist/runtime/auto.mjs +46 -1
  57. package/dist/runtime/bun.mjs +28 -1
  58. package/dist/runtime/deno.mjs +217 -2
  59. package/dist/runtime/detect.mjs +45 -1
  60. package/dist/runtime/node.mjs +169 -2
  61. package/dist/runtime/paths.mjs +48 -1
  62. package/dist/runtime.mjs +7 -1
  63. package/dist/strings.mjs +22 -1
  64. package/dist/testkit.mjs +5 -1
  65. package/dist/version.d.mts +7 -3
  66. package/dist/version.mjs +7 -1
  67. package/package.json +21 -26
  68. package/src/core/cli/dispatch.ts +0 -355
  69. package/src/core/cli/help-links.ts +0 -82
  70. package/src/core/cli/index.ts +0 -1614
  71. package/src/core/cli/planner.ts +0 -656
  72. package/src/core/cli/plugin.ts +0 -117
  73. package/src/core/cli/propagate.ts +0 -97
  74. package/src/core/cli/root-help.ts +0 -342
  75. package/src/core/cli/root-surface.ts +0 -87
  76. package/src/core/cli/runtime-preflight.ts +0 -456
  77. package/src/core/completion/index.ts +0 -138
  78. package/src/core/completion/shells/bash.ts +0 -459
  79. package/src/core/completion/shells/fish.ts +0 -259
  80. package/src/core/completion/shells/powershell.ts +0 -439
  81. package/src/core/completion/shells/shared.ts +0 -310
  82. package/src/core/completion/shells/zsh.ts +0 -381
  83. package/src/core/config/index.ts +0 -417
  84. package/src/core/config/package-json.ts +0 -560
  85. package/src/core/errors/index.ts +0 -193
  86. package/src/core/execution/index.ts +0 -265
  87. package/src/core/help/ansi.ts +0 -144
  88. package/src/core/help/index.ts +0 -563
  89. package/src/core/json-schema/index.ts +0 -910
  90. package/src/core/json-schema/meta-descriptions.generated.ts +0 -202
  91. package/src/core/output/activity.ts +0 -575
  92. package/src/core/output/bind.ts +0 -59
  93. package/src/core/output/contracts.ts +0 -194
  94. package/src/core/output/display-value.ts +0 -48
  95. package/src/core/output/index.ts +0 -704
  96. package/src/core/output/renderers.ts +0 -125
  97. package/src/core/output/writer.ts +0 -46
  98. package/src/core/parse/index.ts +0 -742
  99. package/src/core/prompt/index.ts +0 -623
  100. package/src/core/resolve/args.ts +0 -144
  101. package/src/core/resolve/coerce.ts +0 -500
  102. package/src/core/resolve/config.ts +0 -26
  103. package/src/core/resolve/contracts.ts +0 -135
  104. package/src/core/resolve/errors.ts +0 -227
  105. package/src/core/resolve/flags.ts +0 -269
  106. package/src/core/resolve/index.ts +0 -108
  107. package/src/core/resolve/property.ts +0 -99
  108. package/src/core/schema/activity.ts +0 -240
  109. package/src/core/schema/arg.ts +0 -841
  110. package/src/core/schema/command.ts +0 -1500
  111. package/src/core/schema/flag.ts +0 -917
  112. package/src/core/schema/index.ts +0 -96
  113. package/src/core/schema/middleware.ts +0 -171
  114. package/src/core/schema/number-constraints.ts +0 -153
  115. package/src/core/schema/prompt.ts +0 -171
  116. package/src/core/schema/run.ts +0 -198
  117. package/src/core/schema-dsl/index.ts +0 -109
  118. package/src/core/schema-dsl/parse.ts +0 -262
  119. package/src/core/schema-dsl/runtime.ts +0 -609
  120. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  121. package/src/core/testkit/index.ts +0 -147
  122. package/src/index.ts +0 -181
  123. package/src/runtime/adapter.ts +0 -303
  124. package/src/runtime/auto.ts +0 -86
  125. package/src/runtime/bun.ts +0 -48
  126. package/src/runtime/deno.ts +0 -367
  127. package/src/runtime/detect.ts +0 -105
  128. package/src/runtime/index.ts +0 -21
  129. package/src/runtime/node-builtins.d.ts +0 -27
  130. package/src/runtime/node.ts +0 -289
  131. package/src/runtime/paths.ts +0 -64
  132. package/src/runtime/support.ts +0 -77
  133. package/src/runtime.ts +0 -31
  134. package/src/schema.ts +0 -16
  135. package/src/strings.ts +0 -34
  136. package/src/testkit.ts +0 -25
  137. package/src/version.ts +0 -20
@@ -1,96 +0,0 @@
1
- /**
2
- * Command, flag, and arg schema builders with full type inference.
3
- *
4
- * @module dreamcli/core/schema
5
- */
6
-
7
- export type {
8
- ActivityEvent,
9
- Fallback,
10
- ProgressHandle,
11
- ProgressOptions,
12
- SpinnerHandle,
13
- SpinnerOptions,
14
- TableColumn,
15
- TableFormat,
16
- TableOptions,
17
- TableStream,
18
- } from './activity.ts';
19
- export type {
20
- ArgConfig,
21
- ArgFactory,
22
- ArgKind,
23
- ArgParseFn,
24
- ArgPresence,
25
- ArgSchema,
26
- InferArg,
27
- InferArgs,
28
- ResolvedArgValue,
29
- WithArgPresence,
30
- WithVariadic,
31
- } from './arg.ts';
32
- export { ARG_KINDS, ARG_PRESENCES, ArgBuilder, arg, createArgSchema } from './arg.ts';
33
- export type {
34
- ActionHandler,
35
- ActionParams,
36
- AnyCommandBuilder,
37
- CommandArgEntry,
38
- CommandConfig,
39
- CommandExample,
40
- CommandMeta,
41
- CommandSchema,
42
- DeriveHandler,
43
- DeriveParams,
44
- ErasedCommand,
45
- ErasedDeriveHandler,
46
- ErasedInteractiveResolver,
47
- InteractiveParams,
48
- InteractiveResolver,
49
- InteractiveResult,
50
- Out,
51
- } from './command.ts';
52
- export { CommandBuilder, command, group } from './command.ts';
53
- export type {
54
- ConfirmPromptConfig,
55
- FlagAlias,
56
- FlagConfig,
57
- FlagFactory,
58
- FlagKind,
59
- FlagParseFn,
60
- FlagPresence,
61
- FlagSchema,
62
- FlagSchemaOverrides,
63
- InferFlag,
64
- InferFlags,
65
- InputPromptConfig,
66
- MultiselectPromptConfig,
67
- PromptConfig,
68
- PromptConfigBase,
69
- PromptKind,
70
- PromptResult,
71
- ResolvedValue,
72
- SelectChoice,
73
- SelectPromptConfig,
74
- WithPresence,
75
- } from './flag.ts';
76
- export {
77
- createSchema,
78
- FLAG_KINDS,
79
- FLAG_PRESENCES,
80
- FlagBuilder,
81
- flag,
82
- PROMPT_KINDS,
83
- } from './flag.ts';
84
- export type {
85
- ErasedMiddlewareHandler,
86
- Middleware,
87
- MiddlewareHandler,
88
- MiddlewareParams,
89
- } from './middleware.ts';
90
- export { middleware } from './middleware.ts';
91
- export type { NumberConstraints, NumberConstraintViolation } from './number-constraints.ts';
92
- export {
93
- describeNumberConstraintViolation,
94
- validateNumberConstraints,
95
- } from './number-constraints.ts';
96
- export type { RunOptions, RunResult } from './run.ts';
@@ -1,171 +0,0 @@
1
- /**
2
- * Middleware type definitions and factory function.
3
- *
4
- * Middleware runs before the action handler and can:
5
- * - Add typed context via `next({ key: value })`
6
- * - Short-circuit by throwing `CLIError` (or not calling `next`)
7
- * - Wrap downstream execution (timing, logging) by awaiting `next()`
8
- *
9
- * The {@linkcode Middleware} type uses a phantom generic to track what
10
- * context properties this middleware adds. At runtime, middleware is
11
- * type-erased — the phantom type is only used for compile-time inference
12
- * when `.middleware()` is chained on `CommandBuilder`.
13
- *
14
- * @module dreamcli/core/schema/middleware
15
- */
16
-
17
- import type { CommandMeta, Out } from './command.ts';
18
-
19
- // --- Middleware parameter types
20
-
21
- /**
22
- * Parameters received by a middleware function at runtime.
23
- *
24
- * Middleware receives erased args/flags (since it's defined independently
25
- * of commands) plus the accumulated context from prior middleware and a
26
- * `next` function to continue the chain.
27
- */
28
- interface MiddlewareParams {
29
- /** Fully resolved positional arguments (type-erased). */
30
- readonly args: Readonly<Record<string, unknown>>;
31
- /** Fully resolved flags (type-erased). */
32
- readonly flags: Readonly<Record<string, unknown>>;
33
- /** Context accumulated from previous middleware in the chain. */
34
- readonly ctx: Readonly<Record<string, unknown>>;
35
- /** Output channel. */
36
- readonly out: Out;
37
- /** CLI program metadata (name, bin, version, command). */
38
- readonly meta: CommandMeta;
39
- /**
40
- * Continue to the next middleware or action handler.
41
- *
42
- * Call with context additions that merge into `ctx` for downstream.
43
- * Returns when the entire downstream chain completes — enabling
44
- * wrap-around patterns (timing, try/catch, cleanup).
45
- */
46
- readonly next: (additions: Record<string, unknown>) => Promise<void>;
47
- }
48
-
49
- // --- Handler types
50
-
51
- /**
52
- * Type-erased middleware handler stored on `CommandSchema`.
53
- *
54
- * At runtime, all middleware handlers have this signature. The phantom
55
- * `Output` type on {@linkcode Middleware} is erased.
56
- *
57
- * @internal
58
- */
59
- type ErasedMiddlewareHandler = (params: MiddlewareParams) => void | Promise<void>;
60
-
61
- /**
62
- * Middleware handler function with typed `next()` parameter.
63
- *
64
- * The `Output` generic constrains what properties must be passed to
65
- * {@linkcode MiddlewareParams.next | next()}, ensuring type-safe context additions at the call site.
66
- */
67
- type MiddlewareHandler<Output extends Record<string, unknown>> = (params: {
68
- readonly args: Readonly<Record<string, unknown>>;
69
- readonly flags: Readonly<Record<string, unknown>>;
70
- readonly ctx: Readonly<Record<string, unknown>>;
71
- readonly out: Out;
72
- readonly meta: CommandMeta;
73
- /** Pass context additions downstream. Must include all `Output` properties. */
74
- readonly next: (additions: Output) => Promise<void>;
75
- }) => void | Promise<void>;
76
-
77
- // --- Middleware type — phantom-branded
78
-
79
- /**
80
- * Internal runtime representation of middleware.
81
- * @internal
82
- */
83
- interface MiddlewareImpl {
84
- readonly _handler: ErasedMiddlewareHandler;
85
- }
86
-
87
- /**
88
- * Middleware with phantom output type.
89
- *
90
- * The `Output` parameter tracks what this middleware adds to context at
91
- * compile time. The `_output` brand is phantom — it exists only in the
92
- * type system for inference, not at runtime.
93
- *
94
- * Created via the {@linkcode middleware} factory. Attached to commands via
95
- * `CommandBuilder.middleware()`.
96
- *
97
- * @example
98
- * ```ts
99
- * interface User { id: string; name: string }
100
- *
101
- * const auth = middleware<{ user: User }>(async ({ next }) => {
102
- * const user = await getUser();
103
- * if (!user) throw new CLIError('Not authenticated', { code: 'AUTH_REQUIRED' });
104
- * return next({ user });
105
- * });
106
- * ```
107
- */
108
- type Middleware<Output extends Record<string, unknown>> = MiddlewareImpl & {
109
- /** @internal Phantom type brand — compile-time only. */
110
- readonly _output: Output;
111
- };
112
-
113
- // --- Factory
114
-
115
- /**
116
- * Create a middleware definition.
117
- *
118
- * Middleware runs before the action handler and can add typed context,
119
- * short-circuit execution, or wrap downstream processing.
120
- *
121
- * @param handler - Function receiving `{ args, flags, ctx, out, meta, next }`.
122
- * Call `next(additions)` to continue the chain with added context.
123
- * Omitting the `next()` call short-circuits (e.g., for auth guards).
124
- * @returns {@linkcode Middleware} to attach via `CommandBuilder.middleware()`.
125
- *
126
- * @example
127
- * ```ts
128
- * // Auth guard — adds user to context or throws
129
- * const auth = middleware(async ({ next }) => {
130
- * const user = await getUser();
131
- * if (!user) throw new CLIError('Not authenticated', { code: 'AUTH_REQUIRED' });
132
- * return next({ user });
133
- * });
134
- *
135
- * // Timing wrapper — measures downstream execution
136
- * const timing = middleware(async ({ out, next }) => {
137
- * const start = Date.now();
138
- * await next({});
139
- * out.info(`Done in ${Date.now() - start}ms`);
140
- * });
141
- *
142
- * command('deploy')
143
- * .middleware(timing)
144
- * .middleware(auth)
145
- * .action(({ ctx }) => {
146
- * console.log(ctx.user.name); // typed!
147
- * });
148
- * ```
149
- */
150
- function middleware<Output extends Record<string, unknown>>(
151
- handler: MiddlewareHandler<Output>,
152
- ): Middleware<Output> {
153
- // Runtime representation is just { _handler }.
154
- // The type assertion establishes the phantom _output brand —
155
- // no runtime property is created. handler's Output-constrained
156
- // next() is compatible with the erased (Record<string, unknown>)
157
- // signature at runtime.
158
- const impl: MiddlewareImpl = { _handler: handler as ErasedMiddlewareHandler };
159
- return impl as Middleware<Output>;
160
- }
161
-
162
- // --- Exports
163
-
164
- export type {
165
- ErasedMiddlewareHandler,
166
- Middleware,
167
- MiddlewareHandler,
168
- MiddlewareImpl,
169
- MiddlewareParams,
170
- };
171
- export { middleware };
@@ -1,153 +0,0 @@
1
- /**
2
- * Numeric constraints for number-valued flags and args.
3
- *
4
- * A single, shared representation and validator so the parse path
5
- * (`core/parse`) and the resolver coercion path (`core/resolve/coerce`) cannot
6
- * drift: both import {@link validateNumberConstraints} and apply the checks in
7
- * the same order (finite → int → min → max).
8
- *
9
- * @module dreamcli/core/schema/number-constraints
10
- */
11
-
12
- /**
13
- * Runtime numeric constraints attached to a number flag/arg schema.
14
- *
15
- * Bounds are **inclusive**. All fields are optional; an absent field means "no
16
- * constraint" except for {@link NumberConstraints.finite | finite}, which
17
- * defaults to `true` (so `Infinity` / `-Infinity` are rejected unless opted
18
- * back in).
19
- */
20
- interface NumberConstraints {
21
- /**
22
- * Inclusive lower bound. Values below this are rejected.
23
- * @defaultValue `undefined` (no lower bound)
24
- */
25
- readonly min?: number;
26
- /**
27
- * Inclusive upper bound. Values above this are rejected.
28
- * @defaultValue `undefined` (no upper bound)
29
- */
30
- readonly max?: number;
31
- /**
32
- * Require an integer value. Non-integers (e.g. `3.7`) are rejected.
33
- * @defaultValue `false`
34
- */
35
- readonly int?: boolean;
36
- /**
37
- * Require a finite value. When `true`, `Infinity` / `-Infinity` are rejected.
38
- * @defaultValue `true`
39
- */
40
- readonly finite?: boolean;
41
- }
42
-
43
- /**
44
- * A failed numeric constraint, discriminated by which rule was violated.
45
- *
46
- * `min` / `max` carry the offending bound so callers can render it.
47
- */
48
- type NumberConstraintViolation =
49
- | { readonly kind: 'finite' }
50
- | { readonly kind: 'int' }
51
- | { readonly kind: 'min'; readonly bound: number }
52
- | { readonly kind: 'max'; readonly bound: number };
53
-
54
- /** Default for {@link NumberConstraints.finite} — reject `Infinity` unless opted out. */
55
- const DEFAULT_FINITE = true;
56
-
57
- /**
58
- * Validate a numeric value against constraints.
59
- *
60
- * The single source of truth for numeric-constraint checks, shared by the
61
- * parse and coerce paths. Checks run in a fixed order — **finite → int → min →
62
- * max** — and the first failure is returned. `NaN` is always rejected as a
63
- * `finite` violation, regardless of the `finite` option (a non-finite value can
64
- * otherwise slip past `min`/`max`, since `NaN < x` and `NaN > x` are both false).
65
- *
66
- * @param value - The numeric value to validate.
67
- * @param constraints - Constraints to enforce, or `undefined` for defaults.
68
- * @returns The first {@link NumberConstraintViolation}, or `undefined` if valid.
69
- */
70
- function validateNumberConstraints(
71
- value: number,
72
- constraints: NumberConstraints | undefined,
73
- ): NumberConstraintViolation | undefined {
74
- if (Number.isNaN(value)) {
75
- return { kind: 'finite' };
76
- }
77
- const finite = constraints?.finite ?? DEFAULT_FINITE;
78
- if (finite && !Number.isFinite(value)) {
79
- return { kind: 'finite' };
80
- }
81
- if (constraints?.int === true && !Number.isInteger(value)) {
82
- return { kind: 'int' };
83
- }
84
- if (constraints?.min !== undefined && value < constraints.min) {
85
- return { kind: 'min', bound: constraints.min };
86
- }
87
- if (constraints?.max !== undefined && value > constraints.max) {
88
- return { kind: 'max', bound: constraints.max };
89
- }
90
- return undefined;
91
- }
92
-
93
- /**
94
- * Render a terse, human-readable reason for a constraint violation.
95
- *
96
- * @param violation - The violation to describe.
97
- * @returns A message suffix such as `must be an integer` or `must be >= 0`.
98
- */
99
- function describeNumberConstraintViolation(violation: NumberConstraintViolation): string {
100
- switch (violation.kind) {
101
- case 'finite':
102
- return 'must be a finite number';
103
- case 'int':
104
- return 'must be an integer';
105
- case 'min':
106
- return `must be >= ${violation.bound}`;
107
- case 'max':
108
- return `must be <= ${violation.bound}`;
109
- }
110
- }
111
-
112
- /**
113
- * Assert that a constraints object is well-formed at schema-construction time.
114
- *
115
- * `min` / `max` must be finite — an infinite or `NaN` bound is meaningless (omit
116
- * the field for "no bound") and would serialize to `null` in the emitted JSON
117
- * Schema. An inverted range (`min > max`) is also rejected, since it makes the
118
- * flag/arg permanently unsatisfiable. Throws so the misconfiguration surfaces
119
- * where the flag/arg is declared, not at parse time.
120
- *
121
- * @param constraints - The constraints to validate.
122
- * @throws RangeError if `min` or `max` is non-finite (`Infinity` / `-Infinity` /
123
- * `NaN`), or if `min` exceeds `max`.
124
- */
125
- function assertNumberConstraints(constraints: NumberConstraints): void {
126
- if (constraints.min !== undefined && !Number.isFinite(constraints.min)) {
127
- throw new RangeError(
128
- `number constraint 'min' must be a finite number (got ${constraints.min}); omit it for no lower bound`,
129
- );
130
- }
131
- if (constraints.max !== undefined && !Number.isFinite(constraints.max)) {
132
- throw new RangeError(
133
- `number constraint 'max' must be a finite number (got ${constraints.max}); omit it for no upper bound`,
134
- );
135
- }
136
- if (
137
- constraints.min !== undefined &&
138
- constraints.max !== undefined &&
139
- constraints.min > constraints.max
140
- ) {
141
- throw new RangeError(
142
- `number constraint 'min' (${constraints.min}) must not exceed 'max' (${constraints.max})`,
143
- );
144
- }
145
- }
146
-
147
- export type { NumberConstraints, NumberConstraintViolation };
148
- export {
149
- assertNumberConstraints,
150
- DEFAULT_FINITE,
151
- describeNumberConstraintViolation,
152
- validateNumberConstraints,
153
- };
@@ -1,171 +0,0 @@
1
- /**
2
- * Prompt type definitions for interactive flag resolution.
3
- *
4
- * Prompt configuration is stored on `FlagSchema.prompt` and consumed by the
5
- * resolution chain (v0.3+) when a flag value is missing after CLI/env/config
6
- * resolution. The prompt engine reads this config to present the appropriate
7
- * UI to the user.
8
- *
9
- * @module dreamcli/core/schema/prompt
10
- */
11
-
12
- // --- Prompt kind discriminator
13
-
14
- /** All prompt kind discriminators as a runtime array. */
15
- const PROMPT_KINDS = ['confirm', 'input', 'select', 'multiselect'] as const;
16
-
17
- /**
18
- * The kind of interactive prompt to present.
19
- *
20
- * - `'confirm'` — yes/no boolean question
21
- * - `'input'` — free-text string input
22
- * - `'select'` — single selection from a list
23
- * - `'multiselect'` — multiple selections from a list
24
- */
25
- type PromptKind = (typeof PROMPT_KINDS)[number];
26
-
27
- // --- Per-kind prompt configuration (discriminated union)
28
-
29
- /** Shared fields across all prompt kinds. */
30
- interface PromptConfigBase {
31
- /** The question displayed to the user. */
32
- readonly message: string;
33
- }
34
-
35
- /** Yes/no confirmation prompt — maps to `boolean` flags. Part of {@link PromptConfig}. */
36
- interface ConfirmPromptConfig extends PromptConfigBase {
37
- /** Discriminator identifying this as a yes/no confirmation prompt. */
38
- readonly kind: 'confirm';
39
- /**
40
- * Value used when the user submits an empty line (presses Enter). Also
41
- * drives the displayed hint: `true` → `(Y/n)`, `false` → `(y/N)`.
42
- * @defaultValue `true`
43
- */
44
- readonly default?: boolean;
45
- }
46
-
47
- /** Free-text input prompt — maps to `string` and `number` flags. Part of {@link PromptConfig}. */
48
- interface InputPromptConfig extends PromptConfigBase {
49
- /** Discriminator identifying this as a free-text input prompt. */
50
- readonly kind: 'input';
51
- /** Placeholder text shown before user types (informational only). */
52
- readonly placeholder?: string;
53
- /**
54
- * Value used when the user submits an empty line (presses Enter), shown in
55
- * the hint as `(default: <value>)`. When set, an empty submission resolves
56
- * to this value without running {@link InputPromptConfig.validate | validate}.
57
- * When omitted, an empty submission is treated as "no answer" so resolution
58
- * falls through to the flag's `.default()`.
59
- * @defaultValue `undefined`
60
- */
61
- readonly default?: string;
62
- /**
63
- * Inline validation function. Return `true` if valid, or a string
64
- * error message if invalid. Called before coercion to flag kind.
65
- */
66
- readonly validate?: (value: string) => true | string;
67
- }
68
-
69
- /** Single-selection prompt — maps to `enum` flags or any flag with {@link SelectChoice choices}. Part of {@link PromptConfig}. */
70
- interface SelectPromptConfig extends PromptConfigBase {
71
- /** Discriminator identifying this as a single-selection prompt. */
72
- readonly kind: 'select';
73
- /**
74
- * Available choices. When omitted for `enum` flags, the enum values
75
- * from the flag schema are used automatically.
76
- */
77
- readonly choices?: readonly SelectChoice[];
78
- }
79
-
80
- /**
81
- * Multi-selection prompt — maps to `array` flags.
82
- * Returns an array of selected {@link SelectChoice} values. Part of {@link PromptConfig}.
83
- */
84
- interface MultiselectPromptConfig extends PromptConfigBase {
85
- /** Discriminator identifying this as a multi-selection prompt. */
86
- readonly kind: 'multiselect';
87
- /**
88
- * Available choices. When omitted for `array` flags with enum elements,
89
- * the enum values from the element schema are used automatically.
90
- */
91
- readonly choices?: readonly SelectChoice[];
92
- /**
93
- * Minimum number of selections required.
94
- * @defaultValue `0`
95
- */
96
- readonly min?: number;
97
- /**
98
- * Maximum number of selections allowed.
99
- * @defaultValue `Infinity`
100
- */
101
- readonly max?: number;
102
- }
103
-
104
- // --- Supporting types
105
-
106
- /** A selectable option for {@link SelectPromptConfig} and {@link MultiselectPromptConfig} prompts. */
107
- interface SelectChoice {
108
- /** The value returned when this choice is selected. */
109
- readonly value: string;
110
- /**
111
- * Display label shown to the user.
112
- * @defaultValue {@link SelectChoice.value | value}
113
- */
114
- readonly label?: string;
115
- /** Optional description shown alongside the choice. */
116
- readonly description?: string;
117
- }
118
-
119
- /**
120
- * Discriminated union of all prompt configurations.
121
- *
122
- * Use the `kind` field to narrow:
123
- * ```ts
124
- * if (config.kind === 'select') {
125
- * config.choices // readonly SelectChoice[] | undefined
126
- * }
127
- * ```
128
- */
129
- type PromptConfig =
130
- | ConfirmPromptConfig
131
- | InputPromptConfig
132
- | SelectPromptConfig
133
- | MultiselectPromptConfig;
134
-
135
- // --- Prompt result
136
-
137
- /**
138
- * The raw result returned by a prompt engine for a single prompt.
139
- *
140
- * - `answered: true` — user provided a value
141
- * - `answered: false` — user cancelled/aborted (Ctrl+C, ESC, etc.)
142
- *
143
- * Coercion to the flag's kind is the resolver's responsibility, not the
144
- * prompt engine's.
145
- */
146
- type PromptResult =
147
- | {
148
- /** User provided a value. */
149
- readonly answered: true;
150
- /** The raw value from the prompt engine (not yet coerced). */
151
- readonly value: unknown;
152
- }
153
- | {
154
- /** User cancelled or aborted (Ctrl+C, ESC, etc.). */
155
- readonly answered: false;
156
- };
157
-
158
- // --- Exports
159
-
160
- export type {
161
- ConfirmPromptConfig,
162
- InputPromptConfig,
163
- MultiselectPromptConfig,
164
- PromptConfig,
165
- PromptConfigBase,
166
- PromptKind,
167
- PromptResult,
168
- SelectChoice,
169
- SelectPromptConfig,
170
- };
171
- export { PROMPT_KINDS };