@ix-xs/node-comfort 2.0.0 → 2.1.0

package/src/Cli.js

@@ -15,9 +15,9 @@
  * spin.succeed("Installed");
  */
 
-const readline = require("node:readline");
 const { parseArgs } = require("node:util");
 const color = require("./Color.js");
+const { AbortError } = require("./errors.js");
 
 /**
  * Border styles for `table()` and `box()`.
@@ -143,14 +143,15 @@ const color = require("./Color.js");
  * @property {unknown} [default] Used when the flag is missing.
  * @property {boolean} [multiple] Can be repeated (`--tag a --tag b`); you get an array.
  * @property {boolean} [required] Fail if it's missing.
- * @property {readonly string[]} [choices] Allowed values, for string flags.
+ * @property {readonly string[] | readonly number[]} [choices] Allowed values.
+ * @property {string} [env] An environment variable to read when the flag isn't given, like `"PORT"`. The command line wins, then the variable, then `default`.
  * @property {string} [description] Shown in `--help`.
  */
 
 /**
  * The type of a flag's value.
  * @template {FlagSpec} F
- * @typedef {F["type"] extends "number" ? number : F["type"] extends "boolean" ? boolean : F extends { choices: readonly (infer C)[] } ? C : string} FlagValue
+ * @typedef {F["type"] extends "boolean" ? boolean : F extends { choices: readonly (infer C)[] } ? C : F["type"] extends "number" ? number : string} FlagValue
  */
 
 /**
@@ -166,9 +167,12 @@ const color = require("./Color.js");
  * @property {string} [name] Program name in the help. Defaults to the script name.
  * @property {string} [description] Shown at the top of the help.
  * @property {string} [usage] A usage line, like `"<file> [options]"`.
+ * @property {Record<string, string>} [commands] Subcommands and what they do, like `{ build: "Build the project" }`. The first argument, when there is one, must be one of them and comes back as `command`. They share the flags of the program.
+ * @property {string[]} [examples] Command lines shown at the end of the help.
  * @property {boolean} [help] Answer `--help` and `-h` by printing the help and exiting. Defaults to `true`.
  * @property {string} [version] Answer `--version` with this version.
  * @property {boolean} [strict] Reject unknown flags, with a suggestion. Defaults to `true`.
+ * @property {Record<string, string | undefined>} [env] Where `env` flags are read from. Defaults to `process.env`.
  */
 
 /**
@@ -177,9 +181,22 @@ const color = require("./Color.js");
  * @typedef {object} ParsedArgs
  * @property {ParsedFlags<S>} flags
  * @property {string[]} positionals Arguments that aren't flags.
+ * @property {string | undefined} command The subcommand, when `commands` was given.
  * @property {() => string} help The generated help text.
  */
 
