@kjanat/dreamcli 2.1.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.
@@ -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
- const header = schema.version !== undefined ? `${schema.name} v${schema.version}` : schema.name;
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 };
@@ -11,6 +11,7 @@
11
11
 
12
12
  import type { FormatLoader } from '#internals/core/config/index.ts';
13
13
  import { discoverConfig } from '#internals/core/config/index.ts';
14
+ import type { PackageJsonData } from '#internals/core/config/package-json.ts';
14
15
  import { discoverPackageJson, inferCliName } from '#internals/core/config/package-json.ts';
15
16
  import { CLIError, ParseError } from '#internals/core/errors/index.ts';
16
17
  import type { Verbosity } from '#internals/core/output/index.ts';
@@ -19,6 +20,8 @@ import type { PromptEngine } from '#internals/core/prompt/index.ts';
19
20
  import { createTerminalPrompter } from '#internals/core/prompt/index.ts';
20
21
  import type { CommandSchema, ErasedCommand } from '#internals/core/schema/command.ts';
21
22
  import type { RuntimeAdapter } from '#internals/runtime/adapter.ts';
23
+ import type { HelpLinks } from './help-links.ts';
24
+ import { deriveHelpLinks } from './help-links.ts';
22
25
  import { planInvocation } from './planner.ts';
23
26
  import type { CLIPlugin } from './plugin.ts';
24
27
 
