@kjanat/dreamcli 3.0.1 → 4.0.0-rc.2
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 +962 -1
- package/README.md +7 -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 +173 -119
- 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 +30 -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 +12 -11
- package/skills/cli-creation/SKILL.md +72 -16
- package/skills/cli-creation/references/pattern-cookbook.md +169 -11
- package/dist/core/resolve/property.d.mts +0 -51
- package/dist/core/resolve/property.mjs +0 -53
|
@@ -1,44 +1,290 @@
|
|
|
1
1
|
import { CLIError } from "../errors/index.mjs";
|
|
2
|
-
import { getFlagNegatedName } from "./flag.mjs";
|
|
2
|
+
import { createFlagSchema, getFlagNegatedName } from "./flag.mjs";
|
|
3
|
+
import { createArgSchema } from "./arg.mjs";
|
|
4
|
+
import { stdinConsumerReference, stdinConsumers } from "./source.mjs";
|
|
3
5
|
//#region src/core/schema/command.ts
|
|
4
6
|
/** Resolve an {@link ExampleCommand} to its string form for the given meta. */
|
|
5
7
|
function resolveExampleCommand(command, meta) {
|
|
6
8
|
return typeof command === "function" ? command(meta) : command;
|
|
7
9
|
}
|
|
8
10
|
/**
|
|
11
|
+
* Reject a flag name a plain record cannot carry.
|
|
12
|
+
*
|
|
13
|
+
* Assigning `__proto__` on an object literal sets the prototype instead of an
|
|
14
|
+
* entry, so both construction paths refuse the key rather than let the flag
|
|
15
|
+
* vanish.
|
|
16
|
+
*
|
|
17
|
+
* @param commandName - Command the flag was declared on, for the error details.
|
|
18
|
+
* @param name - Proposed flag name.
|
|
19
|
+
* @throws {@link CLIError} `INVALID_SCHEMA` when the name is `__proto__`.
|
|
20
|
+
*
|
|
21
|
+
* @internal
|
|
22
|
+
*/
|
|
23
|
+
function assertUsableFlagKey(commandName, name) {
|
|
24
|
+
if (name !== "__proto__") return;
|
|
25
|
+
throw new CLIError("Flag name '__proto__' is not usable as a flag", {
|
|
26
|
+
code: "INVALID_SCHEMA",
|
|
27
|
+
details: {
|
|
28
|
+
command: commandName,
|
|
29
|
+
flag: "__proto__"
|
|
30
|
+
},
|
|
31
|
+
suggest: "Rename the flag, for example to \"proto\""
|
|
32
|
+
});
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* Reject a flag record whose entries a name check cannot reach.
|
|
36
|
+
*
|
|
37
|
+
* Only own enumerable keys are read. An object literal routes a bare
|
|
38
|
+
* `__proto__` key to the prototype setter, and a record built over another
|
|
39
|
+
* object hides its inherited entries, so in both cases a declared flag is
|
|
40
|
+
* already gone by the time {@link assertUsableFlagKey} sees a name. The
|
|
41
|
+
* replaced prototype is the evidence common to both. `Object.prototype` and
|
|
42
|
+
* `null` (an `Object.create(null)` record) carry no entries of their own and
|
|
43
|
+
* pass.
|
|
44
|
+
*
|
|
45
|
+
* @param commandName - Command the flags were declared on, for the error details.
|
|
46
|
+
* @param flags - Flag record as the caller supplied it.
|
|
47
|
+
* @throws {@link CLIError} `INVALID_SCHEMA` when the record's prototype is
|
|
48
|
+
* replaced.
|
|
49
|
+
*
|
|
50
|
+
* @internal
|
|
51
|
+
*/
|
|
52
|
+
function assertUsableFlagRecord(commandName, flags) {
|
|
53
|
+
const prototype = Object.getPrototypeOf(flags);
|
|
54
|
+
if (prototype === Object.prototype || prototype === null) return;
|
|
55
|
+
throw new CLIError(`Command '${commandName}' flag record has a replaced prototype. A '__proto__' key sets the prototype instead of adding a flag, and an inherited flag is never read`, {
|
|
56
|
+
code: "INVALID_SCHEMA",
|
|
57
|
+
details: { command: commandName },
|
|
58
|
+
suggest: "Pass a plain object with no '__proto__' key, or a record built with Object.create(null)"
|
|
59
|
+
});
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* Reject an arg name a plain record cannot carry.
|
|
63
|
+
*
|
|
64
|
+
* Resolved args reach the handler as a record keyed by arg name, and the parser
|
|
65
|
+
* accumulates positionals into one, so `__proto__` would swallow the value the
|
|
66
|
+
* user typed and hand the handler the prototype instead.
|
|
67
|
+
*
|
|
68
|
+
* @param commandName - Command the arg was declared on, for the error details.
|
|
69
|
+
* @param name - Proposed arg name.
|
|
70
|
+
* @throws {@link CLIError} `INVALID_SCHEMA` when the name is `__proto__`.
|
|
71
|
+
*
|
|
72
|
+
* @internal
|
|
73
|
+
*/
|
|
74
|
+
function assertUsableArgKey(commandName, name) {
|
|
75
|
+
if (name !== "__proto__") return;
|
|
76
|
+
throw new CLIError(`Argument name '${name}' is not usable as an argument`, {
|
|
77
|
+
code: "INVALID_SCHEMA",
|
|
78
|
+
details: {
|
|
79
|
+
command: commandName,
|
|
80
|
+
arg: name
|
|
81
|
+
},
|
|
82
|
+
suggest: "Rename the argument, for example to \"proto\""
|
|
83
|
+
});
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* Merge definition fields onto the {@link CommandSchema} defaults, recursively.
|
|
87
|
+
*
|
|
88
|
+
* @param definition - Command definition to normalize.
|
|
89
|
+
* @returns A fully populated {@link CommandSchema}.
|
|
90
|
+
* @throws {@link CLIError} `INVALID_SCHEMA` when a name at any depth is empty
|
|
91
|
+
* or contains whitespace, a flag or arg is named `__proto__` at any depth,
|
|
92
|
+
* or a flag record at any depth has a replaced prototype.
|
|
93
|
+
* @throws {@link CLIError} `INVALID_BUILDER_STATE` or `DUPLICATE_STDIN_INPUT` when
|
|
94
|
+
* an input breaks the positional-order or stdin invariants.
|
|
95
|
+
*
|
|
96
|
+
* @internal
|
|
97
|
+
*/
|
|
98
|
+
function buildCommandSchema(definition) {
|
|
99
|
+
if (definition.name === "" || /\s/u.test(definition.name)) throw new CLIError("Command schema requires a non-empty name without whitespace", {
|
|
100
|
+
code: "INVALID_SCHEMA",
|
|
101
|
+
details: { name: definition.name },
|
|
102
|
+
suggest: "Pass a dispatch name such as { name: \"deploy\" }"
|
|
103
|
+
});
|
|
104
|
+
const flagDefinitions = definition.flags ?? {};
|
|
105
|
+
assertUsableFlagRecord(definition.name, flagDefinitions);
|
|
106
|
+
const flags = {};
|
|
107
|
+
for (const [name, value] of Object.entries(flagDefinitions)) {
|
|
108
|
+
assertUsableFlagKey(definition.name, name);
|
|
109
|
+
const flagSchema = createFlagSchema(value);
|
|
110
|
+
validateFlagStdinEntry(definition.name, name, flagSchema, flags, []);
|
|
111
|
+
flags[name] = flagSchema;
|
|
112
|
+
}
|
|
113
|
+
const args = [];
|
|
114
|
+
for (const entry of definition.args ?? []) {
|
|
115
|
+
const schema = createArgSchema(entry.schema);
|
|
116
|
+
validateArgEntry(definition.name, entry.name, schema, flags, args);
|
|
117
|
+
args.push({
|
|
118
|
+
name: entry.name,
|
|
119
|
+
schema
|
|
120
|
+
});
|
|
121
|
+
}
|
|
122
|
+
return {
|
|
123
|
+
name: definition.name,
|
|
124
|
+
description: definition.description,
|
|
125
|
+
aliases: definition.aliases ?? [],
|
|
126
|
+
hidden: definition.hidden ?? false,
|
|
127
|
+
examples: definition.examples ?? [],
|
|
128
|
+
flags,
|
|
129
|
+
args,
|
|
130
|
+
hasAction: definition.hasAction ?? false,
|
|
131
|
+
interactive: definition.interactive,
|
|
132
|
+
commands: (definition.commands ?? []).map((child) => buildCommandSchema(child))
|
|
133
|
+
};
|
|
134
|
+
}
|
|
135
|
+
/**
|
|
136
|
+
* Create a {@link CommandSchema} from a plain definition object.
|
|
137
|
+
*
|
|
138
|
+
* Most consumers should prefer {@link command | command()}, which returns a
|
|
139
|
+
* {@link CommandBuilder} with type inference. `createCommandSchema()` is the
|
|
140
|
+
* low-level escape hatch for tooling that composes schemas as data.
|
|
141
|
+
*
|
|
142
|
+
* Flags, args, and subcommands are normalized recursively, so an already-built
|
|
143
|
+
* schema fed back in produces a deep-equal schema.
|
|
144
|
+
*
|
|
145
|
+
* Flag spellings are checked across the whole tree, so a definition whose names,
|
|
146
|
+
* aliases, or negated spellings collide with each other or with a propagated
|
|
147
|
+
* ancestor flag is rejected here. Both flags still parse under their canonical
|
|
148
|
+
* names, so what a collision costs is the shared spelling. Help advertises it on
|
|
149
|
+
* both flags and the parser answers it with one of them.
|
|
150
|
+
* Args go through the same invariants {@link CommandBuilder.arg} enforces.
|
|
151
|
+
* These are the checks the {@link CommandBuilder} applies as flags, args, and
|
|
152
|
+
* subcommands are registered.
|
|
153
|
+
*
|
|
154
|
+
* @param definition - Command name plus optional flags, args, and subcommands.
|
|
155
|
+
* @returns A fully populated {@link CommandSchema}.
|
|
156
|
+
* @throws {CLIError} With code `'INVALID_SCHEMA'` when a name at any depth is
|
|
157
|
+
* empty or contains whitespace, a flag or arg at any depth is named
|
|
158
|
+
* `__proto__`, which JavaScript cannot carry as a plain record key, or a flag
|
|
159
|
+
* record at any depth has a
|
|
160
|
+
* replaced prototype, which hides the entries a name check would read.
|
|
161
|
+
* @throws {CLIError} With code `'FLAG_NAME_COLLISION'` when two flags on one
|
|
162
|
+
* command share a spelling.
|
|
163
|
+
* @throws {CLIError} With code `'PROPAGATED_FLAG_COLLISION'` when a flag shadows
|
|
164
|
+
* a spelling propagated from an ancestor command.
|
|
165
|
+
* @throws {CLIError} With code `'INVALID_BUILDER_STATE'` when a positional comes
|
|
166
|
+
* after a variadic one, or `'DUPLICATE_STDIN_INPUT'` when two inputs on one
|
|
167
|
+
* command consume stdin and either is exclusive.
|
|
168
|
+
*
|
|
169
|
+
* @example
|
|
170
|
+
* ```ts
|
|
171
|
+
* const schema = createCommandSchema({
|
|
172
|
+
* name: 'deploy',
|
|
173
|
+
* description: 'Ship the build',
|
|
174
|
+
* flags: { force: { kind: 'boolean' } },
|
|
175
|
+
* args: [{ name: 'target', schema: { kind: 'string' } }],
|
|
176
|
+
* });
|
|
177
|
+
* ```
|
|
178
|
+
*/
|
|
179
|
+
function createCommandSchema(definition) {
|
|
180
|
+
const schema = buildCommandSchema(definition);
|
|
181
|
+
validateCommandFlagTree(schema);
|
|
182
|
+
return schema;
|
|
183
|
+
}
|
|
184
|
+
/**
|
|
9
185
|
* Validate a new arg entry against invariants before adding it to the command.
|
|
10
186
|
*
|
|
187
|
+
* @param commandName - Command the arg was declared on. A definition tree reaches
|
|
188
|
+
* here at any depth, so every error carries it in `details`.
|
|
11
189
|
* @param name - Arg name being registered.
|
|
12
190
|
* @param schema - Runtime descriptor of the arg.
|
|
191
|
+
* @param flags - Already-registered flag schemas on this command.
|
|
13
192
|
* @param args - Already-registered arg entries on this command.
|
|
14
193
|
*
|
|
15
|
-
* @throws {@link CLIError} `
|
|
16
|
-
* @throws {@link CLIError} `
|
|
194
|
+
* @throws {@link CLIError} `INVALID_SCHEMA` if the name is `__proto__`.
|
|
195
|
+
* @throws {@link CLIError} `INVALID_BUILDER_STATE` if an earlier arg is variadic.
|
|
196
|
+
* @throws {@link CLIError} `DUPLICATE_STDIN_INPUT` if another input already consumes stdin exclusively.
|
|
17
197
|
*
|
|
18
198
|
* @internal
|
|
19
199
|
*/
|
|
20
|
-
function validateArgEntry(name, schema, args) {
|
|
21
|
-
|
|
200
|
+
function validateArgEntry(commandName, name, schema, flags, args) {
|
|
201
|
+
assertUsableArgKey(commandName, name);
|
|
202
|
+
assertVariadicIsLast(commandName, name, args);
|
|
203
|
+
assertStdinExclusivity(commandName, {
|
|
204
|
+
kind: "arg",
|
|
205
|
+
name,
|
|
206
|
+
stdin: schema.stdin
|
|
207
|
+
}, flags, args);
|
|
208
|
+
}
|
|
209
|
+
/**
|
|
210
|
+
* Reject a positional declared after one that consumes the whole tail.
|
|
211
|
+
*
|
|
212
|
+
* A variadic arg takes every remaining positional, so anything registered after
|
|
213
|
+
* it can never be filled, and a second variadic arg has nothing left to collect.
|
|
214
|
+
*
|
|
215
|
+
* @param commandName - Command the arg was declared on.
|
|
216
|
+
* @param name - Arg name being registered.
|
|
217
|
+
* @param args - Already-registered arg entries on this command.
|
|
218
|
+
* @throws {@link CLIError} `INVALID_BUILDER_STATE` when an earlier arg is variadic.
|
|
219
|
+
*
|
|
220
|
+
* @internal
|
|
221
|
+
*/
|
|
222
|
+
function assertVariadicIsLast(commandName, name, args) {
|
|
223
|
+
const greedy = args.find((entry) => entry.schema.variadic);
|
|
224
|
+
if (greedy === void 0) return;
|
|
225
|
+
throw new CLIError(`Argument <${name}> comes after variadic argument <${greedy.name}>, which consumes every remaining positional`, {
|
|
22
226
|
code: "INVALID_BUILDER_STATE",
|
|
23
227
|
details: {
|
|
228
|
+
command: commandName,
|
|
24
229
|
arg: name,
|
|
25
|
-
|
|
26
|
-
variadic: true
|
|
27
|
-
},
|
|
28
|
-
suggest: "Remove .stdin() or .variadic() from this argument"
|
|
29
|
-
});
|
|
30
|
-
if (!schema.stdinMode) return;
|
|
31
|
-
const existing = args.find((entry) => entry.schema.stdinMode);
|
|
32
|
-
if (existing === void 0) return;
|
|
33
|
-
throw new CLIError(`Only one stdin argument is allowed; <${existing.name}> is already stdin-backed`, {
|
|
34
|
-
code: "DUPLICATE_STDIN_ARG",
|
|
35
|
-
details: {
|
|
36
|
-
arg: name,
|
|
37
|
-
existingArg: existing.name
|
|
230
|
+
variadicArg: greedy.name
|
|
38
231
|
},
|
|
39
|
-
suggest:
|
|
232
|
+
suggest: `Declare <${name}> before <${greedy.name}>, or drop .variadic() from <${greedy.name}>`
|
|
40
233
|
});
|
|
41
234
|
}
|
|
235
|
+
/**
|
|
236
|
+
* Reject a second stdin consumer when either it or an existing one is exclusive.
|
|
237
|
+
*
|
|
238
|
+
* One command reads stdin once, so an exclusive consumer must be the only one.
|
|
239
|
+
* Several `{ consume: 'broadcast' }` inputs coexist and all receive the same
|
|
240
|
+
* buffer. The rule spans both surfaces, so a flag and an arg conflict with each
|
|
241
|
+
* other exactly as two args do.
|
|
242
|
+
*
|
|
243
|
+
* @param commandName - Command the input was declared on.
|
|
244
|
+
* @param candidate - The input being registered.
|
|
245
|
+
* @param flags - Already-registered flag schemas on this command.
|
|
246
|
+
* @param args - Already-registered arg entries on this command.
|
|
247
|
+
* @throws {@link CLIError} `DUPLICATE_STDIN_INPUT` on a conflict.
|
|
248
|
+
*
|
|
249
|
+
* @internal
|
|
250
|
+
*/
|
|
251
|
+
function assertStdinExclusivity(commandName, candidate, flags, args) {
|
|
252
|
+
const stdin = candidate.stdin;
|
|
253
|
+
if (stdin === void 0) return;
|
|
254
|
+
for (const existing of stdinConsumers(flags, args)) {
|
|
255
|
+
if (existing.kind === candidate.kind && existing.name === candidate.name) continue;
|
|
256
|
+
if (stdin.consume === "broadcast" && existing.stdin.consume === "broadcast") continue;
|
|
257
|
+
throw new CLIError(`Only one input may consume stdin exclusively; ${stdinConsumerReference(existing)} already consumes stdin`, {
|
|
258
|
+
code: "DUPLICATE_STDIN_INPUT",
|
|
259
|
+
details: {
|
|
260
|
+
command: commandName,
|
|
261
|
+
...candidate.kind === "flag" ? { flag: candidate.name } : { arg: candidate.name },
|
|
262
|
+
...existing.kind === "flag" ? { existingFlag: existing.name } : { existingArg: existing.name }
|
|
263
|
+
},
|
|
264
|
+
suggest: "Keep .stdin() on a single input per command, or declare every stdin input with { consume: 'broadcast' }"
|
|
265
|
+
});
|
|
266
|
+
}
|
|
267
|
+
}
|
|
268
|
+
/**
|
|
269
|
+
* Validate a new flag against the stdin invariants before adding it.
|
|
270
|
+
*
|
|
271
|
+
* @param commandName - Command the flag was declared on.
|
|
272
|
+
* @param name - Flag name being registered.
|
|
273
|
+
* @param schema - Runtime descriptor of the flag.
|
|
274
|
+
* @param flags - Already-registered flag schemas on this command.
|
|
275
|
+
* @param args - Already-registered arg entries on this command.
|
|
276
|
+
* @throws {@link CLIError} `DUPLICATE_STDIN_INPUT` when another input already
|
|
277
|
+
* consumes stdin exclusively.
|
|
278
|
+
*
|
|
279
|
+
* @internal
|
|
280
|
+
*/
|
|
281
|
+
function validateFlagStdinEntry(commandName, name, schema, flags, args) {
|
|
282
|
+
assertStdinExclusivity(commandName, {
|
|
283
|
+
kind: "flag",
|
|
284
|
+
name,
|
|
285
|
+
stdin: schema.stdin
|
|
286
|
+
}, flags, args);
|
|
287
|
+
}
|
|
42
288
|
function formatFlagToken(name, kind) {
|
|
43
289
|
return kind === "alias" && name.length === 1 ? `-${name}` : `--${name}`;
|
|
44
290
|
}
|
|
@@ -113,11 +359,25 @@ function buildInheritedFlagsForChildren(inherited, local) {
|
|
|
113
359
|
for (const [name, schema] of Object.entries(local)) if (schema.propagate) next[name] = schema;
|
|
114
360
|
return next;
|
|
115
361
|
}
|
|
362
|
+
/**
|
|
363
|
+
* Reject a command whose flags collide on any spelling, walking subcommands.
|
|
364
|
+
*
|
|
365
|
+
* @param command - Command schema to validate.
|
|
366
|
+
* @param inheritedFlags - Propagated ancestor flags visible at this level.
|
|
367
|
+
* @throws {@link CLIError} `FLAG_NAME_COLLISION` or `PROPAGATED_FLAG_COLLISION`.
|
|
368
|
+
*
|
|
369
|
+
* @internal
|
|
370
|
+
*/
|
|
116
371
|
function validateCommandFlagTree(command, inheritedFlags = {}) {
|
|
117
372
|
validateLocalFlagCollisions(command.name, command.flags);
|
|
118
373
|
const visibleInherited = { ...inheritedFlags };
|
|
119
374
|
for (const name of Object.keys(command.flags)) delete visibleInherited[name];
|
|
120
375
|
validateInheritedFlagCollisions(command.name, visibleInherited, command.flags);
|
|
376
|
+
const effectiveFlags = {
|
|
377
|
+
...visibleInherited,
|
|
378
|
+
...command.flags
|
|
379
|
+
};
|
|
380
|
+
for (const [name, schema] of Object.entries(effectiveFlags)) validateFlagStdinEntry(command.name, name, schema, effectiveFlags, command.args);
|
|
121
381
|
const inheritedForChildren = buildInheritedFlagsForChildren(inheritedFlags, command.flags);
|
|
122
382
|
for (const child of command.commands) validateCommandFlagTree(child, inheritedForChildren);
|
|
123
383
|
}
|
|
@@ -166,16 +426,14 @@ var CommandBuilder = class CommandBuilder {
|
|
|
166
426
|
* @internal Nested sub-command builders (type-erased for heterogeneous storage).
|
|
167
427
|
*
|
|
168
428
|
* Stored separately from `schema.commands` because builders carry action
|
|
169
|
-
* handlers and phantom types needed by `
|
|
429
|
+
* handlers and phantom types needed by `compileCommand()` in the CLI layer.
|
|
170
430
|
* `schema.commands` holds pure `CommandSchema[]` for help/completion.
|
|
171
431
|
*/
|
|
172
432
|
_subcommands;
|
|
173
433
|
/**
|
|
174
|
-
* @internal
|
|
434
|
+
* @internal Derive and middleware steps in registration order.
|
|
175
435
|
*
|
|
176
|
-
*
|
|
177
|
-
* for backward compatibility, while derives stay command-local and builder-
|
|
178
|
-
* scoped so future shared/global middleware can compose cleanly.
|
|
436
|
+
* The executor builds the handler chain from this list.
|
|
179
437
|
*/
|
|
180
438
|
_executionSteps;
|
|
181
439
|
/**
|
|
@@ -338,7 +596,6 @@ var CommandBuilder = class CommandBuilder {
|
|
|
338
596
|
middleware(m) {
|
|
339
597
|
return new CommandBuilder({
|
|
340
598
|
...this.schema,
|
|
341
|
-
middleware: [...this.schema.middleware, m._handler],
|
|
342
599
|
hasAction: false
|
|
343
600
|
}, void 0, this._subcommands, [...this._executionSteps, {
|
|
344
601
|
kind: "middleware",
|
|
@@ -513,9 +770,17 @@ var CommandBuilder = class CommandBuilder {
|
|
|
513
770
|
* ```
|
|
514
771
|
*
|
|
515
772
|
* @returns The builder (for chaining).
|
|
773
|
+
* @throws {@link CLIError} `INVALID_SCHEMA` when the name is `__proto__`,
|
|
774
|
+
* which a plain record cannot carry.
|
|
775
|
+
* @throws {@link CLIError} `FLAG_NAME_COLLISION` when the command already
|
|
776
|
+
* declares this name, or the new flag's spellings collide with another
|
|
777
|
+
* flag's.
|
|
778
|
+
* @throws {@link CLIError} `PROPAGATED_FLAG_COLLISION` when a spelling
|
|
779
|
+
* collides with one propagated to a registered subcommand.
|
|
516
780
|
*/
|
|
517
781
|
flag(name, builder) {
|
|
518
|
-
|
|
782
|
+
assertUsableFlagKey(this.schema.name, name);
|
|
783
|
+
if (Object.hasOwn(this.schema.flags, name)) throw new CLIError(`Command '${this.schema.name}' already defines flag --${name}`, {
|
|
519
784
|
code: "FLAG_NAME_COLLISION",
|
|
520
785
|
details: {
|
|
521
786
|
command: this.schema.name,
|
|
@@ -524,6 +789,7 @@ var CommandBuilder = class CommandBuilder {
|
|
|
524
789
|
surfaceKind: "canonical"
|
|
525
790
|
}
|
|
526
791
|
});
|
|
792
|
+
validateFlagStdinEntry(this.schema.name, name, builder.schema, this.schema.flags, this.schema.args);
|
|
527
793
|
const nextFlags = {
|
|
528
794
|
...this.schema.flags,
|
|
529
795
|
[name]: builder.schema
|
|
@@ -574,9 +840,15 @@ var CommandBuilder = class CommandBuilder {
|
|
|
574
840
|
* ```
|
|
575
841
|
*
|
|
576
842
|
* @returns The builder (for chaining).
|
|
843
|
+
* @throws {@link CLIError} `INVALID_SCHEMA` when the name is `__proto__`,
|
|
844
|
+
* which a plain record cannot carry.
|
|
845
|
+
* @throws {@link CLIError} `INVALID_BUILDER_STATE` when an earlier arg on this
|
|
846
|
+
* command is variadic, so this one could never be filled.
|
|
847
|
+
* @throws {@link CLIError} `DUPLICATE_STDIN_INPUT` when another input on this
|
|
848
|
+
* command already consumes stdin exclusively.
|
|
577
849
|
*/
|
|
578
850
|
arg(name, builder) {
|
|
579
|
-
validateArgEntry(name, builder.schema, this.schema.args);
|
|
851
|
+
validateArgEntry(this.schema.name, name, builder.schema, this.schema.flags, this.schema.args);
|
|
580
852
|
const entry = {
|
|
581
853
|
name,
|
|
582
854
|
schema: builder.schema
|
|
@@ -592,7 +864,7 @@ var CommandBuilder = class CommandBuilder {
|
|
|
592
864
|
* Register a nested subcommand on this command.
|
|
593
865
|
*
|
|
594
866
|
* The subcommand's builder is stored in `_subcommands` for the CLI layer's
|
|
595
|
-
* `
|
|
867
|
+
* `compileCommand()` to traverse when building the execution graph. The
|
|
596
868
|
* subcommand's `CommandSchema` is also appended to `schema.commands` for
|
|
597
869
|
* help rendering and completion generation.
|
|
598
870
|
*
|
|
@@ -610,6 +882,9 @@ var CommandBuilder = class CommandBuilder {
|
|
|
610
882
|
*
|
|
611
883
|
* @param sub - Child {@link CommandBuilder} to nest under this command.
|
|
612
884
|
* @returns The builder (for chaining).
|
|
885
|
+
* @throws {@link CLIError} `PROPAGATED_FLAG_COLLISION` when a spelling this
|
|
886
|
+
* command propagates collides with one the subcommand, or any of its own
|
|
887
|
+
* descendants, declares.
|
|
613
888
|
*/
|
|
614
889
|
command(sub) {
|
|
615
890
|
const nextSchema = {
|
|
@@ -693,19 +968,7 @@ var CommandBuilder = class CommandBuilder {
|
|
|
693
968
|
* @returns A fresh {@link CommandBuilder} with empty flags, args, and context.
|
|
694
969
|
*/
|
|
695
970
|
function command(name) {
|
|
696
|
-
return new CommandBuilder({
|
|
697
|
-
name,
|
|
698
|
-
description: void 0,
|
|
699
|
-
aliases: [],
|
|
700
|
-
hidden: false,
|
|
701
|
-
examples: [],
|
|
702
|
-
flags: {},
|
|
703
|
-
args: [],
|
|
704
|
-
hasAction: false,
|
|
705
|
-
interactive: void 0,
|
|
706
|
-
middleware: [],
|
|
707
|
-
commands: []
|
|
708
|
-
});
|
|
971
|
+
return new CommandBuilder(createCommandSchema({ name }));
|
|
709
972
|
}
|
|
710
973
|
/**
|
|
711
974
|
* Create a command builder intended for use as a command group.
|
|
@@ -733,4 +996,4 @@ function group(name) {
|
|
|
733
996
|
return command(name);
|
|
734
997
|
}
|
|
735
998
|
//#endregion
|
|
736
|
-
export { CommandBuilder, command, group, resolveExampleCommand };
|
|
999
|
+
export { CommandBuilder, command, createCommandSchema, group, resolveExampleCommand };
|