@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.
Files changed (3) hide show
  1. package/README.md +1 -1
  2. package/dist/gloss.js +57 -16
  3. 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 bare name found on `PATH`, no stdin, 3 seconds |
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 !== undefined && xdg !== "" ? xdg : join2(where.home ?? homedir(), ".config");
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, isAbsolute, join as join4 } from "path";
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
- const dir = env.XDG_STATE_HOME;
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 first = text.split(`
1321
- `).map((line) => line.trim()).find((line) => line !== "");
1322
- return first === undefined || first.length > MAX_SUMMARY || USAGE_LINE.test(first) || first.startsWith("-") ? undefined : first;
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
- if (!SAFE_NAME2.test(name))
1341
- return;
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 = /\|&|\|\||\||&&|[&;\n]/y;
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 sub = head === undefined ? undefined : describeSubcommand(name, second, env);
1621
- const manual = sub?.page ?? (head === undefined ? undefined : loadPage(name, env));
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 bare name found on PATH only, 3 seconds), so use it for commands you trust.`;
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.5",
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.45.1"
38
+ "@kaynooo/cli-kit": "0.46.2"
39
39
  }
40
40
  }