@znight/cli 0.0.0-stage → 0.1.1

package/src/commands/new.ts

@@ -0,0 +1,245 @@
+/** `znight new <name>`: scaffolds a project, interactively or from flags. */
+import type { Command } from '../command.ts'
+import type { CliContext } from '../context.ts'
+import type { Prompts } from '../integrations/prompts.ts'
+import type { Feature, HttpAdapterName, PackageManager } from '../scaffold/options.ts'
+
+import { basename, resolve } from 'node:path'
+
+import { defineCommand, hasFlag } from '../command.ts'
+import { CliError, UsageError } from '../errors.ts'
+import { toPackageName, unscopedName, validatePackageName } from '../names.ts'
+import { initGit, installDependencies, targetState, writeProject } from '../scaffold/create.ts'
+import {
+  ADAPTER_LABELS,
+  DEFAULT_FEATURES,
+  detectPackageManager,
+  FEATURE_LABELS,
+  FEATURES,
+  HTTP_ADAPTERS,
+  installCommand,
+  PACKAGE_MANAGERS,
+  parseFeatures,
+  runScript,
+} from '../scaffold/options.ts'
+import { renderProject } from '../scaffold/templates.ts'
+import { displayPath } from './shared.ts'
+
+/** `znight new` */
+export const newCommand: Command = defineCommand({
+  meta: {
+    name: 'new',
+    description: 'Create a new Znight project',
+    usage: '[name] [options]',
+    aliases: ['create', 'init'],
+    examples: [
+      'znight new my-service',
+      'znight new my-service --yes --pm pnpm --adapter fastify --features config,observability,messaging',
+      'znight new my-worker --yes --features config,schedule',
+      'znight new . --yes --no-install',
+    ],
+  },
+  args: {
+    name: {
+      type: 'positional',
+      required: false,
+      description: 'Project name (npm package name), or "." for the current directory',
+    },
+    yes: { type: 'boolean', alias: 'y', description: 'Do not ask questions: use the flags and the defaults' },
+    pm: {
+      type: 'enum',
+      options: ['bun', 'npm', 'pnpm', 'yarn'],
+      description: 'Package manager (default: the one running the CLI, bun under Bun, else npm)',
+    },
+    adapter: {
+      type: 'enum',
+      options: ['node', 'fastify', 'express', 'hono'],
+      description: 'HTTP adapter (default: node, the built-in node:http server)',
+    },
+    features: {
+      type: 'string',
+      valueHint: 'list',
+      description:
+        'Comma-separated features: config, observability, messaging, schedule, openapi, or "all" / "none" (default: config,observability)',
+    },
+    install: { type: 'boolean', default: true, description: 'Do not install the dependencies' },
+    git: { type: 'boolean', default: true, description: 'Do not initialise a git repository' },
+    dir: { type: 'string', valueHint: 'path', description: 'Target directory (default: ./<name>)' },
+    force: { type: 'boolean', description: 'Write into a non-empty directory (existing files are overwritten)' },
+  },
+  async run({ args: options, cli, rawArgs }) {
+    const interactive = cli.interactive && options.yes !== true
+    const prompts = interactive ? await cli.services.loadPrompts() : undefined
+    prompts?.intro(cli.colors.bold(`Create a Znight project ${cli.colors.dim(`v${cli.version}`)}`))
+
+    // name and directory
+    let name = options.name
+    if (name === undefined || name === '') {
+      if (prompts === undefined) {
+        throw new UsageError('Missing project name', ['znight new <name> (or "." to use the current directory)'])
+      }
+      name = await prompts.text({
+        message: 'Project name?',
+        placeholder: 'my-service',
+        validate: value => (value === '.' ? undefined : validatePackageName(value.trim())),
+      })
+    }
+    name = name.trim()
+    const inPlace = name === '.'
+    if (inPlace) name = toPackageName(basename(cli.cwd))
+    const problem = validatePackageName(name)
+    if (problem !== undefined) {
+      const candidate = toPackageName(name)
+      throw new UsageError(
+        `Invalid project name "${name}": ${problem}`,
+        candidate !== '' && validatePackageName(candidate) === undefined ? [`try "${candidate}"`] : [],
+      )
+    }
+    const directory = resolve(cli.cwd, options.dir ?? (inPlace ? '.' : unscopedName(name)))
+    await checkTarget(directory, cli, prompts, options.force === true)
+
+    // choices
+    const packageManager: PackageManager =
+      options.pm ??
+      (await prompts?.select({
+        message: 'Package manager?',
+        choices: PACKAGE_MANAGERS.map(pm => ({ value: pm, label: pm })),
+        initialValue: detectPackageManager(cli.env, cli.runtime.name === 'bun'),
+      })) ??
+      detectPackageManager(cli.env, cli.runtime.name === 'bun')
+    const adapter: HttpAdapterName =
+      options.adapter ??
+      (await prompts?.select({
+        message: 'HTTP adapter?',
+        choices: HTTP_ADAPTERS.map(value => ({ value, label: ADAPTER_LABELS[value] })),
+        initialValue: 'node',
+      })) ??
+      'node'
+    const features = await chooseFeatures(options.features, prompts)
+    const install =
+      prompts === undefined || hasFlag(rawArgs, 'install')
+        ? options.install !== false
+        : await prompts.confirm({ message: `Install the dependencies with ${packageManager}?`, initialValue: true })
+    const git =
+      prompts === undefined || hasFlag(rawArgs, 'git')
+        ? options.git !== false
+        : await prompts.confirm({ message: 'Initialise a git repository?', initialValue: true })
+
+    // files
+    const files = renderProject({ name, packageManager, adapter, features, znightVersion: cli.version })
+    writeProject(directory, files)
+    const where = displayPath(directory, cli.cwd)
+    const summary = `${cli.colors.bold(name)} (${packageManager}, ${adapter}${features.length > 0 ? `, ${features.join(', ')}` : ''})`
+    if (prompts === undefined) cli.reporter.success(`Created ${summary} in ${where}`)
+    else prompts.note(files.map(file => file.path).join('\n'), `Created ${summary} in ${where}`)
+
+    if (git) await runGit(directory, cli, prompts)
+    let installed = false
+    if (install) installed = await runInstall(directory, packageManager, cli, prompts)
+
+    // next steps
+    const steps = [
+      ...(inPlace && options.dir === undefined ? [] : [`cd ${where}`]),
+      ...(installed ? [] : [installCommand(packageManager).join(' ')]),
+      runScript(packageManager, 'dev'),
+    ]
+    if (prompts === undefined) {
+      cli.reporter.log()
+      cli.reporter.log(cli.colors.bold('Next steps:'))
+      for (const step of steps) cli.reporter.log(`  ${cli.colors.cyan(step)}`)
+      cli.reporter.log()
+    } else {
+      prompts.outro(`Next steps:\n${steps.map(step => `   ${cli.colors.cyan(step)}`).join('\n')}`)
+    }
+    if (install && !installed) {
+      throw new CliError('The project was created but installing the dependencies failed', {
+        hints: [`run "${installCommand(packageManager).join(' ')}" in ${where}`],
+      })
+    }
+    return 0
+  },
+})
+
+async function checkTarget(
+  directory: string,
+  cli: CliContext,
+  prompts: Prompts | undefined,
+  force: boolean,
+): Promise<void> {
+  const state = targetState(directory)
+  const where = displayPath(directory, cli.cwd)
+  if (state === 'file') throw new CliError(`${where} exists and is not a directory`)
+  if (state !== 'not-empty' || force) return
+  if (prompts !== undefined) {
+    const proceed = await prompts.confirm({
+      message: `${where} is not empty. Write the project into it anyway (existing files are overwritten)?`,
+      initialValue: false,
+    })
+    if (proceed) return
+  }
+  throw new CliError(`${where} is not empty`, {
+    hints: ['choose another name or --dir, or pass --force to write into it anyway'],
+  })
+}
+
+async function chooseFeatures(value: string | undefined, prompts: Prompts | undefined): Promise<Feature[]> {
+  if (value !== undefined) {
+    const parsed = parseFeatures(value)
+    if ('unknown' in parsed) {
+      throw new UsageError(`Unknown feature${parsed.unknown.length > 1 ? 's' : ''}: ${parsed.unknown.join(', ')}`, [
+        `available features: ${FEATURES.join(', ')} (or "all", "none")`,
+      ])
+    }
+    return parsed.features
+  }
+  if (prompts === undefined) return [...DEFAULT_FEATURES]
+  const selected = await prompts.multiselect({
+    message: 'Features? (space to toggle)',
+    choices: FEATURES.map(feature => ({ value: feature, label: FEATURE_LABELS[feature] })),
+    initialValues: DEFAULT_FEATURES,
+  })
+  return FEATURES.filter(feature => selected.includes(feature))
+}
+
+async function runGit(directory: string, cli: CliContext, prompts: Prompts | undefined): Promise<void> {
+  const outcome = await initGit(cli.services.processes, directory, cli.env)
+  const message = {
+    initialized: 'Initialised a git repository',
+    'inside-repository': 'Already inside a git repository: skipped git init',
+    unavailable: 'git is not available: skipped git init',
+    failed: 'git init failed: skipped',
+  }[outcome]
+  if (outcome === 'initialized') {
+    if (prompts === undefined) cli.reporter.success(message)
+  } else {
+    cli.reporter.warn(message)
+  }
+}
+
+async function runInstall(
+  directory: string,
+  packageManager: PackageManager,
+  cli: CliContext,
+  prompts: Prompts | undefined,
+): Promise<boolean> {
+  const command = installCommand(packageManager).join(' ')
+  const spinner = prompts?.spinner()
+  if (spinner === undefined) cli.reporter.info(`Installing the dependencies (${command})...`)
+  else spinner.start(`Installing the dependencies (${command})`)
+  const result = await installDependencies(cli.services.processes, directory, packageManager, cli.env)
+  const ok = result.code === 0 && result.error === undefined
+  if (ok) {
+    if (spinner === undefined) cli.reporter.success('Installed the dependencies')
+    else spinner.stop('Installed the dependencies')
+    return true
+  }
+  const reason =
+    result.error === undefined
+      ? `${command} exited with code ${result.code ?? result.signal}`
+      : `${packageManager} could not be started (${result.error.message})`
+  if (spinner === undefined) cli.reporter.error(reason)
+  else spinner.stop(reason, true)
+  const output = `${result.stdout}${result.stderr}`.trim()
+  if (output !== '') cli.reporter.logError(output.split('\n').slice(-30).join('\n'))
+  return false
+}

