@kjanat/dreamcli 3.0.0-rc.1 → 3.0.0-rc.2
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.
- package/CHANGELOG.md +26 -1
- package/dist/core/cli/dispatch.mjs +214 -1
- package/dist/core/cli/help-links.mjs +41 -1
- package/dist/core/cli/index.mjs +901 -1
- package/dist/core/cli/planner.mjs +300 -1
- package/dist/core/cli/plugin.mjs +41 -1
- package/dist/core/cli/propagate.mjs +57 -1
- package/dist/core/cli/root-help.mjs +208 -4
- package/dist/core/cli/root-surface.mjs +27 -1
- package/dist/core/cli/runtime-preflight.mjs +168 -1
- package/dist/core/completion/index.mjs +90 -1
- package/dist/core/completion/shells/bash.mjs +304 -3
- package/dist/core/completion/shells/fish.mjs +159 -2
- package/dist/core/completion/shells/powershell.mjs +353 -2
- package/dist/core/completion/shells/shared.mjs +154 -1
- package/dist/core/completion/shells/zsh.mjs +244 -2
- package/dist/core/config/index.mjs +246 -1
- package/dist/core/config/package-json.mjs +385 -3
- package/dist/core/errors/index.mjs +87 -1
- package/dist/core/execution/index.mjs +189 -1
- package/dist/core/help/ansi.mjs +122 -2
- package/dist/core/help/index.mjs +329 -7
- package/dist/core/json-schema/index.mjs +487 -9
- package/dist/core/json-schema/meta-descriptions.generated.mjs +93 -28
- package/dist/core/output/activity.mjs +452 -1
- package/dist/core/output/bind.mjs +56 -1
- package/dist/core/output/contracts.mjs +57 -1
- package/dist/core/output/display-value.mjs +32 -1
- package/dist/core/output/index.d.mts +21 -0
- package/dist/core/output/index.mjs +442 -2
- package/dist/core/output/renderers.mjs +46 -1
- package/dist/core/output/writer.mjs +12 -1
- package/dist/core/parse/index.mjs +555 -1
- package/dist/core/prompt/index.d.mts +0 -1
- package/dist/core/prompt/index.mjs +348 -6
- package/dist/core/resolve/args.mjs +105 -1
- package/dist/core/resolve/coerce.mjs +279 -1
- package/dist/core/resolve/config.mjs +19 -1
- package/dist/core/resolve/errors.mjs +140 -2
- package/dist/core/resolve/flags.mjs +196 -1
- package/dist/core/resolve/index.mjs +85 -1
- package/dist/core/resolve/property.d.mts +0 -1
- package/dist/core/resolve/property.mjs +45 -1
- package/dist/core/schema/arg.mjs +463 -1
- package/dist/core/schema/command.d.mts +18 -0
- package/dist/core/schema/command.mjs +712 -1
- package/dist/core/schema/flag.mjs +453 -1
- package/dist/core/schema/middleware.mjs +41 -1
- package/dist/core/schema/number-constraints.mjs +60 -1
- package/dist/core/schema-dsl/runtime.mjs +271 -2
- package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
- package/dist/core/testkit/index.mjs +83 -1
- package/dist/index.d.mts +2 -1
- package/dist/index.mjs +22 -1
- package/dist/runtime/adapter.mjs +82 -1
- package/dist/runtime/auto.mjs +46 -1
- package/dist/runtime/bun.mjs +28 -1
- package/dist/runtime/deno.mjs +217 -2
- package/dist/runtime/detect.mjs +45 -1
- package/dist/runtime/node.mjs +169 -2
- package/dist/runtime/paths.mjs +48 -1
- package/dist/runtime.mjs +7 -1
- package/dist/strings.mjs +22 -1
- package/dist/testkit.mjs +5 -1
- package/dist/version.mjs +7 -1
- package/package.json +17 -26
- package/src/core/cli/dispatch.ts +0 -355
- package/src/core/cli/help-links.ts +0 -82
- package/src/core/cli/index.ts +0 -1614
- package/src/core/cli/planner.ts +0 -656
- package/src/core/cli/plugin.ts +0 -117
- package/src/core/cli/propagate.ts +0 -97
- package/src/core/cli/root-help.ts +0 -342
- package/src/core/cli/root-surface.ts +0 -87
- package/src/core/cli/runtime-preflight.ts +0 -456
- package/src/core/completion/index.ts +0 -138
- package/src/core/completion/shells/bash.ts +0 -459
- package/src/core/completion/shells/fish.ts +0 -259
- package/src/core/completion/shells/powershell.ts +0 -439
- package/src/core/completion/shells/shared.ts +0 -310
- package/src/core/completion/shells/zsh.ts +0 -381
- package/src/core/config/index.ts +0 -417
- package/src/core/config/package-json.ts +0 -560
- package/src/core/errors/index.ts +0 -193
- package/src/core/execution/index.ts +0 -265
- package/src/core/help/ansi.ts +0 -144
- package/src/core/help/index.ts +0 -563
- package/src/core/json-schema/index.ts +0 -910
- package/src/core/json-schema/meta-descriptions.generated.ts +0 -202
- package/src/core/output/activity.ts +0 -575
- package/src/core/output/bind.ts +0 -59
- package/src/core/output/contracts.ts +0 -194
- package/src/core/output/display-value.ts +0 -48
- package/src/core/output/index.ts +0 -704
- package/src/core/output/renderers.ts +0 -125
- package/src/core/output/writer.ts +0 -46
- package/src/core/parse/index.ts +0 -742
- package/src/core/prompt/index.ts +0 -623
- package/src/core/resolve/args.ts +0 -144
- package/src/core/resolve/coerce.ts +0 -500
- package/src/core/resolve/config.ts +0 -26
- package/src/core/resolve/contracts.ts +0 -135
- package/src/core/resolve/errors.ts +0 -227
- package/src/core/resolve/flags.ts +0 -269
- package/src/core/resolve/index.ts +0 -108
- package/src/core/resolve/property.ts +0 -99
- package/src/core/schema/activity.ts +0 -240
- package/src/core/schema/arg.ts +0 -841
- package/src/core/schema/command.ts +0 -1500
- package/src/core/schema/flag.ts +0 -917
- package/src/core/schema/index.ts +0 -96
- package/src/core/schema/middleware.ts +0 -171
- package/src/core/schema/number-constraints.ts +0 -153
- package/src/core/schema/prompt.ts +0 -171
- package/src/core/schema/run.ts +0 -198
- package/src/core/schema-dsl/index.ts +0 -109
- package/src/core/schema-dsl/parse.ts +0 -262
- package/src/core/schema-dsl/runtime.ts +0 -609
- package/src/core/schema-dsl/to-json-schema.ts +0 -102
- package/src/core/testkit/index.ts +0 -147
- package/src/index.ts +0 -181
- package/src/runtime/adapter.ts +0 -303
- package/src/runtime/auto.ts +0 -86
- package/src/runtime/bun.ts +0 -48
- package/src/runtime/deno.ts +0 -367
- package/src/runtime/detect.ts +0 -105
- package/src/runtime/index.ts +0 -21
- package/src/runtime/node-builtins.d.ts +0 -27
- package/src/runtime/node.ts +0 -289
- package/src/runtime/paths.ts +0 -64
- package/src/runtime/support.ts +0 -77
- package/src/runtime.ts +0 -31
- package/src/schema.ts +0 -16
- package/src/strings.ts +0 -34
- package/src/testkit.ts +0 -25
- package/src/version.ts +0 -20
package/src/core/schema/index.ts
DELETED
|
@@ -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 };
|