@clerc/plugin-help 1.2.0 → 1.2.1

package/dist/index.mjs

@@ -4,5 +4,5 @@ import{DOUBLE_DASH as e,NoSuchCommandError as t,definePlugin as n,inferDefault a
 `).map(C).join(`
 `)}`:t}).join(`
 
-`)}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===``?f.bold(e):f.dim(e)}${r?.name?` ${f.bold(r.name)}`:``}${r?``:` ${c(t)}`}`,o=r?.alias?`Alias${d(r.alias).length>1?`es`:``}: ${d(r.alias).map(e=>f.bold(e)).join(`, `)}`:void 0;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(``)?` ${f.dim(`[command]`)}`:` ${f.dim(`<command>`)}`);return(n?.flags&&!u(n.flags)||!u(this._globalFlags))&&(r+=` ${f.dim(`[flags]`)}`),{title:`Usage`,body:[r]}}renderParameters(){let t=this._command;if(!(!t?.parameters||t.parameters.length===0))return{title:`Parameters`,body:x(t.parameters.filter(t=>t!==e).map(a).map(({key:e,type:t,description:n})=>{let r=t?this._formatters.formatTypeValue(t):`string`;return[f.bold(e),f.dim(r),n].filter(l)}))}}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;T(e,this._commandGroups,`command`,a.name);let o=[`${f.bold(_(a.name.slice(t.length)))}${a.alias?` (${d(a.alias).map(_).join(`, `)})`:``}`,a.description].filter(l);if(a.name===``)i=o;else if(e&&e!==y){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(...x(o));for(let[e,t]of this._commandGroups){let r=n.get(e);r&&r.length>0&&(a.length>0&&a.push(``),a.push(`${f.dim(t)}`),a.push(...x(r).map(C)))}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} ${f.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);return{title:n,body:i}}renderFlagItem(e,t){t=i(t);let n=s(e);t.short&&(n+=`, ${s(t.short)}`),t.type===Boolean&&t.negatable!==!1&&t.default===!0&&(n+=`, --no-${e}`);let a=this._formatters.formatTypeValue(t.type),o=t.default;o===void 0&&(o=r(t.type));let c=o!==void 0&&f.dim(`[default: ${f.bold(this._formatters.formatFlagDefault(o))}]`);return[f.bold(n),f.dim(a),t.description,c].filter(l)}renderGroupedFlags(e,t,n){let r=new Map,i=[];for(let[a,o]of Object.entries(e)){let e=o.help?.group;T(e,t,n,a);let s=this.renderFlagItem(a,o);if(e&&e!==y){let t=r.get(e)??[];t.push(s),r.set(e,t)}else i.push(s)}let a=[];i.length>0&&a.push(...x(i));for(let[e,n]of t){let t=r.get(e);t&&t.length>0&&(a.length>0&&a.push(``),a.push(`${f.dim(n)}`),a.push(...x(t).map(C)))}return a}renderCommandFlags(){let e=this._command;if(!(!e?.flags||u(e.flags)))return{title:`Flags`,body:this.renderGroupedFlags(e.flags,this._flagGroups,`flag`)}}renderGlobalFlags(){if(!(!this._globalFlags||u(this._globalFlags)))return{title:`Global Flags`,body:this.renderGroupedFlags(this._globalFlags,this._globalFlagGroups,`global flag`)}}renderNotes(){if(this._notes?.length)return{title:`Notes`,body:this._notes}}renderExamples(){if(this._examples?.length)return{title:`Examples`,body:x(this._examples.map(([e,t])=>[e,`-`,t]))}}};function D(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 O=({command:e=!0,flag:r=!0,showHelpWhenNoCommandSpecified:i=!0,notes:a,examples:s,header:c,footer:u,formatters:d,groups:f={}}={})=>n({setup:n=>{D(n,{groups:f});let p={...v,...d};function m(e){c&&console.log(c),console.log(e),u&&console.log(u)}let h=new E(p,n,n._globalFlags,()=>f,s,a);function g(e){let t=h.renderAvailableSubcommands(e);return t?(m(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(l),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(l)}}).on(`help`,e=>{let r=e.parameters.command,i;if(r.length>0&&([i]=o(n._commands,r),!i)){let e=r.join(` `);if(g(e))return;throw new t(e)}h.setCommand(i),m(h.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(g(e.rawParsed.parameters.join(` `)))return;await t()}h.setCommand(n),m(h.render())}else i&&!e.command&&e.rawParsed.parameters.length===0?(console.log(`No command specified. Showing help:
+`)}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===``?f.bold(e):f.dim(e)}${r?.name?` ${f.bold(r.name)}`:``}${r?``:` ${c(t)}`}`,o=r?.alias===void 0?void 0:`Alias${d(r.alias).length>1?`es`:``}: ${d(r.alias).map(e=>f.bold(_(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(``)?` ${f.dim(`[command]`)}`:` ${f.dim(`<command>`)}`);return(n?.flags&&!u(n.flags)||!u(this._globalFlags))&&(r+=` ${f.dim(`[flags]`)}`),{title:`Usage`,body:[r]}}renderParameters(){let t=this._command;if(!(!t?.parameters||t.parameters.length===0))return{title:`Parameters`,body:x(t.parameters.filter(t=>t!==e).map(a).map(({key:e,type:t,description:n})=>{let r=t?this._formatters.formatTypeValue(t):`string`;return[f.bold(e),f.dim(r),n].filter(l)}))}}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;T(e,this._commandGroups,`command`,a.name);let o=[`${f.bold(_(a.name.slice(t.length)))}${a.alias===void 0?``:` (${d(a.alias).map(_).join(`, `)})`}`,a.description].filter(l);if(a.name===``)i=o;else if(e&&e!==y){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(...x(o));for(let[e,t]of this._commandGroups){let r=n.get(e);r&&r.length>0&&(a.length>0&&a.push(``),a.push(`${f.dim(t)}`),a.push(...x(r).map(C)))}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} ${f.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);return{title:n,body:i}}renderFlagItem(e,t){t=i(t);let n=s(e);t.short&&(n+=`, ${s(t.short)}`),t.type===Boolean&&t.negatable!==!1&&t.default===!0&&(n+=`, --no-${e}`);let a=this._formatters.formatTypeValue(t.type),o=t.default;o===void 0&&(o=r(t.type));let c=o!==void 0&&f.dim(`[default: ${f.bold(this._formatters.formatFlagDefault(o))}]`);return[f.bold(n),f.dim(a),t.description,c].filter(l)}renderGroupedFlags(e,t,n){let r=new Map,i=[];for(let[a,o]of Object.entries(e)){let e=o.help?.group;T(e,t,n,a);let s=this.renderFlagItem(a,o);if(e&&e!==y){let t=r.get(e)??[];t.push(s),r.set(e,t)}else i.push(s)}let a=[];i.length>0&&a.push(...x(i));for(let[e,n]of t){let t=r.get(e);t&&t.length>0&&(a.length>0&&a.push(``),a.push(`${f.dim(n)}`),a.push(...x(t).map(C)))}return a}renderCommandFlags(){let e=this._command;if(!(!e?.flags||u(e.flags)))return{title:`Flags`,body:this.renderGroupedFlags(e.flags,this._flagGroups,`flag`)}}renderGlobalFlags(){if(!(!this._globalFlags||u(this._globalFlags)))return{title:`Global Flags`,body:this.renderGroupedFlags(this._globalFlags,this._globalFlagGroups,`global flag`)}}renderNotes(){if(this._notes?.length)return{title:`Notes`,body:this._notes}}renderExamples(){if(this._examples?.length)return{title:`Examples`,body:x(this._examples.map(([e,t])=>[e,`-`,t]))}}};function D(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 O=({command:e=!0,flag:r=!0,showHelpWhenNoCommandSpecified:i=!0,notes:a,examples:s,header:c,footer:u,formatters:d,groups:f={}}={})=>n({setup:n=>{D(n,{groups:f});let p={...v,...d};function m(e){c&&console.log(c),console.log(e),u&&console.log(u)}let h=new E(p,n,n._globalFlags,()=>f,s,a);function g(e){let t=h.renderAvailableSubcommands(e);return t?(m(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(l),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(l)}}).on(`help`,e=>{let r=e.parameters.command,i;if(r.length>0&&([i]=o(n._commands,r),!i)){let e=r.join(` `);if(g(e))return;throw new t(e)}h.setCommand(i),m(h.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(g(e.rawParsed.parameters.join(` `)))return;await t()}h.setCommand(n),m(h.render())}else i&&!e.command&&e.rawParsed.parameters.length===0?(console.log(`No command specified. Showing help:
 `),m(h.render())):await t()}})}});export{v as defaultFormatters,O as helpPlugin};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clerc/plugin-help",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "author": "Ray <i@mk1.io> (https://github.com/so1ve)",
   "type": "module",
   "description": "Clerc plugin help",
@@ -41,13 +41,13 @@
     "@uttr/tint": "^0.1.3",
     "string-width": "^8.1.0",
     "text-table": "^0.2.0",
-    "@clerc/utils": "1.2.0"
+    "@clerc/utils": "1.2.1"
   },
   "devDependencies": {
     "@types/text-table": "^0.2.5",
     "kons": "^0.7.1",
-    "@clerc/parser": "1.2.0",
-    "@clerc/core": "1.2.0"
+    "@clerc/core": "1.2.1",
+    "@clerc/parser": "1.2.1"
   },
   "peerDependencies": {
     "@clerc/core": "*"