@kjanat/dreamcli 2.2.0 → 2.2.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 +28 -1
- package/dist/core/cli/help-links.d.mts +28 -0
- package/dist/core/cli/help-links.mjs +1 -0
- package/dist/core/cli/index.d.mts +53 -2
- package/dist/core/cli/index.mjs +1 -1
- package/dist/core/cli/root-help.d.mts +4 -0
- package/dist/core/cli/root-help.mjs +4 -5
- package/dist/core/cli/runtime-preflight.d.mts +3 -0
- package/dist/core/cli/runtime-preflight.mjs +1 -1
- package/dist/core/config/index.d.mts +2 -2
- package/dist/core/config/package-json.d.mts +36 -1
- package/dist/core/config/package-json.mjs +1 -1
- package/dist/core/help/ansi.d.mts +78 -0
- package/dist/core/help/ansi.mjs +2 -0
- package/dist/core/help/index.d.mts +9 -1
- package/dist/core/help/index.mjs +4 -5
- package/dist/index.d.mts +4 -2
- package/dist/index.mjs +1 -1
- package/dist/version.mjs +1 -1
- package/package.json +1 -1
- package/src/core/cli/help-links.ts +82 -0
- package/src/core/cli/index.ts +100 -5
- package/src/core/cli/root-help.ts +36 -53
- package/src/core/cli/runtime-preflight.ts +5 -0
- package/src/core/config/index.ts +2 -2
- package/src/core/config/package-json.ts +119 -2
- package/src/core/help/ansi.ts +144 -0
- package/src/core/help/index.ts +9 -50
- package/src/index.ts +4 -1
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ANSI/OSC-aware text helpers for help formatting.
|
|
3
|
+
*
|
|
4
|
+
* Terminal escape sequences (SGR colors, OSC 8 hyperlinks) occupy zero
|
|
5
|
+
* columns when rendered, so width math must measure the *visible* text.
|
|
6
|
+
* {@linkcode visibleWidth} strips escapes before counting, and the shared
|
|
7
|
+
* {@linkcode padEnd}/{@linkcode wrapText} helpers build on it so aligned
|
|
8
|
+
* tables and wrapped lines stay intact when escapes are present.
|
|
9
|
+
*
|
|
10
|
+
* @module dreamcli/core/help/ansi
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
// --- Escape stripping
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* Matches ANSI escape sequences: CSI (e.g. SGR color codes like `\x1b[31m`)
|
|
17
|
+
* and OSC (e.g. OSC 8 hyperlinks), with both BEL and ST terminators.
|
|
18
|
+
*
|
|
19
|
+
* @internal
|
|
20
|
+
*/
|
|
21
|
+
// biome-ignore lint/suspicious/noControlCharactersInRegex: matching terminal escape sequences requires control characters
|
|
22
|
+
const ANSI_PATTERN = /\u001B(?:\[[0-?]*[ -/]*[@-~]|\][^\u0007\u001B]*(?:\u0007|\u001B\\))/g;
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* Remove ANSI CSI and OSC escape sequences from `text`.
|
|
26
|
+
*
|
|
27
|
+
* @param text - Text possibly containing terminal escapes.
|
|
28
|
+
* @returns The text with all escape sequences removed.
|
|
29
|
+
*/
|
|
30
|
+
function stripAnsi(text: string): string {
|
|
31
|
+
return text.replace(ANSI_PATTERN, '');
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* Measure the visible column width of `text`, ignoring ANSI/OSC escapes.
|
|
36
|
+
*
|
|
37
|
+
* Escape sequences (SGR colors, OSC 8 hyperlinks) occupy zero columns when
|
|
38
|
+
* rendered, so `.length` overcounts whenever they are present. Help
|
|
39
|
+
* formatting uses this for padding and wrapping; exported for custom help
|
|
40
|
+
* renderers that mix colors or links into aligned output.
|
|
41
|
+
*
|
|
42
|
+
* @param text - Text possibly containing terminal escapes.
|
|
43
|
+
* @returns Number of visible characters.
|
|
44
|
+
*
|
|
45
|
+
* @example
|
|
46
|
+
* ```ts
|
|
47
|
+
* visibleWidth('plain'); // 5
|
|
48
|
+
* visibleWidth(osc8('https://x.dev', 'x')); // 1
|
|
49
|
+
* ```
|
|
50
|
+
*/
|
|
51
|
+
function visibleWidth(text: string): number {
|
|
52
|
+
return stripAnsi(text).length;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
// --- OSC 8 hyperlinks
|
|
56
|
+
|
|
57
|
+
const OSC = '\u001B]';
|
|
58
|
+
const BEL = '\u0007';
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* Wrap `text` in an [OSC 8 hyperlink](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda)
|
|
62
|
+
* pointing at `url`.
|
|
63
|
+
*
|
|
64
|
+
* Supporting terminals render `text` as a clickable link; non-supporting
|
|
65
|
+
* terminals ignore the escape sequence and show plain text. Combine with
|
|
66
|
+
* {@linkcode visibleWidth}-aware formatting when embedding links in aligned
|
|
67
|
+
* output.
|
|
68
|
+
*
|
|
69
|
+
* @param url - Link target (string or `URL` instance).
|
|
70
|
+
* @param text - Visible link text.
|
|
71
|
+
* @returns The OSC 8 escape sequence wrapping `text`.
|
|
72
|
+
*
|
|
73
|
+
* @example
|
|
74
|
+
* ```ts
|
|
75
|
+
* cli('mycli').version(osc8('https://github.com/me/mycli/releases/tag/v1.0.0', '1.0.0'));
|
|
76
|
+
* ```
|
|
77
|
+
*/
|
|
78
|
+
function osc8(url: string | URL, text: string): string {
|
|
79
|
+
const href = url instanceof URL ? url.href : url;
|
|
80
|
+
return `${OSC}8;;${href}${BEL}${text}${OSC}8;;${BEL}`;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
// --- Width-aware padding and wrapping
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* Pad `text` to `length` visible columns with trailing spaces.
|
|
87
|
+
*
|
|
88
|
+
* @param text - The string to pad (may contain ANSI/OSC escapes).
|
|
89
|
+
* @param length - Target visible width in columns.
|
|
90
|
+
* @returns The padded string, unchanged if already at or beyond `length`.
|
|
91
|
+
*/
|
|
92
|
+
function padEnd(text: string, length: number): string {
|
|
93
|
+
const visible = visibleWidth(text);
|
|
94
|
+
if (visible >= length) return text;
|
|
95
|
+
return text + ' '.repeat(length - visible);
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* Wrap text to `width`, preserving leading indent on continuation lines.
|
|
100
|
+
*
|
|
101
|
+
* Line lengths are measured with {@linkcode visibleWidth}, so embedded
|
|
102
|
+
* ANSI/OSC escapes do not trigger premature wrapping.
|
|
103
|
+
*
|
|
104
|
+
* @param text - The text to wrap.
|
|
105
|
+
* @param width - Maximum line width in columns.
|
|
106
|
+
* @param indent - Number of leading spaces for continuation lines.
|
|
107
|
+
* @returns The wrapped string with newlines inserted as needed.
|
|
108
|
+
*/
|
|
109
|
+
function wrapText(text: string, width: number, indent: number): string {
|
|
110
|
+
if (visibleWidth(text) + indent <= width) return text;
|
|
111
|
+
|
|
112
|
+
const maxLen = width - indent;
|
|
113
|
+
if (maxLen <= 0) return text;
|
|
114
|
+
|
|
115
|
+
const words = text.split(' ');
|
|
116
|
+
const lines: string[] = [];
|
|
117
|
+
let current = '';
|
|
118
|
+
let currentWidth = 0;
|
|
119
|
+
|
|
120
|
+
for (const word of words) {
|
|
121
|
+
const wordWidth = visibleWidth(word);
|
|
122
|
+
if (current.length === 0) {
|
|
123
|
+
current = word;
|
|
124
|
+
currentWidth = wordWidth;
|
|
125
|
+
} else if (currentWidth + 1 + wordWidth <= maxLen) {
|
|
126
|
+
current += ` ${word}`;
|
|
127
|
+
currentWidth += 1 + wordWidth;
|
|
128
|
+
} else {
|
|
129
|
+
lines.push(current);
|
|
130
|
+
current = word;
|
|
131
|
+
currentWidth = wordWidth;
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
if (current.length > 0) {
|
|
135
|
+
lines.push(current);
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
const pad = ' '.repeat(indent);
|
|
139
|
+
return lines.map((line, i) => (i === 0 ? line : `${pad}${line}`)).join('\n');
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
// --- Exports
|
|
143
|
+
|
|
144
|
+
export { osc8, padEnd, stripAnsi, visibleWidth, wrapText };
|
package/src/core/help/index.ts
CHANGED
|
@@ -10,6 +10,7 @@
|
|
|
10
10
|
|
|
11
11
|
import { formatDisplayValue } from '#internals/core/output/display-value.ts';
|
|
12
12
|
import { getFlagAliasNames } from '#internals/core/schema/flag.ts';
|
|
13
|
+
import { padEnd, wrapText } from './ansi.ts';
|
|
13
14
|
import type {
|
|
14
15
|
ArgSchema,
|
|
15
16
|
CommandArgEntry,
|
|
@@ -26,6 +27,13 @@ interface HelpOptions {
|
|
|
26
27
|
readonly width?: number;
|
|
27
28
|
/** Binary/program name shown in the usage line. Defaults to command name. */
|
|
28
29
|
readonly binName?: string;
|
|
30
|
+
/**
|
|
31
|
+
* Emit OSC 8 hyperlinks where link metadata is available (currently the
|
|
32
|
+
* root-help header name/version configured via `CLIBuilder.links()`).
|
|
33
|
+
* Defaults to `false`; `CLIBuilder.execute()`/`.run()` enable it
|
|
34
|
+
* automatically when stdout is a TTY.
|
|
35
|
+
*/
|
|
36
|
+
readonly hyperlinks?: boolean;
|
|
29
37
|
/** @internal Whether this usage line is being rendered as merged root/default help. */
|
|
30
38
|
readonly isDefaultHelp?: boolean;
|
|
31
39
|
}
|
|
@@ -53,56 +61,6 @@ function resolveOptions(options?: HelpOptions): ResolvedHelpOptions {
|
|
|
53
61
|
};
|
|
54
62
|
}
|
|
55
63
|
|
|
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
64
|
// --- Deprecation formatting
|
|
107
65
|
|
|
108
66
|
/**
|
|
@@ -554,4 +512,5 @@ function formatExamplesSection(examples: readonly CommandExample[]): string {
|
|
|
554
512
|
// --- Exports
|
|
555
513
|
|
|
556
514
|
export type { HelpOptions };
|
|
515
|
+
export { osc8, visibleWidth } from './ansi.ts';
|
|
557
516
|
export { formatHelp, formatHelpSections };
|
package/src/index.ts
CHANGED
|
@@ -26,6 +26,7 @@ export type {
|
|
|
26
26
|
CLIRunOptions,
|
|
27
27
|
CLISchema,
|
|
28
28
|
ConfigSettings,
|
|
29
|
+
HelpLinks,
|
|
29
30
|
PackageJsonSettings,
|
|
30
31
|
PluginCommandContext,
|
|
31
32
|
ResolvedCommandParams,
|
|
@@ -49,6 +50,7 @@ export type {
|
|
|
49
50
|
FormatLoader,
|
|
50
51
|
PackageJsonAdapter,
|
|
51
52
|
PackageJsonData,
|
|
53
|
+
PackageRepository,
|
|
52
54
|
} from './core/config/index.ts';
|
|
53
55
|
export {
|
|
54
56
|
buildConfigSearchPaths,
|
|
@@ -56,6 +58,7 @@ export {
|
|
|
56
58
|
discoverConfig,
|
|
57
59
|
discoverPackageJson,
|
|
58
60
|
inferCliName,
|
|
61
|
+
packageRepositoryUrl,
|
|
59
62
|
} from './core/config/index.ts';
|
|
60
63
|
export type {
|
|
61
64
|
CLIErrorJSON,
|
|
@@ -75,7 +78,7 @@ export {
|
|
|
75
78
|
ValidationError,
|
|
76
79
|
} from './core/errors/index.ts';
|
|
77
80
|
export type { HelpOptions } from './core/help/index.ts';
|
|
78
|
-
export { formatHelp } from './core/help/index.ts';
|
|
81
|
+
export { formatHelp, osc8, visibleWidth } from './core/help/index.ts';
|
|
79
82
|
export type { JsonSchemaOptions } from './core/json-schema/index.ts';
|
|
80
83
|
export {
|
|
81
84
|
definitionMetaSchema,
|