@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.
@@ -1,8 +1,7 @@
1
- import{getFlagAliasNames as e}from"../schema/flag.mjs";import{formatDisplayValue as t}from"../output/display-value.mjs";function n(e){return{width:e?.width??80,binName:e?.binName,isDefaultHelp:e?.isDefaultHelp??!1}}function r(e,t){return e.length>=t?e:e+` `.repeat(t-e.length)}function i(e,t,n){if(e.length+n<=t)return e;let r=t-n;if(r<=0)return e;let i=e.split(` `),a=[],o=``;for(let e of i)o.length===0?o=e:o.length+1+e.length<=r?o+=` ${e}`:(a.push(o),o=e);o.length>0&&a.push(o);let s=` `.repeat(n);return a.map((e,t)=>t===0?e:`${s}${e}`).join(`
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 n=[`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)n.push(e);else{let o=r(e,s),c=i(a,t.width,s);n.push(`${o}${c}`)}return n.join(`
5
- `)}function _(e,t){let n=[`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)n.push(a);else{let o=r(a,s),c=i(e.description,t.width,s);n.push(`${o}${c}`)}}return n.join(`
6
- `)}function v(e,t){let n=[`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)n.push(e);else{let a=r(e,o),c=i(s,t.width,o);n.push(`${a}${c}`)}}return n.join(`
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{formatHelp as h}from"./core/help/index.mjs";import{parse as g,tokenize as _}from"./core/parse/index.mjs";import{createTerminalPrompter as v,resolvePromptConfig as y}from"./core/prompt/index.mjs";import{resolve as b}from"./core/resolve/index.mjs";import{createOutput as x}from"./core/output/index.mjs";import{ArgBuilder as S,arg as C,createArgSchema as w}from"./core/schema/arg.mjs";import{CommandBuilder as T,command as E,group as D}from"./core/schema/command.mjs";import{plugin as O}from"./core/cli/plugin.mjs";import{discoverPackageJson as k,inferCliName as A}from"./core/config/package-json.mjs";import{buildConfigSearchPaths as j,configFormat as M,discoverConfig as N}from"./core/config/index.mjs";import{CLIBuilder as P,cli as F}from"./core/cli/index.mjs";import{definitionMetaSchema as I,generateInputSchema as L,generateSchema as R}from"./core/json-schema/index.mjs";import{middleware as z}from"./core/schema/middleware.mjs";export{S as ArgBuilder,P as CLIBuilder,o as CLIError,T as CommandBuilder,e as FlagBuilder,s as ParseError,p as SHELLS,c as ValidationError,C as arg,j as buildConfigSearchPaths,F as cli,E as command,M as configFormat,w as createArgSchema,x as createOutput,t as createSchema,v as createTerminalPrompter,I as definitionMetaSchema,N as discoverConfig,k as discoverPackageJson,n as flag,h as formatHelp,r as generateBashCompletion,m as generateCompletion,i as generateFishCompletion,L as generateInputSchema,a as generatePowerShellCompletion,R as generateSchema,f as generateZshCompletion,D as group,A as inferCliName,l as isCLIError,u as isParseError,d as isValidationError,z as middleware,g as parse,O as plugin,b as resolve,y as resolvePromptConfig,_ as tokenize};
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.0`,t=`763e386`;export{t as DREAMCLI_REVISION,e as DREAMCLI_VERSION};
1
+ const e=`2.2.1`,t=`b084f93`;export{t as DREAMCLI_REVISION,e as DREAMCLI_VERSION};
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kjanat/dreamcli",
3
- "version": "2.1.0",
3
+ "version": "2.2.1",
4
4
  "description": "Schema-first, fully typed TypeScript CLI framework",
5
5
  "keywords": [
6
6
  "cli",
@@ -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 };
@@ -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. Pass `{ inferName: true }` to
443
- * also infer the CLI name from `bin` keys or the package `name` field.
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: settings?.inferName ?? false,
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 };