@kaynooo/cli-out 0.6.0 → 0.7.1

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

@@ -2,11 +2,10 @@
 // @bun
 
 // src/cli.ts
-import process11 from "process";
+import process13 from "process";
 
 // ../kit/src/args.ts
-import { fstatSync } from "fs";
-import process3 from "process";
+import process4 from "process";
 import { parseArgs } from "util";
 
 // ../kit/src/format.ts
@@ -15,7 +14,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 +234,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[";
@@ -344,6 +343,55 @@ function printJson(value) {
   console.log(JSON.stringify(value, undefined, 2));
 }
 
+// ../kit/src/help.ts
+import process3 from "process";
+var OPTIONAL = /\[[^\]]+\]/g;
+var USAGE_PREFIX = /^usage:\s*/i;
+var FULL_STOP = /\.$/;
+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)}`);
+}
+
 // ../kit/src/text.ts
 var ANSI = new RegExp(`${String.fromCharCode(27)}\\[[\\d;?]*[a-z]`, "gi");
 function stripAnsi(text) {
@@ -366,8 +414,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}` };
 }
@@ -402,61 +477,20 @@ 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 };
-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 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 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 = process4.env) {
   const when = plain === true ? "never" : color ?? "auto";
   if (when === "auto")
     return;
@@ -473,14 +507,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 +521,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;
@@ -542,33 +647,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 process5 from "process";
 var KILL_GRACE_MS = 2000;
 var SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
 function exitCodeOf(code, signal) {
@@ -590,7 +671,7 @@ function holdSignals(cleanup) {
     },
     release: () => {
       for (const signal of SIGNALS)
-        process4.off(signal, onSignal);
+        process5.off(signal, onSignal);
     }
   };
   function onSignal(signal) {
@@ -603,10 +684,10 @@ function holdSignals(cleanup) {
       return;
     held.release();
     cleanup(signal);
-    process4.kill(process4.pid, signal);
+    process5.kill(process5.pid, signal);
   }
   for (const signal of SIGNALS)
-    process4.on(signal, onSignal);
+    process5.on(signal, onSignal);
   return held;
 }
 async function runCommand(argv, { cwd, env, stdin = "ignore", timeoutMs, signal, maxBytes = Infinity, onChunk, onStart } = {}) {
@@ -620,7 +701,7 @@ async function runCommand(argv, { cwd, env, stdin = "ignore", timeoutMs, signal,
       return;
     try {
       if (grouped)
-        process4.kill(-proc.pid, killing);
+        process5.kill(-proc.pid, killing);
       else
         proc.kill(killing);
     } catch {}
@@ -694,15 +775,114 @@ 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 process8 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 process7 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 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);
+    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 = process7.env) {
+  const dir = env.XDG_STATE_HOME;
+  return dir !== undefined && isAbsolute(dir) ? dir : join2(homedir2(), ".local", "state");
+}
+function usagePath(env = process7.env) {
+  return join2(stateHome(env), CLI_FOLDER, "usage.jsonl");
+}
+function usageRecorded(env = process7.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 = process7.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(process8.stderr);
+  const styled = takesControlCodes(process8.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}`;
@@ -721,96 +901,85 @@ 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;
 }
 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)
     console.log(line);
   return 0;
 }
-async function runMain({ name, version, run, redact }, argv = process5.argv.slice(2)) {
+async function runMain({ name, version, run, redact, usage }, argv = process8.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);
     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);
-    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);
+  if (usage !== false)
+    recordUsage(usageEntry(name, undefined, argv, code));
+  return code;
 }
 // ../kit/src/secrets.ts
 var SECRET_WORDS = new Set(["key", "pass", "pwd", "auth", "salt", "cookie", "session", "jwt", "ssn", "iban", "card", "cvv", "otp"]);
@@ -819,7 +988,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.1";
 
 // src/shape.ts
 var HEX_LITERAL = /\b0x[0-9a-f]+\b/gi;
@@ -844,6 +1013,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 +1026,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 +1123,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 +1149,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;
@@ -989,11 +1170,11 @@ function fold(text, { threshold, logPath }) {
 
 // src/run.ts
 import { closeSync, rmSync, writeSync } from "fs";
-import process10 from "process";
+import process12 from "process";
 
 // src/logs.ts
-import { join as join2 } from "path";
-import process8 from "process";
+import { join as join3 } from "path";
+import process10 from "process";
 var MAX_AGE_MS = 24 * 60 * 60 * 1000;
 async function logDir() {
   return privateLogDirectory("out");
@@ -1002,7 +1183,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 = join3(dir, `${new Date().toISOString().replaceAll(/[:.]/g, "-")}-${process10.pid}.log`);
   return { path, fd: createLog(path) };
 }
 
@@ -1257,10 +1438,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 dirname2, join as join4 } from "path";
+import process11 from "process";
 var BYTES_PER_TOKEN = 4;
 var KEY_WORD = /^[a-z][a-z:_-]*$/;
 var KEY_WORDS = 3;
@@ -1269,8 +1449,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 = process11.env) {
+  return join4(stateHome(env), CLI_FOLDER, "out", "stats.jsonl");
 }
 function commandKey(command) {
   const [program = "", ...rest] = command.slice(Math.max(0, command.findIndex((word) => !ASSIGNMENT.test(word))));
@@ -1288,8 +1468,8 @@ function commandKey(command) {
 }
 function record(entry, path = statsPath()) {
   try {
-    mkdirSync(dirname(path), { recursive: true, mode: 448 });
-    appendFileSync(path, `${JSON.stringify(entry)}
+    mkdirSync2(dirname2(path), { recursive: true, mode: 448 });
+    appendFileSync2(path, `${JSON.stringify(entry)}
 `, { mode: 384 });
   } catch {}
 }
@@ -1307,29 +1487,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(`
 `);
 }
@@ -1403,11 +1595,11 @@ ${decode(this.tail)}`;
 }
 function replay(chunks) {
   for (const { stream, data } of chunks)
-    process10[stream].write(data);
+    process12[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: process12.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();
@@ -1471,7 +1663,7 @@ function present(recorder, threshold) {
     replay(recorder.chunks);
     return recorder.bytes;
   }
-  process10.stdout.write(printed);
+  process12.stdout.write(printed);
   return Buffer.byteLength(printed);
 }
 
@@ -1520,4 +1712,4 @@ async function main(argv) {
 ${USAGE}`);
   return run(command, lines, was);
 }
-process11.exitCode = await runMain({ name: "out", version, run: main });
+process13.exitCode = await runMain({ name: "out", version, run: main });

package/package.json

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