@kaynooo/cli-gloss 0.0.5 → 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 +57 -16
- 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
|
@@ -116,11 +116,14 @@ var init_config = __esm(() => {
|
|
|
116
116
|
|
|
117
117
|
// ../kit/src/user-config.ts
|
|
118
118
|
import { homedir } from "os";
|
|
119
|
-
import { join as join2 } from "path";
|
|
119
|
+
import { isAbsolute, join as join2 } from "path";
|
|
120
120
|
import process4 from "process";
|
|
121
|
+
function xdgFolder(value, fallback) {
|
|
122
|
+
return value !== undefined && isAbsolute(value) ? value : fallback;
|
|
123
|
+
}
|
|
121
124
|
function configBase(where = {}) {
|
|
122
125
|
const xdg = where.xdg ?? (where.home === undefined ? process4.env.XDG_CONFIG_HOME : undefined);
|
|
123
|
-
return xdg
|
|
126
|
+
return xdgFolder(xdg, join2(where.home ?? homedir(), ".config"));
|
|
124
127
|
}
|
|
125
128
|
function userConfigPath(bin, where = {}) {
|
|
126
129
|
return join2(configBase(where), "kaynooo-cli", `${bin}.json`);
|
|
@@ -777,6 +780,11 @@ init_format();
|
|
|
777
780
|
|
|
778
781
|
// ../kit/src/progress.ts
|
|
779
782
|
init_format();
|
|
783
|
+
|
|
784
|
+
// ../kit/src/process.ts
|
|
785
|
+
var GROUP_SIGNALS = new Set(["SIGINT", "SIGHUP"]);
|
|
786
|
+
|
|
787
|
+
// ../kit/src/progress.ts
|
|
780
788
|
init_style();
|
|
781
789
|
init_theme();
|
|
782
790
|
var ESC = String.fromCharCode(27);
|
|
@@ -921,14 +929,16 @@ init_text();
|
|
|
921
929
|
// ../kit/src/usage.ts
|
|
922
930
|
import { appendFileSync, mkdirSync } from "fs";
|
|
923
931
|
import { homedir as homedir3 } from "os";
|
|
924
|
-
import { dirname as dirname2,
|
|
932
|
+
import { dirname as dirname2, join as join4 } from "path";
|
|
925
933
|
import process13 from "process";
|
|
926
934
|
|
|
927
935
|
// ../kit/src/logs.ts
|
|
936
|
+
init_user_config();
|
|
928
937
|
var DAY_MS = 24 * 60 * 60 * 1000;
|
|
929
938
|
var CLI_FOLDER = "kaynooo-cli";
|
|
930
939
|
|
|
931
940
|
// ../kit/src/usage.ts
|
|
941
|
+
init_user_config();
|
|
932
942
|
var UNKNOWN_OPTION2 = /unknown option '(--[a-z][a-z0-9-]*)[=']/;
|
|
933
943
|
var FLAG_NAME = /^(?:--[a-z][a-z0-9-]*|-[a-zA-Z])$/;
|
|
934
944
|
var LONGEST_NAME = 40;
|
|
@@ -937,8 +947,7 @@ function noteUsageError(message) {
|
|
|
937
947
|
usageError = message;
|
|
938
948
|
}
|
|
939
949
|
function stateHome(env = process13.env) {
|
|
940
|
-
|
|
941
|
-
return dir !== undefined && isAbsolute(dir) ? dir : join4(homedir3(), ".local", "state");
|
|
950
|
+
return xdgFolder(env.XDG_STATE_HOME, join4(homedir3(), ".local", "state"));
|
|
942
951
|
}
|
|
943
952
|
function usagePath(env = process13.env) {
|
|
944
953
|
return join4(stateHome(env), CLI_FOLDER, "usage.jsonl");
|
|
@@ -1141,6 +1150,7 @@ init_style();
|
|
|
1141
1150
|
init_text();
|
|
1142
1151
|
// ../kit/src/secrets.ts
|
|
1143
1152
|
var SECRET_WORDS = new Set(["key", "pass", "pwd", "auth", "salt", "cookie", "session", "jwt", "ssn", "iban", "card", "cvv", "otp"]);
|
|
1153
|
+
var NOT_PASSWORDS = new Set(["compass", "encompass", "bypass", "overpass", "underpass", "surpass", "trespass"]);
|
|
1144
1154
|
// ../kit/src/sessions.ts
|
|
1145
1155
|
var {Glob } = globalThis.Bun;
|
|
1146
1156
|
var SESSION_FILES = new Glob("*.json");
|
|
@@ -1158,8 +1168,13 @@ init_input();
|
|
|
1158
1168
|
init_style();
|
|
1159
1169
|
// ../kit/src/workspace-root.ts
|
|
1160
1170
|
init_user_config();
|
|
1171
|
+
// src/analyze.ts
|
|
1172
|
+
import { basename as basename2 } from "path";
|
|
1173
|
+
|
|
1161
1174
|
// src/help.ts
|
|
1175
|
+
import { realpathSync as realpathSync3 } from "fs";
|
|
1162
1176
|
import { tmpdir } from "os";
|
|
1177
|
+
import { basename } from "path";
|
|
1163
1178
|
import process17 from "process";
|
|
1164
1179
|
|
|
1165
1180
|
// src/man.ts
|
|
@@ -1219,6 +1234,8 @@ function unOverstrike(text) {
|
|
|
1219
1234
|
return kept.join("");
|
|
1220
1235
|
}
|
|
1221
1236
|
function render(source) {
|
|
1237
|
+
if (Bun.which("nroff") === null)
|
|
1238
|
+
return;
|
|
1222
1239
|
const result = Bun.spawnSync(["nroff", "-man", "-Tutf8", "-rLL=200n", "-rLT=200n"], { stdin: source, stdout: "pipe", stderr: "ignore", env: { ...process16.env, GROFF_NO_SGR: "1" } });
|
|
1223
1240
|
if (result.exitCode !== 0)
|
|
1224
1241
|
return;
|
|
@@ -1316,10 +1333,35 @@ var TIMEOUT_MS = 3000;
|
|
|
1316
1333
|
var MAX_BYTES = 512 * 1024;
|
|
1317
1334
|
var MAX_SUMMARY = 100;
|
|
1318
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;
|
|
1319
1338
|
function summaryOf2(text) {
|
|
1320
|
-
const
|
|
1321
|
-
|
|
1322
|
-
|
|
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
|
+
}
|
|
1323
1365
|
}
|
|
1324
1366
|
function helpOf(path, args, env) {
|
|
1325
1367
|
const result = Bun.spawnSync([path, ...args, "--help"], {
|
|
@@ -1337,10 +1379,8 @@ ${result.stderr.toString()}`);
|
|
|
1337
1379
|
return text.trim() === "" ? undefined : text;
|
|
1338
1380
|
}
|
|
1339
1381
|
function loadHelp(name, subcommand, env = process17.env) {
|
|
1340
|
-
|
|
1341
|
-
|
|
1342
|
-
const path = Bun.which(name, { PATH: env.PATH ?? "" });
|
|
1343
|
-
if (path === null)
|
|
1382
|
+
const path = programOf(name, env);
|
|
1383
|
+
if (path === undefined)
|
|
1344
1384
|
return;
|
|
1345
1385
|
const attempts = subcommand !== undefined && SAFE_NAME2.test(subcommand) && !subcommand.startsWith("-") ? [[subcommand], []] : [[]];
|
|
1346
1386
|
for (const args of attempts) {
|
|
@@ -1428,7 +1468,7 @@ function explain(words, options) {
|
|
|
1428
1468
|
|
|
1429
1469
|
// src/shell.ts
|
|
1430
1470
|
var REDIRECT = /&>>?|>&|<&|<<<|<<-?|>>|>\||>|</y;
|
|
1431
|
-
var CONTROL2 =
|
|
1471
|
+
var CONTROL2 = /\|[&|]?|&&|&(?!>)|[;\n]/y;
|
|
1432
1472
|
var ASSIGN = /^[A-Z_]\w*\+?=/i;
|
|
1433
1473
|
var FD = /\d+(?=[<>])/y;
|
|
1434
1474
|
var ESCAPABLE_IN_QUOTES = new Set(['"', "\\", "$", "`"]);
|
|
@@ -1617,8 +1657,9 @@ function analyze(line, settings = {}, depth = 0) {
|
|
|
1617
1657
|
for (const { command, next } of parseLine(line)) {
|
|
1618
1658
|
const [head, second] = command.words;
|
|
1619
1659
|
const name = head?.text ?? "";
|
|
1620
|
-
const
|
|
1621
|
-
const
|
|
1660
|
+
const paged = name.startsWith("/") ? basename2(name) : name;
|
|
1661
|
+
const sub = head === undefined ? undefined : describeSubcommand(paged, second, env);
|
|
1662
|
+
const manual = sub?.page ?? (head === undefined ? undefined : loadPage(paged, env));
|
|
1622
1663
|
const page = manual ?? (runHelp && head !== undefined ? loadHelp(name, second?.text, env) : undefined);
|
|
1623
1664
|
const fromHelp = manual === undefined && page !== undefined;
|
|
1624
1665
|
const words = command.words.slice(sub === undefined && !(fromHelp && page?.name.includes(" ")) ? 1 : 2);
|
|
@@ -1730,7 +1771,7 @@ function render2(line, stream = process.stdout, depth = 0) {
|
|
|
1730
1771
|
var USAGE = `gloss [options] <command line>: explains a shell command line, each option matched to what its man page says
|
|
1731
1772
|
|
|
1732
1773
|
Quote the command line or put it after --: gloss -- tar -xzvf a.tgz. Without arguments it is read from stdin.
|
|
1733
|
-
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.`;
|
|
1734
1775
|
var EXITS = [[0, "it explained the line"], [2, "a usage error"]];
|
|
1735
1776
|
var OPTIONS = {
|
|
1736
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.
|
|
38
|
+
"@kaynooo/cli-kit": "0.46.2"
|
|
39
39
|
}
|
|
40
40
|
}
|