@kjanat/dreamcli 4.0.0-rc.3 → 4.1.0

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 (212) hide show
  1. package/README.md +5 -7
  2. package/dist/{runtime/adapter.d.mts → adapter-YM5QGi3M.d.mts} +4 -4
  3. package/dist/completion-CUMeOnAz.mjs +6 -0
  4. package/dist/completion.d.mts +90 -0
  5. package/dist/completion.mjs +1 -0
  6. package/dist/config-CrlScpYX.mjs +1 -0
  7. package/dist/config.d.mts +2 -0
  8. package/dist/config.mjs +1 -0
  9. package/dist/core-DvXUolc_.mjs +17 -0
  10. package/dist/{core/json-schema/index.d.mts → index-3l8uj16E.d.mts} +43 -34
  11. package/dist/{core/cli/index.d.mts → index-BAj2y70U.d.mts} +116 -57
  12. package/dist/index-BziI2aKc.d.mts +5440 -0
  13. package/dist/index-Cap0MA2V.d.mts +277 -0
  14. package/dist/index-Cp9kt2t-.d.mts +370 -0
  15. package/dist/index-DWsnGZlx.d.mts +831 -0
  16. package/dist/index.d.mts +190 -41
  17. package/dist/index.mjs +1 -26
  18. package/dist/json-schema-DRlrz_IV.mjs +52 -0
  19. package/dist/json-schema.d.mts +2 -0
  20. package/dist/json-schema.mjs +1 -0
  21. package/dist/package-json-BgE9YjjQ.mjs +3 -0
  22. package/dist/prompt.d.mts +48 -0
  23. package/dist/prompt.mjs +1 -0
  24. package/dist/rolldown-runtime-G4Kt5YOX.mjs +1 -0
  25. package/dist/runtime.d.mts +2 -6
  26. package/dist/runtime.mjs +1 -6
  27. package/dist/terminal-C8KTXjv5.mjs +6 -0
  28. package/dist/test-prompter-v__jT2yG.mjs +1 -0
  29. package/dist/testkit.d.mts +54 -6
  30. package/dist/testkit.mjs +1 -5
  31. package/dist/version.mjs +1 -7
  32. package/dreamcli.schema.json +697 -538
  33. package/package.json +29 -7
  34. package/skills/cli-creation/SKILL.md +16 -11
  35. package/CHANGELOG.md +0 -1116
  36. package/dist/core/cli/builtins.d.mts +0 -117
  37. package/dist/core/cli/builtins.mjs +0 -135
  38. package/dist/core/cli/compiled.d.mts +0 -66
  39. package/dist/core/cli/compiled.mjs +0 -76
  40. package/dist/core/cli/dispatch.d.mts +0 -115
  41. package/dist/core/cli/dispatch.mjs +0 -205
  42. package/dist/core/cli/help-links.d.mts +0 -27
  43. package/dist/core/cli/help-links.mjs +0 -41
  44. package/dist/core/cli/index.mjs +0 -1271
  45. package/dist/core/cli/planner.d.mts +0 -174
  46. package/dist/core/cli/planner.mjs +0 -323
  47. package/dist/core/cli/plugin.d.mts +0 -94
  48. package/dist/core/cli/plugin.mjs +0 -41
  49. package/dist/core/cli/propagate.d.mts +0 -39
  50. package/dist/core/cli/propagate.mjs +0 -57
  51. package/dist/core/cli/reserved-flags.d.mts +0 -19
  52. package/dist/core/cli/reserved-flags.mjs +0 -158
  53. package/dist/core/cli/root-help.d.mts +0 -53
  54. package/dist/core/cli/root-help.mjs +0 -221
  55. package/dist/core/cli/root-output-flags.d.mts +0 -74
  56. package/dist/core/cli/root-output-flags.mjs +0 -169
  57. package/dist/core/cli/root-surface.d.mts +0 -64
  58. package/dist/core/cli/root-surface.mjs +0 -28
  59. package/dist/core/cli/runtime-preflight.d.mts +0 -213
  60. package/dist/core/cli/runtime-preflight.mjs +0 -221
  61. package/dist/core/completion/index.d.mts +0 -76
  62. package/dist/core/completion/index.mjs +0 -90
  63. package/dist/core/completion/shells/bash.d.mts +0 -23
  64. package/dist/core/completion/shells/bash.mjs +0 -312
  65. package/dist/core/completion/shells/fish.d.mts +0 -19
  66. package/dist/core/completion/shells/fish.mjs +0 -164
  67. package/dist/core/completion/shells/powershell.d.mts +0 -13
  68. package/dist/core/completion/shells/powershell.mjs +0 -360
  69. package/dist/core/completion/shells/shared.d.mts +0 -164
  70. package/dist/core/completion/shells/shared.mjs +0 -147
  71. package/dist/core/completion/shells/zsh.d.mts +0 -23
  72. package/dist/core/completion/shells/zsh.mjs +0 -256
  73. package/dist/core/config/index.d.mts +0 -191
  74. package/dist/core/config/index.mjs +0 -285
  75. package/dist/core/config/package-json.d.mts +0 -179
  76. package/dist/core/config/package-json.mjs +0 -353
  77. package/dist/core/errors/index.d.mts +0 -125
  78. package/dist/core/errors/index.mjs +0 -87
  79. package/dist/core/execution/index.d.mts +0 -61
  80. package/dist/core/execution/index.mjs +0 -220
  81. package/dist/core/help/ansi.d.mts +0 -84
  82. package/dist/core/help/ansi.mjs +0 -121
  83. package/dist/core/help/index.d.mts +0 -149
  84. package/dist/core/help/index.mjs +0 -418
  85. package/dist/core/help/theme.d.mts +0 -86
  86. package/dist/core/help/theme.mjs +0 -69
  87. package/dist/core/json-schema/index.mjs +0 -1008
  88. package/dist/core/json-schema/meta-descriptions.generated.d.mts +0 -274
  89. package/dist/core/json-schema/meta-descriptions.generated.mjs +0 -136
  90. package/dist/core/output/activity.d.mts +0 -193
  91. package/dist/core/output/activity.mjs +0 -452
  92. package/dist/core/output/bind.d.mts +0 -37
  93. package/dist/core/output/bind.mjs +0 -56
  94. package/dist/core/output/contracts.d.mts +0 -82
  95. package/dist/core/output/contracts.mjs +0 -57
  96. package/dist/core/output/display-value.d.mts +0 -19
  97. package/dist/core/output/display-value.mjs +0 -32
  98. package/dist/core/output/index.d.mts +0 -344
  99. package/dist/core/output/index.mjs +0 -514
  100. package/dist/core/output/renderers.d.mts +0 -45
  101. package/dist/core/output/renderers.mjs +0 -46
  102. package/dist/core/output/writer.d.mts +0 -39
  103. package/dist/core/output/writer.mjs +0 -12
  104. package/dist/core/parse/index.d.mts +0 -178
  105. package/dist/core/parse/index.mjs +0 -850
  106. package/dist/core/parse/occurrences.d.mts +0 -90
  107. package/dist/core/parse/occurrences.mjs +0 -114
  108. package/dist/core/prompt/index.d.mts +0 -213
  109. package/dist/core/prompt/index.mjs +0 -348
  110. package/dist/core/read-flags/index.d.mts +0 -150
  111. package/dist/core/read-flags/index.mjs +0 -217
  112. package/dist/core/resolve/args.d.mts +0 -39
  113. package/dist/core/resolve/args.mjs +0 -182
  114. package/dist/core/resolve/coerce.d.mts +0 -79
  115. package/dist/core/resolve/coerce.mjs +0 -900
  116. package/dist/core/resolve/config.d.mts +0 -10
  117. package/dist/core/resolve/config.mjs +0 -19
  118. package/dist/core/resolve/contracts.d.mts +0 -146
  119. package/dist/core/resolve/errors.d.mts +0 -10
  120. package/dist/core/resolve/errors.mjs +0 -148
  121. package/dist/core/resolve/flags.d.mts +0 -74
  122. package/dist/core/resolve/flags.mjs +0 -246
  123. package/dist/core/resolve/index.d.mts +0 -44
  124. package/dist/core/resolve/index.mjs +0 -123
  125. package/dist/core/resolve/path-checks.d.mts +0 -48
  126. package/dist/core/resolve/path-checks.mjs +0 -102
  127. package/dist/core/resolve/redaction.d.mts +0 -13
  128. package/dist/core/resolve/redaction.mjs +0 -14
  129. package/dist/core/resolve/stages.d.mts +0 -86
  130. package/dist/core/resolve/stages.mjs +0 -170
  131. package/dist/core/resolve/standard.d.mts +0 -26
  132. package/dist/core/resolve/standard.mjs +0 -212
  133. package/dist/core/schema/activity.d.mts +0 -189
  134. package/dist/core/schema/arg.d.mts +0 -1461
  135. package/dist/core/schema/arg.mjs +0 -1139
  136. package/dist/core/schema/brand.d.mts +0 -17
  137. package/dist/core/schema/cardinality.d.mts +0 -302
  138. package/dist/core/schema/cardinality.mjs +0 -514
  139. package/dist/core/schema/command.d.mts +0 -1132
  140. package/dist/core/schema/command.mjs +0 -999
  141. package/dist/core/schema/flag.d.mts +0 -1495
  142. package/dist/core/schema/flag.mjs +0 -1207
  143. package/dist/core/schema/index.d.mts +0 -15
  144. package/dist/core/schema/index.mjs +0 -10
  145. package/dist/core/schema/middleware.d.mts +0 -129
  146. package/dist/core/schema/middleware.mjs +0 -41
  147. package/dist/core/schema/number-constraints.d.mts +0 -96
  148. package/dist/core/schema/number-constraints.mjs +0 -60
  149. package/dist/core/schema/prompt.d.mts +0 -135
  150. package/dist/core/schema/provenance.d.mts +0 -99
  151. package/dist/core/schema/provenance.mjs +0 -28
  152. package/dist/core/schema/run.d.mts +0 -211
  153. package/dist/core/schema/source.d.mts +0 -180
  154. package/dist/core/schema/source.mjs +0 -206
  155. package/dist/core/schema/standard.d.mts +0 -100
  156. package/dist/core/schema/standard.mjs +0 -15
  157. package/dist/core/schema/stdin.d.mts +0 -97
  158. package/dist/core/schema/stdin.mjs +0 -91
  159. package/dist/core/schema/string-constraints.d.mts +0 -108
  160. package/dist/core/schema/string-constraints.mjs +0 -86
  161. package/dist/core/schema/value-parsers.d.mts +0 -150
  162. package/dist/core/schema/value-parsers.mjs +0 -160
  163. package/dist/core/schema/value.d.mts +0 -243
  164. package/dist/core/schema/value.mjs +0 -573
  165. package/dist/core/testkit/index.d.mts +0 -63
  166. package/dist/core/testkit/index.mjs +0 -102
  167. package/dist/runtime/adapter.mjs +0 -92
  168. package/dist/runtime/auto.d.mts +0 -25
  169. package/dist/runtime/auto.mjs +0 -45
  170. package/dist/runtime/deno.d.mts +0 -99
  171. package/dist/runtime/deno.mjs +0 -265
  172. package/dist/runtime/detect.d.mts +0 -86
  173. package/dist/runtime/detect.mjs +0 -45
  174. package/dist/runtime/index.d.mts +0 -6
  175. package/dist/runtime/node.d.mts +0 -71
  176. package/dist/runtime/node.mjs +0 -228
  177. package/dist/runtime/paths.d.mts +0 -31
  178. package/dist/runtime/paths.mjs +0 -48
  179. package/dist/strings.d.mts +0 -27
  180. package/dist/strings.mjs +0 -22
  181. package/examples/basic.ts +0 -37
  182. package/examples/flag-types.ts +0 -79
  183. package/examples/gh/package.json +0 -45
  184. package/examples/gh/src/commands/auth.ts +0 -66
  185. package/examples/gh/src/commands/issue.ts +0 -120
  186. package/examples/gh/src/commands/pr.ts +0 -125
  187. package/examples/gh/src/data/issues.yaml +0 -5
  188. package/examples/gh/src/data/issues.yaml.d.ts +0 -17
  189. package/examples/gh/src/data/pull-requests.yaml +0 -7
  190. package/examples/gh/src/data/pull-requests.yaml.d.ts +0 -18
  191. package/examples/gh/src/docs.ts +0 -11
  192. package/examples/gh/src/lib/auth.ts +0 -37
  193. package/examples/gh/src/lib/utils.ts +0 -17
  194. package/examples/gh/src/main.test.ts +0 -307
  195. package/examples/gh/src/main.ts +0 -46
  196. package/examples/help-config.ts +0 -43
  197. package/examples/interactive.ts +0 -67
  198. package/examples/json-mode.ts +0 -95
  199. package/examples/middleware.ts +0 -71
  200. package/examples/multi-command.ts +0 -66
  201. package/examples/output-extras.ts +0 -46
  202. package/examples/parser-control.ts +0 -40
  203. package/examples/pwsh-demo/README.md +0 -40
  204. package/examples/pwsh-demo/package.json +0 -41
  205. package/examples/pwsh-demo/pwsh-demo.cmd +0 -3
  206. package/examples/pwsh-demo/smoke-powershell.ps1 +0 -218
  207. package/examples/pwsh-demo/src/main.test.ts +0 -45
  208. package/examples/pwsh-demo/src/main.ts +0 -140
  209. package/examples/spinner-progress.ts +0 -49
  210. package/examples/standard-schema.ts +0 -45
  211. package/examples/testing.ts +0 -147
  212. package/examples/transport-launcher.ts +0 -85
