@kaynooo/cli-out 0.7.0 → 0.8.0

package/README.md

@@ -7,6 +7,7 @@ bun install -g @kaynooo/cli-out
 out -- bun install
 bun run build 2>&1 | out
 out --stats --since 7d
+out --grep 'error TS'
 ```
 
 ## Behaviour
@@ -20,14 +21,19 @@ out --stats --since 7d
 - The head and tail are kept, and lines with `error`, `fail`, `warn`, `panic`, `exception`, `fatal` or a stack frame stay even in the folded middle, the first 40 of them. Lines wider than 300 characters are cut in the folded output (the full log keeps them), and a few-lines output that is still heavy keeps a shorter head and tail.
 - The exit code is always the wrapped command's. Piped into with no command, `out` folds what it reads and exits 0, the writer's code left to `set -o pipefail`; only stdout is piped, so `2>&1` brings stderr along. A terminal or `/dev/null` on stdin with no command is a usage error.
 - The output is streamed to a full log as it arrives once it outgrows the 4 MiB held in memory (the first and last 2 MiB), otherwise the log is written when folding. Logs go to `$XDG_RUNTIME_DIR/kaynooo-cli/out` (`~/.cache/kaynooo-cli/out` without it), a folder only the user can enter, files at mode 0600, and logs older than a day are removed on the next run.
-- SIGINT, SIGTERM and SIGHUP go to the command's whole process group, and `out` exits with its code. A watch command (`--watch`, `tsc -w`, `just dev`) is never wrapped by the hook, as its output would sit buffered.
+- SIGINT, SIGTERM and SIGHUP go to the command's whole process group, and `out` exits with its code. A watch command (`--watch`, `tsc -w`, `just dev`) is never wrapped by `guard`, as its output would sit buffered.
+
+## Saved logs
+
+- `out --last` prints the path of the most recent full log, `out --list` lists them (path, size, age, newest first) and `out --grep <regex>` prints the matching lines of the last log, or of the one `--log <name|path>` names, each as `N: line` with N the line number the folded output's `(same as line N)` refers to.
+- Exit 0 when found, 1 when `--grep` matches nothing or `--list` finds no log, 2 when there is no saved log to read or the regex is invalid. A run saves a log only when its output was folded, and logs older than a day are removed.
 
 ## Stats
 
 - Each run appends a line to `$XDG_STATE_HOME/kaynooo-cli/out/stats.jsonl` (`~/.local/state/...` without it, folder 0700, file 0600): the time, the folder, the words naming the command, the bytes it printed, the bytes the session would have read without `out` and the bytes `out` showed. Only lowercase words without digits after the program are kept (`bun run build`, `docker compose exec`), so no argument, assignment or token reaches the file; a `sh -c` chain is named by its last command that is not a `cd`.
-- `--was '<stage>'` (repeatable, in pipeline order) names a `tail`, `head` or `grep` stage `out` stands in for, as the hook passes them when it drops one: the session would have read what that stage printed, so the saving counts against it. Output that folding would not make shorter is printed untouched, so `out` never shows more than the command printed. A stage it cannot read (`tail -f`, a long grep option it does not know) counts the whole output.
+- `--was '<stage>'` (repeatable, in pipeline order) names a `tail`, `head` or `grep` stage `out` stands in for, as `guard` passes them when it drops one: the session would have read what that stage printed, so the saving counts against it. Output that folding would not make shorter is printed untouched, so `out` never shows more than the command printed. A stage it cannot read (`tail -f`, a long grep option it does not know) counts the whole output.
 - `out --stats [--since 7d] [--json]` prints the runs, how many were folded, the bytes printed and shown, and about how many tokens were saved (bytes / 4, an estimate), then the ten commands that saved the most, with the share of runs folded and, per command, the median share of the output a folded run cut.
 
-## Wrapping from a hook
+## Wrapping from guard
 
-The pure functions a Claude Code PreToolUse hook needs live in `src/wrap.ts`: `shouldWrap(command)` is true when every part of a command line is a listed noisy command (installs, builds, test runners, linters, `docker build`/`docker compose build|pull`, `just <recipe>`), with no pipe, redirect, background, substitution, `--json` or `--help`. A runner is known by its last path segment (`vendor/bin/phpunit`), through `php` (`php bin/phpunit`) and inside `docker compose exec|run` or `docker exec` (`docker compose exec -T php vendor/bin/paratest`). A line ending in pipes into `tail` or `head` keeping at least 150 lines (`-n 200`, `-200`, `--lines=200`), out's fold size, is wrapped with those stages and the `2>&1` feeding them dropped, since the folded output is no longer and keeps the failures they would have picked out; a `grep` or a shorter cut shows less than `out` would, so that line is left as it is. `wrap(command)` returns `out -- <command>`, through `sh -c '...'` for `&&` chains and leading `VAR=value` assignments, each dropped stage passed ahead as `--was '<stage>'`. The guard hook imports them from this package.
+The pure functions `guard` needs to wrap a command live in `src/wrap.ts`: `shouldWrap(command)` is true when every part of a command line is a listed noisy command (installs, builds, test runners, linters, `docker build`/`docker compose build|pull`, `just <recipe>`), with no pipe, redirect, background, substitution, `--json` or `--help`. A runner is known by its last path segment (`vendor/bin/phpunit`), through `php` (`php bin/phpunit`) and inside `docker compose exec|run` or `docker exec` (`docker compose exec -T php vendor/bin/paratest`). A line ending in pipes into `tail` or `head` keeping at least 150 lines (`-n 200`, `-200`, `--lines=200`), out's fold size, is wrapped with those stages and the `2>&1` feeding them dropped, since the folded output is no longer and keeps the failures they would have picked out; a `grep` or a shorter cut shows less than `out` would, so that line is left as it is. `wrap(command)` returns `out -- <command>`, through `sh -c '...'` for `&&` chains and leading `VAR=value` assignments, each dropped stage passed ahead as `--was '<stage>'`. The `guard` command imports them to rewrite a command into `out -- ...`; its Claude Code hook never wraps, since a hook cannot swap a command without approving it, and refuses with the command to run instead.

package/dist/cli.js

@@ -2,18 +2,16 @@
 // @bun
 
 // src/cli.ts
-import process11 from "process";
-
+import process14 from "process";
 // ../kit/src/args.ts
-import { fstatSync } from "fs";
-import process3 from "process";
+import process5 from "process";
 import { parseArgs } from "util";
 
 // ../kit/src/format.ts
-import process2 from "process";
+import process3 from "process";
 
 // ../kit/src/style.ts
-import process from "process";
+import process2 from "process";
 
 // ../../node_modules/.bun/@kaynooo+utils@2.31.2+d0769e28dc4dad16/node_modules/@kaynooo/utils/dist/chunk-mtetydvc.js
 function x(s) {
@@ -277,10 +275,10 @@ function le(i = {}) {
 var t = le();
 
 // ../kit/src/style.ts
-function takesControlCodes(stream, env = process.env) {
+function takesControlCodes(stream, env = process2.env) {
   return stream.isTTY === true && env.NO_COLOR === undefined && env.NODE_DISABLE_COLORS === undefined && env.TERM !== "dumb";
 }
-function paint(stream, env = process.env) {
+function paint(stream, env = process2.env) {
   return le({ stream: { isTTY: takesControlCodes(stream, env) }, env });
 }
 var STATUSES = {
@@ -293,10 +291,31 @@ var STATUSES = {
 var STATUS_OF = new Map(Object.entries(STATUSES).flatMap(([status, { words }]) => words.map((word) => [word, status])));
 
 // ../kit/src/format.ts
+var UNITS = [["d", 86400], ["h", 3600], ["m", 60], ["s", 1]];
+function formatSeconds(total) {
+  let rest = Math.max(0, Math.round(total));
+  const amounts = UNITS.map(([unit, size]) => {
+    const amount = Math.floor(rest / size);
+    rest -= amount * size;
+    return `${amount}${unit}`;
+  });
+  const first = amounts.findIndex((amount) => !amount.startsWith("0"));
+  if (first === -1)
+    return "0s";
+  const next = amounts[first + 1];
+  return next === undefined || next.startsWith("0") ? amounts[first] ?? "0s" : `${amounts[first]} ${next}`;
+}
 function upTo(text, separator) {
   const end = text.indexOf(separator);
   return end === -1 ? text : text.slice(0, end);
 }
+function formatAge(date, now = Date.now()) {
+  const at = typeof date === "number" ? date : Date.parse(date);
+  if (Number.isNaN(at))
+    return "-";
+  const seconds = (now - at) / 1000;
+  return seconds < 60 ? "just now" : `${upTo(formatSeconds(seconds), " ")} ago`;
+}
 function truncate(text, width) {
   return text.length <= width ? text : `${text.slice(0, Math.max(0, width - 1))}\u2026`;
 }
@@ -313,7 +332,7 @@ function table(rows, { cellWidth, header = false, align = [], fit } = {}) {
       widths[index] = Math.max(widths[index] ?? 0, textWidth(cell));
   }
   const shown = fit === undefined ? cells : narrow(cells, widths, fit);
-  const colors = paint(process2.stdout);
+  const colors = paint(process3.stdout);
   const lines = shown.map((row) => row.map((cell, index) => {
     const width = widths[index] ?? 0;
     const gap = " ".repeat(Math.max(0, width - textWidth(cell)));
@@ -344,6 +363,63 @@ function printJson(value) {
   console.log(JSON.stringify(value, undefined, 2));
 }
 
+// ../kit/src/help.ts
+import process4 from "process";
+var OPTIONAL = /\[[^\]]+\]/g;
+var USAGE_PREFIX = /^usage:\s*/i;
+var FULL_STOP = /\.$/;
+function usageLine(usage, colors = paint(process4.stdout)) {
+  return `${colors.bold("Usage:")} ${usage.replace(USAGE_PREFIX, "").replaceAll(OPTIONAL, (part) => colors.dim(part))}`;
+}
+function helpText(usage, options, colors = paint(process4.stdout), { examples = [], replaces, exits = [] } = {}) {
+  return [usageLine(usage, colors), ...replacesRows(replaces, colors), "", colors.bold("Options:"), ...optionRows(options, colors), ...exitRows(exits, colors), ...exampleRows(examples, colors)].join(`
+`);
+}
+function exitRows(exits, colors = paint(process4.stdout)) {
+  if (exits.length === 0)
+    return [];
+  const width = Math.max(...exits.map(([code]) => String(code).length));
+  return ["", colors.bold("Exits:"), ...exits.map(([code, meaning]) => `  ${colors.cyan(String(code).padEnd(width))}  ${meaning}`)];
+}
+function replacesRows(replaces, colors = paint(process4.stdout)) {
+  return replaces === undefined ? [] : ["", `${colors.bold("Instead of:")} ${replaces}`];
+}
+function wantsHelpJson(env = process4.env) {
+  return env.KIT_HELP === "json";
+}
+function description(usage, { examples = [], replaces, exits } = {}, options) {
+  const lines = usage.replace(USAGE_PREFIX, "").split(`
+`);
+  const first = lines[0];
+  const colon = first.indexOf(": ");
+  const prose = lines[lines.indexOf("") + 1] ?? "";
+  const fallback = lines.includes("") ? `${prose.charAt(0).toLowerCase()}${prose.slice(1)}`.replace(FULL_STOP, "") : "";
+  return {
+    synopsis: colon === -1 ? first : first.slice(0, colon),
+    summary: colon === -1 ? fallback : first.slice(colon + 2),
+    ...replaces === undefined ? {} : { replaces },
+    examples: examples.map((example) => typeof example === "string" ? { line: example } : { line: example[0], note: example[1] }),
+    ...exits === undefined ? {} : { exits: exits.map(([code, meaning]) => ({ code, meaning })) },
+    ...options === undefined ? {} : { options: Object.entries(options).map(([name, { short, description }]) => ({ name, ...short === undefined ? {} : { short }, ...description === undefined ? {} : { description } })) }
+  };
+}
+function exampleRows(examples, colors = paint(process4.stdout)) {
+  if (examples.length === 0)
+    return [];
+  return ["", colors.bold("Examples:"), ...examples.map((example) => typeof example === "string" ? `  ${example}` : `  ${example[0]}  ${colors.dim(`# ${example[1]}`)}`)];
+}
+function optionRows(options, colors = paint(process4.stdout)) {
+  const rows = Object.entries(options).map(([name, option]) => {
+    const short = option.short === undefined ? "    " : `${colors.cyan(`-${option.short}`)}, `;
+    const named = option.choices === undefined ? "<value>" : `<${option.choices.join("|")}>`;
+    const placeholder = option.optional === undefined ? named : `[${named}]`;
+    const value = option.type === "string" ? ` ${colors.dim(placeholder)}` : "";
+    return { flag: `${short}${colors.cyan(`--${name}`)}${value}`, width: `-x, --${name}`.length + (option.type === "string" ? placeholder.length + 1 : 0), description: option.description ?? "" };
+  });
+  const width = Math.max(0, ...rows.map((row) => row.width));
+  return rows.map((row) => row.description === "" ? `  ${row.flag}` : `  ${row.flag}${" ".repeat(width - row.width)}  ${colors.dim(row.description)}`);
+}
+
 // ../kit/src/text.ts
 var ANSI = new RegExp(`${String.fromCharCode(27)}\\[[\\d;?]*[a-z]`, "gi");
 function stripAnsi(text) {
@@ -366,8 +442,35 @@ function closest(name, names) {
   const [best] = names.map((known) => ({ known, far: distance(name, known) })).sort((a, b) => a.far - b.far);
   return best !== undefined && best.far <= (name.length < 4 ? 1 : 2) ? best.known : undefined;
 }
+// ../kit/src/input.ts
+import { fstatSync } from "fs";
+var WHOLE = /^\d+$/;
+function wholeNumber(value, name, fallback, min = 1) {
+  if (value === undefined)
+    return fallback;
+  const number = Number(value);
+  if (!WHOLE.test(value) || !Number.isSafeInteger(number) || number < min)
+    badUsage(`${name.startsWith("<") ? name : `--${name}`} takes a whole number from ${min}, not ${value}`);
+  return number;
+}
+var DURATION = /^(\d+(?:\.\d+)?)(ms|[smhd])?$/;
+var UNIT_MS = { ms: 1, s: 1000, m: 60000, h: 3600000, d: 86400000 };
+function duration(value, name, fallback, unit = "s") {
+  if (value === undefined)
+    return fallback;
+  const match = DURATION.exec(value.trim());
+  const ms = match === null ? 0 : Number(match[1]) * UNIT_MS[match[2] ?? unit];
+  if (ms < 1)
+    badUsage(`--${name} takes a duration such as 30s, 5m, 1h or 7d, not ${value}`);
+  return ms;
+}
+function isStdinPiped() {
+  const stat = fstatSync(0);
+  return stat.isFIFO() || stat.isFile();
+}
 
 // ../kit/src/args.ts
+var DASHES = /^-+/;
 function jsonOption(holds) {
   return { type: "boolean", description: holds === undefined ? "print JSON" : `print JSON: ${holds}` };
 }
@@ -411,58 +514,11 @@ class Completing {
   }
 }
 var completion = { active: false };
-var OPTIONAL = /\[[^\]]+\]/g;
-var USAGE_PREFIX = /^usage:\s*/i;
-var FULL_STOP = /\.$/;
-var DASHES = /^-+/;
-function usageLine(usage, colors = paint(process3.stdout)) {
-  return `${colors.bold("Usage:")} ${usage.replace(USAGE_PREFIX, "").replaceAll(OPTIONAL, (part) => colors.dim(part))}`;
-}
-function helpText(usage, options, colors = paint(process3.stdout), { examples = [], replaces } = {}) {
-  return [usageLine(usage, colors), ...replacesRows(replaces, colors), "", colors.bold("Options:"), ...optionRows(options, colors), ...exampleRows(examples, colors)].join(`
-`);
-}
-function replacesRows(replaces, colors = paint(process3.stdout)) {
-  return replaces === undefined ? [] : ["", `${colors.bold("Instead of:")} ${replaces}`];
-}
-function wantsHelpJson(env = process3.env) {
-  return env.KIT_HELP === "json";
-}
-function description(usage, { examples = [], replaces } = {}) {
-  const lines = usage.replace(USAGE_PREFIX, "").split(`
-`);
-  const first = lines[0];
-  const colon = first.indexOf(": ");
-  const prose = lines[lines.indexOf("") + 1] ?? "";
-  const fallback = lines.includes("") ? `${prose.charAt(0).toLowerCase()}${prose.slice(1)}`.replace(FULL_STOP, "") : "";
-  return {
-    synopsis: colon === -1 ? first : first.slice(0, colon),
-    summary: colon === -1 ? fallback : first.slice(colon + 2),
-    ...replaces === undefined ? {} : { replaces },
-    examples: examples.map((example) => typeof example === "string" ? { line: example } : { line: example[0], note: example[1] })
-  };
-}
-function exampleRows(examples, colors = paint(process3.stdout)) {
-  if (examples.length === 0)
-    return [];
-  return ["", colors.bold("Examples:"), ...examples.map((example) => typeof example === "string" ? `  ${example}` : `  ${example[0]}  ${colors.dim(`# ${example[1]}`)}`)];
-}
-function optionRows(options, colors = paint(process3.stdout)) {
-  const rows = Object.entries(options).map(([name, option]) => {
-    const short = option.short === undefined ? "    " : `${colors.cyan(`-${option.short}`)}, `;
-    const named = option.choices === undefined ? "<value>" : `<${option.choices.join("|")}>`;
-    const placeholder = option.optional === undefined ? named : `[${named}]`;
-    const value = option.type === "string" ? ` ${colors.dim(placeholder)}` : "";
-    return { flag: `${short}${colors.cyan(`--${name}`)}${value}`, width: `-x, --${name}`.length + (option.type === "string" ? placeholder.length + 1 : 0), description: option.description ?? "" };
-  });
-  const width = Math.max(0, ...rows.map((row) => row.width));
-  return rows.map((row) => row.description === "" ? `  ${row.flag}` : `  ${row.flag}${" ".repeat(width - row.width)}  ${colors.dim(row.description)}`);
-}
 var OUTPUT_OPTIONS = {
   color: { type: "string", description: "auto (on a terminal alone), always or never" },
   plain: { type: "boolean", description: "plain text, no colour or spinner: --color never" }
 };
-function applyOutput(color, plain, env = process3.env) {
+function applyOutput(color, plain, env = process5.env) {
   const when = plain === true ? "never" : color ?? "auto";
   if (when === "auto")
     return;
@@ -485,7 +541,7 @@ function parse(args, usage, options, settings = {}) {
   const { own, rest } = settings.trailing === true ? splitTrailing(args, all, settings.positionals?.length ?? 0) : splitRest(args, settings.rest === true);
   let parsed;
   try {
-    parsed = parseArgs({ args: joinDashValues(withBare(own, all), all), options: all, allowPositionals: true, allowNegative: settings.allowNegative === true, strict: true });
+    parsed = parseArgs({ args: joinDashValues(withBare(withAliases(own, all), all), all), options: all, allowPositionals: true, allowNegative: settings.allowNegative === true, strict: true });
   } catch (error) {
     const message = parseError(error);
     throw new UsageError(message, nearestOption(message, all, settings.allowNegative === true));
@@ -493,7 +549,7 @@ function parse(args, usage, options, settings = {}) {
   const values = parsed.values;
   applyOutput("color" in output ? values.color : undefined, "plain" in output ? values.plain : undefined);
   if (values.help === true) {
-    console.log(wantsHelpJson() ? JSON.stringify(description(usage, settings)) : helpText(usage, listing, undefined, settings));
+    console.log(wantsHelpJson() ? JSON.stringify(description(usage, settings, listing)) : helpText(usage, listing, undefined, settings));
     throw new HelpShown;
   }
   checkChoices(parsed.values, all);
@@ -535,6 +591,18 @@ function listed(options, allowNegative) {
     return [...option.description === undefined ? [] : [[name, option]], [`no-${name}`, { type: "boolean", description: option.negative }]];
   }));
 }
+function withAliases(args, options) {
+  const named = new Map(Object.entries(options).flatMap(([name, { aliases = [] }]) => aliases.map((alias) => [`--${alias}`, `--${name}`])));
+  if (named.size === 0)
+    return args;
+  const separator = args.indexOf("--");
+  const own = separator === -1 ? args : args.slice(0, separator);
+  return [...own.map((arg) => {
+    const at = arg.indexOf("=");
+    const current = named.get(at === -1 ? arg : arg.slice(0, at));
+    return current === undefined ? arg : `${current}${at === -1 ? "" : arg.slice(at)}`;
+  }), ...separator === -1 ? [] : args.slice(separator)];
+}
 function withBare(args, options) {
   const bare = new Map(Object.entries(options).flatMap(([name, { short, optional }]) => optional === undefined ? [] : [[`--${name}`, optional], ...short === undefined ? [] : [[`-${short}`, optional]]]));
   if (bare.size === 0)
@@ -619,33 +687,9 @@ function nearestOption(message, options, allowNegative) {
   const meant = closest(word, known.map((flag) => flag.replace(DASHES, "")));
   return meant === undefined ? undefined : `did you mean ${known.find((flag) => flag.replace(DASHES, "") === meant)}?`;
 }
-var WHOLE = /^\d+$/;
-function wholeNumber(value, name, fallback, min = 1) {
-  if (value === undefined)
-    return fallback;
-  const number = Number(value);
-  if (!WHOLE.test(value) || !Number.isSafeInteger(number) || number < min)
-    badUsage(`${name.startsWith("<") ? name : `--${name}`} takes a whole number from ${min}, not ${value}`);
-  return number;
-}
-var DURATION = /^(\d+(?:\.\d+)?)(ms|[smhd])?$/;
-var UNIT_MS = { ms: 1, s: 1000, m: 60000, h: 3600000, d: 86400000 };
-function duration(value, name, fallback, unit = "s") {
-  if (value === undefined)
-    return fallback;
-  const match = DURATION.exec(value.trim());
-  const ms = match === null ? 0 : Number(match[1]) * UNIT_MS[match[2] ?? unit];
-  if (ms < 1)
-    badUsage(`--${name} takes a duration such as 30s, 5m, 1h or 7d, not ${value}`);
-  return ms;
-}
-function isStdinPiped() {
-  const stat = fstatSync(0);
-  return stat.isFIFO() || stat.isFile();
-}
 // ../kit/src/process.ts
 import { constants } from "os";
-import process4 from "process";
+import process6 from "process";
 var KILL_GRACE_MS = 2000;
 var SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
 function exitCodeOf(code, signal) {
@@ -667,7 +711,7 @@ function holdSignals(cleanup) {
     },
     release: () => {
       for (const signal of SIGNALS)
-        process4.off(signal, onSignal);
+        process6.off(signal, onSignal);
     }
   };
   function onSignal(signal) {
@@ -680,10 +724,10 @@ function holdSignals(cleanup) {
       return;
     held.release();
     cleanup(signal);
-    process4.kill(process4.pid, signal);
+    process6.kill(process6.pid, signal);
   }
   for (const signal of SIGNALS)
-    process4.on(signal, onSignal);
+    process6.on(signal, onSignal);
   return held;
 }
 async function runCommand(argv, { cwd, env, stdin = "ignore", timeoutMs, signal, maxBytes = Infinity, onChunk, onStart } = {}) {
@@ -697,7 +741,7 @@ async function runCommand(argv, { cwd, env, stdin = "ignore", timeoutMs, signal,
       return;
     try {
       if (grouped)
-        process4.kill(-proc.pid, killing);
+        process6.kill(-proc.pid, killing);
       else
         proc.kill(killing);
     } catch {}
@@ -771,15 +815,116 @@ var ESCAPE_CODE = new RegExp(`${ESC}(?:\\[[\\x30-\\x3F]*[\\x20-\\x2F]*[\\x40-\\x
 var RESET_STYLE = `${ESC}[0m`;
 var CLOSE_LINK = `${ESC}]8;;${ESC}\\`;
 // ../kit/src/cli.ts
-import process5 from "process";
+import { readFileSync, realpathSync } from "fs";
+import { dirname as dirname2, join as join3 } from "path";
+import process9 from "process";
+
+// ../kit/src/usage.ts
+import { appendFileSync, mkdirSync } from "fs";
+import { homedir as homedir2 } from "os";
+import { dirname, isAbsolute, join as join2 } from "path";
+import process8 from "process";
+
+// ../kit/src/logs.ts
+import { lstatSync, openSync } from "fs";
+import { mkdir, mkdtemp, readdir, rm, stat } from "fs/promises";
+import { homedir, tmpdir } from "os";
+import { join } from "path";
+import process7 from "process";
+var DAY_MS = 24 * 60 * 60 * 1000;
+var CLI_FOLDER = "kaynooo-cli";
+function isPrivateDirectory(path) {
+  try {
+    const info = lstatSync(path, { throwIfNoEntry: false });
+    return info !== undefined && info.isDirectory() && info.uid === (process7.getuid?.() ?? info.uid) && (info.mode & 63) === 0;
+  } catch {
+    return false;
+  }
+}
+async function privateLogDirectory(name, env = process7.env) {
+  const runtime = env.XDG_RUNTIME_DIR;
+  const base = runtime === undefined || runtime === "" ? join(homedir(), ".cache", CLI_FOLDER) : join(runtime, CLI_FOLDER);
+  const path = join(base, name);
+  try {
+    await mkdir(path, { recursive: true, mode: 448 });
+    if (isPrivateDirectory(path))
+      return path;
+  } catch {}
+  return mkdtemp(join(tmpdir(), `${name.replaceAll("/", "-")}-`));
+}
+async function sweepLogs(dir, maxAgeMs = DAY_MS, now = Date.now()) {
+  let names;
+  try {
+    names = await readdir(dir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    const path = join(dir, name);
+    try {
+      const info = await stat(path);
+      if (info.isDirectory())
+        await sweepLogs(path, maxAgeMs, now);
+      if (now - info.mtimeMs > maxAgeMs)
+        await rm(path, { force: true, recursive: info.isDirectory() });
+    } catch {
+      continue;
+    }
+  }
+}
+function createLog(path) {
+  return openSync(path, "wx", 384);
+}
+
+// ../kit/src/usage.ts
+var UNKNOWN_OPTION2 = /unknown option '(--[a-z][a-z0-9-]*)[=']/;
+var FLAG_NAME = /^(?:--[a-z][a-z0-9-]*|-[a-zA-Z])$/;
+var LONGEST_NAME = 40;
+var usageError;
+function noteUsageError(message) {
+  usageError = message;
+}
+function stateHome(env = process8.env) {
+  const dir = env.XDG_STATE_HOME;
+  return dir !== undefined && isAbsolute(dir) ? dir : join2(homedir2(), ".local", "state");
+}
+function usagePath(env = process8.env) {
+  return join2(stateHome(env), CLI_FOLDER, "usage.jsonl");
+}
+function usageRecorded(env = process8.env) {
+  const off = env.KAYNOOO_CLI_NO_USAGE;
+  return env.NODE_ENV !== "test" && (off === undefined || off === "" || off === "0");
+}
+function flagNames(argv) {
+  const end = argv.indexOf("--");
+  const names = (end === -1 ? argv : argv.slice(0, end)).filter((word) => word.startsWith("-") && word !== "-").map((word) => word.includes("=") ? word.slice(0, word.indexOf("=")) : word);
+  return [...new Set(names)].filter((name) => name.length <= LONGEST_NAME && FLAG_NAME.test(name));
+}
+function usageEntry(bin, command, argv, code, now = new Date) {
+  const unknown = code === 2 && usageError !== undefined ? UNKNOWN_OPTION2.exec(usageError)?.[1] : undefined;
+  usageError = undefined;
+  return { at: now.toISOString(), bin, ...command === undefined ? {} : { command }, flags: flagNames(argv), code, ...unknown === undefined ? {} : { unknown } };
+}
+function recordUsage(entry, env = process8.env) {
+  if (!usageRecorded(env))
+    return;
+  try {
+    const path = usagePath(env);
+    mkdirSync(dirname(path), { recursive: true, mode: 448 });
+    appendFileSync(path, `${JSON.stringify(entry)}
+`, { mode: 384 });
+  } catch {}
+}
+
+// ../kit/src/cli.ts
 var LEVEL_OPTIONS = {
   ...OUTPUT_OPTIONS,
   help: { type: "boolean", short: "h", description: "show this help" }
 };
 var TOP_OPTIONS = { ...LEVEL_OPTIONS, version: { type: "boolean", short: "v", description: "print the version" } };
 function printError(prefix, message, hint, cause) {
-  const colors = paint(process5.stderr);
-  const styled = takesControlCodes(process5.stderr);
+  const colors = paint(process9.stderr);
+  const styled = takesControlCodes(process9.stderr);
   const head = styled ? `${colors.red.bold("error")} ${colors.dim(`${prefix}:`)}` : `error: ${prefix}:`;
   const under = (label, text, tint) => text === undefined ? "" : `
   ${styled ? tint(label) : `${label}:`} ${text}`;
@@ -798,6 +943,8 @@ function reportThrown(prefix, error, redact = (text) => text, json = false) {
   const help = error instanceof UsageError ? `run ${prefix} --help for its options` : undefined;
   const named = error instanceof Error && !(error instanceof Exit) && error.name !== "Error" ? `${error.name}: ${error.message}` : undefined;
   const cause = error instanceof Error && error.cause instanceof Error ? redact(error.cause.message) : undefined;
+  if (error instanceof UsageError)
+    noteUsageError(error.message);
   const report = json ? printJsonError : (message, hint, causeText) => printError(prefix, message, hint, causeText);
   report(redact(named ?? (error instanceof Error ? error.message : String(error))), error instanceof Exit ? error.hint ?? help : undefined, cause);
   return error instanceof Exit ? error.code : 1;
@@ -859,68 +1006,36 @@ async function printCandidates(found) {
     console.log(line);
   return 0;
 }
-async function runMain({ name, version, run, redact }, argv = process5.argv.slice(2)) {
+function packageVersion(entry = Bun.main) {
+  for (let dir = dirname2(realpathSync(entry));; dir = dirname2(dir)) {
+    try {
+      const { version } = JSON.parse(readFileSync(join3(dir, "package.json"), "utf8"));
+      if (typeof version === "string")
+        return version;
+    } catch {}
+    if (dirname2(dir) === dir)
+      return "0.0.0";
+  }
+}
+async function runMain({ name, version, run, redact, usage }, argv = process9.argv.slice(2)) {
   if (argv[0] === COMPLETE)
     return printCandidates(leafCandidates(run, argv.slice(1)));
   if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "-v")) {
-    console.log(version);
+    console.log(version ?? packageVersion());
     return 0;
   }
+  let code;
   try {
-    return await run(argv);
+    code = await run(argv);
   } catch (error) {
-    return reportThrown(name, error, redact, wantsJson(argv));
+    code = reportThrown(name, error, redact, wantsJson(argv));
   }
-}
-// ../kit/src/logs.ts
-import { lstatSync, openSync } from "fs";
-import { mkdir, mkdtemp, readdir, rm, stat } from "fs/promises";
-import { homedir, tmpdir } from "os";
-import { join } from "path";
-import process6 from "process";
-var DAY_MS = 24 * 60 * 60 * 1000;
-var CLI_FOLDER = "kaynooo-cli";
-function isPrivateDirectory(path) {
-  try {
-    const info = lstatSync(path, { throwIfNoEntry: false });
-    return info !== undefined && info.isDirectory() && info.uid === (process6.getuid?.() ?? info.uid) && (info.mode & 63) === 0;
-  } catch {
-    return false;
-  }
-}
-async function privateLogDirectory(name, env = process6.env) {
-  const runtime = env.XDG_RUNTIME_DIR;
-  const base = runtime === undefined || runtime === "" ? join(homedir(), ".cache", CLI_FOLDER) : join(runtime, CLI_FOLDER);
-  const path = join(base, name);
-  try {
-    await mkdir(path, { recursive: true, mode: 448 });
-    if (isPrivateDirectory(path))
-      return path;
-  } catch {}
-  return mkdtemp(join(tmpdir(), `${name.replaceAll("/", "-")}-`));
-}
-async function sweepLogs(dir, maxAgeMs = DAY_MS, now = Date.now()) {
-  let names;
-  try {
-    names = await readdir(dir);
-  } catch {
-    return;
-  }
-  for (const name of names) {
-    const path = join(dir, name);
+  if (usage !== false) {
     try {
-      const info = await stat(path);
-      if (info.isDirectory())
-        await sweepLogs(path, maxAgeMs, now);
-      if (now - info.mtimeMs > maxAgeMs)
-        await rm(path, { force: true, recursive: info.isDirectory() });
-    } catch {
-      continue;
-    }
+      recordUsage(usageEntry(name, undefined, argv, code));
+    } catch {}
   }
-}
-function createLog(path) {
-  return openSync(path, "wx", 384);
+  return code;
 }
 // ../kit/src/secrets.ts
 var SECRET_WORDS = new Set(["key", "pass", "pwd", "auth", "salt", "cookie", "session", "jwt", "ssn", "iban", "card", "cvv", "otp"]);
@@ -928,9 +1043,6 @@ var SECRET_WORDS = new Set(["key", "pass", "pwd", "auth", "salt", "cookie", "ses
 var {Glob } = globalThis.Bun;
 var SESSION_FILES = new Glob("*.json");
 var ACCOUNT_DIRS = new Glob("*/sessions");
-// package.json
-var version = "0.7.0";
-
 // src/shape.ts
 var HEX_LITERAL = /\b0x[0-9a-f]+\b/gi;
 var PATH = /(?:\.{1,2}\/|\/)?[\w.@~-]+(?:\/[\w.@~-]+)+/g;
@@ -1111,11 +1223,11 @@ function fold(text, { threshold, logPath }) {
 
 // src/run.ts
 import { closeSync, rmSync, writeSync } from "fs";
-import process10 from "process";
+import process13 from "process";
 
 // src/logs.ts
-import { join as join2 } from "path";
-import process8 from "process";
+import { join as join4 } from "path";
+import process11 from "process";
 var MAX_AGE_MS = 24 * 60 * 60 * 1000;
 async function logDir() {
   return privateLogDirectory("out");
@@ -1124,7 +1236,7 @@ async function cleanLogs(dir, now = Date.now()) {
   await sweepLogs(dir, MAX_AGE_MS, now);
 }
 function newLog(dir) {
-  const path = join2(dir, `${new Date().toISOString().replaceAll(/[:.]/g, "-")}-${process8.pid}.log`);
+  const path = join4(dir, `${new Date().toISOString().replaceAll(/[:.]/g, "-")}-${process11.pid}.log`);
   return { path, fd: createLog(path) };
 }
 
@@ -1143,13 +1255,16 @@ var ANSI_ESCAPES = { n: `
 var ANSI_DIGITS = { x: 2, u: 4, U: 8 };
 var OCTAL = /^[0-7]{1,3}/;
 var KEYWORDS = new Set(["then", "do", "else", "if", "elif", "while", "until", "!", "{", "}"]);
-var SHELLS = new Set(["sh", "bash", "zsh", "dash", "ash", "ksh"]);
-var COMMAND_STRING_PROGRAMS = new Set([...SHELLS, "su", "runuser"]);
+var SHELLS = new Set(["sh", "bash", "zsh", "dash", "ash", "ksh", "fish", "csh", "tcsh", "nu", "xonsh", "elvish", "pwsh", "powershell"]);
+var SCANNED_PROGRAMS = new Set(["su", "runuser", "flock"]);
+var COMMAND_STRING_PROGRAMS = new Set([...SHELLS, ...SCANNED_PROGRAMS]);
+var POWERSHELL = new Set(["pwsh", "powershell"]);
 var SHELL_VALUE_OPTIONS = new Set(["-o", "-O", "--rcfile", "--init-file"]);
+var FISH_VALUE_OPTIONS = new Set(["-C", "--init-command"]);
 var PRINTERS = new Set(["echo", "printf"]);
 var FIND_EXEC = new Set(["-exec", "-execdir", "-ok", "-okdir"]);
-function wrapper(short = "", long = [], operands = 0) {
-  return { short, long, operands };
+function wrapper(short = "", long = [], operands = 0, runsString = false) {
+  return { short, long, operands, runsString };
 }
 var WRAPPERS = new Map([
   ["command", wrapper()],
@@ -1167,6 +1282,11 @@ var WRAPPERS = new Map([
   ["ionice", wrapper("cnpPu", ["--class", "--classdata", "--pid", "--pgid", "--uid"])],
   ["stdbuf", wrapper("ioe", ["--input", "--output", "--error"])],
   ["chroot", wrapper("", ["--userspec", "--groups"], 1)],
+  ["watch", wrapper("n", ["--interval"], 0, true)],
+  ["flock", wrapper("wE", ["--timeout", "--conflict-exit-code"], 1)],
+  ["parallel", wrapper("jnNSaIPlLdTsC", ["--jobs", "--max-args", "--max-replace-args", "--sshlogin", "--arg-file", "--delimiter", "--colsep"], 0, true)],
+  ["unbuffer", wrapper()],
+  ["systemd-run", wrapper("puEMH", ["--property", "--unit", "--description", "--slice", "--setenv", "--machine", "--host", "--uid", "--gid", "--working-directory", "--nice", "--service-type"])],
   ["xargs", wrapper("IndsEaPL", ["--max-args", "--max-procs", "--max-chars", "--delimiter", "--arg-file", "--eof", "--max-lines", "--process-slot-var"])]
 ]);
 function closerOf(quote) {
@@ -1379,10 +1499,9 @@ function filtered(text, stages) {
 }
 
 // src/stats.ts
-import { appendFileSync, mkdirSync } from "fs";
-import { homedir as homedir2 } from "os";
-import { basename, dirname, join as join3 } from "path";
-import process9 from "process";
+import { appendFileSync as appendFileSync2, mkdirSync as mkdirSync2 } from "fs";
+import { basename, dirname as dirname3, join as join5 } from "path";
+import process12 from "process";
 var BYTES_PER_TOKEN = 4;
 var KEY_WORD = /^[a-z][a-z:_-]*$/;
 var KEY_WORDS = 3;
@@ -1391,8 +1510,8 @@ var ASSIGNMENT = /^\w+=/;
 var CHAIN = /&&|\|\||;/;
 var SHELLS2 = new Set(["sh", "bash", "zsh"]);
 var TOP = 10;
-function statsPath(env = process9.env) {
-  return join3(env.XDG_STATE_HOME ?? join3(homedir2(), ".local", "state"), CLI_FOLDER, "out", "stats.jsonl");
+function statsPath(env = process12.env) {
+  return join5(stateHome(env), CLI_FOLDER, "out", "stats.jsonl");
 }
 function commandKey(command) {
   const [program = "", ...rest] = command.slice(Math.max(0, command.findIndex((word) => !ASSIGNMENT.test(word))));
@@ -1410,8 +1529,8 @@ function commandKey(command) {
 }
 function record(entry, path = statsPath()) {
   try {
-    mkdirSync(dirname(path), { recursive: true, mode: 448 });
-    appendFileSync(path, `${JSON.stringify(entry)}
+    mkdirSync2(dirname3(path), { recursive: true, mode: 448 });
+    appendFileSync2(path, `${JSON.stringify(entry)}
 `, { mode: 384 });
   } catch {}
 }
@@ -1481,6 +1600,7 @@ class Recorder {
   tailBytes = 0;
   dropped = 0;
   log;
+  logFailed = false;
   constructor(dir) {
     this.dir = dir;
   }
@@ -1490,7 +1610,7 @@ class Recorder {
       this.headBytes += chunk.data.length;
       return;
     }
-    writeSync(this.startLog().fd, chunk.data);
+    this.writeToLog(chunk.data);
     this.tail.push(chunk);
     this.tailBytes += chunk.data.length;
     while (this.tail.length > 1 && this.tailBytes - (this.tail[0]?.data.length ?? 0) >= TAIL_BYTES) {
@@ -1499,6 +1619,16 @@ class Recorder {
       this.dropped += gone?.data.length ?? 0;
     }
   }
+  writeToLog(data) {
+    if (this.logFailed)
+      return;
+    try {
+      writeSync(this.startLog().fd, data);
+    } catch (error) {
+      this.logFailed = true;
+      console.error(`out: cannot write the log, the output past ${HEAD_BYTES} bytes is kept in memory only: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
   startLog() {
     if (this.log !== undefined)
       return this.log;
@@ -1531,17 +1661,17 @@ class Recorder {
     if (this.dropped === 0)
       return decode(this.chunks);
     return `${decode(this.head)}
-[out: ${this.dropped} bytes left out of memory, all of it is in the log]
+[out: ${this.dropped} bytes left out of memory${this.logFailed ? "" : ", all of it is in the log"}]
 ${decode(this.tail)}`;
   }
 }
 function replay(chunks) {
   for (const { stream, data } of chunks)
-    process10[stream].write(data);
+    process13[stream].write(data);
 }
 function count(recorder, shown, recorded) {
   const baseline = recorded.was.length === 0 || recorder.overflowing ? undefined : filtered(recorder.text, recorded.was);
-  record({ at: new Date().toISOString(), dir: process10.cwd(), command: recorded.command, bytes: recorder.bytes, baseline: baseline === undefined ? recorder.bytes : Buffer.byteLength(baseline), shown, folded: shown !== recorder.bytes });
+  record({ at: new Date().toISOString(), dir: process13.cwd(), command: recorded.command, bytes: recorder.bytes, baseline: baseline === undefined ? recorder.bytes : Buffer.byteLength(baseline), shown, folded: shown !== recorder.bytes });
 }
 async function run(command, threshold, was = []) {
   const dir = await logDir();
@@ -1566,7 +1696,7 @@ async function run(command, threshold, was = []) {
   } catch (error) {
     if (!started) {
       console.error(`out: cannot run ${command[0]}: ${error instanceof Error ? error.message : String(error)}`);
-      return 127;
+      return error.code === "EACCES" ? 126 : 127;
     }
     console.error(`out: ${error instanceof Error ? error.message : String(error)}`);
     code = 1;
@@ -1605,20 +1735,80 @@ function present(recorder, threshold) {
     replay(recorder.chunks);
     return recorder.bytes;
   }
-  process10.stdout.write(printed);
+  process13.stdout.write(printed);
   return Buffer.byteLength(printed);
 }
 
+// src/saved.ts
+import { readdir as readdir2, stat as stat2 } from "fs/promises";
+import { basename as basename2, join as join6 } from "path";
+async function savedLogs() {
+  const dir = await logDir();
+  const logs = [];
+  for (const name of await readdir2(dir)) {
+    const path = join6(dir, name);
+    try {
+      const info = await stat2(path);
+      if (info.isFile() && name.endsWith(".log"))
+        logs.push({ path, size: info.size, mtimeMs: info.mtimeMs });
+    } catch {
+      continue;
+    }
+  }
+  return logs.toSorted((a, b) => b.mtimeMs - a.mtimeMs || b.path.localeCompare(a.path));
+}
+async function pickLog(name) {
+  const logs = await savedLogs();
+  const found = name === undefined ? logs[0] : logs.find((log) => log.path === name || basename2(log.path) === name);
+  if (found === undefined)
+    fail(name === undefined ? "no saved log (a run saves one only when its output is folded, and logs older than a day are removed)" : `${name} is not a saved log, \`out --list\` names them`);
+  return found;
+}
+async function printLast() {
+  console.log((await pickLog(undefined)).path);
+  return 0;
+}
+async function printList() {
+  const logs = await savedLogs();
+  if (logs.length === 0)
+    fail("no saved log", 1);
+  console.log(table(logs.map((log) => [log.path, `${Math.ceil(log.size / 1024)} KiB`, formatAge(log.mtimeMs)])));
+  return 0;
+}
+async function grepLog(source, name) {
+  let pattern;
+  try {
+    pattern = new RegExp(source);
+  } catch (error) {
+    return badUsage(`--grep is no valid regular expression: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const lines = (await Bun.file((await pickLog(name)).path).text()).split(`
+`);
+  const hits = lines.flatMap((line, i) => pattern.test(line) ? [`${i + 1}: ${line}`] : []);
+  if (hits.length === 0)
+    fail(`no line of the log matches ${source}`, 1);
+  console.log(hits.join(`
+`));
+  return 0;
+}
+
 // src/cli.ts
 var USAGE = `out [-n <lines>] -- <command> [args...]: runs the command and shortens its output when it is long, exiting with its code
 <command> | out [-n <lines>]: shortens the output piped in
 out --stats [--since 7d] [--json]: the runs recorded and about how many tokens they saved
+out --last: the path of the most recent full log
+out --list: the saved logs, the newest first
+out --grep <regex> [--log <name>]: the lines of a saved log (the last by default) matching the regex, with their line numbers
 
-Each run is recorded in ~/.local/state/kaynooo-cli/out/stats.jsonl with the words naming the command, never its arguments; tokens are counted as bytes / 4.
-Exits 0 when the command does, with its own code otherwise, 127 when it cannot be started, 2 on a usage error. Piped into, it exits 0.`;
+Each run is recorded in ~/.local/state/kaynooo-cli/out/stats.jsonl with the words naming the command, never its arguments; tokens are counted as bytes / 4.`;
+var EXITS = [[0, "the command did, or the output piped in was shortened, or the log was found"], ["its own", "the code of a command that failed"], [1, "--grep matched nothing, or --list found no log"], [126, "the command cannot be run (not executable)"], [127, "the command cannot be started"], [2, "a usage error, or no such saved log"]];
 var OPTIONS = {
   lines: { type: "string", short: "n", description: "longest output left untouched (default 150)" },
   was: { type: "string", multiple: true, description: "a tail, head or grep stage out stands in for, so the stats count against what it would have printed (repeatable, in pipeline order)" },
+  last: { type: "boolean", description: "print the path of the most recent full log" },
+  list: { type: "boolean", description: "list the saved logs, the newest first" },
+  grep: { type: "string", description: "print the lines of a saved log matching this regular expression, with their line numbers" },
+  log: { type: "string", description: "with --grep, the saved log to read (its name or path) instead of the last" },
   stats: { type: "boolean", description: "print the runs recorded and the tokens saved" },
   since: { type: "string", description: "with --stats, only the runs this recent (7d, 12h)" },
   json: jsonOption("with --stats, {runs, folded, bytes, shown, tokensSaved, commands}")
@@ -1634,8 +1824,21 @@ async function stats(since, json) {
 }
 async function main(argv) {
   const bare = argv[0] !== undefined && !argv[0].startsWith("-");
-  const parsed = parse(bare ? [] : argv, USAGE, OPTIONS, { rest: true, replaces: "piping a noisy command through tail or head", examples: ["out -- bun install", ["out -n 300 -- bun run build", "up to 300 lines left untouched"], ["bun run build 2>&1 | out", "what is piped in"], ["out --stats --since 7d", "the tokens saved this week"]] });
+  const parsed = parse(bare ? [] : argv, USAGE, OPTIONS, { rest: true, exits: EXITS, replaces: "piping a noisy command through tail or head", examples: ["out -- bun install", ["out -n 300 -- bun run build", "up to 300 lines left untouched"], ["bun run build 2>&1 | out", "what is piped in"], ["out --stats --since 7d", "the tokens saved this week"]] });
   const { values } = parsed;
+  const reads = [values.last === true, values.list === true, values.grep !== undefined, values.stats === true].filter(Boolean).length;
+  if (reads > 1)
+    badUsage("give one of --last, --list, --grep and --stats");
+  if (reads === 1 && ((parsed.rest ?? []).length > 0 || parsed.positionals.length > 0))
+    badUsage("--last, --list, --grep and --stats run no command");
+  if (values.log !== undefined && values.grep === undefined)
+    badUsage("--log goes with --grep");
+  if (values.last === true)
+    return printLast();
+  if (values.list === true)
+    return printList();
+  if (values.grep !== undefined)
+    return grepLog(values.grep, values.log);
   if (values.stats === true) {
     if ((parsed.rest ?? []).length > 0 || parsed.positionals.length > 0)
       badUsage("--stats runs no command");
@@ -1654,4 +1857,4 @@ async function main(argv) {
 ${USAGE}`);
   return run(command, lines, was);
 }
-process11.exitCode = await runMain({ name: "out", version, run: main });
+process14.exitCode = await runMain({ name: "out", run: main });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kaynooo/cli-out",
   "type": "module",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "out: shortens noisy command output for Claude Code, folding long logs and keeping errors, with the full log saved to a file.",
   "author": "Kaynooo <contact@kaynooo.fr>",
   "license": "MIT",
@@ -28,6 +28,6 @@
     "out": "$npm_execpath src/cli.ts"
   },
   "devDependencies": {
-    "@kaynooo/cli-kit": "0.18.0"
+    "@kaynooo/cli-kit": "0.21.0"
   }
 }