package/src/commands/openapi.ts

@@ -0,0 +1,160 @@
+/**
+ * `znight openapi`: writes the OpenAPI document of the application (`openapi.json`, or YAML by
+ * extension) with `@znight/openapi/emit`, or checks that the committed file is up to date
+ * (`--check`, for CI). The modules of the application run in a child process.
+ */
+import type { Command } from '../command.ts'
+import type { CliContext } from '../context.ts'
+import type { CompilerApi, Diagnostic } from '../integrations/compiler.ts'
+import type { OpenApiEmitResultLike } from '../integrations/openapi.ts'
+import type { ViteConfigLoader } from '../integrations/vite.ts'
+
+import { existsSync } from 'node:fs'
+
+import { defineCommand } from '../command.ts'
+import { CliError, errorMessage } from '../errors.ts'
+import { hasErrors } from '../integrations/compiler.ts'
+import { formatDuration, plural } from '../output.ts'
+import { compilerOptions } from './generate.ts'
+import { displayPath, parseHttpPrefix, resolveRoot } from './shared.ts'
+
+/** Values of a repeatable string option (`-o a -o b`, `--output=a`, `--output b,c`). */
+export function repeatedOption(rawArgs: readonly string[], name: string, alias: string): string[] {
+  const values: string[] = []
+  for (let index = 0; index < rawArgs.length; index++) {
+    const token = rawArgs[index] ?? ''
+    let value: string | undefined
+    if (token === `--${name}` || token === `-${alias}`) value = rawArgs[++index]
+    else if (token.startsWith(`--${name}=`)) value = token.slice(name.length + 3)
+    else if (token.startsWith(`-${alias}=`)) value = token.slice(alias.length + 2)
+    if (value === undefined) continue
+    for (const part of value.split(',')) if (part.trim() !== '') values.push(part.trim())
+  }
+  return values
+}
+
+/** `znight openapi` */
+export const openapiCommand: Command = defineCommand({
+  meta: {
+    name: 'openapi',
+    description: 'Emit the OpenAPI document of the application (openapi.json, --check in CI)',
+    usage: '[options]',
+    examples: [
+      'znight openapi                      # writes openapi.json at the project root',
+      'znight openapi -o docs/openapi.yaml # YAML, chosen by the extension (needs yaml)',
+      'znight openapi --check              # CI: exit 1 when the file is missing or stale',
+      'znight openapi --prefix /api        # servers default when @OpenApiDocument declares none',
+      'znight openapi --runtime bun        # load the modules with Bun',
+    ],
+    details: [
+      'The application is compiled like "znight generate" (compile errors stop everything), then its',
+      'generated module is loaded in a child process (Bun: the compiler preload; Node.js: a Vite server)',
+      'and @znight/openapi assembles the document. Nothing is instantiated. Outputs are only written',
+      'when they change. Requires @znight/openapi in the project.',
+    ].join('\n'),
+  },
+  args: {
+    output: {
+      type: 'string',
+      alias: 'o',
+      valueHint: 'file',
+      description: 'Output file, repeatable (.yaml / .yml write YAML). Default: openapi.json',
+    },
+    check: { type: 'boolean', description: 'Do not write: exit with code 1 when an output is missing or stale' },
+    prefix: { type: 'string', valueHint: 'path', description: 'HTTP prefix: the servers default (/api)' },
+    runtime: {
+      type: 'enum',
+      options: ['auto', 'node', 'bun'],
+      description: 'Runtime loading the application modules (default: auto, the one running the CLI)',
+    },
+    converters: {
+      type: 'string',
+      valueHint: 'file',
+      description: 'Module whose default export is a SchemaConverter[] (custom schema libraries)',
+    },
+    root: { type: 'string', valueHint: 'dir', description: 'Project root (default: the current directory)' },
+    config: { type: 'string', valueHint: 'file', description: 'Vite config file (default: vite.config.*)' },
+    'config-loader': {
+      type: 'enum',
+      options: ['bundle', 'runner', 'native'],
+      description: 'How Vite loads the config file (default: bundle)',
+    },
+  },
+  async run({ args, cli, rawArgs }) {
+    const root = resolveRoot(cli, args.root)
+    const outputs = repeatedOption(rawArgs, 'output', 'o')
+    const prefix = parseHttpPrefix(args.prefix, 'prefix')
+    const compiler = await cli.services.loadCompiler(root)
+    const configLoader = args['config-loader'] as ViteConfigLoader | undefined
+    const options = await compilerOptions(cli, compiler, root, args.config, configLoader)
+    const openapi = await cli.services.loadOpenApi(root)
+    const started = performance.now()
+    let result: OpenApiEmitResultLike
+    try {
+      result = await openapi.emitOpenApi({
+        root,
+        output: outputs.length > 0 ? outputs : ['openapi.json'],
+        ...(args.check === true ? { check: true } : {}),
+        ...(prefix === undefined ? {} : { prefix }),
+        ...(args.runtime === undefined ? {} : { runtime: args.runtime as 'auto' | 'node' | 'bun' }),
+        ...(args.converters === undefined ? {} : { converters: args.converters }),
+        ...(args.config === undefined ? {} : { config: args.config }),
+        ...(configLoader === undefined ? {} : { configLoader }),
+        compilerOptions: options,
+      })
+    } catch (error) {
+      const hints = (error as { hints?: unknown } | null)?.hints
+      throw new CliError(`OpenAPI emission failed: ${errorMessage(error)}`, {
+        cause: error,
+        hints: Array.isArray(hints) ? (hints as string[]) : [],
+      })
+    }
+    printDiagnostics(cli, compiler, result.diagnostics, root)
+    if (!result.ok || hasErrors(result.diagnostics)) {
+      const errors = result.diagnostics.filter(diagnostic => diagnostic.severity === 'error').length
+      cli.reporter.error(`OpenAPI emission failed: the application does not compile (${plural(errors, 'error')})`)
+      return 1
+    }
+    for (const warning of result.warnings) cli.reporter.warn(`${warning.code}: ${warning.message}`)
+    const elapsed = formatDuration(performance.now() - started)
+    const operations = Object.values(result.document?.paths ?? {}).reduce(
+      (count, item) => count + Object.keys(item).length,
+      0,
+    )
+    const stats = cli.colors.dim(`(${plural(operations, 'operation')}, ${result.runtime}, ${elapsed})`)
+    if (args.check === true) {
+      for (const file of result.staleFiles) {
+        const shown = displayPath(file, cli.cwd)
+        if (existsSync(file))
+          cli.reporter.error(`${shown} is out of date`, ['run "znight openapi" and commit the result'])
+        else cli.reporter.error(`${shown} is missing`, ['run "znight openapi" and commit the result'])
+      }
+      if (result.stale) return 1
+      cli.reporter.success(
+        `${result.outputs.map(file => cli.colors.bold(displayPath(file, cli.cwd))).join(', ')} up to date ${stats}`,
+      )
+      return 0
+    }
+    for (const file of result.outputs) {
+      const shown = cli.colors.bold(displayPath(file, cli.cwd))
+      cli.reporter.success(`${result.written.includes(file) ? 'Wrote' : 'Up to date:'} ${shown} ${stats}`)
+    }
+    return 0
+  },
+})
+
+function printDiagnostics(
+  cli: CliContext,
+  compiler: CompilerApi,
+  diagnostics: readonly Diagnostic[],
+  root: string,
+): void {
+  if (diagnostics.length === 0) return
+  const text = compiler.formatDiagnostics(diagnostics, {
+    color: cli.colors.isColorSupported,
+    cwd: root,
+    summary: false,
+  })
+  cli.reporter.logError(text.trimEnd())
+  cli.reporter.logError()
+}

