@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,100 +0,0 @@
1
- //#region src/core/schema/standard.d.ts
2
- /**
3
- * The Standard Schema v1 interface, vendored as types only.
4
- *
5
- * Mirrors the specification at https://standardschema.dev so validators from
6
- * zod, valibot, arktype, and any other conforming library can be passed to
7
- * `flag.custom()` / `arg.custom()` without adding a runtime dependency.
8
- *
9
- * @module
10
- */
11
- /** A schema that conforms to the Standard Schema v1 specification. */
12
- export interface StandardSchemaV1<Input = unknown, Output = Input> {
13
- /** The Standard Schema properties, namespaced under a well-known key. */
14
- readonly '~standard': StandardSchemaV1.Props<Input, Output>;
15
- }
16
- /** Types copied from the Standard Schema v1 specification. */
17
- export declare namespace StandardSchemaV1 {
18
- /** The properties exposed under a validator's `~standard` key. */
19
- interface Props<Input = unknown, Output = Input> {
20
- /** The version number of the specification. */
21
- readonly version: 1;
22
- /** The vendor name of the schema library. */
23
- readonly vendor: string;
24
- /** Validate an unknown value, returning its output or the issues found. */
25
- readonly validate: (value: unknown, options?: Options | undefined) => Result<Output> | Promise<Result<Output>>;
26
- /** Inferred input and output types, present only at the type level. */
27
- readonly types?: Types<Input, Output> | undefined;
28
- }
29
- /** Optional parameters passed to a validator. */
30
- interface Options {
31
- /** Explicit support for vendor-specific validation parameters. */
32
- readonly libraryOptions?: Record<string, unknown> | undefined;
33
- }
34
- /** The result of validating a value: either its output or a list of issues. */
35
- type Result<Output> = SuccessResult<Output> | FailureResult;
36
- /** A successful validation carrying the parsed output value. */
37
- interface SuccessResult<Output> {
38
- /** The validated (and possibly transformed) value. */
39
- readonly value: Output;
40
- /** Absent on success. */
41
- readonly issues?: undefined;
42
- }
43
- /** A failed validation carrying validation issues. */
44
- interface FailureResult {
45
- /** The issues that caused validation to fail. */
46
- readonly issues: ReadonlyArray<Issue>;
47
- }
48
- /** A single validation issue. */
49
- interface Issue {
50
- /** The human-readable error message. */
51
- readonly message: string;
52
- /** The path to the offending value, when the validator reports one. */
53
- readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
54
- }
55
- /** One segment of an issue path. */
56
- interface PathSegment {
57
- /** The key of this path segment. */
58
- readonly key: PropertyKey;
59
- }
60
- /** The type-level input and output carried by a validator. */
61
- interface Types<Input = unknown, Output = Input> {
62
- /** The input type accepted by the validator. */
63
- readonly input: Input;
64
- /** The output type produced by the validator. */
65
- readonly output: Output;
66
- }
67
- /** Infer the input type of a Standard Schema validator. */
68
- type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
69
- /** Infer the output type of a Standard Schema validator. */
70
- type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
71
- }
72
- /** Backward-compatible flat alias for {@link StandardSchemaV1.Props}. */
73
- export type StandardSchemaV1Props<Input = unknown, Output = Input> = StandardSchemaV1.Props<Input, Output>;
74
- /** Flat alias for {@link StandardSchemaV1.Options}. */
75
- export type StandardSchemaV1Options = StandardSchemaV1.Options;
76
- /** Flat alias for {@link StandardSchemaV1.Result}. */
77
- export type StandardSchemaV1Result<Output> = StandardSchemaV1.Result<Output>;
78
- /** Flat alias for {@link StandardSchemaV1.SuccessResult}. */
79
- export type StandardSchemaV1SuccessResult<Output> = StandardSchemaV1.SuccessResult<Output>;
80
- /** Flat alias for {@link StandardSchemaV1.FailureResult}. */
81
- export type StandardSchemaV1FailureResult = StandardSchemaV1.FailureResult;
82
- /** Flat alias for {@link StandardSchemaV1.Issue}. */
83
- export type StandardSchemaV1Issue = StandardSchemaV1.Issue;
84
- /** Flat alias for {@link StandardSchemaV1.PathSegment}. */
85
- export type StandardSchemaV1PathSegment = StandardSchemaV1.PathSegment;
86
- /** Backward-compatible flat alias for {@link StandardSchemaV1.Types}. */
87
- export type StandardSchemaV1Types<Input = unknown, Output = Input> = StandardSchemaV1.Types<Input, Output>;
88
- /** Flat alias for {@link StandardSchemaV1.InferInput}. */
89
- export type InferStandardInput<Schema extends StandardSchemaV1> = StandardSchemaV1.InferInput<Schema>;
90
- /** Flat alias for {@link StandardSchemaV1.InferOutput}. */
91
- export type InferStandardOutput<Schema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<Schema>;
92
- /**
93
- * Detect a Standard Schema validator without assuming validators are plain
94
- * objects. Some conforming libraries expose callable schema values.
95
- *
96
- * @internal
97
- */
98
- declare function isStandardSchemaV1(value: unknown): value is StandardSchemaV1;
99
- //#endregion
100
- export { isStandardSchemaV1 };
@@ -1,15 +0,0 @@
1
- //#region src/core/schema/standard.ts
2
- /**
3
- * Detect a Standard Schema validator without assuming validators are plain
4
- * objects. Some conforming libraries expose callable schema values.
5
- *
6
- * @internal
7
- */
8
- function isStandardSchemaV1(value) {
9
- if (value === null || typeof value !== "object" && typeof value !== "function") return false;
10
- if (!("~standard" in value)) return false;
11
- const properties = value["~standard"];
12
- return properties !== null && typeof properties === "object" && "version" in properties && properties.version === 1 && "validate" in properties && typeof properties.validate === "function";
13
- }
14
- //#endregion
15
- export { isStandardSchemaV1 };
@@ -1,97 +0,0 @@
1
- //#region src/core/schema/stdin.d.ts
2
- /**
3
- * The stdin binding shared by the `flag` and `arg` factories.
4
- *
5
- * A {@link StdinBinding} says when an input reads the stdin stream, whether it
6
- * consumes the stream alone, and whether a single value drops the terminator a
7
- * pipe appends. Both factories store one of these under their `stdin` field, and
8
- * the parse, preflight, and resolve pipelines read the stdin axis through it.
9
- *
10
- * @module dreamcli/core/schema/stdin
11
- */
12
- /** All stdin trigger modes as a runtime array. */
13
- declare const STDIN_WHENS: readonly ["dash", "missing", "dash-or-missing"];
14
- /**
15
- * When a stdin-enabled input reads the stdin stream.
16
- *
17
- * - `'dash'` — only an explicit `-` selects stdin; an absent input falls
18
- * through to the later sources
19
- * - `'missing'` — only an absent input selects stdin; a `-` stays the literal
20
- * string `'-'`
21
- * - `'dash-or-missing'` — both select stdin
22
- */
23
- type StdinWhen = (typeof STDIN_WHENS)[number];
24
- /** All stdin consumption modes as a runtime array. */
25
- declare const STDIN_CONSUMES: readonly ["exclusive", "broadcast"];
26
- /**
27
- * How a stdin-enabled input shares the stream with the command's other inputs.
28
- *
29
- * - `'exclusive'` — this input is the command's only stdin consumer, and a
30
- * second exclusive consumer is a schema error
31
- * - `'broadcast'` — every broadcast consumer on the command receives the same
32
- * buffer
33
- */
34
- type StdinConsume = (typeof STDIN_CONSUMES)[number];
35
- /** The normalized stdin axis of a flag or an arg. */
36
- interface StdinBinding {
37
- /** When this input reads the stdin stream. */
38
- readonly when: StdinWhen;
39
- /** Whether this input consumes the stream alone. */
40
- readonly consume: StdinConsume;
41
- /** Whether one trailing line terminator is dropped from a single value. */
42
- readonly trim: boolean;
43
- }
44
- /** Stdin settings accepted by `.stdin()` and by the schema definitions. */
45
- interface StdinOptions {
46
- /**
47
- * When this input reads the stdin stream.
48
- * @defaultValue `'dash-or-missing'`
49
- */
50
- readonly when?: StdinWhen | undefined;
51
- /**
52
- * Whether this input consumes the stream alone.
53
- * @defaultValue `'exclusive'`
54
- */
55
- readonly consume?: StdinConsume | undefined;
56
- /**
57
- * Drop one trailing `\n`, `\r\n`, or `\r` from a single value read off the
58
- * stream, so `echo ./dir | mycli` delivers `'./dir'`. A string is the one
59
- * kind that still carries the terminator at that point; every other kind
60
- * drops it while decoding and is unaffected.
61
- * @defaultValue `false`
62
- */
63
- readonly trim?: boolean | undefined;
64
- }
65
- /** The binding `.stdin()` produces when called without options. */
66
- declare const DEFAULT_STDIN_BINDING: StdinBinding;
67
- /**
68
- * Reject stdin settings that name a mode outside the declared unions.
69
- *
70
- * @param options - Stdin settings from a builder call or a schema definition.
71
- * @throws {CLIError} With code `'INVALID_SCHEMA'` on an unknown mode.
72
- */
73
- declare function assertStdinOptions(options: StdinOptions): void;
74
- /**
75
- * Normalize stdin settings into the binding a schema stores.
76
- *
77
- * @param options - Stdin settings, or `undefined` for every default.
78
- * @returns A fully populated {@link StdinBinding}.
79
- * @throws {CLIError} With code `'INVALID_SCHEMA'` on an unknown mode.
80
- */
81
- declare function normalizeStdinBinding(options?: StdinOptions): StdinBinding;
82
- /**
83
- * Whether an explicit `-` selects stdin for this binding.
84
- *
85
- * @param binding - Anything carrying the stdin trigger.
86
- * @returns `true` for `'dash'` and `'dash-or-missing'`.
87
- */
88
- declare function stdinReadsOnDash(binding: Pick<StdinBinding, 'when'>): boolean;
89
- /**
90
- * Whether an absent CLI value selects stdin for this binding.
91
- *
92
- * @param binding - Anything carrying the stdin trigger.
93
- * @returns `true` for `'missing'` and `'dash-or-missing'`.
94
- */
95
- declare function stdinReadsWhenMissing(binding: Pick<StdinBinding, 'when'>): boolean;
96
- //#endregion
97
- export { DEFAULT_STDIN_BINDING, STDIN_CONSUMES, STDIN_WHENS, type StdinBinding, type StdinConsume, type StdinOptions, type StdinWhen, assertStdinOptions, normalizeStdinBinding, stdinReadsOnDash, stdinReadsWhenMissing };
@@ -1,91 +0,0 @@
1
- import { CLIError } from "../errors/index.mjs";
2
- //#region src/core/schema/stdin.ts
3
- /**
4
- * The stdin binding shared by the `flag` and `arg` factories.
5
- *
6
- * A {@link StdinBinding} says when an input reads the stdin stream, whether it
7
- * consumes the stream alone, and whether a single value drops the terminator a
8
- * pipe appends. Both factories store one of these under their `stdin` field, and
9
- * the parse, preflight, and resolve pipelines read the stdin axis through it.
10
- *
11
- * @module dreamcli/core/schema/stdin
12
- */
13
- /** All stdin trigger modes as a runtime array. */
14
- const STDIN_WHENS = [
15
- "dash",
16
- "missing",
17
- "dash-or-missing"
18
- ];
19
- /** All stdin consumption modes as a runtime array. */
20
- const STDIN_CONSUMES = ["exclusive", "broadcast"];
21
- /** The binding `.stdin()` produces when called without options. */
22
- const DEFAULT_STDIN_BINDING = {
23
- when: "dash-or-missing",
24
- consume: "exclusive",
25
- trim: false
26
- };
27
- /**
28
- * Reject stdin settings that name a mode outside the declared unions.
29
- *
30
- * @param options - Stdin settings from a builder call or a schema definition.
31
- * @throws {CLIError} With code `'INVALID_SCHEMA'` on an unknown mode.
32
- */
33
- function assertStdinOptions(options) {
34
- if (options.when !== void 0 && !STDIN_WHENS.includes(options.when)) throw new CLIError(`Unknown stdin mode '${String(options.when)}'`, {
35
- code: "INVALID_SCHEMA",
36
- details: {
37
- when: options.when,
38
- allowed: [...STDIN_WHENS]
39
- },
40
- suggest: `Use one of: ${STDIN_WHENS.join(", ")}`
41
- });
42
- if (options.consume !== void 0 && !STDIN_CONSUMES.includes(options.consume)) throw new CLIError(`Unknown stdin consumption mode '${String(options.consume)}'`, {
43
- code: "INVALID_SCHEMA",
44
- details: {
45
- consume: options.consume,
46
- allowed: [...STDIN_CONSUMES]
47
- },
48
- suggest: `Use one of: ${STDIN_CONSUMES.join(", ")}`
49
- });
50
- if (options.trim !== void 0 && typeof options.trim !== "boolean") throw new CLIError(`Stdin trim must be a boolean, received '${String(options.trim)}'`, {
51
- code: "INVALID_SCHEMA",
52
- details: { trim: options.trim },
53
- suggest: "Pass trim: true or trim: false"
54
- });
55
- }
56
- /**
57
- * Normalize stdin settings into the binding a schema stores.
58
- *
59
- * @param options - Stdin settings, or `undefined` for every default.
60
- * @returns A fully populated {@link StdinBinding}.
61
- * @throws {CLIError} With code `'INVALID_SCHEMA'` on an unknown mode.
62
- */
63
- function normalizeStdinBinding(options) {
64
- if (options === void 0) return DEFAULT_STDIN_BINDING;
65
- assertStdinOptions(options);
66
- return {
67
- when: options.when ?? DEFAULT_STDIN_BINDING.when,
68
- consume: options.consume ?? DEFAULT_STDIN_BINDING.consume,
69
- trim: options.trim ?? DEFAULT_STDIN_BINDING.trim
70
- };
71
- }
72
- /**
73
- * Whether an explicit `-` selects stdin for this binding.
74
- *
75
- * @param binding - Anything carrying the stdin trigger.
76
- * @returns `true` for `'dash'` and `'dash-or-missing'`.
77
- */
78
- function stdinReadsOnDash(binding) {
79
- return binding.when === "dash" || binding.when === "dash-or-missing";
80
- }
81
- /**
82
- * Whether an absent CLI value selects stdin for this binding.
83
- *
84
- * @param binding - Anything carrying the stdin trigger.
85
- * @returns `true` for `'missing'` and `'dash-or-missing'`.
86
- */
87
- function stdinReadsWhenMissing(binding) {
88
- return binding.when === "missing" || binding.when === "dash-or-missing";
89
- }
90
- //#endregion
91
- export { DEFAULT_STDIN_BINDING, STDIN_CONSUMES, STDIN_WHENS, assertStdinOptions, normalizeStdinBinding, stdinReadsOnDash, stdinReadsWhenMissing };
@@ -1,108 +0,0 @@
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
- * Build the error-detail fields naming the rule a value broke.
84
- *
85
- * The parse path for flags and args and the resolver coercion path for env,
86
- * config, prompt, and stdin all attach these fields, so a consumer reading
87
- * `details` gets one shape wherever the failure came from.
88
- *
89
- * @param violation - The violation to describe.
90
- * @returns `constraint` plus the bound or pattern the violation carries.
91
- */
92
- declare function stringConstraintDetails(violation: StringConstraintViolation): Readonly<Record<string, unknown>>;
93
- /**
94
- * Assert that a constraints object is well-formed at schema-construction time.
95
- *
96
- * Length bounds must be non-negative integers — a fractional or negative
97
- * length is meaningless (omit the field for "no bound"). An inverted range
98
- * (`minLength > maxLength`) is also rejected, since it makes the flag/arg
99
- * permanently unsatisfiable. Throws so the misconfiguration surfaces where
100
- * the flag/arg is declared, not at parse time.
101
- *
102
- * @param constraints - The constraints to validate.
103
- * @throws RangeError if `minLength` or `maxLength` is negative, fractional, or
104
- * non-finite, or if `minLength` exceeds `maxLength`.
105
- */
106
- declare function assertStringConstraints(constraints: StringConstraints): void;
107
- //#endregion
108
- export { type StringConstraintViolation, type StringConstraints, assertStringConstraints, describeStringConstraintViolation, stringConstraintDetails, validateStringConstraints };
@@ -1,86 +0,0 @@
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
- * Build the error-detail fields naming the rule a value broke.
50
- *
51
- * The parse path for flags and args and the resolver coercion path for env,
52
- * config, prompt, and stdin all attach these fields, so a consumer reading
53
- * `details` gets one shape wherever the failure came from.
54
- *
55
- * @param violation - The violation to describe.
56
- * @returns `constraint` plus the bound or pattern the violation carries.
57
- */
58
- function stringConstraintDetails(violation) {
59
- return {
60
- constraint: violation.kind,
61
- ..."bound" in violation ? { bound: violation.bound } : {},
62
- ..."pattern" in violation ? { pattern: violation.pattern } : {}
63
- };
64
- }
65
- /**
66
- * Assert that a constraints object is well-formed at schema-construction time.
67
- *
68
- * Length bounds must be non-negative integers — a fractional or negative
69
- * length is meaningless (omit the field for "no bound"). An inverted range
70
- * (`minLength > maxLength`) is also rejected, since it makes the flag/arg
71
- * permanently unsatisfiable. Throws so the misconfiguration surfaces where
72
- * the flag/arg is declared, not at parse time.
73
- *
74
- * @param constraints - The constraints to validate.
75
- * @throws RangeError if `minLength` or `maxLength` is negative, fractional, or
76
- * non-finite, or if `minLength` exceeds `maxLength`.
77
- */
78
- function assertStringConstraints(constraints) {
79
- for (const field of ["minLength", "maxLength"]) {
80
- const bound = constraints[field];
81
- 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`);
82
- }
83
- 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})`);
84
- }
85
- //#endregion
86
- export { assertStringConstraints, describeStringConstraintViolation, stringConstraintDetails, validateStringConstraints };
@@ -1,150 +0,0 @@
1
- //#region src/core/schema/value-parsers.d.ts
2
- /**
3
- * Value-level machinery behind the sugar factories on both `flag` and `arg`
4
- * (`url()`, `path()`, `date()`, `duration()`, `bytes()`).
5
- *
6
- * Each parser converts a raw CLI/env/config/stdin 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 the subject's context
9
- * (`Failed to parse flag --x: <reason>`, `Failed to parse argument <x>: …`),
10
- * so parsers only describe the value problem itself.
11
- *
12
- * The option types keep their `Flag` prefix from the release that introduced
13
- * them on the flag factory alone. They describe the value, not flag syntax,
14
- * and the arg factory takes the same objects.
15
- *
16
- * @module dreamcli/core/schema/value-parsers
17
- */
18
- /** Options accepted by `flag.url()` and `arg.url()`. */
19
- interface UrlFlagOptions {
20
- /**
21
- * Allowed URL protocols, without the trailing colon (e.g. `['https']`).
22
- * @defaultValue `undefined` (any protocol)
23
- */
24
- readonly protocols?: readonly string[];
25
- }
26
- /** Options accepted by `flag.date()` and `arg.date()`. */
27
- interface DateFlagOptions {
28
- /**
29
- * Inclusive earliest allowed date.
30
- * @defaultValue `undefined` (no lower bound)
31
- */
32
- readonly min?: Date;
33
- /**
34
- * Inclusive latest allowed date.
35
- * @defaultValue `undefined` (no upper bound)
36
- */
37
- readonly max?: Date;
38
- }
39
- /**
40
- * Parse a strict ISO-8601 date string into a `Date`.
41
- *
42
- * Rejects non-string input, non-ISO shapes, and calendar-invalid components
43
- * (`2026-02-31` does not silently roll over to March). Offset-less datetimes
44
- * are interpreted as UTC so results never depend on the machine's timezone.
45
- *
46
- * @param raw - Raw flag value.
47
- * @param options - Optional inclusive date bounds.
48
- * @returns The parsed `Date`.
49
- * @throws Error with a human-readable reason on invalid input.
50
- */
51
- declare function parseDateValue(raw: unknown, options?: DateFlagOptions): Date;
52
- /**
53
- * Parse a URL string into a `URL`, optionally restricting protocols.
54
- *
55
- * @param raw - Raw flag value.
56
- * @param options - Optional protocol allowlist.
57
- * @returns The parsed `URL`.
58
- * @throws Error with a human-readable reason on invalid input.
59
- */
60
- declare function parseUrlValue(raw: unknown, options?: UrlFlagOptions): URL;
61
- /**
62
- * Parse a human duration (`'30s'`, `'5m'`, `'1.5h'`, `'250ms'`, `'2d'`) into
63
- * milliseconds. A bare number (`'1500'`) is treated as milliseconds. Compound
64
- * values (`'1h30m'`) are supported.
65
- *
66
- * @param raw - Raw flag value.
67
- * @returns Duration in milliseconds.
68
- * @throws Error with a human-readable reason on invalid input.
69
- */
70
- declare function parseDurationValue(raw: unknown): number;
71
- /**
72
- * Parse a human byte size (`'512mb'`, `'1.5gb'`, `'64kb'`, `'100b'`) into a
73
- * byte count. Units are binary (`1kb` = 1024 bytes) and case-insensitive; a
74
- * bare number is treated as bytes.
75
- *
76
- * @param raw - Raw flag value.
77
- * @returns Size in bytes.
78
- * @throws Error with a human-readable reason on invalid input.
79
- */
80
- declare function parseBytesValue(raw: unknown): number;
81
- /** Options accepted by `flag.path()` and `arg.path()` for any-kind or file paths. */
82
- interface FilePathFlagOptions {
83
- /**
84
- * Reject the value if nothing exists at the path.
85
- * @defaultValue `false` (`true` when `type` is set)
86
- */
87
- readonly mustExist?: boolean;
88
- /**
89
- * Require the path to be a file or a directory. Implies existence
90
- * unless `mustExist` is explicitly `false`, in which case a missing
91
- * path passes and only an existing path is type-checked.
92
- * @defaultValue `undefined` (any kind)
93
- */
94
- readonly type?: 'file';
95
- /** Directory creation is only available with `type: 'directory'`. */
96
- readonly create?: never;
97
- }
98
- /** Options accepted by `flag.path()` and `arg.path()` for directory paths. */
99
- interface DirectoryPathFlagOptions {
100
- /**
101
- * Reject the value if nothing exists at the path.
102
- * @defaultValue `false` (`true` when `type` is set)
103
- */
104
- readonly mustExist?: boolean;
105
- /**
106
- * Require the path to be a directory. Implies existence unless
107
- * `mustExist` is explicitly `false`, in which case a missing path
108
- * passes and only an existing path is type-checked.
109
- */
110
- readonly type: 'directory';
111
- /**
112
- * Create the directory (recursively) when nothing exists at the path.
113
- * An existing non-directory path still fails the type check.
114
- * @defaultValue `false`
115
- */
116
- readonly create?: boolean;
117
- }
118
- /** Options accepted by `flag.path()` and `arg.path()`. */
119
- type PathFlagOptions = FilePathFlagOptions | DirectoryPathFlagOptions;
120
- /**
121
- * Filesystem expectations attached by `flag.path()` and `arg.path()`.
122
- *
123
- * Checked after resolution (not during parse) via the runtime adapter, so
124
- * `src/core` stays free of platform I/O and every resolved value is validated
125
- * whichever source produced it, defaults included.
126
- */
127
- interface PathChecks {
128
- /** Reject the value if nothing exists at the path. */
129
- readonly mustExist: boolean;
130
- /**
131
- * Require the existing path to be a file or a directory. Implies
132
- * existence when set, unless `mustExist` is `false`.
133
- */
134
- readonly type: 'file' | 'directory' | undefined;
135
- /** Create the directory (recursively) when nothing exists at the path. */
136
- readonly create: boolean;
137
- }
138
- /**
139
- * Normalize path factory options into the {@link PathChecks} a schema stores.
140
- *
141
- * Options that ask for nothing (absent, `{}`, or `mustExist: false` alone)
142
- * produce `undefined`, so the schema records no checks and the resolver skips
143
- * the filesystem entirely.
144
- *
145
- * @param options - Options passed to `flag.path()` or `arg.path()`.
146
- * @returns The checks to store, or `undefined` when none were requested.
147
- */
148
- declare function buildPathChecks(options?: PathFlagOptions): PathChecks | undefined;
149
- //#endregion
150
- export { type DateFlagOptions, type PathChecks, type PathFlagOptions, type UrlFlagOptions, buildPathChecks, parseBytesValue, parseDateValue, parseDurationValue, parseUrlValue };