@kaynooo/cli-pkg 0.7.0 → 0.7.1

package/dist/cli.js

@@ -26,7 +26,7 @@ var __esm = (fn, res, err) => () => {
   return res;
 };
 
-// ../../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))
@@ -245,7 +245,7 @@ class e {
 var m = (s) => s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4, p = (s) => s <= 0.0031308 ? 12.92 * s : 1.055 * s ** 0.4166666666666667 - 0.055, i = (s, r) => Math.round(s * 10 ** r) / 10 ** r;
 var init_chunk_mtetydvc = () => {};
 
-// ../../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
 function h(i, n = globalThis.process?.env ?? {}) {
   if (n.FORCE_COLOR !== undefined)
     return b.has(n.FORCE_COLOR);
@@ -287,7 +287,7 @@ var init_chunk_y1msbssb = __esm(() => {
   t = le();
 });
 
-// ../../node_modules/.bun/@kaynooo+utils@2.31.0+d0769e28dc4dad16/node_modules/@kaynooo/utils/dist/tools/colors.js
+// ../../node_modules/.bun/@kaynooo+utils@2.31.2+d0769e28dc4dad16/node_modules/@kaynooo/utils/dist/tools/colors.js
 var init_colors = __esm(() => {
   init_chunk_y1msbssb();
 });
@@ -421,48 +421,8 @@ var init_format = __esm(() => {
   ESCAPE = String.fromCharCode(27);
 });
 
-// ../kit/src/text.ts
-function distance(a, b) {
-  let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
-  for (const [i, left] of [...a].entries()) {
-    const current = [i + 1];
-    for (const [j, right] of [...b].entries())
-      current.push(Math.min((previous[j + 1] ?? 0) + 1, (current[j] ?? 0) + 1, (previous[j] ?? 0) + (left === right ? 0 : 1)));
-    previous = current;
-  }
-  return previous[b.length] ?? 0;
-}
-function closest(name, names) {
-  const started = names.find((known) => known.startsWith(name));
-  if (started !== undefined)
-    return started;
-  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;
-}
-var ANSI;
-var init_text = __esm(() => {
-  ANSI = new RegExp(`${String.fromCharCode(27)}\\[[\\d;?]*[a-z]`, "gi");
-});
-
-// ../kit/src/args.ts
+// ../kit/src/help.ts
 import process3 from "process";
-import { parseArgs } from "util";
-function jsonOption(holds) {
-  return { type: "boolean", description: holds === undefined ? "print JSON" : `print JSON: ${holds}` };
-}
-function fail(message, code = 2, hint) {
-  throw new Exit(message, code, hint);
-}
-function badUsage(message) {
-  throw new UsageError(message);
-}
-
-class Completing {
-  options;
-  constructor(options) {
-    this.options = options;
-  }
-}
 function usageLine(usage, colors = paint(process3.stdout)) {
   return `${colors.bold("Usage:")} ${usage.replace(USAGE_PREFIX, "").replaceAll(OPTIONAL, (part) => colors.dim(part))}`;
 }
@@ -498,13 +458,95 @@ 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)}`);
 }
-function applyOutput(color, plain, env = process3.env) {
+var OPTIONAL, USAGE_PREFIX, FULL_STOP;
+var init_help = __esm(() => {
+  init_style();
+  OPTIONAL = /\[[^\]]+\]/g;
+  USAGE_PREFIX = /^usage:\s*/i;
+  FULL_STOP = /\.$/;
+});
+
+// ../kit/src/text.ts
+function distance(a, b) {
+  let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (const [i, left] of [...a].entries()) {
+    const current = [i + 1];
+    for (const [j, right] of [...b].entries())
+      current.push(Math.min((previous[j + 1] ?? 0) + 1, (current[j] ?? 0) + 1, (previous[j] ?? 0) + (left === right ? 0 : 1)));
+    previous = current;
+  }
+  return previous[b.length] ?? 0;
+}
+function closest(name, names) {
+  const started = names.find((known) => known.startsWith(name));
+  if (started !== undefined)
+    return started;
+  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;
+}
+var ANSI;
+var init_text = __esm(() => {
+  ANSI = new RegExp(`${String.fromCharCode(27)}\\[[\\d;?]*[a-z]`, "gi");
+});
+
+// ../kit/src/input.ts
+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;
+}
+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;
+}
+var WHOLE, DURATION, UNIT_MS;
+var init_input = __esm(() => {
+  init_args();
+  WHOLE = /^\d+$/;
+  DURATION = /^(\d+(?:\.\d+)?)(ms|[smhd])?$/;
+  UNIT_MS = { ms: 1, s: 1000, m: 60000, h: 3600000, d: 86400000 };
+});
+
+// ../kit/src/args.ts
+import process4 from "process";
+import { parseArgs } from "util";
+function jsonOption(holds) {
+  return { type: "boolean", description: holds === undefined ? "print JSON" : `print JSON: ${holds}` };
+}
+function fail(message, code = 2, hint) {
+  throw new Exit(message, code, hint);
+}
+function badUsage(message) {
+  throw new UsageError(message);
+}
+
+class Completing {
+  options;
+  positionals;
+  candidates;
+  constructor(options, positionals = [], candidates = {}) {
+    this.options = options;
+    this.positionals = positionals;
+    this.candidates = candidates;
+  }
+}
+function applyOutput(color, plain, env = process4.env) {
   const when = plain === true ? "never" : color ?? "auto";
   if (when === "auto")
     return;
@@ -521,14 +563,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));
@@ -536,12 +577,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;
@@ -589,28 +702,14 @@ 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)}?`;
 }
