@kjanat/dreamcli 2.5.0 → 3.0.0-rc.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +128 -1
- package/README.md +9 -2
- package/dist/core/cli/index.d.mts +109 -16
- package/dist/core/cli/index.mjs +1 -1
- package/dist/core/cli/planner.d.mts +27 -5
- package/dist/core/cli/planner.mjs +1 -1
- package/dist/core/cli/root-help.d.mts +16 -2
- package/dist/core/cli/root-help.mjs +3 -5
- package/dist/core/cli/root-surface.d.mts +18 -3
- package/dist/core/cli/root-surface.mjs +1 -1
- package/dist/core/cli/runtime-preflight.d.mts +16 -1
- package/dist/core/cli/runtime-preflight.mjs +1 -1
- package/dist/core/completion/index.d.mts +32 -1
- package/dist/core/completion/index.mjs +1 -1
- package/dist/core/completion/shells/shared.d.mts +10 -0
- package/dist/core/completion/shells/shared.mjs +1 -1
- package/dist/core/help/index.d.mts +45 -1
- package/dist/core/help/index.mjs +6 -6
- package/dist/core/json-schema/index.mjs +1 -1
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +38 -38
- package/dist/core/parse/index.d.mts +15 -1
- package/dist/core/parse/index.mjs +1 -1
- package/dist/core/prompt/index.d.mts +11 -3
- package/dist/core/prompt/index.mjs +3 -3
- package/dist/core/resolve/coerce.mjs +1 -1
- package/dist/core/resolve/flags.mjs +1 -1
- package/dist/core/resolve/property.d.mts +2 -0
- package/dist/core/resolve/property.mjs +1 -1
- package/dist/core/schema/arg.d.mts +90 -10
- package/dist/core/schema/arg.mjs +1 -1
- package/dist/core/schema/command.d.mts +3 -1
- package/dist/core/schema/flag.d.mts +92 -2
- package/dist/core/schema/flag.mjs +1 -1
- package/dist/core/schema/index.d.mts +2 -1
- package/dist/core/schema/number-constraints.d.mts +96 -0
- package/dist/core/schema/number-constraints.mjs +1 -0
- package/dist/core/schema/prompt.d.mts +15 -0
- package/dist/core/schema/run.d.mts +4 -4
- package/dist/core/testkit/index.d.mts +9 -5
- package/dist/core/testkit/index.mjs +1 -1
- package/dist/index.d.mts +2 -1
- package/dist/index.mjs +1 -1
- package/dist/runtime/auto.mjs +1 -1
- package/dist/runtime/bun.mjs +1 -1
- package/dist/runtime/deno.mjs +2 -2
- package/dist/runtime/node.mjs +2 -2
- package/dist/version.mjs +1 -1
- package/examples/basic.ts +5 -1
- package/examples/gh/package.json +2 -7
- package/examples/pwsh-demo/package.json +1 -7
- package/examples/pwsh-demo/src/main.test.ts +1 -4
- package/examples/pwsh-demo/src/main.ts +14 -4
- package/examples/transport-launcher.ts +85 -0
- package/package.json +15 -24
- package/src/core/cli/dispatch.ts +7 -1
- package/src/core/cli/index.ts +235 -34
- package/src/core/cli/planner.ts +192 -23
- package/src/core/cli/root-help.ts +195 -105
- package/src/core/cli/root-surface.ts +25 -12
- package/src/core/cli/runtime-preflight.ts +20 -2
- package/src/core/completion/index.ts +50 -0
- package/src/core/completion/shells/powershell.ts +2 -2
- package/src/core/completion/shells/shared.ts +30 -3
- package/src/core/execution/index.ts +1 -4
- package/src/core/help/index.ts +57 -10
- package/src/core/json-schema/index.ts +23 -4
- package/src/core/json-schema/meta-descriptions.generated.ts +115 -98
- package/src/core/parse/index.ts +62 -1
- package/src/core/prompt/index.ts +54 -14
- package/src/core/resolve/coerce.ts +73 -5
- package/src/core/resolve/flags.ts +14 -0
- package/src/core/resolve/property.ts +4 -4
- package/src/core/schema/arg.ts +125 -3
- package/src/core/schema/command.ts +3 -1
- package/src/core/schema/flag.ts +120 -4
- package/src/core/schema/index.ts +5 -0
- package/src/core/schema/number-constraints.ts +153 -0
- package/src/core/schema/prompt.ts +15 -0
- package/src/core/schema/run.ts +4 -4
- package/src/core/testkit/index.ts +32 -8
- package/src/index.ts +2 -0
- package/src/runtime/auto.ts +0 -24
- package/src/runtime/bun.ts +0 -7
- package/src/runtime/deno.ts +0 -2
- package/src/runtime/node.ts +0 -11
- package/src/runtime/support.ts +1 -59
- package/src/schema.ts +16 -0
- package/dist/runtime/support.d.mts +0 -42
- package/dist/runtime/support.mjs +0 -1
|
@@ -29,13 +29,26 @@ interface RootSurfaceSchemaLike {
|
|
|
29
29
|
/**
|
|
30
30
|
* Normalized root shape shared by help and completion logic.
|
|
31
31
|
*
|
|
32
|
+
* Since v0.3 the default command is a distinct root *surface* rather than a
|
|
33
|
+
* named subcommand: `.default()` no longer registers it under
|
|
34
|
+
* {@link RootSurfaceSchemaLike.commands}. To stay robust against callers that
|
|
35
|
+
* still place the default in the command list (e.g. hand-built test schemas),
|
|
36
|
+
* {@link resolveRootSurface} always derives {@link RootSurface.visibleSubcommands}
|
|
37
|
+
* by excluding the default command from the visible command list.
|
|
38
|
+
*
|
|
32
39
|
* @internal
|
|
33
40
|
*/
|
|
34
41
|
interface RootSurface {
|
|
42
|
+
/** All visible top-level commands as declared in `schema.commands`. */
|
|
35
43
|
readonly visibleCommands: readonly CommandSchema[];
|
|
44
|
+
/** Visible real subcommands — `visibleCommands` minus the default command. */
|
|
45
|
+
readonly visibleSubcommands: readonly CommandSchema[];
|
|
46
|
+
/** The visible default command, or `undefined` when none exists or it is hidden. */
|
|
36
47
|
readonly visibleDefaultCommand: CommandSchema | undefined;
|
|
37
|
-
|
|
38
|
-
readonly
|
|
48
|
+
/** Whether a visible default command exists. */
|
|
49
|
+
readonly hasVisibleDefault: boolean;
|
|
50
|
+
/** Whether any visible real subcommands exist (the default does not count). */
|
|
51
|
+
readonly hasVisibleSubcommands: boolean;
|
|
39
52
|
}
|
|
40
53
|
|
|
41
54
|
/**
|
|
@@ -43,7 +56,9 @@ interface RootSurface {
|
|
|
43
56
|
*
|
|
44
57
|
* Hidden commands are excluded from the visible command list. Hidden
|
|
45
58
|
* default commands remain executable, but are not surfaced through
|
|
46
|
-
* help or completions.
|
|
59
|
+
* help or completions. The default command is reported separately from the
|
|
60
|
+
* real subcommands so help and completion can render it as the root surface
|
|
61
|
+
* instead of echoing it as a pseudo-subcommand.
|
|
47
62
|
*
|
|
48
63
|
* @internal
|
|
49
64
|
*/
|
|
@@ -54,19 +69,17 @@ function resolveRootSurface(schema: RootSurfaceSchemaLike): RootSurface {
|
|
|
54
69
|
const rawDefaultCommand = schema.defaultCommand?.schema;
|
|
55
70
|
const visibleDefaultCommand =
|
|
56
71
|
rawDefaultCommand !== undefined && !rawDefaultCommand.hidden ? rawDefaultCommand : undefined;
|
|
57
|
-
const
|
|
58
|
-
visibleDefaultCommand !== undefined
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
const hasVisibleSiblingCommands =
|
|
62
|
-
visibleDefaultCommand !== undefined &&
|
|
63
|
-
visibleCommands.some((command) => command.name !== visibleDefaultCommand.name);
|
|
72
|
+
const visibleSubcommands =
|
|
73
|
+
visibleDefaultCommand !== undefined
|
|
74
|
+
? visibleCommands.filter((command) => command.name !== visibleDefaultCommand.name)
|
|
75
|
+
: visibleCommands;
|
|
64
76
|
|
|
65
77
|
return {
|
|
66
78
|
visibleCommands,
|
|
79
|
+
visibleSubcommands,
|
|
67
80
|
visibleDefaultCommand,
|
|
68
|
-
|
|
69
|
-
|
|
81
|
+
hasVisibleDefault: visibleDefaultCommand !== undefined,
|
|
82
|
+
hasVisibleSubcommands: visibleSubcommands.length > 0,
|
|
70
83
|
};
|
|
71
84
|
}
|
|
72
85
|
|
|
@@ -9,6 +9,7 @@
|
|
|
9
9
|
* @internal
|
|
10
10
|
*/
|
|
11
11
|
|
|
12
|
+
import type { CompletionOptions, Shell } from '#internals/core/completion/index.ts';
|
|
12
13
|
import type { FormatLoader } from '#internals/core/config/index.ts';
|
|
13
14
|
import { discoverConfig } from '#internals/core/config/index.ts';
|
|
14
15
|
import type { PackageJsonData } from '#internals/core/config/package-json.ts';
|
|
@@ -80,8 +81,22 @@ interface RuntimePreflightSchemaLike {
|
|
|
80
81
|
readonly packageJsonSettings: RuntimeManifestSettings | undefined;
|
|
81
82
|
/** Root-help header link targets; `undefined` fields may be derived from package.json. */
|
|
82
83
|
readonly helpLinks: HelpLinks | undefined;
|
|
83
|
-
/** Whether `.completions()` registered the built-in completions command. */
|
|
84
|
+
/** Whether `.completions()` registered the built-in completions command/flag. */
|
|
84
85
|
readonly hasBuiltInCompletions: boolean;
|
|
86
|
+
/** Eager `--completions <shell>` flag config; `undefined` disables interception. */
|
|
87
|
+
readonly completionsFlag:
|
|
88
|
+
| { readonly shells: readonly Shell[]; readonly options: CompletionOptions | undefined }
|
|
89
|
+
| undefined;
|
|
90
|
+
/** Consumer-configured root-help defaults. */
|
|
91
|
+
readonly helpConfig:
|
|
92
|
+
| {
|
|
93
|
+
readonly inlineDefault?: boolean;
|
|
94
|
+
readonly showDefaultInCommands?: boolean;
|
|
95
|
+
readonly footer?: boolean;
|
|
96
|
+
readonly width?: number;
|
|
97
|
+
readonly hyperlinks?: boolean;
|
|
98
|
+
}
|
|
99
|
+
| undefined;
|
|
85
100
|
/** Plugins forwarded into the execution pipeline. */
|
|
86
101
|
readonly plugins: readonly CLIPlugin[];
|
|
87
102
|
}
|
|
@@ -264,6 +279,7 @@ function invocationNeedsStdin(
|
|
|
264
279
|
case 'needs-subcommand':
|
|
265
280
|
case 'root-help':
|
|
266
281
|
case 'root-version':
|
|
282
|
+
case 'root-completions':
|
|
267
283
|
return false;
|
|
268
284
|
}
|
|
269
285
|
}
|
|
@@ -300,7 +316,9 @@ async function applyPackageJsonDiscovery(
|
|
|
300
316
|
const pkg =
|
|
301
317
|
packageJsonSettings.data ??
|
|
302
318
|
(await discoverManifest(adapter, {
|
|
303
|
-
...(packageJsonSettings.from !== undefined
|
|
319
|
+
...(packageJsonSettings.from !== undefined
|
|
320
|
+
? { startDir: packageJsonSettings.from }
|
|
321
|
+
: {}),
|
|
304
322
|
files: packageJsonSettings.files,
|
|
305
323
|
}));
|
|
306
324
|
if (pkg === null) return schema;
|
|
@@ -41,6 +41,54 @@ const SHELLS: Readonly<readonly ['bash', 'zsh', 'fish', 'powershell']> = Object.
|
|
|
41
41
|
'powershell',
|
|
42
42
|
] as const satisfies readonly ['bash', 'zsh', 'fish', 'powershell']);
|
|
43
43
|
|
|
44
|
+
// --- Shell token normalization
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* Normalize a raw shell token — a bare name (`zsh`), a `$SHELL` path
|
|
48
|
+
* (`/bin/zsh`), or a Windows executable (`…\pwsh.exe`) — to a supported
|
|
49
|
+
* {@link Shell}, or `undefined` when it does not map to one.
|
|
50
|
+
*
|
|
51
|
+
* Mirrors the matching used by the `completions` subcommand so the subcommand
|
|
52
|
+
* and the eager `--completions <shell>` flag accept exactly the same inputs.
|
|
53
|
+
*
|
|
54
|
+
* @param raw - User-supplied shell token or interpreter path.
|
|
55
|
+
* @returns The resolved {@link Shell}, or `undefined` if unrecognized.
|
|
56
|
+
*/
|
|
57
|
+
function normalizeShell(raw: string): Shell | undefined {
|
|
58
|
+
const segments = raw.split(/[\\/]/);
|
|
59
|
+
const basename = segments[segments.length - 1] ?? raw;
|
|
60
|
+
const name = basename.replace(/\.(?:exe|cmd|bat)$/i, '');
|
|
61
|
+
if (name === 'pwsh') return 'powershell';
|
|
62
|
+
return (SHELLS as readonly string[]).includes(name) ? (name as Shell) : undefined;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* Auto-detect the current shell from environment variables.
|
|
67
|
+
*
|
|
68
|
+
* Resolution order:
|
|
69
|
+
* 1. `$SHELL` parsed as an interpreter path (`/bin/zsh` → `zsh`). It wins when
|
|
70
|
+
* it names a shell we support — a pwsh session launched from bash inherits
|
|
71
|
+
* `SHELL=/bin/bash`, and the login shell the user opted into should be
|
|
72
|
+
* honored over the fallback.
|
|
73
|
+
* 2. Otherwise, the presence of `$PSModulePath` signals PowerShell. PowerShell
|
|
74
|
+
* never sets `$SHELL` on any platform but always exports `PSModulePath` for
|
|
75
|
+
* module discovery, so it is the reliable pwsh signal.
|
|
76
|
+
*
|
|
77
|
+
* Returns `undefined` when no signal resolves, leaving the caller to ask the
|
|
78
|
+
* user for an explicit shell.
|
|
79
|
+
*
|
|
80
|
+
* @param env - Environment record (e.g. `process.env` or an adapter's env).
|
|
81
|
+
* @returns The detected {@link Shell}, or `undefined`.
|
|
82
|
+
*/
|
|
83
|
+
function detectShell(env: Readonly<Record<string, string | undefined>>): Shell | undefined {
|
|
84
|
+
const shellVar = env.SHELL;
|
|
85
|
+
const fromShell =
|
|
86
|
+
shellVar !== undefined && shellVar !== '' ? normalizeShell(shellVar) : undefined;
|
|
87
|
+
if (fromShell !== undefined) return fromShell;
|
|
88
|
+
if (env.PSModulePath !== undefined) return 'powershell';
|
|
89
|
+
return undefined;
|
|
90
|
+
}
|
|
91
|
+
|
|
44
92
|
// --- Shell-agnostic dispatch
|
|
45
93
|
|
|
46
94
|
/**
|
|
@@ -84,5 +132,7 @@ export {
|
|
|
84
132
|
generateFishCompletion,
|
|
85
133
|
generatePowerShellCompletion,
|
|
86
134
|
generateZshCompletion,
|
|
135
|
+
detectShell,
|
|
136
|
+
normalizeShell,
|
|
87
137
|
SHELLS,
|
|
88
138
|
};
|
|
@@ -318,14 +318,14 @@ function emitPowerShellHelpers(lines: string[], helperPrefix: string, dataVarNam
|
|
|
318
318
|
lines.push(`function ${helperPrefix}_FormatCompletionValue {`);
|
|
319
319
|
lines.push('\tparam([string]$Value)');
|
|
320
320
|
lines.push('\tif ($Value.Length -eq 0) {');
|
|
321
|
-
lines.push(
|
|
321
|
+
lines.push('\t\treturn "\'\'"');
|
|
322
322
|
lines.push('\t}');
|
|
323
323
|
lines.push('');
|
|
324
324
|
lines.push("\tif ($Value -match '^[a-zA-Z0-9_./:\\\\-]+$') {");
|
|
325
325
|
lines.push('\t\treturn $Value');
|
|
326
326
|
lines.push('\t}');
|
|
327
327
|
lines.push('');
|
|
328
|
-
lines.push(
|
|
328
|
+
lines.push('\treturn "\'$([CodeGeneration]::EscapeSingleQuotedStringContent($Value))\'"');
|
|
329
329
|
lines.push('}');
|
|
330
330
|
lines.push('');
|
|
331
331
|
lines.push(`function ${helperPrefix}_MatchesCompletionPrefix {`);
|
|
@@ -54,6 +54,16 @@ interface CompletionOptions {
|
|
|
54
54
|
* ```
|
|
55
55
|
*/
|
|
56
56
|
readonly functionPrefix?: string;
|
|
57
|
+
/**
|
|
58
|
+
* Where the built-in shell completion is exposed.
|
|
59
|
+
*
|
|
60
|
+
* - `'command'` registers a `completions` subcommand (the default).
|
|
61
|
+
* - `'flag'` exposes an eager `--completions <shell>` flag on the CLI root
|
|
62
|
+
* instead, keeping the root free of a `completions` subcommand.
|
|
63
|
+
*
|
|
64
|
+
* @defaultValue `'command'`
|
|
65
|
+
*/
|
|
66
|
+
readonly as?: 'command' | 'flag';
|
|
57
67
|
/**
|
|
58
68
|
* Controls which root-level surface shell completion exposes when a
|
|
59
69
|
* default command exists.
|
|
@@ -109,13 +119,29 @@ function resolveRootCompletionSurface(
|
|
|
109
119
|
const rootSurface = resolveRootSurface(schema);
|
|
110
120
|
const rootFlags = createRootFlags(schema.version !== undefined);
|
|
111
121
|
const defaultFlags = rootSurface.visibleDefaultCommand?.flags ?? {};
|
|
122
|
+
// Default flags surface at the root either always (`surface`) or only when
|
|
123
|
+
// the default is the sole surface (`subcommands`).
|
|
112
124
|
const includeDefaultFlags =
|
|
113
125
|
rootMode === 'surface'
|
|
114
|
-
? rootSurface.
|
|
115
|
-
: rootSurface.
|
|
126
|
+
? rootSurface.hasVisibleDefault
|
|
127
|
+
: rootSurface.hasVisibleDefault && !rootSurface.hasVisibleSubcommands;
|
|
128
|
+
|
|
129
|
+
// Generated completion scripts keep treating the default command as part of
|
|
130
|
+
// the root surface (a walkable node carrying its own flags/args), regardless
|
|
131
|
+
// of whether it is registered under `commands` — since v0.3 `.default()` keeps
|
|
132
|
+
// it only in `defaultCommand`. Re-add it here so the per-shell generators,
|
|
133
|
+
// which build their dispatch machinery from this list, behave unchanged.
|
|
134
|
+
const defaultCommand = rootSurface.visibleDefaultCommand;
|
|
135
|
+
const alreadyListed =
|
|
136
|
+
defaultCommand !== undefined &&
|
|
137
|
+
rootSurface.visibleCommands.some((c) => c.name === defaultCommand.name);
|
|
138
|
+
const visibleCommands =
|
|
139
|
+
defaultCommand !== undefined && !alreadyListed
|
|
140
|
+
? [defaultCommand, ...rootSurface.visibleCommands]
|
|
141
|
+
: rootSurface.visibleCommands;
|
|
116
142
|
|
|
117
143
|
return {
|
|
118
|
-
visibleCommands
|
|
144
|
+
visibleCommands,
|
|
119
145
|
visibleDefaultCommand: rootSurface.visibleDefaultCommand,
|
|
120
146
|
rootFlags,
|
|
121
147
|
defaultFlags,
|
|
@@ -154,6 +180,7 @@ function createSyntheticRootFlag(description: string): FlagSchema {
|
|
|
154
180
|
configPath: undefined,
|
|
155
181
|
description,
|
|
156
182
|
enumValues: undefined,
|
|
183
|
+
numberConstraints: undefined,
|
|
157
184
|
elementSchema: undefined,
|
|
158
185
|
prompt: undefined,
|
|
159
186
|
parseFn: undefined,
|
|
@@ -16,10 +16,7 @@ import type {
|
|
|
16
16
|
import { CLIError } from '#internals/core/errors/index.ts';
|
|
17
17
|
import { formatHelp } from '#internals/core/help/index.ts';
|
|
18
18
|
import type { CapturedOutput } from '#internals/core/output/index.ts';
|
|
19
|
-
import {
|
|
20
|
-
clearRequestedExitCode,
|
|
21
|
-
getRequestedExitCode,
|
|
22
|
-
} from '#internals/core/output/index.ts';
|
|
19
|
+
import { clearRequestedExitCode, getRequestedExitCode } from '#internals/core/output/index.ts';
|
|
23
20
|
import { includesBeforeSeparator, parse } from '#internals/core/parse/index.ts';
|
|
24
21
|
import { createTestPrompter } from '#internals/core/prompt/index.ts';
|
|
25
22
|
import type { DeprecationWarning, ResolveOptions } from '#internals/core/resolve/index.ts';
|
package/src/core/help/index.ts
CHANGED
|
@@ -34,6 +34,31 @@ interface HelpOptions {
|
|
|
34
34
|
* automatically when stdout is a TTY.
|
|
35
35
|
*/
|
|
36
36
|
readonly hyperlinks?: boolean;
|
|
37
|
+
/**
|
|
38
|
+
* Render the default command's arguments and flags inline in root help.
|
|
39
|
+
*
|
|
40
|
+
* Only affects root-level help. When `false`, root help lists commands and
|
|
41
|
+
* defers default-command details to `<bin> --help`-style hints.
|
|
42
|
+
*
|
|
43
|
+
* @defaultValue `true`
|
|
44
|
+
*/
|
|
45
|
+
readonly inlineDefault?: boolean;
|
|
46
|
+
/**
|
|
47
|
+
* List the default command in the root `Commands:` table.
|
|
48
|
+
*
|
|
49
|
+
* By default the default command is treated as the root surface and omitted
|
|
50
|
+
* from the command list (its args/flags render inline instead).
|
|
51
|
+
*
|
|
52
|
+
* @defaultValue `false`
|
|
53
|
+
*/
|
|
54
|
+
readonly showDefaultInCommands?: boolean;
|
|
55
|
+
/**
|
|
56
|
+
* Show the `Run '<bin> <command> --help' for more information.` footer.
|
|
57
|
+
*
|
|
58
|
+
* Defaults to showing the hint only when visible subcommands exist; set
|
|
59
|
+
* explicitly to force it on or off.
|
|
60
|
+
*/
|
|
61
|
+
readonly footer?: boolean;
|
|
37
62
|
/** @internal Whether this usage line is being rendered as merged root/default help. */
|
|
38
63
|
readonly isDefaultHelp?: boolean;
|
|
39
64
|
}
|
|
@@ -82,7 +107,7 @@ function formatHelpDefaultValue(value: unknown): string {
|
|
|
82
107
|
|
|
83
108
|
// --- Flag formatting
|
|
84
109
|
|
|
85
|
-
/** Formatted flag entry for the flags table. */
|
|
110
|
+
/** Formatted flag entry for the flags table. @internal */
|
|
86
111
|
interface FlagEntry {
|
|
87
112
|
readonly left: string;
|
|
88
113
|
readonly description: string;
|
|
@@ -349,11 +374,15 @@ function formatHelp(schema: CommandSchema, options?: HelpOptions): string {
|
|
|
349
374
|
*/
|
|
350
375
|
function formatUsageLine(schema: CommandSchema, opts: ResolvedHelpOptions): string {
|
|
351
376
|
const parts: string[] = ['Usage:'];
|
|
377
|
+
// For the default command rendered as the root surface (`isDefaultHelp`), the
|
|
378
|
+
// command name is NOT a route — `.default()` does not register a named command,
|
|
379
|
+
// so `mycli <name>` would be consumed as the default's first positional, not a
|
|
380
|
+
// dispatch. Render usage with only the bin name to avoid teaching a fake form.
|
|
352
381
|
const cmdName =
|
|
353
382
|
opts.binName === undefined
|
|
354
383
|
? schema.name
|
|
355
|
-
: opts.isDefaultHelp
|
|
356
|
-
?
|
|
384
|
+
: opts.isDefaultHelp
|
|
385
|
+
? opts.binName
|
|
357
386
|
: `${opts.binName} ${schema.name}`;
|
|
358
387
|
parts.push(cmdName);
|
|
359
388
|
|
|
@@ -422,13 +451,31 @@ function formatFlagsSection(
|
|
|
422
451
|
flags: Readonly<Record<string, FlagSchema>>,
|
|
423
452
|
opts: ResolvedHelpOptions,
|
|
424
453
|
): string {
|
|
425
|
-
|
|
426
|
-
|
|
454
|
+
return formatFlagEntriesBlock('Flags:', buildFlagEntries(flags), opts.width);
|
|
455
|
+
}
|
|
427
456
|
|
|
428
|
-
|
|
457
|
+
/**
|
|
458
|
+
* Render a titled two-column flag block from pre-built {@link FlagEntry} rows.
|
|
459
|
+
*
|
|
460
|
+
* Shared by the per-command `Flags:` section and the root-help `Global options:`
|
|
461
|
+
* block (built-in flags), so column alignment and description wrapping stay
|
|
462
|
+
* identical across both. Returns `''` when there are no entries.
|
|
463
|
+
*
|
|
464
|
+
* @param title - Section heading (e.g. `'Flags:'`, `'Global options:'`).
|
|
465
|
+
* @param entries - Formatted left/description rows.
|
|
466
|
+
* @param width - Terminal width for description wrapping.
|
|
467
|
+
* @returns Multi-line block string, or `''` when `entries` is empty.
|
|
468
|
+
* @internal
|
|
469
|
+
*/
|
|
470
|
+
function formatFlagEntriesBlock(
|
|
471
|
+
title: string,
|
|
472
|
+
entries: readonly FlagEntry[],
|
|
473
|
+
width: number,
|
|
474
|
+
): string {
|
|
429
475
|
if (entries.length === 0) return '';
|
|
476
|
+
const lines: string[] = [title];
|
|
477
|
+
const GAP = 2;
|
|
430
478
|
|
|
431
|
-
// Compute max left width
|
|
432
479
|
let maxLeft = 0;
|
|
433
480
|
for (const entry of entries) {
|
|
434
481
|
const indented = ` ${entry.left}`;
|
|
@@ -442,7 +489,7 @@ function formatFlagsSection(
|
|
|
442
489
|
lines.push(left);
|
|
443
490
|
} else {
|
|
444
491
|
const padded = padEnd(left, descCol);
|
|
445
|
-
const wrapped = wrapText(entry.description,
|
|
492
|
+
const wrapped = wrapText(entry.description, width, descCol);
|
|
446
493
|
lines.push(`${padded}${wrapped}`);
|
|
447
494
|
}
|
|
448
495
|
}
|
|
@@ -512,5 +559,5 @@ function formatExamplesSection(examples: readonly CommandExample[]): string {
|
|
|
512
559
|
// --- Exports
|
|
513
560
|
|
|
514
561
|
export { osc8, visibleWidth } from './ansi.ts';
|
|
515
|
-
export type { HelpOptions };
|
|
516
|
-
export { formatHelp, formatHelpSections };
|
|
562
|
+
export type { FlagEntry, HelpOptions };
|
|
563
|
+
export { formatFlagEntriesBlock, formatHelp, formatHelpSections };
|
|
@@ -579,9 +579,17 @@ function flagToJsonSchemaType(schema: FlagSchema): Record<string, unknown> {
|
|
|
579
579
|
case 'string':
|
|
580
580
|
result.type = 'string';
|
|
581
581
|
break;
|
|
582
|
-
case 'number':
|
|
583
|
-
|
|
582
|
+
case 'number': {
|
|
583
|
+
const constraints = schema.numberConstraints;
|
|
584
|
+
result.type = constraints?.int === true ? 'integer' : 'number';
|
|
585
|
+
if (constraints?.min !== undefined) {
|
|
586
|
+
result.minimum = constraints.min;
|
|
587
|
+
}
|
|
588
|
+
if (constraints?.max !== undefined) {
|
|
589
|
+
result.maximum = constraints.max;
|
|
590
|
+
}
|
|
584
591
|
break;
|
|
592
|
+
}
|
|
585
593
|
case 'boolean':
|
|
586
594
|
result.type = 'boolean';
|
|
587
595
|
break;
|
|
@@ -641,8 +649,19 @@ function argKindToType(schema: ArgSchema): Record<string, unknown> {
|
|
|
641
649
|
switch (schema.kind) {
|
|
642
650
|
case 'string':
|
|
643
651
|
return { type: 'string' };
|
|
644
|
-
case 'number':
|
|
645
|
-
|
|
652
|
+
case 'number': {
|
|
653
|
+
const constraints = schema.numberConstraints;
|
|
654
|
+
const result: Record<string, unknown> = {
|
|
655
|
+
type: constraints?.int === true ? 'integer' : 'number',
|
|
656
|
+
};
|
|
657
|
+
if (constraints?.min !== undefined) {
|
|
658
|
+
result.minimum = constraints.min;
|
|
659
|
+
}
|
|
660
|
+
if (constraints?.max !== undefined) {
|
|
661
|
+
result.maximum = constraints.max;
|
|
662
|
+
}
|
|
663
|
+
return result;
|
|
664
|
+
}
|
|
646
665
|
case 'enum': {
|
|
647
666
|
const result: Record<string, unknown> = { type: 'string' };
|
|
648
667
|
if (schema.enumValues !== undefined) {
|