@kjanat/dreamcli 4.0.0-rc.3 → 4.0.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-D0hbBNVB.d.mts} +2 -4
  3. package/dist/completion-D4mz6axB.mjs +6 -0
  4. package/dist/completion.d.mts +90 -0
  5. package/dist/completion.mjs +1 -0
  6. package/dist/config-B9ddC-Kb.mjs +1 -0
  7. package/dist/config.d.mts +2 -0
  8. package/dist/config.mjs +1 -0
  9. package/dist/core-Cp2w8vRq.mjs +17 -0
  10. package/dist/index-BziI2aKc.d.mts +5440 -0
  11. package/dist/index-DOfClfYR.d.mts +370 -0
  12. package/dist/index-DWsnGZlx.d.mts +831 -0
  13. package/dist/{core/cli/index.d.mts → index-DXROeDPC.d.mts} +116 -57
  14. package/dist/index-DndPmT8J.d.mts +275 -0
  15. package/dist/{core/json-schema/index.d.mts → index-DyoaS234.d.mts} +43 -34
  16. package/dist/index.d.mts +190 -41
  17. package/dist/index.mjs +1 -26
  18. package/dist/json-schema-C9SzZ7jY.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,160 +0,0 @@
1
- //#region src/core/schema/value-parsers.ts
2
- /**
3
- * Strict ISO-8601 shapes accepted by {@link parseDateValue}:
4
- * `YYYY-MM-DD`, optionally followed by `THH:MM`, `:SS`, `.mmm`, and a
5
- * `Z` / `±HH:MM` offset. Anything else — including `Date.parse`-lenient
6
- * inputs like `'0'` or `'March 5'` — is rejected.
7
- */
8
- const ISO_DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?(Z|[+-]\d{2}:\d{2})?)?$/;
9
- /**
10
- * Parse a strict ISO-8601 date string into a `Date`.
11
- *
12
- * Rejects non-string input, non-ISO shapes, and calendar-invalid components
13
- * (`2026-02-31` does not silently roll over to March). Offset-less datetimes
14
- * are interpreted as UTC so results never depend on the machine's timezone.
15
- *
16
- * @param raw - Raw flag value.
17
- * @param options - Optional inclusive date bounds.
18
- * @returns The parsed `Date`.
19
- * @throws Error with a human-readable reason on invalid input.
20
- */
21
- function parseDateValue(raw, options) {
22
- if (raw instanceof Date) return validateDateBounds(raw, options);
23
- if (typeof raw !== "string") throw new Error(`Invalid date '${String(raw)}': expected an ISO-8601 string`);
24
- const match = ISO_DATE_PATTERN.exec(raw);
25
- if (match === null) throw new Error(`Invalid date '${raw}': expected ISO-8601 (e.g. 2026-07-10 or 2026-07-10T14:30:00Z)`);
26
- const [, yearPart, monthPart, dayPart, hourPart, minutePart, secondPart] = match;
27
- const year = Number(yearPart);
28
- const month = Number(monthPart);
29
- const day = Number(dayPart);
30
- if (month < 1 || month > 12) throw new Error(`Invalid date '${raw}': month must be 01-12`);
31
- if (day < 1 || day > daysInMonth(year, month)) throw new Error(`Invalid date '${raw}': not a real calendar date`);
32
- if (hourPart !== void 0 && Number(hourPart) > 23) throw new Error(`Invalid date '${raw}': hours must be 00-23`);
33
- if (minutePart !== void 0 && Number(minutePart) > 59) throw new Error(`Invalid date '${raw}': minutes must be 00-59`);
34
- if (secondPart !== void 0 && Number(secondPart) > 59) throw new Error(`Invalid date '${raw}': seconds must be 00-59`);
35
- const hasTime = match[4] !== void 0;
36
- const hasOffset = match[8] !== void 0;
37
- const parsed = new Date(hasTime && !hasOffset ? `${raw}Z` : raw);
38
- if (Number.isNaN(parsed.getTime())) throw new Error(`Invalid date '${raw}'`);
39
- return validateDateBounds(parsed, options, raw);
40
- }
41
- /** Number of days in a month (1-12), accounting for leap years. */
42
- function daysInMonth(year, month) {
43
- return new Date(Date.UTC(year, month, 0)).getUTCDate();
44
- }
45
- /** Enforce inclusive date bounds, throwing a human-readable error on violation. */
46
- function validateDateBounds(value, options, raw) {
47
- const display = raw ?? value.toISOString();
48
- if (options?.min !== void 0 && value.getTime() < options.min.getTime()) throw new Error(`Date '${display}' is before the earliest allowed ${options.min.toISOString()}`);
49
- if (options?.max !== void 0 && value.getTime() > options.max.getTime()) throw new Error(`Date '${display}' is after the latest allowed ${options.max.toISOString()}`);
50
- return value;
51
- }
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
- function parseUrlValue(raw, options) {
61
- if (typeof raw !== "string" && !(raw instanceof URL)) throw new Error(`Invalid URL '${String(raw)}': expected a URL string`);
62
- let parsed;
63
- try {
64
- parsed = raw instanceof URL ? raw : new URL(raw);
65
- } catch {
66
- throw new Error(`Invalid URL '${String(raw)}'`);
67
- }
68
- if (options?.protocols !== void 0) {
69
- const protocol = parsed.protocol.replace(/:$/, "");
70
- if (!options.protocols.includes(protocol)) throw new Error(`URL protocol '${protocol}' is not allowed. Allowed: ${options.protocols.join(", ")}`);
71
- }
72
- return parsed;
73
- }
74
- /** Duration unit suffixes mapped to their length in milliseconds. */
75
- const DURATION_UNITS = {
76
- ms: 1,
77
- s: 1e3,
78
- m: 6e4,
79
- h: 36e5,
80
- d: 864e5
81
- };
82
- /**
83
- * Parse a human duration (`'30s'`, `'5m'`, `'1.5h'`, `'250ms'`, `'2d'`) into
84
- * milliseconds. A bare number (`'1500'`) is treated as milliseconds. Compound
85
- * values (`'1h30m'`) are supported.
86
- *
87
- * @param raw - Raw flag value.
88
- * @returns Duration in milliseconds.
89
- * @throws Error with a human-readable reason on invalid input.
90
- */
91
- function parseDurationValue(raw) {
92
- if (typeof raw === "number") {
93
- if (!Number.isFinite(raw) || raw < 0) throw new Error(`Invalid duration '${String(raw)}': must be a non-negative number`);
94
- return raw;
95
- }
96
- if (typeof raw !== "string" || raw.length === 0) throw new Error(`Invalid duration '${String(raw)}': expected e.g. 30s, 5m, 1h30m, or 250ms`);
97
- if (/^\d+(?:\.\d+)?$/.test(raw)) return Number(raw);
98
- const segmentPattern = /(\d+(?:\.\d+)?)(ms|s|m|h|d)/gy;
99
- let total = 0;
100
- let consumed = 0;
101
- for (const segment of raw.matchAll(segmentPattern)) {
102
- const [text, amount, unit] = segment;
103
- const scale = unit === void 0 ? void 0 : DURATION_UNITS[unit];
104
- if (amount === void 0 || scale === void 0) break;
105
- total += Number(amount) * scale;
106
- consumed += text.length;
107
- }
108
- if (consumed !== raw.length || consumed === 0) throw new Error(`Invalid duration '${raw}': expected e.g. 30s, 5m, 1h30m, or 250ms`);
109
- return total;
110
- }
111
- /** Byte unit suffixes mapped to their size (binary, 1 kb = 1024 bytes). */
112
- const BYTE_UNITS = {
113
- b: 1,
114
- kb: 1024,
115
- mb: 1024 ** 2,
116
- gb: 1024 ** 3,
117
- tb: 1024 ** 4
118
- };
119
- /**
120
- * Parse a human byte size (`'512mb'`, `'1.5gb'`, `'64kb'`, `'100b'`) into a
121
- * byte count. Units are binary (`1kb` = 1024 bytes) and case-insensitive; a
122
- * bare number is treated as bytes.
123
- *
124
- * @param raw - Raw flag value.
125
- * @returns Size in bytes.
126
- * @throws Error with a human-readable reason on invalid input.
127
- */
128
- function parseBytesValue(raw) {
129
- if (typeof raw === "number") {
130
- if (!Number.isFinite(raw) || raw < 0) throw new Error(`Invalid size '${String(raw)}': must be a non-negative number`);
131
- return raw;
132
- }
133
- if (typeof raw !== "string" || raw.length === 0) throw new Error(`Invalid size '${String(raw)}': expected e.g. 512mb, 1.5gb, or 64kb`);
134
- const match = /^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb|tb)?$/i.exec(raw);
135
- if (match === null || match[1] === void 0) throw new Error(`Invalid size '${raw}': expected e.g. 512mb, 1.5gb, or 64kb`);
136
- const unit = (match[2] ?? "b").toLowerCase();
137
- const scale = BYTE_UNITS[unit];
138
- if (scale === void 0) throw new Error(`Invalid size '${raw}': unknown unit '${match[2] ?? ""}'`);
139
- return Math.round(Number(match[1]) * scale);
140
- }
141
- /**
142
- * Normalize path factory options into the {@link PathChecks} a schema stores.
143
- *
144
- * Options that ask for nothing (absent, `{}`, or `mustExist: false` alone)
145
- * produce `undefined`, so the schema records no checks and the resolver skips
146
- * the filesystem entirely.
147
- *
148
- * @param options - Options passed to `flag.path()` or `arg.path()`.
149
- * @returns The checks to store, or `undefined` when none were requested.
150
- */
151
- function buildPathChecks(options) {
152
- if (options === void 0 || options.mustExist !== true && options.type === void 0) return;
153
- return {
154
- mustExist: options.mustExist ?? true,
155
- type: options.type,
156
- create: options.type === "directory" && options.create === true
157
- };
158
- }
159
- //#endregion
160
- export { buildPathChecks, parseBytesValue, parseDateValue, parseDurationValue, parseUrlValue };
@@ -1,243 +0,0 @@
1
- import { NumberConstraintViolation, NumberConstraints } from "./number-constraints.mjs";
2
- import { StandardSchemaV1 } from "./standard.mjs";
3
- import { StringConstraintViolation, StringConstraints } from "./string-constraints.mjs";
4
- import { DateFlagOptions, PathChecks, PathFlagOptions, UrlFlagOptions } from "./value-parsers.mjs";
5
- import { FlagSchema } from "./flag.mjs";
6
- import { ArgSchema } from "./arg.mjs";
7
- //#region src/core/schema/value.d.ts
8
- /**
9
- * Which surface handed a raw value to the value layer.
10
- *
11
- * `'token'` is a CLI argv token; the rest name the resolver stage that produced
12
- * the value. Codecs widen what they accept as the input gets further from argv.
13
- * `'stdin'` accepts exactly what `'env'` accepts: both deliver a raw string a
14
- * user typed outside argv, so neither gets the extra latitude a prompt answer
15
- * or a typed config value gets.
16
- */
17
- type ValueInput = 'token' | 'stdin' | 'env' | 'config' | 'prompt';
18
- /** The primitive a codec could not read a raw value as. */
19
- type ValueTypeName = 'string' | 'number' | 'boolean';
20
- /** Why decoding rejected a raw value. */
21
- type ValueFailure = {
22
- readonly kind: 'type';
23
- readonly expected: ValueTypeName;
24
- } | {
25
- readonly kind: 'enum';
26
- readonly enumValues: readonly string[] | undefined;
27
- } | {
28
- readonly kind: 'string-constraint';
29
- readonly value: string;
30
- readonly violation: StringConstraintViolation;
31
- } | {
32
- readonly kind: 'number-constraint';
33
- readonly value: number;
34
- readonly violation: NumberConstraintViolation;
35
- } | {
36
- readonly kind: 'thrown';
37
- readonly error: unknown;
38
- };
39
- /** The outcome of decoding one raw value. */
40
- type ValueResult<T> = {
41
- readonly ok: true;
42
- readonly value: T;
43
- } | {
44
- readonly ok: false;
45
- readonly failure: ValueFailure;
46
- };
47
- /** Reads one raw value from one input surface into a typed value. */
48
- type ValueDecoder<T> = (raw: unknown, input: ValueInput) => ValueResult<T>;
49
- /** The narrowest shape every surface's parse function satisfies. */
50
- type ValueParseFn = (raw: never) => unknown;
51
- /** How a raw value becomes a typed one, plus the data the definition round-trip needs. */
52
- type ValueCodec<T = unknown, P = ValueParseFn> = {
53
- readonly name: 'string';
54
- readonly decode: ValueDecoder<T>;
55
- } | {
56
- readonly name: 'number';
57
- readonly decode: ValueDecoder<T>;
58
- } | {
59
- readonly name: 'boolean';
60
- readonly decode: ValueDecoder<T>;
61
- } | {
62
- readonly name: 'enum';
63
- readonly enumValues: readonly string[] | undefined;
64
- readonly decode: ValueDecoder<T>;
65
- } | {
66
- readonly name: 'custom';
67
- readonly parseFn: P | undefined;
68
- readonly decode: ValueDecoder<T>;
69
- };
70
- /** Rules a decoded value must satisfy, discriminated by the codec that produced it. */
71
- type ValueConstraints = {
72
- readonly kind: 'string';
73
- readonly stringConstraints: StringConstraints | undefined;
74
- } | {
75
- readonly kind: 'number';
76
- readonly numberConstraints: NumberConstraints | undefined;
77
- };
78
- /** Everything the value axis of a flag or an arg carries. */
79
- interface ValueSchema<T = unknown, P = ValueParseFn> {
80
- /** How a raw value becomes a typed one. */
81
- readonly codec: ValueCodec<T, P>;
82
- /** Rules the decoded value must satisfy, or `undefined` when the codec has none. */
83
- readonly constraints: ValueConstraints | undefined;
84
- /** Standard Schema v1 validator applied to the resolved value. */
85
- readonly standard: StandardSchemaV1 | undefined;
86
- /** Filesystem checks applied to the resolved value. */
87
- readonly pathChecks: PathChecks | undefined;
88
- /** Help placeholder label (`'url'` renders as `<url>`). */
89
- readonly valueHint: string | undefined;
90
- }
91
- /** The flat definition fields a {@link ValueSchema} contributes to a flag or arg definition. */
92
- interface ValueDefinitionFields<P = ValueParseFn> {
93
- /** String constraints, when the codec is `'string'` and any were declared. */
94
- readonly stringConstraints?: StringConstraints;
95
- /** Numeric constraints, when the codec is `'number'` and any were declared. */
96
- readonly numberConstraints?: NumberConstraints;
97
- /** Parse function, when the codec is `'custom'` and one was supplied. */
98
- readonly parseFn?: P;
99
- /** Standard Schema v1 validator, when one was supplied. */
100
- readonly standard?: StandardSchemaV1;
101
- /** Filesystem checks, when any were declared. */
102
- readonly pathChecks?: PathChecks;
103
- /** Help placeholder label, when the factory set one. */
104
- readonly valueHint?: string;
105
- }
106
- /**
107
- * Decode a raw value and apply the constraints riding on the value schema.
108
- *
109
- * The single entry point both the parse boundary and the resolver coercion
110
- * boundary use, so the two cannot drift on what a value means.
111
- *
112
- * @param value - The value axis of the flag or arg receiving the raw value.
113
- * @param raw - The raw token, env string, config value, or prompt answer.
114
- * @param input - Which surface produced `raw`.
115
- * @returns The decoded value, or the {@link ValueFailure} that rejected it.
116
- */
117
- declare function decodeValue(value: ValueSchema, raw: unknown, input: ValueInput): ValueResult<unknown>;
118
- /**
119
- * Drop the line terminator a pipe appends.
120
- *
121
- * @param text - The raw stdin buffer.
122
- * @returns The text without its single trailing terminator.
123
- */
124
- declare function stripTerminator(text: string): string;
125
- /**
126
- * Whether decoding leaves the line terminator a pipe appends on the value.
127
- *
128
- * @param value - The value axis about to read a stdin buffer.
129
- * @returns `true` when the terminator survives decoding.
130
- */
131
- declare function keepsStdinTerminator(value: ValueSchema): boolean;
132
- /**
133
- * Check a value that skipped decoding against everything the codec would have
134
- * produced and the constraints would have enforced.
135
- *
136
- * A declared default is already the typed value, so it is validated rather than
137
- * read from a raw source: it must lie in the codec's own output domain, and it
138
- * must satisfy the constraints. Standard Schema and filesystem checks ride on
139
- * the value schema separately and stay with their own passes.
140
- *
141
- * @param value - The value axis declaring the codec and the constraints.
142
- * @param decoded - The already-typed value to check.
143
- * @returns The {@link ValueFailure} that rejected it, or `undefined` when it passes.
144
- */
145
- declare function validateDecodedValue(value: ValueSchema, decoded: unknown): ValueFailure | undefined;
146
- /**
147
- * Describe a value failure in the words a message can carry.
148
- *
149
- * The subject the value belonged to is the caller's to name.
150
- *
151
- * @param failure - What the value layer rejected.
152
- * @returns One clause stating the problem.
153
- */
154
- declare function describeValueFailure(failure: ValueFailure): string;
155
- /** A string value, optionally constrained. */
156
- declare function stringValue(stringConstraints?: StringConstraints): ValueSchema<string>;
157
- /**
158
- * A string value that accepts nothing but a string, from every input.
159
- *
160
- * The implicit element of an entries collection, whose values are strings on
161
- * every source rather than a config scalar a string codec would stringify.
162
- */
163
- declare function strictStringValue(): ValueSchema<string>;
164
- /** A number value, optionally constrained. Finiteness applies with or without constraints. */
165
- declare function numberValue(numberConstraints?: NumberConstraints): ValueSchema<number>;
166
- /** A boolean value. */
167
- declare function booleanValue(): ValueSchema<boolean>;
168
- /** A value restricted to the declared literals. */
169
- declare function enumValue(enumValues: readonly string[] | undefined): ValueSchema<string>;
170
- /** A value produced by a flag-style parse function, which accepts any raw source value. */
171
- declare function customValue<P extends (raw: unknown) => unknown>(parseFn: P): ValueSchema<unknown, P>;
172
- /** A value produced by an arg-style parse function, which only ever receives strings. */
173
- declare function stringParsedValue<P extends (raw: string) => unknown>(parseFn: P): ValueSchema<unknown, P>;
174
- /** A value validated by a Standard Schema v1 validator instead of a parse function. */
175
- declare function standardValue(standard: StandardSchemaV1): ValueSchema<unknown, never>;
176
- /** A value passed through untouched. */
177
- declare function passthroughValue(): ValueSchema<unknown, never>;
178
- /** A `URL` value, optionally restricted to an allowlist of protocols. */
179
- declare function urlValue(options?: UrlFlagOptions): ValueSchema<unknown, (raw: unknown) => URL>;
180
- /** A path string, with the filesystem checks the options ask for. */
181
- declare function pathValue(options?: PathFlagOptions): ValueSchema<string>;
182
- /** A `Date` value parsed from strict ISO-8601, optionally bounded. */
183
- declare function dateValue(options?: DateFlagOptions): ValueSchema<unknown, (raw: unknown) => Date>;
184
- /** A duration in milliseconds. */
185
- declare function durationValue(): ValueSchema<unknown, (raw: unknown) => number>;
186
- /** A size in bytes. */
187
- declare function bytesValue(): ValueSchema<unknown, (raw: unknown) => number>;
188
- /**
189
- * Flatten a value schema into the definition fields a factory passes to
190
- * `createFlagSchema()` / `createArgSchema()`.
191
- *
192
- * `enumValues` is not among them. Both enum definitions declare that field as
193
- * required, which an all-optional record cannot satisfy, so the enum factories
194
- * pass it directly.
195
- *
196
- * @param value - The value axis to flatten.
197
- * @returns Only the fields the value actually declares.
198
- */
199
- declare function valueDefinitionFields<T, P>(value: ValueSchema<T, P>): ValueDefinitionFields<P>;
200
- /**
201
- * Project a flag schema onto its value axis.
202
- *
203
- * A collection projects onto the value of each ELEMENT, so `flag.array()` and
204
- * `flag.keyValue()` read their element schema's codec, constraints, validator,
205
- * and path checks here. What the completed collection must satisfy lives on the
206
- * cardinality axis and is read through {@link flagAggregateStandard}.
207
- *
208
- * @param schema - The flag schema to read.
209
- * @returns The value axis of one value of the flag.
210
- */
211
- declare function flagValueSchema(schema: FlagSchema): ValueSchema;
212
- /**
213
- * Standard Schema validator applied to a flag's completed collection.
214
- *
215
- * @param schema - The flag schema to read.
216
- * @returns The aggregate validator, or `undefined` for a scalar flag, whose
217
- * validator is the element's.
218
- */
219
- declare function flagAggregateStandard(schema: FlagSchema): StandardSchemaV1 | undefined;
220
- /**
221
- * Project an arg schema onto its value axis.
222
- *
223
- * An entries arg projects onto the value of each ENTRY, so
224
- * `arg.keyValue(arg.number())` reads its element schema's codec, constraints,
225
- * validator, and path checks here. What the completed record must satisfy lives
226
- * on the cardinality axis and is read through {@link argAggregateStandard}.
227
- *
228
- * @param schema - The arg schema to read.
229
- * @returns The value axis of one value of the arg.
230
- */
231
- declare function argValueSchema(schema: ArgSchema): ValueSchema;
232
- /**
233
- * Standard Schema validator applied to an arg's completed collection.
234
- *
235
- * @param schema - The arg schema to read.
236
- * @returns The aggregate validator, or `undefined` when none was declared on
237
- * the collection itself.
238
- */
239
- declare function argAggregateStandard(schema: ArgSchema): StandardSchemaV1 | undefined;
240
- /** The literals an enum value allows, or `undefined` for every other codec. */
241
- declare function valueEnumValues(value: ValueSchema | undefined): readonly string[] | undefined;
242
- //#endregion
243
- export { type ValueCodec, type ValueConstraints, type ValueDecoder, type ValueDefinitionFields, type ValueFailure, type ValueInput, type ValueParseFn, type ValueResult, type ValueSchema, type ValueTypeName, argAggregateStandard, argValueSchema, booleanValue, bytesValue, customValue, dateValue, decodeValue, describeValueFailure, durationValue, enumValue, flagAggregateStandard, flagValueSchema, keepsStdinTerminator, numberValue, passthroughValue, pathValue, standardValue, strictStringValue, stringParsedValue, stringValue, stripTerminator, urlValue, validateDecodedValue, valueDefinitionFields, valueEnumValues };