@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,8 +1,11 @@
1
1
  import { ActivityEvent, Fallback, ProgressHandle, ProgressOptions, SpinnerHandle, SpinnerOptions, TableColumn, TableFormat, TableOptions, TableStream } from "./activity.mjs";
2
+ import { NumberConstraintViolation, NumberConstraints, describeNumberConstraintViolation, validateNumberConstraints } from "./number-constraints.mjs";
2
3
  import { ARG_KINDS, ARG_PRESENCES, ArgBuilder, ArgConfig, ArgFactory, ArgKind, ArgParseFn, ArgPresence, ArgSchema, InferArg, InferArgs, ResolvedArgValue, WithArgPresence, WithVariadic, arg, createArgSchema } from "./arg.mjs";
3
4
  import { ConfirmPromptConfig, InputPromptConfig, MultiselectPromptConfig, PROMPT_KINDS, PromptConfig, PromptConfigBase, PromptKind, PromptResult, SelectChoice, SelectPromptConfig } from "./prompt.mjs";
4
- import { FLAG_KINDS, FLAG_PRESENCES, FlagAlias, FlagBuilder, FlagConfig, FlagFactory, FlagKind, FlagParseFn, FlagPresence, FlagSchema, FlagSchemaOverrides, InferFlag, InferFlags, ResolvedValue, WithPresence, createSchema, flag } from "./flag.mjs";
5
+ import { StringConstraintViolation, StringConstraints, describeStringConstraintViolation, validateStringConstraints } from "./string-constraints.mjs";
6
+ import { DateFlagOptions, UrlFlagOptions } from "./value-parsers.mjs";
7
+ import { DuplicatePolicy, FLAG_KINDS, FLAG_PRESENCES, FlagAlias, FlagBuilder, FlagConfig, FlagFactory, FlagKind, FlagNegation, FlagParseFn, FlagPresence, FlagSchema, FlagSchemaOverrides, InferFlag, InferFlags, PathChecks, PathFlagOptions, ResolvedValue, WithPresence, createSchema, flag, getFlagNegatedName } from "./flag.mjs";
5
8
  import { ErasedMiddlewareHandler, Middleware, MiddlewareHandler, MiddlewareParams, middleware } from "./middleware.mjs";
6
9
  import { RunOptions, RunResult } from "./run.mjs";
7
10
  import { ActionHandler, ActionParams, AnyCommandBuilder, CommandArgEntry, CommandBuilder, CommandConfig, CommandExample, CommandMeta, CommandSchema, DeriveHandler, DeriveParams, ErasedCommand, ErasedDeriveHandler, ErasedInteractiveResolver, InteractiveParams, InteractiveResolver, InteractiveResult, Out, command, group } from "./command.mjs";
