clap-ts 0.3.0 → 0.4.0

package/src/index.ts

@@ -0,0 +1,58 @@
+/**
+ * clap-ts - A type-safe CLI argument parser for TypeScript, inspired by Rust's clap.
+ *
+ * Re-exports all public API.
+ */
+
+// Types
+export type {
+  ArgType,
+  ArgAction,
+  NumArgs,
+  ValueParserFn,
+  PossibleValue,
+  ValueHint,
+  ColorChoice,
+  ValueSource,
+  Shell,
+  OutputSink,
+  MissingArg,
+  ArgDef,
+  ArgsDef,
+  StyleFn,
+  StylesDef,
+  CommandMeta,
+  ArgGroup,
+  ParsedArgs,
+  CommandContext,
+  CommandDef,
+  RunOptions,
+  ParseResult,
+  InferArgValue,
+  InferArgOptional,
+} from './types.js';
+
+// Parser
+export {
+  parseArgs,
+  getRawArgs,
+  collectGlobalArgs,
+  mergeGlobalArgs,
+  subCommandsOf,
+  hasSubCommands,
+  possibleValues,
+  matchesPossibleValue,
+  CliParseError,
+} from './parser.js';
+
+// Validation
+export { validate } from './validation.js';
+
+// Help renderer
+export { renderHelp, renderUsage, showHelp, showVersion, showError } from './help.js';
+
+// Runner (main API)
+export { defineCommand, defineArgs, defineArg, runCommand, runMain } from './runner.js';
+
+// Generators live behind subpaths so a running CLI never loads them:
+//   clap-ts/completions, clap-ts/man, clap-ts/markdown

package/src/install.ts

