@kaynooo/cli-gloss 0.0.6 → 0.0.7
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/README.md +1 -1
- package/dist/gloss.js +35 -10
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -11,7 +11,7 @@ bun add -g @kaynooo/cli-gloss
|
|
|
11
11
|
| `gloss 'tar -xzvf a.tgz -C /tmp'` | the command, then one row per option with its description, and the value each option takes |
|
|
12
12
|
| `gloss -- git commit -am fix` | the words after `--` are the command line, so no quoting is needed |
|
|
13
13
|
| `echo 'ls -la \| wc -l' \| gloss` | without arguments the command line is read from stdin |
|
|
14
|
-
| `gloss --run-help 'rg -i foo'` | for a command with no man page, runs `rg --help` and reads its options. It runs the command, so only for ones you trust: a
|
|
14
|
+
| `gloss --run-help 'rg -i foo'` | for a command with no man page, runs `rg --help` and reads its options. It runs the command, so only for ones you trust: a program found on `PATH`, by its name or its absolute path, no stdin, 3 seconds |
|
|
15
15
|
| `gloss --json 'grep -in foo file'` | `{line, commands: [{name, page, summary, notes, redirects, substitutions, next}]}` |
|
|
16
16
|
|
|
17
17
|
Pipes, `&&`, `||`, `;` and `&` split the line into commands and say what joins them. Redirects (`> out`, `2>&1`), leading variable assignments and `$(...)` substitutions are explained too, a substitution as a block of its own under the word that holds it.
|
package/dist/gloss.js
CHANGED
|
@@ -1169,10 +1169,12 @@ init_style();
|
|
|
1169
1169
|
// ../kit/src/workspace-root.ts
|
|
1170
1170
|
init_user_config();
|
|
1171
1171
|
// src/analyze.ts
|
|
1172
|
-
import { basename } from "path";
|
|
1172
|
+
import { basename as basename2 } from "path";
|
|
1173
1173
|
|
|
1174
1174
|
// src/help.ts
|
|
1175
|
+
import { realpathSync as realpathSync3 } from "fs";
|
|
1175
1176
|
import { tmpdir } from "os";
|
|
1177
|
+
import { basename } from "path";
|
|
1176
1178
|
import process17 from "process";
|
|
1177
1179
|
|
|
1178
1180
|
// src/man.ts
|
|
@@ -1331,10 +1333,35 @@ var TIMEOUT_MS = 3000;
|
|
|
1331
1333
|
var MAX_BYTES = 512 * 1024;
|
|
1332
1334
|
var MAX_SUMMARY = 100;
|
|
1333
1335
|
var USAGE_LINE = /^usage/i;
|
|
1336
|
+
var HEADER_LINE = /:$/;
|
|
1337
|
+
var VERSION_BANNER = /^\S+(?:\s+[-\u2013]|\s+version)?\s+v?\d+(?:\.\d+)+\b/i;
|
|
1334
1338
|
function summaryOf2(text) {
|
|
1335
|
-
const
|
|
1336
|
-
|
|
1337
|
-
|
|
1339
|
+
const candidates = [];
|
|
1340
|
+
for (const line of text.split(`
|
|
1341
|
+
`)) {
|
|
1342
|
+
const trimmed = line.trim();
|
|
1343
|
+
if (trimmed.startsWith("-") || HEADER_LINE.test(trimmed) && !USAGE_LINE.test(trimmed))
|
|
1344
|
+
break;
|
|
1345
|
+
if (VERSION_BANNER.test(trimmed))
|
|
1346
|
+
candidates.length = 0;
|
|
1347
|
+
else if (trimmed !== "" && line === trimmed && !USAGE_LINE.test(trimmed))
|
|
1348
|
+
candidates.push(trimmed);
|
|
1349
|
+
}
|
|
1350
|
+
const [first] = candidates;
|
|
1351
|
+
return first === undefined || first.length > MAX_SUMMARY ? undefined : first;
|
|
1352
|
+
}
|
|
1353
|
+
function programOf(name, env) {
|
|
1354
|
+
const bare = name.startsWith("/") ? basename(name) : name;
|
|
1355
|
+
if (!SAFE_NAME2.test(bare))
|
|
1356
|
+
return;
|
|
1357
|
+
const path = Bun.which(bare, { PATH: env.PATH ?? "" });
|
|
1358
|
+
if (path === null || bare === name)
|
|
1359
|
+
return path ?? undefined;
|
|
1360
|
+
try {
|
|
1361
|
+
return realpathSync3(name) === realpathSync3(path) ? path : undefined;
|
|
1362
|
+
} catch {
|
|
1363
|
+
return;
|
|
1364
|
+
}
|
|
1338
1365
|
}
|
|
1339
1366
|
function helpOf(path, args, env) {
|
|
1340
1367
|
const result = Bun.spawnSync([path, ...args, "--help"], {
|
|
@@ -1352,10 +1379,8 @@ ${result.stderr.toString()}`);
|
|
|
1352
1379
|
return text.trim() === "" ? undefined : text;
|
|
1353
1380
|
}
|
|
1354
1381
|
function loadHelp(name, subcommand, env = process17.env) {
|
|
1355
|
-
|
|
1356
|
-
|
|
1357
|
-
const path = Bun.which(name, { PATH: env.PATH ?? "" });
|
|
1358
|
-
if (path === null)
|
|
1382
|
+
const path = programOf(name, env);
|
|
1383
|
+
if (path === undefined)
|
|
1359
1384
|
return;
|
|
1360
1385
|
const attempts = subcommand !== undefined && SAFE_NAME2.test(subcommand) && !subcommand.startsWith("-") ? [[subcommand], []] : [[]];
|
|
1361
1386
|
for (const args of attempts) {
|
|
@@ -1632,7 +1657,7 @@ function analyze(line, settings = {}, depth = 0) {
|
|
|
1632
1657
|
for (const { command, next } of parseLine(line)) {
|
|
1633
1658
|
const [head, second] = command.words;
|
|
1634
1659
|
const name = head?.text ?? "";
|
|
1635
|
-
const paged = name.startsWith("/") ?
|
|
1660
|
+
const paged = name.startsWith("/") ? basename2(name) : name;
|
|
1636
1661
|
const sub = head === undefined ? undefined : describeSubcommand(paged, second, env);
|
|
1637
1662
|
const manual = sub?.page ?? (head === undefined ? undefined : loadPage(paged, env));
|
|
1638
1663
|
const page = manual ?? (runHelp && head !== undefined ? loadHelp(name, second?.text, env) : undefined);
|
|
@@ -1746,7 +1771,7 @@ function render2(line, stream = process.stdout, depth = 0) {
|
|
|
1746
1771
|
var USAGE = `gloss [options] <command line>: explains a shell command line, each option matched to what its man page says
|
|
1747
1772
|
|
|
1748
1773
|
Quote the command line or put it after --: gloss -- tar -xzvf a.tgz. Without arguments it is read from stdin.
|
|
1749
|
-
A command is looked up in the man pages on this machine; one with no man page is listed with its words unexplained, unless --run-help reads its options from '<command> --help', which runs the command (a
|
|
1774
|
+
A command is looked up in the man pages on this machine; one with no man page is listed with its words unexplained, unless --run-help reads its options from '<command> --help', which runs the command (a program found on PATH only, by its name or its absolute path, 3 seconds), so use it for commands you trust.`;
|
|
1750
1775
|
var EXITS = [[0, "it explained the line"], [2, "a usage error"]];
|
|
1751
1776
|
var OPTIONS = {
|
|
1752
1777
|
"run-help": { type: "boolean", description: "for a command with no man page, run `<command> --help` and read its options (runs the command)" },
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kaynooo/cli-gloss",
|
|
3
3
|
"type": "module",
|
|
4
|
-
"version": "0.0.
|
|
4
|
+
"version": "0.0.7",
|
|
5
5
|
"description": "gloss: explains a shell command line, each word matched to what its man page says.",
|
|
6
6
|
"author": "Kaynooo <contact@kaynooo.fr>",
|
|
7
7
|
"license": "MIT",
|
|
@@ -35,6 +35,6 @@
|
|
|
35
35
|
"gloss": "$npm_execpath src/gloss.ts"
|
|
36
36
|
},
|
|
37
37
|
"devDependencies": {
|
|
38
|
-
"@kaynooo/cli-kit": "0.46.
|
|
38
|
+
"@kaynooo/cli-kit": "0.46.2"
|
|
39
39
|
}
|
|
40
40
|
}
|