+/**
+ * Options for `spin()`: the spinner's, plus what to say at the end.
+ * @template T
+ * @typedef {SpinnerOptions & { success?: string | ((result: T) => string), fail?: string | ((error: unknown) => string) }} SpinOptions
+ */
+
+/**
+ * Options for `tree()`.
+ * @typedef {object} TreeOptions
+ * @property {boolean} [ascii] Draw with `|`, `+` and `-` instead of box characters.
+ */
+
 /** @type {Record<BorderStyle, string[]>} top-left, top, top-right, right, bottom-right, bottom, bottom-left, left, mid-left, mid, mid-right, cross, top-mid, bottom-mid */
 const BORDERS = {
   rounded: ["╭", "─", "╮", "│", "╯", "─", "╰", "│", "├", "─", "┤", "┼", "┬", "┴"],
@@ -193,6 +210,25 @@ const BORDERS = {
 const SHOW_CURSOR = "\u001b[?25h";
 const HIDE_CURSOR = "\u001b[?25l";
 const CLEAR_LINE = "\r\u001b[2K";
+const CLEAR_BELOW = "\u001b[0J";
+const ESCAPE = "\u001b";
+/** @param {number} lines */
+const _up = (lines) => `\u001b[${lines}A`;
+
+const _FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const _LINE_BREAK = /\r?\n/;
+const _LINE_BREAKS = /\r?\n/g;
+
+/**
+ * Makes sure a status line fits on one row: a line that wraps can't be
+ * cleared with a single escape code.
+ * @param {string} line
+ * @param {{ columns?: number }} stream
+ */
+const _oneRow = (line, stream) => {
+  const flat = line.includes("\n") ? line.replace(_LINE_BREAKS, " ") : line;
+  return stream.columns ? color.truncate(flat, stream.columns - 1) : flat;
+};
 
 /** @param {boolean | undefined} forced */
 const _palette = (forced) => (forced === undefined ? color : color.create(forced ? (color.level > 0 ? color.level : 3) : 0));
@@ -221,21 +257,6 @@ const _align = (text, width, align) => {
   return text + " ".repeat(gap);
 };
 
-/**
- * @param {string} text
- * @param {number} max
- */
-const _cut = (text, max) => {
-  if (color.width(text) <= max) return text;
-  const plain = color.strip(text);
-  let out = "";
-  for (const { segment } of new Intl.Segmenter().segment(plain)) {
-    if (color.width(out + segment) > max - 1) break;
-    out += segment;
-  }
-  return `${out}…`;
-};
-
 /** @param {unknown} value */
 const _cell = (value) => {
   if (value === null || value === undefined) return "";
@@ -290,53 +311,82 @@ const _restoreCursorOnExit = (stream) => {
 function table(rows, options = {}) {
   const palette = _palette(options.colors);
   const padding = " ".repeat(Math.max(0, options.padding ?? 1));
+  const markdown = options.border === "markdown";
   const isArrayRows = rows.length > 0 && Array.isArray(rows[0]);
-  /** @type {TableColumn[]} */
-  const columns = (options.columns ?? (isArrayRows
-    ? Array.from({ length: Math.max(0, ...rows.map((r) => /** @type {unknown[]} */ (r).length)) }, (_, i) => i)
-    : [...new Set(rows.flatMap((r) => Object.keys(/** @type {object} */ (r ?? {}))))]
-  )).map((c) => (typeof c === "object" ? c : { key: c }));
-
-  const body = rows.map((row) => columns.map((col) => {
-    const raw = /** @type {any} */ (row)?.[col.key];
-    const value = col.format ? col.format(raw, row) : raw;
-    const text = _cell(value);
-    return { text: col.maxWidth ? _cut(text, col.maxWidth) : text, numeric: typeof raw === "number" || typeof raw === "bigint" };
-  }));
+  /** @type {Array<string | number | TableColumn>} */
+  let keys = options.columns ?? [];
+  if (!options.columns && isArrayRows) {
+    let longest = 0;
+    for (const row of rows) longest = Math.max(longest, /** @type {unknown[]} */ (row).length);
+    keys = Array.from({ length: longest }, (_, i) => i);
+  } else if (!options.columns) {
+    /** @type {Set<string>} */
+    const seen = new Set();
+    for (const row of rows) for (const key of Object.keys(row ?? {})) seen.add(key);
+    keys = [...seen];
+  }
+  const columns = keys.map((column) => (typeof column === "object" ? column : { key: column }));
+  if (!columns.length) return "";
   const showHeader = options.header ?? !isArrayRows;
-  const headers = columns.map((c) => c.header ?? String(c.key));
-  const widths = columns.map((c, i) => Math.max(showHeader ? color.width(headers[i]) : 0, ...body.map((r) => color.width(r[i].text)), 1));
-  const alignOf = (/** @type {number} */ i, /** @type {boolean} */ numeric) => columns[i].align ?? (numeric ? "right" : "left");
+  const headers = columns.map((column) => column.header ?? String(column.key));
+  const widths = headers.map((header) => Math.max(markdown ? 3 : 1, showHeader ? color.width(header) : 0));
+  const numeric = columns.map(() => rows.length > 0);
+
+  /** @type {Array<Array<{ lines: string[], numeric: boolean }>>} */
+  const body = [];
+  for (const row of rows) {
+    /** @type {Array<{ lines: string[], numeric: boolean }>} */
+    const cells = [];
+    for (let i = 0; i < columns.length; i++) {
+      const column = columns[i];
+      const raw = /** @type {any} */ (row)?.[column.key];
+      const text = _cell(column.format ? column.format(raw, row) : raw);
+      let lines = text.includes("\n") ? text.split(_LINE_BREAK) : [text];
+      if (column.maxWidth) lines = lines.map((line) => color.truncate(line, /** @type {number} */ (column.maxWidth)));
+      // Markdown has no multi-line cells, and a pipe would end the cell.
+      if (markdown) lines = [lines.join("<br>").replace(/\|/g, "\\|")];
+      for (const line of lines) widths[i] = Math.max(widths[i], color.width(line));
+      const isNumber = typeof raw === "number" || typeof raw === "bigint";
+      if (!isNumber) numeric[i] = false;
+      cells.push({ lines, numeric: isNumber });
+    }
+    body.push(cells);
+  }
 
-  if (options.border === "markdown") {
+  if (markdown) {
     const line = (/** @type {string[]} */ cells) => `| ${cells.join(" | ")} |`;
-    const escaped = body.map((r) => r.map((c) => ({ ...c, text: c.text.replace(/\|/g, "\\|") })));
-    const mdWidths = widths.map((w, i) => Math.max(3, w, ...escaped.map((r) => color.width(r[i].text))));
-    /** @type {Array<"left" | "center" | "right">} */
-    const mdAlign = columns.map((c, i) => c.align ?? (body.length > 0 && body.every((r) => r[i].numeric) ? "right" : "left"));
+    const aligns = columns.map((column, i) => column.align ?? (numeric[i] ? "right" : "left"));
     const out = [];
     if (showHeader) {
-      out.push(line(headers.map((h, i) => _align(h, mdWidths[i], mdAlign[i]))));
-      out.push(line(mdWidths.map((w, i) => {
-        const dashes = "-".repeat(w);
-        return mdAlign[i] === "center" ? `:${dashes.slice(2)}:` : mdAlign[i] === "right" ? `${dashes.slice(1)}:` : dashes;
+      out.push(line(headers.map((header, i) => _align(header, widths[i], aligns[i]))));
+      out.push(line(widths.map((width, i) => {
+        const dashes = "-".repeat(width);
+        return aligns[i] === "center" ? `:${dashes.slice(2)}:` : aligns[i] === "right" ? `${dashes.slice(1)}:` : dashes;
       })));
     }
-    for (const r of escaped) out.push(line(r.map((c, i) => _align(c.text, mdWidths[i], mdAlign[i]))));
+    for (const cells of body) out.push(line(cells.map((cell, i) => _align(cell.lines[0], widths[i], aligns[i]))));
     return out.join("\n");
   }
 
-  const b = BORDERS[options.border ?? "rounded"];
-  const dim = (/** @type {string} */ s) => (palette.level > 0 ? palette.gray(s) : s);
+  const b = BORDERS[/** @type {BorderStyle} */ (options.border ?? "rounded")];
+  const dim = (/** @type {string} */ text) => (palette.level > 0 ? palette.gray(text) : text);
   const rule = (/** @type {string} */ left, /** @type {string} */ fill, /** @type {string} */ mid, /** @type {string} */ right) =>
-    dim(left + widths.map((w) => fill.repeat(w + padding.length * 2)).join(mid) + right);
-  const row = (/** @type {string[]} */ cells) => dim(b[7]) + cells.map((c) => padding + c + padding).join(dim(b[3])) + dim(b[3]);
+    dim(left + widths.map((width) => fill.repeat(width + padding.length * 2)).join(mid) + right);
+  const edge = dim(b[7]);
+  const separator = padding + dim(b[3]) + padding;
+  const line = (/** @type {string[]} */ cells) => edge + padding + cells.join(separator) + padding + dim(b[3]);
   const out = [rule(b[0], b[1], b[12], b[2])];
   if (showHeader) {
-    out.push(row(headers.map((h, i) => _align(palette.level > 0 ? palette.bold(h) : h, widths[i], columns[i].align ?? "left"))));
+    out.push(line(headers.map((header, i) => _align(palette.level > 0 ? palette.bold(header) : header, widths[i], columns[i].align ?? "left"))));
     out.push(rule(b[8], b[9], b[11], b[10]));
   }
-  for (const r of body) out.push(row(r.map((c, i) => _align(c.text, widths[i], alignOf(i, c.numeric)))));
+  for (const cells of body) {
+    let height = 1;
+    for (const cell of cells) height = Math.max(height, cell.lines.length);
+    for (let k = 0; k < height; k++) {
+      out.push(line(cells.map((cell, i) => _align(cell.lines[k] ?? "", widths[i], columns[i].align ?? (cell.numeric ? "right" : "left")))));
+    }
+  }
   out.push(rule(b[6], b[5], b[13], b[4]));
   return out.join("\n");
 }
@@ -346,10 +396,10 @@ function table(rows, options = {}) {
  *
  * @example
  * console.log(cli.box("Server ready\nhttp://localhost:3000", { title: "my-app", borderColor: "green" }));
- * // ╭─ my-app ──────────────────╮
- * // │  Server ready             │
- * // │  http://localhost:3000    │
- * // ╰───────────────────────────╯
+ * // ╭─ my-app ────────────────╮
+ * // │  Server ready           │
+ * // │  http://localhost:3000  │
+ * // ╰─────────────────────────╯
  *
  * @param {string} text
  * @param {BoxOptions} [options]
@@ -359,24 +409,96 @@ function box(text, options = {}) {
   const palette = _palette(options.colors);
   const b = BORDERS[options.border ?? "rounded"];
   const pad = typeof options.padding === "number" ? { x: options.padding, y: Math.floor(options.padding / 2) } : { x: 2, y: 0, ...options.padding };
-  const lines = String(text).split(/\r?\n/);
+  const lines = String(text).split(_LINE_BREAK);
   const title = options.title ? ` ${options.title} ` : "";
-  const inner = Math.max(options.width ?? 0, ...lines.map((l) => color.width(l)), color.width(title) + 2 - pad.x * 2) + pad.x * 2;
+  let longest = Math.max(options.width ?? 0, color.width(title) + 2 - pad.x * 2);
+  for (const line of lines) longest = Math.max(longest, color.width(line));
+  const inner = longest + pad.x * 2;
   const paint = (/** @type {string} */ s) => _paint(palette, options.borderColor, s);
   const top = title
     ? paint(b[0] + b[1]) + (palette.level > 0 ? palette.bold(title) : title) + paint(b[1].repeat(Math.max(0, inner - color.width(title) - 1)) + b[2])
     : paint(b[0] + b[1].repeat(inner) + b[2]);
+  const left = paint(b[7]) + " ".repeat(pad.x);
+  const right = " ".repeat(pad.x) + paint(b[3]);
   const blank = paint(b[7]) + " ".repeat(inner) + paint(b[3]);
   const out = [top];
   for (let i = 0; i < pad.y; i++) out.push(blank);
-  for (const line of lines) {
-    out.push(paint(b[7]) + " ".repeat(pad.x) + _align(line, inner - pad.x * 2, options.align ?? "left") + " ".repeat(pad.x) + paint(b[3]));
-  }
+  for (const line of lines) out.push(left + _align(line, longest, options.align ?? "left") + right);
   for (let i = 0; i < pad.y; i++) out.push(blank);
   out.push(paint(b[6] + b[5].repeat(inner) + b[4]));
   return out.join("\n");
 }
 
+/**
+ * Draws nested data as a tree, like the `tree` command does for folders.
+ * Keys are branches. A value that is an object or an array opens a level,
+ * `null` or `true` makes a plain leaf, anything else is shown after the key.
+ *
+ * @example
+ * console.log(cli.tree({
+ *   src: { "index.js": null, lib: ["a.js", "b.js"] },
+ *   "package.json": "1.2 kB",
+ * }));
+ * // ├── src
+ * // │   ├── index.js
+ * // │   └── lib
+ * // │       ├── a.js
+ * // │       └── b.js
+ * // └── package.json: 1.2 kB
+ *
+ * @param {Record<string, unknown> | unknown[]} data
+ * @param {TreeOptions} [options]
+ * @returns {string}
+ */
+function tree(data, options = {}) {
+  const [branch, last, pipe, blank] = options.ascii ? ["+-- ", "+-- ", "|   ", "    "] : ["├── ", "└── ", "│   ", "    "];
+  /** @type {string[]} */
+  const out = [];
+  /** @type {object[]} */
+  const open = [];
+  /** @param {unknown} value */
+  const isBranch = (value) => value !== null && typeof value === "object" && !(value instanceof Date);
+  /**
+   * @param {object} node
+   * @returns {Array<[string, unknown]>}
+   */
+  const entriesOf = (node) => {
+    if (!Array.isArray(node)) return Object.entries(node);
+    /** @type {Array<[string, unknown]>} */
+    const entries = [];
+    for (const item of node) {
+      // An object in a list has no name of its own: its keys take its place.
+      if (isBranch(item) && !Array.isArray(item)) entries.push(...Object.entries(item));
+      else entries.push([_cell(item), null]);
+    }
+    return entries;
+  };
+  /**
+   * @param {object} node
+   * @param {string} indent
+   */
+  const walk = (node, indent) => {
+    if (open.includes(node)) {
+      out.push(`${indent}${last}(circular)`);
+      return;
+    }
+    open.push(node);
+    const entries = entriesOf(node);
+    entries.forEach(([label, value], i) => {
+      const isLast = i === entries.length - 1;
+      const nested = isBranch(value);
+      const text = nested || value === null || value === undefined || value === true ? label : `${label}: ${_cell(value)}`;
+      const [first, ...rest] = text.split(_LINE_BREAK);
+      out.push(indent + (isLast ? last : branch) + first);
+      for (const line of rest) out.push(indent + (isLast ? blank : pipe) + line);
+      if (nested) walk(/** @type {object} */ (value), indent + (isLast ? blank : pipe));
+    });
+    open.pop();
+  };
+  if (isBranch(data)) walk(data, "");
+  return out.join("\n");
+}
+
 /**
  * A spinner for work in progress. Call `.start()`, then finish with
  * `.succeed()`, `.fail()`, `.warn()`, `.info()` or `.stop()`.
@@ -396,24 +518,25 @@ function box(text, options = {}) {
  */
 function spinner(text = "", options = {}) {
   const stream = options.stream ?? process.stderr;
-  const frames = options.frames ?? ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+  const frames = options.frames?.length ? options.frames : _FRAMES;
   const palette = color.create(color.detect(stream));
   const interactive = _isTTY(stream);
   /** @type {NodeJS.Timeout | undefined} */
   let timer;
+  let spinning = false;
   let frame = 0;
   let current = text;
 
   const render = () => {
-    stream.write(`${CLEAR_LINE}${_paint(palette, options.color ?? "cyan", frames[frame % frames.length])} ${current}`);
-    frame++;
+    stream.write(CLEAR_LINE + _oneRow(`${_paint(palette, options.color ?? "cyan", frames[frame++ % frames.length])} ${current}`, stream));
   };
   /**
    * @param {string} symbol
    * @param {string | undefined} finalText
    */
   const finish = (symbol, finalText) => {
-    const wasSpinning = timer !== undefined;
+    const wasSpinning = spinning;
+    spinning = false;
     clearInterval(timer);
     timer = undefined;
     if (interactive && wasSpinning) stream.write(`${CLEAR_LINE}${SHOW_CURSOR}`);
@@ -426,12 +549,12 @@ function spinner(text = "", options = {}) {
     start(newText) {
       if (newText !== undefined) current = newText;
       if (!interactive) {
-        if (timer === undefined) stream.write(`- ${current}\n`);
-        timer = setInterval(() => {}, 1 << 30);
-        timer.unref();
+        if (!spinning) stream.write(`- ${current}\n`);
+        spinning = true;
         return self;
       }
       clearInterval(timer);
+      spinning = true;
       _restoreCursorOnExit(stream);
       stream.write(HIDE_CURSOR);
       render();
@@ -448,15 +571,53 @@ function spinner(text = "", options = {}) {
     },
     set text(value) {
       current = value;
-      if (timer !== undefined && interactive) render();
+      if (spinning && interactive) render();
     },
     get isSpinning() {
-      return timer !== undefined;
+      return spinning;
     },
   };
   return self;
 }
 
+/**
+ * Shows a spinner while some work runs, then `✔` or `✖` depending on how it
+ * ended. Resolves with the result of the work, or rejects with its error.
+ *
+ * @example
+ * const users = await cli.spin("Loading users", () => db.getAll("users"));
+ * await cli.spin("Deploying", deploy(), {
+ *   success: (url) => `Deployed to ${url}`,
+ *   fail: (error) => `Deploy failed: ${error.message}`,
+ * });
+ *
+ * @template T
+ * @param {string} text
+ * @param {Promise<T> | ((spinner: Spinner) => T | Promise<T>)} task A promise, or a function that gets the spinner so it can update the text.
+ * @param {SpinOptions<T>} [options]
+ * @returns {Promise<T>}
+ */
+async function spin(text, task, options = {}) {
+  const current = spinner(text, options).start();
+  try {
+    const result = await (typeof task === "function" ? task(current) : task);
+    current.succeed(typeof options.success === "function" ? options.success(result) : options.success);
+    return result;
+  } catch (error) {
+    current.fail(typeof options.fail === "function" ? options.fail(error) : options.fail);
+    throw error;
+  }
+}
+
+const _PROGRESS_TOKEN = /\{(bar|percent|value|total|eta|elapsed|rate|label)\}/g;
+
+/** @param {number} seconds */
+const _clock = (seconds) => {
+  if (seconds >= 3600) return `${Math.floor(seconds / 3600)}h${String(Math.floor((seconds % 3600) / 60)).padStart(2, "0")}m`;
+  if (seconds >= 60) return `${Math.floor(seconds / 60)}m${String(Math.floor(seconds % 60)).padStart(2, "0")}s`;
+  return `${Math.ceil(seconds)}s`;
+};
+
 /**
  * A progress bar with percentage, ETA and speed. It redraws at most every
  * 50 ms, so calling `tick()` in a tight loop is fine.
@@ -476,38 +637,47 @@ function progress(options) {
   const stream = options.stream ?? process.stderr;
   const interactive = _isTTY(stream);
   const palette = color.create(color.detect(stream));
+  const format = options.format ?? "{bar} {percent}% | {value}/{total} | ETA {eta}";
+  const width = Math.max(1, Math.floor(options.width ?? 30));
+  const complete = options.complete ?? "█";
+  const incomplete = options.incomplete ?? "░";
   const started = Date.now();
   let value = 0;
   let total = Math.max(0, options.total);
   let label = options.label ?? "";
   let lastRender = 0;
   let stopped = false;
+  let cursorHidden = false;
 
   const line = () => {
     const ratio = total > 0 ? Math.min(1, value / total) : 1;
-    const width = options.width ?? 30;
     const filled = Math.round(ratio * width);
     const elapsed = (Date.now() - started) / 1000;
     const rate = elapsed > 0 ? value / elapsed : 0;
-    const eta = rate > 0 && ratio < 1 ? (total - value) / rate : 0;
-    const fmt = (/** @type {number} */ s) => (s >= 3600 ? `${Math.floor(s / 3600)}h${String(Math.floor((s % 3600) / 60)).padStart(2, "0")}m` : s >= 60 ? `${Math.floor(s / 60)}m${String(Math.floor(s % 60)).padStart(2, "0")}s` : `${Math.ceil(s)}s`);
-    const bar = _paint(palette, "cyan", (options.complete ?? "█").repeat(filled)) + _paint(palette, "gray", (options.incomplete ?? "░").repeat(width - filled));
-    return (options.format ?? "{bar} {percent}% | {value}/{total} | ETA {eta}")
-      .replace("{bar}", bar)
-      .replace("{percent}", String(Math.floor(ratio * 100)).padStart(3))
-      .replace("{value}", String(value))
-      .replace("{total}", String(total))
-      .replace("{eta}", fmt(eta))
-      .replace("{elapsed}", fmt(elapsed))
-      .replace("{rate}", `${Math.round(rate * 10) / 10}/s`)
-      .replace("{label}", label);
+    /** @type {Record<string, string>} */
+    const values = {
+      bar: _paint(palette, "cyan", complete.repeat(filled)) + _paint(palette, "gray", incomplete.repeat(width - filled)),
+      percent: String(Math.floor(ratio * 100)).padStart(3),
+      value: String(value),
+      total: String(total),
+      eta: _clock(rate > 0 && ratio < 1 ? (total - value) / rate : 0),
+      elapsed: _clock(elapsed),
+      rate: `${Math.round(rate * 10) / 10}/s`,
+      label,
+    };
+    return format.replace(_PROGRESS_TOKEN, (_token, name) => values[name]);
   };
   const draw = (/** @type {boolean} */ force) => {
     if (!interactive || stopped) return;
     const now = Date.now();
     if (!force && now - lastRender < 50 && value < total) return;
     lastRender = now;
-    stream.write(`${CLEAR_LINE}${line()}`);
+    if (!cursorHidden) {
+      cursorHidden = true;
+      _restoreCursorOnExit(stream);
+      stream.write(HIDE_CURSOR);
+    }
+    stream.write(CLEAR_LINE + _oneRow(line(), stream));
   };
 
   /** @type {ProgressBar} */
@@ -525,7 +695,7 @@ function progress(options) {
       if (stopped) return self;
       draw(true);
       stopped = true;
-      stream.write(interactive ? "\n" : `${line()}\n`);
+      stream.write(interactive ? `\n${SHOW_CURSOR}` : `${line()}\n`);
       return self;
     },
     get value() {
@@ -566,21 +736,21 @@ const _ask = (question, input, output) =>
 /**
  * One line reader per input stream, shared by every prompt, so piped lines
  * that arrive early are queued instead of lost.
- * @typedef {{ rl: readline.Interface, lines: string[], waiting: Array<{ resolve: (line: string) => void, reject: (error: Error) => void }>, closed: boolean }} LineReader
+ * @typedef {{ rl: import("node:readline").Interface, lines: string[], waiting: Array<{ resolve: (line: string) => void, reject: (error: Error) => void }>, closed: boolean }} _LineReader
  */
 
-/** @type {WeakMap<NodeJS.ReadableStream, LineReader>} */
+/** @type {WeakMap<NodeJS.ReadableStream, _LineReader>} */
 const _readers = new WeakMap();
 
 /**
  * @param {NodeJS.ReadableStream} input
- * @returns {LineReader}
+ * @returns {_LineReader}
  */
 const _reader = (input) => {
   const existing = _readers.get(input);
   if (existing) return existing;
-  const rl = readline.createInterface({ input, terminal: false, crlfDelay: Infinity });
-  /** @type {LineReader} */
+  const rl = require("node:readline").createInterface({ input, terminal: false, crlfDelay: Infinity });
+  /** @type {_LineReader} */
   const reader = { rl, lines: [], waiting: [], closed: false };
   rl.on("line", (line) => {
     const next = reader.waiting.shift();
@@ -661,6 +831,8 @@ function password(question, options = {}) {
     input.resume();
     input.setEncoding("utf8");
     const onData = (/** @type {string} */ chunk) => {
+      // Arrow and function keys arrive as an escape sequence: not part of a password.
+      if (chunk.length > 1 && chunk.startsWith(ESCAPE)) return;
       for (const char of chunk) {
         if (char === "\r" || char === "\n") {
           cleanup();
@@ -668,10 +840,11 @@ function password(question, options = {}) {
           resolve(value);
           return;
         }
-        if (char === "\u0003") {
+        // Ctrl+C, Ctrl+D, Escape
+        if (char === "\u0003" || char === "\u0004" || char === ESCAPE) {
           cleanup();
           output.write("\n");
-          reject(new Error("Cancelled"));
+          reject(new AbortError("Cancelled"));
           return;
         }
         if (char === "\u007f" || char === "\b") {
@@ -681,6 +854,12 @@ function password(question, options = {}) {
           }
           continue;
         }
+        // Ctrl+U clears the line, as in a shell
+        if (char === "\u0015") {
+          if (mask) output.write("\b \b".repeat([...value].length));
+          value = "";
+          continue;
+        }
         if (char < " ") continue;
         value += char;
         if (mask) output.write(mask);
@@ -744,72 +923,87 @@ const _interactiveList = (question, items, options, multiple) =>
     const output = options.output ?? process.stdout;
     const palette = color.create(color.detect(output));
     const pageSize = Math.max(1, Math.min(options.pageSize ?? 10, items.length));
+    const hint = multiple ? "(↑↓ move, space select, a all, enter confirm)" : "(↑↓ move, enter confirm)";
+    const usable = items.map((item, i) => (item.disabled ? -1 : i)).filter((i) => i !== -1);
     let cursor = Math.min(Math.max(0, options.default ?? 0), items.length - 1);
-    while (items[cursor]?.disabled && cursor < items.length - 1) cursor++;
+    if (items[cursor].disabled) cursor = usable.find((i) => i > cursor) ?? usable[0];
+    /** @type {Set<number>} */
     const selected = new Set();
     let offset = 0;
     let drawn = 0;
     let error = "";
 
     const draw = () => {
-      if (drawn) output.write(`\u001b[${drawn}A`);
       if (cursor < offset) offset = cursor;
       if (cursor >= offset + pageSize) offset = cursor - pageSize + 1;
-      const lines = [`${palette.cyan("?")} ${question} ${palette.gray(multiple ? "(↑↓ move, space select, enter confirm)" : "(↑↓ move, enter confirm)")}`];
+      const position = items.length > pageSize ? ` ${cursor + 1}/${items.length}` : "";
+      const lines = [`${palette.cyan("?")} ${question} ${palette.gray(hint + position)}`];
       for (let i = offset; i < offset + pageSize; i++) {
         const item = items[i];
         const active = i === cursor;
-        const box = multiple ? (selected.has(i) ? palette.green("◉ ") : "◯ ") : "";
+        const mark = multiple ? (selected.has(i) ? palette.green("◉ ") : "◯ ") : "";
         const text = item.disabled ? palette.gray(`${item.label} (disabled)`) : active ? palette.cyan(item.label) : item.label;
-        lines.push(`${active ? palette.cyan("❯") : " "} ${box}${text}${item.hint ? ` ${palette.gray(item.hint)}` : ""}`);
+        lines.push(`${active ? palette.cyan("❯") : " "} ${mark}${text}${item.hint ? ` ${palette.gray(item.hint)}` : ""}`);
       }
       if (error) lines.push(palette.red(`✖ ${error}`));
-      output.write(lines.map((l) => `\u001b[2K${l}`).join("\n") + "\n");
-      if (drawn > lines.length) output.write(`\u001b[0J`);
+      // Going back up assumes one row per line, so nothing may wrap.
+      const text = lines.map((line) => `\u001b[2K${_oneRow(line, output)}`).join("\n");
+      output.write(`${drawn ? _up(drawn) : ""}${text}\n${drawn > lines.length ? CLEAR_BELOW : ""}`);
       drawn = lines.length;
     };
     const move = (/** @type {number} */ step) => {
-      let next = cursor;
-      for (let tries = 0; tries < items.length; tries++) {
-        next = (next + step + items.length) % items.length;
-        if (!items[next].disabled) break;
-      }
-      cursor = next;
+      const at = usable.indexOf(cursor);
+      cursor = usable[(at + step + usable.length) % usable.length];
+    };
+    const jump = (/** @type {number} */ target) => {
+      // the closest choice that can be picked, looking towards the target first
+      const clamped = Math.max(0, Math.min(items.length - 1, target));
+      cursor = usable.reduce((best, i) => (Math.abs(i - clamped) < Math.abs(best - clamped) ? i : best), cursor);
+    };
+    const cleanup = () => {
+      input.off("keypress", onKey);
+      input.setRawMode(false);
+      input.pause();
+      output.write(SHOW_CURSOR);
     };
-    const onKey = (/** @type {string} */ _str, /** @type {{ name?: string, ctrl?: boolean }} */ key) => {
+    const onKey = (/** @type {string} */ _str, /** @type {{ name?: string, ctrl?: boolean }} */ key = {}) => {
       error = "";
-      if (key.ctrl && key.name === "c") {
+      if ((key.ctrl && (key.name === "c" || key.name === "d")) || key.name === "escape") {
         cleanup();
-        reject(new Error("Cancelled"));
+        reject(new AbortError("Cancelled"));
         return;
       }
       if (key.name === "up" || key.name === "k") move(-1);
       else if (key.name === "down" || key.name === "j") move(1);
-      else if (key.name === "space" && multiple && !items[cursor].disabled) {
+      else if (key.name === "home") jump(0);
+      else if (key.name === "end") jump(items.length - 1);
+      else if (key.name === "pageup") jump(cursor - pageSize);
+      else if (key.name === "pagedown") jump(cursor + pageSize);
+      else if (key.name === "space" && multiple) {
         if (selected.has(cursor)) selected.delete(cursor);
         else selected.add(cursor);
       } else if (key.name === "a" && multiple) {
-        const all = items.every((it, i) => it.disabled || selected.has(i));
-        items.forEach((it, i) => (it.disabled ? null : all ? selected.delete(i) : selected.add(i)));
-      } else if (key.name === "return") {
+        const all = usable.every((i) => selected.has(i));
+        for (const i of usable) {
+          if (all) selected.delete(i);
+          else selected.add(i);
+        }
+      } else if (key.name === "return" || key.name === "enter") {
         if (multiple && selected.size < (options.min ?? 0)) {
           error = `Select at least ${options.min}`;
         } else {
+          const picked = multiple ? [...selected].sort((a, b) => a - b) : [cursor];
+          // Fold the list into one line that says what was chosen.
+          output.write(`${_up(drawn)}${CLEAR_BELOW}${_oneRow(`${palette.green("✔")} ${question} ${palette.cyan(picked.map((i) => items[i].label).join(", "))}`, output)}\n`);
           cleanup();
-          resolve(multiple ? [...selected].sort((a, b) => a - b) : [cursor]);
+          resolve(picked);
           return;
         }
       }
       draw();
     };
-    const cleanup = () => {
-      input.off("keypress", onKey);
-      input.setRawMode(false);
-      input.pause();
-      output.write(SHOW_CURSOR);
-    };
     _releaseReader(input);
-    readline.emitKeypressEvents(input);
+    require("node:readline").emitKeypressEvents(input);
     input.setRawMode(true);
     input.resume();
     _restoreCursorOnExit(output);
@@ -837,7 +1031,7 @@ const _interactiveList = (question, items, options, multiple) =>
  */
 async function select(question, choices, options = {}) {
   const items = _normalizeChoices(choices);
-  if (!items.length) throw new RangeError("select() needs at least one choice");
+  if (!items.some((item) => !item.disabled)) throw new RangeError("select() needs at least one choice that can be picked");
   const input = options.input ?? process.stdin;
   if (input.isTTY && typeof input.setRawMode === "function") {
     const [index] = await _interactiveList(question, items, options, false);
@@ -869,15 +1063,15 @@ async function select(question, choices, options = {}) {
 async function multiselect(question, choices, options = {}) {
   const items = _normalizeChoices(choices);
   const input = options.input ?? process.stdin;
-  if (items.length && input.isTTY && typeof input.setRawMode === "function") {
+  if (items.some((item) => !item.disabled) && input.isTTY && typeof input.setRawMode === "function") {
     const indexes = await _interactiveList(question, items, options, true);
     return indexes.map((i) => items[i].value);
   }
   const output = options.output ?? process.stdout;
-  output.write(`? ${question}\n${items.map((it, i) => `  ${i + 1}. ${it.label}`).join("\n")}\n`);
+  output.write(`? ${question}\n${items.map((it, i) => `  ${i + 1}. ${it.label}${it.disabled ? " (disabled)" : ""}`).join("\n")}\n`);
   for (;;) {
     const answer = (await _ask("Choose (comma-separated numbers): ", input, output)).trim();
-    const indexes = answer === "" ? [] : answer.split(/[\s,]+/).map((n) => Number(n) - 1);
+    const indexes = answer === "" ? [] : answer.split(/[\s,]+/).filter(Boolean).map((n) => Number(n) - 1);
     if (indexes.every((i) => Number.isInteger(i) && items[i] && !items[i].disabled) && indexes.length >= (options.min ?? 0)) {
       return [...new Set(indexes)].sort((a, b) => a - b).map((i) => items[i].value);
     }
@@ -885,58 +1079,98 @@ async function multiselect(question, choices, options = {}) {
   }
 }
 
+const _TRUE = ["1", "true", "yes", "on", "y"];
+const _FALSE = ["0", "false", "no", "off", "n", ""];
+
+/**
+ * @param {string} word
+ * @param {string[]} known
+ * @param {string} [prefix]
+ */
+const _suggest = (word, known, prefix = "") => {
+  const guess = require("./Str.js").closest(word, known);
+  return guess ? `. Did you mean ${prefix}${guess}?` : "";
+};
+
 /**
  * Parses command-line arguments from a schema, and types the result:
  * `flags.port` is a `number`. Handles short aliases, defaults, required
- * flags, allowed values, repeated flags and `--no-flag`, and generates
- * `--help`. A typo gets a "Did you mean...?" suggestion.
+ * flags, allowed values, repeated flags, `--no-flag`, environment variables
+ * as a fallback and subcommands, and generates `--help`. A typo gets a
+ * "Did you mean...?" suggestion.
  *
  * @example
  * // node server.js --port 8080 -v --tag api --tag web public/
  * const { flags, positionals } = cli.args({
- *   port: { type: "number", short: "p", default: 3000, description: "Port to listen on" },
+ *   port: { type: "number", short: "p", default: 3000, env: "PORT", description: "Port to listen on" },
  *   verbose: { type: "boolean", short: "v" },
  *   tag: { type: "string", multiple: true },
  *   env: { type: "string", choices: ["dev", "prod"], default: "dev" },
  * }, { description: "Start the web server", version: "1.0.0" });
  * // flags: { port: 8080, verbose: true, tag: ["api", "web"], env: "dev" }
  *
+ * // node tool.js build --watch
+ * const { command, flags: buildFlags } = cli.args({ watch: { type: "boolean" } }, {
+ *   commands: { build: "Build the project", serve: "Start the dev server" },
+ * });
+ * // command: "build"
+ *
  * @template {Record<string, FlagSpec>} S
  * @param {S} schema
  * @param {ArgsOptions} [options]
  * @returns {ParsedArgs<S>}
- * @throws {TypeError} For unknown flags, bad numbers, missing required flags or values not in `choices`. The message is ready to show.
+ * @throws {TypeError} For unknown flags or commands, bad numbers, missing required flags or values not in `choices`. The message is ready to show.
  */
 function args(schema, options = {}) {
   const argv = options.argv ?? process.argv.slice(2);
   const name = options.name ?? require("node:path").basename(process.argv[1] ?? "cli", ".js");
+  const env = options.env ?? process.env;
+  const commands = options.commands ? Object.keys(options.commands) : [];
 
   const help = () => {
     const lines = [];
     if (options.description) lines.push(options.description, "");
-    lines.push(`Usage: ${name} ${options.usage ?? "[options]"}`, "", "Options:");
+    lines.push(`Usage: ${name} ${options.usage ?? (commands.length ? "<command> [options]" : "[options]")}`);
+    /** @param {Array<[string, string]>} rows */
+    const list = (rows) => {
+      const width = Math.max(...rows.map(([left]) => left.length));
+      for (const [left, right] of rows) lines.push(`  ${left.padEnd(width)}  ${right}`.trimEnd());
+    };
+    if (options.commands && commands.length) {
+      lines.push("", "Commands:");
+      list(Object.entries(options.commands));
+    }
+    lines.push("", "Options:");
+    /** @type {Array<[string, string]>} */
     const rows = Object.entries(schema).map(([key, spec]) => {
       const flag = `${spec.short ? `-${spec.short}, ` : "    "}--${key}${spec.type === "boolean" ? "" : ` <${spec.type}>`}`;
       const details = [
         spec.description ?? "",
         spec.choices ? `(${spec.choices.join(" | ")})` : "",
         spec.default !== undefined ? `[default: ${JSON.stringify(spec.default)}]` : "",
+        spec.env ? `[env: ${spec.env}]` : "",
         spec.required ? "[required]" : "",
       ].filter(Boolean).join(" ");
       return [flag, details];
     });
     if (options.help !== false) rows.push(["-h, --help", "Show this help"]);
     if (options.version) rows.push(["    --version", "Show the version"]);
-    const width = Math.max(...rows.map(([f]) => f.length));
-    for (const [flag, details] of rows) lines.push(`  ${flag.padEnd(width)}  ${details}`.trimEnd());
+    list(rows);
+    if (options.examples?.length) {
+      lines.push("", "Examples:");
+      for (const example of options.examples) lines.push(`  ${example}`);
+    }
     return lines.join("\n");
   };
 
-  if (options.help !== false && (argv.includes("--help") || argv.includes("-h")) && !("help" in schema)) {
+  // Everything after "--" belongs to the program, even if it looks like a flag.
+  const end = argv.indexOf("--");
+  const own = end === -1 ? argv : argv.slice(0, end);
+  if (options.help !== false && (own.includes("--help") || own.includes("-h")) && !Object.hasOwn(schema, "help")) {
     process.stdout.write(`${help()}\n`);
     process.exit(0);
   }
-  if (options.version && argv.includes("--version") && !("version" in schema)) {
+  if (options.version && own.includes("--version") && !Object.hasOwn(schema, "version")) {
     process.stdout.write(`${options.version}\n`);
     process.exit(0);
   }
@@ -955,35 +1189,56 @@ function args(schema, options = {}) {
   } catch (error) {
     const message = /** @type {Error} */ (error).message;
     const unknown = /Unknown option '(-{1,2})([^']+)'/.exec(message);
-    if (unknown) {
-      const { closest } = require("./Str.js");
-      const guess = closest(unknown[2], Object.keys(schema));
-      throw new TypeError(`Unknown option ${unknown[1]}${unknown[2]}${guess ? `. Did you mean --${guess}?` : ""}`);
-    }
-    throw new TypeError(message);
+    if (unknown) throw new TypeError(`Unknown option ${unknown[1]}${unknown[2]}${_suggest(unknown[2].replace(/^no-/, ""), Object.keys(schema), "--")}`);
+    const missing = /Option '(?:-\w, )?--([^ ']+) <value>' argument missing/.exec(message);
+    throw new TypeError(missing ? `Option --${missing[1]} needs a value` : message.split("\n")[0]);
   }
 
   /** @type {Record<string, any>} */
   const flags = {};
   for (const [key, spec] of Object.entries(schema)) {
-    const raw = /** @type {any} */ (parsed.values)[key];
+    const fromEnv = spec.env !== undefined ? env[spec.env] : undefined;
+    const source = /** @type {any} */ (parsed.values)[key] !== undefined ? `Option --${key}` : `Environment variable ${spec.env}`;
+    let raw = /** @type {any} */ (parsed.values)[key];
+    if (raw === undefined && fromEnv !== undefined) {
+      // In a variable, a list is written with commas.
+      raw = spec.multiple ? fromEnv.split(",").map((part) => part.trim()).filter(Boolean) : fromEnv;
+    }
     if (raw === undefined) {
-      if (spec.required) throw new TypeError(`Missing required option --${key}`);
+      if (spec.required) throw new TypeError(`Missing required option --${key}${spec.env ? ` (or ${spec.env} in the environment)` : ""}`);
       flags[key] = spec.default !== undefined ? spec.default : spec.type === "boolean" ? false : spec.multiple ? [] : undefined;
       continue;
     }
     const convert = (/** @type {any} */ value) => {
+      /** @type {any} */
+      let result = value;
       if (spec.type === "number") {
-        const n = Number(value);
-        if (value === "" || !Number.isFinite(n)) throw new TypeError(`Option --${key} expects a number, got "${value}"`);
-        return n;
+        result = Number(value);
+        if (String(value).trim() === "" || !Number.isFinite(result)) throw new TypeError(`${source} expects a number, got "${value}"`);
+      } else if (spec.type === "boolean" && typeof value === "string") {
+        const text = value.trim().toLowerCase();
+        if (!_TRUE.includes(text) && !_FALSE.includes(text)) throw new TypeError(`${source} expects true or false, got "${value}"`);
+        result = _TRUE.includes(text);
       }
-      if (spec.choices && !spec.choices.includes(value)) throw new TypeError(`Option --${key} must be one of: ${spec.choices.join(", ")} (got "${value}")`);
-      return value;
+      if (spec.choices && !(/** @type {readonly unknown[]} */ (spec.choices)).includes(result)) {
+        throw new TypeError(`${source} must be one of: ${spec.choices.join(", ")} (got "${value}")`);
+      }
+      return result;
     };
     flags[key] = Array.isArray(raw) ? raw.map(convert) : convert(raw);
   }
-  return { flags: /** @type {ParsedFlags<S>} */ (flags), positionals: parsed.positionals, help };
+
+  const positionals = parsed.positionals;
+  /** @type {string | undefined} */
+  let command;
+  if (commands.length && positionals.length) {
+    command = positionals[0];
+    if (!commands.includes(command)) {
+      throw new TypeError(`Unknown command "${command}"${_suggest(command, commands) || `. Available: ${commands.join(", ")}`}`);
+    }
+    positionals.shift();
+  }
+  return { flags: /** @type {ParsedFlags<S>} */ (flags), positionals, command, help };
 }
 
 /**
@@ -1005,7 +1260,9 @@ function isInteractive() {
  * @returns {{ columns: number, rows: number }}
  */
 function size() {
-  return { columns: process.stdout.columns || 80, rows: process.stdout.rows || 24 };
+  const columns = process.stdout.columns || process.stderr.columns || Number(process.env.COLUMNS) || 80;
+  const rows = process.stdout.rows || process.stderr.rows || Number(process.env.LINES) || 24;
+  return { columns, rows };
 }
 
 /**
@@ -1020,7 +1277,9 @@ function clear() {
 module.exports = {
   table,
   box,
+  tree,
   spinner,
+  spin,
   progress,
   prompt,
   password,