@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,82 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Root-help header hyperlink resolution.
|
|
3
|
+
*
|
|
4
|
+
* Stores explicit `.links()` URLs and derives missing ones from package.json
|
|
5
|
+
* metadata (`repository` / `homepage`) once that data is available — during
|
|
6
|
+
* runtime preflight for `.run()`, or directly from pre-loaded
|
|
7
|
+
* `.packageJson(data)` for `.execute()`.
|
|
8
|
+
*
|
|
9
|
+
* @module dreamcli/core/cli/help-links
|
|
10
|
+
* @internal
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
import type { PackageJsonData } from '#internals/core/config/package-json.ts';
|
|
14
|
+
import { packageRepositoryUrl } from '#internals/core/config/package-json.ts';
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* OSC 8 hyperlink targets for the root-help header.
|
|
18
|
+
*
|
|
19
|
+
* Set via `CLIBuilder.links()`; fields left `undefined` are derived from
|
|
20
|
+
* package.json metadata when `.packageJson()` is active.
|
|
21
|
+
*/
|
|
22
|
+
interface HelpLinks {
|
|
23
|
+
/** URL the program name links to (e.g. the repository or homepage). */
|
|
24
|
+
readonly name: string | undefined;
|
|
25
|
+
/** URL the version links to (e.g. the release tag). */
|
|
26
|
+
readonly version: string | undefined;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* Build the release-tag URL for a version on a known forge.
|
|
31
|
+
*
|
|
32
|
+
* GitHub and GitLab have stable release-tag routes; other hosts return
|
|
33
|
+
* `undefined` rather than guessing.
|
|
34
|
+
*
|
|
35
|
+
* @internal
|
|
36
|
+
*/
|
|
37
|
+
function releaseTagUrl(repoUrl: string, version: string): string | undefined {
|
|
38
|
+
let hostname: string;
|
|
39
|
+
try {
|
|
40
|
+
hostname = new URL(repoUrl).hostname;
|
|
41
|
+
} catch {
|
|
42
|
+
return undefined;
|
|
43
|
+
}
|
|
44
|
+
if (hostname === 'github.com') return `${repoUrl}/releases/tag/v${version}`;
|
|
45
|
+
if (hostname === 'gitlab.com') return `${repoUrl}/-/releases/v${version}`;
|
|
46
|
+
return undefined;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Fill `undefined` link fields from package.json metadata.
|
|
51
|
+
*
|
|
52
|
+
* Explicit URLs always win. The name falls back to the normalized
|
|
53
|
+
* `repository` URL, then `homepage`; the version falls back to the forge
|
|
54
|
+
* release-tag URL when both a repository and a version are known.
|
|
55
|
+
* Idempotent — already-resolved fields pass through unchanged.
|
|
56
|
+
*
|
|
57
|
+
* @internal
|
|
58
|
+
*/
|
|
59
|
+
function deriveHelpLinks(
|
|
60
|
+
links: HelpLinks | undefined,
|
|
61
|
+
pkg: PackageJsonData | undefined,
|
|
62
|
+
version: string | undefined,
|
|
63
|
+
): HelpLinks | undefined {
|
|
64
|
+
if (links === undefined) return undefined;
|
|
65
|
+
if (pkg === undefined || (links.name !== undefined && links.version !== undefined)) {
|
|
66
|
+
return links;
|
|
67
|
+
}
|
|
68
|
+
const repoUrl = packageRepositoryUrl(pkg);
|
|
69
|
+
return {
|
|
70
|
+
name: links.name ?? repoUrl ?? pkg.homepage,
|
|
71
|
+
version:
|
|
72
|
+
links.version ??
|
|
73
|
+
(repoUrl !== undefined && version !== undefined
|
|
74
|
+
? releaseTagUrl(repoUrl, version)
|
|
75
|
+
: undefined),
|
|
76
|
+
};
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
// --- Exports
|
|
80
|
+
|
|
81
|
+
export type { HelpLinks };
|
|
82
|
+
export { deriveHelpLinks };
|
package/src/core/cli/index.ts
CHANGED
|
@@ -35,6 +35,8 @@ import type { RunOptions, RunResult } from '#internals/core/schema/run.ts';
|
|
|
35
35
|
import { runCommand } from '#internals/core/testkit/index.ts';
|
|
36
36
|
import type { RuntimeAdapter } from '#internals/runtime/adapter.ts';
|
|
37
37
|
import { createAdapter } from '#internals/runtime/auto.ts';
|
|
38
|
+
import type { HelpLinks } from './help-links.ts';
|
|
39
|
+
import { deriveHelpLinks } from './help-links.ts';
|
|
38
40
|
import type { OutputPolicy } from './planner.ts';
|
|
39
41
|
import { planInvocation } from './planner.ts';
|
|
40
42
|
import type { CLIPlugin } from './plugin.ts';
|
|
@@ -185,6 +187,14 @@ interface CLISchema {
|
|
|
185
187
|
* Set via the {@linkcode CLIBuilder.packageJson | .packageJson()} builder method.
|
|
186
188
|
*/
|
|
187
189
|
readonly packageJsonSettings: PackageJsonSettings | undefined;
|
|
190
|
+
/**
|
|
191
|
+
* OSC 8 hyperlink targets for the root-help header (name/version).
|
|
192
|
+
*
|
|
193
|
+
* Set via the {@linkcode CLIBuilder.links | .links()} builder method.
|
|
194
|
+
* Fields left `undefined` are derived from package.json metadata
|
|
195
|
+
* (`repository` / `homepage`) when `.packageJson()` is active.
|
|
196
|
+
*/
|
|
197
|
+
readonly helpLinks: HelpLinks | undefined;
|
|
188
198
|
/** Whether built-in `.completions()` command registration is active. */
|
|
189
199
|
readonly hasBuiltInCompletions: boolean;
|
|
190
200
|
/** Registered CLI plugins. */
|
|
@@ -364,6 +374,54 @@ class CLIBuilder {
|
|
|
364
374
|
return new CLIBuilder({ ...this.schema, description: text });
|
|
365
375
|
}
|
|
366
376
|
|
|
377
|
+
/**
|
|
378
|
+
* Make the root-help header clickable with OSC 8 hyperlinks.
|
|
379
|
+
*
|
|
380
|
+
* Links the program name and version on the first line of root `--help`
|
|
381
|
+
* output in terminals that support
|
|
382
|
+
* [OSC 8 hyperlinks](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda).
|
|
383
|
+
* The escapes are only emitted when stdout is a TTY (overridable via
|
|
384
|
+
* `options.help.hyperlinks`), and only in the header — usage lines, the
|
|
385
|
+
* `--help` hint, the commands table, and completion scripts stay plain.
|
|
386
|
+
*
|
|
387
|
+
* URLs not provided here are derived from package.json metadata when
|
|
388
|
+
* `.packageJson()` is active (works with both filesystem discovery and
|
|
389
|
+
* pre-loaded data):
|
|
390
|
+
* - **name** → normalized `repository` URL, falling back to `homepage`
|
|
391
|
+
* - **version** → forge release tag (`{repo}/releases/tag/v{version}` on
|
|
392
|
+
* GitHub, `{repo}/-/releases/v{version}` on GitLab)
|
|
393
|
+
*
|
|
394
|
+
* @param links - Explicit URLs; omit to derive everything from package.json.
|
|
395
|
+
* @returns The builder (for chaining).
|
|
396
|
+
*
|
|
397
|
+
* @example
|
|
398
|
+
* ```ts
|
|
399
|
+
* // Derive both links from package.json repository/homepage:
|
|
400
|
+
* cli('mycli')
|
|
401
|
+
* .packageJson()
|
|
402
|
+
* .links()
|
|
403
|
+
* .run();
|
|
404
|
+
*
|
|
405
|
+
* // Explicit URLs (no package.json required):
|
|
406
|
+
* cli('mycli')
|
|
407
|
+
* .version('1.0.0')
|
|
408
|
+
* .links({
|
|
409
|
+
* name: 'https://github.com/me/mycli',
|
|
410
|
+
* version: 'https://github.com/me/mycli/releases/tag/v1.0.0',
|
|
411
|
+
* })
|
|
412
|
+
* .run();
|
|
413
|
+
* ```
|
|
414
|
+
*/
|
|
415
|
+
links(links?: { readonly name?: string | URL; readonly version?: string | URL }): CLIBuilder {
|
|
416
|
+
return new CLIBuilder({
|
|
417
|
+
...this.schema,
|
|
418
|
+
helpLinks: {
|
|
419
|
+
name: toUrlString(links?.name),
|
|
420
|
+
version: toUrlString(links?.version),
|
|
421
|
+
},
|
|
422
|
+
});
|
|
423
|
+
}
|
|
424
|
+
|
|
367
425
|
/**
|
|
368
426
|
* Enable automatic config file discovery.
|
|
369
427
|
*
|
|
@@ -766,10 +824,12 @@ class CLIBuilder {
|
|
|
766
824
|
);
|
|
767
825
|
}
|
|
768
826
|
|
|
769
|
-
// Resolve help options — default binName to CLI program name
|
|
827
|
+
// Resolve help options — default binName to CLI program name,
|
|
828
|
+
// hyperlinks to TTY detection (escapes never leak into piped output)
|
|
770
829
|
const helpOptions: HelpOptions = {
|
|
771
830
|
...options?.help,
|
|
772
831
|
binName: options?.help?.binName ?? this.schema.name,
|
|
832
|
+
hyperlinks: options?.help?.hyperlinks ?? out.isTTY,
|
|
773
833
|
};
|
|
774
834
|
|
|
775
835
|
// -- Shared options for command execution ----------------------------------
|
|
@@ -796,7 +856,7 @@ class CLIBuilder {
|
|
|
796
856
|
return buildRunResult({ exitCode: 0, error: undefined }, captured);
|
|
797
857
|
|
|
798
858
|
case 'root-help': {
|
|
799
|
-
const helpText = formatRootHelp(this.schema, planned.help);
|
|
859
|
+
const helpText = formatRootHelp(resolveHelpLinksSchema(this.schema), planned.help);
|
|
800
860
|
out.log(helpText);
|
|
801
861
|
return buildRunResult({ exitCode: 0, error: undefined }, captured);
|
|
802
862
|
}
|
|
@@ -974,6 +1034,32 @@ function inferInvocationName(argv: readonly string[]): string | undefined {
|
|
|
974
1034
|
return argv0 !== undefined ? basename(argv0) : undefined;
|
|
975
1035
|
}
|
|
976
1036
|
|
|
1037
|
+
// --- Help link helpers
|
|
1038
|
+
|
|
1039
|
+
/** Coerce a `string | URL` link input to its string form. @internal */
|
|
1040
|
+
function toUrlString(value: string | URL | undefined): string | undefined {
|
|
1041
|
+
if (value === undefined) return undefined;
|
|
1042
|
+
return value instanceof URL ? value.href : value;
|
|
1043
|
+
}
|
|
1044
|
+
|
|
1045
|
+
/**
|
|
1046
|
+
* Resolve derived help links against pre-loaded package.json data.
|
|
1047
|
+
*
|
|
1048
|
+
* `.run()` resolves links during runtime preflight (where discovered
|
|
1049
|
+
* package.json metadata lives); this covers the filesystem-free
|
|
1050
|
+
* `.execute()` path, where only the `.packageJson(data)` overload can
|
|
1051
|
+
* contribute. Idempotent — already-resolved fields pass through unchanged.
|
|
1052
|
+
*
|
|
1053
|
+
* @internal
|
|
1054
|
+
*/
|
|
1055
|
+
function resolveHelpLinksSchema(schema: CLISchema): CLISchema {
|
|
1056
|
+
if (schema.helpLinks === undefined) return schema;
|
|
1057
|
+
return {
|
|
1058
|
+
...schema,
|
|
1059
|
+
helpLinks: deriveHelpLinks(schema.helpLinks, schema.packageJsonSettings?.data, schema.version),
|
|
1060
|
+
};
|
|
1061
|
+
}
|
|
1062
|
+
|
|
977
1063
|
// --- packageJson.from normalisation
|
|
978
1064
|
|
|
979
1065
|
/**
|
|
@@ -1016,14 +1102,21 @@ function normalizeFromSetting(from: string | URL | undefined): string | undefine
|
|
|
1016
1102
|
*
|
|
1017
1103
|
* A value is treated as `PackageJsonData` when it's a plain object that
|
|
1018
1104
|
* carries at least one recognised field (`name`, `version`, `description`,
|
|
1019
|
-
* or `
|
|
1020
|
-
* `from`) falls through to the settings overload.
|
|
1105
|
+
* `bin`, `homepage`, or `repository`). An empty `{}` or a settings-shaped
|
|
1106
|
+
* object (`inferName` / `from`) falls through to the settings overload.
|
|
1021
1107
|
*
|
|
1022
1108
|
* @internal
|
|
1023
1109
|
*/
|
|
1024
1110
|
function isPackageJsonData(value: unknown): value is PackageJsonData {
|
|
1025
1111
|
if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
|
|
1026
|
-
return
|
|
1112
|
+
return (
|
|
1113
|
+
'name' in value ||
|
|
1114
|
+
'version' in value ||
|
|
1115
|
+
'description' in value ||
|
|
1116
|
+
'bin' in value ||
|
|
1117
|
+
'homepage' in value ||
|
|
1118
|
+
'repository' in value
|
|
1119
|
+
);
|
|
1027
1120
|
}
|
|
1028
1121
|
|
|
1029
1122
|
// --- Factory function
|
|
@@ -1093,6 +1186,7 @@ function cli(nameOrOptions: string | CLIOptions): CLIBuilder {
|
|
|
1093
1186
|
defaultCommand: undefined,
|
|
1094
1187
|
configSettings: undefined,
|
|
1095
1188
|
packageJsonSettings: undefined,
|
|
1189
|
+
helpLinks: undefined,
|
|
1096
1190
|
hasBuiltInCompletions: false,
|
|
1097
1191
|
plugins: [],
|
|
1098
1192
|
});
|
|
@@ -1107,5 +1201,6 @@ export type {
|
|
|
1107
1201
|
PluginCommandContext,
|
|
1108
1202
|
ResolvedCommandParams,
|
|
1109
1203
|
} from './plugin.ts';
|
|
1204
|
+
export type { HelpLinks } from './help-links.ts';
|
|
1110
1205
|
export type { CLIOptions, CLIRunOptions, CLISchema, ConfigSettings, PackageJsonSettings };
|
|
1111
1206
|
export { CLIBuilder, cli, formatRootHelp, plugin };
|
|
@@ -8,6 +8,7 @@
|
|
|
8
8
|
* @internal
|
|
9
9
|
*/
|
|
10
10
|
|
|
11
|
+
import { osc8, padEnd, wrapText } from '#internals/core/help/ansi.ts';
|
|
11
12
|
import type { HelpOptions } from '#internals/core/help/index.ts';
|
|
12
13
|
import { formatHelpSections } from '#internals/core/help/index.ts';
|
|
13
14
|
import type { CommandSchema } from '#internals/core/schema/command.ts';
|
|
@@ -15,7 +16,7 @@ import { resolveRootSurface } from './root-surface.ts';
|
|
|
15
16
|
|
|
16
17
|
// Re-use CLISchema inline to avoid circular import through the barrel.
|
|
17
18
|
// Only the shape matters — we read `.name`, `.version`, `.description`, `.commands`,
|
|
18
|
-
// `.defaultCommand`.
|
|
19
|
+
// `.defaultCommand`, `.helpLinks`.
|
|
19
20
|
/** Structural subset of `CLISchema` — avoids circular imports through the barrel. */
|
|
20
21
|
interface CLISchemaLike {
|
|
21
22
|
readonly name: string;
|
|
@@ -25,6 +26,12 @@ interface CLISchemaLike {
|
|
|
25
26
|
readonly schema: CommandSchema;
|
|
26
27
|
}>;
|
|
27
28
|
readonly defaultCommand: { readonly schema: CommandSchema } | undefined;
|
|
29
|
+
readonly helpLinks?:
|
|
30
|
+
| {
|
|
31
|
+
readonly name: string | undefined;
|
|
32
|
+
readonly version: string | undefined;
|
|
33
|
+
}
|
|
34
|
+
| undefined;
|
|
28
35
|
}
|
|
29
36
|
|
|
30
37
|
// --- Root help formatter
|
|
@@ -40,6 +47,7 @@ interface CLISchemaLike {
|
|
|
40
47
|
*/
|
|
41
48
|
function formatRootHelp(schema: CLISchemaLike, options?: HelpOptions): string {
|
|
42
49
|
const width = options?.width ?? 80;
|
|
50
|
+
const hyperlinks = options?.hyperlinks === true;
|
|
43
51
|
const rootSurface = resolveRootSurface(schema);
|
|
44
52
|
if (rootSurface.hasSingleVisibleDefault) {
|
|
45
53
|
const defaultCommand = rootSurface.visibleDefaultCommand;
|
|
@@ -49,6 +57,7 @@ function formatRootHelp(schema: CLISchemaLike, options?: HelpOptions): string {
|
|
|
49
57
|
rootSurface.visibleCommands,
|
|
50
58
|
rootSurface.visibleDefaultCommand,
|
|
51
59
|
width,
|
|
60
|
+
hyperlinks,
|
|
52
61
|
);
|
|
53
62
|
const usageIndex = sections.findIndex((section) => section.startsWith('Usage: '));
|
|
54
63
|
const commandSections = [
|
|
@@ -79,6 +88,7 @@ function formatRootHelp(schema: CLISchemaLike, options?: HelpOptions): string {
|
|
|
79
88
|
rootSurface.visibleCommands,
|
|
80
89
|
rootSurface.visibleDefaultCommand,
|
|
81
90
|
width,
|
|
91
|
+
hyperlinks,
|
|
82
92
|
);
|
|
83
93
|
const placeholder = commandPlaceholder(
|
|
84
94
|
rootSurface.visibleCommands,
|
|
@@ -99,6 +109,7 @@ function formatRootHelp(schema: CLISchemaLike, options?: HelpOptions): string {
|
|
|
99
109
|
* @param schema - The CLI schema.
|
|
100
110
|
* @param visibleCommands - Non-hidden top-level commands.
|
|
101
111
|
* @param width - Terminal width for text wrapping.
|
|
112
|
+
* @param hyperlinks - Whether to emit OSC 8 hyperlinks in the header.
|
|
102
113
|
* @returns Ordered help sections (joined later with blank lines).
|
|
103
114
|
* @internal
|
|
104
115
|
*/
|
|
@@ -107,12 +118,12 @@ function buildRootSections(
|
|
|
107
118
|
visibleCommands: readonly CommandSchema[],
|
|
108
119
|
visibleDefaultCommand: CommandSchema | undefined,
|
|
109
120
|
width: number,
|
|
121
|
+
hyperlinks: boolean,
|
|
110
122
|
): string[] {
|
|
111
123
|
const sections: string[] = [];
|
|
112
124
|
|
|
113
125
|
// ---- Header: name + version ---------------------------------------------
|
|
114
|
-
|
|
115
|
-
sections.push(header);
|
|
126
|
+
sections.push(formatHeader(schema, hyperlinks));
|
|
116
127
|
|
|
117
128
|
// ---- Description --------------------------------------------------------
|
|
118
129
|
if (schema.description !== undefined) {
|
|
@@ -135,6 +146,28 @@ function buildRootSections(
|
|
|
135
146
|
return sections;
|
|
136
147
|
}
|
|
137
148
|
|
|
149
|
+
/**
|
|
150
|
+
* Render the header line (`name vX.Y.Z`).
|
|
151
|
+
*
|
|
152
|
+
* When `hyperlinks` is enabled and the schema carries link URLs (via
|
|
153
|
+
* `CLIBuilder.links()`, possibly derived from package.json metadata), the
|
|
154
|
+
* name and version are wrapped in OSC 8 hyperlinks. The header is the only
|
|
155
|
+
* place links are emitted — usage lines, hints, and the commands table stay
|
|
156
|
+
* plain.
|
|
157
|
+
*
|
|
158
|
+
* @param schema - The CLI schema.
|
|
159
|
+
* @param hyperlinks - Whether OSC 8 hyperlinks may be emitted.
|
|
160
|
+
* @returns The header line.
|
|
161
|
+
* @internal
|
|
162
|
+
*/
|
|
163
|
+
function formatHeader(schema: CLISchemaLike, hyperlinks: boolean): string {
|
|
164
|
+
const links = hyperlinks ? schema.helpLinks : undefined;
|
|
165
|
+
const name = links?.name !== undefined ? osc8(links.name, schema.name) : schema.name;
|
|
166
|
+
if (schema.version === undefined) return name;
|
|
167
|
+
const version = `v${schema.version}`;
|
|
168
|
+
return `${name} ${links?.version !== undefined ? osc8(links.version, version) : version}`;
|
|
169
|
+
}
|
|
170
|
+
|
|
138
171
|
/**
|
|
139
172
|
* Return the usage-line placeholder for commands (`<command>`, `[command]`, or empty).
|
|
140
173
|
*
|
|
@@ -214,56 +247,6 @@ function mergeUsageSections(rootUsage: string, commandUsage: string): string {
|
|
|
214
247
|
return `${rootUsage}\n${' '.repeat(usagePrefix.length)}${commandSuffix}`;
|
|
215
248
|
}
|
|
216
249
|
|
|
217
|
-
// --- Text helpers (duplicated from help module to avoid coupling)
|
|
218
|
-
|
|
219
|
-
/**
|
|
220
|
-
* Pad `text` to `length` with trailing spaces.
|
|
221
|
-
*
|
|
222
|
-
* @param text - The string to pad.
|
|
223
|
-
* @param length - Target width.
|
|
224
|
-
* @returns Padded string.
|
|
225
|
-
*/
|
|
226
|
-
function padEnd(text: string, length: number): string {
|
|
227
|
-
if (text.length >= length) return text;
|
|
228
|
-
return text + ' '.repeat(length - text.length);
|
|
229
|
-
}
|
|
230
|
-
|
|
231
|
-
/**
|
|
232
|
-
* Wrap text to `width`, preserving leading indent on continuation lines.
|
|
233
|
-
*
|
|
234
|
-
* @param text - The text to wrap.
|
|
235
|
-
* @param width - Maximum line width.
|
|
236
|
-
* @param indent - Indentation for continuation lines.
|
|
237
|
-
* @returns Wrapped text with continuation indentation.
|
|
238
|
-
*/
|
|
239
|
-
function wrapText(text: string, width: number, indent: number): string {
|
|
240
|
-
if (text.length + indent <= width) return text;
|
|
241
|
-
|
|
242
|
-
const maxLen = width - indent;
|
|
243
|
-
if (maxLen <= 0) return text;
|
|
244
|
-
|
|
245
|
-
const words = text.split(' ');
|
|
246
|
-
const lines: string[] = [];
|
|
247
|
-
let current = '';
|
|
248
|
-
|
|
249
|
-
for (const word of words) {
|
|
250
|
-
if (current.length === 0) {
|
|
251
|
-
current = word;
|
|
252
|
-
} else if (current.length + 1 + word.length <= maxLen) {
|
|
253
|
-
current += ` ${word}`;
|
|
254
|
-
} else {
|
|
255
|
-
lines.push(current);
|
|
256
|
-
current = word;
|
|
257
|
-
}
|
|
258
|
-
}
|
|
259
|
-
if (current.length > 0) {
|
|
260
|
-
lines.push(current);
|
|
261
|
-
}
|
|
262
|
-
|
|
263
|
-
const pad = ' '.repeat(indent);
|
|
264
|
-
return lines.map((line, i) => (i === 0 ? line : `${pad}${line}`)).join('\n');
|
|
265
|
-
}
|
|
266
|
-
|
|
267
250
|
// --- Exports
|
|
268
251
|
|
|
269
252
|
export { formatRootHelp };
|
|
@@ -20,6 +20,8 @@ import type { PromptEngine } from '#internals/core/prompt/index.ts';
|
|
|
20
20
|
import { createTerminalPrompter } from '#internals/core/prompt/index.ts';
|
|
21
21
|
import type { CommandSchema, ErasedCommand } from '#internals/core/schema/command.ts';
|
|
22
22
|
import type { RuntimeAdapter } from '#internals/runtime/adapter.ts';
|
|
23
|
+
import type { HelpLinks } from './help-links.ts';
|
|
24
|
+
import { deriveHelpLinks } from './help-links.ts';
|
|
23
25
|
import { planInvocation } from './planner.ts';
|
|
24
26
|
import type { CLIPlugin } from './plugin.ts';
|
|
25
27
|
|
|
@@ -65,6 +67,8 @@ interface RuntimePreflightSchemaLike {
|
|
|
65
67
|
readonly configSettings: RuntimeConfigSettings | undefined;
|
|
66
68
|
/** Package.json discovery settings; `undefined` disables package.json inference. */
|
|
67
69
|
readonly packageJsonSettings: RuntimePackageJsonSettings | undefined;
|
|
70
|
+
/** Root-help header link targets; `undefined` fields may be derived from package.json. */
|
|
71
|
+
readonly helpLinks: HelpLinks | undefined;
|
|
68
72
|
/** Whether `.completions()` registered the built-in completions command. */
|
|
69
73
|
readonly hasBuiltInCompletions: boolean;
|
|
70
74
|
/** Plugins forwarded into the execution pipeline. */
|
|
@@ -296,6 +300,7 @@ async function applyPackageJsonDiscovery(
|
|
|
296
300
|
? { description: pkg.description }
|
|
297
301
|
: {}),
|
|
298
302
|
...(inferredName !== undefined ? { name: inferredName } : {}),
|
|
303
|
+
helpLinks: deriveHelpLinks(schema.helpLinks, pkg, schema.version ?? pkg.version),
|
|
299
304
|
};
|
|
300
305
|
})()
|
|
301
306
|
: schema;
|
package/src/core/config/index.ts
CHANGED
|
@@ -394,8 +394,8 @@ function configFormat(
|
|
|
394
394
|
|
|
395
395
|
// --- Exports
|
|
396
396
|
|
|
397
|
-
export type { PackageJsonAdapter, PackageJsonData } from './package-json.ts';
|
|
398
|
-
export { discoverPackageJson, inferCliName } from './package-json.ts';
|
|
397
|
+
export type { PackageJsonAdapter, PackageJsonData, PackageRepository } from './package-json.ts';
|
|
398
|
+
export { discoverPackageJson, inferCliName, packageRepositoryUrl } from './package-json.ts';
|
|
399
399
|
export type {
|
|
400
400
|
ConfigAdapter,
|
|
401
401
|
ConfigDiscoveryOptions,
|
|
@@ -19,6 +19,19 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
|
|
|
19
19
|
|
|
20
20
|
// --- Types
|
|
21
21
|
|
|
22
|
+
/**
|
|
23
|
+
* Object form of the package.json `repository` field
|
|
24
|
+
* (e.g. `{"type":"git","url":"git+https://github.com/u/r.git"}`).
|
|
25
|
+
*/
|
|
26
|
+
interface PackageRepository {
|
|
27
|
+
/** Version control system type (usually `'git'`). */
|
|
28
|
+
readonly type?: string;
|
|
29
|
+
/** Repository URL or locator. */
|
|
30
|
+
readonly url?: string;
|
|
31
|
+
/** Subdirectory within a monorepo where the package lives. */
|
|
32
|
+
readonly directory?: string;
|
|
33
|
+
}
|
|
34
|
+
|
|
22
35
|
/**
|
|
23
36
|
* Subset of package.json fields relevant to CLI metadata.
|
|
24
37
|
*
|
|
@@ -33,6 +46,10 @@ interface PackageJsonData {
|
|
|
33
46
|
readonly description?: string;
|
|
34
47
|
/** Binary entry point(s) — string for single-bin, object for multi-bin. */
|
|
35
48
|
readonly bin?: string | Readonly<Record<string, string>>;
|
|
49
|
+
/** Project homepage URL. */
|
|
50
|
+
readonly homepage?: string;
|
|
51
|
+
/** Repository locator — URL/shorthand string or `{type, url, directory}` object. */
|
|
52
|
+
readonly repository?: string | PackageRepository;
|
|
36
53
|
}
|
|
37
54
|
|
|
38
55
|
/**
|
|
@@ -162,11 +179,15 @@ function parsePackageJson(content: string): PackageJsonData | null {
|
|
|
162
179
|
const description =
|
|
163
180
|
typeof parsed['description'] === 'string' ? parsed['description'] : undefined;
|
|
164
181
|
const bin = parseBinField(parsed['bin']);
|
|
182
|
+
const homepage = typeof parsed['homepage'] === 'string' ? parsed['homepage'] : undefined;
|
|
183
|
+
const repository = parseRepositoryField(parsed['repository']);
|
|
165
184
|
return {
|
|
166
185
|
...(name !== undefined ? { name } : {}),
|
|
167
186
|
...(version !== undefined ? { version } : {}),
|
|
168
187
|
...(description !== undefined ? { description } : {}),
|
|
169
188
|
...(bin !== undefined ? { bin } : {}),
|
|
189
|
+
...(homepage !== undefined ? { homepage } : {}),
|
|
190
|
+
...(repository !== undefined ? { repository } : {}),
|
|
170
191
|
};
|
|
171
192
|
} catch {
|
|
172
193
|
return null;
|
|
@@ -193,6 +214,102 @@ function parseBinField(value: unknown): string | Readonly<Record<string, string>
|
|
|
193
214
|
return result;
|
|
194
215
|
}
|
|
195
216
|
|
|
217
|
+
/**
|
|
218
|
+
* Parse the `repository` field from package.json.
|
|
219
|
+
*
|
|
220
|
+
* Accepts either a locator string (`"repository": "github:u/r"`) or an
|
|
221
|
+
* object (`"repository": { "type": "git", "url": "..." }`). Returns
|
|
222
|
+
* `undefined` for anything else.
|
|
223
|
+
*
|
|
224
|
+
* @internal
|
|
225
|
+
*/
|
|
226
|
+
function parseRepositoryField(value: unknown): string | PackageRepository | undefined {
|
|
227
|
+
if (typeof value === 'string') return value;
|
|
228
|
+
if (!isPlainObject(value)) return undefined;
|
|
229
|
+
const type = typeof value['type'] === 'string' ? value['type'] : undefined;
|
|
230
|
+
const url = typeof value['url'] === 'string' ? value['url'] : undefined;
|
|
231
|
+
const directory = typeof value['directory'] === 'string' ? value['directory'] : undefined;
|
|
232
|
+
if (type === undefined && url === undefined && directory === undefined) return undefined;
|
|
233
|
+
return {
|
|
234
|
+
...(type !== undefined ? { type } : {}),
|
|
235
|
+
...(url !== undefined ? { url } : {}),
|
|
236
|
+
...(directory !== undefined ? { directory } : {}),
|
|
237
|
+
};
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
// --- packageRepositoryUrl
|
|
241
|
+
|
|
242
|
+
/** Browsable base URLs for npm repository shorthand prefixes. @internal */
|
|
243
|
+
const SHORTHAND_HOSTS: Readonly<Record<string, string>> = {
|
|
244
|
+
github: 'https://github.com',
|
|
245
|
+
gitlab: 'https://gitlab.com',
|
|
246
|
+
bitbucket: 'https://bitbucket.org',
|
|
247
|
+
};
|
|
248
|
+
|
|
249
|
+
/** Strip a trailing `.git` suffix from a repository path. @internal */
|
|
250
|
+
function stripGitSuffix(path: string): string {
|
|
251
|
+
return path.endsWith('.git') ? path.slice(0, -'.git'.length) : path;
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
/**
|
|
255
|
+
* Resolve a package's `repository` field to a browsable `https://` URL.
|
|
256
|
+
*
|
|
257
|
+
* Handles the locator formats npm accepts:
|
|
258
|
+
* - object form: `{ "type": "git", "url": "git+https://github.com/u/r.git" }`
|
|
259
|
+
* - `https`/`git`/`ssh` URLs (`git+` prefix and `.git` suffix stripped)
|
|
260
|
+
* - scp-style locators: `git@github.com:u/r.git`
|
|
261
|
+
* - shorthands: `github:u/r`, `gitlab:u/r`, `bitbucket:u/r`, and bare `u/r`
|
|
262
|
+
* (GitHub, per npm convention)
|
|
263
|
+
*
|
|
264
|
+
* Returns `undefined` when the field is absent or unrecognised.
|
|
265
|
+
*
|
|
266
|
+
* @example
|
|
267
|
+
* ```ts
|
|
268
|
+
* packageRepositoryUrl({ repository: 'git+https://github.com/u/r.git' });
|
|
269
|
+
* // 'https://github.com/u/r'
|
|
270
|
+
* ```
|
|
271
|
+
*/
|
|
272
|
+
function packageRepositoryUrl(pkg: PackageJsonData): string | undefined {
|
|
273
|
+
const raw = typeof pkg.repository === 'string' ? pkg.repository : pkg.repository?.url;
|
|
274
|
+
if (raw === undefined) return undefined;
|
|
275
|
+
|
|
276
|
+
let locator = raw.trim();
|
|
277
|
+
if (locator.length === 0) return undefined;
|
|
278
|
+
|
|
279
|
+
// npm shorthands: `github:u/r`, `gitlab:u/r`, `bitbucket:u/r`
|
|
280
|
+
const shorthand = /^(github|gitlab|bitbucket):([^/]+\/[^/]+)$/.exec(locator);
|
|
281
|
+
if (shorthand !== null && shorthand[1] !== undefined && shorthand[2] !== undefined) {
|
|
282
|
+
const host = SHORTHAND_HOSTS[shorthand[1]];
|
|
283
|
+
if (host !== undefined) {
|
|
284
|
+
return `${host}/${stripGitSuffix(shorthand[2])}`;
|
|
285
|
+
}
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
// Bare `u/r` implies GitHub (npm convention)
|
|
289
|
+
if (/^[\w.-]+\/[\w.-]+$/.test(locator)) {
|
|
290
|
+
return `https://github.com/${stripGitSuffix(locator)}`;
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
if (locator.startsWith('git+')) {
|
|
294
|
+
locator = locator.slice('git+'.length);
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
// scp-style locator: `git@github.com:u/r.git`
|
|
298
|
+
const scp = /^git@([^:/]+):(.+)$/.exec(locator);
|
|
299
|
+
if (scp !== null && scp[1] !== undefined && scp[2] !== undefined) {
|
|
300
|
+
return `https://${scp[1]}/${stripGitSuffix(scp[2].replace(/\/+$/, ''))}`;
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
if (!/^(?:https?|git|ssh):\/\//.test(locator)) return undefined;
|
|
304
|
+
try {
|
|
305
|
+
const url = new URL(locator);
|
|
306
|
+
const path = stripGitSuffix(url.pathname.replace(/\/+$/, ''));
|
|
307
|
+
return `https://${url.hostname}${path}`;
|
|
308
|
+
} catch {
|
|
309
|
+
return undefined;
|
|
310
|
+
}
|
|
311
|
+
}
|
|
312
|
+
|
|
196
313
|
// --- inferCliName
|
|
197
314
|
|
|
198
315
|
/**
|
|
@@ -229,5 +346,5 @@ function inferCliName(pkg: PackageJsonData): string | undefined {
|
|
|
229
346
|
|
|
230
347
|
// --- Exports
|
|
231
348
|
|
|
232
|
-
export type { PackageJsonAdapter, PackageJsonData };
|
|
233
|
-
export { discoverPackageJson, inferCliName };
|
|
349
|
+
export type { PackageJsonAdapter, PackageJsonData, PackageRepository };
|
|
350
|
+
export { discoverPackageJson, inferCliName, packageRepositoryUrl };
|