@kjanat/dreamcli 3.0.0-rc.1 → 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 (194) hide show
  1. package/CHANGELOG.md +217 -1
  2. package/dist/core/cli/dispatch.d.mts +6 -5
  3. package/dist/core/cli/dispatch.mjs +205 -1
  4. package/dist/core/cli/help-links.d.mts +0 -1
  5. package/dist/core/cli/help-links.mjs +41 -1
  6. package/dist/core/cli/index.d.mts +81 -8
  7. package/dist/core/cli/index.mjs +945 -1
  8. package/dist/core/cli/planner.d.mts +5 -1
  9. package/dist/core/cli/planner.mjs +300 -1
  10. package/dist/core/cli/plugin.d.mts +1 -1
  11. package/dist/core/cli/plugin.mjs +41 -1
  12. package/dist/core/cli/propagate.d.mts +1 -1
  13. package/dist/core/cli/propagate.mjs +57 -1
  14. package/dist/core/cli/root-help.d.mts +2 -1
  15. package/dist/core/cli/root-help.mjs +226 -4
  16. package/dist/core/cli/root-surface.d.mts +12 -1
  17. package/dist/core/cli/root-surface.mjs +28 -1
  18. package/dist/core/cli/runtime-preflight.d.mts +14 -2
  19. package/dist/core/cli/runtime-preflight.mjs +169 -1
  20. package/dist/core/completion/index.d.mts +0 -1
  21. package/dist/core/completion/index.mjs +90 -1
  22. package/dist/core/completion/shells/bash.d.mts +0 -1
  23. package/dist/core/completion/shells/bash.mjs +308 -3
  24. package/dist/core/completion/shells/fish.d.mts +0 -1
  25. package/dist/core/completion/shells/fish.mjs +162 -2
  26. package/dist/core/completion/shells/powershell.d.mts +0 -1
  27. package/dist/core/completion/shells/powershell.mjs +358 -2
  28. package/dist/core/completion/shells/shared.d.mts +13 -2
  29. package/dist/core/completion/shells/shared.mjs +176 -1
  30. package/dist/core/completion/shells/zsh.d.mts +0 -1
  31. package/dist/core/completion/shells/zsh.mjs +251 -2
  32. package/dist/core/config/index.d.mts +2 -3
  33. package/dist/core/config/index.mjs +246 -1
  34. package/dist/core/config/package-json.d.mts +27 -4
  35. package/dist/core/config/package-json.mjs +386 -3
  36. package/dist/core/errors/index.d.mts +3 -3
  37. package/dist/core/errors/index.mjs +87 -1
  38. package/dist/core/execution/index.d.mts +0 -1
  39. package/dist/core/execution/index.mjs +201 -1
  40. package/dist/core/help/ansi.d.mts +11 -5
  41. package/dist/core/help/ansi.mjs +121 -2
  42. package/dist/core/help/index.d.mts +22 -3
  43. package/dist/core/help/index.mjs +341 -7
  44. package/dist/core/help/theme.d.mts +68 -0
  45. package/dist/core/help/theme.mjs +46 -0
  46. package/dist/core/json-schema/index.d.mts +15 -2
  47. package/dist/core/json-schema/index.mjs +536 -12
  48. package/dist/core/json-schema/meta-descriptions.generated.d.mts +55 -38
  49. package/dist/core/json-schema/meta-descriptions.generated.mjs +102 -28
  50. package/dist/core/output/activity.d.mts +0 -1
  51. package/dist/core/output/activity.mjs +452 -1
  52. package/dist/core/output/bind.mjs +56 -1
  53. package/dist/core/output/contracts.d.mts +4 -5
  54. package/dist/core/output/contracts.mjs +57 -1
  55. package/dist/core/output/display-value.mjs +32 -1
  56. package/dist/core/output/index.d.mts +21 -1
  57. package/dist/core/output/index.mjs +442 -2
  58. package/dist/core/output/renderers.d.mts +0 -1
  59. package/dist/core/output/renderers.mjs +46 -1
  60. package/dist/core/output/writer.mjs +12 -1
  61. package/dist/core/parse/index.d.mts +40 -7
  62. package/dist/core/parse/index.mjs +727 -1
  63. package/dist/core/prompt/index.d.mts +1 -1
  64. package/dist/core/prompt/index.mjs +348 -6
  65. package/dist/core/resolve/args.d.mts +1 -1
  66. package/dist/core/resolve/args.mjs +105 -1
  67. package/dist/core/resolve/coerce.d.mts +1 -1
  68. package/dist/core/resolve/coerce.mjs +336 -1
  69. package/dist/core/resolve/config.mjs +19 -1
  70. package/dist/core/resolve/contracts.d.mts +9 -4
  71. package/dist/core/resolve/errors.d.mts +0 -1
  72. package/dist/core/resolve/errors.mjs +140 -2
  73. package/dist/core/resolve/flags.d.mts +7 -2
  74. package/dist/core/resolve/flags.mjs +251 -1
  75. package/dist/core/resolve/index.d.mts +2 -2
  76. package/dist/core/resolve/index.mjs +85 -1
  77. package/dist/core/resolve/property.d.mts +4 -2
  78. package/dist/core/resolve/property.mjs +53 -1
  79. package/dist/core/schema/activity.d.mts +31 -11
  80. package/dist/core/schema/arg.d.mts +3 -4
  81. package/dist/core/schema/arg.mjs +463 -1
  82. package/dist/core/schema/command.d.mts +26 -6
  83. package/dist/core/schema/command.mjs +726 -1
  84. package/dist/core/schema/flag.d.mts +485 -19
  85. package/dist/core/schema/flag.mjs +705 -1
  86. package/dist/core/schema/index.d.mts +4 -2
  87. package/dist/core/schema/middleware.d.mts +4 -3
  88. package/dist/core/schema/middleware.mjs +41 -1
  89. package/dist/core/schema/number-constraints.mjs +60 -1
  90. package/dist/core/schema/prompt.d.mts +6 -3
  91. package/dist/core/schema/run.d.mts +20 -1
  92. package/dist/core/schema/string-constraints.d.mts +97 -0
  93. package/dist/core/schema/string-constraints.mjs +69 -0
  94. package/dist/core/schema/value-parsers.d.mts +78 -0
  95. package/dist/core/schema/value-parsers.mjs +142 -0
  96. package/dist/core/schema-dsl/runtime.mjs +271 -2
  97. package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
  98. package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
  99. package/dist/core/testkit/index.d.mts +0 -31
  100. package/dist/core/testkit/index.mjs +83 -1
  101. package/dist/index.d.mts +11 -6
  102. package/dist/index.mjs +22 -1
  103. package/dist/runtime/adapter.d.mts +38 -2
  104. package/dist/runtime/adapter.mjs +87 -1
  105. package/dist/runtime/auto.d.mts +2 -3
  106. package/dist/runtime/auto.mjs +45 -1
  107. package/dist/runtime/deno.d.mts +24 -5
  108. package/dist/runtime/deno.mjs +262 -2
  109. package/dist/runtime/detect.mjs +45 -1
  110. package/dist/runtime/index.d.mts +3 -4
  111. package/dist/runtime/node.d.mts +8 -2
  112. package/dist/runtime/node.mjs +220 -2
  113. package/dist/runtime/paths.mjs +48 -1
  114. package/dist/runtime.d.mts +4 -4
  115. package/dist/runtime.mjs +6 -1
  116. package/dist/strings.mjs +22 -1
  117. package/dist/testkit.d.mts +1 -0
  118. package/dist/testkit.mjs +5 -1
  119. package/dist/version.d.mts +7 -3
  120. package/dist/version.mjs +7 -1
  121. package/dreamcli.schema.json +36 -7
  122. package/package.json +45 -42
  123. package/dist/runtime/bun.d.mts +0 -28
  124. package/dist/runtime/bun.mjs +0 -1
  125. package/src/core/cli/dispatch.ts +0 -355
  126. package/src/core/cli/help-links.ts +0 -82
  127. package/src/core/cli/index.ts +0 -1614
  128. package/src/core/cli/planner.ts +0 -656
  129. package/src/core/cli/plugin.ts +0 -117
  130. package/src/core/cli/propagate.ts +0 -97
  131. package/src/core/cli/root-help.ts +0 -342
  132. package/src/core/cli/root-surface.ts +0 -87
  133. package/src/core/cli/runtime-preflight.ts +0 -456
  134. package/src/core/completion/index.ts +0 -138
  135. package/src/core/completion/shells/bash.ts +0 -459
  136. package/src/core/completion/shells/fish.ts +0 -259
  137. package/src/core/completion/shells/powershell.ts +0 -439
  138. package/src/core/completion/shells/shared.ts +0 -310
  139. package/src/core/completion/shells/zsh.ts +0 -381
  140. package/src/core/config/index.ts +0 -417
  141. package/src/core/config/package-json.ts +0 -560
  142. package/src/core/errors/index.ts +0 -193
  143. package/src/core/execution/index.ts +0 -265
  144. package/src/core/help/ansi.ts +0 -144
  145. package/src/core/help/index.ts +0 -563
  146. package/src/core/json-schema/index.ts +0 -910
  147. package/src/core/json-schema/meta-descriptions.generated.ts +0 -202
  148. package/src/core/output/activity.ts +0 -575
  149. package/src/core/output/bind.ts +0 -59
  150. package/src/core/output/contracts.ts +0 -194
  151. package/src/core/output/display-value.ts +0 -48
  152. package/src/core/output/index.ts +0 -704
  153. package/src/core/output/renderers.ts +0 -125
  154. package/src/core/output/writer.ts +0 -46
  155. package/src/core/parse/index.ts +0 -742
  156. package/src/core/prompt/index.ts +0 -623
  157. package/src/core/resolve/args.ts +0 -144
  158. package/src/core/resolve/coerce.ts +0 -500
  159. package/src/core/resolve/config.ts +0 -26
  160. package/src/core/resolve/contracts.ts +0 -135
  161. package/src/core/resolve/errors.ts +0 -227
  162. package/src/core/resolve/flags.ts +0 -269
  163. package/src/core/resolve/index.ts +0 -108
  164. package/src/core/resolve/property.ts +0 -99
  165. package/src/core/schema/activity.ts +0 -240
  166. package/src/core/schema/arg.ts +0 -841
  167. package/src/core/schema/command.ts +0 -1500
  168. package/src/core/schema/flag.ts +0 -917
  169. package/src/core/schema/index.ts +0 -96
  170. package/src/core/schema/middleware.ts +0 -171
  171. package/src/core/schema/number-constraints.ts +0 -153
  172. package/src/core/schema/prompt.ts +0 -171
  173. package/src/core/schema/run.ts +0 -198
  174. package/src/core/schema-dsl/index.ts +0 -109
  175. package/src/core/schema-dsl/parse.ts +0 -262
  176. package/src/core/schema-dsl/runtime.ts +0 -609
  177. package/src/core/schema-dsl/to-json-schema.ts +0 -102
  178. package/src/core/testkit/index.ts +0 -147
  179. package/src/index.ts +0 -181
  180. package/src/runtime/adapter.ts +0 -303
  181. package/src/runtime/auto.ts +0 -86
  182. package/src/runtime/bun.ts +0 -48
  183. package/src/runtime/deno.ts +0 -367
  184. package/src/runtime/detect.ts +0 -105
  185. package/src/runtime/index.ts +0 -21
  186. package/src/runtime/node-builtins.d.ts +0 -27
  187. package/src/runtime/node.ts +0 -289
  188. package/src/runtime/paths.ts +0 -64
  189. package/src/runtime/support.ts +0 -77
  190. package/src/runtime.ts +0 -31
  191. package/src/schema.ts +0 -16
  192. package/src/strings.ts +0 -34
  193. package/src/testkit.ts +0 -25
  194. 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 };