8
- export { ARG_KINDS, ARG_PRESENCES, type ActionHandler, type ActionParams, type ActivityEvent, type AnyCommandBuilder, ArgBuilder, type ArgConfig, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type CommandArgEntry, CommandBuilder, type CommandConfig, type CommandExample, type CommandMeta, type CommandSchema, type ConfirmPromptConfig, type DeriveHandler, type DeriveParams, type ErasedCommand, type ErasedDeriveHandler, type ErasedInteractiveResolver, type ErasedMiddlewareHandler, FLAG_KINDS, FLAG_PRESENCES, type Fallback, type FlagAlias, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagParseFn, type FlagPresence, type FlagSchema, type FlagSchemaOverrides, type InferArg, type InferArgs, type InferFlag, type InferFlags, type InputPromptConfig, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type Middleware, type MiddlewareHandler, type MiddlewareParams, type MultiselectPromptConfig, type Out, PROMPT_KINDS, type ProgressHandle, type ProgressOptions, type PromptConfig, type PromptConfigBase, type PromptKind, type PromptResult, type ResolvedArgValue, type ResolvedValue, type RunOptions, type RunResult, type SelectChoice, type SelectPromptConfig, type SpinnerHandle, type SpinnerOptions, type TableColumn, type TableFormat, type TableOptions, type TableStream, type WithArgPresence, type WithPresence, type WithVariadic, arg, command, createArgSchema, createSchema, flag, group, middleware };
11
+ export { ARG_KINDS, ARG_PRESENCES, type ActionHandler, type ActionParams, type ActivityEvent, type AnyCommandBuilder, ArgBuilder, type ArgConfig, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type CommandArgEntry, CommandBuilder, type CommandConfig, type CommandExample, type CommandMeta, type CommandSchema, type ConfirmPromptConfig, type DateFlagOptions, type DeriveHandler, type DeriveParams, type DuplicatePolicy, type ErasedCommand, type ErasedDeriveHandler, type ErasedInteractiveResolver, type ErasedMiddlewareHandler, FLAG_KINDS, FLAG_PRESENCES, type Fallback, type FlagAlias, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagNegation, type FlagParseFn, type FlagPresence, type FlagSchema, type FlagSchemaOverrides, type InferArg, type InferArgs, type InferFlag, type InferFlags, type InputPromptConfig, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type Middleware, type MiddlewareHandler, type MiddlewareParams, type MultiselectPromptConfig, type NumberConstraintViolation, type NumberConstraints, type Out, PROMPT_KINDS, type PathChecks, type PathFlagOptions, type ProgressHandle, type ProgressOptions, type PromptConfig, type PromptConfigBase, type PromptKind, type PromptResult, type ResolvedArgValue, type ResolvedValue, type RunOptions, type RunResult, type SelectChoice, type SelectPromptConfig, type SpinnerHandle, type SpinnerOptions, type StringConstraintViolation, type StringConstraints, type TableColumn, type TableFormat, type TableOptions, type TableStream, type UrlFlagOptions, type WithArgPresence, type WithPresence, type WithVariadic, arg, command, createArgSchema, createSchema, describeNumberConstraintViolation, describeStringConstraintViolation, flag, getFlagNegatedName, group, middleware, validateNumberConstraints, validateStringConstraints };
@@ -1,5 +1,4 @@
1
1
  import { CommandMeta, Out } from "./command.mjs";
2
-
3
2
  //#region src/core/schema/middleware.d.ts
4
3
  /**
5
4
  * Parameters received by a middleware function at runtime.
@@ -48,7 +47,8 @@ type MiddlewareHandler<Output extends Record<string, unknown>> = (params: {
48
47
  readonly flags: Readonly<Record<string, unknown>>;
49
48
  readonly ctx: Readonly<Record<string, unknown>>;
50
49
  readonly out: Out;
51
- readonly meta: CommandMeta; /** Pass context additions downstream. Must include all `Output` properties. */
50
+ readonly meta: CommandMeta;
51
+ /** Pass context additions downstream. Must include all `Output` properties. */
52
52
  readonly next: (additions: Output) => Promise<void>;
53
53
  }) => void | Promise<void>;
54
54
  /**
@@ -80,7 +80,8 @@ interface MiddlewareImpl {
80
80
  * ```
81
81
  */
82
82
  type Middleware<Output extends Record<string, unknown>> = MiddlewareImpl & {
83
- /** @internal Phantom type brand — compile-time only. */readonly _output: Output;
83
+ /** @internal Phantom type brand — compile-time only. */
84
+ readonly _output: Output;
84
85
  };
