@clerc/plugin-help 1.2.0 → 1.3.0-beta.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/dist/index.d.mts +55 -54
- package/dist/index.mjs +6 -6
- package/package.json +4 -6
package/dist/index.d.mts
CHANGED
|
@@ -17,16 +17,16 @@ type GroupDefinition = [key: string, name: string];
|
|
|
17
17
|
*/
|
|
18
18
|
interface GroupsOptions {
|
|
19
19
|
/**
|
|
20
|
-
|
|
21
|
-
|
|
20
|
+
* Groups for commands. Each group is defined as `[key, name]`.
|
|
21
|
+
*/
|
|
22
22
|
commands?: GroupDefinition[];
|
|
23
23
|
/**
|
|
24
|
-
|
|
25
|
-
|
|
24
|
+
* Groups for command-specific flags. Each group is defined as `[key, name]`.
|
|
25
|
+
*/
|
|
26
26
|
flags?: GroupDefinition[];
|
|
27
27
|
/**
|
|
28
|
-
|
|
29
|
-
|
|
28
|
+
* Groups for global flags. Each group is defined as `[key, name]`.
|
|
29
|
+
*/
|
|
30
30
|
globalFlags?: GroupDefinition[];
|
|
31
31
|
}
|
|
32
32
|
//#endregion
|
|
@@ -36,88 +36,89 @@ declare const defaultFormatters: Formatters;
|
|
|
36
36
|
//#region src/index.d.ts
|
|
37
37
|
interface HelpOptions {
|
|
38
38
|
/**
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
39
|
+
* Whether to show this item in help output.
|
|
40
|
+
*
|
|
41
|
+
* @default true
|
|
42
|
+
*/
|
|
43
|
+
show?: boolean;
|
|
44
|
+
/**
|
|
45
|
+
* The group this item belongs to. The group must be defined in the `groups`
|
|
46
|
+
* option of `helpPlugin()`.
|
|
47
|
+
*/
|
|
42
48
|
group?: string;
|
|
43
49
|
}
|
|
44
50
|
interface CommandHelpOptions extends HelpOptions {
|
|
45
51
|
/**
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
* @default true
|
|
49
|
-
*/
|
|
50
|
-
show?: boolean;
|
|
51
|
-
/**
|
|
52
|
-
* Notes to show in the help output.
|
|
53
|
-
*/
|
|
52
|
+
* Notes to show in the help output.
|
|
53
|
+
*/
|
|
54
54
|
notes?: string[];
|
|
55
55
|
/**
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
56
|
+
* Examples to show in the help output. Each example is a tuple of `[command,
|
|
57
|
+
* description]`.
|
|
58
|
+
*/
|
|
59
59
|
examples?: [string, string][];
|
|
60
60
|
}
|
|
61
|
+
interface FlagHelpOptions extends HelpOptions {}
|
|
61
62
|
declare module "@clerc/core" {
|
|
62
63
|
interface CommandCustomOptions {
|
|
63
64
|
/**
|
|
64
|
-
|
|
65
|
-
|
|
65
|
+
* Help options for the command.
|
|
66
|
+
*/
|
|
66
67
|
help?: CommandHelpOptions;
|
|
67
68
|
}
|
|
68
69
|
interface FlagCustomOptions {
|
|
69
70
|
/**
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
help?:
|
|
71
|
+
* Help options for the flag.
|
|
72
|
+
*/
|
|
73
|
+
help?: FlagHelpOptions;
|
|
73
74
|
}
|
|
74
75
|
}
|
|
75
76
|
interface HelpPluginOptions {
|
|
76
77
|
/**
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
78
|
+
* Whether to register the `help` command.
|
|
79
|
+
*
|
|
80
|
+
* @default true
|
|
81
|
+
*/
|
|
81
82
|
command?: boolean;
|
|
82
83
|
/**
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
84
|
+
* Whether to register the `--help` global flag.
|
|
85
|
+
*
|
|
86
|
+
* @default true
|
|
87
|
+
*/
|
|
87
88
|
flag?: boolean;
|
|
88
89
|
/**
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
90
|
+
* Whether to show help when no command is specified.
|
|
91
|
+
*
|
|
92
|
+
* @default true
|
|
93
|
+
*/
|
|
93
94
|
showHelpWhenNoCommandSpecified?: boolean;
|
|
94
95
|
/**
|
|
95
|
-
|
|
96
|
-
|
|
96
|
+
* Notes to show in the help output.
|
|
97
|
+
*/
|
|
97
98
|
notes?: string[];
|
|
98
99
|
/**
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
100
|
+
* Examples to show in the help output. Each example is a tuple of `[command,
|
|
101
|
+
* description]`.
|
|
102
|
+
*/
|
|
102
103
|
examples?: [string, string][];
|
|
103
104
|
/**
|
|
104
|
-
|
|
105
|
-
|
|
105
|
+
* Header to show before the help output.
|
|
106
|
+
*/
|
|
106
107
|
header?: string;
|
|
107
108
|
/**
|
|
108
|
-
|
|
109
|
-
|
|
109
|
+
* Footer to show after the help output.
|
|
110
|
+
*/
|
|
110
111
|
footer?: string;
|
|
111
112
|
/**
|
|
112
|
-
|
|
113
|
-
|
|
113
|
+
* Custom formatters for rendering help.
|
|
114
|
+
*/
|
|
114
115
|
formatters?: Partial<Formatters>;
|
|
115
116
|
/**
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
117
|
+
* Group definitions for commands and flags. Groups allow organizing commands
|
|
118
|
+
* and flags into logical sections in help output. Each group is defined as
|
|
119
|
+
* `[key, name]` where `key` is the identifier used in help options and `name`
|
|
120
|
+
* is the display name shown in help output.
|
|
121
|
+
*/
|
|
121
122
|
groups?: GroupsOptions;
|
|
122
123
|
}
|
|
123
124
|
declare const helpPlugin: ({
|
|
@@ -132,4 +133,4 @@ declare const helpPlugin: ({
|
|
|
132
133
|
groups
|
|
133
134
|
}?: HelpPluginOptions) => Plugin;
|
|
134
135
|
//#endregion
|
|
135
|
-
export { CommandHelpOptions, type GroupDefinition, type GroupsOptions, HelpOptions, HelpPluginOptions, defaultFormatters, helpPlugin };
|
|
136
|
+
export { CommandHelpOptions, FlagHelpOptions, type GroupDefinition, type GroupsOptions, HelpOptions, HelpPluginOptions, defaultFormatters, helpPlugin };
|
package/dist/index.mjs
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
import{DOUBLE_DASH as e,NoSuchCommandError as t,definePlugin as n,
|
|
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,toArray as f}from"@clerc/utils";import*as p from"@uttr/tint";import m from"string-width";import h from"text-table";const g=e=>typeof e==`object`&&!Array.isArray(e);function _(e){if(typeof e==`function`)return e.display??e.name;let t=e[0];return`Array<${t.displayName??t.name}>`}function v(e){return typeof e==`function`&&`display`in e&&e.display?e.display:JSON.stringify(e)}function y(e){return e===``?`(root)`:e}const b={formatTypeValue:_,formatFlagDefault:v},x=`default`,S=e=>h(e,{stringLength:m}),C=e=>S(e).split(`
|
|
2
|
+
`),w=` `.repeat(2),T=e=>`${w}${e}`;function E(e){let t=new Map;if(e)for(let[n,r]of e)t.set(n,r);return t}function D(e,t,n,r){if(e&&e!==x&&!t.has(e))throw Error(`Unknown ${n} group "${e}" for "${r}". Available groups: ${[...t.keys()].join(`, `)||`(none)`}`)}var O=class{_command;get _commandGroups(){return E(this._getGroups().commands)}get _flagGroups(){return E(this._getGroups().flags)}get _globalFlagGroups(){return E(this._getGroups().globalFlags)}constructor(e,t,n,r,i,a){this._formatters=e,this._cli=t,this._globalFlags=n,this._getGroups=r,this._examples=i,this._notes=a}setCommand(e){e&&(this._command=e,this._examples=e?.help?.examples,this._notes=e?.help?.notes)}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?`${p.underline.bold(e.title)}\n${t.split(`
|
|
4
|
+
`).map(T).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
|
-
`),m(h.render())):await t()}})}});export{
|
|
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===``?p.bold(e):p.dim(e)}${r?.name?` ${p.bold(r.name)}`:``}${` ${l(t)}`}`,o=r?.alias===void 0?void 0:`Alias${f(r.alias).length>1?`es`:``}: ${f(r.alias).map(e=>p.bold(y(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(``)?` ${p.dim(`[command]`)}`:` ${p.dim(`<command>`)}`);return(n?.flags&&!d(n.flags)||!d(this._globalFlags))&&(r+=` ${p.dim(`[flags]`)}`),{title:`Usage`,body:[r]}}renderParameters(){let t=this._command;if(!(!t?.parameters||t.parameters.length===0))return{title:`Parameters`,body:C(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[p.bold(e),p.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;D(e,this._commandGroups,`command`,a.name);let o=[`${p.bold(y(a.name.slice(t.length)))}${a.alias===void 0?``:` (${f(a.alias).map(y).join(`, `)})`}`,a.description].filter(u);if(a.name===``)i=o;else if(e&&e!==x){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(...C(o));for(let[e,t]of this._commandGroups){let r=n.get(e);r&&r.length>0&&(a.length>0&&a.push(``),a.push(`${p.dim(t)}`),a.push(...C(r).map(T)))}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} ${p.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&&p.dim(`[default: ${p.bold(this._formatters.formatFlagDefault(o))}]`);return[p.bold(n),p.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(g(o)&&o.help?.show===!1)continue;let e=g(o)&&o.help?.group||x;if(e===x){i.push(this.renderFlagItem(a,o));continue}D(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(...C(i));for(let[e,n]of t){let t=r.get(e);t&&t.length>0&&(a.length>0&&a.push(``),a.push(`${p.dim(n)}`),a.push(...C(t).map(T)))}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:C(this._examples.map(([e,t])=>[e,`-`,t]))}}};function k(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 A=({command:e=!0,flag:r=!0,showHelpWhenNoCommandSpecified:i=!0,notes:a,examples:o,header:c,footer:l,formatters:d,groups:f={}}={})=>n({setup:n=>{k(n,{groups:f});let p={...b,...d};function m(e){c&&console.log(c),console.log(e),l&&console.log(l)}let h=new O(p,n,n._globalFlags,()=>f,o,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(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`,e=>{let r=e.parameters.command,i;if(r.length>0&&([i]=s(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:
|
|
8
|
+
`),m(h.render())):await t()}})}});export{b as defaultFormatters,A as helpPlugin};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@clerc/plugin-help",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.3.0-beta.1",
|
|
4
4
|
"author": "Ray <i@mk1.io> (https://github.com/so1ve)",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"description": "Clerc plugin help",
|
|
@@ -28,8 +28,6 @@
|
|
|
28
28
|
".": "./dist/index.mjs",
|
|
29
29
|
"./package.json": "./package.json"
|
|
30
30
|
},
|
|
31
|
-
"main": "./dist/index.mjs",
|
|
32
|
-
"module": "./dist/index.mjs",
|
|
33
31
|
"types": "./dist/index.d.mts",
|
|
34
32
|
"files": [
|
|
35
33
|
"dist"
|
|
@@ -41,13 +39,13 @@
|
|
|
41
39
|
"@uttr/tint": "^0.1.3",
|
|
42
40
|
"string-width": "^8.1.0",
|
|
43
41
|
"text-table": "^0.2.0",
|
|
44
|
-
"@clerc/utils": "1.
|
|
42
|
+
"@clerc/utils": "1.3.0-beta.1"
|
|
45
43
|
},
|
|
46
44
|
"devDependencies": {
|
|
47
45
|
"@types/text-table": "^0.2.5",
|
|
48
46
|
"kons": "^0.7.1",
|
|
49
|
-
"@clerc/parser": "1.
|
|
50
|
-
"@clerc/core": "1.
|
|
47
|
+
"@clerc/parser": "1.3.0-beta.1",
|
|
48
|
+
"@clerc/core": "1.3.0-beta.1"
|
|
51
49
|
},
|
|
52
50
|
"peerDependencies": {
|
|
53
51
|
"@clerc/core": "*"
|