@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.
- package/CHANGELOG.md +47 -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 +118 -5
- 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 +8 -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 +48 -3
- 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 +235 -7
- package/src/core/cli/root-help.ts +36 -53
- package/src/core/cli/runtime-preflight.ts +13 -1
- package/src/core/config/index.ts +2 -2
- package/src/core/config/package-json.ts +135 -5
- package/src/core/help/ansi.ts +144 -0
- package/src/core/help/index.ts +9 -50
- package/src/index.ts +4 -1
- package/src/runtime/node-builtins.d.ts +4 -0
package/dist/core/help/index.mjs
CHANGED
|
@@ -1,8 +1,7 @@
|
|
|
1
|
-
import{getFlagAliasNames as e}from"../schema/flag.mjs";import{formatDisplayValue as t}from"../output/display-value.mjs";function
|
|
2
|
-
`)}function a(e){return typeof e==`string`?`[deprecated: ${e}]`:`[deprecated]`}function o(e){return e===void 0?`undefined`:e===null?`null`:t(e)}function s(t,n){let r=e(n,{kind:`short`}),i=e(n,{kind:`long`}),a=[...r.map(e=>`-${e}`),`--${t}`,...i.map(e=>`--${e}`)];return n.kind===`boolean`?a.join(`, `):`${a.join(`, `)} ${c(n)}`}function c(e){switch(e.kind){case`string`:return`<string>`;case`number`:return`<number>`;case`enum`:return`<${(e.enumValues??[]).join(`|`)}>`;case`array`:return`<${e.elementSchema===void 0?`value`:c(e.elementSchema).slice(1,-1)}>...`;case`boolean`:return``;case`custom`:return`<value>`}}function l(e){let t=[];return e.description!==void 0&&t.push(e.description),e.deprecated!==void 0&&t.push(a(e.deprecated)),e.envVar!==void 0&&t.push(`[env: ${e.envVar}]`),e.configPath!==void 0&&t.push(`[config: ${e.configPath}]`),e.prompt!==void 0&&t.push(`[prompt]`),e.presence===`required`?t.push(`[required]`):e.presence===`defaulted`&&e.kind!==`boolean`&&t.push(`(default: ${o(e.defaultValue)})`),t.join(` `)}function u(t){let n=Object.keys(t);if(n.length===0)return[];let r=[...n].sort((n,r)=>{let i=t[n],a=t[r];if(i===void 0||a===void 0)return 0;let o=e(i,{kind:`short`}).length>0,s=e(a,{kind:`short`}).length>0;return o&&!s?-1:!o&&s?1:n.localeCompare(r)}),i=[];for(let e of r){let n=t[e];n!==void 0&&i.push({left:s(e,n),description:l(n)})}return i}function d(e){let{name:t,schema:n}=e,r=n.kind===`enum`&&n.enumValues!==void 0?n.enumValues.join(`|`):t,i=n.variadic?`...`:``;return n.presence===`required`?`<${r}>${i}`:`[${r}]${i}`}function f(e){let t=[];return e.description!==void 0&&t.push(e.description),e.deprecated!==void 0&&t.push(a(e.deprecated)),e.envVar!==void 0&&t.push(`[env: ${e.envVar}]`),e.presence===`defaulted`&&t.push(`(default: ${o(e.defaultValue)})`),t.join(` `)}function p(e,t){let r=n(t),i=[];i.push(h(e,r)),e.description!==void 0&&i.push(e.description);let a=e.commands.filter(e=>!e.hidden);return a.length>0&&i.push(v(a,r)),e.args.length>0&&i.push(g(e.args,r)),Object.keys(e.flags).length>0&&i.push(_(e.flags,r)),e.examples.length>0&&i.push(y(e.examples)),i}function m(e,t){return`${p(e,t).join(`
|
|
1
|
+
import{getFlagAliasNames as e}from"../schema/flag.mjs";import{formatDisplayValue as t}from"../output/display-value.mjs";import{padEnd as n,wrapText as r}from"./ansi.mjs";function i(e){return{width:e?.width??80,binName:e?.binName,isDefaultHelp:e?.isDefaultHelp??!1}}function a(e){return typeof e==`string`?`[deprecated: ${e}]`:`[deprecated]`}function o(e){return e===void 0?`undefined`:e===null?`null`:t(e)}function s(t,n){let r=e(n,{kind:`short`}),i=e(n,{kind:`long`}),a=[...r.map(e=>`-${e}`),`--${t}`,...i.map(e=>`--${e}`)];return n.kind===`boolean`?a.join(`, `):`${a.join(`, `)} ${c(n)}`}function c(e){switch(e.kind){case`string`:return`<string>`;case`number`:return`<number>`;case`enum`:return`<${(e.enumValues??[]).join(`|`)}>`;case`array`:return`<${e.elementSchema===void 0?`value`:c(e.elementSchema).slice(1,-1)}>...`;case`boolean`:return``;case`custom`:return`<value>`}}function l(e){let t=[];return e.description!==void 0&&t.push(e.description),e.deprecated!==void 0&&t.push(a(e.deprecated)),e.envVar!==void 0&&t.push(`[env: ${e.envVar}]`),e.configPath!==void 0&&t.push(`[config: ${e.configPath}]`),e.prompt!==void 0&&t.push(`[prompt]`),e.presence===`required`?t.push(`[required]`):e.presence===`defaulted`&&e.kind!==`boolean`&&t.push(`(default: ${o(e.defaultValue)})`),t.join(` `)}function u(t){let n=Object.keys(t);if(n.length===0)return[];let r=[...n].sort((n,r)=>{let i=t[n],a=t[r];if(i===void 0||a===void 0)return 0;let o=e(i,{kind:`short`}).length>0,s=e(a,{kind:`short`}).length>0;return o&&!s?-1:!o&&s?1:n.localeCompare(r)}),i=[];for(let e of r){let n=t[e];n!==void 0&&i.push({left:s(e,n),description:l(n)})}return i}function d(e){let{name:t,schema:n}=e,r=n.kind===`enum`&&n.enumValues!==void 0?n.enumValues.join(`|`):t,i=n.variadic?`...`:``;return n.presence===`required`?`<${r}>${i}`:`[${r}]${i}`}function f(e){let t=[];return e.description!==void 0&&t.push(e.description),e.deprecated!==void 0&&t.push(a(e.deprecated)),e.envVar!==void 0&&t.push(`[env: ${e.envVar}]`),e.presence===`defaulted`&&t.push(`(default: ${o(e.defaultValue)})`),t.join(` `)}function p(e,t){let n=i(t),r=[];r.push(h(e,n)),e.description!==void 0&&r.push(e.description);let a=e.commands.filter(e=>!e.hidden);return a.length>0&&r.push(v(a,n)),e.args.length>0&&r.push(g(e.args,n)),Object.keys(e.flags).length>0&&r.push(_(e.flags,n)),e.examples.length>0&&r.push(y(e.examples)),r}function m(e,t){return`${p(e,t).join(`
|
|
3
2
|
|
|
4
|
-
`)}\n`}function h(e,t){let n=[`Usage:`],r=t.binName===void 0||t.isDefaultHelp&&t.binName===e.name?e.name:`${t.binName} ${e.name}`;n.push(r),e.commands.length>0&&n.push(`<command>`),Object.keys(e.flags).length>0&&n.push(`[flags]`);for(let t of e.args)n.push(d(t));return n.join(` `)}function g(e,t){let
|
|
5
|
-
`)}function _(e,t){let
|
|
6
|
-
`)}function v(e,t){let
|
|
3
|
+
`)}\n`}function h(e,t){let n=[`Usage:`],r=t.binName===void 0||t.isDefaultHelp&&t.binName===e.name?e.name:`${t.binName} ${e.name}`;n.push(r),e.commands.length>0&&n.push(`<command>`),Object.keys(e.flags).length>0&&n.push(`[flags]`);for(let t of e.args)n.push(d(t));return n.join(` `)}function g(e,t){let i=[`Arguments:`],a=0,o=[];for(let t of e){let e=` ${d(t)}`,n=f(t.schema);o.push({left:e,desc:n}),e.length>a&&(a=e.length)}let s=a+2;for(let{left:e,desc:a}of o)if(a.length===0)i.push(e);else{let o=n(e,s),c=r(a,t.width,s);i.push(`${o}${c}`)}return i.join(`
|
|
4
|
+
`)}function _(e,t){let i=[`Flags:`],a=u(e);if(a.length===0)return``;let o=0;for(let e of a){let t=` ${e.left}`;t.length>o&&(o=t.length)}let s=o+2;for(let e of a){let a=` ${e.left}`;if(e.description.length===0)i.push(a);else{let o=n(a,s),c=r(e.description,t.width,s);i.push(`${o}${c}`)}}return i.join(`
|
|
5
|
+
`)}function v(e,t){let i=[`Commands:`],a=0;for(let t of e)t.name.length>a&&(a=t.name.length);let o=2+a+2;for(let a of e){let e=` ${a.name}`,s=a.description??``;if(s.length===0)i.push(e);else{let a=n(e,o),c=r(s,t.width,o);i.push(`${a}${c}`)}}return i.join(`
|
|
7
6
|
`)}function y(e){let t=[`Examples:`];for(let n of e)n.description===void 0?t.push(` $ ${n.command}`):(t.push(` ${n.description}:`),t.push(` $ ${n.command}`));return t.join(`
|
|
8
7
|
`)}export{m as formatHelp,p as formatHelpSections};
|
package/dist/index.d.mts
CHANGED
|
@@ -12,17 +12,19 @@ import { DeprecationWarning, ResolveOptions, ResolveResult } from "./core/resolv
|
|
|
12
12
|
import { resolve } from "./core/resolve/index.mjs";
|
|
13
13
|
import { BeforeParseParams, CLIPlugin, CLIPluginHooks, PluginCommandContext, ResolvedCommandParams, plugin } from "./core/cli/plugin.mjs";
|
|
14
14
|
import { CLIError, CLIErrorJSON, CLIErrorOptions, ErrorCode, ParseError, ParseErrorCode, ParseErrorOptions, ValidationError, ValidationErrorCode, ValidationErrorOptions, isCLIError, isParseError, isValidationError } from "./core/errors/index.mjs";
|
|
15
|
+
import { osc8, visibleWidth } from "./core/help/ansi.mjs";
|
|
15
16
|
import { HelpOptions, formatHelp } from "./core/help/index.mjs";
|
|
16
17
|
import { RunResult } from "./core/schema/run.mjs";
|
|
17
18
|
import { ActionHandler, ActionParams, AnyCommandBuilder, CommandArgEntry, CommandBuilder, CommandConfig, CommandExample, CommandMeta, CommandSchema, DeriveHandler, DeriveParams, InteractiveParams, InteractiveResolver, InteractiveResult, Out, command, group } from "./core/schema/command.mjs";
|
|
19
|
+
import { PackageJsonAdapter, PackageJsonData, PackageRepository, discoverPackageJson, inferCliName, packageRepositoryUrl } from "./core/config/package-json.mjs";
|
|
20
|
+
import { HelpLinks } from "./core/cli/help-links.mjs";
|
|
18
21
|
import { CompletionOptions } from "./core/completion/shells/shared.mjs";
|
|
19
22
|
import { generateBashCompletion } from "./core/completion/shells/bash.mjs";
|
|
20
23
|
import { generateFishCompletion } from "./core/completion/shells/fish.mjs";
|
|
21
24
|
import { generatePowerShellCompletion } from "./core/completion/shells/powershell.mjs";
|
|
22
25
|
import { generateZshCompletion } from "./core/completion/shells/zsh.mjs";
|
|
23
26
|
import { SHELLS, Shell, generateCompletion } from "./core/completion/index.mjs";
|
|
24
|
-
import { PackageJsonAdapter, PackageJsonData, discoverPackageJson, inferCliName } from "./core/config/package-json.mjs";
|
|
25
27
|
import { ConfigAdapter, ConfigDiscoveryOptions, ConfigDiscoveryResult, ConfigFound, ConfigNotFound, FormatLoader, buildConfigSearchPaths, configFormat, discoverConfig } from "./core/config/index.mjs";
|
|
26
28
|
import { CLIBuilder, CLIOptions, CLIRunOptions, CLISchema, ConfigSettings, PackageJsonSettings, cli } from "./core/cli/index.mjs";
|
|
27
29
|
import { JsonSchemaOptions, definitionMetaSchema, generateInputSchema, generateSchema } from "./core/json-schema/index.mjs";
|
|
28
|
-
export { type ActionHandler, type ActionParams, type ActivityEvent, type AnyCommandBuilder, ArgBuilder, type ArgConfig, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type BeforeParseParams, CLIBuilder, CLIError, type CLIErrorJSON, type CLIErrorOptions, type CLIOptions, type CLIPlugin, type CLIPluginHooks, type CLIRunOptions, type CLISchema, type CommandArgEntry, CommandBuilder, type CommandConfig, type CommandExample, type CommandMeta, type CommandSchema, type CompletionOptions, type ConfigAdapter, type ConfigDiscoveryOptions, type ConfigDiscoveryResult, type ConfigFound, type ConfigNotFound, type ConfigSettings, type ConfirmPromptConfig, type DeprecationWarning, type DeriveHandler, type DeriveParams, type ErrorCode, type Fallback, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagParseFn, type FlagPresence, type FlagSchema, type FormatLoader, type HelpOptions, type InferArg, type InferArgs, type InferFlag, type InferFlags, type InputPromptConfig, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type JsonSchemaOptions, type Middleware, type MiddlewareHandler, type MiddlewareParams, type MultiselectPromptConfig, type Out, type OutputOptions, type PackageJsonAdapter, type PackageJsonData, type PackageJsonSettings, ParseError, type ParseErrorCode, type ParseErrorOptions, type ParseResult, type PluginCommandContext, type ProgressHandle, type ProgressOptions, type PromptConfig, type PromptConfigBase, type PromptEngine, type PromptKind, type PromptResult, type ReadFn, type ResolveOptions, type ResolveResult, type ResolvedArgValue, type ResolvedCommandParams, type ResolvedMultiselectPromptConfig, type ResolvedPromptConfig, type ResolvedSelectPromptConfig, type ResolvedValue, type RunResult, SHELLS, type SelectChoice, type SelectPromptConfig, type Shell, type SpinnerHandle, type SpinnerOptions, type TableColumn, type TableFormat, type TableOptions, type TableStream, type Token, ValidationError, type ValidationErrorCode, type ValidationErrorOptions, type Verbosity, type WithArgPresence, type WithPresence, type WithVariadic, type WriteFn, arg, buildConfigSearchPaths, cli, command, configFormat, createArgSchema, createOutput, createSchema, createTerminalPrompter, definitionMetaSchema, discoverConfig, discoverPackageJson, flag, formatHelp, generateBashCompletion, generateCompletion, generateFishCompletion, generateInputSchema, generatePowerShellCompletion, generateSchema, generateZshCompletion, group, inferCliName, isCLIError, isParseError, isValidationError, middleware, parse, plugin, resolve, resolvePromptConfig, tokenize };
|
|
30
|
+
export { type ActionHandler, type ActionParams, type ActivityEvent, type AnyCommandBuilder, ArgBuilder, type ArgConfig, type ArgFactory, type ArgKind, type ArgParseFn, type ArgPresence, type ArgSchema, type BeforeParseParams, CLIBuilder, CLIError, type CLIErrorJSON, type CLIErrorOptions, type CLIOptions, type CLIPlugin, type CLIPluginHooks, type CLIRunOptions, type CLISchema, type CommandArgEntry, CommandBuilder, type CommandConfig, type CommandExample, type CommandMeta, type CommandSchema, type CompletionOptions, type ConfigAdapter, type ConfigDiscoveryOptions, type ConfigDiscoveryResult, type ConfigFound, type ConfigNotFound, type ConfigSettings, type ConfirmPromptConfig, type DeprecationWarning, type DeriveHandler, type DeriveParams, type ErrorCode, type Fallback, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagParseFn, type FlagPresence, type FlagSchema, type FormatLoader, type HelpLinks, type HelpOptions, type InferArg, type InferArgs, type InferFlag, type InferFlags, type InputPromptConfig, type InteractiveParams, type InteractiveResolver, type InteractiveResult, type JsonSchemaOptions, type Middleware, type MiddlewareHandler, type MiddlewareParams, type MultiselectPromptConfig, type Out, type OutputOptions, type PackageJsonAdapter, type PackageJsonData, type PackageJsonSettings, type PackageRepository, ParseError, type ParseErrorCode, type ParseErrorOptions, type ParseResult, type PluginCommandContext, type ProgressHandle, type ProgressOptions, type PromptConfig, type PromptConfigBase, type PromptEngine, type PromptKind, type PromptResult, type ReadFn, type ResolveOptions, type ResolveResult, type ResolvedArgValue, type ResolvedCommandParams, type ResolvedMultiselectPromptConfig, type ResolvedPromptConfig, type ResolvedSelectPromptConfig, type ResolvedValue, type RunResult, SHELLS, type SelectChoice, type SelectPromptConfig, type Shell, type SpinnerHandle, type SpinnerOptions, type TableColumn, type TableFormat, type TableOptions, type TableStream, type Token, ValidationError, type ValidationErrorCode, type ValidationErrorOptions, type Verbosity, type WithArgPresence, type WithPresence, type WithVariadic, type WriteFn, arg, buildConfigSearchPaths, cli, command, configFormat, createArgSchema, createOutput, createSchema, createTerminalPrompter, definitionMetaSchema, discoverConfig, discoverPackageJson, flag, formatHelp, generateBashCompletion, generateCompletion, generateFishCompletion, generateInputSchema, generatePowerShellCompletion, generateSchema, generateZshCompletion, group, inferCliName, isCLIError, isParseError, isValidationError, middleware, osc8, packageRepositoryUrl, parse, plugin, resolve, resolvePromptConfig, tokenize, visibleWidth };
|
package/dist/index.mjs
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
import{FlagBuilder as e,createSchema as t,flag as n}from"./core/schema/flag.mjs";import{generateBashCompletion as r}from"./core/completion/shells/bash.mjs";import{generateFishCompletion as i}from"./core/completion/shells/fish.mjs";import{generatePowerShellCompletion as a}from"./core/completion/shells/powershell.mjs";import{CLIError as o,ParseError as s,ValidationError as c,isCLIError as l,isParseError as u,isValidationError as d}from"./core/errors/index.mjs";import{generateZshCompletion as f}from"./core/completion/shells/zsh.mjs";import{SHELLS as p,generateCompletion as m}from"./core/completion/index.mjs";import{
|
|
1
|
+
import{FlagBuilder as e,createSchema as t,flag as n}from"./core/schema/flag.mjs";import{generateBashCompletion as r}from"./core/completion/shells/bash.mjs";import{generateFishCompletion as i}from"./core/completion/shells/fish.mjs";import{generatePowerShellCompletion as a}from"./core/completion/shells/powershell.mjs";import{CLIError as o,ParseError as s,ValidationError as c,isCLIError as l,isParseError as u,isValidationError as d}from"./core/errors/index.mjs";import{generateZshCompletion as f}from"./core/completion/shells/zsh.mjs";import{SHELLS as p,generateCompletion as m}from"./core/completion/index.mjs";import{osc8 as h,visibleWidth as g}from"./core/help/ansi.mjs";import{formatHelp as _}from"./core/help/index.mjs";import{parse as v,tokenize as y}from"./core/parse/index.mjs";import{createTerminalPrompter as b,resolvePromptConfig as x}from"./core/prompt/index.mjs";import{resolve as S}from"./core/resolve/index.mjs";import{createOutput as C}from"./core/output/index.mjs";import{ArgBuilder as w,arg as T,createArgSchema as E}from"./core/schema/arg.mjs";import{CommandBuilder as D,command as O,group as k}from"./core/schema/command.mjs";import{discoverPackageJson as A,inferCliName as j,packageRepositoryUrl as M}from"./core/config/package-json.mjs";import{plugin as N}from"./core/cli/plugin.mjs";import{buildConfigSearchPaths as P,configFormat as F,discoverConfig as I}from"./core/config/index.mjs";import{CLIBuilder as L,cli as R}from"./core/cli/index.mjs";import{definitionMetaSchema as z,generateInputSchema as B,generateSchema as V}from"./core/json-schema/index.mjs";import{middleware as H}from"./core/schema/middleware.mjs";export{w as ArgBuilder,L as CLIBuilder,o as CLIError,D as CommandBuilder,e as FlagBuilder,s as ParseError,p as SHELLS,c as ValidationError,T as arg,P as buildConfigSearchPaths,R as cli,O as command,F as configFormat,E as createArgSchema,C as createOutput,t as createSchema,b as createTerminalPrompter,z as definitionMetaSchema,I as discoverConfig,A as discoverPackageJson,n as flag,_ as formatHelp,r as generateBashCompletion,m as generateCompletion,i as generateFishCompletion,B as generateInputSchema,a as generatePowerShellCompletion,V as generateSchema,f as generateZshCompletion,k as group,j as inferCliName,l as isCLIError,u as isParseError,d as isValidationError,H as middleware,h as osc8,M as packageRepositoryUrl,v as parse,N as plugin,S as resolve,x as resolvePromptConfig,y as tokenize,g as visibleWidth};
|
package/dist/version.mjs
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
const e=`2.1
|
|
1
|
+
const e=`2.2.1`,t=`b084f93`;export{t as DREAMCLI_REVISION,e as DREAMCLI_VERSION};
|
package/package.json
CHANGED
|
@@ -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
|
@@ -12,6 +12,7 @@
|
|
|
12
12
|
import type { CompletionOptions, Shell } from '#internals/core/completion/index.ts';
|
|
13
13
|
import { generateCompletion, SHELLS } from '#internals/core/completion/index.ts';
|
|
14
14
|
import type { FormatLoader } from '#internals/core/config/index.ts';
|
|
15
|
+
import type { PackageJsonData } from '#internals/core/config/package-json.ts';
|
|
15
16
|
import { CLIError } from '#internals/core/errors/index.ts';
|
|
16
17
|
import { buildRunResult, executeCommand } from '#internals/core/execution/index.ts';
|
|
17
18
|
import type { HelpOptions } from '#internals/core/help/index.ts';
|
|
@@ -34,6 +35,8 @@ import type { RunOptions, RunResult } from '#internals/core/schema/run.ts';
|
|
|
34
35
|
import { runCommand } from '#internals/core/testkit/index.ts';
|
|
35
36
|
import type { RuntimeAdapter } from '#internals/runtime/adapter.ts';
|
|
36
37
|
import { createAdapter } from '#internals/runtime/auto.ts';
|
|
38
|
+
import type { HelpLinks } from './help-links.ts';
|
|
39
|
+
import { deriveHelpLinks } from './help-links.ts';
|
|
37
40
|
import type { OutputPolicy } from './planner.ts';
|
|
38
41
|
import { planInvocation } from './planner.ts';
|
|
39
42
|
import type { CLIPlugin } from './plugin.ts';
|
|
@@ -184,6 +187,14 @@ interface CLISchema {
|
|
|
184
187
|
* Set via the {@linkcode CLIBuilder.packageJson | .packageJson()} builder method.
|
|
185
188
|
*/
|
|
186
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;
|
|
187
198
|
/** Whether built-in `.completions()` command registration is active. */
|
|
188
199
|
readonly hasBuiltInCompletions: boolean;
|
|
189
200
|
/** Registered CLI plugins. */
|
|
@@ -228,6 +239,26 @@ interface PackageJsonSettings {
|
|
|
228
239
|
* @defaultValue `false`
|
|
229
240
|
*/
|
|
230
241
|
readonly inferName: boolean;
|
|
242
|
+
/**
|
|
243
|
+
* Explicit filesystem anchor for discovery; overrides `adapter.cwd`.
|
|
244
|
+
*
|
|
245
|
+
* Resolved to a string path before storage. When set, `discoverPackageJson`
|
|
246
|
+
* walks up from here instead of the runtime cwd. Required for installable
|
|
247
|
+
* CLIs whose version should reflect THEIR OWN package, not the consumer's
|
|
248
|
+
* working directory.
|
|
249
|
+
*/
|
|
250
|
+
readonly from: string | undefined;
|
|
251
|
+
/**
|
|
252
|
+
* Pre-loaded data; skips filesystem discovery, uses values verbatim.
|
|
253
|
+
*
|
|
254
|
+
* @example
|
|
255
|
+
* ```ts
|
|
256
|
+
* import pkg from './package.json' with { type: 'json' };
|
|
257
|
+
*
|
|
258
|
+
* cli('mycli').packageJson(pkg);
|
|
259
|
+
* ```
|
|
260
|
+
*/
|
|
261
|
+
readonly data: PackageJsonData | undefined;
|
|
231
262
|
}
|
|
232
263
|
|
|
233
264
|
// --- Options for execute/run
|
|
@@ -343,6 +374,54 @@ class CLIBuilder {
|
|
|
343
374
|
return new CLIBuilder({ ...this.schema, description: text });
|
|
344
375
|
}
|
|
345
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
|
+
|
|
346
425
|
/**
|
|
347
426
|
* Enable automatic config file discovery.
|
|
348
427
|
*
|
|
@@ -429,6 +508,35 @@ class CLIBuilder {
|
|
|
429
508
|
});
|
|
430
509
|
}
|
|
431
510
|
|
|
511
|
+
/**
|
|
512
|
+
* Enable package.json metadata from pre-loaded data.
|
|
513
|
+
*
|
|
514
|
+
* Pass an already-imported `package.json` to skip filesystem discovery
|
|
515
|
+
* entirely — useful for bundled or installable CLIs where the version
|
|
516
|
+
* should be locked at build time. The data's `version`/`description` are
|
|
517
|
+
* merged into the CLI schema immediately, so this form works in **both**
|
|
518
|
+
* `.run()` and `.execute()` (the filesystem-free path). Explicit
|
|
519
|
+
* `.version()`/`.description()` calls still take precedence, and the data
|
|
520
|
+
* form does not infer the CLI name.
|
|
521
|
+
*
|
|
522
|
+
* Detected by field shape: an object carrying at least one of
|
|
523
|
+
* `name`/`version`/`description`/`bin`. An empty `{}` or a settings-shaped
|
|
524
|
+
* object falls through to the settings overload.
|
|
525
|
+
*
|
|
526
|
+
* @param data - Pre-loaded `package.json` metadata.
|
|
527
|
+
*
|
|
528
|
+
* @example
|
|
529
|
+
* ```ts
|
|
530
|
+
* import pkg from './package.json' with { type: 'json' };
|
|
531
|
+
*
|
|
532
|
+
* // No filesystem; works in .run() AND .execute():
|
|
533
|
+
* cli('mycli')
|
|
534
|
+
* .packageJson(pkg)
|
|
535
|
+
* .command(deploy)
|
|
536
|
+
* .run();
|
|
537
|
+
* ```
|
|
538
|
+
*/
|
|
539
|
+
packageJson(data: PackageJsonData): CLIBuilder;
|
|
432
540
|
/**
|
|
433
541
|
* Enable automatic package.json metadata discovery.
|
|
434
542
|
*
|
|
@@ -437,10 +545,15 @@ class CLIBuilder {
|
|
|
437
545
|
* into the CLI schema. Explicit `.version()` and `.description()`
|
|
438
546
|
* calls always take precedence over discovered values.
|
|
439
547
|
*
|
|
440
|
-
* Has no effect in `.execute()` (which is filesystem-free by design)
|
|
548
|
+
* Has no effect in `.execute()` (which is filesystem-free by design) —
|
|
549
|
+
* use the {@link CLIBuilder.packageJson | data overload} for that.
|
|
441
550
|
*
|
|
442
|
-
* @param settings - Optional settings
|
|
443
|
-
* also infer the CLI name from `bin` keys or
|
|
551
|
+
* @param settings - Optional settings:
|
|
552
|
+
* - `inferName`: also infer the CLI name from `bin` keys or `name` field.
|
|
553
|
+
* - `from`: anchor discovery to a specific file/URL/path instead of `cwd`.
|
|
554
|
+
* Pass `import.meta.url` for installable CLIs that need to report
|
|
555
|
+
* THEIR OWN version (not the consumer's project version). Accepts
|
|
556
|
+
* string paths, `file:` URL strings, or `URL` instances.
|
|
444
557
|
*
|
|
445
558
|
* @example
|
|
446
559
|
* ```ts
|
|
@@ -456,6 +569,12 @@ class CLIBuilder {
|
|
|
456
569
|
* .command(deploy)
|
|
457
570
|
* .run();
|
|
458
571
|
*
|
|
572
|
+
* // Installable CLI; discover OUR package.json, not the consumer's:
|
|
573
|
+
* cli('mycli')
|
|
574
|
+
* .packageJson({ from: import.meta.url })
|
|
575
|
+
* .command(deploy)
|
|
576
|
+
* .run();
|
|
577
|
+
*
|
|
459
578
|
* // Explicit values always win:
|
|
460
579
|
* cli('mycli')
|
|
461
580
|
* .packageJson()
|
|
@@ -463,11 +582,31 @@ class CLIBuilder {
|
|
|
463
582
|
* .run();
|
|
464
583
|
* ```
|
|
465
584
|
*/
|
|
466
|
-
packageJson(settings?: { readonly inferName?: boolean }): CLIBuilder
|
|
585
|
+
packageJson(settings?: { readonly inferName?: boolean; readonly from?: string | URL }): CLIBuilder;
|
|
586
|
+
packageJson(
|
|
587
|
+
input?: PackageJsonData | { readonly inferName?: boolean; readonly from?: string | URL },
|
|
588
|
+
): CLIBuilder {
|
|
589
|
+
if (isPackageJsonData(input)) {
|
|
590
|
+
// Merge data into schema immediately so `.execute()` (which skips
|
|
591
|
+
// runtime preflight) still picks up version/description. Explicit
|
|
592
|
+
// `.version()`/`.description()` calls win, matching settings semantics.
|
|
593
|
+
return new CLIBuilder({
|
|
594
|
+
...this.schema,
|
|
595
|
+
...(this.schema.version === undefined && input.version !== undefined
|
|
596
|
+
? { version: input.version }
|
|
597
|
+
: {}),
|
|
598
|
+
...(this.schema.description === undefined && input.description !== undefined
|
|
599
|
+
? { description: input.description }
|
|
600
|
+
: {}),
|
|
601
|
+
packageJsonSettings: { inferName: false, from: undefined, data: input },
|
|
602
|
+
});
|
|
603
|
+
}
|
|
467
604
|
return new CLIBuilder({
|
|
468
605
|
...this.schema,
|
|
469
606
|
packageJsonSettings: {
|
|
470
|
-
inferName:
|
|
607
|
+
inferName: input?.inferName ?? false,
|
|
608
|
+
from: normalizeFromSetting(input?.from),
|
|
609
|
+
data: undefined,
|
|
471
610
|
},
|
|
472
611
|
});
|
|
473
612
|
}
|
|
@@ -685,10 +824,12 @@ class CLIBuilder {
|
|
|
685
824
|
);
|
|
686
825
|
}
|
|
687
826
|
|
|
688
|
-
// 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)
|
|
689
829
|
const helpOptions: HelpOptions = {
|
|
690
830
|
...options?.help,
|
|
691
831
|
binName: options?.help?.binName ?? this.schema.name,
|
|
832
|
+
hyperlinks: options?.help?.hyperlinks ?? out.isTTY,
|
|
692
833
|
};
|
|
693
834
|
|
|
694
835
|
// -- Shared options for command execution ----------------------------------
|
|
@@ -715,7 +856,7 @@ class CLIBuilder {
|
|
|
715
856
|
return buildRunResult({ exitCode: 0, error: undefined }, captured);
|
|
716
857
|
|
|
717
858
|
case 'root-help': {
|
|
718
|
-
const helpText = formatRootHelp(this.schema, planned.help);
|
|
859
|
+
const helpText = formatRootHelp(resolveHelpLinksSchema(this.schema), planned.help);
|
|
719
860
|
out.log(helpText);
|
|
720
861
|
return buildRunResult({ exitCode: 0, error: undefined }, captured);
|
|
721
862
|
}
|
|
@@ -893,6 +1034,91 @@ function inferInvocationName(argv: readonly string[]): string | undefined {
|
|
|
893
1034
|
return argv0 !== undefined ? basename(argv0) : undefined;
|
|
894
1035
|
}
|
|
895
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
|
+
|
|
1063
|
+
// --- packageJson.from normalisation
|
|
1064
|
+
|
|
1065
|
+
/**
|
|
1066
|
+
* Coerce a {@link PackageJsonSettings.from | `packageJson.from`} input
|
|
1067
|
+
* (string path, `file:` URL string, or {@link URL} instance) to a plain
|
|
1068
|
+
* filesystem path string. `undefined` passes through unchanged.
|
|
1069
|
+
*
|
|
1070
|
+
* Runtime-agnostic by design — relies only on the `URL` global (available in
|
|
1071
|
+
* every JS runtime) rather than `node:url`, keeping core free of Node
|
|
1072
|
+
* built-ins. Non-`file:` inputs are returned unchanged as paths.
|
|
1073
|
+
*
|
|
1074
|
+
* @internal
|
|
1075
|
+
*/
|
|
1076
|
+
function normalizeFromSetting(from: string | URL | undefined): string | undefined {
|
|
1077
|
+
if (from === undefined) return undefined;
|
|
1078
|
+
if (from instanceof URL) {
|
|
1079
|
+
// Only file: URLs map to a filesystem path; pass others through verbatim.
|
|
1080
|
+
if (from.protocol !== 'file:') return from.href;
|
|
1081
|
+
} else if (!from.startsWith('file:')) {
|
|
1082
|
+
// Plain path (or non-file URL string) — already usable as-is.
|
|
1083
|
+
return from;
|
|
1084
|
+
}
|
|
1085
|
+
|
|
1086
|
+
/*
|
|
1087
|
+
* `URL.pathname` strips the `file://` scheme/authority; `decodeURIComponent`
|
|
1088
|
+
* resolves percent-escapes. A leading-slash drive letter (`/C:/…`) marks a
|
|
1089
|
+
* Windows path — drop the slash and switch to backslashes; otherwise it is a
|
|
1090
|
+
* POSIX path already.
|
|
1091
|
+
*/
|
|
1092
|
+
const decoded = decodeURIComponent(new URL(from).pathname);
|
|
1093
|
+
if (/^\/[A-Za-z]:/.test(decoded)) {
|
|
1094
|
+
return decoded.slice(1).replace(/\//g, '\\');
|
|
1095
|
+
}
|
|
1096
|
+
return decoded;
|
|
1097
|
+
}
|
|
1098
|
+
|
|
1099
|
+
/**
|
|
1100
|
+
* Predicate distinguishing the {@link PackageJsonData | data} overload of
|
|
1101
|
+
* `.packageJson()` from the settings overload at runtime.
|
|
1102
|
+
*
|
|
1103
|
+
* A value is treated as `PackageJsonData` when it's a plain object that
|
|
1104
|
+
* carries at least one recognised field (`name`, `version`, `description`,
|
|
1105
|
+
* `bin`, `homepage`, or `repository`). An empty `{}` or a settings-shaped
|
|
1106
|
+
* object (`inferName` / `from`) falls through to the settings overload.
|
|
1107
|
+
*
|
|
1108
|
+
* @internal
|
|
1109
|
+
*/
|
|
1110
|
+
function isPackageJsonData(value: unknown): value is PackageJsonData {
|
|
1111
|
+
if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
|
|
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
|
+
);
|
|
1120
|
+
}
|
|
1121
|
+
|
|
896
1122
|
// --- Factory function
|
|
897
1123
|
|
|
898
1124
|
/**
|
|
@@ -960,6 +1186,7 @@ function cli(nameOrOptions: string | CLIOptions): CLIBuilder {
|
|
|
960
1186
|
defaultCommand: undefined,
|
|
961
1187
|
configSettings: undefined,
|
|
962
1188
|
packageJsonSettings: undefined,
|
|
1189
|
+
helpLinks: undefined,
|
|
963
1190
|
hasBuiltInCompletions: false,
|
|
964
1191
|
plugins: [],
|
|
965
1192
|
});
|
|
@@ -974,5 +1201,6 @@ export type {
|
|
|
974
1201
|
PluginCommandContext,
|
|
975
1202
|
ResolvedCommandParams,
|
|
976
1203
|
} from './plugin.ts';
|
|
1204
|
+
export type { HelpLinks } from './help-links.ts';
|
|
977
1205
|
export type { CLIOptions, CLIRunOptions, CLISchema, ConfigSettings, PackageJsonSettings };
|
|
978
1206
|
export { CLIBuilder, cli, formatRootHelp, plugin };
|