@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,514 +0,0 @@
1
- import { CLIError } from "../errors/index.mjs";
2
- import { describeValueFailure, validateDecodedValue } from "./value.mjs";
3
- //#region src/core/schema/cardinality.ts
4
- /**
5
- * The cardinality axis shared by the `flag` and `arg` factories.
6
- *
7
- * A {@link Cardinality} says how many values an input carries and how they
8
- * combine: one value, many values, key/value entries, or an occurrence count.
9
- * `flag.array()`, `flag.keyValue()`, `flag.count()`, `arg.keyValue()`, and
10
- * `.variadic()` all normalize onto it, and the parse and resolve pipelines
11
- * dispatch on {@link flagCardinality} / {@link argCardinality} rather than on
12
- * the kind discriminator.
13
- *
14
- * Splitting is per source. {@link splitBindingOf} resolves one
15
- * {@link SplitPolicy} for CLI tokens, one for environment values, and one for
16
- * the stdin buffer, so a CLI separator no longer decides how an env var or a
17
- * pipe decodes. A cardinality carries the CLI policy alone, which is the one
18
- * the parse boundary needs; every other source reads its policy off its own
19
- * {@link SourceBinding | source binding}.
20
- *
21
- * @module dreamcli/core/schema/cardinality
22
- * @internal
23
- */
24
- /** All split formats as a runtime array. */
25
- const SPLIT_FORMATS = [
26
- "whole",
27
- "delimiter",
28
- "lines",
29
- "json"
30
- ];
31
- /** The whole-value policy, shared by every source that declares none. */
32
- const WHOLE = { format: "whole" };
33
- /** The line policy stdin collections take by default. */
34
- const LINES = { format: "lines" };
35
- /** The comma policy environment collections take by default. */
36
- const ENV_DEFAULT = {
37
- format: "delimiter",
38
- delimiter: ","
39
- };
40
- /** The formats a bare string names, none of which carry a delimiter. */
41
- const NAMED_SPLIT_POLICIES = {
42
- whole: WHOLE,
43
- lines: LINES,
44
- json: { format: "json" }
45
- };
46
- /** Which formats each source accepts. */
47
- const ALLOWED_SPLIT_FORMATS = {
48
- cli: ["whole", "delimiter"],
49
- env: [
50
- "whole",
51
- "delimiter",
52
- "json"
53
- ],
54
- stdin: [
55
- "whole",
56
- "delimiter",
57
- "lines",
58
- "json"
59
- ]
60
- };
61
- /**
62
- * Read a bare string as the format it names, or as the delimiter to split on.
63
- *
64
- * @param setting - The string a caller passed for one source.
65
- * @returns The policy the string stands for.
66
- */
67
- function splitPolicyFromString(setting) {
68
- return Object.hasOwn(NAMED_SPLIT_POLICIES, setting) ? NAMED_SPLIT_POLICIES[setting] ?? WHOLE : {
69
- format: "delimiter",
70
- delimiter: setting
71
- };
72
- }
73
- /**
74
- * Normalize one source's split setting.
75
- *
76
- * @param source - Which source the setting belongs to.
77
- * @param setting - The policy, a format name, or a delimiter.
78
- * @returns The normalized policy.
79
- * @throws {CLIError} With code `'INVALID_SCHEMA'` on a format the source does
80
- * not accept, or an empty delimiter.
81
- */
82
- function normalizeSplitPolicy(source, setting) {
83
- if (typeof setting === "string") return normalizeSplitPolicyObject(source, splitPolicyFromString(setting));
84
- if (typeof setting !== "object" || setting === null) throw new CLIError(`Split policy for ${source} must be a string or object`, {
85
- code: "INVALID_SCHEMA",
86
- details: {
87
- source,
88
- received: setting === null ? "null" : typeof setting
89
- },
90
- suggest: "Pass a format name, delimiter string, or split-policy object"
91
- });
92
- return normalizeSplitPolicyObject(source, setting);
93
- }
94
- /** Validate and normalize an object-form split policy from a typed or JavaScript caller. */
95
- function normalizeSplitPolicyObject(source, setting) {
96
- const policy = setting;
97
- if (typeof policy.format !== "string") throw new CLIError(`Split policy for ${source} requires a string format`, {
98
- code: "INVALID_SCHEMA",
99
- details: {
100
- source,
101
- field: "format",
102
- received: typeof policy.format
103
- },
104
- suggest: "Pass a supported split format"
105
- });
106
- const allowed = ALLOWED_SPLIT_FORMATS[source];
107
- if (!allowed.includes(policy.format)) throw new CLIError(`Split format '${String(policy.format)}' is not available for ${source}`, {
108
- code: "INVALID_SCHEMA",
109
- details: {
110
- source,
111
- format: policy.format,
112
- allowed: [...allowed]
113
- },
114
- suggest: `Use one of: ${allowed.filter((format) => format !== "delimiter").join(", ")}, or a delimiter string`
115
- });
116
- if (policy.format !== "delimiter") return { format: policy.format };
117
- if (typeof policy.delimiter !== "string") throw new CLIError(`Split delimiter for ${source} must be a string`, {
118
- code: "INVALID_SCHEMA",
119
- details: {
120
- source,
121
- format: policy.format,
122
- received: typeof policy.delimiter
123
- },
124
- suggest: "Pass a delimiter string, for example ','"
125
- });
126
- if (policy.delimiter.length === 0) throw new CLIError(`Split delimiter for ${source} must not be empty`, {
127
- code: "INVALID_SCHEMA",
128
- details: {
129
- source,
130
- format: policy.format
131
- },
132
- suggest: "Pass a non-empty delimiter, for example ','"
133
- });
134
- return {
135
- format: "delimiter",
136
- delimiter: policy.delimiter
137
- };
138
- }
139
- /**
140
- * Normalize `.split()` options into the fields a schema stores.
141
- *
142
- * A source the options leave out keeps the policy already stored, so successive
143
- * `.split()` calls each set one source instead of clearing the others.
144
- *
145
- * @param options - Per-source split settings.
146
- * @param stored - The binding already on the schema, when there is one.
147
- * @returns The CLI delimiter and the stored non-CLI binding.
148
- * @throws {CLIError} With code `'INVALID_SCHEMA'` on a format a source does not
149
- * accept, or an empty delimiter.
150
- */
151
- function normalizeSplitOptions(options, stored) {
152
- const cli = options.cli === void 0 ? void 0 : normalizeSplitPolicy("cli", options.cli);
153
- const env = options.env === void 0 ? stored?.env : normalizeSplitPolicy("env", options.env);
154
- const stdin = options.stdin === void 0 ? stored?.stdin : normalizeSplitPolicy("stdin", options.stdin);
155
- return {
156
- separator: cli !== void 0 && cli.format === "delimiter" ? cli.delimiter : void 0,
157
- setsSeparator: cli !== void 0,
158
- split: env === void 0 && stdin === void 0 ? void 0 : {
159
- env,
160
- stdin
161
- }
162
- };
163
- }
164
- /**
165
- * Resolve the split policy of every source from the stored fields.
166
- *
167
- * @param separator - The CLI delimiter carrier.
168
- * @param split - The stored non-CLI policies.
169
- * @returns One policy per source, defaults filled in.
170
- */
171
- function splitBindingOf(separator, split) {
172
- return {
173
- cli: separator === void 0 ? WHOLE : {
174
- format: "delimiter",
175
- delimiter: separator
176
- },
177
- env: split?.env ?? ENV_DEFAULT,
178
- stdin: split?.stdin ?? LINES
179
- };
180
- }
181
- /** All duplicate-key policies as a runtime array. */
182
- const DUPLICATE_KEYS = [
183
- "first",
184
- "last",
185
- "error"
186
- ];
187
- /** The single-value cardinality, shared by every scalar input. */
188
- const ONE = { kind: "one" };
189
- /** The occurrence-count cardinality. */
190
- const COUNT = { kind: "count" };
191
- /**
192
- * Project a flag schema onto its cardinality axis.
193
- *
194
- * @param schema - The flag schema to read.
195
- * @returns How the flag's values combine.
196
- */
197
- function flagCardinality(schema) {
198
- switch (schema.kind) {
199
- case "array": return {
200
- kind: "many",
201
- unique: schema.unique,
202
- cliSplit: splitBindingOf(schema.separator, schema.split).cli
203
- };
204
- case "keyValue": return {
205
- kind: "entries",
206
- duplicateKeys: schema.duplicateKeys,
207
- cliSplit: splitBindingOf(schema.separator, schema.split).cli
208
- };
209
- case "count": return COUNT;
210
- case "string":
211
- case "number":
212
- case "boolean":
213
- case "enum":
214
- case "custom": return ONE;
215
- }
216
- }
217
- /**
218
- * Project an arg schema onto its cardinality axis.
219
- *
220
- * A `keyValue` arg aggregates entries whether or not it is variadic: the
221
- * non-variadic form reads one `k=v` token, the variadic form the whole tail.
222
- *
223
- * @param schema - The arg schema to read.
224
- * @returns How the arg's values combine.
225
- */
226
- function argCardinality(schema) {
227
- if (schema.kind === "keyValue") return {
228
- kind: "entries",
229
- duplicateKeys: schema.duplicateKeys,
230
- cliSplit: splitBindingOf(schema.separator, schema.split).cli
231
- };
232
- if (schema.variadic) return {
233
- kind: "many",
234
- unique: schema.unique,
235
- cliSplit: splitBindingOf(schema.separator, schema.split).cli
236
- };
237
- return ONE;
238
- }
239
- /** Whether a cardinality aggregates several values. */
240
- function isCollection(cardinality) {
241
- return cardinality.kind === "many" || cardinality.kind === "entries";
242
- }
243
- /**
244
- * Split text into the elements of a `many` collection.
245
- *
246
- * @param policy - The source's split policy.
247
- * @param text - The raw source text.
248
- * @returns The elements, or why the text was unreadable.
249
- */
250
- function splitManyText(policy, text) {
251
- switch (policy.format) {
252
- case "whole": return {
253
- ok: true,
254
- parts: text.length === 0 ? [] : [text]
255
- };
256
- case "delimiter": return {
257
- ok: true,
258
- parts: splitDelimited(text, policy.delimiter)
259
- };
260
- case "lines": return {
261
- ok: true,
262
- parts: splitLines(text)
263
- };
264
- case "json": {
265
- const parsed = parseJson(text);
266
- if (!parsed.ok) return parsed;
267
- if (!Array.isArray(parsed.value)) return {
268
- ok: false,
269
- failure: {
270
- kind: "json-shape",
271
- expected: "array"
272
- }
273
- };
274
- return {
275
- ok: true,
276
- parts: parsed.value
277
- };
278
- }
279
- }
280
- }
281
- /**
282
- * Split text into the pairs of an `entries` collection.
283
- *
284
- * Delimited and line-separated text carries `KEY=VALUE` segments split at the
285
- * first `=`; JSON text carries an object.
286
- *
287
- * @param policy - The source's split policy.
288
- * @param text - The raw source text.
289
- * @returns The pairs, or why the text was unreadable.
290
- */
291
- function splitEntriesText(policy, text) {
292
- if (policy.format === "json") {
293
- const parsed = parseJson(text);
294
- if (!parsed.ok) return parsed;
295
- const record = parsed.value;
296
- if (typeof record !== "object" || record === null || Array.isArray(record)) return {
297
- ok: false,
298
- failure: {
299
- kind: "json-shape",
300
- expected: "object"
301
- }
302
- };
303
- return {
304
- ok: true,
305
- parts: Object.entries(record)
306
- };
307
- }
308
- const segments = policy.format === "whole" ? text.length === 0 ? [] : [text] : policy.format === "lines" ? splitLines(text) : splitDelimited(text, policy.delimiter);
309
- const pairs = [];
310
- for (const segment of segments) {
311
- const pair = splitEntryPair(segment);
312
- if (pair === void 0) return {
313
- ok: false,
314
- failure: {
315
- kind: "pair",
316
- raw: segment
317
- }
318
- };
319
- pairs.push(pair);
320
- }
321
- return {
322
- ok: true,
323
- parts: pairs
324
- };
325
- }
326
- /**
327
- * Split one `KEY=VALUE` token at the first `=`.
328
- *
329
- * @param raw - The token to split.
330
- * @returns The pair, or `undefined` when the token has no `=` or an empty key.
331
- */
332
- function splitEntryPair(raw) {
333
- const equals = raw.indexOf("=");
334
- if (equals <= 0) return void 0;
335
- return [raw.slice(0, equals), raw.slice(equals + 1)];
336
- }
337
- /** Split on a literal delimiter, dropping empty segments. */
338
- function splitDelimited(text, delimiter) {
339
- return text.split(delimiter).filter((part) => part.length > 0);
340
- }
341
- /**
342
- * Split text on line terminators.
343
- *
344
- * A final terminator frames the last line rather than starting an empty one, so
345
- * the single empty element it produces is removed and genuine blank lines
346
- * survive: `'a\nb\n'` gives `['a', 'b']` and `'a\nb\n\n'` gives `['a', 'b', '']`.
347
- *
348
- * @param text - The raw source text.
349
- * @returns One element per line.
350
- */
351
- function splitLines(text) {
352
- if (text.length === 0) return [];
353
- const parts = text.split(/\r\n|\n|\r/);
354
- if (parts.length > 1 && parts[parts.length - 1] === "") parts.pop();
355
- return parts;
356
- }
357
- /** Parse JSON text, reporting the thrown error rather than throwing it. */
358
- function parseJson(text) {
359
- try {
360
- return {
361
- ok: true,
362
- value: JSON.parse(text)
363
- };
364
- } catch (error) {
365
- return {
366
- ok: false,
367
- failure: {
368
- kind: "json",
369
- error
370
- }
371
- };
372
- }
373
- }
374
- /** Deduplicate a resolved array, preserving first-seen order. */
375
- function dedupe(values) {
376
- return [...new Set(values)];
377
- }
378
- /**
379
- * Fold ordered pairs into a record under a duplicate-key policy.
380
- *
381
- * `Object.fromEntries` defines own data properties, so a `'__proto__'` key is
382
- * stored verbatim instead of reaching the prototype setter.
383
- *
384
- * @param pairs - The pairs in occurrence order.
385
- * @param duplicateKeys - What a repeated key means.
386
- * @returns The record, or the key that repeated under `'error'` and where.
387
- */
388
- function foldEntries(pairs, duplicateKeys) {
389
- const kept = /* @__PURE__ */ new Map();
390
- for (const [at, [key, value]] of pairs.entries()) {
391
- if (kept.has(key)) {
392
- if (duplicateKeys === "error") return {
393
- ok: false,
394
- duplicateKey: key,
395
- at
396
- };
397
- if (duplicateKeys === "first") continue;
398
- }
399
- kept.set(key, value);
400
- }
401
- return {
402
- ok: true,
403
- value: Object.fromEntries(kept)
404
- };
405
- }
406
- /**
407
- * Validate a declared default against the value and cardinality axes.
408
- *
409
- * A default is already the typed value, so it is validated rather than decoded.
410
- * Only synchronous verdicts are reachable here: a Standard Schema validator
411
- * that returns a promise is left to the resolution-time pass, as are filesystem
412
- * checks.
413
- *
414
- * @param element - The value axis of each element (of the value itself for `'one'`).
415
- * @param cardinality - How the input's values combine.
416
- * @param aggregate - Standard Schema validator applied to the completed collection.
417
- * @param value - The declared default.
418
- * @returns The violation, or `undefined` when the default is valid so far.
419
- */
420
- function validateDefault(element, cardinality, aggregate, value) {
421
- switch (cardinality.kind) {
422
- case "one": return validateDefaultElement(element, void 0, value);
423
- case "count": return typeof value === "number" && Number.isInteger(value) && value >= 0 ? void 0 : {
424
- kind: "shape",
425
- expected: "count"
426
- };
427
- case "many":
428
- if (!Array.isArray(value)) return {
429
- kind: "shape",
430
- expected: "array"
431
- };
432
- for (const [index, entry] of value.entries()) {
433
- const violation = validateDefaultElement(element, String(index), entry);
434
- if (violation !== void 0) return violation;
435
- }
436
- return validateDefaultStandard(aggregate, void 0, value);
437
- case "entries":
438
- if (typeof value !== "object" || value === null || Array.isArray(value)) return {
439
- kind: "shape",
440
- expected: "object"
441
- };
442
- for (const [key, entry] of Object.entries(value)) {
443
- const violation = validateDefaultElement(element, key, entry);
444
- if (violation !== void 0) return violation;
445
- }
446
- return validateDefaultStandard(aggregate, void 0, value);
447
- }
448
- }
449
- /** Apply the element constraints and the element validator to one default entry. */
450
- function validateDefaultElement(element, at, value) {
451
- const failure = validateDecodedValue(element, value);
452
- if (failure !== void 0) return {
453
- kind: "element",
454
- at,
455
- value,
456
- failure
457
- };
458
- return validateDefaultStandard(element.standard, at, value);
459
- }
460
- /** Apply a validator whose verdict is available synchronously. */
461
- function validateDefaultStandard(validator, at, value) {
462
- if (validator === void 0) return void 0;
463
- const result = validator["~standard"].validate(value);
464
- if (result instanceof Promise) return void 0;
465
- if (result.issues === void 0) return void 0;
466
- return {
467
- kind: "standard",
468
- at,
469
- value,
470
- issues: result.issues.map((issue) => issue.message)
471
- };
472
- }
473
- /** Vowel-initial kind names, for the article a message puts before one. */
474
- const VOWEL_INITIAL = /^[aeiou]/i;
475
- /**
476
- * The English article that precedes a kind name.
477
- *
478
- * @param word - The kind name a message names an input by.
479
- * @returns `'an'` before a vowel, `'a'` otherwise.
480
- */
481
- function indefiniteArticle(word) {
482
- return VOWEL_INITIAL.test(word) ? "an" : "a";
483
- }
484
- /**
485
- * Build the construction-time error for a default value that cannot hold.
486
- *
487
- * @param subject - How the input is spelled, `--tag` or `<files>`.
488
- * @param details - Structured identification of the input.
489
- * @param violation - What the default failed.
490
- * @returns The error to throw.
491
- */
492
- function defaultViolationError(subject, details, violation) {
493
- const at = "at" in violation && violation.at !== void 0 ? ` at ${violation.at}` : "";
494
- const reason = describeDefaultViolation(violation);
495
- return new CLIError(`Default value for ${subject}${at} is invalid: ${reason}`, {
496
- code: "INVALID_DEFAULT",
497
- details: {
498
- ...details,
499
- ...at === "" ? {} : { at: "at" in violation ? violation.at : void 0 },
500
- reason
501
- },
502
- suggest: `Change the default so it satisfies what ${subject} accepts`
503
- });
504
- }
505
- /** State the reason a default was rejected. */
506
- function describeDefaultViolation(violation) {
507
- switch (violation.kind) {
508
- case "shape": return violation.expected === "count" ? "expected a non-negative integer" : `expected an ${violation.expected}`;
509
- case "element": return describeValueFailure(violation.failure);
510
- case "standard": return violation.issues.join("; ");
511
- }
512
- }
513
- //#endregion
514
- export { DUPLICATE_KEYS, SPLIT_FORMATS, argCardinality, dedupe, defaultViolationError, flagCardinality, foldEntries, indefiniteArticle, isCollection, normalizeSplitOptions, normalizeSplitPolicy, splitBindingOf, splitEntriesText, splitEntryPair, splitLines, splitManyText, validateDefault };