@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,4 +1,6 @@
|
|
|
1
|
+
import { createFlagSchema } from "../schema/flag.mjs";
|
|
1
2
|
import { command } from "../schema/command.mjs";
|
|
3
|
+
import { BUILTIN_NAMES, BUILTIN_SPECS, builtinEnabled, builtinFlagForms } from "./builtins.mjs";
|
|
2
4
|
import { resolveRootSurface } from "./root-surface.mjs";
|
|
3
5
|
import { osc8, padEnd, wrapText } from "../help/ansi.mjs";
|
|
4
6
|
import { resolveHelpTheme } from "../help/theme.mjs";
|
|
@@ -23,6 +25,9 @@ import { formatFlagEntriesBlock, formatHelpSections } from "../help/index.mjs";
|
|
|
23
25
|
* `.completions({ as: 'flag' })` is active, the eager `--completions <shell>`
|
|
24
26
|
* flag is advertised in the `Flags:` section.
|
|
25
27
|
*
|
|
28
|
+
* A built-in released through `.builtins({ <name>: 'off' })` drops out of
|
|
29
|
+
* `Global options:`, and releasing `help` also drops the `--help` footer hint.
|
|
30
|
+
*
|
|
26
31
|
* @internal
|
|
27
32
|
*/
|
|
28
33
|
function formatRootHelp(schema, options) {
|
|
@@ -61,7 +66,7 @@ function formatRootHelp(schema, options) {
|
|
|
61
66
|
}
|
|
62
67
|
const globalOptions = formatGlobalOptionsSection(schema, width, theme);
|
|
63
68
|
if (globalOptions.length > 0) sections.push(globalOptions);
|
|
64
|
-
if (options?.footer ?? surface.hasVisibleSubcommands) {
|
|
69
|
+
if (builtinEnabled(schema.builtins, "help") && (options?.footer ?? surface.hasVisibleSubcommands)) {
|
|
65
70
|
const footerPlaceholder = surface.hasVisibleSubcommands ? defaultCommand !== void 0 ? " [command]" : " <command>" : "";
|
|
66
71
|
sections.push(`Run '${binName}${footerPlaceholder} --help' for more information.`);
|
|
67
72
|
}
|
|
@@ -98,30 +103,10 @@ function resolveSurfaceCommand(schema, defaultCommand) {
|
|
|
98
103
|
* @internal
|
|
99
104
|
*/
|
|
100
105
|
function completionsFlagSchema(shells) {
|
|
101
|
-
return {
|
|
102
|
-
kind: "enum",
|
|
103
|
-
presence: "optional",
|
|
104
|
-
defaultValue: void 0,
|
|
105
|
-
aliases: [],
|
|
106
|
-
envVar: void 0,
|
|
107
|
-
configPath: void 0,
|
|
106
|
+
return createFlagSchema("enum", {
|
|
108
107
|
description: "Print a shell completion script and exit",
|
|
109
|
-
enumValues: shells
|
|
110
|
-
|
|
111
|
-
separator: void 0,
|
|
112
|
-
unique: false,
|
|
113
|
-
numberConstraints: void 0,
|
|
114
|
-
stringConstraints: void 0,
|
|
115
|
-
pathChecks: void 0,
|
|
116
|
-
valueHint: void 0,
|
|
117
|
-
prompt: void 0,
|
|
118
|
-
parseFn: void 0,
|
|
119
|
-
standard: void 0,
|
|
120
|
-
deprecated: void 0,
|
|
121
|
-
propagate: false,
|
|
122
|
-
negation: void 0,
|
|
123
|
-
duplicates: "last"
|
|
124
|
-
};
|
|
108
|
+
enumValues: shells
|
|
109
|
+
});
|
|
125
110
|
}
|
|
126
111
|
/**
|
|
127
112
|
* Render the header line (`name vX.Y.Z`).
|
|
@@ -168,7 +153,8 @@ function formatRootCommandsSection(visibleCommands, defaultName, width, theme) {
|
|
|
168
153
|
}
|
|
169
154
|
const descCol = 2 + maxNameLen + GAP;
|
|
170
155
|
for (const cmd of visibleCommands) {
|
|
171
|
-
const
|
|
156
|
+
const label = cmd.name === defaultName ? `${theme.command(cmd.name)}${theme.annotation(DEFAULT_TAG)}` : theme.command(cmd.name);
|
|
157
|
+
const padded = padEnd(` ${label}`, descCol);
|
|
172
158
|
const desc = cmd.description ?? "";
|
|
173
159
|
if (desc.length === 0) lines.push(padded.trimEnd());
|
|
174
160
|
else lines.push(`${padded}${wrapText(desc, width, descCol)}`);
|
|
@@ -178,38 +164,42 @@ function formatRootCommandsSection(visibleCommands, defaultName, width, theme) {
|
|
|
178
164
|
/**
|
|
179
165
|
* Build the `Global options:` section advertising the active built-in flags.
|
|
180
166
|
*
|
|
181
|
-
*
|
|
182
|
-
*
|
|
183
|
-
*
|
|
184
|
-
*
|
|
167
|
+
* `-h, --help`, `--json`, and `-q, --quiet` are listed in {@link BUILTIN_NAMES}
|
|
168
|
+
* order while the root owns them; `.builtins({ <name>: 'off' })` hands the token
|
|
169
|
+
* to the commands and drops the entry. `-V, --version` is spliced in after the
|
|
170
|
+
* `help` entry, so it keeps its place whether or not the root still owns
|
|
171
|
+
* `--help`, and is shown only when the program declares a version.
|
|
172
|
+
* `--config <path>` is listed only when `.config()` enabled config discovery.
|
|
173
|
+
* The eager `--completions` flag is intentionally omitted, since it is
|
|
174
|
+
* advertised via the inline surface when active.
|
|
185
175
|
*
|
|
186
|
-
* @param schema - The CLI schema (read for `version` and `
|
|
176
|
+
* @param schema - The CLI schema (read for `version`, `configSettings`, and `builtins`).
|
|
187
177
|
* @param width - Terminal width for description wrapping.
|
|
188
178
|
* @param theme - Theme applied to the title and flag forms.
|
|
189
|
-
* @returns Formatted `Global options:` block
|
|
179
|
+
* @returns Formatted `Global options:` block, or `''` when nothing is active.
|
|
190
180
|
* @internal
|
|
191
181
|
*/
|
|
192
182
|
function formatGlobalOptionsSection(schema, width, theme) {
|
|
193
|
-
const entries = [
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
}
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
});
|
|
183
|
+
const entries = [];
|
|
184
|
+
const pushBuiltin = (name) => {
|
|
185
|
+
if (!builtinEnabled(schema.builtins, name)) return;
|
|
186
|
+
entries.push({
|
|
187
|
+
left: theme.flag(builtinFlagForms(name)),
|
|
188
|
+
description: BUILTIN_SPECS[name].description
|
|
189
|
+
});
|
|
190
|
+
};
|
|
191
|
+
for (const name of BUILTIN_NAMES) {
|
|
192
|
+
pushBuiltin(name);
|
|
193
|
+
if (name === "help" && schema.version !== void 0) entries.push({
|
|
194
|
+
left: theme.flag("-V, --version"),
|
|
195
|
+
description: "Print the version number and exit"
|
|
196
|
+
});
|
|
197
|
+
}
|
|
209
198
|
if (schema.configSettings !== void 0) entries.push({
|
|
210
199
|
left: `${theme.flag("--config")} ${theme.placeholder("<path>")}`,
|
|
211
200
|
description: "Load configuration from the given file"
|
|
212
201
|
});
|
|
202
|
+
if (entries.length === 0) return "";
|
|
213
203
|
return formatFlagEntriesBlock(theme.sectionTitle("Global options:"), entries, width);
|
|
214
204
|
}
|
|
215
205
|
/**
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {}
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
import { ParseError } from "../errors/index.mjs";
|
|
2
|
+
import { flag } from "../schema/flag.mjs";
|
|
3
|
+
import { coerceFlagValue } from "../parse/index.mjs";
|
|
4
|
+
import { BUILTIN_SPECS, builtinEnabled } from "./builtins.mjs";
|
|
5
|
+
//#region src/core/cli/root-output-flags.ts
|
|
6
|
+
/**
|
|
7
|
+
* The root output-flag layer: `--json` and `--quiet`/`-q`.
|
|
8
|
+
*
|
|
9
|
+
* These flags belong to the CLI root instead of any command schema, so every
|
|
10
|
+
* layer that needs the output mode (planner dispatch, `.execute()`, `.run()`
|
|
11
|
+
* preflight, `resolveRenderContext()`, testkit `runCommand()`) reads and strips
|
|
12
|
+
* them through {@linkcode readRootOutputFlags}. Values follow `flag.boolean()`:
|
|
13
|
+
* bare presence, `=true`/`=1`, `=false`/`=0`, last occurrence wins, and an
|
|
14
|
+
* invalid literal produces the parser's own `INVALID_VALUE` error.
|
|
15
|
+
*
|
|
16
|
+
* A built-in released through `.builtins({ json: 'off' })` is neither read nor
|
|
17
|
+
* stripped here, so its tokens reach normal command parsing (#86).
|
|
18
|
+
*
|
|
19
|
+
* @module dreamcli/core/cli/root-output-flags
|
|
20
|
+
* @internal
|
|
21
|
+
*/
|
|
22
|
+
/** The schema root `--json`/`--quiet` share with a command-level boolean flag. */
|
|
23
|
+
const rootBooleanSchema = flag.boolean().schema;
|
|
24
|
+
/** The built-ins whose tokens this module reads, in stable order. */
|
|
25
|
+
const ROOT_OUTPUT_NAMES = ["json", "quiet"];
|
|
26
|
+
/** Index the spellings of one kind, taken from the shared built-in table. */
|
|
27
|
+
function spellingIndex(kind) {
|
|
28
|
+
const index = /* @__PURE__ */ new Map();
|
|
29
|
+
for (const name of ROOT_OUTPUT_NAMES) for (const spelling of BUILTIN_SPECS[name][kind]) index.set(spelling, name);
|
|
30
|
+
return index;
|
|
31
|
+
}
|
|
32
|
+
/** Long spellings, the only ones the tokenizer lets carry an inline `=value`. */
|
|
33
|
+
const ROOT_LONG_SPELLINGS = spellingIndex("long");
|
|
34
|
+
/** Short spellings, which have no inline-value form. */
|
|
35
|
+
const ROOT_SHORT_SPELLINGS = spellingIndex("short");
|
|
36
|
+
/** Coerce an inline `=value` the way a command-level boolean flag coerces it. */
|
|
37
|
+
function coerceRootValue(name, spelling, raw) {
|
|
38
|
+
try {
|
|
39
|
+
return {
|
|
40
|
+
kind: "flag",
|
|
41
|
+
name,
|
|
42
|
+
selection: coerceFlagValue(name, raw, rootBooleanSchema, spelling) === true ? "on" : "off"
|
|
43
|
+
};
|
|
44
|
+
} catch (error) {
|
|
45
|
+
if (error instanceof ParseError) return {
|
|
46
|
+
kind: "invalid",
|
|
47
|
+
name,
|
|
48
|
+
error
|
|
49
|
+
};
|
|
50
|
+
throw error;
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
/** Look up a spelling, skipping built-ins the CLI released to its commands. */
|
|
54
|
+
function ownedName(index, spelling, builtins) {
|
|
55
|
+
const name = index.get(spelling);
|
|
56
|
+
if (name === void 0 || !builtinEnabled(builtins, name)) return void 0;
|
|
57
|
+
return name;
|
|
58
|
+
}
|
|
59
|
+
/** Resolve one pre-separator argv token against the root output flags. */
|
|
60
|
+
function matchRootToken(token, builtins) {
|
|
61
|
+
const shortName = ownedName(ROOT_SHORT_SPELLINGS, token, builtins);
|
|
62
|
+
if (shortName !== void 0) return {
|
|
63
|
+
kind: "flag",
|
|
64
|
+
name: shortName,
|
|
65
|
+
selection: "on"
|
|
66
|
+
};
|
|
67
|
+
const bareName = ownedName(ROOT_LONG_SPELLINGS, token, builtins);
|
|
68
|
+
if (bareName !== void 0) return {
|
|
69
|
+
kind: "flag",
|
|
70
|
+
name: bareName,
|
|
71
|
+
selection: "on"
|
|
72
|
+
};
|
|
73
|
+
const equals = token.indexOf("=");
|
|
74
|
+
if (equals === -1) return { kind: "unrelated" };
|
|
75
|
+
const spelling = token.slice(0, equals);
|
|
76
|
+
const valuedName = ownedName(ROOT_LONG_SPELLINGS, spelling, builtins);
|
|
77
|
+
if (valuedName === void 0) return { kind: "unrelated" };
|
|
78
|
+
return coerceRootValue(valuedName, spelling, token.slice(equals + 1));
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* Read and strip the root output flags from argv.
|
|
82
|
+
*
|
|
83
|
+
* Only tokens before the `--` end-of-options separator are read or stripped, so
|
|
84
|
+
* a literal after `--` reaches the command unchanged (#28). Repeated
|
|
85
|
+
* occurrences follow the `'last'` duplicate policy `flag.boolean()` defaults to.
|
|
86
|
+
*
|
|
87
|
+
* A `'failed'` result still carries the selections and the stripped argv, so a
|
|
88
|
+
* valid `--json` governs how the failure renders and a help or version request
|
|
89
|
+
* can still be honoured ahead of it.
|
|
90
|
+
*
|
|
91
|
+
* @param argv - Raw argv tokens (excluding the binary/script path).
|
|
92
|
+
* @param builtins - Built-in state; a released built-in's tokens are left in
|
|
93
|
+
* argv untouched. `undefined` keeps both built-ins on.
|
|
94
|
+
* @returns The selections, the stripped argv, and the first invalid value's
|
|
95
|
+
* error when one occurred.
|
|
96
|
+
* @internal
|
|
97
|
+
*/
|
|
98
|
+
function readRootOutputFlags(argv, builtins) {
|
|
99
|
+
const separatorIndex = argv.indexOf("--");
|
|
100
|
+
const head = separatorIndex === -1 ? argv : argv.slice(0, separatorIndex);
|
|
101
|
+
const selections = {
|
|
102
|
+
json: "absent",
|
|
103
|
+
quiet: "absent"
|
|
104
|
+
};
|
|
105
|
+
const keptHead = [];
|
|
106
|
+
const errors = /* @__PURE__ */ new Map();
|
|
107
|
+
let stripped = false;
|
|
108
|
+
for (const token of head) {
|
|
109
|
+
const match = matchRootToken(token, builtins);
|
|
110
|
+
if (match.kind === "unrelated") {
|
|
111
|
+
keptHead.push(token);
|
|
112
|
+
continue;
|
|
113
|
+
}
|
|
114
|
+
stripped = true;
|
|
115
|
+
if (match.kind === "invalid") {
|
|
116
|
+
errors.delete(match.name);
|
|
117
|
+
errors.set(match.name, match.error);
|
|
118
|
+
continue;
|
|
119
|
+
}
|
|
120
|
+
selections[match.name] = match.selection;
|
|
121
|
+
errors.delete(match.name);
|
|
122
|
+
}
|
|
123
|
+
const strippedArgv = !stripped ? argv : separatorIndex === -1 ? keptHead : [...keptHead, ...argv.slice(separatorIndex)];
|
|
124
|
+
const resolved = {
|
|
125
|
+
json: selections.json,
|
|
126
|
+
quiet: selections.quiet,
|
|
127
|
+
argv: strippedArgv
|
|
128
|
+
};
|
|
129
|
+
const error = errors.values().next().value;
|
|
130
|
+
return error !== void 0 ? {
|
|
131
|
+
kind: "failed",
|
|
132
|
+
...resolved,
|
|
133
|
+
error
|
|
134
|
+
} : {
|
|
135
|
+
kind: "ok",
|
|
136
|
+
...resolved
|
|
137
|
+
};
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* Resolve JSON mode from the argv selection and an explicit override.
|
|
141
|
+
*
|
|
142
|
+
* An explicit `--json=false` wins over the override; the override applies when
|
|
143
|
+
* argv says nothing.
|
|
144
|
+
*
|
|
145
|
+
* @param flags - Result of {@linkcode readRootOutputFlags}.
|
|
146
|
+
* @param override - Caller-supplied `jsonMode`.
|
|
147
|
+
* @returns Whether the run renders JSON.
|
|
148
|
+
* @internal
|
|
149
|
+
*/
|
|
150
|
+
function resolveRootJsonMode(flags, override) {
|
|
151
|
+
if (flags.json === "absent") return override === true;
|
|
152
|
+
return flags.json === "on";
|
|
153
|
+
}
|
|
154
|
+
/**
|
|
155
|
+
* Resolve verbosity from the argv selection and an explicit override.
|
|
156
|
+
*
|
|
157
|
+
* @param flags - Result of {@linkcode readRootOutputFlags}.
|
|
158
|
+
* @param override - Caller-supplied verbosity.
|
|
159
|
+
* @returns `'quiet'` for `--quiet`, `'normal'` for `--quiet=false`, and the
|
|
160
|
+
* override when argv says nothing.
|
|
161
|
+
* @internal
|
|
162
|
+
*/
|
|
163
|
+
function resolveRootVerbosity(flags, override) {
|
|
164
|
+
if (flags.quiet === "on") return "quiet";
|
|
165
|
+
if (flags.quiet === "off") return "normal";
|
|
166
|
+
return override;
|
|
167
|
+
}
|
|
168
|
+
//#endregion
|
|
169
|
+
export { readRootOutputFlags, resolveRootJsonMode, resolveRootVerbosity };
|
|
@@ -1,68 +1 @@
|
|
|
1
|
-
|
|
2
|
-
//#region src/core/cli/root-surface.d.ts
|
|
3
|
-
/**
|
|
4
|
-
* Structural CLI shape needed for root-surface analysis.
|
|
5
|
-
*
|
|
6
|
-
* Uses structural typing to avoid importing the full `CLISchema` and
|
|
7
|
-
* creating unnecessary cross-module coupling.
|
|
8
|
-
*
|
|
9
|
-
* @internal
|
|
10
|
-
*/
|
|
11
|
-
interface RootSurfaceSchemaLike {
|
|
12
|
-
readonly commands: ReadonlyArray<{
|
|
13
|
-
readonly schema: CommandSchema;
|
|
14
|
-
}>;
|
|
15
|
-
readonly defaultCommand: {
|
|
16
|
-
readonly schema: CommandSchema;
|
|
17
|
-
} | undefined;
|
|
18
|
-
/**
|
|
19
|
-
* Whether the default command is also exposed as a named route
|
|
20
|
-
* (`.default(cmd, { route: true })`). Optional so hand-built schema-like
|
|
21
|
-
* objects default to the surface-only behavior.
|
|
22
|
-
*/
|
|
23
|
-
readonly defaultCommandRouted?: boolean | undefined;
|
|
24
|
-
}
|
|
25
|
-
/**
|
|
26
|
-
* Normalized root shape shared by help and completion logic.
|
|
27
|
-
*
|
|
28
|
-
* Since v0.3 the default command is a distinct root *surface* rather than a
|
|
29
|
-
* named subcommand: `.default()` no longer registers it under
|
|
30
|
-
* {@link RootSurfaceSchemaLike.commands}. To stay robust against callers that
|
|
31
|
-
* still place the default in the command list (e.g. hand-built test schemas),
|
|
32
|
-
* {@link resolveRootSurface} always derives {@link RootSurface.visibleSubcommands}
|
|
33
|
-
* by excluding the default command from the visible command list.
|
|
34
|
-
*
|
|
35
|
-
* @internal
|
|
36
|
-
*/
|
|
37
|
-
interface RootSurface {
|
|
38
|
-
/** All visible top-level commands as declared in `schema.commands`. */
|
|
39
|
-
readonly visibleCommands: readonly CommandSchema[];
|
|
40
|
-
/** Visible real subcommands — `visibleCommands` minus the default command. */
|
|
41
|
-
readonly visibleSubcommands: readonly CommandSchema[];
|
|
42
|
-
/** The visible default command, or `undefined` when none exists or it is hidden. */
|
|
43
|
-
readonly visibleDefaultCommand: CommandSchema | undefined;
|
|
44
|
-
/** Whether a visible default command exists. */
|
|
45
|
-
readonly hasVisibleDefault: boolean;
|
|
46
|
-
/** Whether any visible real subcommands exist (the default does not count). */
|
|
47
|
-
readonly hasVisibleSubcommands: boolean;
|
|
48
|
-
/**
|
|
49
|
-
* Whether the visible default is also a named route (`.default(cmd, { route:
|
|
50
|
-
* true })`), meaning it should be listed in `Commands:` beside its siblings
|
|
51
|
-
* in addition to being rendered as the root surface.
|
|
52
|
-
*/
|
|
53
|
-
readonly defaultRouted: boolean;
|
|
54
|
-
}
|
|
55
|
-
/**
|
|
56
|
-
* Resolve the visible shape of the CLI root.
|
|
57
|
-
*
|
|
58
|
-
* Hidden commands are excluded from the visible command list. Hidden
|
|
59
|
-
* default commands remain executable, but are not surfaced through
|
|
60
|
-
* help or completions. The default command is reported separately from the
|
|
61
|
-
* real subcommands so help and completion can render it as the root surface
|
|
62
|
-
* instead of echoing it as a pseudo-subcommand.
|
|
63
|
-
*
|
|
64
|
-
* @internal
|
|
65
|
-
*/
|
|
66
|
-
declare function resolveRootSurface(schema: RootSurfaceSchemaLike): RootSurface;
|
|
67
|
-
//#endregion
|
|
68
|
-
export { type RootSurface, type RootSurfaceSchemaLike, resolveRootSurface };
|
|
1
|
+
export {}
|
|
@@ -11,8 +11,8 @@
|
|
|
11
11
|
* @internal
|
|
12
12
|
*/
|
|
13
13
|
function resolveRootSurface(schema) {
|
|
14
|
-
const visibleCommands = schema.commands.
|
|
15
|
-
const rawDefaultCommand = schema.defaultCommand
|
|
14
|
+
const visibleCommands = schema.commands.filter((command) => !command.hidden);
|
|
15
|
+
const rawDefaultCommand = schema.defaultCommand;
|
|
16
16
|
const visibleDefaultCommand = rawDefaultCommand !== void 0 && !rawDefaultCommand.hidden ? rawDefaultCommand : void 0;
|
|
17
17
|
const visibleSubcommands = visibleDefaultCommand !== void 0 ? visibleCommands.filter((command) => command.name !== visibleDefaultCommand.name) : visibleCommands;
|
|
18
18
|
return {
|
|
@@ -1,199 +1 @@
|
|
|
1
|
-
|
|
2
|
-
import "../output/index.mjs";
|
|
3
|
-
import { PromptEngine } from "../prompt/index.mjs";
|
|
4
|
-
import { CLIPlugin } from "./plugin.mjs";
|
|
5
|
-
import { CLIError } from "../errors/index.mjs";
|
|
6
|
-
import { HelpThemeFactory } from "../help/theme.mjs";
|
|
7
|
-
import "../help/index.mjs";
|
|
8
|
-
import { CommandSchema, ErasedCommand } from "../schema/command.mjs";
|
|
9
|
-
import { ParseOptions } from "../parse/index.mjs";
|
|
10
|
-
import { RuntimeAdapter } from "../../runtime/adapter.mjs";
|
|
11
|
-
import { PackageJsonData } from "../config/package-json.mjs";
|
|
12
|
-
import { HelpLinks } from "./help-links.mjs";
|
|
13
|
-
import { CompletionOptions } from "../completion/shells/shared.mjs";
|
|
14
|
-
import { Shell } from "../completion/index.mjs";
|
|
15
|
-
import { FormatLoader } from "../config/index.mjs";
|
|
16
|
-
//#region src/core/cli/runtime-preflight.d.ts
|
|
17
|
-
/** Config discovery settings extracted from CLISchema for preflight use. @internal */
|
|
18
|
-
interface RuntimeConfigSettings {
|
|
19
|
-
/** Application name used to locate config files (e.g. `~/.config/<appName>/`). */
|
|
20
|
-
readonly appName: string;
|
|
21
|
-
/** Optional format loaders (JSON/YAML/TOML); `undefined` uses built-in JSON. */
|
|
22
|
-
readonly loaders: readonly FormatLoader[] | undefined;
|
|
23
|
-
}
|
|
24
|
-
/**
|
|
25
|
-
* Manifest discovery settings extracted from CLISchema for preflight use.
|
|
26
|
-
*
|
|
27
|
-
* Mirrors the public `ResolvedManifestSettings` shape (consumed structurally),
|
|
28
|
-
* named with the `Runtime` prefix to match its {@link RuntimeConfigSettings}
|
|
29
|
-
* sibling and avoid colliding with the exported public type.
|
|
30
|
-
* @internal
|
|
31
|
-
*/
|
|
32
|
-
interface RuntimeManifestSettings {
|
|
33
|
-
/** Whether to infer the CLI binary name from `bin` keys or `name`. */
|
|
34
|
-
readonly inferName: boolean;
|
|
35
|
-
/** Strip a leading `@scope/` from the inferred `name` fallback. */
|
|
36
|
-
readonly stripScope: boolean;
|
|
37
|
-
/** Explicit anchor (resolved path) for discovery; `undefined` falls back to `adapter.cwd`. */
|
|
38
|
-
readonly from: string | undefined;
|
|
39
|
-
/** Candidate manifest filenames in priority order. */
|
|
40
|
-
readonly files: readonly string[];
|
|
41
|
-
/** Pre-loaded data; when set, discovery is skipped entirely. */
|
|
42
|
-
readonly data: PackageJsonData | undefined;
|
|
43
|
-
}
|
|
44
|
-
/**
|
|
45
|
-
* Structural subset of CLISchema used by runtime preflight.
|
|
46
|
-
*
|
|
47
|
-
* Decouples adapter-driven sourcing (config, package.json, stdin) from the
|
|
48
|
-
* full CLIBuilder surface so preflight can be tested independently.
|
|
49
|
-
* @internal
|
|
50
|
-
*/
|
|
51
|
-
interface RuntimePreflightSchemaLike {
|
|
52
|
-
/** CLI program name; may be overridden by package.json discovery or inheritance. */
|
|
53
|
-
readonly name: string;
|
|
54
|
-
/** Whether this CLI inherits its name from a parent (nested CLI embedding). */
|
|
55
|
-
readonly inheritName: boolean;
|
|
56
|
-
/** Declared version; `undefined` means version will be inferred from package.json if available. */
|
|
57
|
-
readonly version: string | undefined;
|
|
58
|
-
/** Declared description; `undefined` allows package.json inference. */
|
|
59
|
-
readonly description: string | undefined;
|
|
60
|
-
/** Registered top-level commands for dispatch planning during stdin detection. */
|
|
61
|
-
readonly commands: readonly ErasedCommand[];
|
|
62
|
-
/** Fallback command when no subcommand token matches. */
|
|
63
|
-
readonly defaultCommand: ErasedCommand | undefined;
|
|
64
|
-
/** Whether the default command is also exposed as a named top-level route. */
|
|
65
|
-
readonly defaultCommandRouted: boolean;
|
|
66
|
-
/** Config file discovery settings; `undefined` disables config loading. */
|
|
67
|
-
readonly configSettings: RuntimeConfigSettings | undefined;
|
|
68
|
-
/** Package.json discovery settings; `undefined` disables package.json inference. */
|
|
69
|
-
readonly packageJsonSettings: RuntimeManifestSettings | undefined;
|
|
70
|
-
/** Root-help header link targets; `undefined` fields may be derived from package.json. */
|
|
71
|
-
readonly helpLinks: HelpLinks | undefined;
|
|
72
|
-
/** Whether `.completions()` registered the built-in completions command/flag. */
|
|
73
|
-
readonly hasBuiltInCompletions: boolean;
|
|
74
|
-
/** Eager `--completions <shell>` flag config; `undefined` disables interception. */
|
|
75
|
-
readonly completionsFlag: {
|
|
76
|
-
readonly shells: readonly Shell[];
|
|
77
|
-
readonly options: CompletionOptions | undefined;
|
|
78
|
-
} | undefined;
|
|
79
|
-
/** Consumer-configured root-help defaults. */
|
|
80
|
-
readonly helpConfig: {
|
|
81
|
-
readonly inlineDefault?: boolean;
|
|
82
|
-
readonly showDefaultInCommands?: boolean;
|
|
83
|
-
readonly footer?: boolean;
|
|
84
|
-
readonly width?: number;
|
|
85
|
-
readonly hyperlinks?: boolean;
|
|
86
|
-
readonly theme?: HelpThemeFactory;
|
|
87
|
-
} | undefined;
|
|
88
|
-
/** Flag-parsing behavior settings (e.g. case parity). */
|
|
89
|
-
readonly flagSettings: ParseOptions | undefined;
|
|
90
|
-
/** Plugins forwarded into the execution pipeline. */
|
|
91
|
-
readonly plugins: readonly CLIPlugin[];
|
|
92
|
-
}
|
|
93
|
-
/**
|
|
94
|
-
* Caller-supplied overrides for runtime preflight.
|
|
95
|
-
*
|
|
96
|
-
* When provided, these bypass adapter auto-detection (useful for testing
|
|
97
|
-
* and the `CLIRunOptions` public surface).
|
|
98
|
-
* @internal
|
|
99
|
-
*/
|
|
100
|
-
interface RuntimePreflightOptions {
|
|
101
|
-
/** Environment variables override; bypasses adapter env when set. */
|
|
102
|
-
readonly env?: Readonly<Record<string, string | undefined>>;
|
|
103
|
-
/** Pre-loaded config object; skips config file discovery when set. */
|
|
104
|
-
readonly config?: Readonly<Record<string, unknown>>;
|
|
105
|
-
/** Pre-read stdin data; `null` means stdin was explicitly empty. */
|
|
106
|
-
readonly stdinData?: string | null;
|
|
107
|
-
/** Custom prompt engine; bypasses terminal prompter auto-creation. */
|
|
108
|
-
readonly prompter?: PromptEngine;
|
|
109
|
-
/** Output verbosity level override. */
|
|
110
|
-
readonly verbosity?: Verbosity;
|
|
111
|
-
/** Force JSON output mode regardless of `--json` flag presence. */
|
|
112
|
-
readonly jsonMode?: boolean;
|
|
113
|
-
/** TTY detection override; bypasses adapter TTY check. */
|
|
114
|
-
readonly isTTY?: boolean;
|
|
115
|
-
/** Filesystem probe override for `flag.path()` checks; bypasses the adapter probe. */
|
|
116
|
-
readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
|
|
117
|
-
/** Directory creation override for `flag.path()` `create` checks; bypasses the adapter. */
|
|
118
|
-
readonly mkdir?: (path: string) => Promise<void>;
|
|
119
|
-
}
|
|
120
|
-
/**
|
|
121
|
-
* Fully resolved runtime inputs ready for the execution pipeline.
|
|
122
|
-
*
|
|
123
|
-
* All adapter vs. caller-override decisions are settled by the time this
|
|
124
|
-
* is constructed; the executor treats these as final truth.
|
|
125
|
-
* @internal
|
|
126
|
-
*/
|
|
127
|
-
interface RuntimeExecutionInputs {
|
|
128
|
-
/** Resolved environment variables (from adapter or caller override). */
|
|
129
|
-
readonly env: Readonly<Record<string, string | undefined>>;
|
|
130
|
-
/** Whether stdout is a TTY (controls color, spinners, interactive prompts). */
|
|
131
|
-
readonly isTTY: boolean;
|
|
132
|
-
/** Whether structured JSON output mode is active. */
|
|
133
|
-
readonly jsonMode: boolean;
|
|
134
|
-
/** Output verbosity level. */
|
|
135
|
-
readonly verbosity: Verbosity;
|
|
136
|
-
/** Pre-read stdin data if the invocation declared stdin-mode args. */
|
|
137
|
-
readonly stdinData?: string | null;
|
|
138
|
-
/** Prompt engine for interactive flag resolution; absent in non-TTY. */
|
|
139
|
-
readonly prompter?: PromptEngine;
|
|
140
|
-
/** Loaded config data for the config resolution step. */
|
|
141
|
-
readonly config?: Readonly<Record<string, unknown>>;
|
|
142
|
-
/** Filesystem probe (from the adapter) for `flag.path()` checks. */
|
|
143
|
-
readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
|
|
144
|
-
/** Directory creation (from the adapter) for `flag.path()` `create` checks. */
|
|
145
|
-
readonly mkdir?: (path: string) => Promise<void>;
|
|
146
|
-
}
|
|
147
|
-
/** Preflight succeeded — all runtime inputs are resolved and ready for execution. @internal */
|
|
148
|
-
interface ReadyRuntimePreflight {
|
|
149
|
-
/** Discriminant — preflight completed without errors. */
|
|
150
|
-
readonly kind: 'ready';
|
|
151
|
-
/** Schema after package.json discovery and name inheritance applied. */
|
|
152
|
-
readonly schema: RuntimePreflightSchemaLike;
|
|
153
|
-
/** Argv with valid runtime `--config` tokens stripped out. */
|
|
154
|
-
readonly filteredArgv: readonly string[];
|
|
155
|
-
/** Fully resolved runtime inputs for the execution pipeline. */
|
|
156
|
-
readonly inputs: RuntimeExecutionInputs;
|
|
157
|
-
}
|
|
158
|
-
/** Preflight failed during config file discovery/loading. @internal */
|
|
159
|
-
interface RuntimeConfigErrorPreflight {
|
|
160
|
-
/** Discriminant — config loading produced a structured error. */
|
|
161
|
-
readonly kind: 'config-error';
|
|
162
|
-
/** The config discovery/parse error to render. */
|
|
163
|
-
readonly error: CLIError;
|
|
164
|
-
/** Whether JSON output was requested (needed to choose error rendering). */
|
|
165
|
-
readonly jsonMode: boolean;
|
|
166
|
-
}
|
|
167
|
-
/** Discriminated union of preflight outcomes — either ready or config-error. @internal */
|
|
168
|
-
type RuntimePreflightResult = ReadyRuntimePreflight | RuntimeConfigErrorPreflight;
|
|
169
|
-
/** Options bag for {@linkcode prepareRuntimePreflight}. @internal */
|
|
170
|
-
interface PrepareRuntimePreflightOptions {
|
|
171
|
-
/** CLI schema subset driving preflight decisions. */
|
|
172
|
-
readonly schema: RuntimePreflightSchemaLike;
|
|
173
|
-
/** Runtime adapter providing argv, env, stdin, and filesystem access. */
|
|
174
|
-
readonly adapter: RuntimeAdapter;
|
|
175
|
-
/** Caller-supplied overrides; `undefined` means auto-detect everything. */
|
|
176
|
-
readonly options: RuntimePreflightOptions | undefined;
|
|
177
|
-
/** Name inherited from a parent CLI (nested embedding); `undefined` for standalone. */
|
|
178
|
-
readonly inheritedName: string | undefined;
|
|
179
|
-
}
|
|
180
|
-
/** Extract and strip valid runtime `--config` forms from argv, returning path + filtered tokens. @internal */
|
|
181
|
-
declare function extractConfigFlag(argv: readonly string[]): {
|
|
182
|
-
readonly configPath: string | undefined;
|
|
183
|
-
readonly filteredArgv: readonly string[];
|
|
184
|
-
};
|
|
185
|
-
/** Check whether a single command's args declare stdin-mode and argv leaves them unresolved. @internal */
|
|
186
|
-
declare function commandInvocationNeedsStdin(schema: CommandSchema, argv: readonly string[], flagSettings?: ParseOptions): boolean;
|
|
187
|
-
/** Plan the invocation and check whether the matched command needs stdin data. @internal */
|
|
188
|
-
declare function invocationNeedsStdin(schema: RuntimePreflightSchemaLike, argv: readonly string[]): boolean;
|
|
189
|
-
/**
|
|
190
|
-
* Run all adapter-driven sourcing work before command execution.
|
|
191
|
-
*
|
|
192
|
-
* Discovers config files, reads package.json metadata, detects stdin needs,
|
|
193
|
-
* wires up the prompt engine, and resolves output policy overrides into a
|
|
194
|
-
* single {@linkcode RuntimePreflightResult}.
|
|
195
|
-
* @internal
|
|
196
|
-
*/
|
|
197
|
-
declare function prepareRuntimePreflight(options: PrepareRuntimePreflightOptions): Promise<RuntimePreflightResult>;
|
|
198
|
-
//#endregion
|
|
199
|
-
export { type PrepareRuntimePreflightOptions, type ReadyRuntimePreflight, type RuntimeExecutionInputs, type RuntimePreflightOptions, type RuntimePreflightResult, type RuntimePreflightSchemaLike, commandInvocationNeedsStdin, extractConfigFlag, invocationNeedsStdin, prepareRuntimePreflight };
|
|
1
|
+
export {}
|