package/src/commands/schematic.ts

@@ -0,0 +1,110 @@
+/** `znight g <schematic> <name>`: generates a service, controller, consumer, config, guard, interceptor, factory or job. */
+import type { Command } from '../command.ts'
+import type { Colors } from '../output.ts'
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+
+import { defineCommand, table } from '../command.ts'
+import { CliError, UsageError } from '../errors.ts'
+import { suggest } from '../names.ts'
+import { findSchematic, planSchematic, SCHEMATICS } from '../schematics/index.ts'
+import { displayPath, findProjectRoot, readManifest, resolveRoot } from './shared.ts'
+
+function schematicList(colors: Colors): string {
+  return table(
+    SCHEMATICS.map(
+      schematic => [`${schematic.name} (${schematic.aliases.join(', ')})`, schematic.description] as const,
+    ),
+    colors,
+  ).join('\n')
+}
+
+/** `znight g` */
+export const schematicCommand: Command = defineCommand({
+  meta: {
+    name: 'g',
+    description: 'Generate a service, controller, consumer, config, guard, interceptor, factory or job',
+    usage: '<schematic> <name> [options]',
+    aliases: ['generate <schematic>'],
+    details: colors =>
+      `${colors.bold('Schematics')}\n${schematicList(colors)}\n\nFiles are named <name>.<schematic>.ts (kebab-case), classes <Name><Schematic> (PascalCase).`,
+    examples: [
+      'znight g service users/user           # src/users/user.service.ts (UserService)',
+      'znight g controller order             # src/order/order.controller.ts (OrderController)',
+      'znight g guard auth --flat            # src/auth.guard.ts (AuthGuard)',
+      'znight g interceptor timing --aop     # a method interceptor (@Intercept)',
+      'znight g consumer orders --path src/messaging',
+      'znight g job digest                   # src/digest/digest.jobs.ts (DigestJobs)',
+    ],
+  },
+  args: {
+    schematic: { type: 'positional', required: false, description: 'What to generate (see Schematics below)' },
+    name: {
+      type: 'positional',
+      required: false,
+      description: 'Name, optionally prefixed with directories relative to src/ (users/user-profile)',
+    },
+    path: { type: 'string', valueHint: 'dir', description: 'Directory of the file (default: src/<name>/)' },
+    flat: { type: 'boolean', description: 'Do not create a directory named after the element' },
+    force: { type: 'boolean', alias: 'f', description: 'Overwrite an existing file' },
+    'dry-run': { type: 'boolean', alias: 'd', description: 'Print the file instead of writing it' },
+    aop: { type: 'boolean', description: 'interceptor: a method interceptor (@Intercept) instead of an HTTP one' },
+    root: { type: 'string', valueHint: 'dir', description: 'Project root (default: the nearest package.json)' },
+  },
+  run({ args, cli }) {
+    if (args.schematic === undefined || args.schematic === '') {
+      throw new UsageError('Missing <schematic>', [`available schematics:\n${schematicList(cli.colors)}`])
+    }
+    const schematic = findSchematic(args.schematic)
+    if (schematic === undefined) {
+      const candidate = suggest(
+        args.schematic,
+        SCHEMATICS.map(item => item.name),
+      )
+      throw new UsageError(`Unknown schematic "${args.schematic}"`, [
+        ...(candidate === undefined ? [] : [`did you mean "${candidate}"?`]),
+        `available schematics: ${SCHEMATICS.map(item => item.name).join(', ')}`,
+      ])
+    }
+    if (args.name === undefined || args.name === '') {
+      throw new UsageError('Missing <name>', [
+        `znight g ${schematic.name} <name>, e.g. znight g ${schematic.name} users/user`,
+      ])
+    }
+    const root = args.root === undefined ? findProjectRoot(cli.cwd) : resolveRoot(cli, args.root)
+    const manifest = readManifest(root)
+    const zod = manifest.dependencies?.['zod'] !== undefined || manifest.devDependencies?.['zod'] !== undefined
+    let plan: ReturnType<typeof planSchematic>
+    try {
+      plan = planSchematic({
+        schematic,
+        name: args.name,
+        root,
+        path: args.path === undefined ? undefined : resolve(cli.cwd, args.path),
+        flat: args.flat === true,
+        context: { zod, aop: args.aop === true },
+      })
+    } catch (error) {
+      throw new UsageError(error instanceof Error ? error.message : String(error))
+    }
+    const file = displayPath(plan.file, cli.cwd)
+    if (args['dry-run'] === true) {
+      cli.reporter.info(`Would create ${cli.colors.bold(file)} (${plan.names.className})`)
+      cli.reporter.log()
+      cli.reporter.log(plan.content)
+      return 0
+    }
+    const exists = existsSync(plan.file)
+    if (exists && args.force !== true) {
+      throw new CliError(`${file} already exists`, { hints: ['pass --force to overwrite it'] })
+    }
+    mkdirSync(dirname(plan.file), { recursive: true })
+    writeFileSync(plan.file, plan.content)
+    cli.reporter.success(
+      `${exists ? 'Overwrote' : 'Created'} ${cli.colors.bold(file)} ${cli.colors.dim(`(${plan.names.className})`)}`,
+    )
+    if (plan.hint !== undefined) cli.reporter.log(`  ${cli.colors.dim(plan.hint)}`)
+    return 0
+  },
+})

