@clerc/plugin-help 1.3.0-beta.1 → 1.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/dist/index.d.mts +7 -6
- package/dist/index.mjs +6 -6
- package/package.json +5 -5
package/dist/index.d.mts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { Plugin } from "@clerc/core";
|
|
2
|
+
import { MaybeAsyncGetter } from "@clerc/utils";
|
|
2
3
|
import { FlagDefaultValue, TypeValue } from "@clerc/parser";
|
|
3
4
|
|
|
4
5
|
//#region src/types.d.ts
|
|
@@ -51,12 +52,12 @@ interface CommandHelpOptions extends HelpOptions {
|
|
|
51
52
|
/**
|
|
52
53
|
* Notes to show in the help output.
|
|
53
54
|
*/
|
|
54
|
-
notes?: string[]
|
|
55
|
+
notes?: MaybeAsyncGetter<string[]>;
|
|
55
56
|
/**
|
|
56
57
|
* Examples to show in the help output. Each example is a tuple of `[command,
|
|
57
58
|
* description]`.
|
|
58
59
|
*/
|
|
59
|
-
examples?: [string, string][]
|
|
60
|
+
examples?: MaybeAsyncGetter<[string, string][]>;
|
|
60
61
|
}
|
|
61
62
|
interface FlagHelpOptions extends HelpOptions {}
|
|
62
63
|
declare module "@clerc/core" {
|
|
@@ -95,20 +96,20 @@ interface HelpPluginOptions {
|
|
|
95
96
|
/**
|
|
96
97
|
* Notes to show in the help output.
|
|
97
98
|
*/
|
|
98
|
-
notes?: string[]
|
|
99
|
+
notes?: MaybeAsyncGetter<string[]>;
|
|
99
100
|
/**
|
|
100
101
|
* Examples to show in the help output. Each example is a tuple of `[command,
|
|
101
102
|
* description]`.
|
|
102
103
|
*/
|
|
103
|
-
examples?: [string, string][]
|
|
104
|
+
examples?: MaybeAsyncGetter<[string, string][]>;
|
|
104
105
|
/**
|
|
105
106
|
* Header to show before the help output.
|
|
106
107
|
*/
|
|
107
|
-
header?: string
|
|
108
|
+
header?: MaybeAsyncGetter<string | undefined>;
|
|
108
109
|
/**
|
|
109
110
|
* Footer to show after the help output.
|
|
110
111
|
*/
|
|
111
|
-
footer?: string
|
|
112
|
+
footer?: MaybeAsyncGetter<string | undefined>;
|
|
112
113
|
/**
|
|
113
114
|
* Custom formatters for rendering help.
|
|
114
115
|
*/
|
package/dist/index.mjs
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
import{DOUBLE_DASH as e,NoSuchCommandError as t,definePlugin as n,extractParameterInfo as r,inferDefault as i,normalizeFlagValue as a,normalizeParameterValue as o,resolveCommand as s}from"@clerc/core";import{formatFlagName as c,formatVersion as l,isTruthy as u,objectIsEmpty as d,toArray as
|
|
2
|
-
`),
|
|
3
|
-
`):e.body;return e.title?`${
|
|
4
|
-
`).map(
|
|
1
|
+
import{DOUBLE_DASH as e,NoSuchCommandError as t,definePlugin as n,extractParameterInfo as r,inferDefault as i,normalizeFlagValue as a,normalizeParameterValue as o,resolveCommand as s}from"@clerc/core";import{formatFlagName as c,formatVersion as l,isTruthy as u,objectIsEmpty as d,resolveAsyncValue as f,toArray as p}from"@clerc/utils";import*as m from"@uttr/tint";import h from"fast-string-width";import g from"text-table";const _=e=>typeof e==`object`&&!Array.isArray(e);function v(e){if(typeof e==`function`)return e.display??e.name;let t=e[0];return`Array<${t.displayName??t.name}>`}function y(e){return typeof e==`function`&&`display`in e&&e.display?e.display:JSON.stringify(e)}function b(e){return e===``?`(root)`:e}const x={formatTypeValue:v,formatFlagDefault:y},S=`default`,C=e=>g(e,{stringLength:h}),w=e=>C(e).split(`
|
|
2
|
+
`),T=` `.repeat(2),E=e=>`${T}${e}`;function D(e){let t=new Map;if(e)for(let[n,r]of e)t.set(n,r);return t}function O(e,t,n,r){if(e&&e!==S&&!t.has(e))throw Error(`Unknown ${n} group "${e}" for "${r}". Available groups: ${[...t.keys()].join(`, `)||`(none)`}`)}var k=class{_command;_examples;_notes;get _commandGroups(){return D(this._getGroups().commands)}get _flagGroups(){return D(this._getGroups().flags)}get _globalFlagGroups(){return D(this._getGroups().globalFlags)}constructor(e,t,n,r){this._formatters=e,this._cli=t,this._globalFlags=n,this._getGroups=r}setCommand(e){e&&(this._command=e)}setHelpContent(e,t){this._notes=e,this._examples=t}renderSections(e){return e.filter(u).map(e=>{let t=Array.isArray(e.body)?e.body.filter(e=>e!==void 0).join(`
|
|
3
|
+
`):e.body;return e.title?`${m.underline.bold(e.title)}\n${t.split(`
|
|
4
|
+
`).map(E).join(`
|
|
5
5
|
`)}`:t}).join(`
|
|
6
6
|
|
|
7
|
-
`)}render(){let e=[this.renderHeader(),this.renderUsage(),this.renderParameters(),this.renderCommandFlags(),this.renderGlobalFlags(),this.renderCommands(),this.renderExamples(),this.renderNotes()];return this.renderSections(e)}renderHeader(){let{_scriptName:e,_version:t,_description:n}=this._cli,r=this._command,i=r?r.description:n,a=`${!r||r.name===``?
|
|
8
|
-
`),
|
|
7
|
+
`)}render(){let e=[this.renderHeader(),this.renderUsage(),this.renderParameters(),this.renderCommandFlags(),this.renderGlobalFlags(),this.renderCommands(),this.renderExamples(),this.renderNotes()];return this.renderSections(e)}renderHeader(){let{_scriptName:e,_version:t,_description:n}=this._cli,r=this._command,i=r?r.description:n,a=`${!r||r.name===``?m.bold(e):m.dim(e)}${r?.name?` ${m.bold(r.name)}`:``}${` ${l(t)}`}`,o=r?.alias===void 0?void 0:`Alias${p(r.alias).length>1?`es`:``}: ${p(r.alias).map(e=>m.bold(b(e))).join(`, `)}`;return{body:[`${a}${i?` - ${i}`:``}`,o]}}renderUsage(){let{_scriptName:t}=this._cli,n=this._command,r=`$ ${t}`;if(n){if(n.name&&(r+=` ${n.name}`),n.parameters){let t=n.parameters.indexOf(e),i=t!==-1&&n.parameters.slice(t+1).some(e=>(typeof e==`string`?e:e.key).startsWith(`<`)),a=n.parameters.map(t=>{let n=typeof t==`string`?t:t.key;return t===e&&(n=i?e:`[${e}]`),n});r+=` ${a.join(` `)}`}}else this._cli._commands.size>0&&(!this._cli._commands.has(``)||this._cli._commands.size!==1)&&(r+=this._cli._commands.has(``)?` ${m.dim(`[command]`)}`:` ${m.dim(`<command>`)}`);return(n?.flags&&!d(n.flags)||!d(this._globalFlags))&&(r+=` ${m.dim(`[flags]`)}`),{title:`Usage`,body:[r]}}renderParameters(){let t=this._command;if(!(!t?.parameters||t.parameters.length===0))return{title:`Parameters`,body:w(t.parameters.filter(t=>t!==e).map(o).map(({key:e,type:t,description:n})=>{let i;if(t)i=this._formatters.formatTypeValue(t);else{let{isVariadic:t}=r(e);i=t?`Array<string>`:`string`}return[m.bold(e),m.dim(i),n].filter(u)}))}}getSubcommands(e){let t=new Map;if(e===``)return t;let n=`${e} `;for(let[e,r]of this._cli._commands)if(e.startsWith(n)){let i=e.slice(n.length);t.set(i,r)}return t}buildGroupedCommandsBody(e,t){let n=new Map,r=[],i=[];for(let a of e.values()){if(a.__isAlias||a.help?.show===!1)continue;let e=a.help?.group;O(e,this._commandGroups,`command`,a.name);let o=[`${m.bold(b(a.name.slice(t.length)))}${a.alias===void 0?``:` (${p(a.alias).map(b).join(`, `)})`}`,a.description].filter(u);if(a.name===``)i=o;else if(e&&e!==S){let t=n.get(e)??[];t.push(o),n.set(e,t)}else r.push(o)}let a=[],o=[];i.length>0&&o.push(i),r.length>0&&o.push(...r),o.length>0&&a.push(...w(o));for(let[e,t]of this._commandGroups){let r=n.get(e);r&&r.length>0&&(a.length>0&&a.push(``),a.push(`${m.dim(t)}`),a.push(...w(r).map(E)))}return a}renderAvailableSubcommands(e){let t=this.getSubcommands(e);if(t.size===0)return null;let n=`${e} `,r=this.buildGroupedCommandsBody(t,n);if(r.length===0)return null;let i=[{body:`${this._cli._scriptName} ${m.bold(e)} not found`},{title:`Available Subcommands`,body:r}];return this.renderSections(i)}renderCommands(){let e=this._cli._commands,t,n=`Commands`,r=``;if(this._command){if(r=this._command.name?`${this._command.name} `:``,n=`Subcommands`,t=this.getSubcommands(this._command.name),t.size===0)return}else t=e;if(t.size===0)return;let i=this.buildGroupedCommandsBody(t,r);if(i.length!==0)return{title:n,body:i}}renderFlagItem(e,t){t=a(t);let n=c(e);t.short&&(n+=`, ${c(t.short)}`),t.type===Boolean&&t.negatable!==!1&&t.default===!0&&(n+=`, --no-${e}`);let r=this._formatters.formatTypeValue(t.type),o=t.default;o===void 0&&(o=i(t.type));let s=o!==void 0&&m.dim(`[default: ${m.bold(this._formatters.formatFlagDefault(o))}]`);return[m.bold(n),m.dim(r),t.description,s].filter(u)}renderGroupedFlags(e,t,n){let r=new Map,i=[];for(let[a,o]of Object.entries(e)){if(_(o)&&o.help?.show===!1)continue;let e=_(o)&&o.help?.group||S;if(e===S){i.push(this.renderFlagItem(a,o));continue}O(e,t,n,a);let s=r.get(e)??[];s.push(this.renderFlagItem(a,o)),r.set(e,s)}let a=[];i.length>0&&a.push(...w(i));for(let[e,n]of t){let t=r.get(e);t&&t.length>0&&(a.length>0&&a.push(``),a.push(`${m.dim(n)}`),a.push(...w(t).map(E)))}return a}renderCommandFlags(){let e=this._command;if(!e?.flags||d(e.flags))return;let t=this.renderGroupedFlags(e.flags,this._flagGroups,`flag`);if(t.length!==0)return{title:`Flags`,body:t}}renderGlobalFlags(){if(!this._globalFlags||d(this._globalFlags))return;let e=this.renderGroupedFlags(this._globalFlags,this._globalFlagGroups,`global flag`);if(e.length!==0)return{title:`Global Flags`,body:e}}renderNotes(){if(this._notes?.length)return{title:`Notes`,body:this._notes}}renderExamples(){if(this._examples?.length)return{title:`Examples`,body:w(this._examples.map(([e,t])=>[e,`-`,t]))}}};function A(e,{groups:t}){e.store.help={addGroup:e=>{e.commands&&(t.commands=[...t.commands??[],...e.commands]),e.flags&&(t.flags=[...t.flags??[],...e.flags]),e.globalFlags&&(t.globalFlags=[...t.globalFlags??[],...e.globalFlags])}}}const j=({command:e=!0,flag:r=!0,showHelpWhenNoCommandSpecified:i=!0,notes:a,examples:o,header:c,footer:l,formatters:d,groups:p={}}={})=>n({setup:n=>{A(n,{groups:p});let m={...x,...d};async function h(e){let t=e?.notes??a,n=e?.examples??o;return{notes:t?await f(t):void 0,examples:n?await f(n):void 0}}async function g(e){let t=c&&await f(c);t&&console.log(t),console.log(e);let n=l&&await f(l);n&&console.log(n)}let _=new k(m,n,n._globalFlags,()=>p);async function v(e){let t=_.renderAvailableSubcommands(e);return t?(await g(t),!0):!1}e&&n.command(`help`,`Show help`,{parameters:[`[command...]`],help:{notes:[`If no command is specified, show help for the CLI.`,`If a command is specified, show help for the command.`,r&&`-h is an alias for --help.`].filter(u),examples:[e&&[`$ ${n._scriptName} help`,`Show help`],e&&[`$ ${n._scriptName} help <command>`,`Show help for a specific command`],r&&[`$ ${n._scriptName} <command> --help`,`Show help for a specific command`]].filter(u)}}).on(`help`,async e=>{let r=e.parameters.command,i;if(r.length>0&&([i]=s(n._commands,r),!i)){let e=r.join(` `);if(await v(e))return;throw new t(e)}_.setCommand(i);let{notes:a,examples:o}=await h(i?.help);_.setHelpContent(a,o),await g(_.render())}),r&&n.globalFlag(`help`,`Show help`,{short:`h`,type:Boolean,default:!1}),n.interceptor({enforce:`post`,handler:async(e,t)=>{if(e.flags.help){let n=e.command;if(!n&&e.rawParsed.parameters.length>0){if(await v(e.rawParsed.parameters.join(` `)))return;await t()}_.setCommand(n);let{notes:r,examples:i}=await h(n?.help);_.setHelpContent(r,i),await g(_.render())}else if(i&&!e.command&&e.rawParsed.parameters.length===0){console.log(`No command specified. Showing help:
|
|
8
|
+
`),_.setCommand(void 0);let{notes:e,examples:t}=await h(void 0);_.setHelpContent(e,t),await g(_.render())}else await t()}})}});export{x as defaultFormatters,j as helpPlugin};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@clerc/plugin-help",
|
|
3
|
-
"version": "1.3.0
|
|
3
|
+
"version": "1.3.0",
|
|
4
4
|
"author": "Ray <i@mk1.io> (https://github.com/so1ve)",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"description": "Clerc plugin help",
|
|
@@ -37,15 +37,15 @@
|
|
|
37
37
|
},
|
|
38
38
|
"dependencies": {
|
|
39
39
|
"@uttr/tint": "^0.1.3",
|
|
40
|
-
"string-width": "^
|
|
40
|
+
"fast-string-width": "^3.0.2",
|
|
41
41
|
"text-table": "^0.2.0",
|
|
42
|
-
"@clerc/utils": "1.3.0
|
|
42
|
+
"@clerc/utils": "1.3.0"
|
|
43
43
|
},
|
|
44
44
|
"devDependencies": {
|
|
45
45
|
"@types/text-table": "^0.2.5",
|
|
46
46
|
"kons": "^0.7.1",
|
|
47
|
-
"@clerc/
|
|
48
|
-
"@clerc/
|
|
47
|
+
"@clerc/core": "1.3.0",
|
|
48
|
+
"@clerc/parser": "1.3.0"
|
|
49
49
|
},
|
|
50
50
|
"peerDependencies": {
|
|
51
51
|
"@clerc/core": "*"
|