@kaynooo/cli-out 0.6.0 → 0.7.0

package/README.md

@@ -11,13 +11,13 @@ out --stats --since 7d
 
 ## Behaviour
 
-- Output of at most 150 lines (`-n <lines>` changes it) passes through byte for byte, stdout and stderr to their own streams.
+- Output of at most 150 lines (`-n <lines>` changes it) and about 8 KB (55 bytes per allowed line) passes through byte for byte, stdout and stderr to their own streams.
 - Longer output is captured (both streams, in arrival order) and printed folded, after a header with the line count, how many lines were left out and the path of the full log.
 - Lines alike in shape (ANSI codes stripped; numbers, hashes, durations, percentages, paths and file names normalized) fold into one line with a count and the last line: `[1/300] compiling a.ts (x300, last: [300/300] compiling z.ts)`.
 - A block of 2 to 20 lines repeated back to back is shown once, followed by `(block repeated N times)`.
 - A line or block seen earlier is replaced by `(same as line N)`, N being a line of the full log, and the header lists the most repeated messages with their counts.
 - Carriage-return progress (spinners, bars) keeps only the final state of each line.
-- 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 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.
@@ -26,7 +26,7 @@ out --stats --since 7d
 
 - 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.
-- `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.
+- `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
 

package/dist/cli.js

@@ -15,7 +15,7 @@ import process2 from "process";
 // ../kit/src/style.ts
 import process from "process";
 
-// ../../node_modules/.bun/@kaynooo+utils@2.31.0+d0769e28dc4dad16/node_modules/@kaynooo/utils/dist/chunk-mtetydvc.js
+// ../../node_modules/.bun/@kaynooo+utils@2.31.2+d0769e28dc4dad16/node_modules/@kaynooo/utils/dist/chunk-mtetydvc.js
 function x(s) {
   let r = s.startsWith("#") ? s.slice(1).toLowerCase() : s.toLowerCase();
   if (!/^[a-f0-9]+$/.test(r))
@@ -235,7 +235,7 @@ class e {
   }
 }
 
-// ../../node_modules/.bun/@kaynooo+utils@2.31.0+d0769e28dc4dad16/node_modules/@kaynooo/utils/dist/chunk-y1msbssb.js
+// ../../node_modules/.bun/@kaynooo+utils@2.31.2+d0769e28dc4dad16/node_modules/@kaynooo/utils/dist/chunk-y1msbssb.js
 var r = 39;
 var o = 49;
 var f2 = "\x1B[";