@@ -34,6 +37,10 @@ interface RuntimeConfigSettings {
34
37
  interface RuntimePackageJsonSettings {
35
38
  /** Whether to infer the CLI binary name from `package.json` `bin` field. */
36
39
  readonly inferName: boolean;
40
+ /** Explicit anchor (resolved path) for discovery; `undefined` falls back to `adapter.cwd`. */
41
+ readonly from: string | undefined;
42
+ /** Pre-loaded data; when set, discovery is skipped entirely. */
43
+ readonly data: PackageJsonData | undefined;
37
44
  }
38
45
 
39
46
  /**
@@ -60,6 +67,8 @@ interface RuntimePreflightSchemaLike {
60
67
  readonly configSettings: RuntimeConfigSettings | undefined;
61
68
  /** Package.json discovery settings; `undefined` disables package.json inference. */
62
69
  readonly packageJsonSettings: RuntimePackageJsonSettings | undefined;
70
+ /** Root-help header link targets; `undefined` fields may be derived from package.json. */
71
+ readonly helpLinks: HelpLinks | undefined;
63
72
  /** Whether `.completions()` registered the built-in completions command. */
64
73
  readonly hasBuiltInCompletions: boolean;
65
74
  /** Plugins forwarded into the execution pipeline. */
@@ -276,7 +285,9 @@ async function applyPackageJsonDiscovery(
276
285
  const packageSchema =
277
286
  packageJsonSettings !== undefined && !isCompletions
278
287
  ? await (async (): Promise<RuntimePreflightSchemaLike> => {
279
- const pkg = await discoverPackageJson(adapter);
288
+ // Pre-loaded data short-circuits filesystem discovery entirely.
289
+ const pkg =
290
+ packageJsonSettings.data ?? (await discoverPackageJson(adapter, packageJsonSettings.from));
280
291
  if (pkg === null) return schema;
281
292
 
282
293
  const inferredName = packageJsonSettings.inferName ? inferCliName(pkg) : undefined;
@@ -289,6 +300,7 @@ async function applyPackageJsonDiscovery(
289
300
  ? { description: pkg.description }
290
301
  : {}),
291
302
  ...(inferredName !== undefined ? { name: inferredName } : {}),
303
+ helpLinks: deriveHelpLinks(schema.helpLinks, pkg, schema.version ?? pkg.version),
292
304
  };
293
305
  })()
294
306
  : schema;
@@ -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
  /**
@@ -86,7 +103,8 @@ function joinPath(base: string, segment: string): string {
86
103
  // --- discoverPackageJson
87
104
 
88
105
  /**
89
- * Discover the nearest `package.json` by walking up from `adapter.cwd`.
106
+ * Discover the nearest `package.json` by walking up from `startDir` (or
107
+ * `adapter.cwd` when omitted).
90
108
  *
91
109
  * Convenience helper behind `CLIBuilder.packageJson()`. Most apps should let
92
110
  * the CLI runtime discover package metadata automatically; call this directly
@@ -96,6 +114,15 @@ function joinPath(base: string, segment: string): string {
96
114
  * is found (not an error). Malformed JSON and non-object roots also
97
115
  * return `null` — the feature is a convenience, not a hard requirement.
98
116
  *
117
+ * @param adapter - Adapter providing `readFile` + `cwd`.
118
+ * @param startDir - Optional explicit directory or file path to walk up from.
119
+ * Pass an absolute path inside your own package (e.g.
120
+ * `fileURLToPath(import.meta.url)`) when authoring an installable CLI whose
121
+ * version should reflect the CLI's own package, not the consumer's working
122
+ * directory. Defaults to `adapter.cwd` when `undefined`. A file path is
123
+ * probed as a directory first (yielding nothing) before the walk-up reaches
124
+ * its real parent directory, so passing `import.meta.url` resolves correctly.
125
+ *
99
126
  * @example
100
127
  * ```ts
101
128
  * import { discoverPackageJson } from '@kjanat/dreamcli';
@@ -106,8 +133,11 @@ function joinPath(base: string, segment: string): string {
106
133
  * }
107
134
  * ```
108
135
  */
109
- async function discoverPackageJson(adapter: PackageJsonAdapter): Promise<PackageJsonData | null> {
110
- let dir: string | undefined = adapter.cwd;
136
+ async function discoverPackageJson(
137
+ adapter: PackageJsonAdapter,
138
+ startDir?: string,
139
+ ): Promise<PackageJsonData | null> {
140
+ let dir: string | undefined = startDir ?? adapter.cwd;
111
141
 
112
142
  while (dir !== undefined) {
113
143
  let content: string | null = null;
@@ -149,11 +179,15 @@ function parsePackageJson(content: string): PackageJsonData | null {
149
179
  const description =
150
180
  typeof parsed['description'] === 'string' ? parsed['description'] : undefined;
151
181
  const bin = parseBinField(parsed['bin']);
182
+ const homepage = typeof parsed['homepage'] === 'string' ? parsed['homepage'] : undefined;
183
+ const repository = parseRepositoryField(parsed['repository']);
152
184
  return {
153
185
  ...(name !== undefined ? { name } : {}),
154
186
  ...(version !== undefined ? { version } : {}),
155
187
  ...(description !== undefined ? { description } : {}),
156
188
  ...(bin !== undefined ? { bin } : {}),
189
+ ...(homepage !== undefined ? { homepage } : {}),
190
+ ...(repository !== undefined ? { repository } : {}),
157
191
  };
158
192
  } catch {
159
193
  return null;
@@ -180,6 +214,102 @@ function parseBinField(value: unknown): string | Readonly<Record<string, string>
180
214
  return result;
181
215
  }
182
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
+
183
313
  // --- inferCliName
184
314
 
185
315
  /**
@@ -216,5 +346,5 @@ function inferCliName(pkg: PackageJsonData): string | undefined {
216
346
 
217
347
  // --- Exports
218
348
 
219
- export type { PackageJsonAdapter, PackageJsonData };
220
- export { discoverPackageJson, inferCliName };
349
+ export type { PackageJsonAdapter, PackageJsonData, PackageRepository };
350
+ export { discoverPackageJson, inferCliName, packageRepositoryUrl };
@@ -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 };
@@ -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,
@@ -21,3 +21,7 @@ declare module 'node:readline' {
21
21
  declare module 'node:fs/promises' {
22
22
  function readFile(path: string | URL, encoding: 'utf8'): Promise<string>;
23
23
  }
24
+
25
+ declare module 'node:url' {
26
+ function fileURLToPath(url: string | URL): string;
27
+ }