package/src/commands/shared.ts

@@ -0,0 +1,106 @@
+/** Helpers shared by the commands. */
+import type { CliContext } from '../context.ts'
+
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+
+import { CliError, UsageError } from '../errors.ts'
+
+/** `--root`, resolved against the working directory. Must be an existing directory. */
+export function resolveRoot(cli: CliContext, root: string | undefined): string {
+  const directory = resolve(cli.cwd, root ?? '.')
+  let isDirectory = false
+  try {
+    isDirectory = statSync(directory).isDirectory()
+  } catch {
+    isDirectory = false
+  }
+  if (!isDirectory) throw new CliError(`Project root not found: ${directory}`)
+  return directory
+}
+
+/** The nearest directory containing a `package.json`, from `start` upwards (`start` when none). */
+export function findProjectRoot(start: string): string {
+  let directory = start
+  for (;;) {
+    if (existsSync(join(directory, 'package.json'))) return directory
+    const parent = dirname(directory)
+    if (parent === directory) return start
+    directory = parent
+  }
+}
+
+/** Reads `package.json` of `root` (an empty object when missing or invalid). */
+export function readManifest(root: string): {
+  dependencies?: Record<string, string>
+  devDependencies?: Record<string, string>
+} {
+  try {
+    const manifest: unknown = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+    return typeof manifest === 'object' && manifest !== null ? manifest : {}
+  } catch {
+    return {}
+  }
+}
+
+/** Parses a non-negative integer option (milliseconds...). */
+export function parseNonNegativeInteger(value: string | undefined, option: string, fallback: number): number {
+  if (value === undefined || value === '') return fallback
+  const parsed = Number(value)
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new UsageError(`Invalid value for --${option}: expected a non-negative integer, got "${value}"`)
+  }
+  return parsed
+}
+
+/** An HTTP prefix option (`/api`, the `prefix` of `HttpPlugin`): `undefined` when not given. */
+export function parseHttpPrefix(value: string | undefined, option: string): string | undefined {
+  if (value === undefined) return undefined
+  if (!value.startsWith('/')) {
+    throw new UsageError(`Invalid --${option} "${value}": expected a path starting with "/"`)
+  }
+  return value
+}
+
+/** A path for messages: relative to `from`, or absolute when that is shorter. POSIX separators. */
+export function displayPath(file: string, from: string): string {
+  const path = relative(from, file)
+  if (path === '') return '.'
+  const shortest = isAbsolute(path) || (path.startsWith('..') && file.length < path.length) ? file : path
+  return shortest.split(sep).join('/')
+}
+
+/**
+ * Signals stopping a long-running command: Ctrl+C, `kill`, the terminal closed (`SIGHUP`) and, on
+ * POSIX, `Ctrl+\` (`SIGQUIT`). Without a listener the last two kill the CLI without running its exit
+ * hooks, leaving the application of `znight dev` (in its own session) running.
+ */
+export const TERMINATION_SIGNALS: readonly NodeJS.Signals[] =
+  process.platform === 'win32' ? ['SIGINT', 'SIGTERM', 'SIGHUP'] : ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT']
+
+/**
+ * Calls `onFirst` on the first {@link TERMINATION_SIGNALS termination signal}; `onRepeat` runs on
+ * any later one (force quit). Returns a function removing the listeners.
+ */
+export function onTermination(
+  cli: CliContext,
+  onFirst: (signal: NodeJS.Signals) => void,
+  onRepeat: (signal: NodeJS.Signals) => void,
+): () => void {
+  let received = false
+  const listeners = TERMINATION_SIGNALS.map(signal => {
+    const listener = (): void => {
+      if (received) {
+        onRepeat(signal)
+        return
+      }
+      received = true
+      onFirst(signal)
+    }
+    cli.signals.on(signal, listener)
+    return [signal, listener] as const
+  })
+  return () => {
+    for (const [signal, listener] of listeners) cli.signals.off(signal, listener)
+  }
+}