clap-ts 0.3.0 → 0.4.0

package/src/plugins.ts

@@ -0,0 +1,193 @@
+/**
+ * Subcommands discovered from installed packages, the way git, eslint and kubectl
+ * grow: drop `my-tool-plugin-deploy` next to the CLI and `my-tool deploy` works.
+ *
+ * ```ts
+ * import { pluginSubCommands } from 'clap-ts/plugins';
+ *
+ * const main = defineCommand({
+ *   meta: { name: 'my-tool' },
+ *   lazySubCommands: pluginSubCommands('my-tool'),
+ * });
+ * ```
+ *
+ * Pairs with `lazySubCommands`: discovery is a directory scan and each plugin is
+ * a module import, so neither happens until a token could be a subcommand.
+ */
+
+import { readdirSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createRequire } from 'node:module';
+import type { CommandDef } from './types.js';
+
+/** A plugin package found on disk, before it has been loaded. */
+export interface DiscoveredPlugin {
+  /** Subcommand name, the part after the prefix. */
+  readonly name: string;
+  /** Full package name. */
+  readonly packageName: string;
+  /** Directory the package lives in. */
+  readonly dir: string;
+}
+
+export interface PluginOptions {
+  /**
+   * Package name prefix. Defaults to `<tool>-plugin-`, so `my-tool-plugin-deploy`
+   * becomes the `deploy` subcommand.
+   */
+  readonly prefix?: string;
+  /** Directories to scan. Defaults to every `node_modules` up from `cwd`. */
+  readonly searchPaths?: readonly string[];
+  /** Where to start the walk (default `process.cwd()`). */
+  readonly cwd?: string;
+  /** Load a package and return its command. Defaults to a dynamic import of the package. */
+  readonly load?: (plugin: DiscoveredPlugin) => CommandDef<any> | undefined;
+  /** Called when a plugin fails to load. Defaults to rethrowing. */
+  readonly onError?: (plugin: DiscoveredPlugin, error: unknown) => void;
+}
+
+/** Every `node_modules` directory from `cwd` up to the filesystem root. */
+export function nodeModulesPaths(cwd: string = process.cwd()): string[] {
+  const paths: string[] = [];
+  let dir = cwd;
+  for (;;) {
+    if (!dir.endsWith(`${'/'}node_modules`)) {
+      paths.push(join(dir, 'node_modules'));
+    }
+    const parent = join(dir, '..');
+    if (parent === dir) {
+      return paths;
+    }
+    dir = parent;
+  }
+}
+
+/**
+ * Find plugin packages without loading any of them.
+ *
+ * Scoped packages are handled: `@acme/my-tool-plugin-deploy` is found under its
+ * scope directory and reported as `deploy`. The nearest copy of a package wins,
+ * matching how resolution works.
+ */
+export function discoverPlugins(tool: string, opts?: PluginOptions): DiscoveredPlugin[] {
+  const prefix = opts?.prefix ?? `${tool}-plugin-`;
+  const roots = opts?.searchPaths ?? nodeModulesPaths(opts?.cwd);
+
+  const found = new Map<string, DiscoveredPlugin>();
+
+  const consider = (packageName: string, dir: string): void => {
+    const base = packageName.includes('/') ? packageName.slice(packageName.indexOf('/') + 1) : packageName;
+    if (!base.startsWith(prefix) || base.length === prefix.length) {
+      return;
+    }
+    const name = base.slice(prefix.length);
+    // The first root wins, so a local copy shadows one further up.
+    if (!found.has(name)) {
+      found.set(name, { name, packageName, dir });
+    }
+  };
+
+  for (const root of roots) {
+    let entries: string[];
+    try {
+      entries = readdirSync(root);
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (entry.startsWith('.')) {
+        continue;
+      }
+      if (entry.startsWith('@')) {
+        let scoped: string[];
+        try {
+          scoped = readdirSync(join(root, entry));
+        } catch {
+          continue;
+        }
+        for (const inner of scoped) {
+          consider(`${entry}/${inner}`, join(root, entry, inner));
+        }
+        continue;
+      }
+      consider(entry, join(root, entry));
+    }
+  }
+
+  return [...found.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Read a discovered package's own name and description, for help before it loads. */
+function packageMeta(plugin: DiscoveredPlugin): { description?: string } {
+  const pkgPath = join(plugin.dir, 'package.json');
+  if (!existsSync(pkgPath)) {
+    return {};
+  }
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { description?: string };
+    return pkg.description === undefined ? {} : { description: pkg.description };
+  } catch {
+    return {};
+  }
+}
+
+function defaultLoad(plugin: DiscoveredPlugin): CommandDef<any> | undefined {
+  const require = createRequire(join(plugin.dir, 'package.json'));
+  const loaded = require(plugin.packageName) as
+    | CommandDef<any>
+    | { default?: CommandDef<any>; command?: CommandDef<any> };
+
+  if ('meta' in loaded && loaded.meta !== undefined) {
+    return loaded as CommandDef<any>;
+  }
+  const mod = loaded as { default?: CommandDef<any>; command?: CommandDef<any> };
+  return mod.default ?? mod.command;
+}
+
+/**
+ * A thunk for `lazySubCommands` that discovers and loads plugin packages.
+ *
+ * Nothing is scanned or imported until the thunk runs, which the parser only
+ * does when a token could be a subcommand.
+ */
+export function pluginSubCommands(
+  tool: string,
+  opts?: PluginOptions,
+): () => Record<string, CommandDef<any>> {
+  return () => {
+    const load = opts?.load ?? defaultLoad;
+    const commands: Record<string, CommandDef<any>> = {};
+
+    for (const plugin of discoverPlugins(tool, opts)) {
+      let command: CommandDef<any> | undefined;
+      try {
+        command = load(plugin);
+      } catch (error) {
+        if (opts?.onError === undefined) {
+          throw new Error(
+            `plugin '${plugin.packageName}' failed to load: ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+          );
+        }
+        opts.onError(plugin, error);
+        continue;
+      }
+
+      if (command === undefined) {
+        continue;
+      }
+
+      // Fall back to the package description so help says something useful
+      // even when the plugin did not set one.
+      const meta = command.meta.description === undefined ? packageMeta(plugin) : {};
+      commands[plugin.name] = {
+        ...command,
+        meta: { ...command.meta, name: plugin.name, ...meta },
+      };
+    }
+
+    return commands;
+  };
+}

package/src/progress.ts

@@ -0,0 +1,295 @@
+/**
+ * Spinners and progress bars that know when nobody is watching.
+ *
+ * ```ts
+ * import { spinner, progressBar } from 'clap-ts/progress';
+ *
+ * const spin = spinner('Fetching');
+ * spin.start();
+ * await work();
+ * spin.succeed('Fetched 12 items');
+ * ```
+ *
+ * Both write to stderr and both go quiet when it is not a terminal, so piping a
+ * command's output never fills a log file with redraw escapes. `NO_COLOR` and
+ * `CI` are honoured the same way.
+ */
+
+import { styleText } from 'node:util';
+import type { OutputSink } from './types.js';
+import { displayWidth, truncate } from './output.js';
+
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const ASCII_FRAMES = ['-', '\\', '|', '/'];
+
+/** A stream that can also be interrogated about being a terminal. */
+interface MaybeTty extends OutputSink {
+  isTTY?: boolean;
+  columns?: number;
+}
+
+export interface ProgressOptions {
+  /** Where to draw (default process.stderr). */
+  readonly sink?: OutputSink;
+  /**
+   * Draw at all. Defaults to true only when the sink is a terminal and CI is
+   * unset, so redirected output stays clean.
+   */
+  readonly enabled?: boolean;
+  /** Use ASCII frames instead of braille. */
+  readonly ascii?: boolean;
+  /** Milliseconds between spinner frames (default 80). */
+  readonly interval?: number;
+  /** Force colour on or off. */
+  readonly color?: boolean;
+  /**
+   * Shortest gap between redraws, in milliseconds (default 16, about 60 a
+   * second). A loop that updates thousands of times a second would otherwise
+   * spend its time writing escape sequences nobody can read.
+   */
+  readonly throttle?: number;
+}
+
+const HIDE_CURSOR = '\x1b[?25l';
+const SHOW_CURSOR = '\x1b[?25h';
+const CLEAR_LINE = '\r\x1b[2K';
+
+/** Columns available to draw into. */
+function widthOf(sink: MaybeTty): number {
+  return typeof sink.columns === 'number' && sink.columns > 0 ? sink.columns : 80;
+}
+
+function resolveSink(opts?: ProgressOptions): MaybeTty {
+  return (opts?.sink ?? process.stderr) as MaybeTty;
+}
+
+function shouldDraw(sink: MaybeTty, opts?: ProgressOptions): boolean {
+  if (opts?.enabled !== undefined) {
+    return opts.enabled;
+  }
+  // A pipe, a file or a CI log gets no redraws.
+  return sink.isTTY === true && process.env['CI'] === undefined;
+}
+
+function paint(color: boolean, codes: Parameters<typeof styleText>[0], text: string): string {
+  return color ? styleText(codes, text, { validateStream: false }) : text;
+}
+
+export interface Spinner {
+  /** Begin animating. Safe to call twice. */
+  start(text?: string): Spinner;
+  /** Change the message without interrupting the animation. */
+  update(text: string): Spinner;
+  /** Stop and leave a green tick. */
+  succeed(text?: string): Spinner;
+  /** Stop and leave a red cross. */
+  fail(text?: string): Spinner;
+  /** Stop and leave a yellow warning mark. */
+  warn(text?: string): Spinner;
+  /** Stop and erase, leaving nothing behind. */
+  stop(): Spinner;
+  /** Whether this spinner draws anything at all. */
+  readonly enabled: boolean;
+}
+
+/**
+ * A spinner for work of unknown length.
+ *
+ * When drawing is off the terminating calls still print their message once, so
+ * a piped run reports what happened without any animation.
+ */
+export function spinner(initialText = '', opts?: ProgressOptions): Spinner {
+  const sink = resolveSink(opts);
+  const enabled = shouldDraw(sink, opts);
+  const frames = opts?.ascii === true ? ASCII_FRAMES : FRAMES;
+  const interval = opts?.interval ?? 80;
+  const color = opts?.color ?? styleText('red', 'x') !== 'x';
+
+  let text = initialText;
+  let frame = 0;
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let cursorHidden = false;
+
+  const restoreCursor = (): void => {
+    if (cursorHidden) {
+      sink.write(SHOW_CURSOR);
+      cursorHidden = false;
+    }
+  };
+
+  const clear = (): void => {
+    sink.write(CLEAR_LINE);
+  };
+
+  const draw = (): void => {
+    clear();
+    // Two columns for the frame and its space; anything longer wraps, and a
+    // wrapped line cannot be erased by a single carriage return.
+    const room = widthOf(sink) - 2;
+    sink.write(`${paint(color, 'cyan', frames[frame]!)} ${truncate(text, room)}`);
+    frame = (frame + 1) % frames.length;
+  };
+
+  const finish = (mark: string, codes: Parameters<typeof styleText>[0], done?: string): Spinner => {
+    if (timer !== undefined) {
+      clearInterval(timer);
+      timer = undefined;
+    }
+    const message = done ?? text;
+    if (enabled) {
+      clear();
+      restoreCursor();
+    }
+    if (message.length > 0) {
+      sink.write(`${paint(color, codes, mark)} ${message}\n`);
+    }
+    return api;
+  };
+
+  const api: Spinner = {
+    enabled,
+    start(next) {
+      if (next !== undefined) {
+        text = next;
+      }
+      if (!enabled || timer !== undefined) {
+        return api;
+      }
+      // A visible cursor flickers over the animating frame.
+      sink.write(HIDE_CURSOR);
+      cursorHidden = true;
+      draw();
+      timer = setInterval(draw, interval);
+      // Never hold the event loop open for a spinner.
+      timer.unref?.();
+      return api;
+    },
+    update(next) {
+      text = next;
+      if (enabled && timer !== undefined) {
+        draw();
+      }
+      return api;
+    },
+    succeed: (done) => finish('✔', 'green', done),
+    fail: (done) => finish('✖', 'red', done),
+    warn: (done) => finish('⚠', 'yellow', done),
+    stop() {
+      if (timer !== undefined) {
+        clearInterval(timer);
+        timer = undefined;
+      }
+      if (enabled) {
+        clear();
+        restoreCursor();
+      }
+      return api;
+    },
+  };
+
+  return api;
+}
+
+export interface ProgressBar {
+  /** Move to an absolute position. */
+  update(current: number, text?: string): ProgressBar;
+  /** Move forward by an amount (default 1). */
+  tick(by?: number, text?: string): ProgressBar;
+  /** Fill the bar and finish the line. */
+  finish(text?: string): ProgressBar;
+  /** Abandon the bar, erasing it. */
+  stop(): ProgressBar;
+  /** Render the current line without drawing it, for tests. */
+  render(): string;
+  readonly enabled: boolean;
+}
+
+export interface ProgressBarOptions extends ProgressOptions {
+  /** Total the bar counts up to. */
+  readonly total: number;
+  /** Bar width in characters (default: a third of the terminal, 20 to 40). */
+  readonly width?: number;
+  /** Label shown before the bar. */
+  readonly text?: string;
+}
+
+/**
+ * A determinate progress bar.
+ *
+ * `render` returns the line it would draw, which is what makes this testable
+ * without a terminal.
+ */
+export function progressBar(opts: ProgressBarOptions): ProgressBar {
+  const sink = resolveSink(opts);
+  const enabled = shouldDraw(sink, opts);
+  const color = opts.color ?? styleText('red', 'x') !== 'x';
+  const total = Math.max(1, opts.total);
+  const columns = widthOf(sink);
+  const width = opts.width ?? Math.min(40, Math.max(20, Math.floor(columns / 3)));
+  const throttle = opts.throttle ?? 16;
+
+  let current = 0;
+  let text = opts.text ?? '';
+  let lastDraw = 0;
+
+  const render = (): string => {
+    const ratio = Math.min(1, current / total);
+    const filled = Math.round(ratio * width);
+    const bar = '█'.repeat(filled) + '░'.repeat(width - filled);
+    const percent = `${String(Math.round(ratio * 100)).padStart(3)}%`;
+    const counts = `${String(current)}/${String(total)}`;
+    const line = `${bar} ${percent} ${counts}${text.length > 0 ? ` ${text}` : ''}`;
+
+    // Fit the terminal: a line that wraps cannot be erased by a carriage
+    // return, so the next redraw would stack instead of replacing.
+    const fitted = displayWidth(line) > columns ? truncate(line, columns) : line;
+    return color ? fitted.replace(bar, paint(color, 'cyan', bar)) : fitted;
+  };
+
+  const draw = (force: boolean): void => {
+    const now = Date.now();
+    // The final frame always lands; the ones in between can be skipped.
+    if (!force && throttle > 0 && now - lastDraw < throttle) {
+      return;
+    }
+    lastDraw = now;
+    sink.write(`${CLEAR_LINE}${render()}`);
+  };
+
+  const api: ProgressBar = {
+    enabled,
+    render,
+    update(next, nextText) {
+      current = Math.max(0, Math.min(total, next));
+      if (nextText !== undefined) {
+        text = nextText;
+      }
+      if (enabled) {
+        draw(false);
+      }
+      return api;
+    },
+    tick: (by = 1, nextText) => api.update(current + by, nextText),
+    finish(done) {
+      current = total;
+      if (done !== undefined) {
+        text = done;
+      }
+      if (enabled) {
+        draw(true);
+        sink.write('\n');
+      } else if (text.length > 0) {
+        sink.write(`${text}\n`);
+      }
+      return api;
+    },
+    stop() {
+      if (enabled) {
+        sink.write(CLEAR_LINE);
+      }
+      return api;
+    },
+  };
+
+  return api;
+}