@@ -0,0 +1,226 @@
+/**
+ * Put generated completions and man pages where the system will find them.
+ *
+ * ```ts
+ * import { withInstallers } from 'clap-ts/install';
+ *
+ * runMain(withInstallers(main));
+ * // my-tool completions install zsh
+ * // my-tool man install
+ * ```
+ *
+ * Everything respects `XDG_DATA_HOME`, and nothing is written until the target
+ * directory is created, so a dry run can report the path without touching disk.
+ */
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import type { CommandDef, Shell } from './types.js';
+import { generateCompletions } from './completions.js';
+import { generateManPages } from './man.js';
+
+const XDG_DATA = process.env['XDG_DATA_HOME'] ?? join(homedir(), '.local', 'share');
+const XDG_CONFIG = process.env['XDG_CONFIG_HOME'] ?? join(homedir(), '.config');
+
+/** Where a shell looks for user completions, and what the file must be called. */
+export interface CompletionTarget {
+  readonly dir: string;
+  readonly file: string;
+  /** A line the user must add themselves, when sourcing is not automatic. */
+  readonly manualStep?: string;
+}
+
+/**
+ * The per-user completion path for a shell.
+ *
+ * bash, zsh and fish load these directories on their own. powershell, elvish
+ * and nushell have no drop-in directory, so those report a line to add to the
+ * profile instead.
+ */
+export function completionTarget(shell: Shell, binaryName: string): CompletionTarget {
+  switch (shell) {
+    case 'bash':
+      return { dir: join(XDG_DATA, 'bash-completion', 'completions'), file: binaryName };
+    case 'zsh':
+      return {
+        dir: join(XDG_DATA, 'zsh', 'site-functions'),
+        file: `_${binaryName}`,
+        manualStep: `add ${join(XDG_DATA, 'zsh', 'site-functions')} to $fpath before compinit`,
+      };
+    case 'fish':
+      return { dir: join(XDG_CONFIG, 'fish', 'completions'), file: `${binaryName}.fish` };
+    case 'powershell':
+      return {
+        dir: join(XDG_CONFIG, 'powershell', 'completions'),
+        file: `${binaryName}.ps1`,
+        manualStep: `add \`. ${join(XDG_CONFIG, 'powershell', 'completions', `${binaryName}.ps1`)}\` to $PROFILE`,
+      };
+    case 'elvish':
+      return {
+        dir: join(XDG_CONFIG, 'elvish', 'lib'),
+        file: `${binaryName}.elv`,
+        manualStep: `add \`use ${binaryName}\` to ~/.config/elvish/rc.elv`,
+      };
+    case 'nushell':
+      return {
+        dir: join(XDG_CONFIG, 'nushell', 'completions'),
+        file: `${binaryName}.nu`,
+        manualStep: `add \`source ${join(XDG_CONFIG, 'nushell', 'completions', `${binaryName}.nu`)}\` to your config`,
+      };
+  }
+}
+
+/** What an install did, or would have done. */
+export interface InstallResult {
+  readonly paths: readonly string[];
+  readonly manualStep?: string;
+  readonly dryRun: boolean;
+}
+
+export interface InstallOptions {
+  /** Report the paths without writing anything. */
+  readonly dryRun?: boolean;
+  /** Write here instead of the per-user location. */
+  readonly dir?: string;
+  /** Binary name; defaults to the command's binName or name. */
+  readonly binaryName?: string;
+}
+
+function write(dir: string, file: string, contents: string, dryRun: boolean): string {
+  const path = join(dir, file);
+  if (!dryRun) {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, contents);
+  }
+  return path;
+}
+
+/** Write the completion script for one shell to its per-user location. */
+export function installCompletions(
+  command: CommandDef,
+  shell: Shell,
+  opts?: InstallOptions,
+): InstallResult {
+  const binaryName = opts?.binaryName ?? command.meta.binName ?? command.meta.name;
+  const target = completionTarget(shell, binaryName);
+  const dir = opts?.dir ?? target.dir;
+  const dryRun = opts?.dryRun === true;
+
+  const path = write(dir, target.file, generateCompletions(command, shell, binaryName), dryRun);
+  return {
+    paths: [path],
+    ...(target.manualStep === undefined ? {} : { manualStep: target.manualStep }),
+    dryRun,
+  };
+}
+
+/** Write a man page per command into the per-user man directory. */
+export function installManPages(command: CommandDef, opts?: InstallOptions): InstallResult {
+  const binaryName = opts?.binaryName ?? command.meta.binName ?? command.meta.name;
+  const dryRun = opts?.dryRun === true;
+  const pages = generateManPages(command, { name: binaryName });
+  const dir = opts?.dir ?? join(XDG_DATA, 'man', 'man1');
+
+  const paths: string[] = [];
+  for (const [file, roff] of pages) {
+    paths.push(write(dir, file, roff, dryRun));
+  }
+  return {
+    paths,
+    manualStep: `add ${join(XDG_DATA, 'man')} to $MANPATH if your system does not read it already`,
+    dryRun,
+  };
+}
+
+const SHELLS: readonly Shell[] = ['bash', 'zsh', 'fish', 'powershell', 'elvish', 'nushell'];
+
+/**
+ * Add `completions` and `man` subcommands that both print and install.
+ *
+ * `tool completions bash` writes the script to stdout as before;
+ * `tool completions install bash` puts it where the shell will find it.
+ */
+export function withInstallers(rootCommand: CommandDef<any>): CommandDef<any> {
+  const completions: CommandDef = {
+    meta: {
+      name: 'completions',
+      description: 'Print or install a shell completion script',
+      aliases: ['completion'],
+      // `completions install zsh` names the shell on the subcommand, so the
+      // shell positional here is only required when printing.
+      subcommandNegatesReqs: true,
+    },
+    args: {
+      shell: {
+        type: 'positional',
+        valueName: 'SHELL',
+        required: true,
+        valueParser: [...SHELLS],
+        description: `Target shell: ${SHELLS.join(', ')}`,
+      },
+    },
+    subCommands: {
+      install: {
+        meta: { name: 'install', description: 'Write the script where the shell will find it' },
+        args: {
+          shell: {
+            type: 'positional',
+            valueName: 'SHELL',
+            required: true,
+            valueParser: [...SHELLS],
+            description: 'Shell to install for',
+          },
+          dryRun: { type: 'boolean', description: 'Report the path without writing' },
+        },
+        run({ args, stdout }) {
+          const result = installCompletions(rootCommand, args['shell'] as Shell, {
+            dryRun: args['dryRun'] === true,
+          });
+          const verb = result.dryRun ? 'would write' : 'wrote';
+          stdout.write(`${verb} ${result.paths[0]!}\n`);
+          if (result.manualStep !== undefined) {
+            stdout.write(`note: ${result.manualStep}\n`);
+          }
+        },
+      },
+    },
+    run({ args, stdout }) {
+      stdout.write(generateCompletions(rootCommand, args['shell'] as Shell));
+    },
+  };
+
+  const man: CommandDef = {
+    meta: { name: 'man', description: 'Print or install man pages' },
+    args: {
+      dryRun: { type: 'boolean', description: 'Report the paths without writing' },
+    },
+    subCommands: {
+      install: {
+        meta: { name: 'install', description: 'Write man pages where man will find them' },
+        args: { dryRun: { type: 'boolean', description: 'Report the paths without writing' } },
+        run({ args, stdout }) {
+          const result = installManPages(rootCommand, { dryRun: args['dryRun'] === true });
+          const verb = result.dryRun ? 'would write' : 'wrote';
+          for (const path of result.paths) {
+            stdout.write(`${verb} ${path}\n`);
+          }
+          if (result.manualStep !== undefined) {
+            stdout.write(`note: ${result.manualStep}\n`);
+          }
+        },
+      },
+    },
+    run({ stdout }) {
+      for (const roff of generateManPages(rootCommand).values()) {
+        stdout.write(roff);
+      }
+    },
+  };
+
+  return {
+    ...rootCommand,
+    subCommands: { ...rootCommand.subCommands, completions, man },
+    lazySubCommands: rootCommand.lazySubCommands,
+  };
+}

