@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
|
@@ -9,9 +9,9 @@
|
|
|
9
9
|
* @module dreamcli/core/errors
|
|
10
10
|
*/
|
|
11
11
|
/** Codes emitted during argv parsing. */
|
|
12
|
-
type ParseErrorCode =
|
|
12
|
+
type ParseErrorCode = "UNKNOWN_FLAG" | "UNKNOWN_COMMAND" | "MISSING_VALUE" | "INVALID_VALUE" | "INVALID_SCHEMA" | "DUPLICATE_FLAG" | "UNEXPECTED_POSITIONAL";
|
|
13
13
|
/** Codes emitted during post-parse validation / resolution. */
|
|
14
|
-
type ValidationErrorCode =
|
|
14
|
+
type ValidationErrorCode = "REQUIRED_FLAG" | "REQUIRED_ARG" | "MISSING_STDIN" | "INVALID_ENUM" | "TYPE_MISMATCH" | "CONSTRAINT_VIOLATED";
|
|
15
15
|
/** Any framework error code (extensible via `string & {}`). */
|
|
16
16
|
type ErrorCode = ParseErrorCode | ValidationErrorCode | (string & {});
|
|
17
17
|
/** Options accepted by the `CLIError` constructor. */
|
|
@@ -38,7 +38,7 @@ interface CLIErrorOptions {
|
|
|
38
38
|
*/
|
|
39
39
|
declare class CLIError extends Error {
|
|
40
40
|
/** Error class name, always `'CLIError'` for the base class. @override */
|
|
41
|
-
readonly name: string;
|
|
41
|
+
override readonly name: string;
|
|
42
42
|
/** Stable machine-readable identifier. */
|
|
43
43
|
readonly code: ErrorCode;
|
|
44
44
|
/** Process exit code (defaults to `1`). */
|
|
@@ -71,7 +71,7 @@ interface CLIErrorJSON {
|
|
|
71
71
|
readonly details?: Readonly<Record<string, unknown>>;
|
|
72
72
|
}
|
|
73
73
|
/** Options for {@linkcode ParseError}. Code is narrowed to parse-specific codes. */
|
|
74
|
-
interface ParseErrorOptions extends Omit<CLIErrorOptions,
|
|
74
|
+
interface ParseErrorOptions extends Omit<CLIErrorOptions, "code" | "exitCode"> {
|
|
75
75
|
/** Parse-category error code (e.g. `'UNKNOWN_FLAG'`, `'MISSING_VALUE'`). */
|
|
76
76
|
readonly code: ParseErrorCode;
|
|
77
77
|
/**
|
|
@@ -87,14 +87,14 @@ interface ParseErrorOptions extends Omit<CLIErrorOptions, 'code' | 'exitCode'> {
|
|
|
87
87
|
*/
|
|
88
88
|
declare class ParseError extends CLIError {
|
|
89
89
|
/** Always `'ParseError'`. @override */
|
|
90
|
-
readonly name: "ParseError";
|
|
90
|
+
override readonly name: "ParseError";
|
|
91
91
|
/** Narrowed to parse-category codes. */
|
|
92
92
|
readonly code: ParseErrorCode;
|
|
93
93
|
/** Create a parse error with exit code defaulting to `2`. */
|
|
94
94
|
constructor(message: string, options: ParseErrorOptions);
|
|
95
95
|
}
|
|
96
96
|
/** Options for {@linkcode ValidationError}. Code is narrowed to validation-specific codes. */
|
|
97
|
-
interface ValidationErrorOptions extends Omit<CLIErrorOptions,
|
|
97
|
+
interface ValidationErrorOptions extends Omit<CLIErrorOptions, "code" | "exitCode"> {
|
|
98
98
|
/** Validation-category error code (e.g. `'REQUIRED_FLAG'`, `'INVALID_ENUM'`). */
|
|
99
99
|
readonly code: ValidationErrorCode;
|
|
100
100
|
/**
|
|
@@ -110,7 +110,7 @@ interface ValidationErrorOptions extends Omit<CLIErrorOptions, 'code' | 'exitCod
|
|
|
110
110
|
*/
|
|
111
111
|
declare class ValidationError extends CLIError {
|
|
112
112
|
/** Always `'ValidationError'`. @override */
|
|
113
|
-
readonly name: "ValidationError";
|
|
113
|
+
override readonly name: "ValidationError";
|
|
114
114
|
/** Narrowed to validation-category codes. */
|
|
115
115
|
readonly code: ValidationErrorCode;
|
|
116
116
|
/** Create a validation error with exit code defaulting to `2`. */
|
|
@@ -1,48 +1 @@
|
|
|
1
|
-
|
|
2
|
-
import { CLIError } from "../errors/index.mjs";
|
|
3
|
-
import { RunOptions, RunResult } from "../schema/run.mjs";
|
|
4
|
-
import { CommandMeta, CommandSchema, Out, RunnableCommand } from "../schema/command.mjs";
|
|
5
|
-
//#region src/core/execution/index.d.ts
|
|
6
|
-
/**
|
|
7
|
-
* Explicit executor input for a single command invocation.
|
|
8
|
-
* @internal
|
|
9
|
-
*/
|
|
10
|
-
interface CommandExecutionRequest {
|
|
11
|
-
/** The command instance whose handler will be invoked. */
|
|
12
|
-
readonly command: RunnableCommand;
|
|
13
|
-
/** Raw argument tokens to parse (excluding the program name). */
|
|
14
|
-
readonly argv: readonly string[];
|
|
15
|
-
/** Output channel for handler and error rendering. */
|
|
16
|
-
readonly out: Out;
|
|
17
|
-
/** Frozen schema definition (flags, args, metadata) for parsing and resolution. */
|
|
18
|
-
readonly schema: CommandSchema;
|
|
19
|
-
/** Runtime metadata (binary name, version) propagated to the handler. */
|
|
20
|
-
readonly meta: CommandMeta;
|
|
21
|
-
/** Optional overrides for env, config, prompter, plugins, and JSON mode. */
|
|
22
|
-
readonly options?: RunOptions;
|
|
23
|
-
}
|
|
24
|
-
/**
|
|
25
|
-
* Minimal executor result before output buffers are assembled into `RunResult`.
|
|
26
|
-
* @internal
|
|
27
|
-
*/
|
|
28
|
-
interface CommandExecutionResult {
|
|
29
|
-
/** Process exit code (`0` on success, error-specific otherwise). */
|
|
30
|
-
readonly exitCode: number;
|
|
31
|
-
/** The structured error if the command failed, `undefined` on success. */
|
|
32
|
-
readonly error: CLIError | undefined;
|
|
33
|
-
}
|
|
34
|
-
/**
|
|
35
|
-
* Run the full parse -> resolve -> plugin -> handler pipeline for one command.
|
|
36
|
-
*
|
|
37
|
-
* Handles `--help` short-circuit, plugin lifecycle hooks, deprecation warnings,
|
|
38
|
-
* and error wrapping. Both CLI dispatch and testkit `runCommand` converge here.
|
|
39
|
-
* @internal
|
|
40
|
-
*/
|
|
41
|
-
declare function executeCommand(request: CommandExecutionRequest): Promise<CommandExecutionResult>;
|
|
42
|
-
/**
|
|
43
|
-
* Assemble a {@linkcode CommandExecutionResult} and captured output buffers into a public `RunResult`.
|
|
44
|
-
* @internal
|
|
45
|
-
*/
|
|
46
|
-
declare function buildRunResult(result: CommandExecutionResult, captured: CapturedOutput): RunResult;
|
|
47
|
-
//#endregion
|
|
48
|
-
export { type CommandExecutionRequest, type CommandExecutionResult, buildRunResult, executeCommand };
|
|
1
|
+
export {}
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { CLIError } from "../errors/index.mjs";
|
|
2
|
-
import {
|
|
2
|
+
import { parse, requestsHelp } from "../parse/index.mjs";
|
|
3
|
+
import { builtinEnabled } from "../cli/builtins.mjs";
|
|
3
4
|
import { formatHelp } from "../help/index.mjs";
|
|
4
5
|
import { generateCommandSchema } from "../json-schema/index.mjs";
|
|
5
6
|
import { clearRequestedExitCode, getRequestedExitCode } from "../output/index.mjs";
|
|
@@ -7,6 +8,15 @@ import { createTestPrompter } from "../prompt/index.mjs";
|
|
|
7
8
|
import { resolve } from "../resolve/index.mjs";
|
|
8
9
|
//#region src/core/execution/index.ts
|
|
9
10
|
/**
|
|
11
|
+
* Shared command execution seam.
|
|
12
|
+
*
|
|
13
|
+
* Centralizes the parse -> resolve -> plugin -> handler pipeline so CLI and
|
|
14
|
+
* testkit can converge on one owned execution path during the re-foundation.
|
|
15
|
+
*
|
|
16
|
+
* @module dreamcli/core/execution
|
|
17
|
+
* @internal
|
|
18
|
+
*/
|
|
19
|
+
/**
|
|
10
20
|
* Run the full parse -> resolve -> plugin -> handler pipeline for one command.
|
|
11
21
|
*
|
|
12
22
|
* Handles `--help` short-circuit, plugin lifecycle hooks, deprecation warnings,
|
|
@@ -17,7 +27,7 @@ async function executeCommand(request) {
|
|
|
17
27
|
const { argv, command, meta, options, out, schema } = request;
|
|
18
28
|
clearRequestedExitCode(out);
|
|
19
29
|
try {
|
|
20
|
-
if (
|
|
30
|
+
if (builtinEnabled(options?.builtins, "help") && requestsHelp(argv)) {
|
|
21
31
|
if (out.jsonMode || options?.jsonMode === true) {
|
|
22
32
|
out.json(generateCommandSchema(schema, void 0, {
|
|
23
33
|
name: options?.help?.binName ?? schema.name,
|
|
@@ -40,9 +50,9 @@ async function executeCommand(request) {
|
|
|
40
50
|
}
|
|
41
51
|
const handler = command.handler;
|
|
42
52
|
if (handler === void 0) {
|
|
43
|
-
const error = new CLIError(`Command '${
|
|
53
|
+
const error = new CLIError(`Command '${schema.name}' has no action handler`, {
|
|
44
54
|
code: "NO_ACTION",
|
|
45
|
-
suggest: `Add an .action() handler to the '${
|
|
55
|
+
suggest: `Add an .action() handler to the '${schema.name}' command`
|
|
46
56
|
});
|
|
47
57
|
out.error(error.message);
|
|
48
58
|
return {
|
|
@@ -58,14 +68,15 @@ async function executeCommand(request) {
|
|
|
58
68
|
});
|
|
59
69
|
const parsed = parse(schema, argv, options?.flags);
|
|
60
70
|
const effectivePrompter = options?.prompter ?? (options?.answers !== void 0 ? createTestPrompter(options.answers) : void 0);
|
|
61
|
-
const
|
|
71
|
+
const resolveOptions = {
|
|
62
72
|
...options?.stdinData !== void 0 ? { stdinData: options.stdinData } : {},
|
|
63
73
|
...options?.env !== void 0 ? { env: options.env } : {},
|
|
64
74
|
...options?.config !== void 0 ? { config: options.config } : {},
|
|
65
75
|
...effectivePrompter !== void 0 ? { prompter: effectivePrompter } : {},
|
|
66
76
|
...options?.stat !== void 0 ? { stat: options.stat } : {},
|
|
67
77
|
...options?.mkdir !== void 0 ? { mkdir: options.mkdir } : {}
|
|
68
|
-
}
|
|
78
|
+
};
|
|
79
|
+
const resolved = await resolve(schema, parsed, resolveOptions);
|
|
69
80
|
const resolvedParams = {
|
|
70
81
|
args: resolved.args,
|
|
71
82
|
flags: resolved.flags,
|
|
@@ -77,7 +88,7 @@ async function executeCommand(request) {
|
|
|
77
88
|
await runResolvedHooks(options?.plugins, "afterResolve", resolvedParams);
|
|
78
89
|
for (const deprecation of resolved.deprecations) out.warn(formatDeprecation(deprecation));
|
|
79
90
|
await runResolvedHooks(options?.plugins, "beforeAction", resolvedParams);
|
|
80
|
-
await executeWithExecutionSteps(command, handler, resolved
|
|
91
|
+
await executeWithExecutionSteps(command, handler, resolved, out, meta);
|
|
81
92
|
await runResolvedHooks(options?.plugins, "afterAction", resolvedParams);
|
|
82
93
|
return {
|
|
83
94
|
exitCode: getRequestedExitCode(out) ?? 0,
|
|
@@ -95,7 +106,8 @@ async function executeCommand(request) {
|
|
|
95
106
|
error
|
|
96
107
|
};
|
|
97
108
|
}
|
|
98
|
-
const
|
|
109
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
110
|
+
const wrapped = new CLIError(`Unexpected error: ${message}`, {
|
|
99
111
|
code: "UNEXPECTED_ERROR",
|
|
100
112
|
cause: error
|
|
101
113
|
});
|
|
@@ -124,12 +136,15 @@ async function runResolvedHooks(plugins, hookName, params) {
|
|
|
124
136
|
if (hook !== void 0) await hook(params);
|
|
125
137
|
}
|
|
126
138
|
}
|
|
127
|
-
async function executeWithExecutionSteps(command, handler,
|
|
128
|
-
const steps = command.
|
|
139
|
+
async function executeWithExecutionSteps(command, handler, resolved, out, meta) {
|
|
140
|
+
const steps = command.steps;
|
|
141
|
+
const { args, flags } = resolved;
|
|
142
|
+
const sources = resolved.provenance;
|
|
129
143
|
let chain = async (ctx) => {
|
|
130
144
|
await handler({
|
|
131
145
|
flags,
|
|
132
146
|
args,
|
|
147
|
+
sources,
|
|
133
148
|
ctx,
|
|
134
149
|
out,
|
|
135
150
|
meta
|
|
@@ -145,6 +160,7 @@ async function executeWithExecutionSteps(command, handler, flags, args, out, met
|
|
|
145
160
|
const additions = await step.handler({
|
|
146
161
|
args,
|
|
147
162
|
flags,
|
|
163
|
+
sources,
|
|
148
164
|
ctx,
|
|
149
165
|
out,
|
|
150
166
|
meta
|
|
@@ -163,23 +179,22 @@ async function executeWithExecutionSteps(command, handler, flags, args, out, met
|
|
|
163
179
|
});
|
|
164
180
|
};
|
|
165
181
|
break;
|
|
166
|
-
case "middleware":
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
break;
|
|
182
|
+
case "middleware": chain = async (ctx) => {
|
|
183
|
+
await step.handler({
|
|
184
|
+
args,
|
|
185
|
+
flags,
|
|
186
|
+
sources,
|
|
187
|
+
ctx,
|
|
188
|
+
out,
|
|
189
|
+
meta,
|
|
190
|
+
next: async (additions) => {
|
|
191
|
+
await downstream({
|
|
192
|
+
...ctx,
|
|
193
|
+
...additions
|
|
194
|
+
});
|
|
195
|
+
}
|
|
196
|
+
});
|
|
197
|
+
};
|
|
183
198
|
}
|
|
184
199
|
}
|
|
185
200
|
await chain({});
|
|
@@ -1,15 +1,4 @@
|
|
|
1
1
|
//#region src/core/help/ansi.d.ts
|
|
2
|
-
/**
|
|
3
|
-
* ANSI/OSC-aware text helpers for help formatting.
|
|
4
|
-
*
|
|
5
|
-
* Terminal escape sequences (SGR colors, OSC 8 hyperlinks) occupy zero
|
|
6
|
-
* columns when rendered, so width math must measure the *visible* text.
|
|
7
|
-
* {@linkcode visibleWidth} strips escapes before counting, and the shared
|
|
8
|
-
* {@linkcode padEnd}/{@linkcode wrapText} helpers build on it so aligned
|
|
9
|
-
* tables and wrapped lines stay intact when escapes are present.
|
|
10
|
-
*
|
|
11
|
-
* @module dreamcli/core/help/ansi
|
|
12
|
-
*/
|
|
13
2
|
/**
|
|
14
3
|
* Remove ANSI CSI and OSC escape sequences from `text`.
|
|
15
4
|
*
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
+
import { CommandSchema } from "../schema/command.mjs";
|
|
1
2
|
import { HelpTheme, HelpThemeFactory } from "./theme.mjs";
|
|
2
3
|
import { osc8, visibleWidth } from "./ansi.mjs";
|
|
3
|
-
import { CommandSchema } from "../schema/command.mjs";
|
|
4
4
|
import "../schema/index.mjs";
|
|
5
5
|
import { Colors } from "ansispeck";
|
|
6
6
|
//#region src/core/help/index.d.ts
|
|
@@ -22,7 +22,7 @@ interface HelpOptions {
|
|
|
22
22
|
*
|
|
23
23
|
* @defaultValue `'alphabetical'`
|
|
24
24
|
*/
|
|
25
|
-
readonly flagOrder?:
|
|
25
|
+
readonly flagOrder?: "alphabetical" | "declaration";
|
|
26
26
|
/**
|
|
27
27
|
* Custom comparator over flag long names for the `Flags:` table. When set,
|
|
28
28
|
* it wins over {@link HelpOptions.flagOrder}.
|
|
@@ -62,8 +62,6 @@ interface HelpOptions {
|
|
|
62
62
|
* explicitly to force it on or off.
|
|
63
63
|
*/
|
|
64
64
|
readonly footer?: boolean;
|
|
65
|
-
/** @internal Whether this usage line is being rendered as merged root/default help. */
|
|
66
|
-
readonly isDefaultHelp?: boolean;
|
|
67
65
|
/**
|
|
68
66
|
* Gated ANSI palette used to style help output. Identity formatters mean
|
|
69
67
|
* plain text. `CLIBuilder.execute()`/`.run()` thread the output channel's
|
|
@@ -82,22 +80,6 @@ interface HelpOptions {
|
|
|
82
80
|
*/
|
|
83
81
|
readonly theme?: HelpThemeFactory;
|
|
84
82
|
}
|
|
85
|
-
/** Formatted flag entry for the flags table. @internal */
|
|
86
|
-
interface FlagEntry {
|
|
87
|
-
/** Preformatted flag names and value hint for the left table column. */
|
|
88
|
-
readonly left: string;
|
|
89
|
-
/** Preformatted help text for the description table column. */
|
|
90
|
-
readonly description: string;
|
|
91
|
-
}
|
|
92
|
-
/**
|
|
93
|
-
* Build the ordered help sections without joining them.
|
|
94
|
-
*
|
|
95
|
-
* @internal
|
|
96
|
-
* @param schema - The {@link CommandSchema} to render.
|
|
97
|
-
* @param options - Optional {@link HelpOptions} for width/bin name.
|
|
98
|
-
* @returns Array of section strings (usage, description, commands, args, flags, examples).
|
|
99
|
-
*/
|
|
100
|
-
declare function formatHelpSections(schema: CommandSchema, options?: HelpOptions): readonly string[];
|
|
101
83
|
/**
|
|
102
84
|
* Generate help text from a command schema.
|
|
103
85
|
*
|
|
@@ -124,19 +106,5 @@ declare function formatHelpSections(schema: CommandSchema, options?: HelpOptions
|
|
|
124
106
|
* ```
|
|
125
107
|
*/
|
|
126
108
|
declare function formatHelp(schema: CommandSchema, options?: HelpOptions): string;
|
|
127
|
-
/**
|
|
128
|
-
* Render a titled two-column flag block from pre-built {@link FlagEntry} rows.
|
|
129
|
-
*
|
|
130
|
-
* Shared by the per-command `Flags:` section and the root-help `Global options:`
|
|
131
|
-
* block (built-in flags), so column alignment and description wrapping stay
|
|
132
|
-
* identical across both. Returns `''` when there are no entries.
|
|
133
|
-
*
|
|
134
|
-
* @param title - Section heading (e.g. `'Flags:'`, `'Global options:'`), pre-styled by the caller.
|
|
135
|
-
* @param entries - Formatted left/description rows.
|
|
136
|
-
* @param width - Terminal width for description wrapping.
|
|
137
|
-
* @returns Multi-line block string, or `''` when `entries` is empty.
|
|
138
|
-
* @internal
|
|
139
|
-
*/
|
|
140
|
-
declare function formatFlagEntriesBlock(title: string, entries: readonly FlagEntry[], width: number): string;
|
|
141
109
|
//#endregion
|
|
142
|
-
export { type
|
|
110
|
+
export { type HelpOptions, type HelpTheme, type HelpThemeFactory, formatHelp, osc8, visibleWidth };
|
package/dist/core/help/index.mjs
CHANGED
|
@@ -82,7 +82,25 @@ function formatValueHint(schema) {
|
|
|
82
82
|
}
|
|
83
83
|
}
|
|
84
84
|
/**
|
|
85
|
-
*
|
|
85
|
+
* Name what selects the stdin stream for an input, in the `[env: X]` style.
|
|
86
|
+
*
|
|
87
|
+
* `[stdin]` covers the default trigger, where both an explicit `-` and an
|
|
88
|
+
* absent input read the stream. The narrower triggers say which one applies, so
|
|
89
|
+
* a reader knows whether typing `-` is required.
|
|
90
|
+
*
|
|
91
|
+
* @param stdin - The input's stdin axis.
|
|
92
|
+
* @returns The annotation to render beside the description.
|
|
93
|
+
*/
|
|
94
|
+
function formatStdinAnnotation(stdin) {
|
|
95
|
+
switch (stdin.when) {
|
|
96
|
+
case "dash": return "[stdin: '-']";
|
|
97
|
+
case "missing": return "[stdin: when omitted]";
|
|
98
|
+
case "dash-or-missing": return "[stdin]";
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
/**
|
|
102
|
+
* Build description with stdin/env/config/prompt/default/required/deprecated
|
|
103
|
+
* annotations.
|
|
86
104
|
*
|
|
87
105
|
* @param schema - The {@link FlagSchema} to describe.
|
|
88
106
|
* @param theme - Theme applied to the metadata annotations (description stays plain).
|
|
@@ -92,11 +110,12 @@ function formatFlagDescription(schema, theme) {
|
|
|
92
110
|
const parts = [];
|
|
93
111
|
if (schema.description !== void 0) parts.push(schema.description);
|
|
94
112
|
if (schema.deprecated !== void 0) parts.push(theme.deprecated(formatDeprecated(schema.deprecated)));
|
|
113
|
+
if (schema.stdin !== void 0) parts.push(theme.annotation(formatStdinAnnotation(schema.stdin)));
|
|
95
114
|
if (schema.envVar !== void 0) parts.push(theme.annotation(`[env: ${schema.envVar}]`));
|
|
96
115
|
if (schema.configPath !== void 0) parts.push(theme.annotation(`[config: ${schema.configPath}]`));
|
|
97
116
|
if (schema.prompt !== void 0) parts.push(theme.annotation("[prompt]"));
|
|
98
|
-
if (schema.presence === "required") parts.push(theme.annotation("[required]"));
|
|
99
|
-
else if (schema.presence === "defaulted" && schema.kind !== "boolean" && schema.kind !== "count") parts.push(theme.defaultValue(`(default: ${formatHelpDefaultValue(schema.defaultValue)})`));
|
|
117
|
+
if (schema.presence === "required" && schema.defaultValue === void 0) parts.push(theme.annotation("[required]"));
|
|
118
|
+
else if ((schema.presence === "defaulted" || schema.defaultValue !== void 0) && schema.kind !== "boolean" && schema.kind !== "count") parts.push(theme.defaultValue(`(default: ${formatHelpDefaultValue(schema.defaultValue)})`));
|
|
100
119
|
return parts.join(" ");
|
|
101
120
|
}
|
|
102
121
|
/**
|
|
@@ -153,11 +172,12 @@ function formatArgUsage(entry) {
|
|
|
153
172
|
const { name, schema } = entry;
|
|
154
173
|
const label = schema.kind === "enum" && schema.enumValues !== void 0 ? schema.enumValues.join("|") : name;
|
|
155
174
|
const variadicSuffix = schema.variadic ? "..." : "";
|
|
156
|
-
if (schema.presence === "required") return `<${label}>${variadicSuffix}`;
|
|
175
|
+
if (schema.presence === "required" && schema.defaultValue === void 0) return `<${label}>${variadicSuffix}`;
|
|
157
176
|
return `[${label}]${variadicSuffix}`;
|
|
158
177
|
}
|
|
159
178
|
/**
|
|
160
|
-
* Format arg description with
|
|
179
|
+
* Format arg description with stdin/env/config/prompt/default/deprecated
|
|
180
|
+
* annotations.
|
|
161
181
|
*
|
|
162
182
|
* @param schema - The {@link ArgSchema} to describe.
|
|
163
183
|
* @param theme - Theme applied to the metadata annotations (description stays plain).
|
|
@@ -167,8 +187,11 @@ function formatArgDescription(schema, theme) {
|
|
|
167
187
|
const parts = [];
|
|
168
188
|
if (schema.description !== void 0) parts.push(schema.description);
|
|
169
189
|
if (schema.deprecated !== void 0) parts.push(theme.deprecated(formatDeprecated(schema.deprecated)));
|
|
190
|
+
if (schema.stdin !== void 0) parts.push(theme.annotation(formatStdinAnnotation(schema.stdin)));
|
|
170
191
|
if (schema.envVar !== void 0) parts.push(theme.annotation(`[env: ${schema.envVar}]`));
|
|
171
|
-
if (schema.
|
|
192
|
+
if (schema.configPath !== void 0) parts.push(theme.annotation(`[config: ${schema.configPath}]`));
|
|
193
|
+
if (schema.prompt !== void 0) parts.push(theme.annotation("[prompt]"));
|
|
194
|
+
if (schema.presence === "defaulted" || schema.defaultValue !== void 0) parts.push(theme.defaultValue(`(default: ${formatHelpDefaultValue(schema.defaultValue)})`));
|
|
172
195
|
return parts.join(" ");
|
|
173
196
|
}
|
|
174
197
|
/**
|
|
@@ -44,25 +44,5 @@ interface HelpTheme {
|
|
|
44
44
|
* unconditionally, gating is the framework's job.
|
|
45
45
|
*/
|
|
46
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
47
|
//#endregion
|
|
68
|
-
export {
|
|
48
|
+
export type { HelpTheme, HelpThemeFactory };
|