-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;
-}
-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;
-}
-var Exit, UsageError, HelpShown, completion, OPTIONAL, USAGE_PREFIX, FULL_STOP, DASHES, OUTPUT_OPTIONS, UNKNOWN_OPTION, WHOLE, DURATION, UNIT_MS;
+var DASHES, Exit, UsageError, HelpShown, completion, OUTPUT_OPTIONS, UNKNOWN_OPTION;
 var init_args = __esm(() => {
   init_format();
-  init_style();
+  init_help();
   init_text();
+  init_help();
+  init_input();
+  DASHES = /^-+/;
   Exit = class Exit extends Error {
     code;
     hint;
@@ -631,18 +730,11 @@ var init_args = __esm(() => {
     }
   };
   completion = { active: false };
-  OPTIONAL = /\[[^\]]+\]/g;
-  USAGE_PREFIX = /^usage:\s*/i;
-  FULL_STOP = /\.$/;
-  DASHES = /^-+/;
   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" }
   };
   UNKNOWN_OPTION = /^unknown option '(-[^']+)'/;
-  WHOLE = /^\d+$/;
-  DURATION = /^(\d+(?:\.\d+)?)(ms|[smhd])?$/;
-  UNIT_MS = { ms: 1, s: 1000, m: 60000, h: 3600000, d: 86400000 };
 });
 
 // ../kit/src/chart.ts