85
86
  /**
86
87
  * Create a middleware definition.
@@ -1 +1,41 @@
1
- function e(e){return{_handler:e}}export{e as middleware};
1
+ //#region src/core/schema/middleware.ts
2
+ /**
3
+ * Create a middleware definition.
4
+ *
5
+ * Middleware runs before the action handler and can add typed context,
6
+ * short-circuit execution, or wrap downstream processing.
7
+ *
8
+ * @param handler - Function receiving `{ args, flags, ctx, out, meta, next }`.
9
+ * Call `next(additions)` to continue the chain with added context.
10
+ * Omitting the `next()` call short-circuits (e.g., for auth guards).
11
+ * @returns {@linkcode Middleware} to attach via `CommandBuilder.middleware()`.
12
+ *
13
+ * @example
14
+ * ```ts
15
+ * // Auth guard — adds user to context or throws
16
+ * const auth = middleware(async ({ next }) => {
17
+ * const user = await getUser();
18
+ * if (!user) throw new CLIError('Not authenticated', { code: 'AUTH_REQUIRED' });
19
+ * return next({ user });
20
+ * });
21
+ *
22
+ * // Timing wrapper — measures downstream execution
23
+ * const timing = middleware(async ({ out, next }) => {
24
+ * const start = Date.now();
25
+ * await next({});
26
+ * out.info(`Done in ${Date.now() - start}ms`);
27
+ * });
28
+ *
29
+ * command('deploy')
30
+ * .middleware(timing)
31
+ * .middleware(auth)
32
+ * .action(({ ctx }) => {
33
+ * console.log(ctx.user.name); // typed!
34
+ * });
35
+ * ```
36
+ */
37
+ function middleware(handler) {
38
+ return { _handler: handler };
39
+ }
40
+ //#endregion
41
+ export { middleware };
@@ -0,0 +1,96 @@
1
+ //#region src/core/schema/number-constraints.d.ts
2
+ /**
3
+ * Numeric constraints for number-valued flags and args.
4
+ *
5
+ * A single, shared representation and validator so the parse path
6
+ * (`core/parse`) and the resolver coercion path (`core/resolve/coerce`) cannot
7
+ * drift: both import {@link validateNumberConstraints} and apply the checks in
8
+ * the same order (finite → int → min → max).
9
+ *
10
+ * @module dreamcli/core/schema/number-constraints
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
+ * A failed numeric constraint, discriminated by which rule was violated.
44
+ *
45
+ * `min` / `max` carry the offending bound so callers can render it.
46
+ */
47
+ type NumberConstraintViolation = {
48
+ readonly kind: 'finite';
49
+ } | {
50
+ readonly kind: 'int';
51
+ } | {
52
+ readonly kind: 'min';
53
+ readonly bound: number;
54
+ } | {
55
+ readonly kind: 'max';
56
+ readonly bound: number;
57
+ };
58
+ /** Default for {@link NumberConstraints.finite} — reject `Infinity` unless opted out. */
59
+ declare const DEFAULT_FINITE = true;
60
+ /**
61
+ * Validate a numeric value against constraints.
62
+ *
63
+ * The single source of truth for numeric-constraint checks, shared by the
64
+ * parse and coerce paths. Checks run in a fixed order — **finite → int → min →
65
+ * max** — and the first failure is returned. `NaN` is always rejected as a
66
+ * `finite` violation, regardless of the `finite` option (a non-finite value can
67
+ * otherwise slip past `min`/`max`, since `NaN < x` and `NaN > x` are both false).
68
+ *
69
+ * @param value - The numeric value to validate.
70
+ * @param constraints - Constraints to enforce, or `undefined` for defaults.
71
+ * @returns The first {@link NumberConstraintViolation}, or `undefined` if valid.
72
+ */
73
+ declare function validateNumberConstraints(value: number, constraints: NumberConstraints | undefined): NumberConstraintViolation | undefined;
74
+ /**
75
+ * Render a terse, human-readable reason for a constraint violation.
76
+ *
77
+ * @param violation - The violation to describe.
78
+ * @returns A message suffix such as `must be an integer` or `must be >= 0`.
79
+ */
80
+ declare function describeNumberConstraintViolation(violation: NumberConstraintViolation): string;
81
+ /**
82
+ * Assert that a constraints object is well-formed at schema-construction time.
83
+ *
84
+ * `min` / `max` must be finite — an infinite or `NaN` bound is meaningless (omit
85
+ * the field for "no bound") and would serialize to `null` in the emitted JSON
86
+ * Schema. An inverted range (`min > max`) is also rejected, since it makes the
87
+ * flag/arg permanently unsatisfiable. Throws so the misconfiguration surfaces
88
+ * where the flag/arg is declared, not at parse time.
89
+ *
90
+ * @param constraints - The constraints to validate.
91
+ * @throws RangeError if `min` or `max` is non-finite (`Infinity` / `-Infinity` /
92
+ * `NaN`), or if `min` exceeds `max`.
93
+ */
94
+ declare function assertNumberConstraints(constraints: NumberConstraints): void;
95
+ //#endregion
96
+ export { DEFAULT_FINITE, type NumberConstraintViolation, type NumberConstraints, assertNumberConstraints, describeNumberConstraintViolation, validateNumberConstraints };
@@ -0,0 +1,60 @@
1
+ /**
2
+ * Validate a numeric value against constraints.
3
+ *
4
+ * The single source of truth for numeric-constraint checks, shared by the
5
+ * parse and coerce paths. Checks run in a fixed order — **finite → int → min →
6
+ * max** — and the first failure is returned. `NaN` is always rejected as a
7
+ * `finite` violation, regardless of the `finite` option (a non-finite value can
8
+ * otherwise slip past `min`/`max`, since `NaN < x` and `NaN > x` are both false).
9
+ *
10
+ * @param value - The numeric value to validate.
11
+ * @param constraints - Constraints to enforce, or `undefined` for defaults.
12
+ * @returns The first {@link NumberConstraintViolation}, or `undefined` if valid.
13
+ */
14
+ function validateNumberConstraints(value, constraints) {
15
+ if (Number.isNaN(value)) return { kind: "finite" };
16
+ if ((constraints?.finite ?? true) && !Number.isFinite(value)) return { kind: "finite" };
17
+ if (constraints?.int === true && !Number.isInteger(value)) return { kind: "int" };
18
+ if (constraints?.min !== void 0 && value < constraints.min) return {
19
+ kind: "min",
20
+ bound: constraints.min
21
+ };
22
+ if (constraints?.max !== void 0 && value > constraints.max) return {
23
+ kind: "max",
24
+ bound: constraints.max
25
+ };
26
+ }
27
+ /**
28
+ * Render a terse, human-readable reason for a constraint violation.
29
+ *
30
+ * @param violation - The violation to describe.
31
+ * @returns A message suffix such as `must be an integer` or `must be >= 0`.
32
+ */
33
+ function describeNumberConstraintViolation(violation) {
34
+ switch (violation.kind) {
35
+ case "finite": return "must be a finite number";
36
+ case "int": return "must be an integer";
37
+ case "min": return `must be >= ${violation.bound}`;
38
+ case "max": return `must be <= ${violation.bound}`;
39
+ }
40
+ }
41
+ /**
42
+ * Assert that a constraints object is well-formed at schema-construction time.
43
+ *
44
+ * `min` / `max` must be finite — an infinite or `NaN` bound is meaningless (omit
45
+ * the field for "no bound") and would serialize to `null` in the emitted JSON
46
+ * Schema. An inverted range (`min > max`) is also rejected, since it makes the
47
+ * flag/arg permanently unsatisfiable. Throws so the misconfiguration surfaces
48
+ * where the flag/arg is declared, not at parse time.
49
+ *
50
+ * @param constraints - The constraints to validate.
51
+ * @throws RangeError if `min` or `max` is non-finite (`Infinity` / `-Infinity` /
52
+ * `NaN`), or if `min` exceeds `max`.
53
+ */
54
+ function assertNumberConstraints(constraints) {
55
+ if (constraints.min !== void 0 && !Number.isFinite(constraints.min)) throw new RangeError(`number constraint 'min' must be a finite number (got ${constraints.min}); omit it for no lower bound`);
56
+ if (constraints.max !== void 0 && !Number.isFinite(constraints.max)) throw new RangeError(`number constraint 'max' must be a finite number (got ${constraints.max}); omit it for no upper bound`);
57
+ if (constraints.min !== void 0 && constraints.max !== void 0 && constraints.min > constraints.max) throw new RangeError(`number constraint 'min' (${constraints.min}) must not exceed 'max' (${constraints.max})`);
58
+ }
59
+ //#endregion
60
+ export { assertNumberConstraints, describeNumberConstraintViolation, validateNumberConstraints };
@@ -10,7 +10,7 @@
10
10
  * @module dreamcli/core/schema/prompt
