@kjanat/dreamcli 0.0.0 → 2.0.0
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 +706 -0
- package/LICENSE +22 -0
- package/README.md +502 -0
- package/dist/core/cli/dispatch.d.mts +85 -0
- package/dist/core/cli/dispatch.mjs +1 -0
- package/dist/core/cli/index.d.mts +418 -0
- package/dist/core/cli/index.mjs +1 -0
- package/dist/core/cli/planner.d.mts +143 -0
- package/dist/core/cli/planner.mjs +1 -0
- package/dist/core/cli/plugin.d.mts +94 -0
- package/dist/core/cli/plugin.mjs +1 -0
- package/dist/core/cli/propagate.d.mts +39 -0
- package/dist/core/cli/propagate.mjs +1 -0
- package/dist/core/cli/root-help.d.mts +28 -0
- package/dist/core/cli/root-help.mjs +7 -0
- package/dist/core/cli/root-surface.d.mts +42 -0
- package/dist/core/cli/root-surface.mjs +1 -0
- package/dist/core/cli/runtime-preflight.d.mts +149 -0
- package/dist/core/cli/runtime-preflight.mjs +1 -0
- package/dist/core/completion/index.d.mts +46 -0
- package/dist/core/completion/index.mjs +1 -0
- package/dist/core/completion/shells/bash.d.mts +24 -0
- package/dist/core/completion/shells/bash.mjs +3 -0
- package/dist/core/completion/shells/fish.d.mts +20 -0
- package/dist/core/completion/shells/fish.mjs +2 -0
- package/dist/core/completion/shells/powershell.d.mts +14 -0
- package/dist/core/completion/shells/powershell.mjs +2 -0
- package/dist/core/completion/shells/shared.d.mts +139 -0
- package/dist/core/completion/shells/shared.mjs +1 -0
- package/dist/core/completion/shells/zsh.d.mts +24 -0
- package/dist/core/completion/shells/zsh.mjs +2 -0
- package/dist/core/config/index.d.mts +161 -0
- package/dist/core/config/index.mjs +1 -0
- package/dist/core/config/package-json.d.mts +68 -0
- package/dist/core/config/package-json.mjs +1 -0
- package/dist/core/errors/index.d.mts +126 -0
- package/dist/core/errors/index.mjs +1 -0
- package/dist/core/execution/index.d.mts +49 -0
- package/dist/core/execution/index.mjs +1 -0
- package/dist/core/help/index.d.mts +49 -0
- package/dist/core/help/index.mjs +8 -0
- package/dist/core/json-schema/index.d.mts +109 -0
- package/dist/core/json-schema/index.mjs +55 -0
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +185 -0
- package/dist/core/json-schema/meta-descriptions.generated.mjs +28 -0
- package/dist/core/output/activity.d.mts +194 -0
- package/dist/core/output/activity.mjs +1 -0
- package/dist/core/output/contracts.d.mts +88 -0
- package/dist/core/output/contracts.mjs +1 -0
- package/dist/core/output/display-value.d.mts +19 -0
- package/dist/core/output/display-value.mjs +1 -0
- package/dist/core/output/index.d.mts +280 -0
- package/dist/core/output/index.mjs +2 -0
- package/dist/core/output/renderers.d.mts +46 -0
- package/dist/core/output/renderers.mjs +1 -0
- package/dist/core/output/writer.d.mts +40 -0
- package/dist/core/output/writer.mjs +1 -0
- package/dist/core/parse/index.d.mts +79 -0
- package/dist/core/parse/index.mjs +1 -0
- package/dist/core/prompt/index.d.mts +205 -0
- package/dist/core/prompt/index.mjs +6 -0
- package/dist/core/resolve/args.d.mts +8 -0
- package/dist/core/resolve/args.mjs +1 -0
- package/dist/core/resolve/coerce.d.mts +22 -0
- package/dist/core/resolve/coerce.mjs +1 -0
- package/dist/core/resolve/config.d.mts +10 -0
- package/dist/core/resolve/config.mjs +1 -0
- package/dist/core/resolve/contracts.d.mts +112 -0
- package/dist/core/resolve/errors.d.mts +11 -0
- package/dist/core/resolve/errors.mjs +2 -0
- package/dist/core/resolve/flags.d.mts +10 -0
- package/dist/core/resolve/flags.mjs +1 -0
- package/dist/core/resolve/index.d.mts +42 -0
- package/dist/core/resolve/index.mjs +1 -0
- package/dist/core/resolve/property.d.mts +47 -0
- package/dist/core/resolve/property.mjs +1 -0
- package/dist/core/schema/activity.d.mts +169 -0
- package/dist/core/schema/arg.d.mts +559 -0
- package/dist/core/schema/arg.mjs +1 -0
- package/dist/core/schema/command.d.mts +960 -0
- package/dist/core/schema/command.mjs +1 -0
- package/dist/core/schema/flag.d.mts +491 -0
- package/dist/core/schema/flag.mjs +1 -0
- package/dist/core/schema/index.d.mts +8 -0
- package/dist/core/schema/middleware.d.mts +122 -0
- package/dist/core/schema/middleware.mjs +1 -0
- package/dist/core/schema/prompt.d.mts +117 -0
- package/dist/core/schema/run.d.mts +171 -0
- package/dist/core/schema-dsl/runtime.d.mts +144 -0
- package/dist/core/schema-dsl/runtime.mjs +2 -0
- package/dist/core/schema-dsl/to-json-schema.d.mts +30 -0
- package/dist/core/schema-dsl/to-json-schema.mjs +1 -0
- package/dist/core/testkit/index.d.mts +54 -0
- package/dist/core/testkit/index.mjs +1 -0
- package/dist/index.d.mts +28 -0
- package/dist/index.mjs +1 -0
- package/dist/runtime/adapter.d.mts +212 -0
- package/dist/runtime/adapter.mjs +1 -0
- package/dist/runtime/auto.d.mts +26 -0
- package/dist/runtime/auto.mjs +1 -0
- package/dist/runtime/bun.d.mts +28 -0
- package/dist/runtime/bun.mjs +1 -0
- package/dist/runtime/deno.d.mts +76 -0
- package/dist/runtime/deno.mjs +2 -0
- package/dist/runtime/detect.d.mts +86 -0
- package/dist/runtime/detect.mjs +1 -0
- package/dist/runtime/index.d.mts +7 -0
- package/dist/runtime/node.d.mts +65 -0
- package/dist/runtime/node.mjs +2 -0
- package/dist/runtime/paths.d.mts +31 -0
- package/dist/runtime/paths.mjs +1 -0
- package/dist/runtime/support.d.mts +42 -0
- package/dist/runtime/support.mjs +1 -0
- package/dist/runtime.d.mts +7 -0
- package/dist/runtime.mjs +1 -0
- package/dist/testkit.d.mts +6 -0
- package/dist/testkit.mjs +1 -0
- package/dist/version.d.mts +16 -0
- package/dist/version.mjs +1 -0
- package/dreamcli.schema.json +338 -0
- package/examples/basic.ts +33 -0
- package/examples/gh/package.json +44 -0
- package/examples/gh/src/commands/auth.ts +66 -0
- package/examples/gh/src/commands/issue.ts +120 -0
- package/examples/gh/src/commands/pr.ts +125 -0
- package/examples/gh/src/data/issues.yaml +5 -0
- package/examples/gh/src/data/issues.yaml.d.ts +17 -0
- package/examples/gh/src/data/pull-requests.yaml +7 -0
- package/examples/gh/src/data/pull-requests.yaml.d.ts +18 -0
- package/examples/gh/src/docs.ts +11 -0
- package/examples/gh/src/lib/auth.ts +37 -0
- package/examples/gh/src/lib/utils.ts +17 -0
- package/examples/gh/src/main.test.ts +307 -0
- package/examples/gh/src/main.ts +40 -0
- package/examples/interactive.ts +66 -0
- package/examples/json-mode.ts +91 -0
- package/examples/middleware.ts +71 -0
- package/examples/multi-command.ts +66 -0
- package/examples/spinner-progress.ts +49 -0
- package/examples/testing.ts +147 -0
- package/package.json +149 -2
- package/src/core/cli/dispatch.ts +286 -0
- package/src/core/cli/index.ts +978 -0
- package/src/core/cli/planner.ts +413 -0
- package/src/core/cli/plugin.ts +117 -0
- package/src/core/cli/propagate.ts +97 -0
- package/src/core/cli/root-help.ts +269 -0
- package/src/core/cli/root-surface.ts +74 -0
- package/src/core/cli/runtime-preflight.ts +409 -0
- package/src/core/completion/index.ts +88 -0
- package/src/core/completion/shells/bash.ts +459 -0
- package/src/core/completion/shells/fish.ts +259 -0
- package/src/core/completion/shells/powershell.ts +405 -0
- package/src/core/completion/shells/shared.ts +283 -0
- package/src/core/completion/shells/zsh.ts +381 -0
- package/src/core/config/index.ts +407 -0
- package/src/core/config/package-json.ts +220 -0
- package/src/core/errors/index.ts +193 -0
- package/src/core/execution/index.ts +270 -0
- package/src/core/help/index.ts +557 -0
- package/src/core/json-schema/index.ts +891 -0
- package/src/core/json-schema/meta-descriptions.generated.ts +202 -0
- package/src/core/output/activity.ts +568 -0
- package/src/core/output/contracts.ts +194 -0
- package/src/core/output/display-value.ts +48 -0
- package/src/core/output/index.ts +669 -0
- package/src/core/output/renderers.ts +125 -0
- package/src/core/output/writer.ts +46 -0
- package/src/core/parse/index.ts +661 -0
- package/src/core/prompt/index.ts +583 -0
- package/src/core/resolve/args.ts +144 -0
- package/src/core/resolve/coerce.ts +432 -0
- package/src/core/resolve/config.ts +26 -0
- package/src/core/resolve/contracts.ts +135 -0
- package/src/core/resolve/errors.ts +227 -0
- package/src/core/resolve/flags.ts +205 -0
- package/src/core/resolve/index.ts +108 -0
- package/src/core/resolve/property.ts +99 -0
- package/src/core/schema/activity.ts +240 -0
- package/src/core/schema/arg.ts +719 -0
- package/src/core/schema/command.ts +1490 -0
- package/src/core/schema/flag.ts +756 -0
- package/src/core/schema/index.ts +91 -0
- package/src/core/schema/middleware.ts +171 -0
- package/src/core/schema/prompt.ts +156 -0
- package/src/core/schema/run.ts +195 -0
- package/src/core/schema-dsl/index.ts +109 -0
- package/src/core/schema-dsl/parse.ts +262 -0
- package/src/core/schema-dsl/runtime.ts +609 -0
- package/src/core/schema-dsl/to-json-schema.ts +102 -0
- package/src/core/testkit/index.ts +123 -0
- package/src/index.ts +170 -0
- package/src/runtime/adapter.ts +303 -0
- package/src/runtime/auto.ts +110 -0
- package/src/runtime/bun.ts +55 -0
- package/src/runtime/deno.ts +369 -0
- package/src/runtime/detect.ts +105 -0
- package/src/runtime/index.ts +21 -0
- package/src/runtime/node-builtins.d.ts +23 -0
- package/src/runtime/node.ts +300 -0
- package/src/runtime/paths.ts +62 -0
- package/src/runtime/support.ts +135 -0
- package/src/runtime.ts +31 -0
- package/src/testkit.ts +25 -0
- package/src/version.ts +20 -0
|
@@ -0,0 +1,557 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Auto-generated help text from command schemas.
|
|
3
|
+
*
|
|
4
|
+
* Renders usage line, description, positional args, flags table, and
|
|
5
|
+
* examples from a {@linkcode CommandSchema}. Designed for TTY output with
|
|
6
|
+
* configurable width.
|
|
7
|
+
*
|
|
8
|
+
* @module dreamcli/core/help
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
import { formatDisplayValue } from '#internals/core/output/display-value.ts';
|
|
12
|
+
import { getFlagAliasNames } from '#internals/core/schema/flag.ts';
|
|
13
|
+
import type {
|
|
14
|
+
ArgSchema,
|
|
15
|
+
CommandArgEntry,
|
|
16
|
+
CommandExample,
|
|
17
|
+
CommandSchema,
|
|
18
|
+
FlagSchema,
|
|
19
|
+
} from '#internals/core/schema/index.ts';
|
|
20
|
+
|
|
21
|
+
// --- Configuration
|
|
22
|
+
|
|
23
|
+
/** Options for customising help output. */
|
|
24
|
+
interface HelpOptions {
|
|
25
|
+
/** Maximum line width (columns). Defaults to 80. */
|
|
26
|
+
readonly width?: number;
|
|
27
|
+
/** Binary/program name shown in the usage line. Defaults to command name. */
|
|
28
|
+
readonly binName?: string;
|
|
29
|
+
/** @internal Whether this usage line is being rendered as merged root/default help. */
|
|
30
|
+
readonly isDefaultHelp?: boolean;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/** Resolved help options with defaults applied. */
|
|
34
|
+
interface ResolvedHelpOptions {
|
|
35
|
+
readonly width: number;
|
|
36
|
+
readonly binName: string | undefined;
|
|
37
|
+
readonly isDefaultHelp: boolean;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
const DEFAULT_WIDTH = 80;
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* Apply defaults to optional {@link HelpOptions}.
|
|
44
|
+
*
|
|
45
|
+
* @param options - User-supplied help options, or `undefined` for all defaults.
|
|
46
|
+
* @returns Fully resolved options with defaults applied.
|
|
47
|
+
*/
|
|
48
|
+
function resolveOptions(options?: HelpOptions): ResolvedHelpOptions {
|
|
49
|
+
return {
|
|
50
|
+
width: options?.width ?? DEFAULT_WIDTH,
|
|
51
|
+
binName: options?.binName,
|
|
52
|
+
isDefaultHelp: options?.isDefaultHelp ?? false,
|
|
53
|
+
};
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
// --- Internal helpers
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* Pad `text` to `length` with trailing spaces.
|
|
60
|
+
*
|
|
61
|
+
* @param text - The string to pad.
|
|
62
|
+
* @param length - Target length in characters.
|
|
63
|
+
* @returns The padded string, unchanged if already at or beyond `length`.
|
|
64
|
+
*/
|
|
65
|
+
function padEnd(text: string, length: number): string {
|
|
66
|
+
if (text.length >= length) return text;
|
|
67
|
+
return text + ' '.repeat(length - text.length);
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Wrap text to `width`, preserving leading indent on continuation lines.
|
|
72
|
+
*
|
|
73
|
+
* @param text - The text to wrap.
|
|
74
|
+
* @param width - Maximum line width in columns.
|
|
75
|
+
* @param indent - Number of leading spaces for continuation lines.
|
|
76
|
+
* @returns The wrapped string with newlines inserted as needed.
|
|
77
|
+
*/
|
|
78
|
+
function wrapText(text: string, width: number, indent: number): string {
|
|
79
|
+
if (text.length + indent <= width) return text;
|
|
80
|
+
|
|
81
|
+
const maxLen = width - indent;
|
|
82
|
+
if (maxLen <= 0) return text;
|
|
83
|
+
|
|
84
|
+
const words = text.split(' ');
|
|
85
|
+
const lines: string[] = [];
|
|
86
|
+
let current = '';
|
|
87
|
+
|
|
88
|
+
for (const word of words) {
|
|
89
|
+
if (current.length === 0) {
|
|
90
|
+
current = word;
|
|
91
|
+
} else if (current.length + 1 + word.length <= maxLen) {
|
|
92
|
+
current += ` ${word}`;
|
|
93
|
+
} else {
|
|
94
|
+
lines.push(current);
|
|
95
|
+
current = word;
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
if (current.length > 0) {
|
|
99
|
+
lines.push(current);
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
const pad = ' '.repeat(indent);
|
|
103
|
+
return lines.map((line, i) => (i === 0 ? line : `${pad}${line}`)).join('\n');
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
// --- Deprecation formatting
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* Format a deprecation annotation for help text.
|
|
110
|
+
*
|
|
111
|
+
* @param deprecated - `true` for a generic marker, or a string explaining the deprecation.
|
|
112
|
+
* @returns Bracketed deprecation label, e.g. `[deprecated]` or `[deprecated: use --foo]`.
|
|
113
|
+
*/
|
|
114
|
+
function formatDeprecated(deprecated: string | true): string {
|
|
115
|
+
return typeof deprecated === 'string' ? `[deprecated: ${deprecated}]` : '[deprecated]';
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/** Format a default value for help output, preserving nullish sentinels. */
|
|
119
|
+
function formatHelpDefaultValue(value: unknown): string {
|
|
120
|
+
if (value === undefined) return 'undefined';
|
|
121
|
+
if (value === null) return 'null';
|
|
122
|
+
return formatDisplayValue(value);
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
// --- Flag formatting
|
|
126
|
+
|
|
127
|
+
/** Formatted flag entry for the flags table. */
|
|
128
|
+
interface FlagEntry {
|
|
129
|
+
readonly left: string;
|
|
130
|
+
readonly description: string;
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* Format a flag's left column: `-a, --name <type>`.
|
|
135
|
+
*
|
|
136
|
+
* @param name - Long flag name (without `--` prefix).
|
|
137
|
+
* @param schema - The {@link FlagSchema} describing the flag.
|
|
138
|
+
* @returns Formatted left-column string for the flags table.
|
|
139
|
+
*/
|
|
140
|
+
function formatFlagLeft(name: string, schema: FlagSchema): string {
|
|
141
|
+
const visibleShortAliases = getFlagAliasNames(schema, { kind: 'short' });
|
|
142
|
+
const visibleLongAliases = getFlagAliasNames(schema, { kind: 'long' });
|
|
143
|
+
const forms = [
|
|
144
|
+
...visibleShortAliases.map((alias) => `-${alias}`),
|
|
145
|
+
`--${name}`,
|
|
146
|
+
...visibleLongAliases.map((alias) => `--${alias}`),
|
|
147
|
+
];
|
|
148
|
+
|
|
149
|
+
// Value placeholder (skip for boolean)
|
|
150
|
+
if (schema.kind !== 'boolean') {
|
|
151
|
+
return `${forms.join(', ')} ${formatValueHint(schema)}`;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
return forms.join(', ');
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
/**
|
|
158
|
+
* Produce a type hint like `<string>`, `<number>`, `<us|eu|ap>`.
|
|
159
|
+
*
|
|
160
|
+
* @param schema - The {@link FlagSchema} whose value type determines the hint.
|
|
161
|
+
* @returns Angle-bracketed hint string, or empty string for booleans.
|
|
162
|
+
*/
|
|
163
|
+
function formatValueHint(schema: FlagSchema): string {
|
|
164
|
+
switch (schema.kind) {
|
|
165
|
+
case 'string':
|
|
166
|
+
return '<string>';
|
|
167
|
+
case 'number':
|
|
168
|
+
return '<number>';
|
|
169
|
+
case 'enum': {
|
|
170
|
+
const vals = schema.enumValues ?? [];
|
|
171
|
+
return `<${vals.join('|')}>`;
|
|
172
|
+
}
|
|
173
|
+
case 'array': {
|
|
174
|
+
const elemHint =
|
|
175
|
+
schema.elementSchema !== undefined
|
|
176
|
+
? formatValueHint(schema.elementSchema).slice(1, -1) // strip < >
|
|
177
|
+
: 'value';
|
|
178
|
+
return `<${elemHint}>...`;
|
|
179
|
+
}
|
|
180
|
+
case 'boolean':
|
|
181
|
+
return '';
|
|
182
|
+
case 'custom':
|
|
183
|
+
return '<value>';
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/**
|
|
188
|
+
* Build description with env/config/prompt/default/required/deprecated annotations.
|
|
189
|
+
*
|
|
190
|
+
* @param schema - The {@link FlagSchema} to describe.
|
|
191
|
+
* @returns Concatenated description string with metadata annotations.
|
|
192
|
+
*/
|
|
193
|
+
function formatFlagDescription(schema: FlagSchema): string {
|
|
194
|
+
const parts: string[] = [];
|
|
195
|
+
|
|
196
|
+
if (schema.description !== undefined) {
|
|
197
|
+
parts.push(schema.description);
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
// Deprecation annotation — prominent, before other metadata
|
|
201
|
+
if (schema.deprecated !== undefined) {
|
|
202
|
+
parts.push(formatDeprecated(schema.deprecated));
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
// Resolution source annotations — show users where values can come from
|
|
206
|
+
if (schema.envVar !== undefined) {
|
|
207
|
+
parts.push(`[env: ${schema.envVar}]`);
|
|
208
|
+
}
|
|
209
|
+
if (schema.configPath !== undefined) {
|
|
210
|
+
parts.push(`[config: ${schema.configPath}]`);
|
|
211
|
+
}
|
|
212
|
+
if (schema.prompt !== undefined) {
|
|
213
|
+
parts.push('[prompt]');
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
if (schema.presence === 'required') {
|
|
217
|
+
parts.push('[required]');
|
|
218
|
+
} else if (schema.presence === 'defaulted' && schema.kind !== 'boolean') {
|
|
219
|
+
// Don't show "(default: false)" for boolean — it's obvious
|
|
220
|
+
parts.push(`(default: ${formatHelpDefaultValue(schema.defaultValue)})`);
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
return parts.join(' ');
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
/**
|
|
227
|
+
* Build the flag entries sorted: short-aliased first, then alphabetical.
|
|
228
|
+
*
|
|
229
|
+
* @param flags - Map of flag names to {@link FlagSchema} definitions.
|
|
230
|
+
* @returns Sorted array of {@link FlagEntry} objects for the flags table.
|
|
231
|
+
*/
|
|
232
|
+
function buildFlagEntries(flags: Readonly<Record<string, FlagSchema>>): readonly FlagEntry[] {
|
|
233
|
+
const names = Object.keys(flags);
|
|
234
|
+
if (names.length === 0) return [];
|
|
235
|
+
|
|
236
|
+
// Sort: flags with short aliases first, then alphabetically by name
|
|
237
|
+
const sorted = [...names].sort((a, b) => {
|
|
238
|
+
const aSchema = flags[a];
|
|
239
|
+
const bSchema = flags[b];
|
|
240
|
+
if (aSchema === undefined || bSchema === undefined) return 0;
|
|
241
|
+
const aHasShort = getFlagAliasNames(aSchema, { kind: 'short' }).length > 0;
|
|
242
|
+
const bHasShort = getFlagAliasNames(bSchema, { kind: 'short' }).length > 0;
|
|
243
|
+
if (aHasShort && !bHasShort) return -1;
|
|
244
|
+
if (!aHasShort && bHasShort) return 1;
|
|
245
|
+
return a.localeCompare(b);
|
|
246
|
+
});
|
|
247
|
+
|
|
248
|
+
const entries: FlagEntry[] = [];
|
|
249
|
+
for (const name of sorted) {
|
|
250
|
+
const schema = flags[name];
|
|
251
|
+
if (schema === undefined) continue;
|
|
252
|
+
entries.push({
|
|
253
|
+
left: formatFlagLeft(name, schema),
|
|
254
|
+
description: formatFlagDescription(schema),
|
|
255
|
+
});
|
|
256
|
+
}
|
|
257
|
+
return entries;
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
// --- Arg formatting
|
|
261
|
+
|
|
262
|
+
/**
|
|
263
|
+
* Format a positional arg for the usage line.
|
|
264
|
+
*
|
|
265
|
+
* @param entry - The {@link CommandArgEntry} containing name and schema.
|
|
266
|
+
* @returns Bracketed arg token, e.g. `<file>` or `[output]...`.
|
|
267
|
+
*/
|
|
268
|
+
function formatArgUsage(entry: CommandArgEntry): string {
|
|
269
|
+
const { name, schema } = entry;
|
|
270
|
+
const label =
|
|
271
|
+
schema.kind === 'enum' && schema.enumValues !== undefined ? schema.enumValues.join('|') : name;
|
|
272
|
+
const variadicSuffix = schema.variadic ? '...' : '';
|
|
273
|
+
if (schema.presence === 'required') {
|
|
274
|
+
return `<${label}>${variadicSuffix}`;
|
|
275
|
+
}
|
|
276
|
+
return `[${label}]${variadicSuffix}`;
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
/**
|
|
280
|
+
* Format arg description with annotations.
|
|
281
|
+
*
|
|
282
|
+
* @param schema - The {@link ArgSchema} to describe.
|
|
283
|
+
* @returns Concatenated description string with metadata annotations.
|
|
284
|
+
*/
|
|
285
|
+
function formatArgDescription(schema: ArgSchema): string {
|
|
286
|
+
const parts: string[] = [];
|
|
287
|
+
|
|
288
|
+
if (schema.description !== undefined) {
|
|
289
|
+
parts.push(schema.description);
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
if (schema.deprecated !== undefined) {
|
|
293
|
+
parts.push(formatDeprecated(schema.deprecated));
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
if (schema.envVar !== undefined) {
|
|
297
|
+
parts.push(`[env: ${schema.envVar}]`);
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
if (schema.presence === 'defaulted') {
|
|
301
|
+
parts.push(`(default: ${formatHelpDefaultValue(schema.defaultValue)})`);
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
return parts.join(' ');
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
// --- Main generator
|
|
308
|
+
|
|
309
|
+
/**
|
|
310
|
+
* Build the ordered help sections without joining them.
|
|
311
|
+
*
|
|
312
|
+
* @internal
|
|
313
|
+
* @param schema - The {@link CommandSchema} to render.
|
|
314
|
+
* @param options - Optional {@link HelpOptions} for width/bin name.
|
|
315
|
+
* @returns Array of section strings (usage, description, commands, args, flags, examples).
|
|
316
|
+
*/
|
|
317
|
+
function formatHelpSections(schema: CommandSchema, options?: HelpOptions): readonly string[] {
|
|
318
|
+
const opts = resolveOptions(options);
|
|
319
|
+
const sections: string[] = [];
|
|
320
|
+
|
|
321
|
+
// ---- Usage line ---------------------------------------------------------
|
|
322
|
+
sections.push(formatUsageLine(schema, opts));
|
|
323
|
+
|
|
324
|
+
// ---- Description --------------------------------------------------------
|
|
325
|
+
if (schema.description !== undefined) {
|
|
326
|
+
sections.push(schema.description);
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
// ---- Commands (subcommands) ---------------------------------------------
|
|
330
|
+
const visibleCommands = schema.commands.filter((c) => !c.hidden);
|
|
331
|
+
if (visibleCommands.length > 0) {
|
|
332
|
+
sections.push(formatCommandsSection(visibleCommands, opts));
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
// ---- Arguments ----------------------------------------------------------
|
|
336
|
+
if (schema.args.length > 0) {
|
|
337
|
+
sections.push(formatArgsSection(schema.args, opts));
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
// ---- Flags --------------------------------------------------------------
|
|
341
|
+
const flagNames = Object.keys(schema.flags);
|
|
342
|
+
if (flagNames.length > 0) {
|
|
343
|
+
sections.push(formatFlagsSection(schema.flags, opts));
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
// ---- Examples -----------------------------------------------------------
|
|
347
|
+
if (schema.examples.length > 0) {
|
|
348
|
+
sections.push(formatExamplesSection(schema.examples));
|
|
349
|
+
}
|
|
350
|
+
|
|
351
|
+
return sections;
|
|
352
|
+
}
|
|
353
|
+
|
|
354
|
+
/**
|
|
355
|
+
* Generate help text from a command schema.
|
|
356
|
+
*
|
|
357
|
+
* Low-level formatter: most applications reach this through `--help`,
|
|
358
|
+
* `help <command>`, or root help rendering in `CLIBuilder`. Call
|
|
359
|
+
* `formatHelp()` directly when embedding DreamCLI help text into custom UIs,
|
|
360
|
+
* tests, or generated docs.
|
|
361
|
+
*
|
|
362
|
+
* Sections rendered (in order):
|
|
363
|
+
* 1. **Usage** line — `program <command> [flags] <args>`
|
|
364
|
+
* 2. **Description** — the command's `.description()` text
|
|
365
|
+
* 3. **Commands** — subcommands table (if any, skips hidden)
|
|
366
|
+
* 4. **Arguments** — positional args table (if any)
|
|
367
|
+
* 5. **Flags** — flags table with type hints and defaults
|
|
368
|
+
* 6. **Examples** — usage examples (if any)
|
|
369
|
+
*
|
|
370
|
+
* @param schema - The command schema to render help for.
|
|
371
|
+
* @param options - Formatting options (width, binary name).
|
|
372
|
+
* @returns The formatted help string.
|
|
373
|
+
*
|
|
374
|
+
* @example
|
|
375
|
+
* ```ts
|
|
376
|
+
* const text = formatHelp(deploy.schema, { binName: 'mycli' });
|
|
377
|
+
* ```
|
|
378
|
+
*/
|
|
379
|
+
function formatHelp(schema: CommandSchema, options?: HelpOptions): string {
|
|
380
|
+
return `${formatHelpSections(schema, options).join('\n\n')}\n`;
|
|
381
|
+
}
|
|
382
|
+
|
|
383
|
+
// --- Section renderers
|
|
384
|
+
|
|
385
|
+
/**
|
|
386
|
+
* Render the `Usage:` line for a command.
|
|
387
|
+
*
|
|
388
|
+
* @param schema - The {@link CommandSchema} to summarize.
|
|
389
|
+
* @param opts - Resolved help options (bin name, default-help flag).
|
|
390
|
+
* @returns Single-line usage string, e.g. `Usage: mycli deploy [flags] <env>`.
|
|
391
|
+
*/
|
|
392
|
+
function formatUsageLine(schema: CommandSchema, opts: ResolvedHelpOptions): string {
|
|
393
|
+
const parts: string[] = ['Usage:'];
|
|
394
|
+
const cmdName =
|
|
395
|
+
opts.binName === undefined
|
|
396
|
+
? schema.name
|
|
397
|
+
: opts.isDefaultHelp && opts.binName === schema.name
|
|
398
|
+
? schema.name
|
|
399
|
+
: `${opts.binName} ${schema.name}`;
|
|
400
|
+
parts.push(cmdName);
|
|
401
|
+
|
|
402
|
+
// Subcommand placeholder — groups show <command> before flags/args
|
|
403
|
+
if (schema.commands.length > 0) {
|
|
404
|
+
parts.push('<command>');
|
|
405
|
+
}
|
|
406
|
+
|
|
407
|
+
// Flags placeholder
|
|
408
|
+
const flagNames = Object.keys(schema.flags);
|
|
409
|
+
if (flagNames.length > 0) {
|
|
410
|
+
parts.push('[flags]');
|
|
411
|
+
}
|
|
412
|
+
|
|
413
|
+
// Positional args
|
|
414
|
+
for (const entry of schema.args) {
|
|
415
|
+
parts.push(formatArgUsage(entry));
|
|
416
|
+
}
|
|
417
|
+
|
|
418
|
+
return parts.join(' ');
|
|
419
|
+
}
|
|
420
|
+
|
|
421
|
+
/**
|
|
422
|
+
* Render the `Arguments:` help section.
|
|
423
|
+
*
|
|
424
|
+
* @param args - Positional arg entries from the {@link CommandSchema}.
|
|
425
|
+
* @param opts - Resolved help options for line-width wrapping.
|
|
426
|
+
* @returns Multi-line arguments section string.
|
|
427
|
+
*/
|
|
428
|
+
function formatArgsSection(args: readonly CommandArgEntry[], opts: ResolvedHelpOptions): string {
|
|
429
|
+
const lines: string[] = ['Arguments:'];
|
|
430
|
+
const GAP = 2;
|
|
431
|
+
|
|
432
|
+
// Compute max left width
|
|
433
|
+
let maxLeft = 0;
|
|
434
|
+
const entries: Array<{ left: string; desc: string }> = [];
|
|
435
|
+
for (const entry of args) {
|
|
436
|
+
const left = ` ${formatArgUsage(entry)}`;
|
|
437
|
+
const desc = formatArgDescription(entry.schema);
|
|
438
|
+
entries.push({ left, desc });
|
|
439
|
+
if (left.length > maxLeft) maxLeft = left.length;
|
|
440
|
+
}
|
|
441
|
+
|
|
442
|
+
const descCol = maxLeft + GAP;
|
|
443
|
+
for (const { left, desc } of entries) {
|
|
444
|
+
if (desc.length === 0) {
|
|
445
|
+
lines.push(left);
|
|
446
|
+
} else {
|
|
447
|
+
const padded = padEnd(left, descCol);
|
|
448
|
+
const wrapped = wrapText(desc, opts.width, descCol);
|
|
449
|
+
lines.push(`${padded}${wrapped}`);
|
|
450
|
+
}
|
|
451
|
+
}
|
|
452
|
+
|
|
453
|
+
return lines.join('\n');
|
|
454
|
+
}
|
|
455
|
+
|
|
456
|
+
/**
|
|
457
|
+
* Render the `Flags:` help section.
|
|
458
|
+
*
|
|
459
|
+
* @param flags - Map of flag names to {@link FlagSchema} definitions.
|
|
460
|
+
* @param opts - Resolved help options for line-width wrapping.
|
|
461
|
+
* @returns Multi-line flags section string.
|
|
462
|
+
*/
|
|
463
|
+
function formatFlagsSection(
|
|
464
|
+
flags: Readonly<Record<string, FlagSchema>>,
|
|
465
|
+
opts: ResolvedHelpOptions,
|
|
466
|
+
): string {
|
|
467
|
+
const lines: string[] = ['Flags:'];
|
|
468
|
+
const GAP = 2;
|
|
469
|
+
|
|
470
|
+
const entries = buildFlagEntries(flags);
|
|
471
|
+
if (entries.length === 0) return '';
|
|
472
|
+
|
|
473
|
+
// Compute max left width
|
|
474
|
+
let maxLeft = 0;
|
|
475
|
+
for (const entry of entries) {
|
|
476
|
+
const indented = ` ${entry.left}`;
|
|
477
|
+
if (indented.length > maxLeft) maxLeft = indented.length;
|
|
478
|
+
}
|
|
479
|
+
|
|
480
|
+
const descCol = maxLeft + GAP;
|
|
481
|
+
for (const entry of entries) {
|
|
482
|
+
const left = ` ${entry.left}`;
|
|
483
|
+
if (entry.description.length === 0) {
|
|
484
|
+
lines.push(left);
|
|
485
|
+
} else {
|
|
486
|
+
const padded = padEnd(left, descCol);
|
|
487
|
+
const wrapped = wrapText(entry.description, opts.width, descCol);
|
|
488
|
+
lines.push(`${padded}${wrapped}`);
|
|
489
|
+
}
|
|
490
|
+
}
|
|
491
|
+
|
|
492
|
+
return lines.join('\n');
|
|
493
|
+
}
|
|
494
|
+
|
|
495
|
+
/**
|
|
496
|
+
* Render the `Commands:` help section.
|
|
497
|
+
*
|
|
498
|
+
* @param commands - Visible subcommand schemas (hidden commands pre-filtered).
|
|
499
|
+
* @param opts - Resolved help options for line-width wrapping.
|
|
500
|
+
* @returns Multi-line commands section string.
|
|
501
|
+
*/
|
|
502
|
+
function formatCommandsSection(
|
|
503
|
+
commands: readonly CommandSchema[],
|
|
504
|
+
opts: ResolvedHelpOptions,
|
|
505
|
+
): string {
|
|
506
|
+
const lines: string[] = ['Commands:'];
|
|
507
|
+
const GAP = 2;
|
|
508
|
+
|
|
509
|
+
// Compute max name length for alignment
|
|
510
|
+
let maxNameLen = 0;
|
|
511
|
+
for (const cmd of commands) {
|
|
512
|
+
if (cmd.name.length > maxNameLen) {
|
|
513
|
+
maxNameLen = cmd.name.length;
|
|
514
|
+
}
|
|
515
|
+
}
|
|
516
|
+
|
|
517
|
+
const descCol = 2 + maxNameLen + GAP; // 2 for indent
|
|
518
|
+
for (const cmd of commands) {
|
|
519
|
+
const left = ` ${cmd.name}`;
|
|
520
|
+
const desc = cmd.description ?? '';
|
|
521
|
+
if (desc.length === 0) {
|
|
522
|
+
lines.push(left);
|
|
523
|
+
} else {
|
|
524
|
+
const padded = padEnd(left, descCol);
|
|
525
|
+
const wrapped = wrapText(desc, opts.width, descCol);
|
|
526
|
+
lines.push(`${padded}${wrapped}`);
|
|
527
|
+
}
|
|
528
|
+
}
|
|
529
|
+
|
|
530
|
+
return lines.join('\n');
|
|
531
|
+
}
|
|
532
|
+
|
|
533
|
+
/**
|
|
534
|
+
* Render the `Examples:` help section.
|
|
535
|
+
*
|
|
536
|
+
* @param examples - Array of {@link CommandExample} entries.
|
|
537
|
+
* @returns Multi-line examples section string.
|
|
538
|
+
*/
|
|
539
|
+
function formatExamplesSection(examples: readonly CommandExample[]): string {
|
|
540
|
+
const lines: string[] = ['Examples:'];
|
|
541
|
+
|
|
542
|
+
for (const example of examples) {
|
|
543
|
+
if (example.description !== undefined) {
|
|
544
|
+
lines.push(` ${example.description}:`);
|
|
545
|
+
lines.push(` $ ${example.command}`);
|
|
546
|
+
} else {
|
|
547
|
+
lines.push(` $ ${example.command}`);
|
|
548
|
+
}
|
|
549
|
+
}
|
|
550
|
+
|
|
551
|
+
return lines.join('\n');
|
|
552
|
+
}
|
|
553
|
+
|
|
554
|
+
// --- Exports
|
|
555
|
+
|
|
556
|
+
export type { HelpOptions };
|
|
557
|
+
export { formatHelp, formatHelpSections };
|