@@ -653,7 +745,7 @@ var init_chart = __esm(() => {
 
 // ../kit/src/process.ts
 import { constants } from "os";
-import process4 from "process";
+import process5 from "process";
 function exitCodeOf(code, signal) {
   if (code !== null)
     return code;
@@ -673,7 +765,7 @@ function holdSignals(cleanup) {
     },
     release: () => {
       for (const signal of SIGNALS)
-        process4.off(signal, onSignal);
+        process5.off(signal, onSignal);
     }
   };
   function onSignal(signal) {
@@ -686,10 +778,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 } = {}) {
@@ -703,7 +795,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 {}
@@ -776,8 +868,8 @@ var init_process = __esm(() => {
 });
 
 // ../kit/src/progress.ts
-import process5 from "process";
-function liveRegion(render, stream = process5.stderr, env = process5.env) {
+import process6 from "process";
+function liveRegion(render, stream = process6.stderr, env = process6.env) {
   if (!takesControlCodes(stream, env))
     return { redraw: () => {
       return;
@@ -818,11 +910,11 @@ function liveRegion(render, stream = process5.stderr, env = process5.env) {
     clear();
     restore();
     release();
-    process5.off("exit", onExit);
+    process6.off("exit", onExit);
     signals.release();
   }
   timer.unref();
-  process5.on("exit", onExit);
+  process6.on("exit", onExit);
   return {
     redraw: draw,
     print: (text) => {
@@ -861,14 +953,14 @@ function cutToWidth(line, width) {
   return `${kept}${RESET_STYLE}${linked ? CLOSE_LINK : ""}`;
 }
 function swallowInput() {
-  const input = process5.stdin;
+  const input = process6.stdin;
   if (!input.isTTY)
     return () => {
       return;
     };
   const onData = (data) => {
     if (data.includes(CTRL_C))
-      process5.kill(process5.pid, "SIGINT");
+      process6.kill(process6.pid, "SIGINT");
   };
   input.setRawMode(true);
   input.on("data", onData);
@@ -884,7 +976,7 @@ function swallowInput() {
   };
 }
 function interceptOutput(clear) {
-  const targets = [...CONSOLE_METHODS.map((name) => [console, name]), [process5.stdout, "write"], [process5.stderr, "write"]];
+  const targets = [...CONSOLE_METHODS.map((name) => [console, name]), [process6.stdout, "write"], [process6.stderr, "write"]];
   const wrapped = targets.map(([target, name]) => {
     const original = Reflect.get(target, name);
     const wrapper = (...args) => {
@@ -928,10 +1020,63 @@ var init_ci = __esm(() => {
   init_tool();
 });
 
+// ../kit/src/logs.ts
+var DAY_MS, CLI_FOLDER = "kaynooo-cli";
+var init_logs = __esm(() => {
+  DAY_MS = 24 * 60 * 60 * 1000;
+});
+
+// ../kit/src/usage.ts
+import { appendFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { dirname, isAbsolute, join } from "path";
+import process7 from "process";
+function noteUsageError(message) {
+  usageError = message;
+}
+function stateHome(env = process7.env) {
+  const dir = env.XDG_STATE_HOME;
+  return dir !== undefined && isAbsolute(dir) ? dir : join(homedir(), ".local", "state");
+}
+function usagePath(env = process7.env) {
+  return join(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 {}
+}
+var UNKNOWN_OPTION2, FLAG_NAME, LONGEST_NAME = 40, usageError;
+var init_usage = __esm(() => {
+  init_logs();
+  UNKNOWN_OPTION2 = /unknown option '(--[a-z][a-z0-9-]*)[=']/;
+  FLAG_NAME = /^(?:--[a-z][a-z0-9-]*|-[a-zA-Z])$/;
+});
+
 // ../kit/src/cli.ts
-import process6 from "process";
-async function commandRows(commands, colors) {
-  const width = Math.max(...Object.keys(commands).map((name) => name.length));
+import process8 from "process";
+async function commandRows(all, colors) {
+  const commands = shown(all);
+  const width = Math.max(0, ...Object.keys(commands).map((name) => name.length));
   const groups = new Map([["Commands:", []]]);
   const summaries = await Promise.all(Object.values(commands).map(async ({ summary }) => resolveSummary(summary)));
   for (const [index, [name, { group }]] of Object.entries(commands).entries()) {
@@ -942,6 +1087,9 @@ async function commandRows(commands, colors) {
   }
   return [...groups].filter(([, rows]) => rows.length > 0).flatMap(([heading, rows], index) => [...index === 0 ? [] : [""], colors.bold(heading), ...rows]);
 }
+function shown(commands) {
+  return Object.fromEntries(Object.entries(commands).filter(([, { hidden }]) => hidden !== true));
+}
 function takeOutputFlags(argv) {
   let index = 0;
   for (;index < argv.length; index++) {
@@ -973,7 +1121,7 @@ async function expand(scope, words) {
   }
   return { ...scope, commands, lazy: [] };
 }
-async function help({ path, header, summary: lazySummary, commands, defaultCommand, examples, replaces }, stream) {
+async function help2({ path, header, summary: lazySummary, commands, defaultCommand, examples, replaces }, stream) {
   const colors = paint(stream);
   const prefix = path.join(" ");
   const summary = await resolveSummary(lazySummary);
@@ -1000,8 +1148,8 @@ async function help({ path, header, summary: lazySummary, commands, defaultComma
 `);
 }
 function printError(prefix, message, hint, cause) {
-  const colors = paint(process6.stderr);
-  const styled = takesControlCodes(process6.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}`;
@@ -1020,6 +1168,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;
@@ -1033,12 +1183,20 @@ async function dispatch(level, typed, { version, redact }) {
     return reportThrown(prefix, error);
   }
   const [name, ...args] = argv;
+  const fallback = level.defaultCommand === undefined ? undefined : level.commands[level.defaultCommand];
+  if (name === undefined && level.runBare && fallback !== undefined && "run" in fallback) {
+    try {
+      return await fallback.run([]);
+    } catch (error) {
+      return reportThrown(`${prefix} ${level.defaultCommand}`, error, redact, false);
+    }
+  }
   if (name === undefined && level.path.length > 1) {
-    console.error(await help(await expand(level, [...level.path.slice(1), ...argv]), process6.stderr));
+    console.error(await help2(await expand(level, [...level.path.slice(1), ...argv]), process8.stderr));
     return 2;
   }
   if (name === undefined || name === "help" || name === "--help" || name === "-h") {
-    console.log(await help(await expand(level, [...level.path.slice(1), ...argv]), process6.stdout));
+    console.log(await help2(await expand(level, [...level.path.slice(1), ...argv]), process8.stdout));
     return 0;
   }
   if (level.path.length === 1 && (name === "--version" || name === "-v")) {
@@ -1047,6 +1205,7 @@ async function dispatch(level, typed, { version, redact }) {
   }
   let command = level.commands[level.aliases?.[name] ?? name];
   let rest = args;
+  let ran = name;
   if (command === undefined && level.lazy.length > 0) {
     level = await expand(level, [...level.path.slice(1), ...argv]);
     command = level.commands[level.aliases?.[name] ?? name];
@@ -1054,38 +1213,75 @@ async function dispatch(level, typed, { version, redact }) {
   if (command === undefined && level.defaultCommand !== undefined) {
     command = level.commands[level.defaultCommand];
     rest = argv;
+    ran = level.defaultCommand;
   }
   if (command === undefined) {
-    const meant = closest(name, Object.keys(level.commands));
+    const meant = closest(name, Object.keys(shown(level.commands)));
     printError(prefix, `no command ${name}`, meant === undefined ? `run ${prefix} --help for its commands` : `did you mean ${meant}?`);
     return 2;
   }
   if ("commands" in command) {
     const { summary } = command;
-    return dispatch({ path: [...level.path, name], header: (colors, text) => `${colors.bold(`${prefix} ${name}`)}  ${text}`, summary, ...scopeOf(command.commands, command.extraCommands, command.aliases), defaultCommand: undefined, examples: command.examples, replaces: undefined }, rest, { version, redact });
+    return dispatch({ path: [...level.path, name], header: (colors, text) => `${colors.bold(`${prefix} ${name}`)}  ${text}`, summary, ...scopeOf(command.commands, command.extraCommands, command.aliases), defaultCommand: undefined, runBare: false, examples: command.examples, replaces: undefined }, rest, { version, redact });
   }
   try {
     return await command.run(rest);
   } catch (error) {
-    return reportThrown(`${prefix} ${name}`, error, redact, wantsJson(rest));
+    return reportThrown(`${prefix} ${ran}`, error, redact, wantsJson(rest));
   }
 }
-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({});
+}
+async function optionsOf(run) {
+  return (await completingOf(run)).options;
+}
+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 candidates(scope, defaultCommand, words, before = []) {
   const [word = "", ...rest] = words;
@@ -1096,8 +1292,13 @@ async function candidates(scope, defaultCommand, words, before = []) {
     ({ commands, aliases } = await expand(scope, [...before, ...words]));
     command = commands[aliases?.[word] ?? word];
   }
-  if (listing)
-    return Promise.all(Object.entries(commands).map(async ([name, { summary }]) => `${name}	${await resolveSummary(summary)}`));
+  if (listing) {
+    const own = await Promise.all(Object.entries(shown(commands)).map(async ([name, { summary }]) => `${name}	${await resolveSummary(summary)}`));
+    const fallback = defaultCommand === undefined ? undefined : commands[defaultCommand];
+    const values = fallback !== undefined && "run" in fallback ? await leafCandidates(fallback.run, [word]) : [];
+    const valueOf = (line) => line.slice(0, line.includes("\t") ? line.indexOf("\t") : undefined);
+    return [...own, ...values.filter((line) => line !== FILES && !(valueOf(line) in commands))];
+  }
   if (command === undefined) {
     const fallback = defaultCommand === undefined ? undefined : commands[defaultCommand];
     return fallback !== undefined && "run" in fallback ? leafCandidates(fallback.run, words) : [];
@@ -1109,16 +1310,38 @@ async function printCandidates(found) {
     console.log(line);
   return 0;
 }
-async function runCli(cli, argv = process6.argv.slice(2)) {
+async function runCli(cli, argv = process8.argv.slice(2)) {
   if (argv[0] === COMPLETE)
     return printCandidates(candidates(scopeOf(cli.commands, cli.extraCommands, cli.aliases), cli.defaultCommand, argv.slice(1)));
-  return dispatch({ path: [cli.name], header: (colors, about) => `${colors.bold(cli.name)} ${colors.dim(cli.version)}  ${about}`, summary: cli.about, ...scopeOf(cli.commands, cli.extraCommands, cli.aliases), defaultCommand: cli.defaultCommand, examples: cli.examples, replaces: cli.replaces }, argv, { version: cli.version, redact: cli.redact });
+  const code = await dispatch({ path: [cli.name], header: (colors, about) => `${colors.bold(cli.name)} ${colors.dim(cli.version)}  ${about}`, summary: cli.about, ...scopeOf(cli.commands, cli.extraCommands, cli.aliases), defaultCommand: cli.defaultCommand, runBare: cli.runBare === true, examples: cli.examples, replaces: cli.replaces }, argv, { version: cli.version, redact: cli.redact });
+  if (cli.usage !== false) {
+    try {
+      recordUsage(usageEntry(cli.name, commandPath(scopeOf(cli.commands, cli.extraCommands, cli.aliases), argv), argv, code));
+    } catch {}
+  }
+  return code;
+}
+function commandPath(scope, argv) {
+  const path = [];
+  let level = scope;
+  for (const word of argv.filter((each) => !each.startsWith("-"))) {
+    const name = level.aliases !== undefined && Object.hasOwn(level.aliases, word) ? level.aliases[word] ?? word : word;
+    const command = Object.hasOwn(level.commands, name) ? level.commands[name] : undefined;
+    if (command === undefined)
+      break;
+    path.push(word);
+    if (!("commands" in command))
+      break;
+    level = scopeOf(command.commands, command.extraCommands, command.aliases);
+  }
+  return path.length === 0 ? undefined : path.join(" ");
 }
 var LEVEL_OPTIONS, TOP_OPTIONS, COMPLETE = "__complete", FILES = "__files__";
 var init_cli = __esm(() => {
   init_args();
   init_style();
   init_text();
+  init_usage();
   LEVEL_OPTIONS = {
     ...OUTPUT_OPTIONS,
     help: { type: "boolean", short: "h", description: "show this help" }
@@ -1140,7 +1363,7 @@ var init_git = __esm(() => {
 // ../kit/src/limit.ts
 function limitOptions(fallback) {
   return {
-    limit: { type: "string", description: `show at most this many rows, the rest counted (${fallback})` },
+    limit: { type: "string", short: "n", description: `show at most this many rows, the rest counted (${fallback})` },
     full: { type: "boolean", description: "show every row" }
   };
 }
@@ -1162,12 +1385,6 @@ var init_limit = __esm(() => {
   init_args();
 });
 
-// ../kit/src/logs.ts
-var DAY_MS;
-var init_logs = __esm(() => {
-  DAY_MS = 24 * 60 * 60 * 1000;
-});
-
 // ../kit/src/secrets.ts
 var SECRET_WORDS;
 var init_secrets = __esm(() => {
@@ -1199,6 +1416,7 @@ var init_src = __esm(() => {
   init_style();
   init_text();
   init_tool();
+  init_usage();
 });
 
 // src/registry.ts
@@ -1257,9 +1475,9 @@ var init_registry = __esm(() => {
 });
 
 // src/config.ts
-import { homedir } from "os";
-import { dirname, join } from "path";
-import process8 from "process";
+import { homedir as homedir2 } from "os";
+import { dirname as dirname2, join as join2 } from "path";
+import process10 from "process";
 function expand2(value, env) {
   let missing = false;
   const expanded = value.replace(ENV_REFERENCE, (_, braced, bare) => {
@@ -1348,18 +1566,18 @@ async function readIfThere(path) {
   const file = Bun.file(path);
   return await file.exists() ? file.text() : undefined;
 }
-async function loadConfigs(cwd = process8.cwd(), env = process8.env, home = homedir()) {
+async function loadConfigs(cwd = process10.cwd(), env = process10.env, home = homedir2()) {
   const directories = [];
-  for (let dir = cwd;!directories.includes(dir); dir = dirname(dir))
+  for (let dir = cwd;!directories.includes(dir); dir = dirname2(dir))
     directories.push(dir);
   if (!directories.includes(home))
     directories.push(home);
   const configs = [];
   for (const dir of directories) {
-    const bunfig = await readIfThere(join(dir, "bunfig.toml"));
-    const npmrc = await readIfThere(join(dir, ".npmrc"));
+    const bunfig = await readIfThere(join2(dir, "bunfig.toml"));
+    const npmrc = await readIfThere(join2(dir, ".npmrc"));
     if (bunfig !== undefined)
-      configs.push(readable(join(dir, "bunfig.toml"), () => parseBunfig(bunfig, env)));
+      configs.push(readable(join2(dir, "bunfig.toml"), () => parseBunfig(bunfig, env)));
     if (npmrc !== undefined)
       configs.push(parseNpmrc(npmrc, env));
   }
@@ -1377,11 +1595,11 @@ function parseSettings(text) {
     settings.blockSeverity = raw.blockSeverity;
   return settings;
 }
-async function loadSettings(cwd = process8.cwd(), home = homedir()) {
+async function loadSettings(cwd = process10.cwd(), home = homedir2()) {
   const files = [];
-  for (let dir = cwd;!files.includes(join(dir, SETTINGS_FILE)); dir = dirname(dir))
-    files.push(join(dir, SETTINGS_FILE));
-  files.push(join(home, ".config", "pkg", "config.json"));
+  for (let dir = cwd;!files.includes(join2(dir, SETTINGS_FILE)); dir = dirname2(dir))
+    files.push(join2(dir, SETTINGS_FILE));
+  files.push(join2(home, ".config", "pkg", "config.json"));
   const settings = {};
   for (const file of files) {
     const text = await readIfThere(file);
@@ -2240,12 +2458,12 @@ function render(report, now = Date.now()) {
 `);
 }
 async function check(args) {
-  const parsed = parse(args, usage, options);
+  const parsed = parse(args, usage2, options);
   const { values, positionals } = parsed;
   if (positionals.length === 0)
     fail(`a package name is needed
 
-${usage}`);
+${usage2}`);
   const context = { configs: await loadConfigs(), settings: await loadSettings(), minAgeDays: wholeNumber(values["min-age"], "min-age", DEFAULT_MIN_AGE_DAYS, 0) };
   const reports = await Promise.all(positionals.map(async (text) => checkPackage(text, context)));
   if (values.json === true)
@@ -2256,7 +2474,7 @@ ${usage}`);
 `));
   return reports.some((report) => report.blocked) ? 1 : 0;
 }
-var usage = `pkg [check] <name>[@version]...
+var usage2 = `pkg [check] <name>[@version]...
 
 Checks npm packages before they are added: whether the name exists, the latest and the newest version at least two weeks old, weekly downloads, licence, repository, install scripts and a near miss of a popular name.
 
@@ -2309,8 +2527,8 @@ var exports_audit = {};
 __export(exports_audit, {
   audit: () => audit
 });
-import { join as join2, resolve as resolve2 } from "path";
-import process9 from "process";
+import { join as join3, resolve as resolve2 } from "path";
+import process11 from "process";
 function hasFinding(audited) {
   return audited.blocked || audited.warnings.length > 0 || audited.advisories.length > 0;
 }
@@ -2365,12 +2583,12 @@ function renderAudit(findings, total) {
 `);
 }
 async function audit(args) {
-  const { values, positionals: [asked] } = parse(args, usage2, options2, { positionals: ["[dir]"] });
+  const { values, positionals: [asked] } = parse(args, usage3, options2, { positionals: ["[dir]"] });
   const level = values["audit-level"] ?? "low";
   if (!isSeverity(level))
     fail(`--audit-level takes ${SEVERITIES.join(", ")}, not ${level}`);
-  const dir = resolve2(asked ?? process9.cwd());
-  const lock = Bun.file(join2(dir, "bun.lock"));
+  const dir = resolve2(asked ?? process11.cwd());
+  const lock = Bun.file(join3(dir, "bun.lock"));
   if (!await lock.exists())
     fail(`no bun.lock in ${dir}`);
   const packages = parseBunLock(await lock.text());
@@ -2393,7 +2611,7 @@ async function audit(args) {
     return 1;
   return unavailable.length > 0 ? 2 : 0;
 }
-var usage2 = `pkg audit [dir]
+var usage3 = `pkg audit [dir]
 
 Reads the bun.lock in the folder (the current one by default) and runs on every registry package it pins the checks \`pkg check\` runs before an add: age, install scripts, a deprecated version, a near miss of a popular name, and the licence allowlist of the pkg config. It also lists the known advisories of each version, with the GHSA, the severity and the fixed version, from the registry's bulk advisory endpoint, the one \`bun audit\` reads.
 Findings are grouped per package, each registry package looked up once per run.
@@ -2492,7 +2710,7 @@ var init_pin = __esm(() => {
 
 // src/consumers.ts
 import { existsSync, readdirSync, readFileSync } from "fs";
-import { dirname as dirname2, join as join3, relative } from "path";
+import { dirname as dirname3, join as join4, relative } from "path";
 function packageFiles(dir, depth, found) {
   let entries;
   try {
@@ -2502,18 +2720,18 @@ function packageFiles(dir, depth, found) {
   }
   for (const entry of entries) {
     if (entry.isFile() && entry.name === "package.json")
-      found.push(join3(dir, entry.name));
+      found.push(join4(dir, entry.name));
     else if (entry.isDirectory() && depth < MAX_DEPTH && !entry.name.startsWith(".") && !SKIPPED.has(entry.name))
-      packageFiles(join3(dir, entry.name), depth + 1, found);
+      packageFiles(join4(dir, entry.name), depth + 1, found);
   }
   return found;
 }
 function managerFor(dir, root) {
-  for (let at = dir;; at = dirname2(at)) {
-    const lockfile = LOCKFILES.find(([file]) => existsSync(join3(at, file)));
+  for (let at = dir;; at = dirname3(at)) {
+    const lockfile = LOCKFILES.find(([file]) => existsSync(join4(at, file)));
     if (lockfile !== undefined)
       return lockfile[1];
-    if (at === root || at === dirname2(at))
+    if (at === root || at === dirname3(at))
       return "bun";
   }
 }
@@ -2529,7 +2747,7 @@ function findConsumers(name, root) {
     const kind = KINDS.find((each) => typeof manifest[each]?.[name] === "string");
     const spec = kind === undefined ? undefined : manifest[kind]?.[name];
     if (kind !== undefined && spec !== undefined)
-      consumers.push({ dir: relative(root, dirname2(path)) || ".", path, kind, spec, manager: managerFor(dirname2(path), root) });
+      consumers.push({ dir: relative(root, dirname3(path)) || ".", path, kind, spec, manager: managerFor(dirname3(path), root) });
   }
   return consumers;
 }
@@ -2555,8 +2773,8 @@ __export(exports_bump, {
   bump: () => bump
 });
 import { existsSync as existsSync2 } from "fs";
-import { homedir as homedir2 } from "os";
-import { dirname as dirname3, join as join4, relative as relative2 } from "path";
+import { homedir as homedir3 } from "os";
+import { dirname as dirname4, join as join5, relative as relative2 } from "path";
 async function lookup(name, registry, fetcher) {
   try {
     return { packument: await fetchPackument(name, registry, fetcher) };
@@ -2616,11 +2834,11 @@ async function vet(name, version, settings) {
   return false;
 }
 function lockfileOf(dir, root) {
-  for (let at = dir;; at = dirname3(at)) {
-    const found = ["bun.lock", "bun.lockb"].find((file) => existsSync2(join4(at, file)));
+  for (let at = dir;; at = dirname4(at)) {
+    const found = ["bun.lock", "bun.lockb"].find((file) => existsSync2(join5(at, file)));
     if (found !== undefined)
-      return relative2(dir, join4(at, found));
-    if (at === root || at === dirname3(at))
+      return relative2(dir, join5(at, found));
+    if (at === root || at === dirname4(at))
       return;
   }
 }
@@ -2654,7 +2872,7 @@ async function bumpConsumers(name, version, settings) {
     note(`${local} non-registry dependenc${local === 1 ? "y" : "ies"} (workspace:, file:, git, URL, alias, catalog:)`, "left as they are");
   for (const consumer of consumers) {
     const argv = addCommand(consumer, name, version);
-    const where = join4(settings.root, consumer.dir);
+    const where = join5(settings.root, consumer.dir);
     if (consumer.kind === "peerDependencies") {
       skipped.push(consumer.dir);
       note(consumer.dir, `peer range ${consumer.spec}, left as it is`);
@@ -2697,9 +2915,9 @@ async function bumpConsumers(name, version, settings) {
   return isClean;
 }
 async function bump(args) {
-  const { values, positionals: [name, asked] } = parse(args, usage3, options3, { positionals: ["<name>", "[version]"] });
+  const { values, positionals: [name, asked] } = parse(args, usage4, options3, { positionals: ["<name>", "[version]"] });
   const settings = {
-    root: values.root ?? join4(homedir2(), "Workspace"),
+    root: values.root ?? join5(homedir3(), "Workspace"),
     configs: await loadConfigs(),
     timeout: duration(values.timeout, "timeout", 10 * 60000),
     isDryRun: values["dry-run"] === true,
@@ -2713,7 +2931,7 @@ async function bump(args) {
     return 1;
   return await bumpConsumers(name, version, settings) ? 0 : 1;
 }
-var usage3 = `pkg bump <name> [version]
+var usage4 = `pkg bump <name> [version]
 
 Waits until the registry serves the version (the latest when none is given, an exact version otherwise), vets it as \`pkg check\` does (advisories, licence allowlist, and a minimum age only when --min-age asks for one), then runs \`bun add --exact --no-cache\` in each folder under --root whose package.json depends on the package, the kind of dependency kept, a line per folder.
 A version the vetting blocks is refused before any folder is touched, unless --force is given.
@@ -2745,11 +2963,11 @@ var exports_consumers = {};
 __export(exports_consumers, {
   consumers: () => consumers
 });
-import { homedir as homedir3 } from "os";
-import { join as join5 } from "path";
+import { homedir as homedir4 } from "os";
+import { join as join6 } from "path";
 function consumers(args) {
-  const { values, positionals: [name] } = parse(args, usage4, options4, { positionals: ["<name>"] });
-  const root = values.root ?? join5(homedir3(), "Workspace");
+  const { values, positionals: [name] } = parse(args, usage5, options4, { positionals: ["<name>"] });
+  const root = values.root ?? join6(homedir4(), "Workspace");
   const { shown, footer } = capped(findConsumers(name, root), limitOf(values, CONSUMERS_LIMIT));
   if (values.json === true)
     printJson(shown);
@@ -2760,7 +2978,7 @@ function consumers(args) {
 `));
   return 0;
 }
-var usage4 = `pkg consumers <name>
+var usage5 = `pkg consumers <name>
 
 Lists the folders under --root whose package.json depends on the package: the folder, the kind of dependency, the version it asks for and the manager its lockfile pins, 30 at most with the count of the rest after them (--limit <n>, --full for all; --json is never cut unless --limit is given).
 
@@ -2778,12 +2996,12 @@ var init_consumers2 = __esm(() => {
 
 // src/cli.ts
 init_src();
-import process10 from "process";
+import process12 from "process";
 // package.json
-var version = "0.7.0";
+var version = "0.7.1";
 
 // src/cli.ts
-process10.exitCode = await runCli({
+process12.exitCode = await runCli({
   name: "pkg",
   version,
   about: "checks npm packages before they are added, and moves a lib's consumers onto a new release",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kaynooo/cli-pkg",
   "type": "module",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "pkg: check an npm package before it is added, for a guessed name, a version under two weeks old and install scripts.",
   "author": "Kaynooo <contact@kaynooo.fr>",
   "license": "MIT",
@@ -30,6 +30,6 @@
     "record": "$npm_execpath scripts/record.ts"
   },
   "devDependencies": {
-    "@kaynooo/cli-kit": "0.15.0"
+    "@kaynooo/cli-kit": "0.20.0"
   }
 }