@@ -402,8 +402,12 @@ class HelpShown extends Exit {
 
 class Completing {
   options;
-  constructor(options) {
+  positionals;
+  candidates;
+  constructor(options, positionals = [], candidates = {}) {
     this.options = options;
+    this.positionals = positionals;
+    this.candidates = candidates;
   }
 }
 var completion = { active: false };
@@ -446,8 +450,10 @@ function exampleRows(examples, colors = paint(process3.stdout)) {
 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 value = option.type === "string" ? ` ${colors.dim("<value>")}` : "";
-    return { flag: `${short}${colors.cyan(`--${name}`)}${value}`, width: `-x, --${name}`.length + (option.type === "string" ? " <value>".length : 0), description: option.description ?? "" };
+    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)}`);
@@ -473,14 +479,13 @@ function applyOutput(color, plain, env = process3.env) {
 function parse(args, usage, options, settings = {}) {
   const output = Object.fromEntries(Object.entries(OUTPUT_OPTIONS).filter(([name]) => !(name in options)));
   const all = { ...options, ...output, help: { type: "boolean", short: "h", description: "show this help" } };
+  const listing = listed(all, settings.allowNegative === true);
   if (completion.active)
-    throw new Completing(all);
-  const separator = settings.rest === true ? args.indexOf("--") : -1;
-  const own = separator === -1 ? args : args.slice(0, separator);
-  const rest = separator === -1 ? undefined : args.slice(separator + 1);
+    throw new Completing(listing, settings.positionals, settings.candidates);
+  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(own, all), options: all, allowPositionals: true, allowNegative: settings.allowNegative === true, strict: true });
+    parsed = parseArgs({ args: joinDashValues(withBare(own, 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));
@@ -488,12 +493,84 @@ 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, all, undefined, settings));
+    console.log(wantsHelpJson() ? JSON.stringify(description(usage, settings)) : helpText(usage, listing, undefined, settings));
     throw new HelpShown;
   }
+  checkChoices(parsed.values, all);
+  checkConflicts(parsed.values, all);
   if (settings.positionals !== undefined)
     checkPositionals(parsed.positionals, settings.positionals);
-  return { ...parsed, positionals: parsed.positionals, rest };
+  return { ...parsed, values: parsed.values, positionals: parsed.positionals, rest };
+}
+function splitRest(args, passes) {
+  const separator = passes ? args.indexOf("--") : -1;
+  return { own: separator === -1 ? args : args.slice(0, separator), rest: separator === -1 ? undefined : args.slice(separator + 1) };
+}
+function splitTrailing(args, options, count) {
+  const takesValue = (word) => !word.includes("=") && Object.entries(options).some(([name, { short, type }]) => type === "string" && (word === `--${name}` || word === `-${short}`));
+  let seen = 0;
+  if (count === 0)
+    return { own: args, rest: undefined };
+  for (let at = 0;at < args.length; at++) {
+    const word = args[at];
+    if (word === "--")
+      break;
+    if (word.startsWith("-")) {
+      if (takesValue(word))
+        at++;
+      continue;
+    }
+    seen++;
+    if (seen === count)
+      return { own: args.slice(0, at + 1), rest: args.slice(at + 1) };
+  }
+  return { own: args, rest: undefined };
+}
+function listed(options, allowNegative) {
+  if (!allowNegative)
+    return options;
+  return Object.fromEntries(Object.entries(options).flatMap(([name, option]) => {
+    if (option.type !== "boolean" || option.negative === undefined)
+      return [[name, option]];
+    return [...option.description === undefined ? [] : [[name, option]], [`no-${name}`, { type: "boolean", description: option.negative }]];
+  }));
+}
+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)
+    return args;
+  const separator = args.indexOf("--");
+  const own = separator === -1 ? args : args.slice(0, separator);
+  return [...own.flatMap((arg, index) => {
+    const optional = bare.get(arg);
+    const next = own[index + 1];
+    const value = next !== undefined && (optional?.accepts === undefined ? !next.startsWith("-") : optional.accepts.test(next));
+    return optional === undefined || value ? [arg] : [arg, optional.bare];
+  }), ...separator === -1 ? [] : args.slice(separator)];
+}
+function checkConflicts(values, options) {
+  const given = (name) => values[name] !== undefined && values[name] !== false;
+  for (const [name, { conflicts = [] }] of Object.entries(options)) {
+    const other = given(name) ? conflicts.find(given) : undefined;
+    if (other !== undefined)
+      badUsage(`--${name} cannot be used with --${other}`);
+  }
+}
+function checkChoices(values, options) {
+  for (const [name, option] of Object.entries(options)) {
+    if (option.choices === undefined)
+      continue;
+    const given = values[name];
+    for (const value of Array.isArray(given) ? given : [given]) {
+      if (typeof value === "string")
+        oneOf(value, name, option.choices);
+    }
+  }
+}
+function oneOf(value, name, choices) {
+  if (!choices.includes(value))
+    badUsage(`${name.startsWith("<") ? name : `--${name}`} takes one of ${choices.join(", ")}, not ${value}`);
+  return value;
 }
 function checkPositionals(given, names) {
   const variadic = names.at(-1)?.replace("]", "").endsWith("...") === true;
@@ -727,22 +804,55 @@ function reportThrown(prefix, error, redact = (text) => text, json = false) {
 }
 var COMPLETE = "__complete";
 var FILES = "__files__";
-async function optionsOf(run) {
+async function completingOf(run) {
   completion.active = true;
   try {
     await run([]);
   } catch (error) {
     if (error instanceof Completing)
-      return error.options;
+      return error;
   } finally {
     completion.active = false;
   }
-  return {};
+  return new Completing({});
+}
+function candidateLine(candidate) {
+  return typeof candidate === "string" ? candidate : candidate.join("\t");
+}
+function positionalBeingTyped(before, { options, positionals }) {
+  const takesValue = (word) => !word.includes("=") && Object.entries(options).some(([name, { short, type }]) => type === "string" && (word === `--${name}` || word === `-${short}`));
+  let index = 0;
+  let at = 0;
+  while (at < before.length) {
+    const word = before[at];
+    if (word === "--") {
+      index += before.length - at - 1;
+      break;
+    }
+    if (!word.startsWith("-"))
+      index++;
+    else if (takesValue(word))
+      at++;
+    at++;
+  }
+  const last = positionals.at(-1);
+  if (index < positionals.length)
+    return positionals[index];
+  return last?.replace("]", "").endsWith("...") === true ? last : undefined;
 }
 async function leafCandidates(run, words) {
-  if (!(words.at(-1) ?? "").startsWith("-"))
-    return [FILES];
-  return Object.entries(await optionsOf(run)).map(([name, option]) => option.description === undefined ? `--${name}` : `--${name}	${option.description}`);
+  const completing = await completingOf(run);
+  if ((words.at(-1) ?? "").startsWith("-"))
+    return Object.entries(completing.options).map(([name, option]) => option.description === undefined ? `--${name}` : `--${name}	${option.description}`);
+  const flag = words.at(-2);
+  const option = flag?.startsWith("-") === true ? Object.entries(completing.options).find(([name, { short }]) => flag === `--${name}` || flag === `-${short}`)?.[1] : undefined;
+  if (option?.type === "string") {
+    const values = option.choices === undefined ? await option.candidates?.() : option.choices;
+    return values === undefined ? [FILES] : values.map(candidateLine);
+  }
+  const name = positionalBeingTyped(words.slice(0, -1), completing);
+  const values = name === undefined ? undefined : await completing.candidates[name]?.();
+  return values === undefined ? [FILES] : values.map(candidateLine);
 }
 async function printCandidates(found) {
   for (const line of await found)
@@ -819,7 +929,7 @@ var {Glob } = globalThis.Bun;
 var SESSION_FILES = new Glob("*.json");
 var ACCOUNT_DIRS = new Glob("*/sessions");
 // package.json
-var version = "0.6.0";
+var version = "0.7.0";
 
 // src/shape.ts
 var HEX_LITERAL = /\b0x[0-9a-f]+\b/gi;
@@ -844,6 +954,9 @@ var HEAD = 40;
 var TAIL = 60;
 var MAX_BLOCK = 20;
 var MIN_REFERENCED = 20;
+var BYTES_PER_LINE = 55;
+var MAX_WIDTH = 300;
+var MAX_KEPT_IMPORTANT = 40;
 var TOP_REPEATED = 3;
 var LINE_BREAK = /\r\n|\r|\n/;
 var LINE_END = /(?:\r\n|\r|\n)$/;
@@ -854,7 +967,10 @@ function lineCount(text) {
   return LINE_END.test(text) ? count - 1 : count;
 }
 function shouldFold(text, threshold) {
-  return lineCount(text) > threshold;
+  return lineCount(text) > threshold || Buffer.byteLength(text) > threshold * BYTES_PER_LINE;
+}
+function cutWide(line) {
+  return line.length > MAX_WIDTH ? `${line.slice(0, MAX_WIDTH)}... [+${line.length - MAX_WIDTH} chars]` : line;
 }
 function finalState(line) {
   const segments = line.split("\r").filter((segment) => segment !== "");
@@ -948,11 +1064,16 @@ function toEntries(units) {
 function fold(text, { threshold, logPath }) {
   const lines = splitLines(text);
   const { entries, references, repeated } = toEntries(toUnits(lines, lines.map((line) => shape(line))));
-  const head = Math.min(HEAD, Math.floor(threshold / 3));
-  const tail = Math.min(TAIL, Math.floor(threshold / 2));
+  for (const entry of entries)
+    entry.text = cutWide(entry.text);
+  const heavy = entries.reduce((sum, { text }) => sum + text.length + 1, 0) > threshold * BYTES_PER_LINE;
+  const shrink = heavy && entries.length <= threshold ? 2 : 1;
+  const head = Math.floor(Math.min(HEAD, Math.floor(threshold / 3)) / shrink);
+  const tail = Math.floor(Math.min(TAIL, Math.floor(threshold / 2)) / shrink);
   const out = [];
   let dropped = 0;
-  if (entries.length <= threshold) {
+  let kept = 0;
+  if (entries.length <= threshold && !heavy) {
     out.push(...entries.map(({ text }) => text));
   } else {
     const middleEnd = entries.length - tail;
@@ -969,7 +1090,8 @@ function fold(text, { threshold, logPath }) {
         out.push(entry.text);
         continue;
       }
-      if (entry.important) {
+      if (entry.important && kept < MAX_KEPT_IMPORTANT) {
+        kept++;
         closeGap();
         out.push(entry.text);
         continue;
@@ -1307,29 +1429,41 @@ async function readEntries(path = statsPath(), since = 0) {
     }
   });
 }
+function median(values) {
+  const sorted = values.toSorted((a, b) => a - b);
+  const middle = Math.floor(sorted.length / 2);
+  if (sorted.length === 0)
+    return;
+  return sorted.length % 2 === 1 ? sorted[middle] : ((sorted[middle - 1] ?? 0) + (sorted[middle] ?? 0)) / 2;
+}
 function tokens(bytes) {
   return Math.round(bytes / BYTES_PER_TOKEN);
 }
 function formatNumber(value) {
   return value.toLocaleString("en-US");
 }
+function cut2(runs) {
+  const value = median(runs.filter((run) => run.folded && run.baseline > 0).map((run) => (1 - run.shown / run.baseline) * 100));
+  return value === undefined ? undefined : Math.round(value);
+}
 function summarize(entries) {
   const commands = Map.groupBy(entries, (entry) => entry.command).entries().map(([command, runs]) => ({
     command,
     runs: runs.length,
     folded: runs.filter((run) => run.folded).length,
-    tokensSaved: tokens(runs.reduce((sum, run) => sum + run.baseline - run.shown, 0))
+    tokensSaved: tokens(runs.reduce((sum, run) => sum + run.baseline - run.shown, 0)),
+    medianCut: cut2(runs)
   }));
   const sum = (field) => entries.reduce((total, entry) => total + entry[field], 0);
-  return { runs: entries.length, folded: entries.filter((entry) => entry.folded).length, bytes: sum("bytes"), shown: sum("shown"), tokensSaved: tokens(sum("baseline") - sum("shown")), commands: [...commands].sort((a, b) => b.tokensSaved - a.tokensSaved) };
+  return { runs: entries.length, folded: entries.filter((entry) => entry.folded).length, bytes: sum("bytes"), shown: sum("shown"), tokensSaved: tokens(sum("baseline") - sum("shown")), foldedShare: entries.length === 0 ? 0 : Math.round(entries.filter((entry) => entry.folded).length / entries.length * 100), commands: [...commands].sort((a, b) => b.tokensSaved - a.tokensSaved) };
 }
 function renderSummary(summary, period) {
   if (summary.runs === 0)
     return `no run of out recorded ${period}`;
   const top = summary.commands.slice(0, TOP).filter((each) => each.tokensSaved !== 0);
   return [
-    `${formatNumber(summary.runs)} runs ${period}, ${formatNumber(summary.folded)} folded: ${formatNumber(summary.bytes)} bytes printed, ${formatNumber(summary.shown)} shown, about ${formatNumber(summary.tokensSaved)} tokens saved (bytes / ${BYTES_PER_TOKEN})`,
-    ...top.length === 0 ? [] : ["", table([["command", "runs", "folded", "tokens saved"], ...top.map((each) => [each.command, formatNumber(each.runs), formatNumber(each.folded), formatNumber(each.tokensSaved)])])]
+    `${formatNumber(summary.runs)} runs ${period}, ${formatNumber(summary.folded)} folded (${summary.foldedShare}%): ${formatNumber(summary.bytes)} bytes printed, ${formatNumber(summary.shown)} shown, about ${formatNumber(summary.tokensSaved)} tokens saved (bytes / ${BYTES_PER_TOKEN})`,
+    ...top.length === 0 ? [] : ["", table([["command", "runs", "folded", "median cut", "tokens saved"], ...top.map((each) => [each.command, formatNumber(each.runs), formatNumber(each.folded), each.medianCut === undefined ? "-" : `${each.medianCut}%`, formatNumber(each.tokensSaved)])])]
   ].join(`
 `);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kaynooo/cli-out",
   "type": "module",
-  "version": "0.6.0",
+  "version": "0.7.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.15.0"
+    "@kaynooo/cli-kit": "0.18.0"
   }
 }