@kjanat/dreamcli 3.0.0-rc.1 → 3.0.0-rc.11
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 +227 -1
- 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 +81 -8
- package/dist/core/cli/index.mjs +945 -1
- package/dist/core/cli/planner.d.mts +5 -1
- 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 +2 -1
- package/dist/core/cli/root-help.mjs +226 -4
- package/dist/core/cli/root-surface.d.mts +12 -1
- package/dist/core/cli/root-surface.mjs +28 -1
- package/dist/core/cli/runtime-preflight.d.mts +14 -2
- package/dist/core/cli/runtime-preflight.mjs +169 -1
- package/dist/core/completion/index.d.mts +0 -1
- 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 +13 -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 +22 -3
- 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 +55 -38
- 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 +40 -7
- package/dist/core/parse/index.mjs +727 -1
- package/dist/core/prompt/index.d.mts +1 -1
- 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 +4 -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 +3 -4
- package/dist/core/schema/arg.mjs +463 -1
- package/dist/core/schema/command.d.mts +26 -6
- package/dist/core/schema/command.mjs +726 -1
- package/dist/core/schema/flag.d.mts +485 -19
- package/dist/core/schema/flag.mjs +705 -1
- package/dist/core/schema/index.d.mts +4 -2
- package/dist/core/schema/middleware.d.mts +4 -3
- package/dist/core/schema/middleware.mjs +41 -1
- package/dist/core/schema/number-constraints.mjs +60 -1
- package/dist/core/schema/prompt.d.mts +6 -3
- package/dist/core/schema/run.d.mts +20 -1
- 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 +0 -31
- package/dist/core/testkit/index.mjs +83 -1
- package/dist/index.d.mts +11 -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/package.json +45 -42
- package/dist/runtime/bun.d.mts +0 -28
- package/dist/runtime/bun.mjs +0 -1
- package/src/core/cli/dispatch.ts +0 -355
- package/src/core/cli/help-links.ts +0 -82
- package/src/core/cli/index.ts +0 -1614
- package/src/core/cli/planner.ts +0 -656
- package/src/core/cli/plugin.ts +0 -117
- package/src/core/cli/propagate.ts +0 -97
- package/src/core/cli/root-help.ts +0 -342
- package/src/core/cli/root-surface.ts +0 -87
- package/src/core/cli/runtime-preflight.ts +0 -456
- package/src/core/completion/index.ts +0 -138
- 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 -310
- 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 -265
- package/src/core/help/ansi.ts +0 -144
- package/src/core/help/index.ts +0 -563
- package/src/core/json-schema/index.ts +0 -910
- package/src/core/json-schema/meta-descriptions.generated.ts +0 -202
- 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 -742
- package/src/core/prompt/index.ts +0 -623
- package/src/core/resolve/args.ts +0 -144
- package/src/core/resolve/coerce.ts +0 -500
- 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 -269
- 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 -841
- package/src/core/schema/command.ts +0 -1500
- package/src/core/schema/flag.ts +0 -917
- package/src/core/schema/index.ts +0 -96
- package/src/core/schema/middleware.ts +0 -171
- package/src/core/schema/number-constraints.ts +0 -153
- package/src/core/schema/prompt.ts +0 -171
- 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 -147
- package/src/index.ts +0 -181
- package/src/runtime/adapter.ts +0 -303
- package/src/runtime/auto.ts +0 -86
- package/src/runtime/bun.ts +0 -48
- package/src/runtime/deno.ts +0 -367
- 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 -289
- package/src/runtime/paths.ts +0 -64
- package/src/runtime/support.ts +0 -77
- package/src/runtime.ts +0 -31
- package/src/schema.ts +0 -16
- package/src/strings.ts +0 -34
- package/src/testkit.ts +0 -25
- package/src/version.ts +0 -20
package/dist/core/help/index.mjs
CHANGED
|
@@ -1,7 +1,341 @@
|
|
|
1
|
-
import{getFlagAliasNames
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
1
|
+
import { getFlagAliasNames } from "../schema/flag.mjs";
|
|
2
|
+
import { formatDisplayValue } from "../output/display-value.mjs";
|
|
3
|
+
import { osc8, padEnd, visibleWidth, wrapText } from "./ansi.mjs";
|
|
4
|
+
import { resolveHelpTheme } from "./theme.mjs";
|
|
5
|
+
//#region src/core/help/index.ts
|
|
6
|
+
const DEFAULT_WIDTH = 80;
|
|
7
|
+
/**
|
|
8
|
+
* Apply defaults to optional {@link HelpOptions}.
|
|
9
|
+
*
|
|
10
|
+
* @param options - User-supplied help options, or `undefined` for all defaults.
|
|
11
|
+
* @returns Fully resolved options with defaults applied.
|
|
12
|
+
*/
|
|
13
|
+
function resolveOptions(options) {
|
|
14
|
+
return {
|
|
15
|
+
width: options?.width ?? DEFAULT_WIDTH,
|
|
16
|
+
binName: options?.binName,
|
|
17
|
+
isDefaultHelp: options?.isDefaultHelp ?? false,
|
|
18
|
+
theme: resolveHelpTheme(options?.colors, options?.theme)
|
|
19
|
+
};
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Format a deprecation annotation for help text.
|
|
23
|
+
*
|
|
24
|
+
* @param deprecated - `true` for a generic marker, or a string explaining the deprecation.
|
|
25
|
+
* @returns Bracketed deprecation label, e.g. `[deprecated]` or `[deprecated: use --foo]`.
|
|
26
|
+
*/
|
|
27
|
+
function formatDeprecated(deprecated) {
|
|
28
|
+
return typeof deprecated === "string" ? `[deprecated: ${deprecated}]` : "[deprecated]";
|
|
29
|
+
}
|
|
30
|
+
/** Format a default value for help output, preserving nullish sentinels. */
|
|
31
|
+
function formatHelpDefaultValue(value) {
|
|
32
|
+
if (value === void 0) return "undefined";
|
|
33
|
+
if (value === null) return "null";
|
|
34
|
+
return formatDisplayValue(value);
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Format a flag's left column: `-a, --name <type>`.
|
|
38
|
+
*
|
|
39
|
+
* @param name - Long flag name (without `--` prefix).
|
|
40
|
+
* @param schema - The {@link FlagSchema} describing the flag.
|
|
41
|
+
* @param theme - Theme applied to the flag forms and value hint.
|
|
42
|
+
* @returns Formatted left-column string for the flags table.
|
|
43
|
+
*/
|
|
44
|
+
function formatFlagLeft(name, schema, theme) {
|
|
45
|
+
const visibleShortAliases = getFlagAliasNames(schema, { kind: "short" });
|
|
46
|
+
const visibleLongAliases = getFlagAliasNames(schema, { kind: "long" });
|
|
47
|
+
const negation = schema.negation !== void 0 && !schema.negation.hidden ? schema.negation : void 0;
|
|
48
|
+
const canonicalForm = negation !== void 0 && negation.alias === void 0 ? `--[no-]${name}` : `--${name}`;
|
|
49
|
+
const forms = [
|
|
50
|
+
...visibleShortAliases.map((alias) => `-${alias}`),
|
|
51
|
+
canonicalForm,
|
|
52
|
+
...visibleLongAliases.map((alias) => `--${alias}`),
|
|
53
|
+
...negation?.alias !== void 0 ? [`--${negation.alias}`] : []
|
|
54
|
+
];
|
|
55
|
+
if (schema.kind !== "boolean" && schema.kind !== "count") return `${theme.flag(forms.join(", "))} ${theme.placeholder(formatValueHint(schema))}`;
|
|
56
|
+
return theme.flag(forms.join(", "));
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* Produce a type hint like `<string>`, `<number>`, `<us|eu|ap>`.
|
|
60
|
+
*
|
|
61
|
+
* A schema-level `valueHint` (set by sugar factories like `flag.url()`)
|
|
62
|
+
* overrides the kind-derived hint.
|
|
63
|
+
*
|
|
64
|
+
* @param schema - The {@link FlagSchema} whose value type determines the hint.
|
|
65
|
+
* @returns Angle-bracketed hint string, or empty string for no-value kinds.
|
|
66
|
+
*/
|
|
67
|
+
function formatValueHint(schema) {
|
|
68
|
+
if (schema.valueHint !== void 0) return `<${schema.valueHint}>`;
|
|
69
|
+
switch (schema.kind) {
|
|
70
|
+
case "string": return "<string>";
|
|
71
|
+
case "number": return "<number>";
|
|
72
|
+
case "enum": return `<${(schema.enumValues ?? []).join("|")}>`;
|
|
73
|
+
case "array": return `<${schema.elementSchema !== void 0 ? formatValueHint(schema.elementSchema).slice(1, -1) : "value"}>...`;
|
|
74
|
+
case "boolean":
|
|
75
|
+
case "count": return "";
|
|
76
|
+
case "custom": return "<value>";
|
|
77
|
+
case "keyValue": return "<key=value>";
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* Build description with env/config/prompt/default/required/deprecated annotations.
|
|
82
|
+
*
|
|
83
|
+
* @param schema - The {@link FlagSchema} to describe.
|
|
84
|
+
* @param theme - Theme applied to the metadata annotations (description stays plain).
|
|
85
|
+
* @returns Concatenated description string with metadata annotations.
|
|
86
|
+
*/
|
|
87
|
+
function formatFlagDescription(schema, theme) {
|
|
88
|
+
const parts = [];
|
|
89
|
+
if (schema.description !== void 0) parts.push(schema.description);
|
|
90
|
+
if (schema.deprecated !== void 0) parts.push(theme.deprecated(formatDeprecated(schema.deprecated)));
|
|
91
|
+
if (schema.envVar !== void 0) parts.push(theme.annotation(`[env: ${schema.envVar}]`));
|
|
92
|
+
if (schema.configPath !== void 0) parts.push(theme.annotation(`[config: ${schema.configPath}]`));
|
|
93
|
+
if (schema.prompt !== void 0) parts.push(theme.annotation("[prompt]"));
|
|
94
|
+
if (schema.presence === "required") parts.push(theme.annotation("[required]"));
|
|
95
|
+
else if (schema.presence === "defaulted" && schema.kind !== "boolean" && schema.kind !== "count") parts.push(theme.defaultValue(`(default: ${formatHelpDefaultValue(schema.defaultValue)})`));
|
|
96
|
+
return parts.join(" ");
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* Build the flag entries sorted: short-aliased first, then alphabetical.
|
|
100
|
+
*
|
|
101
|
+
* @param flags - Map of flag names to {@link FlagSchema} definitions.
|
|
102
|
+
* @param theme - Theme threaded into the per-flag formatters.
|
|
103
|
+
* @returns Sorted array of {@link FlagEntry} objects for the flags table.
|
|
104
|
+
*/
|
|
105
|
+
function buildFlagEntries(flags, theme) {
|
|
106
|
+
const names = Object.keys(flags);
|
|
107
|
+
if (names.length === 0) return [];
|
|
108
|
+
const sorted = [...names].sort((a, b) => {
|
|
109
|
+
const aSchema = flags[a];
|
|
110
|
+
const bSchema = flags[b];
|
|
111
|
+
if (aSchema === void 0 || bSchema === void 0) return 0;
|
|
112
|
+
const aHasShort = getFlagAliasNames(aSchema, { kind: "short" }).length > 0;
|
|
113
|
+
const bHasShort = getFlagAliasNames(bSchema, { kind: "short" }).length > 0;
|
|
114
|
+
if (aHasShort && !bHasShort) return -1;
|
|
115
|
+
if (!aHasShort && bHasShort) return 1;
|
|
116
|
+
return a.localeCompare(b);
|
|
117
|
+
});
|
|
118
|
+
const entries = [];
|
|
119
|
+
for (const name of sorted) {
|
|
120
|
+
const schema = flags[name];
|
|
121
|
+
if (schema === void 0) continue;
|
|
122
|
+
entries.push({
|
|
123
|
+
left: formatFlagLeft(name, schema, theme),
|
|
124
|
+
description: formatFlagDescription(schema, theme)
|
|
125
|
+
});
|
|
126
|
+
}
|
|
127
|
+
return entries;
|
|
128
|
+
}
|
|
129
|
+
/**
|
|
130
|
+
* Format a positional arg for the usage line.
|
|
131
|
+
*
|
|
132
|
+
* @param entry - The {@link CommandArgEntry} containing name and schema.
|
|
133
|
+
* @returns Bracketed arg token, e.g. `<file>` or `[output]...`.
|
|
134
|
+
*/
|
|
135
|
+
function formatArgUsage(entry) {
|
|
136
|
+
const { name, schema } = entry;
|
|
137
|
+
const label = schema.kind === "enum" && schema.enumValues !== void 0 ? schema.enumValues.join("|") : name;
|
|
138
|
+
const variadicSuffix = schema.variadic ? "..." : "";
|
|
139
|
+
if (schema.presence === "required") return `<${label}>${variadicSuffix}`;
|
|
140
|
+
return `[${label}]${variadicSuffix}`;
|
|
141
|
+
}
|
|
142
|
+
/**
|
|
143
|
+
* Format arg description with annotations.
|
|
144
|
+
*
|
|
145
|
+
* @param schema - The {@link ArgSchema} to describe.
|
|
146
|
+
* @param theme - Theme applied to the metadata annotations (description stays plain).
|
|
147
|
+
* @returns Concatenated description string with metadata annotations.
|
|
148
|
+
*/
|
|
149
|
+
function formatArgDescription(schema, theme) {
|
|
150
|
+
const parts = [];
|
|
151
|
+
if (schema.description !== void 0) parts.push(schema.description);
|
|
152
|
+
if (schema.deprecated !== void 0) parts.push(theme.deprecated(formatDeprecated(schema.deprecated)));
|
|
153
|
+
if (schema.envVar !== void 0) parts.push(theme.annotation(`[env: ${schema.envVar}]`));
|
|
154
|
+
if (schema.presence === "defaulted") parts.push(theme.defaultValue(`(default: ${formatHelpDefaultValue(schema.defaultValue)})`));
|
|
155
|
+
return parts.join(" ");
|
|
156
|
+
}
|
|
157
|
+
/**
|
|
158
|
+
* Build the ordered help sections without joining them.
|
|
159
|
+
*
|
|
160
|
+
* @internal
|
|
161
|
+
* @param schema - The {@link CommandSchema} to render.
|
|
162
|
+
* @param options - Optional {@link HelpOptions} for width/bin name.
|
|
163
|
+
* @returns Array of section strings (usage, description, commands, args, flags, examples).
|
|
164
|
+
*/
|
|
165
|
+
function formatHelpSections(schema, options) {
|
|
166
|
+
const opts = resolveOptions(options);
|
|
167
|
+
const sections = [];
|
|
168
|
+
sections.push(formatUsageLine(schema, opts));
|
|
169
|
+
if (schema.description !== void 0) sections.push(schema.description);
|
|
170
|
+
const visibleCommands = schema.commands.filter((c) => !c.hidden);
|
|
171
|
+
if (visibleCommands.length > 0) sections.push(formatCommandsSection(visibleCommands, opts));
|
|
172
|
+
if (schema.args.length > 0) sections.push(formatArgsSection(schema.args, opts));
|
|
173
|
+
if (Object.keys(schema.flags).length > 0) sections.push(formatFlagsSection(schema.flags, opts));
|
|
174
|
+
if (schema.examples.length > 0) sections.push(formatExamplesSection(schema.examples, opts.theme));
|
|
175
|
+
return sections;
|
|
176
|
+
}
|
|
177
|
+
/**
|
|
178
|
+
* Generate help text from a command schema.
|
|
179
|
+
*
|
|
180
|
+
* Low-level formatter: most applications reach this through `--help`,
|
|
181
|
+
* `help <command>`, or root help rendering in `CLIBuilder`. Call
|
|
182
|
+
* `formatHelp()` directly when embedding DreamCLI help text into custom UIs,
|
|
183
|
+
* tests, or generated docs.
|
|
184
|
+
*
|
|
185
|
+
* Sections rendered (in order):
|
|
186
|
+
* 1. **Usage** line — `program <command> [flags] <args>`
|
|
187
|
+
* 2. **Description** — the command's `.description()` text
|
|
188
|
+
* 3. **Commands** — subcommands table (if any, skips hidden)
|
|
189
|
+
* 4. **Arguments** — positional args table (if any)
|
|
190
|
+
* 5. **Flags** — flags table with type hints and defaults
|
|
191
|
+
* 6. **Examples** — usage examples (if any)
|
|
192
|
+
*
|
|
193
|
+
* @param schema - The command schema to render help for.
|
|
194
|
+
* @param options - Formatting options (width, binary name).
|
|
195
|
+
* @returns The formatted help string.
|
|
196
|
+
*
|
|
197
|
+
* @example
|
|
198
|
+
* ```ts
|
|
199
|
+
* const text = formatHelp(deploy.schema, { binName: 'mycli' });
|
|
200
|
+
* ```
|
|
201
|
+
*/
|
|
202
|
+
function formatHelp(schema, options) {
|
|
203
|
+
return `${formatHelpSections(schema, options).join("\n\n")}\n`;
|
|
204
|
+
}
|
|
205
|
+
/**
|
|
206
|
+
* Render the `Usage:` line for a command.
|
|
207
|
+
*
|
|
208
|
+
* @param schema - The {@link CommandSchema} to summarize.
|
|
209
|
+
* @param opts - Resolved help options (bin name, default-help flag).
|
|
210
|
+
* @returns Single-line usage string, e.g. `Usage: mycli deploy [flags] <env>`.
|
|
211
|
+
*/
|
|
212
|
+
function formatUsageLine(schema, opts) {
|
|
213
|
+
const { theme } = opts;
|
|
214
|
+
const parts = [theme.sectionTitle("Usage:")];
|
|
215
|
+
const cmdName = opts.binName === void 0 ? schema.name : opts.isDefaultHelp ? opts.binName : `${opts.binName} ${schema.name}`;
|
|
216
|
+
parts.push(theme.usageBin(cmdName));
|
|
217
|
+
if (schema.commands.length > 0) parts.push(theme.placeholder("<command>"));
|
|
218
|
+
if (Object.keys(schema.flags).length > 0) parts.push(theme.placeholder("[flags]"));
|
|
219
|
+
for (const entry of schema.args) parts.push(theme.arg(formatArgUsage(entry)));
|
|
220
|
+
return parts.join(" ");
|
|
221
|
+
}
|
|
222
|
+
/**
|
|
223
|
+
* Render the `Arguments:` help section.
|
|
224
|
+
*
|
|
225
|
+
* @param args - Positional arg entries from the {@link CommandSchema}.
|
|
226
|
+
* @param opts - Resolved help options for line-width wrapping.
|
|
227
|
+
* @returns Multi-line arguments section string.
|
|
228
|
+
*/
|
|
229
|
+
function formatArgsSection(args, opts) {
|
|
230
|
+
const { theme } = opts;
|
|
231
|
+
const lines = [theme.sectionTitle("Arguments:")];
|
|
232
|
+
const GAP = 2;
|
|
233
|
+
let maxLeft = 0;
|
|
234
|
+
const entries = [];
|
|
235
|
+
for (const entry of args) {
|
|
236
|
+
const left = ` ${theme.arg(formatArgUsage(entry))}`;
|
|
237
|
+
const desc = formatArgDescription(entry.schema, theme);
|
|
238
|
+
entries.push({
|
|
239
|
+
left,
|
|
240
|
+
desc
|
|
241
|
+
});
|
|
242
|
+
const leftWidth = visibleWidth(left);
|
|
243
|
+
if (leftWidth > maxLeft) maxLeft = leftWidth;
|
|
244
|
+
}
|
|
245
|
+
const descCol = maxLeft + GAP;
|
|
246
|
+
for (const { left, desc } of entries) if (desc.length === 0) lines.push(left);
|
|
247
|
+
else {
|
|
248
|
+
const padded = padEnd(left, descCol);
|
|
249
|
+
const wrapped = wrapText(desc, opts.width, descCol);
|
|
250
|
+
lines.push(`${padded}${wrapped}`);
|
|
251
|
+
}
|
|
252
|
+
return lines.join("\n");
|
|
253
|
+
}
|
|
254
|
+
/**
|
|
255
|
+
* Render the `Flags:` help section.
|
|
256
|
+
*
|
|
257
|
+
* @param flags - Map of flag names to {@link FlagSchema} definitions.
|
|
258
|
+
* @param opts - Resolved help options for line-width wrapping.
|
|
259
|
+
* @returns Multi-line flags section string.
|
|
260
|
+
*/
|
|
261
|
+
function formatFlagsSection(flags, opts) {
|
|
262
|
+
return formatFlagEntriesBlock(opts.theme.sectionTitle("Flags:"), buildFlagEntries(flags, opts.theme), opts.width);
|
|
263
|
+
}
|
|
264
|
+
/**
|
|
265
|
+
* Render a titled two-column flag block from pre-built {@link FlagEntry} rows.
|
|
266
|
+
*
|
|
267
|
+
* Shared by the per-command `Flags:` section and the root-help `Global options:`
|
|
268
|
+
* block (built-in flags), so column alignment and description wrapping stay
|
|
269
|
+
* identical across both. Returns `''` when there are no entries.
|
|
270
|
+
*
|
|
271
|
+
* @param title - Section heading (e.g. `'Flags:'`, `'Global options:'`), pre-styled by the caller.
|
|
272
|
+
* @param entries - Formatted left/description rows.
|
|
273
|
+
* @param width - Terminal width for description wrapping.
|
|
274
|
+
* @returns Multi-line block string, or `''` when `entries` is empty.
|
|
275
|
+
* @internal
|
|
276
|
+
*/
|
|
277
|
+
function formatFlagEntriesBlock(title, entries, width) {
|
|
278
|
+
if (entries.length === 0) return "";
|
|
279
|
+
const lines = [title];
|
|
280
|
+
const GAP = 2;
|
|
281
|
+
let maxLeft = 0;
|
|
282
|
+
for (const entry of entries) {
|
|
283
|
+
const indentedWidth = visibleWidth(entry.left) + 2;
|
|
284
|
+
if (indentedWidth > maxLeft) maxLeft = indentedWidth;
|
|
285
|
+
}
|
|
286
|
+
const descCol = maxLeft + GAP;
|
|
287
|
+
for (const entry of entries) {
|
|
288
|
+
const left = ` ${entry.left}`;
|
|
289
|
+
if (entry.description.length === 0) lines.push(left);
|
|
290
|
+
else {
|
|
291
|
+
const padded = padEnd(left, descCol);
|
|
292
|
+
const wrapped = wrapText(entry.description, width, descCol);
|
|
293
|
+
lines.push(`${padded}${wrapped}`);
|
|
294
|
+
}
|
|
295
|
+
}
|
|
296
|
+
return lines.join("\n");
|
|
297
|
+
}
|
|
298
|
+
/**
|
|
299
|
+
* Render the `Commands:` help section.
|
|
300
|
+
*
|
|
301
|
+
* @param commands - Visible subcommand schemas (hidden commands pre-filtered).
|
|
302
|
+
* @param opts - Resolved help options for line-width wrapping.
|
|
303
|
+
* @returns Multi-line commands section string.
|
|
304
|
+
*/
|
|
305
|
+
function formatCommandsSection(commands, opts) {
|
|
306
|
+
const { theme } = opts;
|
|
307
|
+
const lines = [theme.sectionTitle("Commands:")];
|
|
308
|
+
const GAP = 2;
|
|
309
|
+
let maxNameLen = 0;
|
|
310
|
+
for (const cmd of commands) if (cmd.name.length > maxNameLen) maxNameLen = cmd.name.length;
|
|
311
|
+
const descCol = 2 + maxNameLen + GAP;
|
|
312
|
+
for (const cmd of commands) {
|
|
313
|
+
const left = ` ${theme.command(cmd.name)}`;
|
|
314
|
+
const desc = cmd.description ?? "";
|
|
315
|
+
if (desc.length === 0) lines.push(left);
|
|
316
|
+
else {
|
|
317
|
+
const padded = padEnd(left, descCol);
|
|
318
|
+
const wrapped = wrapText(desc, opts.width, descCol);
|
|
319
|
+
lines.push(`${padded}${wrapped}`);
|
|
320
|
+
}
|
|
321
|
+
}
|
|
322
|
+
return lines.join("\n");
|
|
323
|
+
}
|
|
324
|
+
/**
|
|
325
|
+
* Render the `Examples:` help section.
|
|
326
|
+
*
|
|
327
|
+
* @param examples - Array of {@link CommandExample} entries.
|
|
328
|
+
* @param theme - Theme applied to the section title and `$` prompt marker.
|
|
329
|
+
* @returns Multi-line examples section string.
|
|
330
|
+
*/
|
|
331
|
+
function formatExamplesSection(examples, theme) {
|
|
332
|
+
const lines = [theme.sectionTitle("Examples:")];
|
|
333
|
+
const prompt = theme.examplePrompt("$");
|
|
334
|
+
for (const example of examples) if (example.description !== void 0) {
|
|
335
|
+
lines.push(` ${example.description}:`);
|
|
336
|
+
lines.push(` ${prompt} ${example.command}`);
|
|
337
|
+
} else lines.push(` ${prompt} ${example.command}`);
|
|
338
|
+
return lines.join("\n");
|
|
339
|
+
}
|
|
340
|
+
//#endregion
|
|
341
|
+
export { formatFlagEntriesBlock, formatHelp, formatHelpSections, osc8, visibleWidth };
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import { Colors, Formatter } from "ansispeck";
|
|
2
|
+
//#region src/core/help/theme.d.ts
|
|
3
|
+
/**
|
|
4
|
+
* Semantic styling roles for help output.
|
|
5
|
+
*
|
|
6
|
+
* Roles that appear inside wrap-eligible description text (`defaultValue`,
|
|
7
|
+
* `annotation`, `deprecated`) should stick to foreground colors and `dim` —
|
|
8
|
+
* a styled span may cross a soft-wrap boundary, and while color/dim carry
|
|
9
|
+
* invisibly across the continuation indent, `underline`/`inverse`/background
|
|
10
|
+
* styles would visibly paint it.
|
|
11
|
+
*/
|
|
12
|
+
interface HelpTheme {
|
|
13
|
+
/** Section headings: `Usage:`, `Arguments:`, `Flags:`, `Commands:`, `Examples:`, `Global options:`. */
|
|
14
|
+
readonly sectionTitle: Formatter;
|
|
15
|
+
/** Binary / command path in the usage line. */
|
|
16
|
+
readonly usageBin: Formatter;
|
|
17
|
+
/** Flag forms in the flags table: `-f, --force`. */
|
|
18
|
+
readonly flag: Formatter;
|
|
19
|
+
/** Grammar tokens: `<string>`, `<command>`, `[flags]`, value hints. */
|
|
20
|
+
readonly placeholder: Formatter;
|
|
21
|
+
/** Command names in `Commands:` tables. */
|
|
22
|
+
readonly command: Formatter;
|
|
23
|
+
/** Positional arg tokens: `<file>`, `[out]...`. */
|
|
24
|
+
readonly arg: Formatter;
|
|
25
|
+
/** Default-value annotations: `(default: 8080)`. */
|
|
26
|
+
readonly defaultValue: Formatter;
|
|
27
|
+
/** Metadata annotations: `[env: X]`, `[config: a.b]`, `[prompt]`, `[required]`, ` (default)`. */
|
|
28
|
+
readonly annotation: Formatter;
|
|
29
|
+
/** Deprecation labels: `[deprecated]`, `[deprecated: use --x]`. */
|
|
30
|
+
readonly deprecated: Formatter;
|
|
31
|
+
/** Program name in the root-help header. */
|
|
32
|
+
readonly headerName: Formatter;
|
|
33
|
+
/** Version (`vX.Y.Z`) in the root-help header. */
|
|
34
|
+
readonly headerVersion: Formatter;
|
|
35
|
+
/** The `$` prompt marker in `Examples:`. */
|
|
36
|
+
readonly examplePrompt: Formatter;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* User theme customization: receives the gated palette and returns role
|
|
40
|
+
* overrides merged over the default theme.
|
|
41
|
+
*
|
|
42
|
+
* The palette formatters are identity functions when color is disabled, and
|
|
43
|
+
* the factory itself is only invoked when color is enabled — style
|
|
44
|
+
* unconditionally, gating is the framework's job.
|
|
45
|
+
*/
|
|
46
|
+
type HelpThemeFactory = (colors: Colors) => Partial<HelpTheme>;
|
|
47
|
+
/**
|
|
48
|
+
* The built-in help theme (clap/cargo conventions).
|
|
49
|
+
*
|
|
50
|
+
* @param c - Palette to build formatters from (typically the gated `out.color`).
|
|
51
|
+
* @internal
|
|
52
|
+
*/
|
|
53
|
+
declare function defaultHelpTheme(c: Colors): HelpTheme;
|
|
54
|
+
/**
|
|
55
|
+
* Resolve the effective help theme from a palette and optional user factory.
|
|
56
|
+
*
|
|
57
|
+
* When the palette renders no styling (color disabled — its formatters are
|
|
58
|
+
* identity functions), the user factory is **never invoked**: even a factory
|
|
59
|
+
* that emits raw escapes cannot leak them into color-off output. When color
|
|
60
|
+
* is enabled, factory overrides merge over {@linkcode defaultHelpTheme}.
|
|
61
|
+
*
|
|
62
|
+
* @param colors - Gated palette, or `undefined` for a color-off theme.
|
|
63
|
+
* @param theme - Optional user overrides factory.
|
|
64
|
+
* @internal
|
|
65
|
+
*/
|
|
66
|
+
declare function resolveHelpTheme(colors: Colors | undefined, theme: HelpThemeFactory | undefined): HelpTheme;
|
|
67
|
+
//#endregion
|
|
68
|
+
export { type HelpTheme, type HelpThemeFactory, defaultHelpTheme, resolveHelpTheme };
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { createColors } from "ansispeck";
|
|
2
|
+
//#region src/core/help/theme.ts
|
|
3
|
+
/**
|
|
4
|
+
* The built-in help theme (clap/cargo conventions).
|
|
5
|
+
*
|
|
6
|
+
* @param c - Palette to build formatters from (typically the gated `out.color`).
|
|
7
|
+
* @internal
|
|
8
|
+
*/
|
|
9
|
+
function defaultHelpTheme(c) {
|
|
10
|
+
return {
|
|
11
|
+
sectionTitle: (input) => c.bold(c.underline(input)),
|
|
12
|
+
usageBin: c.bold,
|
|
13
|
+
flag: c.cyan,
|
|
14
|
+
placeholder: c.dim,
|
|
15
|
+
command: c.cyan,
|
|
16
|
+
arg: c.cyan,
|
|
17
|
+
defaultValue: c.dim,
|
|
18
|
+
annotation: c.dim,
|
|
19
|
+
deprecated: c.yellow,
|
|
20
|
+
headerName: c.bold,
|
|
21
|
+
headerVersion: c.dim,
|
|
22
|
+
examplePrompt: c.dim
|
|
23
|
+
};
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Resolve the effective help theme from a palette and optional user factory.
|
|
27
|
+
*
|
|
28
|
+
* When the palette renders no styling (color disabled — its formatters are
|
|
29
|
+
* identity functions), the user factory is **never invoked**: even a factory
|
|
30
|
+
* that emits raw escapes cannot leak them into color-off output. When color
|
|
31
|
+
* is enabled, factory overrides merge over {@linkcode defaultHelpTheme}.
|
|
32
|
+
*
|
|
33
|
+
* @param colors - Gated palette, or `undefined` for a color-off theme.
|
|
34
|
+
* @param theme - Optional user overrides factory.
|
|
35
|
+
* @internal
|
|
36
|
+
*/
|
|
37
|
+
function resolveHelpTheme(colors, theme) {
|
|
38
|
+
const palette = colors ?? createColors(false);
|
|
39
|
+
if (!(palette.bold("x") !== "x") || theme === void 0) return defaultHelpTheme(palette);
|
|
40
|
+
return {
|
|
41
|
+
...defaultHelpTheme(palette),
|
|
42
|
+
...theme(palette)
|
|
43
|
+
};
|
|
44
|
+
}
|
|
45
|
+
//#endregion
|
|
46
|
+
export { defaultHelpTheme, resolveHelpTheme };
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { CommandSchema } from "../schema/command.mjs";
|
|
2
|
+
import "../schema/index.mjs";
|
|
2
3
|
import { CLISchema } from "../cli/index.mjs";
|
|
3
|
-
|
|
4
4
|
//#region src/core/json-schema/index.d.ts
|
|
5
5
|
/**
|
|
6
6
|
* Options for JSON Schema generation.
|
|
@@ -53,6 +53,19 @@ interface JsonSchemaOptions {
|
|
|
53
53
|
* ```
|
|
54
54
|
*/
|
|
55
55
|
declare function generateSchema(schema: CLISchema, options?: JsonSchemaOptions): Record<string, unknown>;
|
|
56
|
+
/**
|
|
57
|
+
* Generate the definition metadata document for a single command.
|
|
58
|
+
*
|
|
59
|
+
* The per-command counterpart of {@link generateSchema}: the same
|
|
60
|
+
* JSON-serializable shape as one entry of its `commands` array (flags, args,
|
|
61
|
+
* subcommands, examples). Powers `--help` in `--json` mode and is useful for
|
|
62
|
+
* embedding one command's definition into custom tooling.
|
|
63
|
+
*
|
|
64
|
+
* @param schema - The command schema to serialize.
|
|
65
|
+
* @param options - Generation options.
|
|
66
|
+
* @returns A plain object suitable for `JSON.stringify()`.
|
|
67
|
+
*/
|
|
68
|
+
declare function generateCommandSchema(schema: CommandSchema, options?: JsonSchemaOptions): Record<string, unknown>;
|
|
56
69
|
/**
|
|
57
70
|
* Generate a JSON Schema (draft 2020-12) for validating CLI input as JSON.
|
|
58
71
|
*
|
|
@@ -106,4 +119,4 @@ declare function generateInputSchema(schema: CLISchema | CommandSchema, options?
|
|
|
106
119
|
*/
|
|
107
120
|
declare const definitionMetaSchema: Record<string, unknown>;
|
|
108
121
|
//#endregion
|
|
109
|
-
export { type JsonSchemaOptions, definitionMetaSchema, generateInputSchema, generateSchema };
|
|
122
|
+
export { type JsonSchemaOptions, definitionMetaSchema, generateCommandSchema, generateInputSchema, generateSchema };
|