package/src/log.ts

@@ -0,0 +1,225 @@
+/**
+ * A levelled logger wired to the verbosity arguments a CLI already declares.
+ *
+ * ```ts
+ * import { loggerFrom } from 'clap-ts/log';
+ *
+ * const main = defineCommand({
+ *   meta: { name: 'tool' },
+ *   args: {
+ *     verbose: { type: 'boolean', short: 'v', action: 'count', description: 'More output' },
+ *     quiet: { type: 'boolean', short: 'q', description: 'Errors only' },
+ *   },
+ *   run(ctx) {
+ *     const log = loggerFrom(ctx);
+ *     log.info('starting');   // shown by default
+ *     log.debug('details');   // shown with -v
+ *   },
+ * });
+ * ```
+ *
+ * Everything goes to stderr, leaving stdout for the command's actual output so
+ * a pipeline is not polluted by progress chatter.
+ */
+
+import { styleText } from 'node:util';
+import type { OutputSink } from './types.js';
+
+/** Ordered from quietest to loudest. */
+export const LEVELS = ['silent', 'error', 'warn', 'info', 'debug', 'trace'] as const;
+
+export type LogLevel = (typeof LEVELS)[number];
+
+const RANK: Record<LogLevel, number> = {
+  silent: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4,
+  trace: 5,
+};
+
+export interface Logger {
+  readonly level: LogLevel;
+  /** Whether a message at this level would be shown. */
+  enabled(level: LogLevel): boolean;
+  error(message: string, ...rest: unknown[]): void;
+  warn(message: string, ...rest: unknown[]): void;
+  info(message: string, ...rest: unknown[]): void;
+  debug(message: string, ...rest: unknown[]): void;
+  trace(message: string, ...rest: unknown[]): void;
+  /** A logger writing the same place at a different level. */
+  withLevel(level: LogLevel): Logger;
+}
+
+export interface LoggerOptions {
+  /** Level to log at (default 'info'). */
+  readonly level?: LogLevel;
+  /** Where messages go (default process.stderr). */
+  readonly sink?: OutputSink;
+  /** Prefix each line, for instance with the tool name. */
+  readonly prefix?: string;
+  /** Force colour on or off; defaults to whatever the stream supports. */
+  readonly color?: boolean;
+}
+
+type Paint = (text: string) => string;
+
+const PLAIN: Paint = (text) => text;
+
+function labels(color: boolean): Record<Exclude<LogLevel, 'silent'>, string> {
+  const paint = (codes: Parameters<typeof styleText>[0], text: string): string =>
+    color ? styleText(codes, text, { validateStream: false }) : text;
+  return {
+    error: paint('red', 'error'),
+    warn: paint('yellow', 'warning'),
+    info: paint('cyan', 'info'),
+    debug: paint('magenta', 'debug'),
+    trace: paint('gray', 'trace'),
+  };
+}
+
+/**
+ * Render one extra value.
+ *
+ * An Error is the most common thing to log and `JSON.stringify` turns it into
+ * `{}`, losing the message. A cyclic object throws outright, which would take
+ * the CLI down for the sake of a log line, so serialisation falls back to
+ * String rather than propagating.
+ */
+function renderValue(value: unknown): string {
+  if (typeof value === 'string') {
+    return value;
+  }
+  if (value instanceof Error) {
+    return value.stack ?? `${value.name}: ${value.message}`;
+  }
+  if (value === undefined) {
+    return 'undefined';
+  }
+  if (typeof value === 'bigint' || typeof value === 'symbol' || typeof value === 'function') {
+    return String(value);
+  }
+  try {
+    return JSON.stringify(value, safeReplacer()) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+/** A replacer that names a cycle instead of throwing on it. */
+function safeReplacer(): (key: string, value: unknown) => unknown {
+  const seen = new WeakSet<object>();
+  return (_key, value) => {
+    if (typeof value !== 'object' || value === null) {
+      return value;
+    }
+    if (seen.has(value)) {
+      return '[Circular]';
+    }
+    seen.add(value);
+    return value;
+  };
+}
+
+function format(rest: readonly unknown[]): string {
+  if (rest.length === 0) {
+    return '';
+  }
+  return ` ${rest.map(renderValue).join(' ')}`;
+}
+
+/** Build a logger writing to a sink. */
+export function createLogger(opts?: LoggerOptions): Logger {
+  const level = opts?.level ?? 'info';
+  const sink = opts?.sink ?? process.stderr;
+  const color = opts?.color ?? styleText('red', 'x') !== 'x';
+  const tag = labels(color);
+  const prefix = opts?.prefix === undefined ? '' : `${opts.prefix} `;
+  const threshold = RANK[level];
+
+  const write = (at: Exclude<LogLevel, 'silent'>, message: string, rest: unknown[]): void => {
+    if (RANK[at] > threshold) {
+      return;
+    }
+    sink.write(`${prefix}${tag[at]}: ${message}${format(rest)}\n`);
+  };
+
+  const logger: Logger = {
+    level,
+    enabled: (at) => RANK[at] <= threshold,
+    error: (message, ...rest) => {
+      write('error', message, rest);
+    },
+    warn: (message, ...rest) => {
+      write('warn', message, rest);
+    },
+    info: (message, ...rest) => {
+      write('info', message, rest);
+    },
+    debug: (message, ...rest) => {
+      write('debug', message, rest);
+    },
+    trace: (message, ...rest) => {
+      write('trace', message, rest);
+    },
+    withLevel: (next) => createLogger({ ...opts, level: next }),
+  };
+  return logger;
+}
+
+export interface LevelFromArgsOptions {
+  /** Name of the count-action verbosity arg (default 'verbose'). */
+  readonly verboseKey?: string;
+  /** Name of the quiet flag (default 'quiet'). */
+  readonly quietKey?: string;
+  /** Name of an explicit level arg, which overrides the other two. */
+  readonly levelKey?: string;
+  /** Level with no flags given (default 'info'). */
+  readonly base?: LogLevel;
+}
+
+/**
+ * Work out a level from parsed arguments.
+ *
+ * An explicit level wins. Otherwise `--quiet` drops to errors only, and each
+ * `-v` climbs one step, so `-vv` reaches trace from the default of info.
+ */
+export function levelFromArgs(
+  args: Record<string, unknown>,
+  opts?: LevelFromArgsOptions,
+): LogLevel {
+  const explicit = args[opts?.levelKey ?? 'logLevel'];
+  if (typeof explicit === 'string' && (LEVELS as readonly string[]).includes(explicit)) {
+    return explicit as LogLevel;
+  }
+
+  if (args[opts?.quietKey ?? 'quiet'] === true) {
+    return 'error';
+  }
+
+  const base = RANK[opts?.base ?? 'info'];
+  const verbose = args[opts?.verboseKey ?? 'verbose'];
+  const steps = typeof verbose === 'number' ? verbose : verbose === true ? 1 : 0;
+  return LEVELS[Math.min(base + steps, LEVELS.length - 1)]!;
+}
+
+/**
+ * A logger for a command context, taking its level from the parsed arguments
+ * and writing to the context's stderr so the testing helpers capture it.
+ */
+export function loggerFrom(
+  // Structural rather than CommandContext<T>, so any command's context fits
+  // without the generic having to be named at the call site.
+  ctx: { readonly args: unknown; readonly stderr: OutputSink },
+  opts?: LoggerOptions & LevelFromArgsOptions,
+): Logger {
+  return createLogger({
+    ...opts,
+    sink: opts?.sink ?? ctx.stderr,
+    level: opts?.level ?? levelFromArgs(ctx.args as Record<string, unknown>, opts),
+  });
+}
+
+/** A logger that discards everything, for tests and dry runs. */
+export const silentLogger: Logger = createLogger({ level: 'silent', sink: { write: PLAIN } });