@kaynooo/cli-gloss 0.0.6 → 0.0.8

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 +37 -12
  3. package/package.json +3 -3
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
@@ -1,5 +1,5 @@
1
- #!/usr/bin/env -S bun --no-env-file --config=/dev/null
2
- // @bun
1
+ #!/bin/sh
2
+ // @bun 2>/dev/null; exec bun --no-env-file --config=/dev/null "$0" "$@"
3
3
  var __esm = (fn, res, err) => () => {
4
4
  if (fn)
5
5
  try {
@@ -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 first = text.split(`
1336
- `).map((line) => line.trim()).find((line) => line !== "");
1337
- 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
+ }
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
- if (!SAFE_NAME2.test(name))
1356
- return;
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("/") ? basename(name) : name;
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 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.`;
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.6",
4
+ "version": "0.0.8",
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",
@@ -31,10 +31,10 @@
31
31
  "registry": "https://git.kaynooo.fr/api/packages/kaynooo/npm/"
32
32
  },
33
33
  "scripts": {
34
- "build": "$npm_execpath build src/gloss.ts --target bun --outdir dist",
34
+ "build": "$npm_execpath build src/gloss.ts --target bun --outdir dist && $npm_execpath ../../scripts/shell-shebang.ts",
35
35
  "gloss": "$npm_execpath src/gloss.ts"
36
36
  },
37
37
  "devDependencies": {
38
- "@kaynooo/cli-kit": "0.46.0"
38
+ "@kaynooo/cli-kit": "0.46.4"
39
39
  }
40
40
  }