@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,61 +1,28 @@
|
|
|
1
1
|
import { OutputPolicy } from "../output/contracts.mjs";
|
|
2
|
-
import {
|
|
2
|
+
import { CommandMeta, CommandSchema } from "../schema/command.mjs";
|
|
3
3
|
import { CLIError } from "../errors/index.mjs";
|
|
4
4
|
import { HelpOptions } from "../help/index.mjs";
|
|
5
|
-
import {
|
|
6
|
-
import {
|
|
7
|
-
import { CompletionOptions } from "../completion/shells/shared.mjs";
|
|
8
|
-
import { Shell } from "../completion/index.mjs";
|
|
5
|
+
import { CLIPlugin } from "./plugin.mjs";
|
|
6
|
+
import { CompiledCommand } from "./compiled.mjs";
|
|
9
7
|
//#region src/core/cli/planner.d.ts
|
|
10
|
-
/**
|
|
11
|
-
* Structural subset of CLISchema used by the planner.
|
|
12
|
-
*
|
|
13
|
-
* Decouples invocation planning from the full CLIBuilder surface so the
|
|
14
|
-
* planner can be tested and reasoned about without constructing a real CLI.
|
|
15
|
-
* @internal
|
|
16
|
-
*/
|
|
17
|
-
interface PlannerSchemaLike {
|
|
18
|
-
/** CLI program name used in help text and error messages. */
|
|
19
|
-
readonly name: string;
|
|
20
|
-
/** Declared version string; `undefined` disables `--version` interception. */
|
|
21
|
-
readonly version: string | undefined;
|
|
22
|
-
/** Registered top-level commands available for dispatch. */
|
|
23
|
-
readonly commands: readonly ErasedCommand[];
|
|
24
|
-
/** Fallback command when no subcommand token matches. */
|
|
25
|
-
readonly defaultCommand: ErasedCommand | undefined;
|
|
26
|
-
/** Whether the default command is also exposed as a named top-level route. */
|
|
27
|
-
readonly defaultCommandRouted: boolean;
|
|
28
|
-
/**
|
|
29
|
-
* Eager `--completions <shell>` flag configuration, when `.completions()`
|
|
30
|
-
* was registered with `{ as: 'flag' }`. `undefined` disables interception.
|
|
31
|
-
*/
|
|
32
|
-
readonly completionsFlag: {
|
|
33
|
-
readonly shells: readonly Shell[];
|
|
34
|
-
readonly options: CompletionOptions | undefined;
|
|
35
|
-
} | undefined;
|
|
36
|
-
/** Flag-parsing behavior settings (case parity) applied to flag lookups. */
|
|
37
|
-
readonly flagSettings?: ParseOptions | undefined;
|
|
38
|
-
/** Plugins forwarded into every matched execution plan. */
|
|
39
|
-
readonly plugins: readonly CLIPlugin[];
|
|
40
|
-
}
|
|
41
8
|
/** Root-level help interception outcome. */
|
|
42
9
|
interface RootHelpOutcome {
|
|
43
10
|
/** Discriminant — argv matched `--help` / `-h` before any command. */
|
|
44
|
-
readonly kind:
|
|
11
|
+
readonly kind: "root-help";
|
|
45
12
|
/** Help options to render root-level usage. */
|
|
46
13
|
readonly help: HelpOptions;
|
|
47
14
|
}
|
|
48
15
|
/** Root-level version interception outcome. */
|
|
49
16
|
interface RootVersionOutcome {
|
|
50
17
|
/** Discriminant — argv matched `--version` / `-V` and schema declares a version. */
|
|
51
|
-
readonly kind:
|
|
18
|
+
readonly kind: "root-version";
|
|
52
19
|
/** Resolved version string to render. */
|
|
53
20
|
readonly version: string;
|
|
54
21
|
}
|
|
55
22
|
/** Root-level `--completions [shell]` interception outcome. */
|
|
56
23
|
interface RootCompletionsOutcome {
|
|
57
24
|
/** Discriminant — argv matched the eager `--completions [shell]` flag. */
|
|
58
|
-
readonly kind:
|
|
25
|
+
readonly kind: "root-completions";
|
|
59
26
|
/**
|
|
60
27
|
* Resolved, validated target shell, or `undefined` when the flag was given
|
|
61
28
|
* without a value and the shell should be auto-detected from the environment.
|
|
@@ -67,14 +34,14 @@ interface RootCompletionsOutcome {
|
|
|
67
34
|
/** CLI-level dispatch failure before command execution starts. */
|
|
68
35
|
interface DispatchErrorOutcome {
|
|
69
36
|
/** Discriminant — dispatch could not resolve a command from argv. */
|
|
70
|
-
readonly kind:
|
|
37
|
+
readonly kind: "dispatch-error";
|
|
71
38
|
/** Structured error with suggestion text for the caller to render. */
|
|
72
39
|
readonly error: CLIError;
|
|
73
40
|
}
|
|
74
41
|
/** Successful planner handoff to the shared command execution path. */
|
|
75
42
|
interface PlannerMatchOutcome {
|
|
76
43
|
/** Discriminant — dispatch found a matching command for argv. */
|
|
77
|
-
readonly kind:
|
|
44
|
+
readonly kind: "match";
|
|
78
45
|
/** Fully resolved execution plan ready for the executor pipeline. */
|
|
79
46
|
readonly plan: CommandExecutionPlan;
|
|
80
47
|
}
|
|
@@ -92,8 +59,8 @@ type DispatchOutcome = RootHelpOutcome | RootVersionOutcome | RootCompletionsOut
|
|
|
92
59
|
* propagated ancestor flags are collected and child definitions shadow them.
|
|
93
60
|
*/
|
|
94
61
|
interface CommandExecutionPlan {
|
|
95
|
-
/**
|
|
96
|
-
readonly command:
|
|
62
|
+
/** Compiled command node that owns the handler and execution steps. */
|
|
63
|
+
readonly command: CompiledCommand;
|
|
97
64
|
/** Command schema with propagated ancestor flags merged in. */
|
|
98
65
|
readonly mergedSchema: CommandSchema;
|
|
99
66
|
/** Remaining argv tokens after command dispatch consumed the command path. */
|
|
@@ -108,7 +75,7 @@ interface CommandExecutionPlan {
|
|
|
108
75
|
readonly help: HelpOptions | undefined;
|
|
109
76
|
}
|
|
110
77
|
interface BuildCommandExecutionPlanOptions {
|
|
111
|
-
readonly command:
|
|
78
|
+
readonly command: CompiledCommand;
|
|
112
79
|
readonly commandPath: readonly CommandSchema[];
|
|
113
80
|
readonly argv: readonly string[];
|
|
114
81
|
readonly meta: CommandMeta;
|
|
@@ -116,54 +83,14 @@ interface BuildCommandExecutionPlanOptions {
|
|
|
116
83
|
readonly output: OutputPolicy;
|
|
117
84
|
readonly help: HelpOptions | undefined;
|
|
118
85
|
}
|
|
119
|
-
/**
|
|
120
|
-
* Dispatch resolved a group command that requires a subcommand selection.
|
|
121
|
-
*
|
|
122
|
-
* The caller should render subcommand-level help for the matched group.
|
|
123
|
-
* @internal
|
|
124
|
-
*/
|
|
125
|
-
interface NeedsSubcommandOutcome {
|
|
126
|
-
/** Discriminant — group command matched but no leaf subcommand was selected. */
|
|
127
|
-
readonly kind: 'needs-subcommand';
|
|
128
|
-
/** The group command that was matched. */
|
|
129
|
-
readonly command: ErasedCommand;
|
|
130
|
-
/** Full ancestor path from root to this group, used for propagated flag collection. */
|
|
131
|
-
readonly commandPath: readonly CommandSchema[];
|
|
132
|
-
/** Help options scoped to the group command's bin path. */
|
|
133
|
-
readonly help: HelpOptions;
|
|
134
|
-
}
|
|
135
|
-
/** Full planner result including the `needs-subcommand` variant used by CLIBuilder. @internal */
|
|
136
|
-
type InvocationPlan = DispatchOutcome | NeedsSubcommandOutcome;
|
|
137
|
-
/** Options bag for {@linkcode planInvocation}. @internal */
|
|
138
|
-
interface PlanInvocationOptions {
|
|
139
|
-
/** CLI schema subset driving dispatch decisions. */
|
|
140
|
-
readonly schema: PlannerSchemaLike;
|
|
141
|
-
/** Raw argv tokens (typically `adapter.argv.slice(2)`). */
|
|
142
|
-
readonly argv: readonly string[];
|
|
143
|
-
/** Root-level help configuration for rendering. */
|
|
144
|
-
readonly help: HelpOptions;
|
|
145
|
-
/** Output policy propagated into matched execution plans. */
|
|
146
|
-
readonly output: OutputPolicy;
|
|
147
|
-
}
|
|
148
|
-
/** Build a name+alias lookup map for top-level commands. @internal */
|
|
149
|
-
declare function buildRootCommandMap(commands: readonly ErasedCommand[]): ReadonlyMap<string, ErasedCommand>;
|
|
150
86
|
/**
|
|
151
87
|
* Merge propagated ancestor flags into the matched command schema.
|
|
152
88
|
*
|
|
153
89
|
* Child flag definitions win when names collide, matching current CLI
|
|
154
90
|
* dispatch semantics and the future planner contract.
|
|
155
91
|
*/
|
|
156
|
-
declare function mergeCommandSchema(command:
|
|
92
|
+
declare function mergeCommandSchema(command: CompiledCommand, commandPath: readonly CommandSchema[]): CommandSchema;
|
|
157
93
|
/** Build the planner handoff for a matched command invocation. */
|
|
158
94
|
declare function buildCommandExecutionPlan(options: BuildCommandExecutionPlanOptions): CommandExecutionPlan;
|
|
159
|
-
/**
|
|
160
|
-
* Decide what to do with an argv invocation before any command executes.
|
|
161
|
-
*
|
|
162
|
-
* Handles root interception (`--help`, `--version`, `--completions <shell>`,
|
|
163
|
-
* bare `help` token), dispatches into the command tree, falls back to the
|
|
164
|
-
* default command, and produces structured errors for unknown commands/flags.
|
|
165
|
-
* @internal
|
|
166
|
-
*/
|
|
167
|
-
declare function planInvocation(options: PlanInvocationOptions): InvocationPlan;
|
|
168
95
|
//#endregion
|
|
169
|
-
export { type CommandExecutionPlan, type DispatchErrorOutcome, type DispatchOutcome, type
|
|
96
|
+
export { type CommandExecutionPlan, type DispatchErrorOutcome, type DispatchOutcome, type OutputPolicy, type PlannerMatchOutcome, type RootCompletionsOutcome, type RootHelpOutcome, type RootVersionOutcome, buildCommandExecutionPlan, mergeCommandSchema };
|
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
import { CLIError, ParseError } from "../errors/index.mjs";
|
|
2
|
-
import { buildFlagLookup, flagExpectsValue, includesBeforeSeparator } from "../parse/index.mjs";
|
|
2
|
+
import { buildFlagLookup, flagExpectsValue, includesBeforeSeparator, requestsHelp } from "../parse/index.mjs";
|
|
3
|
+
import { builtinEnabled } from "./builtins.mjs";
|
|
3
4
|
import { collectPropagatedFlags } from "./propagate.mjs";
|
|
4
5
|
import { normalizeShell } from "../completion/index.mjs";
|
|
5
6
|
import { dispatch, findClosestCommand } from "./dispatch.mjs";
|
|
7
|
+
import { readRootOutputFlags } from "./root-output-flags.mjs";
|
|
6
8
|
//#region src/core/cli/planner.ts
|
|
7
9
|
function buildMeta(schema, helpOptions, commandName) {
|
|
8
10
|
return {
|
|
@@ -58,17 +60,17 @@ function buildCommandExecutionPlan(options) {
|
|
|
58
60
|
help: options.help
|
|
59
61
|
};
|
|
60
62
|
}
|
|
61
|
-
function buildPlannerMatchOutcome(
|
|
63
|
+
function buildPlannerMatchOutcome(options, command, commandPath, argv) {
|
|
62
64
|
return {
|
|
63
65
|
kind: "match",
|
|
64
66
|
plan: buildCommandExecutionPlan({
|
|
65
67
|
command,
|
|
66
68
|
commandPath,
|
|
67
69
|
argv,
|
|
68
|
-
meta: buildMeta(schema, help, command.schema.name),
|
|
69
|
-
plugins:
|
|
70
|
-
output,
|
|
71
|
-
help
|
|
70
|
+
meta: buildMeta(options.schema, options.help, command.schema.name),
|
|
71
|
+
plugins: options.compiled.plugins,
|
|
72
|
+
output: options.output,
|
|
73
|
+
help: options.help
|
|
72
74
|
})
|
|
73
75
|
};
|
|
74
76
|
}
|
|
@@ -110,11 +112,11 @@ function findUnknownFlagBeforePositional(argv, flags, parseOptions) {
|
|
|
110
112
|
*
|
|
111
113
|
* @internal
|
|
112
114
|
*/
|
|
113
|
-
function scanRootHead(head, valueFlags) {
|
|
115
|
+
function scanRootHead(head, valueFlags, helpOwned) {
|
|
114
116
|
for (let index = 0; index < head.length; index++) {
|
|
115
117
|
const token = head[index];
|
|
116
118
|
if (token === void 0) continue;
|
|
117
|
-
if (token === "--help" || token === "-h") return {
|
|
119
|
+
if (helpOwned && (token === "--help" || token === "-h")) return {
|
|
118
120
|
helpBeforeCommand: true,
|
|
119
121
|
firstCommandToken: void 0,
|
|
120
122
|
commandTokenIndex: -1
|
|
@@ -146,6 +148,22 @@ function scanRootHead(head, valueFlags) {
|
|
|
146
148
|
};
|
|
147
149
|
}
|
|
148
150
|
/**
|
|
151
|
+
* Build the `Run '<scope> --help'` hint carried by a dispatch failure.
|
|
152
|
+
*
|
|
153
|
+
* A CLI that released `help` through `.builtins({ help: 'off' })` rejects the
|
|
154
|
+
* token, so the hint is dropped rather than pointing at a flag the program
|
|
155
|
+
* answers with `Unknown flag --help`.
|
|
156
|
+
*
|
|
157
|
+
* @param scopePath - Binary name plus any ancestor command names.
|
|
158
|
+
* @param helpOwned - Whether the root still owns `--help`.
|
|
159
|
+
* @returns The `suggest` field, or an empty object.
|
|
160
|
+
*
|
|
161
|
+
* @internal
|
|
162
|
+
*/
|
|
163
|
+
function helpHint(scopePath, helpOwned) {
|
|
164
|
+
return helpOwned ? { suggest: `Run '${scopePath} --help' for available commands` } : {};
|
|
165
|
+
}
|
|
166
|
+
/**
|
|
149
167
|
* Detect and resolve the eager `--completions [shell]` flag before dispatch.
|
|
150
168
|
*
|
|
151
169
|
* Accepts `--completions <shell>` and `--completions=<shell>`. When no value is
|
|
@@ -190,12 +208,6 @@ function planCompletionsFlag(argv, config) {
|
|
|
190
208
|
};
|
|
191
209
|
}
|
|
192
210
|
}
|
|
193
|
-
/** Root-level output flags stripped before dispatch (never part of a command schema). */
|
|
194
|
-
const ROOT_OUTPUT_FLAGS = /* @__PURE__ */ new Set([
|
|
195
|
-
"--json",
|
|
196
|
-
"--quiet",
|
|
197
|
-
"-q"
|
|
198
|
-
]);
|
|
199
211
|
/**
|
|
200
212
|
* Decide what to do with an argv invocation before any command executes.
|
|
201
213
|
*
|
|
@@ -205,12 +217,12 @@ const ROOT_OUTPUT_FLAGS = /* @__PURE__ */ new Set([
|
|
|
205
217
|
* @internal
|
|
206
218
|
*/
|
|
207
219
|
function planInvocation(options) {
|
|
208
|
-
const
|
|
209
|
-
const
|
|
210
|
-
const
|
|
211
|
-
const
|
|
212
|
-
const
|
|
213
|
-
const defaultCommand = options.
|
|
220
|
+
const helpOwned = builtinEnabled(options.schema.builtins, "help");
|
|
221
|
+
const rootOutputFlags = readRootOutputFlags(options.argv, options.schema.builtins);
|
|
222
|
+
const filteredArgv = rootOutputFlags.argv;
|
|
223
|
+
const separatorIndex = filteredArgv.indexOf("--");
|
|
224
|
+
const filteredHead = separatorIndex === -1 ? filteredArgv : filteredArgv.slice(0, separatorIndex);
|
|
225
|
+
const defaultCommand = options.compiled.defaultCommand;
|
|
214
226
|
const rootValueFlags = defaultCommand !== void 0 ? buildFlagLookup(defaultCommand.schema.flags, options.schema.flagSettings) : void 0;
|
|
215
227
|
if (options.schema.version !== void 0 && (includesBeforeSeparator(options.argv, "--version") || includesBeforeSeparator(options.argv, "-V"))) return {
|
|
216
228
|
kind: "root-version",
|
|
@@ -220,13 +232,13 @@ function planInvocation(options) {
|
|
|
220
232
|
const completionsOutcome = planCompletionsFlag(options.argv, options.schema.completionsFlag);
|
|
221
233
|
if (completionsOutcome !== void 0) return completionsOutcome;
|
|
222
234
|
}
|
|
223
|
-
const headScan = scanRootHead(filteredHead, rootValueFlags);
|
|
235
|
+
const headScan = scanRootHead(filteredHead, rootValueFlags, helpOwned);
|
|
224
236
|
if (headScan.helpBeforeCommand) return {
|
|
225
237
|
kind: "root-help",
|
|
226
238
|
help: options.help
|
|
227
239
|
};
|
|
228
|
-
if (headScan.firstCommandToken === "help") {
|
|
229
|
-
if (!options.
|
|
240
|
+
if (helpOwned && headScan.firstCommandToken === "help") {
|
|
241
|
+
if (!options.compiled.commands.some((command) => command.schema.name === "help" || command.schema.aliases.includes("help"))) {
|
|
230
242
|
const rest = filteredArgv.slice(headScan.commandTokenIndex + 1);
|
|
231
243
|
if (rest.length === 0) return {
|
|
232
244
|
kind: "root-help",
|
|
@@ -238,7 +250,11 @@ function planInvocation(options) {
|
|
|
238
250
|
});
|
|
239
251
|
}
|
|
240
252
|
}
|
|
241
|
-
if (
|
|
253
|
+
if (rootOutputFlags.kind === "failed" && !(helpOwned && requestsHelp(filteredArgv))) return {
|
|
254
|
+
kind: "dispatch-error",
|
|
255
|
+
error: rootOutputFlags.error
|
|
256
|
+
};
|
|
257
|
+
if (options.compiled.commands.length === 0 && defaultCommand === void 0) return {
|
|
242
258
|
kind: "dispatch-error",
|
|
243
259
|
error: new CLIError("No commands registered", {
|
|
244
260
|
code: "NO_ACTION",
|
|
@@ -249,17 +265,18 @@ function planInvocation(options) {
|
|
|
249
265
|
kind: "root-help",
|
|
250
266
|
help: options.help
|
|
251
267
|
};
|
|
252
|
-
const
|
|
268
|
+
const rootCommands = defaultCommand !== void 0 && options.schema.defaultCommandRouted ? [...options.compiled.commands, defaultCommand] : options.compiled.commands;
|
|
269
|
+
const result = dispatch(filteredArgv, buildRootCommandMap(rootCommands), [], rootValueFlags, options.schema.flagSettings);
|
|
253
270
|
switch (result.kind) {
|
|
254
271
|
case "unknown": {
|
|
255
272
|
if (defaultCommand !== void 0 && result.parentPath.length === 0) {
|
|
256
|
-
if ((result.input !== "" ? findClosestCommand(result.input, result.candidates) : void 0) === void 0 && canDelegateUnknownRootToDefault(defaultCommand, result.input)) return buildPlannerMatchOutcome(options
|
|
273
|
+
if ((result.input !== "" ? findClosestCommand(result.input, result.candidates) : void 0) === void 0 && canDelegateUnknownRootToDefault(defaultCommand, result.input)) return buildPlannerMatchOutcome(options, defaultCommand, [defaultCommand.schema], filteredArgv);
|
|
257
274
|
const unknownFlag = findUnknownFlagBeforePositional(filteredArgv, defaultCommand.schema.flags, options.schema.flagSettings);
|
|
258
275
|
if (unknownFlag !== void 0) return {
|
|
259
276
|
kind: "dispatch-error",
|
|
260
277
|
error: new ParseError(`Unknown flag ${unknownFlag}`, {
|
|
261
278
|
code: "UNKNOWN_FLAG",
|
|
262
|
-
|
|
279
|
+
...helpHint(options.schema.name, helpOwned)
|
|
263
280
|
})
|
|
264
281
|
};
|
|
265
282
|
}
|
|
@@ -273,7 +290,7 @@ function planInvocation(options) {
|
|
|
273
290
|
kind: "dispatch-error",
|
|
274
291
|
error: new ParseError(`Unknown flag ${unknownFlag}`, {
|
|
275
292
|
code: "UNKNOWN_FLAG",
|
|
276
|
-
|
|
293
|
+
...helpHint(options.schema.name, helpOwned)
|
|
277
294
|
})
|
|
278
295
|
};
|
|
279
296
|
}
|
|
@@ -283,7 +300,7 @@ function planInvocation(options) {
|
|
|
283
300
|
kind: "dispatch-error",
|
|
284
301
|
error: new ParseError(`Unknown command: ${result.input}`, {
|
|
285
302
|
code: "UNKNOWN_COMMAND",
|
|
286
|
-
|
|
303
|
+
...suggestion !== void 0 ? { suggest: `Did you mean '${suggestion}'?` } : helpHint(scopePath, helpOwned)
|
|
287
304
|
})
|
|
288
305
|
};
|
|
289
306
|
}
|
|
@@ -299,7 +316,7 @@ function planInvocation(options) {
|
|
|
299
316
|
}
|
|
300
317
|
};
|
|
301
318
|
}
|
|
302
|
-
case "match": return buildPlannerMatchOutcome(options
|
|
319
|
+
case "match": return buildPlannerMatchOutcome(options, result.command, result.commandPath, result.remainingArgv);
|
|
303
320
|
}
|
|
304
321
|
}
|
|
305
322
|
//#endregion
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
+
import { CommandMeta, CommandSchema, Out } from "../schema/command.mjs";
|
|
1
2
|
import { DeprecationWarning } from "../resolve/contracts.mjs";
|
|
2
3
|
import "../resolve/index.mjs";
|
|
3
|
-
import { CommandMeta, CommandSchema, Out } from "../schema/command.mjs";
|
|
4
4
|
//#region src/core/cli/plugin.d.ts
|
|
5
5
|
/** Shared hook payload for a concrete command execution. */
|
|
6
6
|
interface PluginCommandContext {
|
|
@@ -41,7 +41,7 @@ function collectPropagatedFlags(commandPath) {
|
|
|
41
41
|
let shadowedByDescendant = false;
|
|
42
42
|
for (let j = i + 1; j < commandPath.length - 1; j++) {
|
|
43
43
|
const descendant = commandPath[j];
|
|
44
|
-
if (descendant !== void 0 &&
|
|
44
|
+
if (descendant !== void 0 && Object.hasOwn(descendant.flags, name)) {
|
|
45
45
|
shadowedByDescendant = true;
|
|
46
46
|
break;
|
|
47
47
|
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {}
|
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
import { CLIError } from "../errors/index.mjs";
|
|
2
|
+
import { getFlagAliasNames, getFlagNegatedName } from "../schema/flag.mjs";
|
|
3
|
+
import { BUILTIN_NAMES, builtinEnabled, builtinSpelling, builtinTokens } from "./builtins.mjs";
|
|
4
|
+
//#region src/core/cli/reserved-flags.ts
|
|
5
|
+
/**
|
|
6
|
+
* Build-time guard for command flags the CLI root already owns.
|
|
7
|
+
*
|
|
8
|
+
* `--json`, `--quiet`/`-q` and `--help`/`-h` never reach a command handler, and
|
|
9
|
+
* `--version`/`-V` joins them once the CLI declares a version. A command flag
|
|
10
|
+
* spelled the same way can never be set, so registering one throws
|
|
11
|
+
* {@linkcode CLIError} `RESERVED_FLAG` here rather than building a CLI whose
|
|
12
|
+
* flag silently stays at its default (#84).
|
|
13
|
+
*
|
|
14
|
+
* A built-in released through `.builtins({ <name>: 'off' })` drops out of the
|
|
15
|
+
* reserved set, which is what makes the flag declarable (#86).
|
|
16
|
+
*
|
|
17
|
+
* @module dreamcli/core/cli/reserved-flags
|
|
18
|
+
* @internal
|
|
19
|
+
*/
|
|
20
|
+
/** Remedy for a reserved token whose only fix is a different spelling. */
|
|
21
|
+
const RENAME = "Rename the flag";
|
|
22
|
+
/** Why the root never hands a command the tokens it strips from argv. */
|
|
23
|
+
const STRIPPED = "The root strips that token before dispatch";
|
|
24
|
+
/** Why a command never receives `--help`, in either interception path. */
|
|
25
|
+
const HELP_INTERCEPTED = "A help request renders before flags are parsed";
|
|
26
|
+
/** Why a command never receives `--version`. */
|
|
27
|
+
const VERSION_INTERCEPTED = "The root intercepts that token before dispatch";
|
|
28
|
+
/** Extra clause offered for `--quiet`, which has a framework equivalent. */
|
|
29
|
+
const STATUS_ALTERNATIVE = "use out.status() for output that root --quiet suppresses";
|
|
30
|
+
/** Offer the `.builtins()` opt-out alongside renaming. */
|
|
31
|
+
function releaseRemedy(name, ...alternatives) {
|
|
32
|
+
return [
|
|
33
|
+
RENAME,
|
|
34
|
+
...alternatives,
|
|
35
|
+
`release the built-in with .builtins({ ${name}: 'off' }) before registering the command`
|
|
36
|
+
].join(", or ");
|
|
37
|
+
}
|
|
38
|
+
/** Why the root owns each built-in's tokens. */
|
|
39
|
+
const BUILTIN_EFFECTS = {
|
|
40
|
+
help: HELP_INTERCEPTED,
|
|
41
|
+
json: STRIPPED,
|
|
42
|
+
quiet: STRIPPED
|
|
43
|
+
};
|
|
44
|
+
/** How a collision with each built-in is fixed. */
|
|
45
|
+
const BUILTIN_REMEDIES = {
|
|
46
|
+
help: releaseRemedy("help"),
|
|
47
|
+
json: releaseRemedy("json"),
|
|
48
|
+
quiet: releaseRemedy("quiet", STATUS_ALTERNATIVE)
|
|
49
|
+
};
|
|
50
|
+
/** Reservation for `--version`/`-V`, active once the CLI declares a version. */
|
|
51
|
+
const VERSION_RESERVED = {
|
|
52
|
+
rootSpelling: "--version",
|
|
53
|
+
effect: VERSION_INTERCEPTED,
|
|
54
|
+
remedy: RENAME
|
|
55
|
+
};
|
|
56
|
+
/** Tokens the root owns only once a version is configured. */
|
|
57
|
+
const VERSION_TOKENS = ["version", "V"];
|
|
58
|
+
/**
|
|
59
|
+
* The tokens a CLI's commands may not spell.
|
|
60
|
+
*
|
|
61
|
+
* Built from the shared built-in spelling table, so the reserved set and the spellings
|
|
62
|
+
* the root actually reads cannot drift, and a released built-in is absent here
|
|
63
|
+
* by construction.
|
|
64
|
+
*/
|
|
65
|
+
function reservedTokens(version, builtins) {
|
|
66
|
+
const reserved = /* @__PURE__ */ new Map();
|
|
67
|
+
for (const name of BUILTIN_NAMES) {
|
|
68
|
+
if (!builtinEnabled(builtins, name)) continue;
|
|
69
|
+
const entry = {
|
|
70
|
+
rootSpelling: builtinSpelling(name),
|
|
71
|
+
effect: BUILTIN_EFFECTS[name],
|
|
72
|
+
remedy: BUILTIN_REMEDIES[name]
|
|
73
|
+
};
|
|
74
|
+
for (const token of builtinTokens(name)) reserved.set(token, entry);
|
|
75
|
+
}
|
|
76
|
+
if (version !== void 0) for (const token of VERSION_TOKENS) reserved.set(token, VERSION_RESERVED);
|
|
77
|
+
return reserved;
|
|
78
|
+
}
|
|
79
|
+
/** Render a bare token the way argv spells it. */
|
|
80
|
+
function spellingOf(token) {
|
|
81
|
+
return token.length === 1 ? `-${token}` : `--${token}`;
|
|
82
|
+
}
|
|
83
|
+
/** Every spelling one flag answers to, paired with the declaration it came from. */
|
|
84
|
+
function flagSpellings(flagName, flagSchema) {
|
|
85
|
+
const spellings = [[flagName, "name"]];
|
|
86
|
+
for (const alias of getFlagAliasNames(flagSchema, { includeHidden: true })) spellings.push([alias, "alias"]);
|
|
87
|
+
const negated = getFlagNegatedName(flagName, flagSchema);
|
|
88
|
+
if (negated !== void 0) spellings.push([negated, "negation"]);
|
|
89
|
+
return spellings;
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* Find the first flag in a command tree whose spelling is reserved.
|
|
93
|
+
*
|
|
94
|
+
* @param schema - Command to walk, including its nested subcommands.
|
|
95
|
+
* @param reserved - Reserved tokens for the current CLI configuration.
|
|
96
|
+
* @returns The collision, or `undefined` when the tree is clean.
|
|
97
|
+
*
|
|
98
|
+
* @internal
|
|
99
|
+
*/
|
|
100
|
+
function findReservedCollision(schema, reserved) {
|
|
101
|
+
for (const [flagName, flagSchema] of Object.entries(schema.flags)) for (const [token, origin] of flagSpellings(flagName, flagSchema)) {
|
|
102
|
+
const match = reserved.get(token);
|
|
103
|
+
if (match === void 0) continue;
|
|
104
|
+
return {
|
|
105
|
+
commandName: schema.name,
|
|
106
|
+
flagName,
|
|
107
|
+
spelling: spellingOf(token),
|
|
108
|
+
origin,
|
|
109
|
+
reserved: match
|
|
110
|
+
};
|
|
111
|
+
}
|
|
112
|
+
for (const child of schema.commands) {
|
|
113
|
+
const nested = findReservedCollision(child, reserved);
|
|
114
|
+
if (nested !== void 0) return nested;
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
/** Describe the colliding declaration the way the error opens. */
|
|
118
|
+
function subjectOf(collision) {
|
|
119
|
+
switch (collision.origin) {
|
|
120
|
+
case "name": return `defines a '${collision.spelling}' flag`;
|
|
121
|
+
case "alias": return `defines a '${collision.spelling}' alias on flag '${collision.flagName}'`;
|
|
122
|
+
case "negation": return `defines a '${collision.spelling}' negated spelling on flag '${collision.flagName}'`;
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
/** Build the `RESERVED_FLAG` error for a collision. */
|
|
126
|
+
function reservedFlagError(collision) {
|
|
127
|
+
return new CLIError(`Command '${collision.commandName}' ${subjectOf(collision)}, which is reserved by the root '${collision.reserved.rootSpelling}' flag. ${collision.reserved.effect}, so the command can never receive it`, {
|
|
128
|
+
code: "RESERVED_FLAG",
|
|
129
|
+
details: {
|
|
130
|
+
command: collision.commandName,
|
|
131
|
+
flag: collision.flagName
|
|
132
|
+
},
|
|
133
|
+
suggest: collision.reserved.remedy
|
|
134
|
+
});
|
|
135
|
+
}
|
|
136
|
+
/**
|
|
137
|
+
* Reject command trees declaring a flag the CLI root already owns.
|
|
138
|
+
*
|
|
139
|
+
* @param version - The CLI's declared version; `undefined` leaves
|
|
140
|
+
* `--version`/`-V` available to commands.
|
|
141
|
+
* @param commands - Command trees to walk. `undefined` entries are skipped so
|
|
142
|
+
* callers can pass an absent default command directly.
|
|
143
|
+
* @param builtins - Built-in state; a released built-in reserves nothing.
|
|
144
|
+
* `undefined` keeps every built-in on.
|
|
145
|
+
* @throws {@linkcode CLIError} `RESERVED_FLAG` for the first collision found.
|
|
146
|
+
*
|
|
147
|
+
* @internal
|
|
148
|
+
*/
|
|
149
|
+
function assertNoReservedFlagCollisions(version, commands, builtins) {
|
|
150
|
+
const reserved = reservedTokens(version, builtins);
|
|
151
|
+
for (const schema of commands) {
|
|
152
|
+
if (schema === void 0) continue;
|
|
153
|
+
const collision = findReservedCollision(schema, reserved);
|
|
154
|
+
if (collision !== void 0) throw reservedFlagError(collision);
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
//#endregion
|
|
158
|
+
export { assertNoReservedFlagCollisions };
|
|
@@ -1,47 +1 @@
|
|
|
1
|
-
|
|
2
|
-
import { CommandSchema } from "../schema/command.mjs";
|
|
3
|
-
//#region src/core/cli/root-help.d.ts
|
|
4
|
-
/** Structural subset of `CLISchema` — avoids circular imports through the barrel. */
|
|
5
|
-
interface CLISchemaLike {
|
|
6
|
-
readonly name: string;
|
|
7
|
-
readonly version: string | undefined;
|
|
8
|
-
readonly description: string | undefined;
|
|
9
|
-
readonly commands: ReadonlyArray<{
|
|
10
|
-
readonly schema: CommandSchema;
|
|
11
|
-
}>;
|
|
12
|
-
readonly defaultCommand: {
|
|
13
|
-
readonly schema: CommandSchema;
|
|
14
|
-
} | undefined;
|
|
15
|
-
/** Whether the default is also a named route — listed in `Commands:` when so. */
|
|
16
|
-
readonly defaultCommandRouted?: boolean | undefined;
|
|
17
|
-
readonly helpLinks?: {
|
|
18
|
-
readonly name: string | undefined;
|
|
19
|
-
readonly version: string | undefined;
|
|
20
|
-
} | undefined;
|
|
21
|
-
readonly completionsFlag?: {
|
|
22
|
-
readonly shells: readonly string[];
|
|
23
|
-
} | undefined;
|
|
24
|
-
/**
|
|
25
|
-
* Config discovery settings. Only its presence is read — defined means
|
|
26
|
-
* `.config()` enabled the built-in `--config <path>` flag, so root help
|
|
27
|
-
* advertises it in `Global options:`.
|
|
28
|
-
*/
|
|
29
|
-
readonly configSettings?: {
|
|
30
|
-
readonly appName: string;
|
|
31
|
-
} | undefined;
|
|
32
|
-
}
|
|
33
|
-
/**
|
|
34
|
-
* Generate root-level help text for the CLI program.
|
|
35
|
-
*
|
|
36
|
-
* Shows program name, version, description, usage line, and available
|
|
37
|
-
* subcommands. The default command is the CLI's root *surface*: its arguments
|
|
38
|
-
* and flags are rendered inline (unless `inlineDefault` is `false`) and it is
|
|
39
|
-
* omitted from the `Commands:` list unless `showDefaultInCommands` is set. When
|
|
40
|
-
* `.completions({ as: 'flag' })` is active, the eager `--completions <shell>`
|
|
41
|
-
* flag is advertised in the `Flags:` section.
|
|
42
|
-
*
|
|
43
|
-
* @internal
|
|
44
|
-
*/
|
|
45
|
-
declare function formatRootHelp(schema: CLISchemaLike, options?: HelpOptions): string;
|
|
46
|
-
//#endregion
|
|
47
|
-
export { formatRootHelp };
|
|
1
|
+
export {}
|