@clerc/plugin-help 1.2.1 → 1.3.0-beta.2
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 +62 -60
- package/dist/index.mjs +6 -6
- package/package.json +5 -7
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
|
|
@@ -17,16 +18,16 @@ type GroupDefinition = [key: string, name: string];
|
|
|
17
18
|
*/
|
|
18
19
|
interface GroupsOptions {
|
|
19
20
|
/**
|
|
20
|
-
|
|
21
|
-
|
|
21
|
+
* Groups for commands. Each group is defined as `[key, name]`.
|
|
22
|
+
*/
|
|
22
23
|
commands?: GroupDefinition[];
|
|
23
24
|
/**
|
|
24
|
-
|
|
25
|
-
|
|
25
|
+
* Groups for command-specific flags. Each group is defined as `[key, name]`.
|
|
26
|
+
*/
|
|
26
27
|
flags?: GroupDefinition[];
|
|
27
28
|
/**
|
|
28
|
-
|
|
29
|
-
|
|
29
|
+
* Groups for global flags. Each group is defined as `[key, name]`.
|
|
30
|
+
*/
|
|
30
31
|
globalFlags?: GroupDefinition[];
|
|
31
32
|
}
|
|
32
33
|
//#endregion
|
|
@@ -36,88 +37,89 @@ declare const defaultFormatters: Formatters;
|
|
|
36
37
|
//#region src/index.d.ts
|
|
37
38
|
interface HelpOptions {
|
|
38
39
|
/**
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
40
|
+
* Whether to show this item in help output.
|
|
41
|
+
*
|
|
42
|
+
* @default true
|
|
43
|
+
*/
|
|
44
|
+
show?: boolean;
|
|
45
|
+
/**
|
|
46
|
+
* The group this item belongs to. The group must be defined in the `groups`
|
|
47
|
+
* option of `helpPlugin()`.
|
|
48
|
+
*/
|
|
42
49
|
group?: string;
|
|
43
50
|
}
|
|
44
51
|
interface CommandHelpOptions extends HelpOptions {
|
|
45
52
|
/**
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
*/
|
|
50
|
-
show?: boolean;
|
|
51
|
-
/**
|
|
52
|
-
* Notes to show in the help output.
|
|
53
|
-
*/
|
|
54
|
-
notes?: string[];
|
|
53
|
+
* Notes to show in the help output.
|
|
54
|
+
*/
|
|
55
|
+
notes?: MaybeAsyncGetter<string[]>;
|
|
55
56
|
/**
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
examples?: [string, string][]
|
|
57
|
+
* Examples to show in the help output. Each example is a tuple of `[command,
|
|
58
|
+
* description]`.
|
|
59
|
+
*/
|
|
60
|
+
examples?: MaybeAsyncGetter<[string, string][]>;
|
|
60
61
|
}
|
|
62
|
+
interface FlagHelpOptions extends HelpOptions {}
|
|
61
63
|
declare module "@clerc/core" {
|
|
62
64
|
interface CommandCustomOptions {
|
|
63
65
|
/**
|
|
64
|
-
|
|
65
|
-
|
|
66
|
+
* Help options for the command.
|
|
67
|
+
*/
|
|
66
68
|
help?: CommandHelpOptions;
|
|
67
69
|
}
|
|
68
70
|
interface FlagCustomOptions {
|
|
69
71
|
/**
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
help?:
|
|
72
|
+
* Help options for the flag.
|
|
73
|
+
*/
|
|
74
|
+
help?: FlagHelpOptions;
|
|
73
75
|
}
|
|
74
76
|
}
|
|
75
77
|
interface HelpPluginOptions {
|
|
76
78
|
/**
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
79
|
+
* Whether to register the `help` command.
|
|
80
|
+
*
|
|
81
|
+
* @default true
|
|
82
|
+
*/
|
|
81
83
|
command?: boolean;
|
|
82
84
|
/**
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
85
|
+
* Whether to register the `--help` global flag.
|
|
86
|
+
*
|
|
87
|
+
* @default true
|
|
88
|
+
*/
|
|
87
89
|
flag?: boolean;
|
|
88
90
|
/**
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
91
|
+
* Whether to show help when no command is specified.
|
|
92
|
+
*
|
|
93
|
+
* @default true
|
|
94
|
+
*/
|
|
93
95
|
showHelpWhenNoCommandSpecified?: boolean;
|
|
94
96
|
/**
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
notes?: string[]
|
|
97
|
+
* Notes to show in the help output.
|
|
98
|
+
*/
|
|
99
|
+
notes?: MaybeAsyncGetter<string[]>;
|
|
98
100
|
/**
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
examples?: [string, string][]
|
|
101
|
+
* Examples to show in the help output. Each example is a tuple of `[command,
|
|
102
|
+
* description]`.
|
|
103
|
+
*/
|
|
104
|
+
examples?: MaybeAsyncGetter<[string, string][]>;
|
|
103
105
|
/**
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
header?: string
|
|
106
|
+
* Header to show before the help output.
|
|
107
|
+
*/
|
|
108
|
+
header?: MaybeAsyncGetter<string>;
|
|
107
109
|
/**
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
footer?: string
|
|
110
|
+
* Footer to show after the help output.
|
|
111
|
+
*/
|
|
112
|
+
footer?: MaybeAsyncGetter<string>;
|
|
111
113
|
/**
|
|
112
|
-
|
|
113
|
-
|
|
114
|
+
* Custom formatters for rendering help.
|
|
115
|
+
*/
|
|
114
116
|
formatters?: Partial<Formatters>;
|
|
115
117
|
/**
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
118
|
+
* Group definitions for commands and flags. Groups allow organizing commands
|
|
119
|
+
* and flags into logical sections in help output. Each group is defined as
|
|
120
|
+
* `[key, name]` where `key` is the identifier used in help options and `name`
|
|
121
|
+
* is the display name shown in help output.
|
|
122
|
+
*/
|
|
121
123
|
groups?: GroupsOptions;
|
|
122
124
|
}
|
|
123
125
|
declare const helpPlugin: ({
|
|
@@ -132,4 +134,4 @@ declare const helpPlugin: ({
|
|
|
132
134
|
groups
|
|
133
135
|
}?: HelpPluginOptions) => Plugin;
|
|
134
136
|
//#endregion
|
|
135
|
-
export { CommandHelpOptions, type GroupDefinition, type GroupsOptions, HelpOptions, HelpPluginOptions, defaultFormatters, helpPlugin };
|
|
137
|
+
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,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){c&&console.log(await f(c)),console.log(e),l&&console.log(await f(l))}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.2
|
|
3
|
+
"version": "1.3.0-beta.2",
|
|
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"
|
|
@@ -39,15 +37,15 @@
|
|
|
39
37
|
},
|
|
40
38
|
"dependencies": {
|
|
41
39
|
"@uttr/tint": "^0.1.3",
|
|
42
|
-
"string-width": "^
|
|
40
|
+
"fast-string-width": "^3.0.2",
|
|
43
41
|
"text-table": "^0.2.0",
|
|
44
|
-
"@clerc/utils": "1.2
|
|
42
|
+
"@clerc/utils": "1.3.0-beta.2"
|
|
45
43
|
},
|
|
46
44
|
"devDependencies": {
|
|
47
45
|
"@types/text-table": "^0.2.5",
|
|
48
46
|
"kons": "^0.7.1",
|
|
49
|
-
"@clerc/core": "1.2
|
|
50
|
-
"@clerc/parser": "1.2
|
|
47
|
+
"@clerc/core": "1.3.0-beta.2",
|
|
48
|
+
"@clerc/parser": "1.3.0-beta.2"
|
|
51
49
|
},
|
|
52
50
|
"peerDependencies": {
|
|
53
51
|
"@clerc/core": "*"
|