@kjanat/dreamcli 3.0.0-rc.1 → 3.0.0-rc.10
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 +217 -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
|
@@ -1 +1,201 @@
|
|
|
1
|
-
import
|
|
1
|
+
import { CLIError } from "../errors/index.mjs";
|
|
2
|
+
import { includesBeforeSeparator, parse } from "../parse/index.mjs";
|
|
3
|
+
import { formatHelp } from "../help/index.mjs";
|
|
4
|
+
import { generateCommandSchema } from "../json-schema/index.mjs";
|
|
5
|
+
import { clearRequestedExitCode, getRequestedExitCode } from "../output/index.mjs";
|
|
6
|
+
import { createTestPrompter } from "../prompt/index.mjs";
|
|
7
|
+
import { resolve } from "../resolve/index.mjs";
|
|
8
|
+
//#region src/core/execution/index.ts
|
|
9
|
+
/**
|
|
10
|
+
* Run the full parse -> resolve -> plugin -> handler pipeline for one command.
|
|
11
|
+
*
|
|
12
|
+
* Handles `--help` short-circuit, plugin lifecycle hooks, deprecation warnings,
|
|
13
|
+
* and error wrapping. Both CLI dispatch and testkit `runCommand` converge here.
|
|
14
|
+
* @internal
|
|
15
|
+
*/
|
|
16
|
+
async function executeCommand(request) {
|
|
17
|
+
const { argv, command, meta, options, out, schema } = request;
|
|
18
|
+
clearRequestedExitCode(out);
|
|
19
|
+
try {
|
|
20
|
+
if (includesBeforeSeparator(argv, "--help") || includesBeforeSeparator(argv, "-h")) {
|
|
21
|
+
if (out.jsonMode || options?.jsonMode === true) {
|
|
22
|
+
out.json(generateCommandSchema(schema));
|
|
23
|
+
return {
|
|
24
|
+
exitCode: 0,
|
|
25
|
+
error: void 0
|
|
26
|
+
};
|
|
27
|
+
}
|
|
28
|
+
const helpText = formatHelp(schema, options?.help?.colors !== void 0 ? options.help : {
|
|
29
|
+
...options?.help,
|
|
30
|
+
colors: out.color
|
|
31
|
+
});
|
|
32
|
+
out.log(helpText);
|
|
33
|
+
return {
|
|
34
|
+
exitCode: 0,
|
|
35
|
+
error: void 0
|
|
36
|
+
};
|
|
37
|
+
}
|
|
38
|
+
const handler = command.handler;
|
|
39
|
+
if (handler === void 0) {
|
|
40
|
+
const error = new CLIError(`Command '${command.schema.name}' has no action handler`, {
|
|
41
|
+
code: "NO_ACTION",
|
|
42
|
+
suggest: `Add an .action() handler to the '${command.schema.name}' command`
|
|
43
|
+
});
|
|
44
|
+
out.error(error.message);
|
|
45
|
+
return {
|
|
46
|
+
exitCode: 1,
|
|
47
|
+
error
|
|
48
|
+
};
|
|
49
|
+
}
|
|
50
|
+
await runBeforeParseHooks(options?.plugins, {
|
|
51
|
+
argv,
|
|
52
|
+
command: schema,
|
|
53
|
+
meta,
|
|
54
|
+
out
|
|
55
|
+
});
|
|
56
|
+
const parsed = parse(schema, argv, options?.flags);
|
|
57
|
+
const effectivePrompter = options?.prompter ?? (options?.answers !== void 0 ? createTestPrompter(options.answers) : void 0);
|
|
58
|
+
const resolved = await resolve(schema, parsed, {
|
|
59
|
+
...options?.stdinData !== void 0 ? { stdinData: options.stdinData } : {},
|
|
60
|
+
...options?.env !== void 0 ? { env: options.env } : {},
|
|
61
|
+
...options?.config !== void 0 ? { config: options.config } : {},
|
|
62
|
+
...effectivePrompter !== void 0 ? { prompter: effectivePrompter } : {},
|
|
63
|
+
...options?.stat !== void 0 ? { stat: options.stat } : {}
|
|
64
|
+
});
|
|
65
|
+
const resolvedParams = {
|
|
66
|
+
args: resolved.args,
|
|
67
|
+
flags: resolved.flags,
|
|
68
|
+
deprecations: resolved.deprecations,
|
|
69
|
+
command: schema,
|
|
70
|
+
meta,
|
|
71
|
+
out
|
|
72
|
+
};
|
|
73
|
+
await runResolvedHooks(options?.plugins, "afterResolve", resolvedParams);
|
|
74
|
+
for (const deprecation of resolved.deprecations) out.warn(formatDeprecation(deprecation));
|
|
75
|
+
await runResolvedHooks(options?.plugins, "beforeAction", resolvedParams);
|
|
76
|
+
await executeWithExecutionSteps(command, handler, resolved.flags, resolved.args, out, meta);
|
|
77
|
+
await runResolvedHooks(options?.plugins, "afterAction", resolvedParams);
|
|
78
|
+
return {
|
|
79
|
+
exitCode: getRequestedExitCode(out) ?? 0,
|
|
80
|
+
error: void 0
|
|
81
|
+
};
|
|
82
|
+
} catch (error) {
|
|
83
|
+
if (error instanceof CLIError) {
|
|
84
|
+
if (options?.jsonMode === true) out.json({ error: error.toJSON() });
|
|
85
|
+
else {
|
|
86
|
+
out.error(error.message);
|
|
87
|
+
if (error.suggest !== void 0) out.error(`Suggestion: ${error.suggest}`);
|
|
88
|
+
}
|
|
89
|
+
return {
|
|
90
|
+
exitCode: error.exitCode,
|
|
91
|
+
error
|
|
92
|
+
};
|
|
93
|
+
}
|
|
94
|
+
const wrapped = new CLIError(`Unexpected error: ${error instanceof Error ? error.message : String(error)}`, {
|
|
95
|
+
code: "UNEXPECTED_ERROR",
|
|
96
|
+
cause: error
|
|
97
|
+
});
|
|
98
|
+
if (options?.jsonMode === true) out.json({ error: wrapped.toJSON() });
|
|
99
|
+
else out.error(wrapped.message);
|
|
100
|
+
return {
|
|
101
|
+
exitCode: 1,
|
|
102
|
+
error: wrapped
|
|
103
|
+
};
|
|
104
|
+
} finally {
|
|
105
|
+
out.stopActive();
|
|
106
|
+
clearRequestedExitCode(out);
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
async function runBeforeParseHooks(plugins, params) {
|
|
110
|
+
if (plugins === void 0) return;
|
|
111
|
+
for (const current of plugins) {
|
|
112
|
+
const hook = current.hooks.beforeParse;
|
|
113
|
+
if (hook !== void 0) await hook(params);
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
async function runResolvedHooks(plugins, hookName, params) {
|
|
117
|
+
if (plugins === void 0) return;
|
|
118
|
+
for (const current of plugins) {
|
|
119
|
+
const hook = current.hooks[hookName];
|
|
120
|
+
if (hook !== void 0) await hook(params);
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
async function executeWithExecutionSteps(command, handler, flags, args, out, meta) {
|
|
124
|
+
const steps = command._executionSteps;
|
|
125
|
+
let chain = async (ctx) => {
|
|
126
|
+
await handler({
|
|
127
|
+
flags,
|
|
128
|
+
args,
|
|
129
|
+
ctx,
|
|
130
|
+
out,
|
|
131
|
+
meta
|
|
132
|
+
});
|
|
133
|
+
};
|
|
134
|
+
for (let i = steps.length - 1; i >= 0; i--) {
|
|
135
|
+
const step = steps[i];
|
|
136
|
+
if (step === void 0) continue;
|
|
137
|
+
const downstream = chain;
|
|
138
|
+
switch (step.kind) {
|
|
139
|
+
case "derive":
|
|
140
|
+
chain = async (ctx) => {
|
|
141
|
+
const additions = await step.handler({
|
|
142
|
+
args,
|
|
143
|
+
flags,
|
|
144
|
+
ctx,
|
|
145
|
+
out,
|
|
146
|
+
meta
|
|
147
|
+
});
|
|
148
|
+
if (additions === void 0) {
|
|
149
|
+
await downstream(ctx);
|
|
150
|
+
return;
|
|
151
|
+
}
|
|
152
|
+
if (typeof additions !== "object" || additions === null || Array.isArray(additions)) throw new CLIError("derive() must return an object or undefined", {
|
|
153
|
+
code: "INVALID_BUILDER_STATE",
|
|
154
|
+
suggest: "Return an object to add context, or return nothing for validation-only derive handlers"
|
|
155
|
+
});
|
|
156
|
+
await downstream({
|
|
157
|
+
...ctx,
|
|
158
|
+
...additions
|
|
159
|
+
});
|
|
160
|
+
};
|
|
161
|
+
break;
|
|
162
|
+
case "middleware":
|
|
163
|
+
chain = async (ctx) => {
|
|
164
|
+
await step.handler({
|
|
165
|
+
args,
|
|
166
|
+
flags,
|
|
167
|
+
ctx,
|
|
168
|
+
out,
|
|
169
|
+
meta,
|
|
170
|
+
next: async (additions) => {
|
|
171
|
+
await downstream({
|
|
172
|
+
...ctx,
|
|
173
|
+
...additions
|
|
174
|
+
});
|
|
175
|
+
}
|
|
176
|
+
});
|
|
177
|
+
};
|
|
178
|
+
break;
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
await chain({});
|
|
182
|
+
}
|
|
183
|
+
/**
|
|
184
|
+
* Assemble a {@linkcode CommandExecutionResult} and captured output buffers into a public `RunResult`.
|
|
185
|
+
* @internal
|
|
186
|
+
*/
|
|
187
|
+
function buildRunResult(result, captured) {
|
|
188
|
+
return {
|
|
189
|
+
exitCode: result.exitCode,
|
|
190
|
+
stdout: captured.stdout,
|
|
191
|
+
stderr: captured.stderr,
|
|
192
|
+
activity: captured.activity,
|
|
193
|
+
error: result.error
|
|
194
|
+
};
|
|
195
|
+
}
|
|
196
|
+
function formatDeprecation(deprecation) {
|
|
197
|
+
const entity = deprecation.kind === "flag" ? `flag --${deprecation.name}` : `argument <${deprecation.name}>`;
|
|
198
|
+
return typeof deprecation.message === "string" ? `Warning: ${entity} is deprecated: ${deprecation.message}` : `Warning: ${entity} is deprecated`;
|
|
199
|
+
}
|
|
200
|
+
//#endregion
|
|
201
|
+
export { buildRunResult, executeCommand };
|
|
@@ -13,6 +13,11 @@
|
|
|
13
13
|
/**
|
|
14
14
|
* Remove ANSI CSI and OSC escape sequences from `text`.
|
|
15
15
|
*
|
|
16
|
+
* Delegates to `ansispeck`'s stripper, which handles SGR sequences and OSC
|
|
17
|
+
* hyperlinks under both terminators. Kept as a named export so help
|
|
18
|
+
* formatting and custom help renderers reach the width-aware helpers and
|
|
19
|
+
* their stripper through one module.
|
|
20
|
+
*
|
|
16
21
|
* @param text - Text possibly containing terminal escapes.
|
|
17
22
|
* @returns The text with all escape sequences removed.
|
|
18
23
|
*/
|
|
@@ -39,10 +44,10 @@ declare function visibleWidth(text: string): number;
|
|
|
39
44
|
* Wrap `text` in an [OSC 8 hyperlink](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda)
|
|
40
45
|
* pointing at `url`.
|
|
41
46
|
*
|
|
42
|
-
* Supporting terminals render `text` as a clickable link;
|
|
43
|
-
*
|
|
44
|
-
*
|
|
45
|
-
*
|
|
47
|
+
* Supporting terminals render `text` as a clickable link; others show it
|
|
48
|
+
* plain. `text` defaults to the URL, so an omitted label degrades to a
|
|
49
|
+
* usable address. The framework's help layer decides *whether* to link
|
|
50
|
+
* (`help.hyperlinks`); this always emits when called.
|
|
46
51
|
*
|
|
47
52
|
* @param url - Link target (string or `URL` instance).
|
|
48
53
|
* @param text - Visible link text.
|
|
@@ -51,9 +56,10 @@ declare function visibleWidth(text: string): number;
|
|
|
51
56
|
* @example
|
|
52
57
|
* ```ts
|
|
53
58
|
* cli('mycli').version(osc8('https://github.com/me/mycli/releases/tag/v1.0.0', '1.0.0'));
|
|
59
|
+
* osc8('https://dreamcli.kjanat.dev'); // linked, displayed as the URL
|
|
54
60
|
* ```
|
|
55
61
|
*/
|
|
56
|
-
declare function osc8(url: string | URL, text
|
|
62
|
+
declare function osc8(url: string | URL, text?: string): string;
|
|
57
63
|
/**
|
|
58
64
|
* Pad `text` to `length` visible columns with trailing spaces.
|
|
59
65
|
*
|
package/dist/core/help/ansi.mjs
CHANGED
|
@@ -1,2 +1,121 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
import { createColors, strip } from "ansispeck";
|
|
2
|
+
//#region src/core/help/ansi.ts
|
|
3
|
+
/**
|
|
4
|
+
* ANSI/OSC-aware text helpers for help formatting.
|
|
5
|
+
*
|
|
6
|
+
* Terminal escape sequences (SGR colors, OSC 8 hyperlinks) occupy zero
|
|
7
|
+
* columns when rendered, so width math must measure the *visible* text.
|
|
8
|
+
* {@linkcode visibleWidth} strips escapes before counting, and the shared
|
|
9
|
+
* {@linkcode padEnd}/{@linkcode wrapText} helpers build on it so aligned
|
|
10
|
+
* tables and wrapped lines stay intact when escapes are present.
|
|
11
|
+
*
|
|
12
|
+
* @module dreamcli/core/help/ansi
|
|
13
|
+
*/
|
|
14
|
+
/**
|
|
15
|
+
* Remove ANSI CSI and OSC escape sequences from `text`.
|
|
16
|
+
*
|
|
17
|
+
* Delegates to `ansispeck`'s stripper, which handles SGR sequences and OSC
|
|
18
|
+
* hyperlinks under both terminators. Kept as a named export so help
|
|
19
|
+
* formatting and custom help renderers reach the width-aware helpers and
|
|
20
|
+
* their stripper through one module.
|
|
21
|
+
*
|
|
22
|
+
* @param text - Text possibly containing terminal escapes.
|
|
23
|
+
* @returns The text with all escape sequences removed.
|
|
24
|
+
*/
|
|
25
|
+
function stripAnsi(text) {
|
|
26
|
+
return strip(text);
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Measure the visible column width of `text`, ignoring ANSI/OSC escapes.
|
|
30
|
+
*
|
|
31
|
+
* Escape sequences (SGR colors, OSC 8 hyperlinks) occupy zero columns when
|
|
32
|
+
* rendered, so `.length` overcounts whenever they are present. Help
|
|
33
|
+
* formatting uses this for padding and wrapping; exported for custom help
|
|
34
|
+
* renderers that mix colors or links into aligned output.
|
|
35
|
+
*
|
|
36
|
+
* @param text - Text possibly containing terminal escapes.
|
|
37
|
+
* @returns Number of visible characters.
|
|
38
|
+
*
|
|
39
|
+
* @example
|
|
40
|
+
* ```ts
|
|
41
|
+
* visibleWidth('plain'); // 5
|
|
42
|
+
* visibleWidth(osc8('https://x.dev', 'x')); // 1
|
|
43
|
+
* ```
|
|
44
|
+
*/
|
|
45
|
+
function visibleWidth(text) {
|
|
46
|
+
return stripAnsi(text).length;
|
|
47
|
+
}
|
|
48
|
+
const emitLink = createColors(false, true).link;
|
|
49
|
+
/**
|
|
50
|
+
* Wrap `text` in an [OSC 8 hyperlink](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda)
|
|
51
|
+
* pointing at `url`.
|
|
52
|
+
*
|
|
53
|
+
* Supporting terminals render `text` as a clickable link; others show it
|
|
54
|
+
* plain. `text` defaults to the URL, so an omitted label degrades to a
|
|
55
|
+
* usable address. The framework's help layer decides *whether* to link
|
|
56
|
+
* (`help.hyperlinks`); this always emits when called.
|
|
57
|
+
*
|
|
58
|
+
* @param url - Link target (string or `URL` instance).
|
|
59
|
+
* @param text - Visible link text.
|
|
60
|
+
* @returns The OSC 8 escape sequence wrapping `text`.
|
|
61
|
+
*
|
|
62
|
+
* @example
|
|
63
|
+
* ```ts
|
|
64
|
+
* cli('mycli').version(osc8('https://github.com/me/mycli/releases/tag/v1.0.0', '1.0.0'));
|
|
65
|
+
* osc8('https://dreamcli.kjanat.dev'); // linked, displayed as the URL
|
|
66
|
+
* ```
|
|
67
|
+
*/
|
|
68
|
+
function osc8(url, text) {
|
|
69
|
+
return emitLink(url, text);
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* Pad `text` to `length` visible columns with trailing spaces.
|
|
73
|
+
*
|
|
74
|
+
* @param text - The string to pad (may contain ANSI/OSC escapes).
|
|
75
|
+
* @param length - Target visible width in columns.
|
|
76
|
+
* @returns The padded string, unchanged if already at or beyond `length`.
|
|
77
|
+
*/
|
|
78
|
+
function padEnd(text, length) {
|
|
79
|
+
const visible = visibleWidth(text);
|
|
80
|
+
if (visible >= length) return text;
|
|
81
|
+
return text + " ".repeat(length - visible);
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Wrap text to `width`, preserving leading indent on continuation lines.
|
|
85
|
+
*
|
|
86
|
+
* Line lengths are measured with {@linkcode visibleWidth}, so embedded
|
|
87
|
+
* ANSI/OSC escapes do not trigger premature wrapping.
|
|
88
|
+
*
|
|
89
|
+
* @param text - The text to wrap.
|
|
90
|
+
* @param width - Maximum line width in columns.
|
|
91
|
+
* @param indent - Number of leading spaces for continuation lines.
|
|
92
|
+
* @returns The wrapped string with newlines inserted as needed.
|
|
93
|
+
*/
|
|
94
|
+
function wrapText(text, width, indent) {
|
|
95
|
+
if (visibleWidth(text) + indent <= width) return text;
|
|
96
|
+
const maxLen = width - indent;
|
|
97
|
+
if (maxLen <= 0) return text;
|
|
98
|
+
const words = text.split(" ");
|
|
99
|
+
const lines = [];
|
|
100
|
+
let current = "";
|
|
101
|
+
let currentWidth = 0;
|
|
102
|
+
for (const word of words) {
|
|
103
|
+
const wordWidth = visibleWidth(word);
|
|
104
|
+
if (current.length === 0) {
|
|
105
|
+
current = word;
|
|
106
|
+
currentWidth = wordWidth;
|
|
107
|
+
} else if (currentWidth + 1 + wordWidth <= maxLen) {
|
|
108
|
+
current += ` ${word}`;
|
|
109
|
+
currentWidth += 1 + wordWidth;
|
|
110
|
+
} else {
|
|
111
|
+
lines.push(current);
|
|
112
|
+
current = word;
|
|
113
|
+
currentWidth = wordWidth;
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
if (current.length > 0) lines.push(current);
|
|
117
|
+
const pad = " ".repeat(indent);
|
|
118
|
+
return lines.map((line, i) => i === 0 ? line : `${pad}${line}`).join("\n");
|
|
119
|
+
}
|
|
120
|
+
//#endregion
|
|
121
|
+
export { osc8, padEnd, stripAnsi, visibleWidth, wrapText };
|
|
@@ -1,6 +1,8 @@
|
|
|
1
|
+
import { HelpTheme, HelpThemeFactory } from "./theme.mjs";
|
|
1
2
|
import { osc8, visibleWidth } from "./ansi.mjs";
|
|
2
3
|
import { CommandSchema } from "../schema/command.mjs";
|
|
3
|
-
|
|
4
|
+
import "../schema/index.mjs";
|
|
5
|
+
import { Colors } from "ansispeck";
|
|
4
6
|
//#region src/core/help/index.d.ts
|
|
5
7
|
/** Options for customising help output. */
|
|
6
8
|
interface HelpOptions {
|
|
@@ -42,6 +44,23 @@ interface HelpOptions {
|
|
|
42
44
|
readonly footer?: boolean;
|
|
43
45
|
/** @internal Whether this usage line is being rendered as merged root/default help. */
|
|
44
46
|
readonly isDefaultHelp?: boolean;
|
|
47
|
+
/**
|
|
48
|
+
* Gated ANSI palette used to style help output. Identity formatters mean
|
|
49
|
+
* plain text. `CLIBuilder.execute()`/`.run()` thread the output channel's
|
|
50
|
+
* `out.color` here automatically, so styling follows the same policy as
|
|
51
|
+
* handler output (TTY + color support, no `--json`, `NO_COLOR` honored).
|
|
52
|
+
*
|
|
53
|
+
* @defaultValue `undefined` (plain text)
|
|
54
|
+
*/
|
|
55
|
+
readonly colors?: Colors;
|
|
56
|
+
/**
|
|
57
|
+
* Theme overrides merged over the built-in help theme. Receives the gated
|
|
58
|
+
* palette; never invoked when color is off, so overrides cannot leak
|
|
59
|
+
* escapes into piped output.
|
|
60
|
+
*
|
|
61
|
+
* @defaultValue `undefined` (built-in theme)
|
|
62
|
+
*/
|
|
63
|
+
readonly theme?: HelpThemeFactory;
|
|
45
64
|
}
|
|
46
65
|
/** Formatted flag entry for the flags table. @internal */
|
|
47
66
|
interface FlagEntry {
|
|
@@ -90,7 +109,7 @@ declare function formatHelp(schema: CommandSchema, options?: HelpOptions): strin
|
|
|
90
109
|
* block (built-in flags), so column alignment and description wrapping stay
|
|
91
110
|
* identical across both. Returns `''` when there are no entries.
|
|
92
111
|
*
|
|
93
|
-
* @param title - Section heading (e.g. `'Flags:'`, `'Global options:'`).
|
|
112
|
+
* @param title - Section heading (e.g. `'Flags:'`, `'Global options:'`), pre-styled by the caller.
|
|
94
113
|
* @param entries - Formatted left/description rows.
|
|
95
114
|
* @param width - Terminal width for description wrapping.
|
|
96
115
|
* @returns Multi-line block string, or `''` when `entries` is empty.
|
|
@@ -98,4 +117,4 @@ declare function formatHelp(schema: CommandSchema, options?: HelpOptions): strin
|
|
|
98
117
|
*/
|
|
99
118
|
declare function formatFlagEntriesBlock(title: string, entries: readonly FlagEntry[], width: number): string;
|
|
100
119
|
//#endregion
|
|
101
|
-
export { type FlagEntry, type HelpOptions, formatFlagEntriesBlock, formatHelp, formatHelpSections, osc8, visibleWidth };
|
|
120
|
+
export { type FlagEntry, type HelpOptions, type HelpTheme, type HelpThemeFactory, formatFlagEntriesBlock, formatHelp, formatHelpSections, osc8, visibleWidth };
|