@kjanat/dreamcli 2.2.0 → 2.3.0
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 +43 -1
- package/dist/core/cli/dispatch.d.mts +30 -2
- package/dist/core/cli/dispatch.mjs +1 -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/planner.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/execution/index.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/core/parse/index.d.mts +31 -1
- package/dist/core/parse/index.mjs +1 -1
- package/dist/index.d.mts +4 -2
- package/dist/index.mjs +1 -1
- package/dist/version.mjs +1 -1
- package/package.json +5 -2
- package/src/core/cli/dispatch.ts +70 -7
- package/src/core/cli/help-links.ts +82 -0
- package/src/core/cli/index.ts +104 -6
- package/src/core/cli/planner.ts +23 -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/execution/index.ts +1 -9
- package/src/core/help/ansi.ts +144 -0
- package/src/core/help/index.ts +9 -50
- package/src/core/parse/index.ts +21 -1
- package/src/index.ts +4 -1
package/src/core/cli/planner.ts
CHANGED
|
@@ -12,6 +12,7 @@
|
|
|
12
12
|
|
|
13
13
|
import { CLIError, ParseError } from '#internals/core/errors/index.ts';
|
|
14
14
|
import type { HelpOptions } from '#internals/core/help/index.ts';
|
|
15
|
+
import { buildFlagLookup, includesBeforeSeparator } from '#internals/core/parse/index.ts';
|
|
15
16
|
import type { OutputPolicy } from '#internals/core/output/contracts.ts';
|
|
16
17
|
import type { CommandMeta, CommandSchema, ErasedCommand } from '#internals/core/schema/command.ts';
|
|
17
18
|
import { dispatch, findClosestCommand } from './dispatch.ts';
|
|
@@ -257,13 +258,20 @@ function buildPlannerMatchOutcome(
|
|
|
257
258
|
* @internal
|
|
258
259
|
*/
|
|
259
260
|
function planInvocation(options: PlanInvocationOptions): InvocationPlan {
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
261
|
+
// `--json` is a root-level flag, not part of any command schema, so it is
|
|
262
|
+
// stripped before dispatch/parse — but only before the `--` separator, so a
|
|
263
|
+
// literal `--json` positional (after `--`) survives and reaches the command
|
|
264
|
+
// (#28). The `--json` *output mode* is detected separately in `.execute()`.
|
|
265
|
+
const separatorIndex = options.argv.indexOf('--');
|
|
266
|
+
const head = separatorIndex === -1 ? options.argv : options.argv.slice(0, separatorIndex);
|
|
267
|
+
const tail = separatorIndex === -1 ? [] : options.argv.slice(separatorIndex);
|
|
268
|
+
const filteredHead = head.includes('--json') ? head.filter((arg) => arg !== '--json') : head;
|
|
269
|
+
const filteredArgv = separatorIndex === -1 ? filteredHead : [...filteredHead, ...tail];
|
|
263
270
|
|
|
264
271
|
if (
|
|
265
272
|
options.schema.version !== undefined &&
|
|
266
|
-
(
|
|
273
|
+
(includesBeforeSeparator(options.argv, '--version') ||
|
|
274
|
+
includesBeforeSeparator(options.argv, '-V'))
|
|
267
275
|
) {
|
|
268
276
|
return {
|
|
269
277
|
kind: 'root-version',
|
|
@@ -316,8 +324,18 @@ function planInvocation(options: PlanInvocationOptions): InvocationPlan {
|
|
|
316
324
|
};
|
|
317
325
|
}
|
|
318
326
|
|
|
319
|
-
const result = dispatch(filteredArgv, buildRootCommandMap(options.schema.commands));
|
|
320
327
|
const defaultCommand = options.schema.defaultCommand;
|
|
328
|
+
// At the root, a default command's flags govern value-flag arity so a
|
|
329
|
+
// space-separated value (`mycli --region eu`) is not misread as a command
|
|
330
|
+
// name and stolen from the default-command fallback (see #25).
|
|
331
|
+
const rootValueFlags =
|
|
332
|
+
defaultCommand !== undefined ? buildFlagLookup(defaultCommand.schema.flags) : undefined;
|
|
333
|
+
const result = dispatch(
|
|
334
|
+
filteredArgv,
|
|
335
|
+
buildRootCommandMap(options.schema.commands),
|
|
336
|
+
[],
|
|
337
|
+
rootValueFlags,
|
|
338
|
+
);
|
|
321
339
|
|
|
322
340
|
switch (result.kind) {
|
|
323
341
|
case 'unknown': {
|
|
@@ -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 };
|
|
@@ -16,7 +16,7 @@ import type {
|
|
|
16
16
|
import { CLIError } from '#internals/core/errors/index.ts';
|
|
17
17
|
import { formatHelp } from '#internals/core/help/index.ts';
|
|
18
18
|
import type { CapturedOutput } from '#internals/core/output/index.ts';
|
|
19
|
-
import { parse } from '#internals/core/parse/index.ts';
|
|
19
|
+
import { includesBeforeSeparator, parse } from '#internals/core/parse/index.ts';
|
|
20
20
|
import { createTestPrompter } from '#internals/core/prompt/index.ts';
|
|
21
21
|
import type { DeprecationWarning, ResolveOptions } from '#internals/core/resolve/index.ts';
|
|
22
22
|
import { resolve } from '#internals/core/resolve/index.ts';
|
|
@@ -258,13 +258,5 @@ function formatDeprecation(deprecation: DeprecationWarning): string {
|
|
|
258
258
|
: `Warning: ${entity} is deprecated`;
|
|
259
259
|
}
|
|
260
260
|
|
|
261
|
-
function includesBeforeSeparator(argv: readonly string[], token: string): boolean {
|
|
262
|
-
for (const arg of argv) {
|
|
263
|
-
if (arg === '--') return false;
|
|
264
|
-
if (arg === token) return true;
|
|
265
|
-
}
|
|
266
|
-
return false;
|
|
267
|
-
}
|
|
268
|
-
|
|
269
261
|
export type { CommandExecutionRequest, CommandExecutionResult };
|
|
270
262
|
export { buildRunResult, executeCommand };
|
|
@@ -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/core/parse/index.ts
CHANGED
|
@@ -101,6 +101,26 @@ function tokenize(argv: readonly string[]): readonly Token[] {
|
|
|
101
101
|
return tokens;
|
|
102
102
|
}
|
|
103
103
|
|
|
104
|
+
/**
|
|
105
|
+
* Whether `token` appears in argv before the `--` end-of-options separator.
|
|
106
|
+
*
|
|
107
|
+
* Everything at or after the first `--` is a literal positional, so root-level
|
|
108
|
+
* flag interception (`--help` / `--version` / `--json`) must use this instead of
|
|
109
|
+
* a naive `Array.includes()` — otherwise a post-separator literal (`-- --json`)
|
|
110
|
+
* is wrongly treated as the flag.
|
|
111
|
+
*
|
|
112
|
+
* @param argv - Raw argument strings.
|
|
113
|
+
* @param token - Exact flag token to look for (e.g. `--version`).
|
|
114
|
+
* @returns `true` if `token` occurs before any `--` separator.
|
|
115
|
+
*/
|
|
116
|
+
function includesBeforeSeparator(argv: readonly string[], token: string): boolean {
|
|
117
|
+
for (const arg of argv) {
|
|
118
|
+
if (arg === '--') return false;
|
|
119
|
+
if (arg === token) return true;
|
|
120
|
+
}
|
|
121
|
+
return false;
|
|
122
|
+
}
|
|
123
|
+
|
|
104
124
|
// --- Parse result
|
|
105
125
|
|
|
106
126
|
/**
|
|
@@ -658,4 +678,4 @@ function levenshtein(a: string, b: string): number {
|
|
|
658
678
|
// --- Exports
|
|
659
679
|
|
|
660
680
|
export type { ParseResult, Token };
|
|
661
|
-
export { parse, tokenize };
|
|
681
|
+
export { buildFlagLookup, flagExpectsValue, includesBeforeSeparator, parse, tokenize };
|