@clerc/plugin-help 0.20.0 → 0.22.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.js +54 -29
- package/dist/index.mjs +54 -29
- package/package.json +4 -4
package/dist/index.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { definePlugin,
|
|
1
|
+
import { definePlugin, Root, resolveCommand, NoSuchCommandError } from '@clerc/core';
|
|
2
2
|
import { toArray, gracefulFlagName } from '@clerc/utils';
|
|
3
3
|
import pc from 'picocolors';
|
|
4
4
|
import getFuncName from 'get-func-name';
|
|
@@ -55,24 +55,35 @@ const render = (sections) => {
|
|
|
55
55
|
};
|
|
56
56
|
|
|
57
57
|
const DELIMITER = pc.yellow("-");
|
|
58
|
+
const NO_DESCRIPTION = "(No description)";
|
|
59
|
+
const ROOT = "<Root>";
|
|
60
|
+
const NAME = "Name:";
|
|
61
|
+
const VERSION = "Version:";
|
|
62
|
+
const COMMANDS = "Commands:";
|
|
63
|
+
const SUBCOMMAND = "Subcommand:";
|
|
64
|
+
const FLAGS = "Flags:";
|
|
65
|
+
const DESCRIPTION = "Description:";
|
|
66
|
+
const USAGE = "Usage:";
|
|
67
|
+
const EXAMPLES = "Examples:";
|
|
68
|
+
const NOTES = "Notes:";
|
|
58
69
|
const print = (s) => {
|
|
59
70
|
process.stdout.write(s);
|
|
60
71
|
};
|
|
61
|
-
const formatCommandName = (name) => Array.isArray(name) ? name.join(" ") : typeof name === "string" ? name :
|
|
72
|
+
const formatCommandName = (name) => Array.isArray(name) ? name.join(" ") : typeof name === "string" ? name : ROOT;
|
|
62
73
|
const generateCliDetail = (sections, cli, subcommand) => {
|
|
63
74
|
const items = [
|
|
64
75
|
{
|
|
65
|
-
title:
|
|
76
|
+
title: NAME,
|
|
66
77
|
body: pc.red(cli._name)
|
|
67
78
|
},
|
|
68
79
|
{
|
|
69
|
-
title:
|
|
80
|
+
title: VERSION,
|
|
70
81
|
body: pc.yellow(cli._version)
|
|
71
82
|
}
|
|
72
83
|
];
|
|
73
84
|
if (subcommand) {
|
|
74
85
|
items.push({
|
|
75
|
-
title:
|
|
86
|
+
title: SUBCOMMAND,
|
|
76
87
|
body: pc.green(`${cli._name} ${formatCommandName(subcommand.name)}`)
|
|
77
88
|
});
|
|
78
89
|
}
|
|
@@ -81,14 +92,14 @@ const generateCliDetail = (sections, cli, subcommand) => {
|
|
|
81
92
|
items
|
|
82
93
|
});
|
|
83
94
|
sections.push({
|
|
84
|
-
title:
|
|
95
|
+
title: DESCRIPTION,
|
|
85
96
|
body: [(subcommand == null ? void 0 : subcommand.description) || cli._description]
|
|
86
97
|
});
|
|
87
98
|
};
|
|
88
99
|
const generateExamples = (sections, examples) => {
|
|
89
100
|
const examplesFormatted = examples.map(([command, description]) => [command, DELIMITER, description]);
|
|
90
101
|
sections.push({
|
|
91
|
-
title:
|
|
102
|
+
title: EXAMPLES,
|
|
92
103
|
body: splitTable(...examplesFormatted)
|
|
93
104
|
});
|
|
94
105
|
};
|
|
@@ -97,20 +108,30 @@ const generateHelp = (ctx, notes, examples) => {
|
|
|
97
108
|
const sections = [];
|
|
98
109
|
generateCliDetail(sections, cli);
|
|
99
110
|
sections.push({
|
|
100
|
-
title:
|
|
111
|
+
title: USAGE,
|
|
101
112
|
body: [pc.magenta(`$ ${cli._name} [command] [flags]`)]
|
|
102
113
|
});
|
|
103
|
-
const commands = [...ctx.
|
|
104
|
-
const commandNameWithAlias = [typeof command.name === "symbol" ? "" : command.name, ...toArray(command.alias || [])].
|
|
114
|
+
const commands = [...ctx.hasRoot ? [cli._commands[Root]] : [], ...Object.values(cli._commands)].map((command) => {
|
|
115
|
+
const commandNameWithAlias = [typeof command.name === "symbol" ? "" : command.name, ...toArray(command.alias || [])].sort((a, b) => {
|
|
116
|
+
if (a === Root) {
|
|
117
|
+
return -1;
|
|
118
|
+
}
|
|
119
|
+
if (b === Root) {
|
|
120
|
+
return 1;
|
|
121
|
+
}
|
|
122
|
+
return a.length - b.length;
|
|
123
|
+
}).map((n) => {
|
|
124
|
+
return n === "" || typeof n === "symbol" ? `${cli._name}` : `${cli._name} ${n}`;
|
|
125
|
+
}).join(", ");
|
|
105
126
|
return [pc.cyan(commandNameWithAlias), DELIMITER, command.description];
|
|
106
127
|
});
|
|
107
128
|
sections.push({
|
|
108
|
-
title:
|
|
129
|
+
title: COMMANDS,
|
|
109
130
|
body: splitTable(...commands)
|
|
110
131
|
});
|
|
111
132
|
if (notes) {
|
|
112
133
|
sections.push({
|
|
113
|
-
title:
|
|
134
|
+
title: NOTES,
|
|
114
135
|
body: notes
|
|
115
136
|
});
|
|
116
137
|
}
|
|
@@ -123,19 +144,22 @@ const generateSubcommandHelp = (ctx, command) => {
|
|
|
123
144
|
var _a;
|
|
124
145
|
const { cli } = ctx;
|
|
125
146
|
const subcommand = resolveCommand(cli._commands, command);
|
|
126
|
-
if (!subcommand
|
|
147
|
+
if (!subcommand) {
|
|
127
148
|
throw new NoSuchCommandError(formatCommandName(command));
|
|
128
149
|
}
|
|
129
150
|
const sections = [];
|
|
130
151
|
generateCliDetail(sections, cli, subcommand);
|
|
131
152
|
const parameters = ((_a = subcommand.parameters) == null ? void 0 : _a.join(" ")) || void 0;
|
|
153
|
+
const commandName = ctx.name === Root ? "" : ` ${formatCommandName(subcommand.name)}`;
|
|
154
|
+
const parametersString = parameters ? ` ${parameters}` : "";
|
|
155
|
+
const flagsString = subcommand.flags ? " [flags]" : "";
|
|
132
156
|
sections.push({
|
|
133
|
-
title:
|
|
134
|
-
body: [pc.magenta(`$ ${cli._name}${
|
|
157
|
+
title: USAGE,
|
|
158
|
+
body: [pc.magenta(`$ ${cli._name}${commandName}${parametersString}${flagsString}`)]
|
|
135
159
|
});
|
|
136
160
|
if (subcommand.flags) {
|
|
137
161
|
sections.push({
|
|
138
|
-
title:
|
|
162
|
+
title: FLAGS,
|
|
139
163
|
body: splitTable(
|
|
140
164
|
...Object.entries(subcommand.flags).map(([name, flag]) => {
|
|
141
165
|
const flagNameWithAlias = [gracefulFlagName(name)];
|
|
@@ -143,9 +167,7 @@ const generateSubcommandHelp = (ctx, command) => {
|
|
|
143
167
|
flagNameWithAlias.push(gracefulFlagName(flag.alias));
|
|
144
168
|
}
|
|
145
169
|
const items = [pc.blue(flagNameWithAlias.join(", "))];
|
|
146
|
-
|
|
147
|
-
items.push(DELIMITER, flag.description);
|
|
148
|
-
}
|
|
170
|
+
items.push(DELIMITER, flag.description || NO_DESCRIPTION);
|
|
149
171
|
if (flag.type) {
|
|
150
172
|
const type = stringifyType(flag.type);
|
|
151
173
|
items.push(pc.gray(`(${type})`));
|
|
@@ -157,7 +179,7 @@ const generateSubcommandHelp = (ctx, command) => {
|
|
|
157
179
|
}
|
|
158
180
|
if (subcommand.notes) {
|
|
159
181
|
sections.push({
|
|
160
|
-
title:
|
|
182
|
+
title: NOTES,
|
|
161
183
|
body: subcommand.notes
|
|
162
184
|
});
|
|
163
185
|
}
|
|
@@ -197,21 +219,24 @@ const helpPlugin = ({
|
|
|
197
219
|
});
|
|
198
220
|
}
|
|
199
221
|
cli.inspector((ctx, next) => {
|
|
200
|
-
|
|
222
|
+
const hasHelpFlag = ctx.raw.mergedFlags.h || ctx.raw.mergedFlags.help;
|
|
223
|
+
if (!ctx.hasRootOrAlias && !ctx.raw._.length && showHelpWhenNoCommand && !hasHelpFlag) {
|
|
201
224
|
let str = "No command supplied.\n\n";
|
|
202
225
|
str += generateHelp(ctx, notes, examples);
|
|
203
226
|
str += "\n";
|
|
204
227
|
print(str);
|
|
205
228
|
process.exit(1);
|
|
206
|
-
} else if (
|
|
207
|
-
if (ctx.raw._.length
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
229
|
+
} else if (hasHelpFlag) {
|
|
230
|
+
if (ctx.raw._.length) {
|
|
231
|
+
if (ctx.called !== Root) {
|
|
232
|
+
if (ctx.name === Root) {
|
|
233
|
+
print(generateHelp(ctx, notes, examples));
|
|
234
|
+
} else {
|
|
235
|
+
print(generateSubcommandHelp(ctx, ctx.raw._));
|
|
236
|
+
}
|
|
214
237
|
}
|
|
238
|
+
} else {
|
|
239
|
+
print(generateHelp(ctx, notes, examples));
|
|
215
240
|
}
|
|
216
241
|
} else {
|
|
217
242
|
next();
|
package/dist/index.mjs
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { definePlugin,
|
|
1
|
+
import { definePlugin, Root, resolveCommand, NoSuchCommandError } from '@clerc/core';
|
|
2
2
|
import { toArray, gracefulFlagName } from '@clerc/utils';
|
|
3
3
|
import pc from 'picocolors';
|
|
4
4
|
import getFuncName from 'get-func-name';
|
|
@@ -55,24 +55,35 @@ const render = (sections) => {
|
|
|
55
55
|
};
|
|
56
56
|
|
|
57
57
|
const DELIMITER = pc.yellow("-");
|
|
58
|
+
const NO_DESCRIPTION = "(No description)";
|
|
59
|
+
const ROOT = "<Root>";
|
|
60
|
+
const NAME = "Name:";
|
|
61
|
+
const VERSION = "Version:";
|
|
62
|
+
const COMMANDS = "Commands:";
|
|
63
|
+
const SUBCOMMAND = "Subcommand:";
|
|
64
|
+
const FLAGS = "Flags:";
|
|
65
|
+
const DESCRIPTION = "Description:";
|
|
66
|
+
const USAGE = "Usage:";
|
|
67
|
+
const EXAMPLES = "Examples:";
|
|
68
|
+
const NOTES = "Notes:";
|
|
58
69
|
const print = (s) => {
|
|
59
70
|
process.stdout.write(s);
|
|
60
71
|
};
|
|
61
|
-
const formatCommandName = (name) => Array.isArray(name) ? name.join(" ") : typeof name === "string" ? name :
|
|
72
|
+
const formatCommandName = (name) => Array.isArray(name) ? name.join(" ") : typeof name === "string" ? name : ROOT;
|
|
62
73
|
const generateCliDetail = (sections, cli, subcommand) => {
|
|
63
74
|
const items = [
|
|
64
75
|
{
|
|
65
|
-
title:
|
|
76
|
+
title: NAME,
|
|
66
77
|
body: pc.red(cli._name)
|
|
67
78
|
},
|
|
68
79
|
{
|
|
69
|
-
title:
|
|
80
|
+
title: VERSION,
|
|
70
81
|
body: pc.yellow(cli._version)
|
|
71
82
|
}
|
|
72
83
|
];
|
|
73
84
|
if (subcommand) {
|
|
74
85
|
items.push({
|
|
75
|
-
title:
|
|
86
|
+
title: SUBCOMMAND,
|
|
76
87
|
body: pc.green(`${cli._name} ${formatCommandName(subcommand.name)}`)
|
|
77
88
|
});
|
|
78
89
|
}
|
|
@@ -81,14 +92,14 @@ const generateCliDetail = (sections, cli, subcommand) => {
|
|
|
81
92
|
items
|
|
82
93
|
});
|
|
83
94
|
sections.push({
|
|
84
|
-
title:
|
|
95
|
+
title: DESCRIPTION,
|
|
85
96
|
body: [(subcommand == null ? void 0 : subcommand.description) || cli._description]
|
|
86
97
|
});
|
|
87
98
|
};
|
|
88
99
|
const generateExamples = (sections, examples) => {
|
|
89
100
|
const examplesFormatted = examples.map(([command, description]) => [command, DELIMITER, description]);
|
|
90
101
|
sections.push({
|
|
91
|
-
title:
|
|
102
|
+
title: EXAMPLES,
|
|
92
103
|
body: splitTable(...examplesFormatted)
|
|
93
104
|
});
|
|
94
105
|
};
|
|
@@ -97,20 +108,30 @@ const generateHelp = (ctx, notes, examples) => {
|
|
|
97
108
|
const sections = [];
|
|
98
109
|
generateCliDetail(sections, cli);
|
|
99
110
|
sections.push({
|
|
100
|
-
title:
|
|
111
|
+
title: USAGE,
|
|
101
112
|
body: [pc.magenta(`$ ${cli._name} [command] [flags]`)]
|
|
102
113
|
});
|
|
103
|
-
const commands = [...ctx.
|
|
104
|
-
const commandNameWithAlias = [typeof command.name === "symbol" ? "" : command.name, ...toArray(command.alias || [])].
|
|
114
|
+
const commands = [...ctx.hasRoot ? [cli._commands[Root]] : [], ...Object.values(cli._commands)].map((command) => {
|
|
115
|
+
const commandNameWithAlias = [typeof command.name === "symbol" ? "" : command.name, ...toArray(command.alias || [])].sort((a, b) => {
|
|
116
|
+
if (a === Root) {
|
|
117
|
+
return -1;
|
|
118
|
+
}
|
|
119
|
+
if (b === Root) {
|
|
120
|
+
return 1;
|
|
121
|
+
}
|
|
122
|
+
return a.length - b.length;
|
|
123
|
+
}).map((n) => {
|
|
124
|
+
return n === "" || typeof n === "symbol" ? `${cli._name}` : `${cli._name} ${n}`;
|
|
125
|
+
}).join(", ");
|
|
105
126
|
return [pc.cyan(commandNameWithAlias), DELIMITER, command.description];
|
|
106
127
|
});
|
|
107
128
|
sections.push({
|
|
108
|
-
title:
|
|
129
|
+
title: COMMANDS,
|
|
109
130
|
body: splitTable(...commands)
|
|
110
131
|
});
|
|
111
132
|
if (notes) {
|
|
112
133
|
sections.push({
|
|
113
|
-
title:
|
|
134
|
+
title: NOTES,
|
|
114
135
|
body: notes
|
|
115
136
|
});
|
|
116
137
|
}
|
|
@@ -123,19 +144,22 @@ const generateSubcommandHelp = (ctx, command) => {
|
|
|
123
144
|
var _a;
|
|
124
145
|
const { cli } = ctx;
|
|
125
146
|
const subcommand = resolveCommand(cli._commands, command);
|
|
126
|
-
if (!subcommand
|
|
147
|
+
if (!subcommand) {
|
|
127
148
|
throw new NoSuchCommandError(formatCommandName(command));
|
|
128
149
|
}
|
|
129
150
|
const sections = [];
|
|
130
151
|
generateCliDetail(sections, cli, subcommand);
|
|
131
152
|
const parameters = ((_a = subcommand.parameters) == null ? void 0 : _a.join(" ")) || void 0;
|
|
153
|
+
const commandName = ctx.name === Root ? "" : ` ${formatCommandName(subcommand.name)}`;
|
|
154
|
+
const parametersString = parameters ? ` ${parameters}` : "";
|
|
155
|
+
const flagsString = subcommand.flags ? " [flags]" : "";
|
|
132
156
|
sections.push({
|
|
133
|
-
title:
|
|
134
|
-
body: [pc.magenta(`$ ${cli._name}${
|
|
157
|
+
title: USAGE,
|
|
158
|
+
body: [pc.magenta(`$ ${cli._name}${commandName}${parametersString}${flagsString}`)]
|
|
135
159
|
});
|
|
136
160
|
if (subcommand.flags) {
|
|
137
161
|
sections.push({
|
|
138
|
-
title:
|
|
162
|
+
title: FLAGS,
|
|
139
163
|
body: splitTable(
|
|
140
164
|
...Object.entries(subcommand.flags).map(([name, flag]) => {
|
|
141
165
|
const flagNameWithAlias = [gracefulFlagName(name)];
|
|
@@ -143,9 +167,7 @@ const generateSubcommandHelp = (ctx, command) => {
|
|
|
143
167
|
flagNameWithAlias.push(gracefulFlagName(flag.alias));
|
|
144
168
|
}
|
|
145
169
|
const items = [pc.blue(flagNameWithAlias.join(", "))];
|
|
146
|
-
|
|
147
|
-
items.push(DELIMITER, flag.description);
|
|
148
|
-
}
|
|
170
|
+
items.push(DELIMITER, flag.description || NO_DESCRIPTION);
|
|
149
171
|
if (flag.type) {
|
|
150
172
|
const type = stringifyType(flag.type);
|
|
151
173
|
items.push(pc.gray(`(${type})`));
|
|
@@ -157,7 +179,7 @@ const generateSubcommandHelp = (ctx, command) => {
|
|
|
157
179
|
}
|
|
158
180
|
if (subcommand.notes) {
|
|
159
181
|
sections.push({
|
|
160
|
-
title:
|
|
182
|
+
title: NOTES,
|
|
161
183
|
body: subcommand.notes
|
|
162
184
|
});
|
|
163
185
|
}
|
|
@@ -197,21 +219,24 @@ const helpPlugin = ({
|
|
|
197
219
|
});
|
|
198
220
|
}
|
|
199
221
|
cli.inspector((ctx, next) => {
|
|
200
|
-
|
|
222
|
+
const hasHelpFlag = ctx.raw.mergedFlags.h || ctx.raw.mergedFlags.help;
|
|
223
|
+
if (!ctx.hasRootOrAlias && !ctx.raw._.length && showHelpWhenNoCommand && !hasHelpFlag) {
|
|
201
224
|
let str = "No command supplied.\n\n";
|
|
202
225
|
str += generateHelp(ctx, notes, examples);
|
|
203
226
|
str += "\n";
|
|
204
227
|
print(str);
|
|
205
228
|
process.exit(1);
|
|
206
|
-
} else if (
|
|
207
|
-
if (ctx.raw._.length
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
229
|
+
} else if (hasHelpFlag) {
|
|
230
|
+
if (ctx.raw._.length) {
|
|
231
|
+
if (ctx.called !== Root) {
|
|
232
|
+
if (ctx.name === Root) {
|
|
233
|
+
print(generateHelp(ctx, notes, examples));
|
|
234
|
+
} else {
|
|
235
|
+
print(generateSubcommandHelp(ctx, ctx.raw._));
|
|
236
|
+
}
|
|
214
237
|
}
|
|
238
|
+
} else {
|
|
239
|
+
print(generateHelp(ctx, notes, examples));
|
|
215
240
|
}
|
|
216
241
|
} else {
|
|
217
242
|
next();
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@clerc/plugin-help",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.22.0",
|
|
4
4
|
"author": "Ray <nn_201312@163.com> (https://github.com/so1ve)",
|
|
5
5
|
"description": "Clerc plugin help",
|
|
6
6
|
"keywords": [
|
|
@@ -53,11 +53,11 @@
|
|
|
53
53
|
"dependencies": {
|
|
54
54
|
"get-func-name": "^2.0.0",
|
|
55
55
|
"picocolors": "^1.0.0",
|
|
56
|
-
"@clerc/toolkit": "0.
|
|
57
|
-
"@clerc/utils": "0.
|
|
56
|
+
"@clerc/toolkit": "0.22.0",
|
|
57
|
+
"@clerc/utils": "0.22.0"
|
|
58
58
|
},
|
|
59
59
|
"devDependencies": {
|
|
60
|
-
"@clerc/core": "0.
|
|
60
|
+
"@clerc/core": "0.22.0"
|
|
61
61
|
},
|
|
62
62
|
"scripts": {
|
|
63
63
|
"build": "puild",
|