@znight/cli 0.0.0-stage → 0.1.0

package/src/integrations/watch.ts

@@ -0,0 +1,243 @@
+/**
+ * File watching for `znight generate --watch` (`fs.watch`, recursive on macOS, Windows and Linux with
+ * Node.js >= 20 / Bun). It covers what the Vite plugin and the Bun preload watch: the `include`
+ * directories of the project and of its source libraries (recursively), the project root
+ * (`package.json`, `tsconfig.json`, lockfiles) and the directories of the files the last compile
+ * depends on (`watchFiles`: library manifests, compiled libraries...), refreshed after every compile.
+ * Which events matter is the compiler's call (`includeRoots()`, `isRelevantChange()`); this module
+ * only turns `fs.watch` events, which carry no kind and report a moved directory without its files,
+ * into compiler changes.
+ *
+ * Paths handed to the compiler are absolute, real (symbolic links resolved) and POSIX-style, like the
+ * paths of the compiler itself (`watchFiles`, `includeRoots()`).
+ */
+import type { ChangeKind, CompilerChanges } from './compiler.ts'
+
+import { existsSync, type FSWatcher, realpathSync, statSync, watch } from 'node:fs'
+import { join, posix, resolve } from 'node:path'
+
+/** A directory to watch. */
+export interface WatchTarget {
+  readonly path: string
+  readonly recursive: boolean
+}
+
+/** A running watcher. */
+export interface FileWatcher {
+  close(): void
+}
+
+/**
+ * Starts watching `targets`; `onChange` receives the absolute path of every changed file or
+ * directory (created, modified, deleted or renamed), except in ignored directories
+ * ({@link isIgnoredPath}).
+ */
+export type WatchFactory = (targets: readonly WatchTarget[], onChange: (file: string) => void) => FileWatcher
+
+const IGNORED_SEGMENTS = new Set(['node_modules', 'dist', 'coverage'])
+
+/** Native separators to forward slashes (the compiler's path style, also on Windows). */
+export function toPosixPath(path: string): string {
+  return path.includes('\\') ? path.replaceAll('\\', '/') : path
+}
+
+/**
+ * The absolute, POSIX-style real path of `path` (symbolic links resolved and the on-disk casing:
+ * `/var` → `/private/var` on macOS), also when its last segments do not exist (anymore): the real
+ * path of the deepest existing parent, then the rest. Makes watcher paths comparable with the
+ * compiler's.
+ */
+export function realPath(path: string): string {
+  const absolute = resolve(path)
+  try {
+    return toPosixPath(realpathSync.native(absolute))
+  } catch {
+    const parent = resolve(absolute, '..')
+    if (parent === absolute) return toPosixPath(absolute)
+    return `${realPath(parent).replace(/\/$/, '')}/${posix.basename(toPosixPath(absolute))}`
+  }
+}
+
+/**
+ * Whether a path relative to a watched directory is never relevant: inside `node_modules`, `dist`,
+ * `coverage` or a dot directory (`.git`, `.znight`...).
+ */
+export function isIgnoredPath(relativePath: string): boolean {
+  return relativePath.split(/[\\/]/).some(segment => IGNORED_SEGMENTS.has(segment) || segment.startsWith('.'))
+}
+
+/** `true` when `file` is `directory` or inside it (absolute POSIX paths). */
+export function isWithin(directory: string, file: string): boolean {
+  return file === directory || file.startsWith(directory.endsWith('/') ? directory : `${directory}/`)
+}
+
+/** Drops the directories nested in another one; sorted, de-duplicated. */
+function outermost(directories: Iterable<string>): string[] {
+  const sorted = [...new Set(directories)].sort()
+  return sorted.filter(directory => !sorted.some(other => other !== directory && isWithin(other, directory)))
+}
+
+/**
+ * Directories to watch: the include `roots` (`includeRoots()` of the compiler) recursively; the
+ * project `root` and the directories of `files` (the `watchFiles` of the last compile) that are
+ * outside them, non-recursively.
+ */
+export function watchTargets(root: string, roots: readonly string[], files: Iterable<string> = []): WatchTarget[] {
+  const recursive = outermost(roots.map(toPosixPath))
+  const covered = (directory: string): boolean => recursive.some(base => isWithin(base, directory))
+  const flat = new Set<string>()
+  const directories = [toPosixPath(resolve(root))]
+  for (const file of files) directories.push(posix.dirname(toPosixPath(resolve(file))))
+  for (const directory of directories) if (!covered(directory)) flat.add(directory)
+  return [
+    ...recursive.map(path => ({ path, recursive: true })),
+    ...[...flat].sort().map(path => ({ path, recursive: false })),
+  ]
+}
+
+type PathKind = 'file' | 'directory' | 'missing'
+
+function kindOf(path: string): PathKind {
+  try {
+    return statSync(path).isDirectory() ? 'directory' : 'file'
+  } catch {
+    return 'missing'
+  }
+}
+
+/** The known files inside `directory`. */
+function knownWithin(known: ReadonlySet<string>, directory: string): string[] {
+  const prefix = directory.endsWith('/') ? directory : `${directory}/`
+  return [...known].filter(file => file.startsWith(prefix))
+}
+
+/**
+ * The kind of an `fs.watch` event on `file` (absolute, real, POSIX-style), which `fs.watch` does not
+ * tell, from the disk and the files of the last compile (`known`): `removed` when it is gone,
+ * `changed` for a known file, `added` otherwise (a new file, a directory created or moved there).
+ */
+export function changeKind(file: string, known: ReadonlySet<string>): ChangeKind {
+  switch (kindOf(file)) {
+    case 'missing':
+      return 'removed'
+    case 'directory':
+      return 'added'
+    default:
+      return known.has(file) ? 'changed' : 'added'
+  }
+}
+
+/**
+ * Classifies relevant paths (`isRelevantChange()` of the compiler) for the incremental compiler,
+ * given the files of the last compile: a deleted path is removed with the known files it contained
+ * (a directory moved away), an existing directory is added (the compiler re-runs the scan) and the
+ * known files it contains are re-read (or removed when gone), an existing file is changed when
+ * known, added otherwise.
+ */
+export function classifyChanges(files: Iterable<string>, known: ReadonlySet<string>): CompilerChanges {
+  const changed = new Set<string>()
+  const added = new Set<string>()
+  const removed = new Set<string>()
+  for (const file of files) {
+    switch (kindOf(file)) {
+      case 'missing':
+        removed.add(file)
+        for (const inner of knownWithin(known, file)) removed.add(inner)
+        break
+      case 'directory':
+        added.add(file)
+        for (const inner of knownWithin(known, file)) (existsSync(inner) ? changed : removed).add(inner)
+        break
+      default:
+        if (known.has(file)) changed.add(file)
+        else added.add(file)
+    }
+  }
+  return {
+    changed: [...changed].filter(file => !removed.has(file)),
+    added: [...added].filter(file => !removed.has(file)),
+    removed: [...removed],
+  }
+}
+
+/** The default {@link WatchFactory}, based on `fs.watch`. */
+export const watchFiles: WatchFactory = (targets, onChange) => {
+  const watchers: FSWatcher[] = []
+  for (const target of targets) {
+    if (!existsSync(target.path)) continue
+    let watcher: FSWatcher
+    try {
+      watcher = watch(target.path, { recursive: target.recursive }, (_event, filename) => {
+        // no file name (rare, Linux): something changed in the directory itself
+        if (filename === null) {
+          onChange(target.path)
+          return
+        }
+        const name = filename.toString()
+        if (!isIgnoredPath(name)) onChange(join(target.path, name))
+      })
+    } catch {
+      // removed meanwhile (or not watchable): the next compile refreshes the targets
+      continue
+    }
+    watcher.on('error', () => {
+      // a watched directory was removed: keep the other watchers running
+    })
+    watchers.push(watcher)
+  }
+  return {
+    close: () => {
+      for (const watcher of watchers) watcher.close()
+    },
+  }
+}
+
+const targetKey = (target: WatchTarget): string => `${target.recursive ? 'r' : 'f'}:${target.path}`
+
+/**
+ * The watchers of a set of targets that changes after every compile: one watcher per target (started
+ * with a {@link WatchFactory}), so that unchanged targets keep their watcher.
+ */
+export class TargetWatchers {
+  readonly #factory: WatchFactory
+  readonly #onChange: (file: string) => void
+  readonly #watchers = new Map<string, { readonly watcher: FileWatcher; readonly existed: boolean }>()
+
+  constructor(factory: WatchFactory, onChange: (file: string) => void) {
+    this.#factory = factory
+    this.#onChange = onChange
+  }
+
+  /** The watched targets. */
+  get targets(): WatchTarget[] {
+    return [...this.#watchers.keys()].map(key => ({ path: key.slice(2), recursive: key.startsWith('r') }))
+  }
+
+  /**
+   * Watches exactly `targets`: stops the watchers of the targets that are gone, starts the new ones,
+   * and restarts those whose directory was missing when they started, or was itself created, moved or
+   * deleted since (`touched`: the paths of the last changes).
+   */
+  update(targets: readonly WatchTarget[], touched: ReadonlySet<string> = new Set()): void {
+    const wanted = new Map(targets.map(target => [targetKey(target), target]))
+    for (const [key, entry] of this.#watchers) {
+      if (wanted.has(key)) continue
+      entry.watcher.close()
+      this.#watchers.delete(key)
+    }
+    for (const [key, target] of wanted) {
+      const entry = this.#watchers.get(key)
+      const exists = existsSync(target.path)
+      if (entry !== undefined) {
+        if (!exists || (entry.existed && !touched.has(target.path))) continue
+        entry.watcher.close()
+      }
+      this.#watchers.set(key, { watcher: this.#factory([target], this.#onChange), existed: exists })
+    }
+  }
+
+  close(): void {
+    for (const entry of this.#watchers.values()) entry.watcher.close()
+    this.#watchers.clear()
+  }
+}

package/src/main.ts

@@ -0,0 +1,195 @@
+/**
+ * Entry point of the CLI: global options, command dispatch, help, and error reporting with exit
+ * codes (0 ok, 1 failure, 2 usage, 130 cancelled).
+ */
+import type { Command } from './command.ts'
+import type { CliContext, CliContextOptions } from './context.ts'
+
+import { renderCommandHelp, table } from './command.ts'
+import { buildCommand } from './commands/build.ts'
+import { devCommand } from './commands/dev.ts'
+import { generateCommand } from './commands/generate.ts'
+import { newCommand } from './commands/new.ts'
+import { openapiCommand } from './commands/openapi.ts'
+import { schematicCommand } from './commands/schematic.ts'
+import { startCommand } from './commands/start.ts'
+import { createContext } from './context.ts'
+import { CancelledError, CliError, ExitCode, errorMessage, UsageError } from './errors.ts'
+import { suggest } from './names.ts'
+
+/** Every command, in help order. */
+export const COMMANDS: readonly Command[] = [
+  newCommand,
+  generateCommand,
+  schematicCommand,
+  devCommand,
+  buildCommand,
+  startCommand,
+  openapiCommand,
+]
+
+/** Finds a command by name or alias. */
+export function findCommand(name: string): Command | undefined {
+  return COMMANDS.find(command => command.meta.name === name || command.meta.aliases?.includes(name) === true)
+}
+
+interface GlobalOptions {
+  color?: boolean
+  debug: boolean
+  rest: string[]
+}
+
+/** Extracts `--color`, `--no-color` and `--debug` (anywhere before `--`). */
+function extractGlobalOptions(argv: readonly string[]): GlobalOptions {
+  const separator = argv.indexOf('--')
+  const before = separator === -1 ? argv : argv.slice(0, separator)
+  const after = separator === -1 ? [] : argv.slice(separator)
+  const result: GlobalOptions = { debug: false, rest: [] }
+  for (const arg of before) {
+    if (arg === '--color') result.color = true
+    else if (arg === '--no-color') result.color = false
+    else if (arg === '--debug') result.debug = true
+    else result.rest.push(arg)
+  }
+  result.rest.push(...after)
+  return result
+}
+
+/**
+ * Runs the CLI with `argv` (without the executable and script, i.e. `process.argv.slice(2)`).
+ * Resolves with the exit code; never throws.
+ */
+export async function main(argv: readonly string[], options: CliContextOptions = {}): Promise<number> {
+  const globals = extractGlobalOptions(argv)
+  const cli = createContext({
+    ...options,
+    ...(globals.color === undefined ? {} : { color: globals.color }),
+    ...(globals.debug ? { debug: true } : {}),
+  })
+  try {
+    return await dispatch(globals.rest, cli)
+  } catch (error) {
+    return reportError(error, cli)
+  }
+}
+
+async function dispatch(argv: readonly string[], cli: CliContext): Promise<number> {
+  const separator = argv.indexOf('--')
+  const args = separator === -1 ? [...argv] : argv.slice(0, separator)
+  const passthrough = separator === -1 ? [] : argv.slice(separator + 1)
+  const [first, ...rest] = args
+
+  if (first === undefined || first === '-h' || first === '--help') {
+    cli.reporter.log(renderRootHelp(cli))
+    return ExitCode.Ok
+  }
+  if (first === '-v' || first === '--version' || first === 'version') {
+    cli.reporter.log(cli.version)
+    return ExitCode.Ok
+  }
+  if (first === 'help') {
+    const target = rest[0] === undefined ? undefined : findCommand(rest[0])
+    if (rest[0] !== undefined && target === undefined) throw unknownCommand(rest[0])
+    cli.reporter.log(target === undefined ? renderRootHelp(cli) : renderCommandHelp(target, cli.colors))
+    return ExitCode.Ok
+  }
+  if (first.startsWith('-')) {
+    throw new UsageError(`Unknown option ${first}`, ['options go after the command: znight <command> [options]'])
+  }
+
+  let command = findCommand(first)
+  let commandArgs = rest
+  // `generate:service user` and `generate service user` are aliases of `g service user`
+  if (command === undefined && first.startsWith('generate:')) {
+    command = schematicCommand
+    commandArgs = [first.slice('generate:'.length), ...rest]
+  } else if (command === generateCommand && rest[0] !== undefined && !rest[0].startsWith('-')) {
+    command = schematicCommand
+  }
+  if (command === undefined) throw unknownCommand(first)
+
+  if (commandArgs.includes('-h') || commandArgs.includes('--help')) {
+    cli.reporter.log(renderCommandHelp(command, cli.colors))
+    return ExitCode.Ok
+  }
+  try {
+    return await command.execute(commandArgs, passthrough, cli)
+  } catch (error) {
+    if (error instanceof UsageError) {
+      throw new UsageError(error.message, [...error.hints, `run "znight ${command.meta.name} --help" for the usage`])
+    }
+    throw error
+  }
+}
+
+function unknownCommand(name: string): UsageError {
+  const candidate = suggest(
+    name,
+    COMMANDS.flatMap(command => [command.meta.name, ...(command.meta.aliases ?? [])]),
+  )
+  return new UsageError(`Unknown command "${name}"`, [
+    ...(candidate === undefined ? [] : [`did you mean "znight ${candidate}"?`]),
+    'run "znight --help" for the list of commands',
+  ])
+}
+
+/** The help of `znight` (list of commands). */
+export function renderRootHelp(cli: Pick<CliContext, 'colors' | 'version'>): string {
+  const { colors } = cli
+  const commands = table(
+    [
+      ['new <name>', newCommand.meta.description],
+      ['generate', 'Generate the DI container (--check in CI, --watch)'],
+      ['g <schematic> <name>', 'Generate a service, controller, consumer, config, guard, interceptor, factory or job'],
+      ['dev', 'Build in watch mode, restart the application on every change'],
+      ['build', buildCommand.meta.description],
+      ['start', startCommand.meta.description],
+      ['openapi', openapiCommand.meta.description],
+    ],
+    colors,
+  )
+  const options = table(
+    [
+      ['-h, --help', 'Show the help (also: znight <command> --help)'],
+      ['-v, --version', 'Show the version'],
+      ['--color, --no-color', 'Force or disable colors (NO_COLOR and FORCE_COLOR are honoured)'],
+      ['--debug', 'Print the stack trace of unexpected errors (or ZNIGHT_DEBUG=1)'],
+    ],
+    colors,
+  )
+  return [
+    `${colors.bold('znight')} ${colors.dim(`v${cli.version}`)} ${colors.dim('—')} compile-time dependency injection for TypeScript`,
+    '',
+    colors.bold('Usage'),
+    `  ${colors.cyan('znight <command> [options]')}`,
+    '',
+    colors.bold('Commands'),
+    ...commands,
+    '',
+    colors.bold('Global options'),
+    ...options,
+    '',
+    `Run ${colors.cyan('znight <command> --help')} for the options of a command.`,
+    '',
+  ].join('\n')
+}
+
+function reportError(error: unknown, cli: CliContext): number {
+  if (error instanceof CancelledError) {
+    cli.reporter.warn(error.message)
+    return error.exitCode
+  }
+  if (error instanceof CliError) {
+    cli.reporter.error(error.message, error.hints)
+    if (cli.debug && error.cause !== undefined) cli.reporter.logError(stackOf(error.cause))
+    return error.exitCode
+  }
+  cli.reporter.error(`Unexpected error: ${errorMessage(error)}`)
+  if (cli.debug) cli.reporter.logError(stackOf(error))
+  else cli.reporter.logError(cli.colors.dim('  run with --debug (or ZNIGHT_DEBUG=1) for the stack trace'))
+  return ExitCode.Failure
+}
+
+function stackOf(error: unknown): string {
+  return error instanceof Error && error.stack !== undefined ? error.stack : String(error)
+}

package/src/names.ts

@@ -0,0 +1,106 @@
+/**
+ * Naming helpers shared by `znight new` and `znight g`: case conversions, npm package names,
+ * "did you mean" suggestions.
+ */
+
+/** Splits an identifier into lower-case words: `UserProfile`, `user_profile`, `HTTPClient` → words. */
+export function words(name: string): string[] {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .split(/[^A-Za-z0-9]+/)
+    .filter(word => word !== '')
+    .map(word => word.toLowerCase())
+}
+
+/** `user-profile` */
+export function kebabCase(name: string): string {
+  return words(name).join('-')
+}
+
+/** `UserProfile` */
+export function pascalCase(name: string): string {
+  return words(name)
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join('')
+}
+
+/** `userProfile` */
+export function camelCase(name: string): string {
+  const pascal = pascalCase(name)
+  return pascal.charAt(0).toLowerCase() + pascal.slice(1)
+}
+
+/** `USER_PROFILE` */
+export function constantCase(name: string): string {
+  return words(name)
+    .map(word => word.toUpperCase())
+    .join('_')
+}
+
+const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/
+
+/**
+ * Validates an npm package name (lower case, URL-safe, at most 214 characters, optional scope).
+ * Returns a problem description, or `undefined` when the name is valid.
+ */
+export function validatePackageName(name: string): string | undefined {
+  if (name === '') return 'the name cannot be empty'
+  if (name.length > 214) return 'the name cannot be longer than 214 characters'
+  if (name !== name.trim()) return 'the name cannot start or end with spaces'
+  if (name !== name.toLowerCase()) return 'the name must be lower case'
+  if (name.startsWith('.') || name.startsWith('_')) return 'the name cannot start with "." or "_"'
+  if (!PACKAGE_NAME.test(name)) {
+    return 'the name may only contain lower-case letters, digits, "-", ".", "_" and "~" (and an optional @scope/)'
+  }
+  return undefined
+}
+
+/** Turns any string into a valid package name candidate: `My App!` → `my-app`. */
+export function toPackageName(name: string): string {
+  return name
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/^[._]+/, '')
+    .replace(/[^a-z0-9@/._~-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+}
+
+/** The unscoped part of a package name: `@acme/api` → `api`. */
+export function unscopedName(name: string): string {
+  const slash = name.indexOf('/')
+  return name.startsWith('@') && slash !== -1 ? name.slice(slash + 1) : name
+}
+
+/** Levenshtein distance (small strings only). */
+export function editDistance(a: string, b: string): number {
+  const previous = Array.from({ length: b.length + 1 }, (_, index) => index)
+  for (let i = 1; i <= a.length; i++) {
+    let diagonal = previous[0] ?? 0
+    previous[0] = i
+    for (let j = 1; j <= b.length; j++) {
+      const above = previous[j] ?? 0
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      previous[j] = Math.min(above + 1, (previous[j - 1] ?? 0) + 1, diagonal + cost)
+      diagonal = above
+    }
+  }
+  return previous[b.length] ?? 0
+}
+
+/** The closest candidate within a distance of `max(2, length / 3)`, if any. */
+export function suggest(input: string, candidates: Iterable<string>): string | undefined {
+  let best: string | undefined
+  let bestDistance = Number.POSITIVE_INFINITY
+  const limit = Math.max(2, Math.floor(input.length / 3))
+  for (const candidate of candidates) {
+    const distance = editDistance(input.toLowerCase(), candidate.toLowerCase())
+    if (distance < bestDistance && distance <= limit) {
+      best = candidate
+      bestDistance = distance
+    }
+  }
+  return best
+}

package/src/output.ts

@@ -0,0 +1,110 @@
+/**
+ * Terminal output: color detection (NO_COLOR, FORCE_COLOR, `--color` / `--no-color`, TTY), a small
+ * reporter writing consistent status lines, and formatting helpers.
+ */
+import { stripVTControlCharacters } from 'node:util'
+import picocolors from 'picocolors'
+
+/** picocolors formatters (`colors.red('x')`...). */
+export type Colors = ReturnType<typeof picocolors.createColors>
+
+/** A writable text stream (`process.stdout`, or a test double). */
+export interface OutputStream {
+  write(chunk: string): unknown
+  readonly isTTY?: boolean | undefined
+  readonly columns?: number | undefined
+}
+
+/** Inputs of {@link shouldUseColor}. */
+export interface ColorInputs {
+  readonly env: Readonly<Record<string, string | undefined>>
+  readonly stream: OutputStream
+  /** `true` for `--color`, `false` for `--no-color`, `undefined` when neither was passed. */
+  readonly flag?: boolean | undefined
+}
+
+/**
+ * Whether colors should be written: `--no-color` and a non-empty `NO_COLOR` disable them,
+ * `--color` and `FORCE_COLOR` (other than `0`/`false`) force them, otherwise a TTY that is not
+ * `TERM=dumb` gets colors.
+ */
+export function shouldUseColor({ env, stream, flag }: ColorInputs): boolean {
+  if (flag !== undefined) return flag
+  if (env['NO_COLOR'] !== undefined && env['NO_COLOR'] !== '') return false
+  const force = env['FORCE_COLOR']
+  if (force !== undefined) return force !== '0' && force !== 'false'
+  return stream.isTTY === true && env['TERM'] !== 'dumb'
+}
+
+/** picocolors formatters, enabled or not. */
+export function createColors(enabled: boolean): Colors {
+  return picocolors.createColors(enabled)
+}
+
+/** Removes ANSI escape sequences. */
+export function stripAnsi(text: string): string {
+  return stripVTControlCharacters(text)
+}
+
+/** Writes consistent status lines. Errors and warnings go to stderr, everything else to stdout. */
+export interface Reporter {
+  readonly colors: Colors
+  /** A raw line on stdout. */
+  log(message?: string): void
+  /** `› message` */
+  info(message: string): void
+  /** `✓ message` */
+  success(message: string): void
+  /** `! message` (stderr) */
+  warn(message: string, hints?: readonly string[]): void
+  /** `✗ message` (stderr) */
+  error(message: string, hints?: readonly string[]): void
+  /** A raw line on stderr. */
+  logError(message?: string): void
+}
+
+/** Creates a {@link Reporter} writing to the given streams. */
+export function createReporter(stdout: OutputStream, stderr: OutputStream, colors: Colors): Reporter {
+  const line = (stream: OutputStream, text: string): void => {
+    stream.write(`${text}\n`)
+  }
+  const withHints = (stream: OutputStream, hints: readonly string[] | undefined): void => {
+    for (const hint of hints ?? []) line(stream, `  ${colors.dim('=')} ${colors.bold('hint:')} ${hint}`)
+  }
+  return {
+    colors,
+    log: (message = '') => line(stdout, message),
+    info: message => line(stdout, `${colors.cyan('›')} ${message}`),
+    success: message => line(stdout, `${colors.green('✓')} ${message}`),
+    warn: (message, hints) => {
+      line(stderr, `${colors.yellow('!')} ${message}`)
+      withHints(stderr, hints)
+    },
+    error: (message, hints) => {
+      line(stderr, `${colors.red('✗')} ${colors.red(message)}`)
+      withHints(stderr, hints)
+    },
+    logError: (message = '') => line(stderr, message),
+  }
+}
+
+/** `850ms`, `1.24s`, `2m 05s`. */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${Math.round(ms)}ms`
+  if (ms < 60_000) return `${(ms / 1000).toFixed(2)}s`
+  const minutes = Math.floor(ms / 60_000)
+  const seconds = Math.round((ms % 60_000) / 1000)
+  return `${minutes}m ${String(seconds).padStart(2, '0')}s`
+}
+
+/** `512 B`, `1.5 kB`, `2.31 MB` (SI units, like Vite). */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1000) return `${bytes} B`
+  if (bytes < 1_000_000) return `${(bytes / 1000).toFixed(2)} kB`
+  return `${(bytes / 1_000_000).toFixed(2)} MB`
+}
+
+/** `1 provider`, `3 providers`. */
+export function plural(count: number, singular: string, pluralForm = `${singular}s`): string {
+  return `${count} ${count === 1 ? singular : pluralForm}`
+}