11
11
  */
12
12
  /** All prompt kind discriminators as a runtime array. */
13
- declare const PROMPT_KINDS: readonly ['confirm', 'input', 'select', 'multiselect'];
13
+ declare const PROMPT_KINDS: readonly ["confirm", "input", "select", "multiselect"];
14
14
  /**
15
15
  * The kind of interactive prompt to present.
16
16
  *
@@ -29,6 +29,12 @@ interface PromptConfigBase {
29
29
  interface ConfirmPromptConfig extends PromptConfigBase {
30
30
  /** Discriminator identifying this as a yes/no confirmation prompt. */
31
31
  readonly kind: 'confirm';
32
+ /**
33
+ * Value used when the user submits an empty line (presses Enter). Also
34
+ * drives the displayed hint: `true` → `(Y/n)`, `false` → `(y/N)`.
35
+ * @defaultValue `true`
36
+ */
37
+ readonly default?: boolean;
32
38
  }
33
39
  /** Free-text input prompt — maps to `string` and `number` flags. Part of {@link PromptConfig}. */
34
40
  interface InputPromptConfig extends PromptConfigBase {
@@ -36,6 +42,15 @@ interface InputPromptConfig extends PromptConfigBase {
36
42
  readonly kind: 'input';
37
43
  /** Placeholder text shown before user types (informational only). */
38
44
  readonly placeholder?: string;
45
+ /**
46
+ * Value used when the user submits an empty line (presses Enter), shown in
47
+ * the hint as `(default: <value>)`. When set, an empty submission resolves
48
+ * to this value without running {@link InputPromptConfig.validate | validate}.
49
+ * When omitted, an empty submission is treated as "no answer" so resolution
50
+ * falls through to the flag's `.default()`.
51
+ * @defaultValue `undefined`
52
+ */
53
+ readonly default?: string;
39
54
  /**
40
55
  * Inline validation function. Return `true` if valid, or a string
41
56
  * error message if invalid. Called before coercion to flag kind.
@@ -108,10 +123,13 @@ type PromptConfig = ConfirmPromptConfig | InputPromptConfig | SelectPromptConfig
108
123
  * prompt engine's.
109
124
  */
110
125
  type PromptResult = {
111
- /** User provided a value. */readonly answered: true; /** The raw value from the prompt engine (not yet coerced). */
126
+ /** User provided a value. */
127
+ readonly answered: true;
128
+ /** The raw value from the prompt engine (not yet coerced). */
112
129
  readonly value: unknown;
113
130
  } | {
114
- /** User cancelled or aborted (Ctrl+C, ESC, etc.). */readonly answered: false;
131
+ /** User cancelled or aborted (Ctrl+C, ESC, etc.). */
132
+ readonly answered: false;
115
133
  };
116
134
  //#endregion
117
135
  export { type ConfirmPromptConfig, type InputPromptConfig, type MultiselectPromptConfig, PROMPT_KINDS, type PromptConfig, type PromptConfigBase, type PromptKind, type PromptResult, type SelectChoice, type SelectPromptConfig };
@@ -6,7 +6,7 @@ import { CLIPlugin } from "../cli/plugin.mjs";
6
6
  import { CLIError } from "../errors/index.mjs";
7
7
  import { HelpOptions } from "../help/index.mjs";
8
8
  import { CommandMeta, CommandSchema, Out } from "./command.mjs";
9
-
9
+ import { ParseOptions } from "../parse/index.mjs";
10
10
  //#region src/core/schema/run.d.ts
11
11
  /**
12
12
  * Options accepted by `runCommand()` and internal command execution paths.
@@ -59,6 +59,15 @@ interface RunOptions {
59
59
  * Ignored when an explicit `prompter` is provided.
60
60
  */
61
61
  readonly answers?: readonly TestAnswer[];
62
+ /**
63
+ * Filesystem probe for `flag.path()` checks: reports what exists at a
64
+ * path (`'file'`, `'directory'`, or `null` for nothing).
65
+ *
66
+ * `CLIBuilder.run()` supplies the runtime adapter's probe automatically.
67
+ * When absent (process-free `.execute()` / `runCommand()` without an
68
+ * override), path checks are skipped.
69
+ */
70
+ readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
62
71
  /**
63
72
  * Verbosity level for the output channel.
64
73
  * @defaultValue `'normal'`
@@ -103,6 +112,16 @@ interface RunOptions {
103
112
  * Used when `--help` is detected.
104
113
  */
105
114
  readonly help?: HelpOptions;
115
+ /**
116
+ * Flag-parsing behavior settings.
117
+ *
118
+ * `caseParity` accepts the kebab↔camel counterpart spelling of each flag
119
+ * name/alias (`--doThis` for `do-this`, and vice versa). The CLI layer
120
+ * threads `cli(name, { flags })` settings here automatically.
121
+ *
122
+ * @defaultValue `{ caseParity: true }`
123
+ */
124
+ readonly flags?: ParseOptions;
106
125
  /**
107
126
  * Command schema with propagated flags merged in.
108
127
  *
@@ -133,10 +152,10 @@ interface RunOptions {
133
152
  /**
134
153
  * Structured result from {@linkcode runCommand}.
135
154
  *
136
- * Contains the exit code, captured stdout/stderr output, recorded
137
- * {@linkcode ActivityEvent | activity events}, and an `error` field.
138
- * `error` is `undefined` when execution completed without throwing, even if
139
- * the handler requested a non-zero status via {@linkcode Out.setExitCode}.
155
+ * Contains the exit code, captured stdout/stderr output, recorded
156
+ * {@linkcode ActivityEvent | activity events}, and an `error` field.
157
+ * `error` is `undefined` when execution completed without throwing, even if
158
+ * the handler requested a non-zero status via {@linkcode Out.setExitCode}.
140
159
  *
141
160
  * @example
142
161
  * ```ts
@@ -0,0 +1,97 @@
1
+ //#region src/core/schema/string-constraints.d.ts
2
+ /**
3
+ * String constraints for string-valued flags.
4
+ *
5
+ * A single, shared representation and validator so the parse path
6
+ * (`core/parse`) and the resolver coercion path (`core/resolve/coerce`) cannot
7
+ * drift: both import {@link validateStringConstraints} and apply the checks in
8
+ * the same order (nonEmpty → minLength → maxLength → pattern).
9
+ *
10
+ * @module dreamcli/core/schema/string-constraints
11
+ */
12
+ /**
13
+ * Runtime string constraints attached to a string flag/arg schema.
14
+ *
15
+ * Length bounds are **inclusive** and measured in UTF-16 code units
16
+ * (`String.prototype.length`). All fields are optional; an absent field means
17
+ * "no constraint".
18
+ */
19
+ interface StringConstraints {
20
+ /**
21
+ * Reject empty strings (`''`). Whitespace-only strings are still accepted;
22
+ * combine with {@link StringConstraints.pattern | pattern} for stricter rules.
23
+ * @defaultValue `false`
24
+ */
25
+ readonly nonEmpty?: boolean;
26
+ /**
27
+ * Inclusive minimum length. Shorter values are rejected.
28
+ * @defaultValue `undefined` (no minimum)
29
+ */
30
+ readonly minLength?: number;
31
+ /**
32
+ * Inclusive maximum length. Longer values are rejected.
33
+ * @defaultValue `undefined` (no maximum)
34
+ */
35
+ readonly maxLength?: number;
36
+ /**
37
+ * Regular expression the value must match. Tested with
38
+ * `RegExp.prototype.test`; anchor with `^`/`$` for full-string matching.
39
+ * @defaultValue `undefined` (no pattern)
40
+ */
41
+ readonly pattern?: RegExp;
42
+ }
43
+ /**
44
+ * A failed string constraint, discriminated by which rule was violated.
45
+ *
46
+ * `minLength` / `maxLength` carry the offending bound and `pattern` carries
47
+ * the source so callers can render them.
48
+ */
49
+ type StringConstraintViolation = {
50
+ readonly kind: 'nonEmpty';
51
+ } | {
52
+ readonly kind: 'minLength';
53
+ readonly bound: number;
54
+ } | {
55
+ readonly kind: 'maxLength';
56
+ readonly bound: number;
57
+ } | {
58
+ readonly kind: 'pattern';
59
+ readonly pattern: string;
60
+ };
61
+ /**
62
+ * Validate a string value against constraints.
63
+ *
64
+ * The single source of truth for string-constraint checks, shared by the
65
+ * parse and coerce paths. Checks run in a fixed order — **nonEmpty →
66
+ * minLength → maxLength → pattern** — and the first failure is returned.
67
+ * Stateful regexes (`g` / `y` flags) are tested from index 0 every time, so
68
+ * repeated validations cannot flip-flop on `lastIndex`.
69
+ *
70
+ * @param value - The string value to validate.
71
+ * @param constraints - Constraints to enforce, or `undefined` for none.
72
+ * @returns The first {@link StringConstraintViolation}, or `undefined` if valid.
73
+ */
74
+ declare function validateStringConstraints(value: string, constraints: StringConstraints | undefined): StringConstraintViolation | undefined;
75
+ /**
76
+ * Render a terse, human-readable reason for a constraint violation.
77
+ *
78
+ * @param violation - The violation to describe.
79
+ * @returns A message suffix such as `must not be empty` or `must match /^ghp_/`.
80
+ */
81
+ declare function describeStringConstraintViolation(violation: StringConstraintViolation): string;
82
+ /**
83
+ * Assert that a constraints object is well-formed at schema-construction time.
84
+ *
85
+ * Length bounds must be non-negative integers — a fractional or negative
86
+ * length is meaningless (omit the field for "no bound"). An inverted range
87
+ * (`minLength > maxLength`) is also rejected, since it makes the flag/arg
88
+ * permanently unsatisfiable. Throws so the misconfiguration surfaces where
89
+ * the flag/arg is declared, not at parse time.
90
+ *
91
+ * @param constraints - The constraints to validate.
92
+ * @throws RangeError if `minLength` or `maxLength` is negative, fractional, or
93
+ * non-finite, or if `minLength` exceeds `maxLength`.
94
+ */
95
+ declare function assertStringConstraints(constraints: StringConstraints): void;
96
+ //#endregion
97
+ export { type StringConstraintViolation, type StringConstraints, assertStringConstraints, describeStringConstraintViolation, validateStringConstraints };
@@ -0,0 +1,69 @@
1
+ //#region src/core/schema/string-constraints.ts
2
+ /**
3
+ * Validate a string value against constraints.
4
+ *
5
+ * The single source of truth for string-constraint checks, shared by the
6
+ * parse and coerce paths. Checks run in a fixed order — **nonEmpty →
7
+ * minLength → maxLength → pattern** — and the first failure is returned.
8
+ * Stateful regexes (`g` / `y` flags) are tested from index 0 every time, so
9
+ * repeated validations cannot flip-flop on `lastIndex`.
10
+ *
11
+ * @param value - The string value to validate.
12
+ * @param constraints - Constraints to enforce, or `undefined` for none.
13
+ * @returns The first {@link StringConstraintViolation}, or `undefined` if valid.
14
+ */
15
+ function validateStringConstraints(value, constraints) {
16
+ if (constraints === void 0) return;
17
+ if (constraints.nonEmpty === true && value.length === 0) return { kind: "nonEmpty" };
18
+ if (constraints.minLength !== void 0 && value.length < constraints.minLength) return {
19
+ kind: "minLength",
20
+ bound: constraints.minLength
21
+ };
22
+ if (constraints.maxLength !== void 0 && value.length > constraints.maxLength) return {
23
+ kind: "maxLength",
24
+ bound: constraints.maxLength
25
+ };
26
+ if (constraints.pattern !== void 0) {
27
+ constraints.pattern.lastIndex = 0;
28
+ if (!constraints.pattern.test(value)) return {
29
+ kind: "pattern",
30
+ pattern: String(constraints.pattern)
31
+ };
32
+ }
33
+ }
34
+ /**
35
+ * Render a terse, human-readable reason for a constraint violation.
36
+ *
37
+ * @param violation - The violation to describe.
38
+ * @returns A message suffix such as `must not be empty` or `must match /^ghp_/`.
39
+ */
40
+ function describeStringConstraintViolation(violation) {
41
+ switch (violation.kind) {
42
+ case "nonEmpty": return "must not be empty";
43
+ case "minLength": return `must be at least ${violation.bound} characters`;
44
+ case "maxLength": return `must be at most ${violation.bound} characters`;
45
+ case "pattern": return `must match ${violation.pattern}`;
46
+ }
47
+ }
48
+ /**
49
+ * Assert that a constraints object is well-formed at schema-construction time.
50
+ *
51
+ * Length bounds must be non-negative integers — a fractional or negative
52
+ * length is meaningless (omit the field for "no bound"). An inverted range
53
+ * (`minLength > maxLength`) is also rejected, since it makes the flag/arg
54
+ * permanently unsatisfiable. Throws so the misconfiguration surfaces where
55
+ * the flag/arg is declared, not at parse time.
56
+ *
57
+ * @param constraints - The constraints to validate.
58
+ * @throws RangeError if `minLength` or `maxLength` is negative, fractional, or
59
+ * non-finite, or if `minLength` exceeds `maxLength`.
60
+ */
61
+ function assertStringConstraints(constraints) {
62
+ for (const field of ["minLength", "maxLength"]) {
63
+ const bound = constraints[field];
64
+ if (bound !== void 0 && (!Number.isInteger(bound) || bound < 0)) throw new RangeError(`string constraint '${field}' must be a non-negative integer (got ${bound}); omit it for no bound`);
65
+ }
66
+ if (constraints.minLength !== void 0 && constraints.maxLength !== void 0 && constraints.minLength > constraints.maxLength) throw new RangeError(`string constraint 'minLength' (${constraints.minLength}) must not exceed 'maxLength' (${constraints.maxLength})`);
67
+ }
68
+ //#endregion
69
+ export { assertStringConstraints, describeStringConstraintViolation, validateStringConstraints };
@@ -0,0 +1,78 @@
1
+ //#region src/core/schema/value-parsers.d.ts
2
+ /**
3
+ * Parse functions backing the sugar flag factories (`flag.url()`,
4
+ * `flag.date()`, `flag.duration()`, `flag.bytes()`).
5
+ *
6
+ * Each parser converts a raw CLI/env/config value into a typed value and
7
+ * throws a plain `Error` with a human-readable reason on invalid input. The
8
+ * parse and resolve pipelines wrap thrown errors with flag context
9
+ * (`Failed to parse flag --x: <reason>`), so parsers only describe the value
10
+ * problem itself.
11
+ *
12
+ * @module dreamcli/core/schema/value-parsers
13
+ */
14
+ /** Options accepted by `flag.url()`. */
15
+ interface UrlFlagOptions {
16
+ /**
17
+ * Allowed URL protocols, without the trailing colon (e.g. `['https']`).
18
+ * @defaultValue `undefined` (any protocol)
19
+ */
20
+ readonly protocols?: readonly string[];
21
+ }
22
+ /** Options accepted by `flag.date()`. */
23
+ interface DateFlagOptions {
24
+ /**
25
+ * Inclusive earliest allowed date.
26
+ * @defaultValue `undefined` (no lower bound)
27
+ */
28
+ readonly min?: Date;
29
+ /**
30
+ * Inclusive latest allowed date.
31
+ * @defaultValue `undefined` (no upper bound)
32
+ */
33
+ readonly max?: Date;
34
+ }
35
+ /**
36
+ * Parse a strict ISO-8601 date string into a `Date`.
37
+ *
38
+ * Rejects non-string input, non-ISO shapes, and calendar-invalid components
39
+ * (`2026-02-31` does not silently roll over to March). Offset-less datetimes
40
+ * are interpreted as UTC so results never depend on the machine's timezone.
41
+ *
42
+ * @param raw - Raw flag value.
43
+ * @param options - Optional inclusive date bounds.
44
+ * @returns The parsed `Date`.
45
+ * @throws Error with a human-readable reason on invalid input.
46
+ */
47
+ declare function parseDateValue(raw: unknown, options?: DateFlagOptions): Date;
48
+ /**
49
+ * Parse a URL string into a `URL`, optionally restricting protocols.
50
+ *
51
+ * @param raw - Raw flag value.
52
+ * @param options - Optional protocol allowlist.
53
+ * @returns The parsed `URL`.
54
+ * @throws Error with a human-readable reason on invalid input.
55
+ */
56
+ declare function parseUrlValue(raw: unknown, options?: UrlFlagOptions): URL;
57
+ /**
58
+ * Parse a human duration (`'30s'`, `'5m'`, `'1.5h'`, `'250ms'`, `'2d'`) into
59
+ * milliseconds. A bare number (`'1500'`) is treated as milliseconds. Compound
60
+ * values (`'1h30m'`) are supported.
61
+ *
62
+ * @param raw - Raw flag value.
63
+ * @returns Duration in milliseconds.
64
+ * @throws Error with a human-readable reason on invalid input.
65
+ */
66
+ declare function parseDurationValue(raw: unknown): number;
67
+ /**
68
+ * Parse a human byte size (`'512mb'`, `'1.5gb'`, `'64kb'`, `'100b'`) into a
69
+ * byte count. Units are binary (`1kb` = 1024 bytes) and case-insensitive; a
70
+ * bare number is treated as bytes.
71
+ *
72
+ * @param raw - Raw flag value.
73
+ * @returns Size in bytes.
74
+ * @throws Error with a human-readable reason on invalid input.
75
+ */
76
+ declare function parseBytesValue(raw: unknown): number;
77
+ //#endregion
78
+ export { type DateFlagOptions, type UrlFlagOptions, parseBytesValue, parseDateValue, parseDurationValue, parseUrlValue };