@@ -1,15 +0,0 @@
1
- import { NumberConstraintViolation, NumberConstraints, describeNumberConstraintViolation, validateNumberConstraints } from "./number-constraints.mjs";
2
- import { ConfirmPromptConfig, InputPromptConfig, MultiselectPromptConfig, PROMPT_KINDS, PromptConfig, PromptConfigBase, PromptKind, PromptResult, SelectChoice, SelectPromptConfig } from "./prompt.mjs";
3
- import { InferStandardInput, InferStandardOutput, StandardSchemaV1, StandardSchemaV1FailureResult, StandardSchemaV1Issue, StandardSchemaV1Options, StandardSchemaV1PathSegment, StandardSchemaV1Props, StandardSchemaV1Result, StandardSchemaV1SuccessResult, StandardSchemaV1Types } from "./standard.mjs";
4
- import { STDIN_CONSUMES, STDIN_WHENS, StdinBinding, StdinConsume, StdinOptions, StdinWhen } from "./stdin.mjs";
5
- import { StringConstraintViolation, StringConstraints, describeStringConstraintViolation, stringConstraintDetails, validateStringConstraints } from "./string-constraints.mjs";
6
- import { DateFlagOptions, PathChecks, PathFlagOptions, UrlFlagOptions } from "./value-parsers.mjs";
7
- import { ArrayFlagDefinition, BooleanFlagDefinition, CountFlagDefinition, CustomFlagDefinition, DuplicatePolicy, EnumFlagDefinition, FLAG_KINDS, FLAG_PRESENCES, FlagAlias, FlagBuilder, FlagConfig, FlagDefinition, FlagDefinitionBase, FlagDefinitionByKind, FlagDefinitionOverrides, FlagFactory, FlagKind, FlagNegation, FlagParseFn, FlagPresence, FlagSchema, InferFlag, InferFlags, KeyValueFlagDefinition, NumberFlagDefinition, ResolvedValue, StringElementConfig, StringFlagDefinition, WithPresence, WithoutElementEligibility, createFlagSchema, flag, getFlagNegatedName } from "./flag.mjs";
8
- import { DUPLICATE_KEYS, DuplicateKeys, SPLIT_FORMATS, SourceSplitBinding, SplitBinding, SplitFormat, SplitOptions, SplitPolicy, SplitSetting } from "./cardinality.mjs";
9
- import { ARG_KINDS, ARG_PRESENCES, AllowedArgPromptConfig, ArgBuilder, ArgConfig, ArgDefaultValue, ArgDefinition, ArgDefinitionBase, ArgDefinitionByKind, ArgDefinitionOverrides, ArgFactory, ArgKind, ArgParseFn, ArgPresence, ArgSchema, BooleanArgDefinition, CustomArgDefinition, EnumArgDefinition, InferArg, InferArgs, KeyValueArgDefinition, NumberArgDefinition, PromptConfigByArgKind, ResolvedArgValue, StringArgDefinition, StringArgElementConfig, WithArgPresence, WithVariadic, WithoutArgElementEligibility, arg, createArgSchema } from "./arg.mjs";
10
- import { ActivityEvent, Fallback, ProgressHandle, ProgressOptions, SpinnerHandle, SpinnerOptions, TableColumn, TableFormat, TableOptions, TableStream } from "./activity.mjs";
11
- import { Middleware, MiddlewareHandler, MiddlewareParams, middleware } from "./middleware.mjs";
12
- import { InputSources, ResolutionProvenance, SourcesOf, wasExplicit } from "./provenance.mjs";
13
- import { ActionHandler, ActionParams, AnyCommandBuilder, CommandArgEntry, CommandArgEntryDefinition, CommandBuilder, CommandDefinition, CommandExample, CommandMeta, CommandSchema, DeriveHandler, DeriveParams, ExampleCommand, ExampleMeta, InteractiveParams, InteractiveResolver, InteractiveResult, Out, command, createCommandSchema, group, resolveExampleCommand } from "./command.mjs";
14
- import { RunOptions, RunResult } from "./run.mjs";
15
- export { ARG_KINDS, ARG_PRESENCES, type ActionHandler, type ActionParams, type ActivityEvent, type AllowedArgPromptConfig, type AnyCommandBuilder, ArgBuilder, type ArgConfig, type ArgDefaultValue, type ArgDefinition, type ArgDefinitionBase, type ArgDefinitionByKind, type ArgDefinitionOverrides, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type ArrayFlagDefinition, type BooleanArgDefinition, type BooleanFlagDefinition, type CommandArgEntry, type CommandArgEntryDefinition, CommandBuilder, type CommandDefinition, type CommandExample, type CommandMeta, type CommandSchema, type ConfirmPromptConfig, type CountFlagDefinition, type CustomArgDefinition, type CustomFlagDefinition, DUPLICATE_KEYS, type DateFlagOptions, type DeriveHandler, type DeriveParams, type DuplicateKeys, type DuplicatePolicy, type EnumArgDefinition, type EnumFlagDefinition, type ExampleCommand, type ExampleMeta, FLAG_KINDS, FLAG_PRESENCES, type Fallback, type FlagAlias, FlagBuilder, type FlagConfig, type FlagDefinition, type FlagDefinitionBase, type FlagDefinitionByKind, type FlagDefinitionOverrides, type FlagFactory, type FlagKind, type FlagNegation, type FlagParseFn, type FlagPresence, type FlagSchema, type InferArg, type InferArgs, type InferFlag, type InferFlags, type InferStandardInput, type InferStandardOutput, type InputPromptConfig, type InputSources, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type KeyValueArgDefinition, type KeyValueFlagDefinition, type Middleware, type MiddlewareHandler, type MiddlewareParams, type MultiselectPromptConfig, type NumberArgDefinition, type NumberConstraintViolation, type NumberConstraints, type NumberFlagDefinition, type Out, PROMPT_KINDS, type PathChecks, type PathFlagOptions, type ProgressHandle, type ProgressOptions, type PromptConfig, type PromptConfigBase, type PromptConfigByArgKind, type PromptKind, type PromptResult, type ResolutionProvenance, type ResolvedArgValue, type ResolvedValue, type RunOptions, type RunResult, SPLIT_FORMATS, STDIN_CONSUMES, STDIN_WHENS, type SelectChoice, type SelectPromptConfig, type SourceSplitBinding, type SourcesOf, type SpinnerHandle, type SpinnerOptions, type SplitBinding, type SplitFormat, type SplitOptions, type SplitPolicy, type SplitSetting, type StandardSchemaV1, type StandardSchemaV1FailureResult, type StandardSchemaV1Issue, type StandardSchemaV1Options, type StandardSchemaV1PathSegment, type StandardSchemaV1Props, type StandardSchemaV1Result, type StandardSchemaV1SuccessResult, type StandardSchemaV1Types, type StdinBinding, type StdinConsume, type StdinOptions, type StdinWhen, type StringArgDefinition, type StringArgElementConfig, type StringConstraintViolation, type StringConstraints, type StringElementConfig, type StringFlagDefinition, type TableColumn, type TableFormat, type TableOptions, type TableStream, type UrlFlagOptions, type WithArgPresence, type WithPresence, type WithVariadic, type WithoutArgElementEligibility, type WithoutElementEligibility, arg, command, createArgSchema, createCommandSchema, createFlagSchema, describeNumberConstraintViolation, describeStringConstraintViolation, flag, getFlagNegatedName, group, middleware, resolveExampleCommand, stringConstraintDetails, validateNumberConstraints, validateStringConstraints, wasExplicit };
@@ -1,10 +0,0 @@
1
- import { describeNumberConstraintViolation } from "./number-constraints.mjs";
2
- import { describeStringConstraintViolation, stringConstraintDetails } from "./string-constraints.mjs";
3
- import { DUPLICATE_KEYS, SPLIT_FORMATS } from "./cardinality.mjs";
4
- import "./stdin.mjs";
5
- import { FlagBuilder, createFlagSchema, flag, getFlagNegatedName } from "./flag.mjs";
6
- import { ArgBuilder, arg, createArgSchema } from "./arg.mjs";
7
- import { CommandBuilder, command, createCommandSchema, group, resolveExampleCommand } from "./command.mjs";
8
- import { middleware } from "./middleware.mjs";
9
- import { wasExplicit } from "./provenance.mjs";
10
- export { ArgBuilder, CommandBuilder, DUPLICATE_KEYS, FlagBuilder, SPLIT_FORMATS, arg, command, createArgSchema, createCommandSchema, createFlagSchema, describeNumberConstraintViolation, describeStringConstraintViolation, flag, getFlagNegatedName, group, middleware, resolveExampleCommand, stringConstraintDetails, wasExplicit };
@@ -1,129 +0,0 @@
1
- import { CommandMeta, ErasedInputSources, Out } from "./command.mjs";
2
- //#region src/core/schema/middleware.d.ts
3
- /**
4
- * Parameters received by a middleware function at runtime.
5
- *
6
- * Middleware receives erased args, flags, and provenance (since it's defined
7
- * independently of commands) plus the accumulated context from prior middleware
8
- * and a `next` function to continue the chain.
9
- */
10
- interface MiddlewareParams {
11
- /** Fully resolved positional arguments (type-erased). */
12
- readonly args: Readonly<Record<string, unknown>>;
13
- /** Fully resolved flags (type-erased). */
14
- readonly flags: Readonly<Record<string, unknown>>;
15
- /**
16
- * Where each resolved value came from, keyed like `flags` and `args`.
17
- *
18
- * Erased alongside them, so any key reads as `ResolutionProvenance |
19
- * undefined`. A key the bound command never declared, and one an input
20
- * resolved no value for, both read `undefined`.
21
- */
22
- readonly sources: ErasedInputSources;
23
- /** Context accumulated from previous middleware in the chain. */
24
- readonly ctx: Readonly<Record<string, unknown>>;
25
- /** Output channel. */
26
- readonly out: Out;
27
- /** CLI program metadata (name, bin, version, command). */
28
- readonly meta: CommandMeta;
29
- /**
30
- * Continue to the next middleware or action handler.
31
- *
32
- * Call with context additions that merge into `ctx` for downstream.
33
- * Returns when the entire downstream chain completes — enabling
34
- * wrap-around patterns (timing, try/catch, cleanup).
35
- */
36
- readonly next: (additions: Record<string, unknown>) => Promise<void>;
37
- }
38
- /**
39
- * Type-erased middleware handler stored on the command builder.
40
- *
41
- * At runtime, all middleware handlers have this signature. The phantom
42
- * `Output` type on {@linkcode Middleware} is erased.
43
- */
44
- type ErasedMiddlewareHandler = (params: MiddlewareParams) => void | Promise<void>;
45
- /**
46
- * Middleware handler function with typed `next()` parameter.
47
- *
48
- * The `Output` generic constrains what properties must be passed to
49
- * {@linkcode MiddlewareParams.next | next()}, ensuring type-safe context additions at the call site.
50
- */
51
- type MiddlewareHandler<Output extends Record<string, unknown>> = (params: {
52
- readonly args: Readonly<Record<string, unknown>>;
53
- readonly flags: Readonly<Record<string, unknown>>;
54
- readonly sources: ErasedInputSources;
55
- readonly ctx: Readonly<Record<string, unknown>>;
56
- readonly out: Out;
57
- readonly meta: CommandMeta;
58
- /** Pass context additions downstream. Must include all `Output` properties. */
59
- readonly next: (additions: Output) => Promise<void>;
60
- }) => void | Promise<void>;
61
- /**
62
- * Internal runtime representation of middleware.
63
- */
64
- interface MiddlewareImpl {
65
- readonly _handler: ErasedMiddlewareHandler;
66
- }
67
- /**
68
- * Middleware with phantom output type.
69
- *
70
- * The `Output` parameter tracks what this middleware adds to context at
71
- * compile time. The `_output` brand is phantom — it exists only in the
72
- * type system for inference, not at runtime.
73
- *
74
- * Created via the {@linkcode middleware} factory. Attached to commands via
75
- * `CommandBuilder.middleware()`.
76
- *
77
- * @example
78
- * ```ts
79
- * interface User { id: string; name: string }
80
- *
81
- * const auth = middleware<{ user: User }>(async ({ next }) => {
82
- * const user = await getUser();
83
- * if (!user) throw new CLIError('Not authenticated', { code: 'AUTH_REQUIRED' });
84
- * return next({ user });
85
- * });
86
- * ```
87
- */
88
- type Middleware<Output extends Record<string, unknown>> = MiddlewareImpl & {
89
- /** @internal Phantom type brand — compile-time only. */
90
- readonly _output: Output;
91
- };
92
- /**
93
- * Create a middleware definition.
94
- *
95
- * Middleware runs before the action handler and can add typed context,
96
- * short-circuit execution, or wrap downstream processing.
97
- *
98
- * @param handler - Function receiving `{ args, flags, ctx, out, meta, next }`.
99
- * Call `next(additions)` to continue the chain with added context.
100
- * Omitting the `next()` call short-circuits (e.g., for auth guards).
101
- * @returns {@linkcode Middleware} to attach via `CommandBuilder.middleware()`.
102
- *
103
- * @example
104
- * ```ts
105
- * // Auth guard — adds user to context or throws
106
- * const auth = middleware(async ({ next }) => {
107
- * const user = await getUser();
108
- * if (!user) throw new CLIError('Not authenticated', { code: 'AUTH_REQUIRED' });
109
- * return next({ user });
110
- * });
111
- *
112
- * // Timing wrapper — measures downstream execution
113
- * const timing = middleware(async ({ out, next }) => {
114
- * const start = Date.now();
115
- * await next({});
116
- * out.info(`Done in ${Date.now() - start}ms`);
117
- * });
118
- *
119
- * command('deploy')
120
- * .middleware(timing)
121
- * .middleware(auth)
122
- * .action(({ ctx }) => {
123
- * console.log(ctx.user.name); // typed!
124
- * });
125
- * ```
126
- */
127
- declare function middleware<Output extends Record<string, unknown>>(handler: MiddlewareHandler<Output>): Middleware<Output>;
128
- //#endregion
129
- export { type ErasedMiddlewareHandler, type Middleware, type MiddlewareHandler, type MiddlewareImpl, type MiddlewareParams, middleware };
@@ -1,41 +0,0 @@
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 };
@@ -1,96 +0,0 @@
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 };
@@ -1,60 +0,0 @@
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 };
@@ -1,135 +0,0 @@
1
- //#region src/core/schema/prompt.d.ts
2
- /**
3
- * Prompt type definitions for interactive flag resolution.
4
- *
5
- * Prompt configuration is stored on `FlagSchema.prompt` and consumed by the
6
- * resolution chain (v0.3+) when a flag value is missing after CLI/env/config
7
- * resolution. The prompt engine reads this config to present the appropriate
8
- * UI to the user.
9
- *
10
- * @module dreamcli/core/schema/prompt
11
- */
12
- /** All prompt kind discriminators as a runtime array. */
13
- declare const PROMPT_KINDS: readonly ["confirm", "input", "select", "multiselect"];
14
- /**
15
- * The kind of interactive prompt to present.
16
- *
17
- * - `'confirm'` — yes/no boolean question
18
- * - `'input'` — free-text string input
19
- * - `'select'` — single selection from a list
20
- * - `'multiselect'` — multiple selections from a list
21
- */
22
- type PromptKind = (typeof PROMPT_KINDS)[number];
23
- /** Shared fields across all prompt kinds. */
24
- interface PromptConfigBase {
25
- /** The question displayed to the user. */
26
- readonly message: string;
27
- }
28
- /** Yes/no confirmation prompt — maps to `boolean` flags. Part of {@link PromptConfig}. */
29
- interface ConfirmPromptConfig extends PromptConfigBase {
30
- /** Discriminator identifying this as a yes/no confirmation prompt. */
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;
38
- }
39
- /** Free-text input prompt — maps to `string` and `number` flags. Part of {@link PromptConfig}. */
40
- interface InputPromptConfig extends PromptConfigBase {
41
- /** Discriminator identifying this as a free-text input prompt. */
42
- readonly kind: 'input';
43
- /** Placeholder text shown before user types (informational only). */
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;
54
- /**
55
- * Inline validation function. Return `true` if valid, or a string
56
- * error message if invalid. Called before coercion to flag kind.
57
- */
58
- readonly validate?: (value: string) => true | string;
59
- }
60
- /** Single-selection prompt — maps to `enum` flags or any flag with {@link SelectChoice choices}. Part of {@link PromptConfig}. */
61
- interface SelectPromptConfig extends PromptConfigBase {
62
- /** Discriminator identifying this as a single-selection prompt. */
63
- readonly kind: 'select';
64
- /**
65
- * Available choices. When omitted for `enum` flags, the enum values
66
- * from the flag schema are used automatically.
67
- */
68
- readonly choices?: readonly SelectChoice[];
69
- }
70
- /**
71
- * Multi-selection prompt — maps to `array` flags.
72
- * Returns an array of selected {@link SelectChoice} values. Part of {@link PromptConfig}.
73
- */
74
- interface MultiselectPromptConfig extends PromptConfigBase {
75
- /** Discriminator identifying this as a multi-selection prompt. */
76
- readonly kind: 'multiselect';
77
- /**
78
- * Available choices. When omitted for `array` flags with enum elements,
79
- * the enum values from the element schema are used automatically.
80
- */
81
- readonly choices?: readonly SelectChoice[];
82
- /**
83
- * Minimum number of selections required.
84
- * @defaultValue `0`
85
- */
86
- readonly min?: number;
87
- /**
88
- * Maximum number of selections allowed.
89
- * @defaultValue `Infinity`
90
- */
91
- readonly max?: number;
92
- }
93
- /** A selectable option for {@link SelectPromptConfig} and {@link MultiselectPromptConfig} prompts. */
94
- interface SelectChoice {
95
- /** The value returned when this choice is selected. */
96
- readonly value: string;
97
- /**
98
- * Display label shown to the user.
99
- * @defaultValue {@link SelectChoice.value | value}
100
- */
101
- readonly label?: string;
102
- /** Optional description shown alongside the choice. */
103
- readonly description?: string;
104
- }
105
- /**
106
- * Discriminated union of all prompt configurations.
107
- *
108
- * Use the `kind` field to narrow:
109
- * ```ts
110
- * if (config.kind === 'select') {
111
- * config.choices // readonly SelectChoice[] | undefined
112
- * }
113
- * ```
114
- */
115
- type PromptConfig = ConfirmPromptConfig | InputPromptConfig | SelectPromptConfig | MultiselectPromptConfig;
116
- /**
117
- * The raw result returned by a prompt engine for a single prompt.
118
- *
119
- * - `answered: true` — user provided a value
120
- * - `answered: false` — user cancelled/aborted (Ctrl+C, ESC, etc.)
121
- *
122
- * Coercion to the flag's kind is the resolver's responsibility, not the
123
- * prompt engine's.
124
- */
125
- type PromptResult = {
126
- /** User provided a value. */
127
- readonly answered: true;
128
- /** The raw value from the prompt engine (not yet coerced). */
129
- readonly value: unknown;
130
- } | {
131
- /** User cancelled or aborted (Ctrl+C, ESC, etc.). */
132
- readonly answered: false;
133
- };
134
- //#endregion
135
- export { type ConfirmPromptConfig, type InputPromptConfig, type MultiselectPromptConfig, PROMPT_KINDS, type PromptConfig, type PromptConfigBase, type PromptKind, type PromptResult, type SelectChoice, type SelectPromptConfig };
@@ -1,99 +0,0 @@
1
- //#region src/core/schema/provenance.d.ts
2
- /**
3
- * Where a resolved value came from.
4
- *
5
- * Resolution records one {@link ResolutionProvenance} per input that produced a
6
- * value, and the same record reaches a handler through `sources` and a
7
- * `resolve()` caller through `ResolveResult.provenance`. {@link wasExplicit}
8
- * derives the explicit-versus-defaulted question from it.
9
- *
10
- * @module dreamcli/core/schema/provenance
11
- */
12
- /**
13
- * Which stage produced a resolved value, and how.
14
- *
15
- * `via` and `trigger` distinguish the two ways stdin delivers bytes. An explicit
16
- * `-` keeps CLI precedence and reports `{ stage: 'cli', via: 'stdin', trigger:
17
- * 'dash' }`; an absent input takes the fallback stage between CLI and env and
18
- * reports `{ stage: 'stdin', via: 'stdin', trigger: 'fallback' }`.
19
- *
20
- * @example
21
- * ```ts
22
- * command('deploy')
23
- * .flag('region', flag.string().env('REGION').default('us'))
24
- * .action(({ sources }) => {
25
- * const region = sources.flags.region;
26
- * if (region?.stage === 'env') console.log(`from ${region.envVar}`);
27
- * });
28
- * ```
29
- */
30
- type ResolutionProvenance = {
31
- readonly stage: 'cli';
32
- } | {
33
- readonly stage: 'cli';
34
- readonly via: 'stdin';
35
- readonly trigger: 'dash';
36
- } | {
37
- readonly stage: 'stdin';
38
- readonly via: 'stdin';
39
- readonly trigger: 'fallback';
40
- } | {
41
- readonly stage: 'env';
42
- readonly envVar: string;
43
- } | {
44
- readonly stage: 'config';
45
- readonly configPath: string;
46
- } | {
47
- readonly stage: 'prompt';
48
- } | {
49
- readonly stage: 'default';
50
- };
51
- /**
52
- * Provenance of every input of one surface, keyed by input name.
53
- *
54
- * An input that resolved no value has no record, so every member is optional in
55
- * value even though the key set is the surface's own.
56
- *
57
- * @typeParam T - The record of flag or arg builders whose keys this mirrors.
58
- */
59
- type SourcesOf<T> = { readonly [K in keyof T]: ResolutionProvenance | undefined; };
60
- /**
61
- * Where each of a command's resolved values came from.
62
- *
63
- * Handed to an action, derive, or middleware handler as `sources`, keyed by the
64
- * same names as `flags` and `args`.
65
- *
66
- * @typeParam F - The command's flag builders.
67
- * @typeParam A - The command's arg builders.
68
- */
69
- interface InputSources<F, A> {
70
- /** Provenance of every declared flag, keyed by flag name. */
71
- readonly flags: SourcesOf<F>;
72
- /** Provenance of every declared arg, keyed by arg name. */
73
- readonly args: SourcesOf<A>;
74
- }
75
- /**
76
- * Whether a value came from somewhere other than its declared default.
77
- *
78
- * Every stage but `'default'` means the value was supplied: typed on the command
79
- * line, piped, exported, written in a config file, or answered at a prompt. An
80
- * input that resolved no value at all has no record and is not explicit.
81
- *
82
- * Read `stage` directly for a narrower question, such as `stage === 'cli'` for
83
- * "the user typed it on this command line".
84
- *
85
- * @param source - The provenance record of one input, or `undefined`.
86
- * @returns `true` when a source other than the default produced the value.
87
- *
88
- * @example
89
- * ```ts
90
- * command('build')
91
- * .flag('out', flag.string().default('dist'))
92
- * .action(({ sources, out }) => {
93
- * if (wasExplicit(sources.flags.out)) out.info('using an overridden output');
94
- * });
95
- * ```
96
- */
97
- declare function wasExplicit(source: ResolutionProvenance | undefined): boolean;
98
- //#endregion
99
- export { type InputSources, type ResolutionProvenance, type SourcesOf, wasExplicit };
@@ -1,28 +0,0 @@
1
- //#region src/core/schema/provenance.ts
2
- /**
3
- * Whether a value came from somewhere other than its declared default.
4
- *
5
- * Every stage but `'default'` means the value was supplied: typed on the command
6
- * line, piped, exported, written in a config file, or answered at a prompt. An
7
- * input that resolved no value at all has no record and is not explicit.
8
- *
9
- * Read `stage` directly for a narrower question, such as `stage === 'cli'` for
10
- * "the user typed it on this command line".
11
- *
12
- * @param source - The provenance record of one input, or `undefined`.
13
- * @returns `true` when a source other than the default produced the value.
14
- *
15
- * @example
16
- * ```ts
17
- * command('build')
18
- * .flag('out', flag.string().default('dist'))
19
- * .action(({ sources, out }) => {
20
- * if (wasExplicit(sources.flags.out)) out.info('using an overridden output');
21
- * });
22
- * ```
23
- */
24
- function wasExplicit(source) {
25
- return source !== void 0 && source.stage !== "default";
26
- }
27
- //#endregion
28
- export { wasExplicit };