@kjanat/dreamcli 2.5.0 → 3.0.0-rc.10
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 +344 -1
- package/README.md +9 -2
- package/dist/core/cli/dispatch.d.mts +6 -5
- package/dist/core/cli/dispatch.mjs +205 -1
- package/dist/core/cli/help-links.d.mts +0 -1
- package/dist/core/cli/help-links.mjs +41 -1
- package/dist/core/cli/index.d.mts +185 -19
- package/dist/core/cli/index.mjs +945 -1
- package/dist/core/cli/planner.d.mts +32 -6
- package/dist/core/cli/planner.mjs +300 -1
- package/dist/core/cli/plugin.d.mts +1 -1
- package/dist/core/cli/plugin.mjs +41 -1
- package/dist/core/cli/propagate.d.mts +1 -1
- package/dist/core/cli/propagate.mjs +57 -1
- package/dist/core/cli/root-help.d.mts +18 -3
- package/dist/core/cli/root-help.mjs +226 -6
- package/dist/core/cli/root-surface.d.mts +30 -4
- package/dist/core/cli/root-surface.mjs +28 -1
- package/dist/core/cli/runtime-preflight.d.mts +30 -3
- package/dist/core/cli/runtime-preflight.mjs +169 -1
- package/dist/core/completion/index.d.mts +32 -2
- package/dist/core/completion/index.mjs +90 -1
- package/dist/core/completion/shells/bash.d.mts +0 -1
- package/dist/core/completion/shells/bash.mjs +308 -3
- package/dist/core/completion/shells/fish.d.mts +0 -1
- package/dist/core/completion/shells/fish.mjs +162 -2
- package/dist/core/completion/shells/powershell.d.mts +0 -1
- package/dist/core/completion/shells/powershell.mjs +358 -2
- package/dist/core/completion/shells/shared.d.mts +23 -2
- package/dist/core/completion/shells/shared.mjs +176 -1
- package/dist/core/completion/shells/zsh.d.mts +0 -1
- package/dist/core/completion/shells/zsh.mjs +251 -2
- package/dist/core/config/index.d.mts +2 -3
- package/dist/core/config/index.mjs +246 -1
- package/dist/core/config/package-json.d.mts +27 -4
- package/dist/core/config/package-json.mjs +386 -3
- package/dist/core/errors/index.d.mts +3 -3
- package/dist/core/errors/index.mjs +87 -1
- package/dist/core/execution/index.d.mts +0 -1
- package/dist/core/execution/index.mjs +201 -1
- package/dist/core/help/ansi.d.mts +11 -5
- package/dist/core/help/ansi.mjs +121 -2
- package/dist/core/help/index.d.mts +65 -2
- package/dist/core/help/index.mjs +341 -7
- package/dist/core/help/theme.d.mts +68 -0
- package/dist/core/help/theme.mjs +46 -0
- package/dist/core/json-schema/index.d.mts +15 -2
- package/dist/core/json-schema/index.mjs +536 -12
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +22 -5
- package/dist/core/json-schema/meta-descriptions.generated.mjs +102 -28
- package/dist/core/output/activity.d.mts +0 -1
- package/dist/core/output/activity.mjs +452 -1
- package/dist/core/output/bind.mjs +56 -1
- package/dist/core/output/contracts.d.mts +4 -5
- package/dist/core/output/contracts.mjs +57 -1
- package/dist/core/output/display-value.mjs +32 -1
- package/dist/core/output/index.d.mts +21 -1
- package/dist/core/output/index.mjs +442 -2
- package/dist/core/output/renderers.d.mts +0 -1
- package/dist/core/output/renderers.mjs +46 -1
- package/dist/core/output/writer.mjs +12 -1
- package/dist/core/parse/index.d.mts +54 -7
- package/dist/core/parse/index.mjs +727 -1
- package/dist/core/prompt/index.d.mts +12 -4
- package/dist/core/prompt/index.mjs +348 -6
- package/dist/core/resolve/args.d.mts +1 -1
- package/dist/core/resolve/args.mjs +105 -1
- package/dist/core/resolve/coerce.d.mts +1 -1
- package/dist/core/resolve/coerce.mjs +336 -1
- package/dist/core/resolve/config.mjs +19 -1
- package/dist/core/resolve/contracts.d.mts +9 -4
- package/dist/core/resolve/errors.d.mts +0 -1
- package/dist/core/resolve/errors.mjs +140 -2
- package/dist/core/resolve/flags.d.mts +7 -2
- package/dist/core/resolve/flags.mjs +251 -1
- package/dist/core/resolve/index.d.mts +2 -2
- package/dist/core/resolve/index.mjs +85 -1
- package/dist/core/resolve/property.d.mts +6 -2
- package/dist/core/resolve/property.mjs +53 -1
- package/dist/core/schema/activity.d.mts +31 -11
- package/dist/core/schema/arg.d.mts +92 -13
- package/dist/core/schema/arg.mjs +463 -1
- package/dist/core/schema/command.d.mts +29 -7
- package/dist/core/schema/command.mjs +726 -1
- package/dist/core/schema/flag.d.mts +577 -21
- package/dist/core/schema/flag.mjs +705 -1
- package/dist/core/schema/index.d.mts +5 -2
- package/dist/core/schema/middleware.d.mts +4 -3
- package/dist/core/schema/middleware.mjs +41 -1
- package/dist/core/schema/number-constraints.d.mts +96 -0
- package/dist/core/schema/number-constraints.mjs +60 -0
- package/dist/core/schema/prompt.d.mts +21 -3
- package/dist/core/schema/run.d.mts +24 -5
- package/dist/core/schema/string-constraints.d.mts +97 -0
- package/dist/core/schema/string-constraints.mjs +69 -0
- package/dist/core/schema/value-parsers.d.mts +78 -0
- package/dist/core/schema/value-parsers.mjs +142 -0
- package/dist/core/schema-dsl/runtime.mjs +271 -2
- package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
- package/dist/core/schema-dsl/to-json-schema.mjs +74 -1
- package/dist/core/testkit/index.d.mts +9 -36
- package/dist/core/testkit/index.mjs +83 -1
- package/dist/index.d.mts +12 -6
- package/dist/index.mjs +22 -1
- package/dist/runtime/adapter.d.mts +38 -2
- package/dist/runtime/adapter.mjs +87 -1
- package/dist/runtime/auto.d.mts +2 -3
- package/dist/runtime/auto.mjs +45 -1
- package/dist/runtime/deno.d.mts +24 -5
- package/dist/runtime/deno.mjs +262 -2
- package/dist/runtime/detect.mjs +45 -1
- package/dist/runtime/index.d.mts +3 -4
- package/dist/runtime/node.d.mts +8 -2
- package/dist/runtime/node.mjs +220 -2
- package/dist/runtime/paths.mjs +48 -1
- package/dist/runtime.d.mts +4 -4
- package/dist/runtime.mjs +6 -1
- package/dist/strings.mjs +22 -1
- package/dist/testkit.d.mts +1 -0
- package/dist/testkit.mjs +5 -1
- package/dist/version.d.mts +7 -3
- package/dist/version.mjs +7 -1
- package/dreamcli.schema.json +36 -7
- package/examples/basic.ts +5 -1
- package/examples/gh/package.json +2 -7
- package/examples/pwsh-demo/package.json +1 -7
- package/examples/pwsh-demo/src/main.test.ts +1 -4
- package/examples/pwsh-demo/src/main.ts +14 -4
- package/examples/transport-launcher.ts +85 -0
- package/package.json +43 -49
- package/dist/runtime/bun.d.mts +0 -28
- package/dist/runtime/bun.mjs +0 -1
- package/dist/runtime/support.d.mts +0 -42
- package/dist/runtime/support.mjs +0 -1
- package/src/core/cli/dispatch.ts +0 -349
- package/src/core/cli/help-links.ts +0 -82
- package/src/core/cli/index.ts +0 -1413
- package/src/core/cli/planner.ts +0 -487
- package/src/core/cli/plugin.ts +0 -117
- package/src/core/cli/propagate.ts +0 -97
- package/src/core/cli/root-help.ts +0 -252
- package/src/core/cli/root-surface.ts +0 -74
- package/src/core/cli/runtime-preflight.ts +0 -438
- package/src/core/completion/index.ts +0 -88
- package/src/core/completion/shells/bash.ts +0 -459
- package/src/core/completion/shells/fish.ts +0 -259
- package/src/core/completion/shells/powershell.ts +0 -439
- package/src/core/completion/shells/shared.ts +0 -283
- package/src/core/completion/shells/zsh.ts +0 -381
- package/src/core/config/index.ts +0 -417
- package/src/core/config/package-json.ts +0 -560
- package/src/core/errors/index.ts +0 -193
- package/src/core/execution/index.ts +0 -268
- package/src/core/help/ansi.ts +0 -144
- package/src/core/help/index.ts +0 -516
- package/src/core/json-schema/index.ts +0 -891
- package/src/core/json-schema/meta-descriptions.generated.ts +0 -185
- package/src/core/output/activity.ts +0 -575
- package/src/core/output/bind.ts +0 -59
- package/src/core/output/contracts.ts +0 -194
- package/src/core/output/display-value.ts +0 -48
- package/src/core/output/index.ts +0 -704
- package/src/core/output/renderers.ts +0 -125
- package/src/core/output/writer.ts +0 -46
- package/src/core/parse/index.ts +0 -681
- package/src/core/prompt/index.ts +0 -583
- package/src/core/resolve/args.ts +0 -144
- package/src/core/resolve/coerce.ts +0 -432
- package/src/core/resolve/config.ts +0 -26
- package/src/core/resolve/contracts.ts +0 -135
- package/src/core/resolve/errors.ts +0 -227
- package/src/core/resolve/flags.ts +0 -255
- package/src/core/resolve/index.ts +0 -108
- package/src/core/resolve/property.ts +0 -99
- package/src/core/schema/activity.ts +0 -240
- package/src/core/schema/arg.ts +0 -719
- package/src/core/schema/command.ts +0 -1498
- package/src/core/schema/flag.ts +0 -801
- package/src/core/schema/index.ts +0 -91
- package/src/core/schema/middleware.ts +0 -171
- package/src/core/schema/prompt.ts +0 -156
- package/src/core/schema/run.ts +0 -198
- package/src/core/schema-dsl/index.ts +0 -109
- package/src/core/schema-dsl/parse.ts +0 -262
- package/src/core/schema-dsl/runtime.ts +0 -609
- package/src/core/schema-dsl/to-json-schema.ts +0 -102
- package/src/core/testkit/index.ts +0 -123
- package/src/index.ts +0 -179
- package/src/runtime/adapter.ts +0 -303
- package/src/runtime/auto.ts +0 -110
- package/src/runtime/bun.ts +0 -55
- package/src/runtime/deno.ts +0 -369
- package/src/runtime/detect.ts +0 -105
- package/src/runtime/index.ts +0 -21
- package/src/runtime/node-builtins.d.ts +0 -27
- package/src/runtime/node.ts +0 -300
- package/src/runtime/paths.ts +0 -64
- package/src/runtime/support.ts +0 -135
- package/src/runtime.ts +0 -31
- package/src/strings.ts +0 -34
- package/src/testkit.ts +0 -25
- package/src/version.ts +0 -20
|
@@ -3,7 +3,9 @@ import { CLIPlugin } from "./plugin.mjs";
|
|
|
3
3
|
import { CLIError } from "../errors/index.mjs";
|
|
4
4
|
import { HelpOptions } from "../help/index.mjs";
|
|
5
5
|
import { CommandMeta, CommandSchema, ErasedCommand } from "../schema/command.mjs";
|
|
6
|
-
|
|
6
|
+
import { ParseOptions } from "../parse/index.mjs";
|
|
7
|
+
import { CompletionOptions } from "../completion/shells/shared.mjs";
|
|
8
|
+
import { Shell } from "../completion/index.mjs";
|
|
7
9
|
//#region src/core/cli/planner.d.ts
|
|
8
10
|
/**
|
|
9
11
|
* Structural subset of CLISchema used by the planner.
|
|
@@ -21,6 +23,18 @@ interface PlannerSchemaLike {
|
|
|
21
23
|
readonly commands: readonly ErasedCommand[];
|
|
22
24
|
/** Fallback command when no subcommand token matches. */
|
|
23
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;
|
|
24
38
|
/** Plugins forwarded into every matched execution plan. */
|
|
25
39
|
readonly plugins: readonly CLIPlugin[];
|
|
26
40
|
}
|
|
@@ -38,6 +52,18 @@ interface RootVersionOutcome {
|
|
|
38
52
|
/** Resolved version string to render. */
|
|
39
53
|
readonly version: string;
|
|
40
54
|
}
|
|
55
|
+
/** Root-level `--completions [shell]` interception outcome. */
|
|
56
|
+
interface RootCompletionsOutcome {
|
|
57
|
+
/** Discriminant — argv matched the eager `--completions [shell]` flag. */
|
|
58
|
+
readonly kind: 'root-completions';
|
|
59
|
+
/**
|
|
60
|
+
* Resolved, validated target shell, or `undefined` when the flag was given
|
|
61
|
+
* without a value and the shell should be auto-detected from the environment.
|
|
62
|
+
*/
|
|
63
|
+
readonly shell: Shell | undefined;
|
|
64
|
+
/** Generator options captured at build time. */
|
|
65
|
+
readonly options: CompletionOptions | undefined;
|
|
66
|
+
}
|
|
41
67
|
/** CLI-level dispatch failure before command execution starts. */
|
|
42
68
|
interface DispatchErrorOutcome {
|
|
43
69
|
/** Discriminant — dispatch could not resolve a command from argv. */
|
|
@@ -58,7 +84,7 @@ interface PlannerMatchOutcome {
|
|
|
58
84
|
* `CLIBuilder.execute()` still renders and executes these outcomes, but
|
|
59
85
|
* planning itself is intentionally bounded to this union.
|
|
60
86
|
*/
|
|
61
|
-
type DispatchOutcome = RootHelpOutcome | RootVersionOutcome | DispatchErrorOutcome | PlannerMatchOutcome;
|
|
87
|
+
type DispatchOutcome = RootHelpOutcome | RootVersionOutcome | RootCompletionsOutcome | DispatchErrorOutcome | PlannerMatchOutcome;
|
|
62
88
|
/**
|
|
63
89
|
* Concrete execution handoff produced by a successful planner match.
|
|
64
90
|
*
|
|
@@ -133,11 +159,11 @@ declare function buildCommandExecutionPlan(options: BuildCommandExecutionPlanOpt
|
|
|
133
159
|
/**
|
|
134
160
|
* Decide what to do with an argv invocation before any command executes.
|
|
135
161
|
*
|
|
136
|
-
* Handles root interception (`--help`, `--version`,
|
|
137
|
-
* dispatches into the command tree, falls back to the
|
|
138
|
-
* produces structured errors for unknown commands/flags.
|
|
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.
|
|
139
165
|
* @internal
|
|
140
166
|
*/
|
|
141
167
|
declare function planInvocation(options: PlanInvocationOptions): InvocationPlan;
|
|
142
168
|
//#endregion
|
|
143
|
-
export { type CommandExecutionPlan, type DispatchErrorOutcome, type DispatchOutcome, type InvocationPlan, type NeedsSubcommandOutcome, type OutputPolicy, type PlanInvocationOptions, type PlannerMatchOutcome, type PlannerSchemaLike, type RootHelpOutcome, type RootVersionOutcome, buildCommandExecutionPlan, buildRootCommandMap, mergeCommandSchema, planInvocation };
|
|
169
|
+
export { type CommandExecutionPlan, type DispatchErrorOutcome, type DispatchOutcome, type InvocationPlan, type NeedsSubcommandOutcome, type OutputPolicy, type PlanInvocationOptions, type PlannerMatchOutcome, type PlannerSchemaLike, type RootCompletionsOutcome, type RootHelpOutcome, type RootVersionOutcome, buildCommandExecutionPlan, buildRootCommandMap, mergeCommandSchema, planInvocation };
|
|
@@ -1 +1,300 @@
|
|
|
1
|
-
import{
|
|
1
|
+
import { CLIError, ParseError } from "../errors/index.mjs";
|
|
2
|
+
import { buildFlagLookup, flagExpectsValue, includesBeforeSeparator } from "../parse/index.mjs";
|
|
3
|
+
import { collectPropagatedFlags } from "./propagate.mjs";
|
|
4
|
+
import { normalizeShell } from "../completion/index.mjs";
|
|
5
|
+
import { dispatch, findClosestCommand } from "./dispatch.mjs";
|
|
6
|
+
//#region src/core/cli/planner.ts
|
|
7
|
+
function buildMeta(schema, helpOptions, commandName) {
|
|
8
|
+
return {
|
|
9
|
+
name: schema.name,
|
|
10
|
+
bin: helpOptions.binName ?? schema.name,
|
|
11
|
+
version: schema.version,
|
|
12
|
+
command: commandName
|
|
13
|
+
};
|
|
14
|
+
}
|
|
15
|
+
/** Build a name+alias lookup map for top-level commands. @internal */
|
|
16
|
+
function buildRootCommandMap(commands) {
|
|
17
|
+
const rootCommands = /* @__PURE__ */ new Map();
|
|
18
|
+
const addRoute = (route, command) => {
|
|
19
|
+
const existing = rootCommands.get(route);
|
|
20
|
+
if (existing !== void 0) throw new CLIError(`Duplicate root command route '${route}' (${existing.schema.name} and ${command.schema.name})`, {
|
|
21
|
+
code: "DUPLICATE_COMMAND",
|
|
22
|
+
suggest: "Ensure root command names and aliases are unique"
|
|
23
|
+
});
|
|
24
|
+
rootCommands.set(route, command);
|
|
25
|
+
};
|
|
26
|
+
for (const cmd of commands) {
|
|
27
|
+
addRoute(cmd.schema.name, cmd);
|
|
28
|
+
for (const alias of cmd.schema.aliases) addRoute(alias, cmd);
|
|
29
|
+
}
|
|
30
|
+
return rootCommands;
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Merge propagated ancestor flags into the matched command schema.
|
|
34
|
+
*
|
|
35
|
+
* Child flag definitions win when names collide, matching current CLI
|
|
36
|
+
* dispatch semantics and the future planner contract.
|
|
37
|
+
*/
|
|
38
|
+
function mergeCommandSchema(command, commandPath) {
|
|
39
|
+
const propagated = collectPropagatedFlags(commandPath);
|
|
40
|
+
if (Object.keys(propagated).length === 0) return command.schema;
|
|
41
|
+
return {
|
|
42
|
+
...command.schema,
|
|
43
|
+
flags: {
|
|
44
|
+
...propagated,
|
|
45
|
+
...command.schema.flags
|
|
46
|
+
}
|
|
47
|
+
};
|
|
48
|
+
}
|
|
49
|
+
/** Build the planner handoff for a matched command invocation. */
|
|
50
|
+
function buildCommandExecutionPlan(options) {
|
|
51
|
+
return {
|
|
52
|
+
command: options.command,
|
|
53
|
+
mergedSchema: mergeCommandSchema(options.command, options.commandPath),
|
|
54
|
+
argv: options.argv,
|
|
55
|
+
meta: options.meta,
|
|
56
|
+
plugins: options.plugins,
|
|
57
|
+
output: options.output,
|
|
58
|
+
help: options.help
|
|
59
|
+
};
|
|
60
|
+
}
|
|
61
|
+
function buildPlannerMatchOutcome(schema, command, commandPath, argv, help, output) {
|
|
62
|
+
return {
|
|
63
|
+
kind: "match",
|
|
64
|
+
plan: buildCommandExecutionPlan({
|
|
65
|
+
command,
|
|
66
|
+
commandPath,
|
|
67
|
+
argv,
|
|
68
|
+
meta: buildMeta(schema, help, command.schema.name),
|
|
69
|
+
plugins: schema.plugins,
|
|
70
|
+
output,
|
|
71
|
+
help
|
|
72
|
+
})
|
|
73
|
+
};
|
|
74
|
+
}
|
|
75
|
+
function canDelegateUnknownRootToDefault(command, input) {
|
|
76
|
+
return input === "" || command.schema.args.length > 0;
|
|
77
|
+
}
|
|
78
|
+
function findUnknownFlagBeforePositional(argv, flags, parseOptions) {
|
|
79
|
+
const lookup = buildFlagLookup(flags, parseOptions);
|
|
80
|
+
for (let index = 0; index < argv.length; index++) {
|
|
81
|
+
const token = argv[index];
|
|
82
|
+
if (token === void 0 || token === "--") return void 0;
|
|
83
|
+
if (token === "-" || !token.startsWith("-")) return void 0;
|
|
84
|
+
if (token.startsWith("--")) {
|
|
85
|
+
const equalsIndex = token.indexOf("=");
|
|
86
|
+
const name = token.slice(2, equalsIndex === -1 ? void 0 : equalsIndex);
|
|
87
|
+
const entry = lookup.get(name);
|
|
88
|
+
if (entry === void 0) return equalsIndex === -1 ? token : `--${name}`;
|
|
89
|
+
if (equalsIndex === -1 && flagExpectsValue(entry.schema)) index++;
|
|
90
|
+
continue;
|
|
91
|
+
}
|
|
92
|
+
const chars = token.slice(1);
|
|
93
|
+
for (let charIndex = 0; charIndex < chars.length; charIndex++) {
|
|
94
|
+
const char = chars.charAt(charIndex);
|
|
95
|
+
const entry = lookup.get(char);
|
|
96
|
+
if (entry === void 0) return `-${char}`;
|
|
97
|
+
if (!flagExpectsValue(entry.schema)) continue;
|
|
98
|
+
if (charIndex === chars.length - 1) index++;
|
|
99
|
+
break;
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* Scan the pre-`--`, `--json`-stripped head to locate the first command-dispatch
|
|
105
|
+
* token and detect a root-level `--help` / `-h` ahead of it.
|
|
106
|
+
*
|
|
107
|
+
* Value-flag arity is honoured (via `valueFlags`) so a flag value that happens
|
|
108
|
+
* to look like a command name is not mistaken for one — matching how
|
|
109
|
+
* {@linkcode dispatch} reads the same argv.
|
|
110
|
+
*
|
|
111
|
+
* @internal
|
|
112
|
+
*/
|
|
113
|
+
function scanRootHead(head, valueFlags) {
|
|
114
|
+
for (let index = 0; index < head.length; index++) {
|
|
115
|
+
const token = head[index];
|
|
116
|
+
if (token === void 0) continue;
|
|
117
|
+
if (token === "--help" || token === "-h") return {
|
|
118
|
+
helpBeforeCommand: true,
|
|
119
|
+
firstCommandToken: void 0,
|
|
120
|
+
commandTokenIndex: -1
|
|
121
|
+
};
|
|
122
|
+
if (token === "-" || !token.startsWith("-")) return {
|
|
123
|
+
helpBeforeCommand: false,
|
|
124
|
+
firstCommandToken: token,
|
|
125
|
+
commandTokenIndex: index
|
|
126
|
+
};
|
|
127
|
+
if (token.startsWith("--")) {
|
|
128
|
+
const equalsIndex = token.indexOf("=");
|
|
129
|
+
const name = token.slice(2, equalsIndex === -1 ? void 0 : equalsIndex);
|
|
130
|
+
const entry = valueFlags?.get(name);
|
|
131
|
+
if (entry !== void 0 && equalsIndex === -1 && flagExpectsValue(entry.schema)) index++;
|
|
132
|
+
continue;
|
|
133
|
+
}
|
|
134
|
+
const chars = token.slice(1);
|
|
135
|
+
for (let charIndex = 0; charIndex < chars.length; charIndex++) {
|
|
136
|
+
const entry = valueFlags?.get(chars.charAt(charIndex));
|
|
137
|
+
if (entry === void 0 || !flagExpectsValue(entry.schema)) continue;
|
|
138
|
+
if (charIndex === chars.length - 1) index++;
|
|
139
|
+
break;
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
return {
|
|
143
|
+
helpBeforeCommand: false,
|
|
144
|
+
firstCommandToken: void 0,
|
|
145
|
+
commandTokenIndex: -1
|
|
146
|
+
};
|
|
147
|
+
}
|
|
148
|
+
/**
|
|
149
|
+
* Detect and resolve the eager `--completions [shell]` flag before dispatch.
|
|
150
|
+
*
|
|
151
|
+
* Accepts `--completions <shell>` and `--completions=<shell>`. When no value is
|
|
152
|
+
* given (`--completions` alone, or followed by another flag), the shell is left
|
|
153
|
+
* `undefined` so the caller can auto-detect it from the environment. Scans only
|
|
154
|
+
* before a `--` separator so a literal positional survives.
|
|
155
|
+
*
|
|
156
|
+
* Returns `undefined` when the flag is absent, a `root-completions` outcome
|
|
157
|
+
* otherwise, or a `dispatch-error` when an explicit value names an unknown shell.
|
|
158
|
+
*
|
|
159
|
+
* @internal
|
|
160
|
+
*/
|
|
161
|
+
function planCompletionsFlag(argv, config) {
|
|
162
|
+
const separatorIndex = argv.indexOf("--");
|
|
163
|
+
const scanEnd = separatorIndex === -1 ? argv.length : separatorIndex;
|
|
164
|
+
for (let index = 0; index < scanEnd; index++) {
|
|
165
|
+
const token = argv[index];
|
|
166
|
+
if (token === void 0) continue;
|
|
167
|
+
let rawShell;
|
|
168
|
+
if (token === "--completions") {
|
|
169
|
+
const next = index + 1 < scanEnd ? argv[index + 1] : void 0;
|
|
170
|
+
rawShell = next !== void 0 && !next.startsWith("-") ? next : void 0;
|
|
171
|
+
} else if (token.startsWith("--completions=")) rawShell = token.slice(14);
|
|
172
|
+
else continue;
|
|
173
|
+
if (rawShell === void 0 || rawShell === "") return {
|
|
174
|
+
kind: "root-completions",
|
|
175
|
+
shell: void 0,
|
|
176
|
+
options: config.options
|
|
177
|
+
};
|
|
178
|
+
const shell = normalizeShell(rawShell);
|
|
179
|
+
if (shell === void 0 || !config.shells.includes(shell)) return {
|
|
180
|
+
kind: "dispatch-error",
|
|
181
|
+
error: new ParseError(`Unknown shell '${rawShell}'`, {
|
|
182
|
+
code: "INVALID_VALUE",
|
|
183
|
+
suggest: `Valid shells: ${config.shells.join(", ")}`
|
|
184
|
+
})
|
|
185
|
+
};
|
|
186
|
+
return {
|
|
187
|
+
kind: "root-completions",
|
|
188
|
+
shell,
|
|
189
|
+
options: config.options
|
|
190
|
+
};
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
/**
|
|
194
|
+
* Decide what to do with an argv invocation before any command executes.
|
|
195
|
+
*
|
|
196
|
+
* Handles root interception (`--help`, `--version`, `--completions <shell>`,
|
|
197
|
+
* bare `help` token), dispatches into the command tree, falls back to the
|
|
198
|
+
* default command, and produces structured errors for unknown commands/flags.
|
|
199
|
+
* @internal
|
|
200
|
+
*/
|
|
201
|
+
function planInvocation(options) {
|
|
202
|
+
const separatorIndex = options.argv.indexOf("--");
|
|
203
|
+
const head = separatorIndex === -1 ? options.argv : options.argv.slice(0, separatorIndex);
|
|
204
|
+
const tail = separatorIndex === -1 ? [] : options.argv.slice(separatorIndex);
|
|
205
|
+
const filteredHead = head.includes("--json") ? head.filter((arg) => arg !== "--json") : head;
|
|
206
|
+
const filteredArgv = separatorIndex === -1 ? filteredHead : [...filteredHead, ...tail];
|
|
207
|
+
const defaultCommand = options.schema.defaultCommand;
|
|
208
|
+
const rootValueFlags = defaultCommand !== void 0 ? buildFlagLookup(defaultCommand.schema.flags, options.schema.flagSettings) : void 0;
|
|
209
|
+
if (options.schema.version !== void 0 && (includesBeforeSeparator(options.argv, "--version") || includesBeforeSeparator(options.argv, "-V"))) return {
|
|
210
|
+
kind: "root-version",
|
|
211
|
+
version: options.schema.version
|
|
212
|
+
};
|
|
213
|
+
if (options.schema.completionsFlag !== void 0) {
|
|
214
|
+
const completionsOutcome = planCompletionsFlag(options.argv, options.schema.completionsFlag);
|
|
215
|
+
if (completionsOutcome !== void 0) return completionsOutcome;
|
|
216
|
+
}
|
|
217
|
+
const headScan = scanRootHead(filteredHead, rootValueFlags);
|
|
218
|
+
if (headScan.helpBeforeCommand) return {
|
|
219
|
+
kind: "root-help",
|
|
220
|
+
help: options.help
|
|
221
|
+
};
|
|
222
|
+
if (headScan.firstCommandToken === "help") {
|
|
223
|
+
if (!options.schema.commands.some((command) => command.schema.name === "help" || command.schema.aliases.includes("help"))) {
|
|
224
|
+
const rest = filteredArgv.slice(headScan.commandTokenIndex + 1);
|
|
225
|
+
if (rest.length === 0) return {
|
|
226
|
+
kind: "root-help",
|
|
227
|
+
help: options.help
|
|
228
|
+
};
|
|
229
|
+
return planInvocation({
|
|
230
|
+
...options,
|
|
231
|
+
argv: [...rest, "--help"]
|
|
232
|
+
});
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
if (options.schema.commands.length === 0 && defaultCommand === void 0) return {
|
|
236
|
+
kind: "dispatch-error",
|
|
237
|
+
error: new CLIError("No commands registered", {
|
|
238
|
+
code: "NO_ACTION",
|
|
239
|
+
suggest: "Add commands via .command() or .default() before calling .run()"
|
|
240
|
+
})
|
|
241
|
+
};
|
|
242
|
+
if (filteredArgv.length === 0 && defaultCommand === void 0) return {
|
|
243
|
+
kind: "root-help",
|
|
244
|
+
help: options.help
|
|
245
|
+
};
|
|
246
|
+
const result = dispatch(filteredArgv, buildRootCommandMap(defaultCommand !== void 0 && options.schema.defaultCommandRouted ? [...options.schema.commands, defaultCommand] : options.schema.commands), [], rootValueFlags, options.schema.flagSettings);
|
|
247
|
+
switch (result.kind) {
|
|
248
|
+
case "unknown": {
|
|
249
|
+
if (defaultCommand !== void 0 && result.parentPath.length === 0) {
|
|
250
|
+
if ((result.input !== "" ? findClosestCommand(result.input, result.candidates) : void 0) === void 0 && canDelegateUnknownRootToDefault(defaultCommand, result.input)) return buildPlannerMatchOutcome(options.schema, defaultCommand, [defaultCommand.schema], filteredArgv, options.help, options.output);
|
|
251
|
+
const unknownFlag = findUnknownFlagBeforePositional(filteredArgv, defaultCommand.schema.flags, options.schema.flagSettings);
|
|
252
|
+
if (unknownFlag !== void 0) return {
|
|
253
|
+
kind: "dispatch-error",
|
|
254
|
+
error: new ParseError(`Unknown flag ${unknownFlag}`, {
|
|
255
|
+
code: "UNKNOWN_FLAG",
|
|
256
|
+
suggest: `Run '${options.schema.name} --help' for available commands`
|
|
257
|
+
})
|
|
258
|
+
};
|
|
259
|
+
}
|
|
260
|
+
if (result.input === "") {
|
|
261
|
+
const unknownFlag = filteredArgv.find((token) => token.startsWith("-"));
|
|
262
|
+
if (unknownFlag === void 0) return {
|
|
263
|
+
kind: "root-help",
|
|
264
|
+
help: options.help
|
|
265
|
+
};
|
|
266
|
+
return {
|
|
267
|
+
kind: "dispatch-error",
|
|
268
|
+
error: new ParseError(`Unknown flag ${unknownFlag}`, {
|
|
269
|
+
code: "UNKNOWN_FLAG",
|
|
270
|
+
suggest: `Run '${options.schema.name} --help' for available commands`
|
|
271
|
+
})
|
|
272
|
+
};
|
|
273
|
+
}
|
|
274
|
+
const suggestion = findClosestCommand(result.input, result.candidates);
|
|
275
|
+
const scopePath = result.parentPath.length > 0 ? `${options.schema.name} ${result.parentPath.map((schema) => schema.name).join(" ")}` : options.schema.name;
|
|
276
|
+
return {
|
|
277
|
+
kind: "dispatch-error",
|
|
278
|
+
error: new ParseError(`Unknown command: ${result.input}`, {
|
|
279
|
+
code: "UNKNOWN_COMMAND",
|
|
280
|
+
suggest: suggestion !== void 0 ? `Did you mean '${suggestion}'?` : `Run '${scopePath} --help' for available commands`
|
|
281
|
+
})
|
|
282
|
+
};
|
|
283
|
+
}
|
|
284
|
+
case "needs-subcommand": {
|
|
285
|
+
const ancestorNames = result.commandPath.slice(0, -1).map((schema) => schema.name);
|
|
286
|
+
return {
|
|
287
|
+
kind: "needs-subcommand",
|
|
288
|
+
command: result.command,
|
|
289
|
+
commandPath: result.commandPath,
|
|
290
|
+
help: {
|
|
291
|
+
...options.help,
|
|
292
|
+
binName: [options.schema.name, ...ancestorNames].join(" ")
|
|
293
|
+
}
|
|
294
|
+
};
|
|
295
|
+
}
|
|
296
|
+
case "match": return buildPlannerMatchOutcome(options.schema, result.command, result.commandPath, result.remainingArgv, options.help, options.output);
|
|
297
|
+
}
|
|
298
|
+
}
|
|
299
|
+
//#endregion
|
|
300
|
+
export { buildCommandExecutionPlan, buildRootCommandMap, mergeCommandSchema, planInvocation };
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { DeprecationWarning } from "../resolve/contracts.mjs";
|
|
2
|
+
import "../resolve/index.mjs";
|
|
2
3
|
import { CommandMeta, CommandSchema, Out } from "../schema/command.mjs";
|
|
3
|
-
|
|
4
4
|
//#region src/core/cli/plugin.d.ts
|
|
5
5
|
/** Shared hook payload for a concrete command execution. */
|
|
6
6
|
interface PluginCommandContext {
|
package/dist/core/cli/plugin.mjs
CHANGED
|
@@ -1 +1,41 @@
|
|
|
1
|
-
|
|
1
|
+
//#region src/core/cli/plugin.ts
|
|
2
|
+
/**
|
|
3
|
+
* Create a CLI plugin from lifecycle hooks.
|
|
4
|
+
*
|
|
5
|
+
* @param hooks - Lifecycle hooks to register.
|
|
6
|
+
* @param name - Optional plugin name for diagnostics.
|
|
7
|
+
*
|
|
8
|
+
* @example
|
|
9
|
+
* ```ts
|
|
10
|
+
* import { cli, command, plugin } from '@kjanat/dreamcli';
|
|
11
|
+
*
|
|
12
|
+
* const deploy = command('deploy').action(({ out }) => {
|
|
13
|
+
* out.log('deploying');
|
|
14
|
+
* });
|
|
15
|
+
*
|
|
16
|
+
* const trace = plugin(
|
|
17
|
+
* {
|
|
18
|
+
* beforeParse: ({ argv, out }) => {
|
|
19
|
+
* out.info(`argv: ${argv.join(' ')}`);
|
|
20
|
+
* },
|
|
21
|
+
* afterResolve: ({ flags, args }) => {
|
|
22
|
+
* console.log({ flags, args });
|
|
23
|
+
* },
|
|
24
|
+
* },
|
|
25
|
+
* 'trace',
|
|
26
|
+
* );
|
|
27
|
+
*
|
|
28
|
+
* cli('mycli').plugin(trace).command(deploy).run();
|
|
29
|
+
* ```
|
|
30
|
+
*
|
|
31
|
+
* @returns A frozen {@link CLIPlugin} definition.
|
|
32
|
+
*/
|
|
33
|
+
function plugin(hooks, name) {
|
|
34
|
+
const frozenHooks = Object.freeze({ ...hooks });
|
|
35
|
+
return Object.freeze({
|
|
36
|
+
hooks: frozenHooks,
|
|
37
|
+
name
|
|
38
|
+
});
|
|
39
|
+
}
|
|
40
|
+
//#endregion
|
|
41
|
+
export { plugin };
|
|
@@ -1 +1,57 @@
|
|
|
1
|
-
|
|
1
|
+
//#region src/core/cli/propagate.ts
|
|
2
|
+
/**
|
|
3
|
+
* Collect propagated flags from a command path.
|
|
4
|
+
*
|
|
5
|
+
* The command path is an ordered array of {@linkcode CommandSchema} from the root
|
|
6
|
+
* ancestor to the target command that will actually execute. Each ancestor's
|
|
7
|
+
* flags marked `propagate: true` are accumulated. If a descendant (including
|
|
8
|
+
* the target) defines a flag with the same name — regardless of whether the
|
|
9
|
+
* descendant's flag has `propagate: true` — it shadows the ancestor's flag.
|
|
10
|
+
*
|
|
11
|
+
* The target command's own flags are **not** included in the result. This
|
|
12
|
+
* function returns only the *inherited* propagated flags that should be merged
|
|
13
|
+
* into the target command's flag set before resolution.
|
|
14
|
+
*
|
|
15
|
+
* @param commandPath - Ordered schemas from root ancestor to target (inclusive).
|
|
16
|
+
* Must contain at least one element (the target itself). When the path has
|
|
17
|
+
* only one element, no ancestors exist and the result is empty.
|
|
18
|
+
*
|
|
19
|
+
* @returns A record of propagated flag schemas keyed by flag name. Empty when
|
|
20
|
+
* the path has no ancestors or no ancestor flags have `propagate: true`.
|
|
21
|
+
*
|
|
22
|
+
* @example
|
|
23
|
+
* ```ts
|
|
24
|
+
* // Given: root (--verbose [propagate]) → db → migrate
|
|
25
|
+
* // Where migrate does NOT define --verbose
|
|
26
|
+
* const inherited = collectPropagatedFlags([rootSchema, dbSchema, migrateSchema]);
|
|
27
|
+
* // inherited = { verbose: <FlagSchema from root> }
|
|
28
|
+
*
|
|
29
|
+
* // If db also defines --verbose (shadowing root):
|
|
30
|
+
* const inherited2 = collectPropagatedFlags([rootSchema, dbSchemaWithVerbose, migrateSchema]);
|
|
31
|
+
* // inherited2 = { verbose: <FlagSchema from db> }
|
|
32
|
+
* ```
|
|
33
|
+
*/
|
|
34
|
+
function collectPropagatedFlags(commandPath) {
|
|
35
|
+
if (commandPath.length <= 1) return {};
|
|
36
|
+
const accumulated = {};
|
|
37
|
+
for (let i = 0; i < commandPath.length - 1; i++) {
|
|
38
|
+
const ancestor = commandPath[i];
|
|
39
|
+
if (ancestor === void 0) continue;
|
|
40
|
+
for (const [name, flagSchema] of Object.entries(ancestor.flags)) if (flagSchema.propagate) {
|
|
41
|
+
let shadowedByDescendant = false;
|
|
42
|
+
for (let j = i + 1; j < commandPath.length - 1; j++) {
|
|
43
|
+
const descendant = commandPath[j];
|
|
44
|
+
if (descendant !== void 0 && name in descendant.flags) {
|
|
45
|
+
shadowedByDescendant = true;
|
|
46
|
+
break;
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
if (!shadowedByDescendant) accumulated[name] = flagSchema;
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
const target = commandPath[commandPath.length - 1];
|
|
53
|
+
if (target !== void 0) for (const name of Object.keys(target.flags)) delete accumulated[name];
|
|
54
|
+
return accumulated;
|
|
55
|
+
}
|
|
56
|
+
//#endregion
|
|
57
|
+
export { collectPropagatedFlags };
|
|
@@ -1,6 +1,5 @@
|
|
|
1
1
|
import { HelpOptions } from "../help/index.mjs";
|
|
2
2
|
import { CommandSchema } from "../schema/command.mjs";
|
|
3
|
-
|
|
4
3
|
//#region src/core/cli/root-help.d.ts
|
|
5
4
|
/** Structural subset of `CLISchema` — avoids circular imports through the barrel. */
|
|
6
5
|
interface CLISchemaLike {
|
|
@@ -13,17 +12,33 @@ interface CLISchemaLike {
|
|
|
13
12
|
readonly defaultCommand: {
|
|
14
13
|
readonly schema: CommandSchema;
|
|
15
14
|
} | undefined;
|
|
15
|
+
/** Whether the default is also a named route — listed in `Commands:` when so. */
|
|
16
|
+
readonly defaultCommandRouted?: boolean | undefined;
|
|
16
17
|
readonly helpLinks?: {
|
|
17
18
|
readonly name: string | undefined;
|
|
18
19
|
readonly version: string | undefined;
|
|
19
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;
|
|
20
32
|
}
|
|
21
33
|
/**
|
|
22
34
|
* Generate root-level help text for the CLI program.
|
|
23
35
|
*
|
|
24
36
|
* Shows program name, version, description, usage line, and available
|
|
25
|
-
*
|
|
26
|
-
*
|
|
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.
|
|
27
42
|
*
|
|
28
43
|
* @internal
|
|
29
44
|
*/
|