@kjanat/dreamcli 3.0.0 → 4.0.0-rc.1
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.
- package/CHANGELOG.md +967 -1
- package/README.md +9 -3
- package/dist/core/cli/builtins.d.mts +47 -0
- package/dist/core/cli/builtins.mjs +135 -0
- package/dist/core/cli/compiled.d.mts +29 -0
- package/dist/core/cli/compiled.mjs +76 -0
- package/dist/core/cli/dispatch.d.mts +9 -85
- package/dist/core/cli/help-links.d.mts +2 -14
- package/dist/core/cli/index.d.mts +282 -101
- package/dist/core/cli/index.mjs +497 -264
- package/dist/core/cli/planner.d.mts +13 -86
- package/dist/core/cli/planner.mjs +47 -30
- package/dist/core/cli/plugin.d.mts +1 -1
- package/dist/core/cli/propagate.mjs +1 -1
- package/dist/core/cli/reserved-flags.d.mts +1 -0
- package/dist/core/cli/reserved-flags.mjs +158 -0
- package/dist/core/cli/root-help.d.mts +1 -47
- package/dist/core/cli/root-help.mjs +37 -47
- package/dist/core/cli/root-output-flags.d.mts +1 -0
- package/dist/core/cli/root-output-flags.mjs +169 -0
- package/dist/core/cli/root-surface.d.mts +1 -68
- package/dist/core/cli/root-surface.mjs +2 -2
- package/dist/core/cli/runtime-preflight.d.mts +1 -199
- package/dist/core/cli/runtime-preflight.mjs +67 -17
- package/dist/core/completion/index.d.mts +2 -2
- package/dist/core/completion/shells/bash.d.mts +0 -1
- package/dist/core/completion/shells/bash.mjs +2 -1
- package/dist/core/completion/shells/fish.d.mts +0 -1
- package/dist/core/completion/shells/fish.mjs +2 -1
- package/dist/core/completion/shells/powershell.d.mts +0 -1
- package/dist/core/completion/shells/powershell.mjs +2 -1
- package/dist/core/completion/shells/shared.d.mts +3 -114
- package/dist/core/completion/shells/shared.mjs +9 -39
- package/dist/core/completion/shells/zsh.d.mts +0 -1
- package/dist/core/completion/shells/zsh.mjs +2 -1
- package/dist/core/config/index.d.mts +3 -3
- package/dist/core/config/index.mjs +2 -2
- package/dist/core/config/package-json.d.mts +2 -33
- package/dist/core/config/package-json.mjs +1 -34
- package/dist/core/errors/index.d.mts +7 -7
- package/dist/core/execution/index.d.mts +1 -48
- package/dist/core/execution/index.mjs +42 -27
- package/dist/core/help/ansi.d.mts +0 -11
- package/dist/core/help/index.d.mts +3 -35
- package/dist/core/help/index.mjs +29 -6
- package/dist/core/help/theme.d.mts +1 -21
- package/dist/core/json-schema/index.d.mts +279 -10
- package/dist/core/json-schema/index.mjs +482 -237
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +79 -7
- package/dist/core/json-schema/meta-descriptions.generated.mjs +40 -6
- package/dist/core/output/activity.d.mts +1 -193
- package/dist/core/output/activity.mjs +1 -1
- package/dist/core/output/bind.d.mts +1 -37
- package/dist/core/output/contracts.d.mts +7 -13
- package/dist/core/output/contracts.mjs +1 -1
- package/dist/core/output/display-value.d.mts +1 -19
- package/dist/core/output/index.d.mts +5 -187
- package/dist/core/output/index.mjs +44 -9
- package/dist/core/output/renderers.d.mts +1 -45
- package/dist/core/output/writer.d.mts +0 -1
- package/dist/core/parse/index.d.mts +27 -5
- package/dist/core/parse/index.mjs +350 -227
- package/dist/core/parse/occurrences.d.mts +89 -0
- package/dist/core/parse/occurrences.mjs +114 -0
- package/dist/core/prompt/index.d.mts +3 -3
- package/dist/core/read-flags/index.d.mts +150 -0
- package/dist/core/read-flags/index.mjs +217 -0
- package/dist/core/resolve/args.d.mts +35 -4
- package/dist/core/resolve/args.mjs +132 -55
- package/dist/core/resolve/coerce.d.mts +66 -9
- package/dist/core/resolve/coerce.mjs +834 -270
- package/dist/core/resolve/config.d.mts +1 -10
- package/dist/core/resolve/contracts.d.mts +67 -44
- package/dist/core/resolve/errors.mjs +29 -21
- package/dist/core/resolve/flags.d.mts +36 -9
- package/dist/core/resolve/flags.mjs +129 -151
- package/dist/core/resolve/index.d.mts +8 -6
- package/dist/core/resolve/index.mjs +51 -18
- package/dist/core/resolve/path-checks.d.mts +47 -0
- package/dist/core/resolve/path-checks.mjs +102 -0
- package/dist/core/resolve/redaction.d.mts +12 -0
- package/dist/core/resolve/redaction.mjs +14 -0
- package/dist/core/resolve/stages.d.mts +85 -0
- package/dist/core/resolve/stages.mjs +170 -0
- package/dist/core/resolve/standard.d.mts +1 -24
- package/dist/core/resolve/standard.mjs +141 -43
- package/dist/core/schema/activity.d.mts +16 -16
- package/dist/core/schema/arg.d.mts +849 -71
- package/dist/core/schema/arg.mjs +727 -54
- package/dist/core/schema/brand.d.mts +17 -0
- package/dist/core/schema/cardinality.d.mts +301 -0
- package/dist/core/schema/cardinality.mjs +514 -0
- package/dist/core/schema/command.d.mts +181 -112
- package/dist/core/schema/command.mjs +305 -42
- package/dist/core/schema/flag.d.mts +515 -173
- package/dist/core/schema/flag.mjs +576 -78
- package/dist/core/schema/index.d.mts +11 -8
- package/dist/core/schema/index.mjs +10 -0
- package/dist/core/schema/middleware.d.mts +15 -12
- package/dist/core/schema/number-constraints.d.mts +5 -5
- package/dist/core/schema/prompt.d.mts +4 -4
- package/dist/core/schema/provenance.d.mts +99 -0
- package/dist/core/schema/provenance.mjs +28 -0
- package/dist/core/schema/run.d.mts +21 -60
- package/dist/core/schema/source.d.mts +179 -0
- package/dist/core/schema/source.mjs +206 -0
- package/dist/core/schema/standard.d.mts +12 -19
- package/dist/core/schema/stdin.d.mts +87 -0
- package/dist/core/schema/stdin.mjs +91 -0
- package/dist/core/schema/string-constraints.d.mts +16 -5
- package/dist/core/schema/string-constraints.mjs +18 -1
- package/dist/core/schema/value-parsers.d.mts +81 -9
- package/dist/core/schema/value-parsers.mjs +19 -1
- package/dist/core/schema/value.d.mts +242 -0
- package/dist/core/schema/value.mjs +573 -0
- package/dist/core/testkit/index.d.mts +28 -3
- package/dist/core/testkit/index.mjs +40 -26
- package/dist/index.d.mts +21 -16
- package/dist/index.mjs +10 -6
- package/dist/runtime/adapter.d.mts +3 -3
- package/dist/runtime/deno.d.mts +3 -3
- package/dist/runtime/detect.d.mts +2 -2
- package/dist/runtime/node.d.mts +3 -3
- package/dist/runtime/paths.d.mts +1 -31
- package/dist/runtime.d.mts +4 -4
- package/dist/strings.d.mts +1 -16
- package/dist/testkit.d.mts +2 -2
- package/dist/testkit.mjs +1 -1
- package/dist/version.d.mts +0 -13
- package/dist/version.mjs +2 -2
- package/dreamcli.schema.json +368 -78
- package/examples/interactive.ts +6 -5
- package/package.json +10 -9
- package/skills/cli-creation/SKILL.md +196 -0
- package/skills/cli-creation/agents/openai.yaml +4 -0
- package/skills/cli-creation/assets/templates/multi-command.bun-test.ts.tpl +20 -0
- package/skills/cli-creation/assets/templates/multi-command.test.ts.tpl +20 -0
- package/skills/cli-creation/assets/templates/multi-command.ts.tpl +89 -0
- package/skills/cli-creation/assets/templates/single-command.bun-test.ts.tpl +29 -0
- package/skills/cli-creation/assets/templates/single-command.test.ts.tpl +29 -0
- package/skills/cli-creation/assets/templates/single-command.ts.tpl +47 -0
- package/skills/cli-creation/references/consumer-workflow.md +65 -0
- package/skills/cli-creation/references/pattern-cookbook.md +451 -0
- package/skills/cli-creation/references/runtime-notes.md +29 -0
- package/skills/cli-creation/scripts/scaffold_cli.py +360 -0
- package/dist/core/resolve/property.d.mts +0 -51
- package/dist/core/resolve/property.mjs +0 -53
|
@@ -1,7 +1,10 @@
|
|
|
1
|
+
import { CLIError } from "../errors/index.mjs";
|
|
1
2
|
import { assertNumberConstraints } from "./number-constraints.mjs";
|
|
2
|
-
import { isStandardSchemaV1 } from "./standard.mjs";
|
|
3
3
|
import { assertStringConstraints } from "./string-constraints.mjs";
|
|
4
|
-
import {
|
|
4
|
+
import { bytesValue, customValue, dateValue, durationValue, flagAggregateStandard, flagValueSchema, numberValue, pathValue, standardValue, stringValue, urlValue, valueDefinitionFields } from "./value.mjs";
|
|
5
|
+
import { DUPLICATE_KEYS, SPLIT_FORMATS, defaultViolationError, flagCardinality, indefiniteArticle, isCollection, normalizeSplitOptions, normalizeSplitPolicy, validateDefault } from "./cardinality.mjs";
|
|
6
|
+
import { isStandardSchemaV1 } from "./standard.mjs";
|
|
7
|
+
import { normalizeStdinBinding } from "./stdin.mjs";
|
|
5
8
|
//#region src/core/schema/flag.ts
|
|
6
9
|
/**
|
|
7
10
|
* Flag schema builder with full type inference.
|
|
@@ -13,6 +16,17 @@ import { parseBytesValue, parseDateValue, parseDurationValue, parseUrlValue } fr
|
|
|
13
16
|
*
|
|
14
17
|
* @module dreamcli/core/schema/flag
|
|
15
18
|
*/
|
|
19
|
+
/** All flag kind discriminators as a runtime array. */
|
|
20
|
+
const FLAG_KINDS = [
|
|
21
|
+
"string",
|
|
22
|
+
"number",
|
|
23
|
+
"boolean",
|
|
24
|
+
"enum",
|
|
25
|
+
"array",
|
|
26
|
+
"custom",
|
|
27
|
+
"count",
|
|
28
|
+
"keyValue"
|
|
29
|
+
];
|
|
16
30
|
/**
|
|
17
31
|
* Normalise an alias input into a full {@link FlagAlias} object.
|
|
18
32
|
*
|
|
@@ -69,37 +83,303 @@ function getFlagNegatedName(name, schema) {
|
|
|
69
83
|
if (schema.negation === void 0) return void 0;
|
|
70
84
|
return schema.negation.alias ?? `no-${name}`;
|
|
71
85
|
}
|
|
86
|
+
/** Every runtime key carried by a normalized {@link FlagSchema}. */
|
|
87
|
+
const NORMALIZED_FLAG_SCHEMA_KEYS = [
|
|
88
|
+
"kind",
|
|
89
|
+
"presence",
|
|
90
|
+
"defaultValue",
|
|
91
|
+
"aliases",
|
|
92
|
+
"stdin",
|
|
93
|
+
"envVar",
|
|
94
|
+
"configPath",
|
|
95
|
+
"description",
|
|
96
|
+
"enumValues",
|
|
97
|
+
"numberConstraints",
|
|
98
|
+
"stringConstraints",
|
|
99
|
+
"elementSchema",
|
|
100
|
+
"separator",
|
|
101
|
+
"split",
|
|
102
|
+
"duplicateKeys",
|
|
103
|
+
"unique",
|
|
104
|
+
"pathChecks",
|
|
105
|
+
"valueHint",
|
|
106
|
+
"prompt",
|
|
107
|
+
"parseFn",
|
|
108
|
+
"standard",
|
|
109
|
+
"aggregateStandard",
|
|
110
|
+
"deprecated",
|
|
111
|
+
"propagate",
|
|
112
|
+
"negation",
|
|
113
|
+
"duplicates"
|
|
114
|
+
];
|
|
72
115
|
/**
|
|
73
|
-
*
|
|
116
|
+
* Whether an element input already carries every normalized schema key.
|
|
74
117
|
*
|
|
75
|
-
*
|
|
76
|
-
*
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
118
|
+
* @param element - Element definition or schema.
|
|
119
|
+
* @returns `true` when the value is already a built {@link FlagSchema}.
|
|
120
|
+
*/
|
|
121
|
+
function isNormalizedFlagSchema(element) {
|
|
122
|
+
return NORMALIZED_FLAG_SCHEMA_KEYS.every((key) => key in element);
|
|
123
|
+
}
|
|
124
|
+
/** Reject flag-level fields on a collection factory's element builder. */
|
|
125
|
+
function assertEligibleFlagElementBuilder(schema) {
|
|
126
|
+
if (COLLECTION_FLAG_KINDS.includes(schema.kind) || schema.kind === "count") throw new CLIError(`Flag element schema kind '${schema.kind}' is not supported`, {
|
|
127
|
+
code: "INVALID_SCHEMA",
|
|
128
|
+
details: {
|
|
129
|
+
kind: schema.kind,
|
|
130
|
+
field: "kind"
|
|
131
|
+
},
|
|
132
|
+
suggest: "Use a scalar value kind for the collection element"
|
|
133
|
+
});
|
|
134
|
+
const defaults = [
|
|
135
|
+
["presence", schema.kind === "boolean" ? "defaulted" : "optional"],
|
|
136
|
+
["defaultValue", schema.kind === "boolean" ? false : void 0],
|
|
137
|
+
["stdin", void 0],
|
|
138
|
+
["envVar", void 0],
|
|
139
|
+
["configPath", void 0],
|
|
140
|
+
["description", void 0],
|
|
141
|
+
["elementSchema", void 0],
|
|
142
|
+
["separator", void 0],
|
|
143
|
+
["split", void 0],
|
|
144
|
+
["duplicateKeys", "last"],
|
|
145
|
+
["unique", false],
|
|
146
|
+
["prompt", void 0],
|
|
147
|
+
["aggregateStandard", void 0],
|
|
148
|
+
["deprecated", void 0],
|
|
149
|
+
["propagate", false],
|
|
150
|
+
["negation", void 0],
|
|
151
|
+
["duplicates", "last"]
|
|
152
|
+
];
|
|
153
|
+
for (const [field, allowed] of defaults) {
|
|
154
|
+
if (schema[field] === allowed) continue;
|
|
155
|
+
throw new CLIError(`Flag element schema field '${String(field)}' is not supported`, {
|
|
156
|
+
code: "INVALID_SCHEMA",
|
|
157
|
+
details: {
|
|
158
|
+
kind: schema.kind,
|
|
159
|
+
field
|
|
160
|
+
},
|
|
161
|
+
suggest: `Drop '${String(field)}' from the collection element`
|
|
162
|
+
});
|
|
163
|
+
}
|
|
164
|
+
if (schema.aliases.length !== 0) throw new CLIError("Flag element schema field 'aliases' is not supported", {
|
|
165
|
+
code: "INVALID_SCHEMA",
|
|
166
|
+
details: {
|
|
167
|
+
kind: schema.kind,
|
|
168
|
+
field: "aliases"
|
|
169
|
+
},
|
|
170
|
+
suggest: "Drop 'aliases' from the collection element"
|
|
171
|
+
});
|
|
172
|
+
}
|
|
173
|
+
/**
|
|
174
|
+
* Normalise an array flag's element input into a built {@link FlagSchema}.
|
|
80
175
|
*
|
|
81
|
-
*
|
|
82
|
-
*
|
|
176
|
+
* An already-built schema is returned unchanged, so repeated normalization
|
|
177
|
+
* preserves element identity.
|
|
178
|
+
*
|
|
179
|
+
* @param element - Element definition or schema.
|
|
180
|
+
* @returns The element as a fully populated {@link FlagSchema}.
|
|
181
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` when a field belongs to a
|
|
182
|
+
* different {@link FlagKind}.
|
|
183
|
+
*/
|
|
184
|
+
function normalizeFlagElementSchema(element) {
|
|
185
|
+
if (isNormalizedFlagSchema(element)) {
|
|
186
|
+
assertValidFlagDefinition(element.kind, element);
|
|
187
|
+
return element;
|
|
188
|
+
}
|
|
189
|
+
const { kind, ...fields } = element;
|
|
190
|
+
assertValidFlagDefinition(kind, fields);
|
|
191
|
+
return buildFlagSchema(kind, normalizeFlagDefinitionFields(fields));
|
|
192
|
+
}
|
|
193
|
+
/**
|
|
194
|
+
* Resolve a definition's nested `elementSchema` into a built {@link FlagSchema}.
|
|
195
|
+
*
|
|
196
|
+
* @param fields - Definition fields excluding the kind discriminator.
|
|
197
|
+
* @returns The same fields with `elementSchema` normalized.
|
|
198
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` when a nested element field
|
|
199
|
+
* belongs to a different {@link FlagKind}.
|
|
200
|
+
*/
|
|
201
|
+
function normalizeFlagDefinitionFields(fields) {
|
|
202
|
+
const { elementSchema, ...rest } = fields;
|
|
203
|
+
if (elementSchema === void 0) return rest;
|
|
204
|
+
return {
|
|
205
|
+
...rest,
|
|
206
|
+
elementSchema: normalizeFlagElementSchema(elementSchema)
|
|
207
|
+
};
|
|
208
|
+
}
|
|
209
|
+
/** Flag kinds that can read from stdin: every scalar, plus the collections. */
|
|
210
|
+
const STDIN_CAPABLE_FLAG_KINDS = [
|
|
211
|
+
"string",
|
|
212
|
+
"number",
|
|
213
|
+
"boolean",
|
|
214
|
+
"enum",
|
|
215
|
+
"custom",
|
|
216
|
+
"array",
|
|
217
|
+
"keyValue"
|
|
218
|
+
];
|
|
219
|
+
/** The collection kinds, which carry an element schema and split policies. */
|
|
220
|
+
const COLLECTION_FLAG_KINDS = ["array", "keyValue"];
|
|
221
|
+
/**
|
|
222
|
+
* Fields that are only meaningful on some {@link FlagKind}s, mapped to them.
|
|
223
|
+
*/
|
|
224
|
+
const KIND_SPECIFIC_FLAG_FIELDS = [
|
|
225
|
+
["enumValues", ["enum"]],
|
|
226
|
+
["numberConstraints", ["number"]],
|
|
227
|
+
["stringConstraints", ["string"]],
|
|
228
|
+
["pathChecks", ["string"]],
|
|
229
|
+
["elementSchema", COLLECTION_FLAG_KINDS],
|
|
230
|
+
["separator", COLLECTION_FLAG_KINDS],
|
|
231
|
+
["split", COLLECTION_FLAG_KINDS],
|
|
232
|
+
["aggregateStandard", COLLECTION_FLAG_KINDS],
|
|
233
|
+
["parseFn", ["custom"]],
|
|
234
|
+
["negation", ["boolean"]]
|
|
235
|
+
];
|
|
236
|
+
/**
|
|
237
|
+
* Reject a definition that carries a field belonging to another {@link FlagKind}.
|
|
238
|
+
*
|
|
239
|
+
* A field set to `undefined` counts as absent, `unique` counts as absent when
|
|
240
|
+
* `false`, and `duplicateKeys` counts as absent when `'last'`, so re-feeding a
|
|
241
|
+
* built {@link FlagSchema} back through {@link createFlagSchema} stays valid: a
|
|
242
|
+
* built schema always carries those defaults, whatever its kind. The compile-time
|
|
243
|
+
* `this` parameter on `.unique()` and `.duplicateKeys()` is what rejects
|
|
244
|
+
* `.duplicateKeys('last')` on a scalar, since the runtime cannot tell that call
|
|
245
|
+
* apart from a round-tripped default.
|
|
246
|
+
*
|
|
247
|
+
* @param kind - Declared kind of the definition.
|
|
248
|
+
* @param fields - Definition fields excluding the kind discriminator.
|
|
249
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` on an unknown kind or a kind
|
|
250
|
+
* mismatch.
|
|
251
|
+
* @internal
|
|
252
|
+
*/
|
|
253
|
+
function assertValidFlagDefinition(kind, fields) {
|
|
254
|
+
assertKnownFlagKind(kind);
|
|
255
|
+
for (const [field, requiredKinds] of KIND_SPECIFIC_FLAG_FIELDS) {
|
|
256
|
+
if (requiredKinds.includes(kind)) continue;
|
|
257
|
+
if (fields[field] === void 0) continue;
|
|
258
|
+
throw invalidFlagFieldError(kind, field, requiredKinds);
|
|
259
|
+
}
|
|
260
|
+
if (kind !== "array" && fields.unique === true) throw invalidFlagFieldError(kind, "unique", ["array"]);
|
|
261
|
+
if (kind !== "keyValue" && fields.duplicateKeys !== void 0 && fields.duplicateKeys !== "last") throw invalidFlagFieldError(kind, "duplicateKeys", ["keyValue"]);
|
|
262
|
+
if (fields.duplicateKeys !== void 0 && !DUPLICATE_KEYS.includes(fields.duplicateKeys)) throw new CLIError(`Unknown duplicate-key policy '${String(fields.duplicateKeys)}'`, {
|
|
263
|
+
code: "INVALID_SCHEMA",
|
|
264
|
+
details: {
|
|
265
|
+
duplicateKeys: fields.duplicateKeys,
|
|
266
|
+
allowed: [...DUPLICATE_KEYS]
|
|
267
|
+
},
|
|
268
|
+
suggest: `Use one of: ${DUPLICATE_KEYS.join(", ")}`
|
|
269
|
+
});
|
|
270
|
+
if (kind === "enum" && fields.enumValues === void 0) throw new CLIError("Flag schema kind 'enum' requires field 'enumValues'", {
|
|
271
|
+
code: "INVALID_SCHEMA",
|
|
272
|
+
details: {
|
|
273
|
+
kind,
|
|
274
|
+
field: "enumValues"
|
|
275
|
+
},
|
|
276
|
+
suggest: "Pass the allowed values in 'enumValues'"
|
|
277
|
+
});
|
|
278
|
+
if ((kind === "array" || kind === "count" || kind === "keyValue") && fields.duplicates !== void 0 && fields.duplicates !== "last") throw new CLIError(`Flag schema field 'duplicates' is not supported on kind '${kind}'`, {
|
|
279
|
+
code: "INVALID_SCHEMA",
|
|
280
|
+
details: {
|
|
281
|
+
kind,
|
|
282
|
+
field: "duplicates"
|
|
283
|
+
},
|
|
284
|
+
suggest: `Drop 'duplicates'; kind '${kind}' accumulates every occurrence`
|
|
285
|
+
});
|
|
286
|
+
if ((kind === "count" || kind === "keyValue") && fields.prompt !== void 0) throw new CLIError(`Flag schema field 'prompt' is not available on kind '${kind}'`, {
|
|
287
|
+
code: "INVALID_SCHEMA",
|
|
288
|
+
details: {
|
|
289
|
+
kind,
|
|
290
|
+
field: "prompt"
|
|
291
|
+
},
|
|
292
|
+
suggest: `Drop 'prompt' from the ${kind} flag`
|
|
293
|
+
});
|
|
294
|
+
if (fields.stdin !== void 0) assertStdinCapableKind(kind);
|
|
295
|
+
}
|
|
296
|
+
/**
|
|
297
|
+
* Reject a discriminator outside {@link FLAG_KINDS}.
|
|
298
|
+
*
|
|
299
|
+
* The types admit only a declared kind, so this catches an untyped JavaScript
|
|
300
|
+
* caller before an unknown discriminator reaches an exhaustive `switch` that
|
|
301
|
+
* has no arm for it.
|
|
302
|
+
*
|
|
303
|
+
* @param kind - Declared kind of the definition.
|
|
304
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` on an unknown kind.
|
|
305
|
+
* @internal
|
|
306
|
+
*/
|
|
307
|
+
function assertKnownFlagKind(kind) {
|
|
308
|
+
if (FLAG_KINDS.includes(kind)) return;
|
|
309
|
+
throw new CLIError(`Unknown flag kind '${String(kind)}'`, {
|
|
310
|
+
code: "INVALID_SCHEMA",
|
|
311
|
+
details: {
|
|
312
|
+
kind,
|
|
313
|
+
allowed: [...FLAG_KINDS]
|
|
314
|
+
},
|
|
315
|
+
suggest: `Use one of: ${FLAG_KINDS.join(", ")}`
|
|
316
|
+
});
|
|
317
|
+
}
|
|
318
|
+
/**
|
|
319
|
+
* Reject a stdin binding on a flag kind that has no value to read.
|
|
320
|
+
*
|
|
321
|
+
* A `count` flag carries occurrences rather than a value, so both construction
|
|
322
|
+
* paths refuse the binding with the same error.
|
|
323
|
+
*
|
|
324
|
+
* @param kind - Declared kind of the flag.
|
|
325
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` on a kind that cannot read stdin.
|
|
326
|
+
*/
|
|
327
|
+
function assertStdinCapableKind(kind) {
|
|
328
|
+
if (STDIN_CAPABLE_FLAG_KINDS.some((allowed) => allowed === kind)) return;
|
|
329
|
+
throw new CLIError(`Flag schema field 'stdin' is not available on kind '${kind}'`, {
|
|
330
|
+
code: "INVALID_SCHEMA",
|
|
331
|
+
details: {
|
|
332
|
+
kind,
|
|
333
|
+
field: "stdin",
|
|
334
|
+
allowedKinds: [...STDIN_CAPABLE_FLAG_KINDS]
|
|
335
|
+
},
|
|
336
|
+
suggest: `Drop 'stdin' or declare the flag as one of: ${STDIN_CAPABLE_FLAG_KINDS.join(", ")}`
|
|
337
|
+
});
|
|
338
|
+
}
|
|
339
|
+
/**
|
|
340
|
+
* Build the `'INVALID_SCHEMA'` error for a field used on the wrong kind.
|
|
341
|
+
*
|
|
342
|
+
* @param kind - Declared kind of the definition.
|
|
343
|
+
* @param field - Offending field name.
|
|
344
|
+
* @param requiredKind - Kind the field belongs to.
|
|
345
|
+
* @returns The error to throw.
|
|
346
|
+
*/
|
|
347
|
+
function invalidFlagFieldError(kind, field, requiredKinds) {
|
|
348
|
+
const listed = requiredKinds.map((required) => `'${required}'`).join(" or ");
|
|
349
|
+
return new CLIError(`Flag schema field '${field}' requires kind ${listed}, received kind '${kind}'`, {
|
|
350
|
+
code: "INVALID_SCHEMA",
|
|
351
|
+
details: {
|
|
352
|
+
kind,
|
|
353
|
+
field,
|
|
354
|
+
requiredKinds: [...requiredKinds]
|
|
355
|
+
},
|
|
356
|
+
suggest: `Drop '${field}' or declare the flag as kind ${listed}`
|
|
357
|
+
});
|
|
358
|
+
}
|
|
359
|
+
/**
|
|
360
|
+
* Merge already-normalized schema fields onto the {@link FlagSchema} defaults.
|
|
361
|
+
*
|
|
362
|
+
* A field set to `undefined` falls back to its default for the fields
|
|
363
|
+
* {@link FlagSchema} declares as non-nullable.
|
|
83
364
|
*
|
|
84
365
|
* @param kind - Discriminator for the value type this flag accepts.
|
|
85
|
-
* @param overrides -
|
|
366
|
+
* @param overrides - Schema fields shallow-merged onto the defaults.
|
|
86
367
|
* @returns A fully populated {@link FlagSchema}.
|
|
87
|
-
*
|
|
88
|
-
* @example
|
|
89
|
-
* ```ts
|
|
90
|
-
* const schema = createSchema('enum', {
|
|
91
|
-
* enumValues: ['us', 'eu', 'ap'],
|
|
92
|
-
* description: 'Deployment region',
|
|
93
|
-
* });
|
|
94
|
-
* ```
|
|
95
368
|
*/
|
|
96
|
-
function
|
|
369
|
+
function buildFlagSchema(kind, overrides) {
|
|
370
|
+
const schema = assembleFlagSchema(kind, overrides);
|
|
371
|
+
assertValidFlagDefault(void 0, schema);
|
|
372
|
+
return schema;
|
|
373
|
+
}
|
|
374
|
+
/** Merge the normalized fields onto the defaults, without validating the result. */
|
|
375
|
+
function assembleFlagSchema(kind, overrides) {
|
|
97
376
|
const aliases = overrides?.aliases !== void 0 ? normalizeFlagAliases(overrides.aliases) : [];
|
|
98
|
-
const { aliases: _ignoredAliases, ...rest } = overrides ?? {};
|
|
377
|
+
const { aliases: _ignoredAliases, presence, stdin, unique, propagate, duplicates, duplicateKeys, ...rest } = overrides ?? {};
|
|
99
378
|
return {
|
|
100
379
|
kind,
|
|
101
|
-
presence: "optional",
|
|
380
|
+
presence: presence ?? "optional",
|
|
102
381
|
defaultValue: void 0,
|
|
382
|
+
stdin: stdin === void 0 ? void 0 : normalizeStdinBinding(stdin),
|
|
103
383
|
envVar: void 0,
|
|
104
384
|
configPath: void 0,
|
|
105
385
|
description: void 0,
|
|
@@ -108,21 +388,55 @@ function createSchema(kind, overrides) {
|
|
|
108
388
|
stringConstraints: void 0,
|
|
109
389
|
elementSchema: void 0,
|
|
110
390
|
separator: void 0,
|
|
111
|
-
|
|
391
|
+
split: void 0,
|
|
392
|
+
duplicateKeys: duplicateKeys ?? "last",
|
|
393
|
+
unique: unique ?? false,
|
|
112
394
|
pathChecks: void 0,
|
|
113
395
|
valueHint: void 0,
|
|
114
396
|
prompt: void 0,
|
|
115
397
|
parseFn: void 0,
|
|
116
398
|
standard: void 0,
|
|
399
|
+
aggregateStandard: void 0,
|
|
117
400
|
deprecated: void 0,
|
|
118
|
-
propagate: false,
|
|
401
|
+
propagate: propagate ?? false,
|
|
119
402
|
negation: void 0,
|
|
120
|
-
duplicates: "last",
|
|
403
|
+
duplicates: duplicates ?? "last",
|
|
121
404
|
...rest,
|
|
122
405
|
aliases
|
|
123
406
|
};
|
|
124
407
|
}
|
|
125
408
|
/**
|
|
409
|
+
* Reject a declared default the flag could never hold.
|
|
410
|
+
*
|
|
411
|
+
* A default is a typed value, so it is validated rather than decoded: string
|
|
412
|
+
* and number constraints, element and aggregate Standard Schema verdicts
|
|
413
|
+
* available synchronously, and the shape the cardinality requires. Filesystem
|
|
414
|
+
* checks and asynchronous validators stay with the resolution-time pass.
|
|
415
|
+
*
|
|
416
|
+
* @param name - Canonical flag name, when one is known.
|
|
417
|
+
* @param schema - The flag schema carrying the default.
|
|
418
|
+
* @throws {CLIError} With code `'INVALID_DEFAULT'` when the default is invalid.
|
|
419
|
+
*/
|
|
420
|
+
function assertValidFlagDefault(name, schema) {
|
|
421
|
+
if (schema.defaultValue === void 0) return;
|
|
422
|
+
const violation = validateDefault(flagValueSchema(schema), flagCardinality(schema), flagAggregateStandard(schema), schema.defaultValue);
|
|
423
|
+
if (violation === void 0) return;
|
|
424
|
+
throw defaultViolationError(name === void 0 ? `${indefiniteArticle(schema.kind)} ${schema.kind} flag` : `flag --${name}`, {
|
|
425
|
+
kind: schema.kind,
|
|
426
|
+
...name === void 0 ? {} : { flag: name }
|
|
427
|
+
}, violation);
|
|
428
|
+
}
|
|
429
|
+
function createFlagSchema(kindOrDefinition, overrides) {
|
|
430
|
+
if (typeof kindOrDefinition === "string") {
|
|
431
|
+
const fields = overrides ?? {};
|
|
432
|
+
assertValidFlagDefinition(kindOrDefinition, fields);
|
|
433
|
+
return buildFlagSchema(kindOrDefinition, normalizeFlagDefinitionFields(fields));
|
|
434
|
+
}
|
|
435
|
+
const { kind, ...fields } = kindOrDefinition;
|
|
436
|
+
assertValidFlagDefinition(kind, fields);
|
|
437
|
+
return buildFlagSchema(kind, normalizeFlagDefinitionFields(fields));
|
|
438
|
+
}
|
|
439
|
+
/**
|
|
126
440
|
* Immutable flag schema builder.
|
|
127
441
|
*
|
|
128
442
|
* The type parameter `C` is a phantom that tracks the value type and presence
|
|
@@ -168,11 +482,13 @@ var FlagBuilder = class FlagBuilder {
|
|
|
168
482
|
* ```
|
|
169
483
|
*/
|
|
170
484
|
default(value) {
|
|
171
|
-
|
|
485
|
+
const schema = {
|
|
172
486
|
...this.schema,
|
|
173
487
|
presence: "defaulted",
|
|
174
488
|
defaultValue: value
|
|
175
|
-
}
|
|
489
|
+
};
|
|
490
|
+
assertValidFlagDefault(void 0, schema);
|
|
491
|
+
return new FlagBuilder(schema);
|
|
176
492
|
}
|
|
177
493
|
/**
|
|
178
494
|
* Mark the flag as required. If not resolved from any source the framework
|
|
@@ -225,6 +541,9 @@ var FlagBuilder = class FlagBuilder {
|
|
|
225
541
|
/**
|
|
226
542
|
* Bind to an environment variable (resolved in v0.2+).
|
|
227
543
|
*
|
|
544
|
+
* The env value is read after CLI and stdin, and before config, the prompt,
|
|
545
|
+
* and the default: CLI → stdin → **env** → config → prompt → default.
|
|
546
|
+
*
|
|
228
547
|
* @param varName - Environment variable name (e.g. `'PORT'`).
|
|
229
548
|
* @returns The builder (for chaining).
|
|
230
549
|
*
|
|
@@ -243,8 +562,63 @@ var FlagBuilder = class FlagBuilder {
|
|
|
243
562
|
});
|
|
244
563
|
}
|
|
245
564
|
/**
|
|
565
|
+
* Let this flag read its value from piped stdin.
|
|
566
|
+
*
|
|
567
|
+
* An explicit `--<name> -` is CLI-sourced with bytes from stdin and keeps
|
|
568
|
+
* CLI precedence. An absent flag takes the stdin fallback stage, which sits
|
|
569
|
+
* between CLI and env, so a flag set in the environment still reads stdin
|
|
570
|
+
* and stdin wins. The whole buffer becomes the value, byte for byte for a
|
|
571
|
+
* string flag; every other kind drops the single line terminator a pipe
|
|
572
|
+
* appends before decoding, and `{ trim: true }` drops it for a string flag
|
|
573
|
+
* too.
|
|
574
|
+
*
|
|
575
|
+
* A collection reads the buffer as elements instead: `--tag -` splices what
|
|
576
|
+
* stdin decodes into the position the `-` occupies, so
|
|
577
|
+
* `--tag before --tag - --tag after` over `'a\nb\n'` resolves to
|
|
578
|
+
* `['before', 'a', 'b', 'after']`. `.split({ stdin })` sets the decoding.
|
|
579
|
+
* Each `-` stands for the whole source, so `--tag - --tag -` splices the
|
|
580
|
+
* buffer twice. A `-` typed beside other occurrences with nothing piped fails
|
|
581
|
+
* with `MISSING_STDIN`; occurrences of nothing but `-` fall through to the
|
|
582
|
+
* later sources.
|
|
583
|
+
*
|
|
584
|
+
* A stdin-enabled flag cannot receive a literal `-` as its value, since the
|
|
585
|
+
* token names the source.
|
|
586
|
+
*
|
|
587
|
+
* Available on every flag kind except `count`. One command may declare a
|
|
588
|
+
* single exclusive stdin consumer; pass `{ consume: 'broadcast' }` on every
|
|
589
|
+
* input that should share the buffer.
|
|
590
|
+
*
|
|
591
|
+
* @param options - When to read stdin, how to share it, and whether to trim.
|
|
592
|
+
* @returns The builder (for chaining).
|
|
593
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` on a `count` flag.
|
|
594
|
+
*
|
|
595
|
+
* @example
|
|
596
|
+
* ```ts
|
|
597
|
+
* flag.string().stdin().describe('Message body')
|
|
598
|
+
* // $ echo hi | mycli send → body = 'hi\n'
|
|
599
|
+
* // $ mycli send --body - → body reads stdin
|
|
600
|
+
* // $ mycli send --body hello → body = 'hello'
|
|
601
|
+
*
|
|
602
|
+
* flag.string().stdin({ when: 'dash' })
|
|
603
|
+
* // only `--body -` reads stdin
|
|
604
|
+
*
|
|
605
|
+
* flag.path({ mustExist: true }).stdin({ trim: true })
|
|
606
|
+
* // $ echo ./dist | mycli clean → path = './dist', checked on disk
|
|
607
|
+
* ```
|
|
608
|
+
*/
|
|
609
|
+
stdin(options) {
|
|
610
|
+
assertStdinCapableKind(this.schema.kind);
|
|
611
|
+
return new FlagBuilder({
|
|
612
|
+
...this.schema,
|
|
613
|
+
stdin: normalizeStdinBinding(options)
|
|
614
|
+
});
|
|
615
|
+
}
|
|
616
|
+
/**
|
|
246
617
|
* Bind to a dotted config path (resolved in v0.2+).
|
|
247
618
|
*
|
|
619
|
+
* The config value is read after CLI, stdin, and env, and before the prompt
|
|
620
|
+
* and the default: CLI → stdin → env → **config** → prompt → default.
|
|
621
|
+
*
|
|
248
622
|
* @param path - Dotted config key (e.g. `'deploy.region'`).
|
|
249
623
|
* @returns The builder (for chaining).
|
|
250
624
|
*
|
|
@@ -279,7 +653,7 @@ var FlagBuilder = class FlagBuilder {
|
|
|
279
653
|
/**
|
|
280
654
|
* Attach interactive prompt configuration for v0.3+ resolution.
|
|
281
655
|
*
|
|
282
|
-
* When a flag value is not resolved from CLI, env, or config, the
|
|
656
|
+
* When a flag value is not resolved from CLI, stdin, env, or config, the
|
|
283
657
|
* prompt engine uses this config to interactively ask the user.
|
|
284
658
|
* In non-interactive contexts (CI, piped stdin) prompts are skipped
|
|
285
659
|
* and resolution falls through to default or required validation.
|
|
@@ -367,7 +741,7 @@ var FlagBuilder = class FlagBuilder {
|
|
|
367
741
|
* ```
|
|
368
742
|
*/
|
|
369
743
|
int(value = true) {
|
|
370
|
-
return
|
|
744
|
+
return nextFlag({
|
|
371
745
|
...this.schema,
|
|
372
746
|
numberConstraints: {
|
|
373
747
|
...this.schema.numberConstraints,
|
|
@@ -395,7 +769,7 @@ var FlagBuilder = class FlagBuilder {
|
|
|
395
769
|
min: value
|
|
396
770
|
};
|
|
397
771
|
assertNumberConstraints(numberConstraints);
|
|
398
|
-
return
|
|
772
|
+
return nextFlag({
|
|
399
773
|
...this.schema,
|
|
400
774
|
numberConstraints
|
|
401
775
|
});
|
|
@@ -418,7 +792,7 @@ var FlagBuilder = class FlagBuilder {
|
|
|
418
792
|
max: value
|
|
419
793
|
};
|
|
420
794
|
assertNumberConstraints(numberConstraints);
|
|
421
|
-
return
|
|
795
|
+
return nextFlag({
|
|
422
796
|
...this.schema,
|
|
423
797
|
numberConstraints
|
|
424
798
|
});
|
|
@@ -438,7 +812,7 @@ var FlagBuilder = class FlagBuilder {
|
|
|
438
812
|
* ```
|
|
439
813
|
*/
|
|
440
814
|
finite(allow = true) {
|
|
441
|
-
return
|
|
815
|
+
return nextFlag({
|
|
442
816
|
...this.schema,
|
|
443
817
|
numberConstraints: {
|
|
444
818
|
...this.schema.numberConstraints,
|
|
@@ -459,7 +833,7 @@ var FlagBuilder = class FlagBuilder {
|
|
|
459
833
|
* ```
|
|
460
834
|
*/
|
|
461
835
|
nonEmpty(value = true) {
|
|
462
|
-
return
|
|
836
|
+
return nextFlag({
|
|
463
837
|
...this.schema,
|
|
464
838
|
stringConstraints: {
|
|
465
839
|
...this.schema.stringConstraints,
|
|
@@ -485,7 +859,7 @@ var FlagBuilder = class FlagBuilder {
|
|
|
485
859
|
minLength: value
|
|
486
860
|
};
|
|
487
861
|
assertStringConstraints(stringConstraints);
|
|
488
|
-
return
|
|
862
|
+
return nextFlag({
|
|
489
863
|
...this.schema,
|
|
490
864
|
stringConstraints
|
|
491
865
|
});
|
|
@@ -508,7 +882,7 @@ var FlagBuilder = class FlagBuilder {
|
|
|
508
882
|
maxLength: value
|
|
509
883
|
};
|
|
510
884
|
assertStringConstraints(stringConstraints);
|
|
511
|
-
return
|
|
885
|
+
return nextFlag({
|
|
512
886
|
...this.schema,
|
|
513
887
|
stringConstraints
|
|
514
888
|
});
|
|
@@ -526,7 +900,7 @@ var FlagBuilder = class FlagBuilder {
|
|
|
526
900
|
* ```
|
|
527
901
|
*/
|
|
528
902
|
pattern(value) {
|
|
529
|
-
return
|
|
903
|
+
return nextFlag({
|
|
530
904
|
...this.schema,
|
|
531
905
|
stringConstraints: {
|
|
532
906
|
...this.schema.stringConstraints,
|
|
@@ -539,11 +913,13 @@ var FlagBuilder = class FlagBuilder {
|
|
|
539
913
|
* `--tag a,b --tag c` resolves to `['a', 'b', 'c']`. Elements are coerced
|
|
540
914
|
* (and rejected) individually with the element schema's own error format.
|
|
541
915
|
*
|
|
542
|
-
*
|
|
543
|
-
*
|
|
916
|
+
* The separator is the CLI policy alone. Env values split on `','` and the
|
|
917
|
+
* stdin buffer on line terminators unless `.split()` says otherwise.
|
|
544
918
|
*
|
|
545
919
|
* @param value - Separator string (e.g. `','`).
|
|
546
920
|
* @returns The builder (for chaining).
|
|
921
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` on a flag that carries a
|
|
922
|
+
* single value.
|
|
547
923
|
*
|
|
548
924
|
* @example
|
|
549
925
|
* ```ts
|
|
@@ -552,19 +928,103 @@ var FlagBuilder = class FlagBuilder {
|
|
|
552
928
|
* ```
|
|
553
929
|
*/
|
|
554
930
|
separator(value) {
|
|
555
|
-
|
|
556
|
-
return
|
|
931
|
+
normalizeSplitPolicy("cli", value);
|
|
932
|
+
return nextFlag({
|
|
557
933
|
...this.schema,
|
|
558
934
|
separator: value
|
|
559
935
|
});
|
|
560
936
|
}
|
|
561
937
|
/**
|
|
938
|
+
* Set how each source decodes into elements.
|
|
939
|
+
*
|
|
940
|
+
* CLI tokens accept `'whole'` and a delimiter; env values also accept
|
|
941
|
+
* `'json'`; the stdin buffer accepts every format, including `'lines'`. The
|
|
942
|
+
* strings `'whole'`, `'lines'`, and `'json'` name their format, and every
|
|
943
|
+
* other string is the delimiter to split on. A source left out keeps what it
|
|
944
|
+
* already had, or its default: whole CLI tokens (or the `.separator()`
|
|
945
|
+
* delimiter), comma-delimited env values, line-delimited stdin. A config
|
|
946
|
+
* value is a native array or object, and a config string decodes under the
|
|
947
|
+
* env policy. For stdin, `'whole'` passes the complete buffer to a string
|
|
948
|
+
* element, including its final line terminator.
|
|
949
|
+
*
|
|
950
|
+
* @param options - Per-source split settings.
|
|
951
|
+
* @returns The builder (for chaining).
|
|
952
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` on a format the source does
|
|
953
|
+
* not accept, an empty delimiter, or a flag that carries a single value.
|
|
954
|
+
*
|
|
955
|
+
* @example
|
|
956
|
+
* ```ts
|
|
957
|
+
* flag.array(flag.string()).split({ cli: ',', env: { format: 'json' } }).env('TAGS')
|
|
958
|
+
* // --tag a,b → ['a', 'b']
|
|
959
|
+
* // TAGS='["a","b"]' → ['a', 'b']
|
|
960
|
+
* ```
|
|
961
|
+
*/
|
|
962
|
+
split(options) {
|
|
963
|
+
const normalized = normalizeSplitOptions(options, this.schema.split);
|
|
964
|
+
return nextFlag({
|
|
965
|
+
...this.schema,
|
|
966
|
+
...normalized.setsSeparator ? { separator: normalized.separator } : {},
|
|
967
|
+
split: normalized.split
|
|
968
|
+
});
|
|
969
|
+
}
|
|
970
|
+
/**
|
|
971
|
+
* Set how a repeated key combines.
|
|
972
|
+
*
|
|
973
|
+
* Applies to repeated CLI occurrences, delimited env pairs, and spliced stdin
|
|
974
|
+
* reads in the same occurrence order. JSON decoding does not preserve
|
|
975
|
+
* repeated object member names, so it cannot reliably expose them here.
|
|
976
|
+
*
|
|
977
|
+
* @param policy - `'last'` (default), `'first'`, or `'error'`.
|
|
978
|
+
* @returns The builder (for chaining).
|
|
979
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` on a flag that is not
|
|
980
|
+
* `keyValue`.
|
|
981
|
+
*
|
|
982
|
+
* @example
|
|
983
|
+
* ```ts
|
|
984
|
+
* flag.keyValue().duplicateKeys('error').env('VARS')
|
|
985
|
+
* // $ VARS='A=1,A=2' mycli run
|
|
986
|
+
* // # → Duplicate key '<redacted>' from env VARS for flag --env (CONSTRAINT_VIOLATED)
|
|
987
|
+
* ```
|
|
988
|
+
*/
|
|
989
|
+
duplicateKeys(policy) {
|
|
990
|
+
return nextFlag({
|
|
991
|
+
...this.schema,
|
|
992
|
+
duplicateKeys: policy
|
|
993
|
+
});
|
|
994
|
+
}
|
|
995
|
+
/**
|
|
996
|
+
* Validate the resolved value with a Standard Schema v1 validator.
|
|
997
|
+
*
|
|
998
|
+
* On a scalar builder the validator sees each value; on a collection builder
|
|
999
|
+
* it sees the completed array or record, after every element passed its own
|
|
1000
|
+
* validator. `flag.array(flag.string().standard(s))` validates elements,
|
|
1001
|
+
* `flag.array(flag.string()).standard(s)` validates the array.
|
|
1002
|
+
*
|
|
1003
|
+
* @param schema - A Standard Schema v1 validator.
|
|
1004
|
+
* @returns The builder (for chaining).
|
|
1005
|
+
*
|
|
1006
|
+
* @example
|
|
1007
|
+
* ```ts
|
|
1008
|
+
* import { z } from 'zod';
|
|
1009
|
+
* flag.array(flag.string()).standard(z.array(z.string()).min(1))
|
|
1010
|
+
* ```
|
|
1011
|
+
*/
|
|
1012
|
+
standard(schema) {
|
|
1013
|
+
const aggregate = isCollection(flagCardinality(this.schema));
|
|
1014
|
+
return nextFlag({
|
|
1015
|
+
...this.schema,
|
|
1016
|
+
...aggregate ? { aggregateStandard: schema } : { standard: schema }
|
|
1017
|
+
});
|
|
1018
|
+
}
|
|
1019
|
+
/**
|
|
562
1020
|
* Deduplicate the resolved array, preserving first-seen order. Applied
|
|
563
1021
|
* after all sources resolve, using `SameValueZero` semantics (like `Set`).
|
|
564
1022
|
*
|
|
565
1023
|
* @param value - Whether to deduplicate.
|
|
566
1024
|
* @defaultValue `true`
|
|
567
1025
|
* @returns The builder (for chaining).
|
|
1026
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` on a flag that is not
|
|
1027
|
+
* `array`.
|
|
568
1028
|
*
|
|
569
1029
|
* @example
|
|
570
1030
|
* ```ts
|
|
@@ -573,7 +1033,7 @@ var FlagBuilder = class FlagBuilder {
|
|
|
573
1033
|
* ```
|
|
574
1034
|
*/
|
|
575
1035
|
unique(value = true) {
|
|
576
|
-
return
|
|
1036
|
+
return nextFlag({
|
|
577
1037
|
...this.schema,
|
|
578
1038
|
unique: value
|
|
579
1039
|
});
|
|
@@ -590,6 +1050,8 @@ var FlagBuilder = class FlagBuilder {
|
|
|
590
1050
|
* @param options - Optional custom spelling (`alias`, without `--`) and
|
|
591
1051
|
* `hidden` to keep the negated spelling parseable but unadvertised.
|
|
592
1052
|
* @returns The builder (for chaining).
|
|
1053
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` on a flag that is not
|
|
1054
|
+
* `boolean`.
|
|
593
1055
|
*
|
|
594
1056
|
* @example
|
|
595
1057
|
* ```ts
|
|
@@ -599,7 +1061,7 @@ var FlagBuilder = class FlagBuilder {
|
|
|
599
1061
|
* ```
|
|
600
1062
|
*/
|
|
601
1063
|
negatable(options) {
|
|
602
|
-
return
|
|
1064
|
+
return nextFlag({
|
|
603
1065
|
...this.schema,
|
|
604
1066
|
negation: {
|
|
605
1067
|
alias: options?.alias,
|
|
@@ -626,84 +1088,120 @@ var FlagBuilder = class FlagBuilder {
|
|
|
626
1088
|
* ```
|
|
627
1089
|
*/
|
|
628
1090
|
duplicates(policy) {
|
|
629
|
-
return
|
|
1091
|
+
return nextFlag({
|
|
630
1092
|
...this.schema,
|
|
631
1093
|
duplicates: policy
|
|
632
1094
|
});
|
|
633
1095
|
}
|
|
634
1096
|
};
|
|
635
1097
|
/**
|
|
1098
|
+
* Continue a builder chain, rejecting a schema the change just invalidated.
|
|
1099
|
+
*
|
|
1100
|
+
* The `this` constraint on each modifier states to the compiler which kinds
|
|
1101
|
+
* carry the field it sets; this states the same rule to a caller who reaches
|
|
1102
|
+
* the builder from JavaScript, with the error {@link createFlagSchema} already
|
|
1103
|
+
* gives, so what a builder produces is always a definition the framework can
|
|
1104
|
+
* read back.
|
|
1105
|
+
*
|
|
1106
|
+
* A constraint added after `.default()` still governs the default, so the
|
|
1107
|
+
* verdict is the same whichever order the chain was written in.
|
|
1108
|
+
*
|
|
1109
|
+
* @param schema - The schema the modifier produced.
|
|
1110
|
+
* @returns A builder over that schema.
|
|
1111
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` when the field does not belong
|
|
1112
|
+
* on the flag, or `'INVALID_DEFAULT'` when the default no longer holds.
|
|
1113
|
+
* @internal
|
|
1114
|
+
*/
|
|
1115
|
+
function nextFlag(schema) {
|
|
1116
|
+
assertValidFlagDefinition(schema.kind, schema);
|
|
1117
|
+
assertValidFlagDefault(void 0, schema);
|
|
1118
|
+
return new FlagBuilder(schema);
|
|
1119
|
+
}
|
|
1120
|
+
/**
|
|
636
1121
|
* Flag schema factory. Call `flag.<kind>()` to create an immutable
|
|
637
1122
|
* {@link FlagBuilder} with full type inference and safe modifier chaining.
|
|
638
1123
|
*/
|
|
639
1124
|
const flag = {
|
|
640
1125
|
string(constraints) {
|
|
641
1126
|
if (constraints !== void 0) assertStringConstraints(constraints);
|
|
642
|
-
return new FlagBuilder(
|
|
1127
|
+
return new FlagBuilder(createFlagSchema("string", valueDefinitionFields(stringValue(constraints))));
|
|
643
1128
|
},
|
|
644
1129
|
number(constraints) {
|
|
645
1130
|
if (constraints !== void 0) assertNumberConstraints(constraints);
|
|
646
|
-
return new FlagBuilder(
|
|
1131
|
+
return new FlagBuilder(createFlagSchema("number", valueDefinitionFields(numberValue(constraints))));
|
|
647
1132
|
},
|
|
648
1133
|
boolean() {
|
|
649
|
-
return new FlagBuilder(
|
|
1134
|
+
return new FlagBuilder(createFlagSchema("boolean", {
|
|
650
1135
|
presence: "defaulted",
|
|
651
1136
|
defaultValue: false
|
|
652
1137
|
}));
|
|
653
1138
|
},
|
|
654
1139
|
enum(values) {
|
|
655
|
-
return new FlagBuilder(
|
|
1140
|
+
return new FlagBuilder(createFlagSchema("enum", { enumValues: values }));
|
|
656
1141
|
},
|
|
657
1142
|
array(element) {
|
|
658
|
-
|
|
1143
|
+
assertFlagElementBuilder("array", element);
|
|
1144
|
+
return new FlagBuilder(createFlagSchema("array", { elementSchema: element.schema }));
|
|
659
1145
|
},
|
|
660
1146
|
custom(parseFnOrSchema) {
|
|
661
|
-
if (isStandardSchemaV1(parseFnOrSchema)) return new FlagBuilder(
|
|
662
|
-
return new FlagBuilder(
|
|
1147
|
+
if (isStandardSchemaV1(parseFnOrSchema)) return new FlagBuilder(createFlagSchema("custom", valueDefinitionFields(standardValue(parseFnOrSchema))));
|
|
1148
|
+
return new FlagBuilder(createFlagSchema("custom", valueDefinitionFields(customValue(parseFnOrSchema))));
|
|
663
1149
|
},
|
|
664
1150
|
url(options) {
|
|
665
|
-
return new FlagBuilder(
|
|
666
|
-
parseFn: (raw) => parseUrlValue(raw, options),
|
|
667
|
-
valueHint: "url"
|
|
668
|
-
}));
|
|
1151
|
+
return new FlagBuilder(createFlagSchema("custom", valueDefinitionFields(urlValue(options))));
|
|
669
1152
|
},
|
|
670
1153
|
path(options) {
|
|
671
|
-
return new FlagBuilder(
|
|
672
|
-
pathChecks: options?.mustExist === true || options?.type !== void 0 ? {
|
|
673
|
-
mustExist: options.mustExist ?? true,
|
|
674
|
-
type: options.type,
|
|
675
|
-
create: options.type === "directory" && options.create === true
|
|
676
|
-
} : void 0,
|
|
677
|
-
valueHint: "path"
|
|
678
|
-
}));
|
|
1154
|
+
return new FlagBuilder(createFlagSchema("string", valueDefinitionFields(pathValue(options))));
|
|
679
1155
|
},
|
|
680
1156
|
date(options) {
|
|
681
|
-
return new FlagBuilder(
|
|
682
|
-
parseFn: (raw) => parseDateValue(raw, options),
|
|
683
|
-
valueHint: "date"
|
|
684
|
-
}));
|
|
1157
|
+
return new FlagBuilder(createFlagSchema("custom", valueDefinitionFields(dateValue(options))));
|
|
685
1158
|
},
|
|
686
1159
|
duration() {
|
|
687
|
-
return new FlagBuilder(
|
|
688
|
-
parseFn: parseDurationValue,
|
|
689
|
-
valueHint: "duration"
|
|
690
|
-
}));
|
|
1160
|
+
return new FlagBuilder(createFlagSchema("custom", valueDefinitionFields(durationValue())));
|
|
691
1161
|
},
|
|
692
1162
|
bytes() {
|
|
693
|
-
return new FlagBuilder(
|
|
694
|
-
parseFn: parseBytesValue,
|
|
695
|
-
valueHint: "size"
|
|
696
|
-
}));
|
|
1163
|
+
return new FlagBuilder(createFlagSchema("custom", valueDefinitionFields(bytesValue())));
|
|
697
1164
|
},
|
|
698
1165
|
count() {
|
|
699
|
-
return new FlagBuilder(
|
|
1166
|
+
return new FlagBuilder(createFlagSchema("count", {
|
|
700
1167
|
presence: "defaulted",
|
|
701
1168
|
defaultValue: 0
|
|
702
1169
|
}));
|
|
703
1170
|
},
|
|
704
|
-
keyValue() {
|
|
705
|
-
|
|
1171
|
+
keyValue(element) {
|
|
1172
|
+
if (element !== void 0) assertFlagElementBuilder("keyValue", element);
|
|
1173
|
+
return new FlagBuilder(createFlagSchema("keyValue", {
|
|
1174
|
+
valueHint: "key=value",
|
|
1175
|
+
...element !== void 0 ? { elementSchema: element.schema } : {}
|
|
1176
|
+
}));
|
|
706
1177
|
}
|
|
707
1178
|
};
|
|
1179
|
+
/**
|
|
1180
|
+
* Reject a collection factory handed something other than a flag builder.
|
|
1181
|
+
*
|
|
1182
|
+
* The types demand one, so this catches an untyped JavaScript caller before the
|
|
1183
|
+
* factory reads `.schema` off a value that has none.
|
|
1184
|
+
*
|
|
1185
|
+
* @param factory - Name of the factory being called.
|
|
1186
|
+
* @param element - What the caller passed as the element.
|
|
1187
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` when it is not a
|
|
1188
|
+
* {@link FlagBuilder}.
|
|
1189
|
+
* @internal
|
|
1190
|
+
*/
|
|
1191
|
+
function assertFlagElementBuilder(factory, element) {
|
|
1192
|
+
if (element instanceof FlagBuilder) {
|
|
1193
|
+
assertEligibleFlagElementBuilder(element.schema);
|
|
1194
|
+
return;
|
|
1195
|
+
}
|
|
1196
|
+
throw new CLIError(`flag.${factory}() requires an element builder`, {
|
|
1197
|
+
code: "INVALID_SCHEMA",
|
|
1198
|
+
details: {
|
|
1199
|
+
factory,
|
|
1200
|
+
field: "element",
|
|
1201
|
+
received: typeof element
|
|
1202
|
+
},
|
|
1203
|
+
suggest: `Pass an element builder, as in flag.${factory}(flag.string())`
|
|
1204
|
+
});
|
|
1205
|
+
}
|
|
708
1206
|
//#endregion
|
|
709
|
-
export { FlagBuilder,
|
|
1207
|
+
export { DUPLICATE_KEYS, FLAG_KINDS, FlagBuilder, SPLIT_FORMATS, createFlagSchema, flag, getFlagAliasNames, getFlagNegatedName, normalizeFlagAlias, normalizeFlagAliases };
|