@clerc/plugin-help 1.3.0-beta.2 → 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 +2 -2
- package/dist/index.mjs +1 -1
- package/package.json +4 -4
package/dist/index.d.mts
CHANGED
|
@@ -105,11 +105,11 @@ interface HelpPluginOptions {
|
|
|
105
105
|
/**
|
|
106
106
|
* Header to show before the help output.
|
|
107
107
|
*/
|
|
108
|
-
header?: MaybeAsyncGetter<string>;
|
|
108
|
+
header?: MaybeAsyncGetter<string | undefined>;
|
|
109
109
|
/**
|
|
110
110
|
* Footer to show after the help output.
|
|
111
111
|
*/
|
|
112
|
-
footer?: MaybeAsyncGetter<string>;
|
|
112
|
+
footer?: MaybeAsyncGetter<string | undefined>;
|
|
113
113
|
/**
|
|
114
114
|
* Custom formatters for rendering help.
|
|
115
115
|
*/
|
package/dist/index.mjs
CHANGED
|
@@ -4,5 +4,5 @@ import{DOUBLE_DASH as e,NoSuchCommandError as t,definePlugin as n,extractParamet
|
|
|
4
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===``?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){c&&
|
|
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
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",
|
|
@@ -39,13 +39,13 @@
|
|
|
39
39
|
"@uttr/tint": "^0.1.3",
|
|
40
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/core": "1.3.0
|
|
48
|
-
"@clerc/parser": "1.3.0
|
|
47
|
+
"@clerc/core": "1.3.0",
|
|
48
|
+
"@clerc/parser": "1.3.0"
|
|
49
49
|
},
|
|
50
50
|
"peerDependencies": {
|
|
51
51
|
"@clerc/core": "*"
|