@znight/cli 0.0.0-stage → 0.1.1

package/dist/orphan-Dn-2xMBd.mjs

@@ -0,0 +1,45 @@
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+// src/dev/orphan.ts
+/**
+* Environment variable configuring the guard in the application process:
+* `<CLI pid>:<poll interval ms>:<kill timeout ms>`. The guard removes it from the environment right
+* away, so that the processes the application starts itself are not guarded.
+*/
+const ORPHAN_GUARD_ENV = "ZNIGHT_DEV_PARENT";
+/** Package export of the preloaded module (resolved from the CLI itself). */
+const ORPHAN_GUARD_MODULE = "@znight/cli/orphan-guard";
+/**
+* The runtime arguments and environment installing the guard in an application run with `runtime`,
+* `undefined` when the guard module cannot be located (the application then runs without it).
+*/
+function orphanGuard(runtime, settings, resolveModule = (specifier) => import.meta.resolve(specifier)) {
+	let url;
+	try {
+		url = resolveModule(ORPHAN_GUARD_MODULE);
+	} catch {
+		return;
+	}
+	if (!url.startsWith("file:") || !existsSync(fileURLToPath(url))) return void 0;
+	const args = runtime === "node" ? ["--import", url] : ["--preload", fileURLToPath(url)];
+	const value = `${settings.parentPid}:${settings.pollMs}:${settings.killTimeoutMs}`;
+	return {
+		args,
+		env: { [ORPHAN_GUARD_ENV]: value }
+	};
+}
+/** Reads {@link ORPHAN_GUARD_ENV}: `undefined` when it is missing or malformed. */
+function parseOrphanGuard(value) {
+	const parts = value?.split(":") ?? [];
+	if (parts.length !== 3 || parts.some((part) => !/^\d+$/.test(part))) return void 0;
+	const [parentPid = 0, pollMs = 0, killTimeoutMs = 0] = parts.map(Number);
+	if (parentPid <= 0 || pollMs <= 0) return void 0;
+	return {
+		parentPid,
+		pollMs,
+		killTimeoutMs
+	};
+}
+export { orphanGuard as n, parseOrphanGuard as r, ORPHAN_GUARD_ENV as t };
+
+//# sourceMappingURL=orphan-Dn-2xMBd.mjs.map

package/dist/orphan-Dn-2xMBd.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"orphan-Dn-2xMBd.mjs","names":[],"sources":["../src/dev/orphan.ts"],"sourcesContent":["/**\n * The orphan guard of `znight dev`. The application runs detached (its own process group, so that a\n * terminal Ctrl+C reaches the CLI only), so when the CLI dies without stopping it (`kill -9`, the OOM\n * killer) it keeps running, holding its port. The CLI therefore preloads `orphan-guard.ts` into the\n * application (`--import` on Node.js, `--preload` on Bun): it watches the CLI process and stops the\n * application once the CLI is gone. No cooperation of the application is needed.\n */\nimport type { RuntimeName } from '../runtime.ts'\n\nimport { existsSync } from 'node:fs'\nimport { fileURLToPath } from 'node:url'\n\n/**\n * Environment variable configuring the guard in the application process:\n * `<CLI pid>:<poll interval ms>:<kill timeout ms>`. The guard removes it from the environment right\n * away, so that the processes the application starts itself are not guarded.\n */\nexport const ORPHAN_GUARD_ENV = 'ZNIGHT_DEV_PARENT'\n\n/** Package export of the preloaded module (resolved from the CLI itself). */\nconst ORPHAN_GUARD_MODULE = '@znight/cli/orphan-guard'\n\n/** Settings of the guard. */\nexport interface OrphanGuardSettings {\n  /** The CLI process, parent of the application. */\n  readonly parentPid: number\n  /** How often the guard checks that the CLI is still there. */\n  readonly pollMs: number\n  /** Time the application gets to stop after SIGTERM before SIGKILL. */\n  readonly killTimeoutMs: number\n}\n\n/** What a spawned application needs for the guard: runtime arguments and environment. */\nexport interface OrphanGuard {\n  /** Runtime arguments preloading the guard (before the entry file). */\n  readonly args: readonly string[]\n  /** Environment variables configuring it. */\n  readonly env: Readonly<Record<string, string>>\n}\n\n/** Default {@link OrphanGuardSettings.pollMs}. */\nexport const ORPHAN_GUARD_POLL_MS = 500\n\n/**\n * The runtime arguments and environment installing the guard in an application run with `runtime`,\n * `undefined` when the guard module cannot be located (the application then runs without it).\n */\nexport function orphanGuard(\n  runtime: RuntimeName,\n  settings: OrphanGuardSettings,\n  resolveModule: (specifier: string) => string = specifier => import.meta.resolve(specifier),\n): OrphanGuard | undefined {\n  let url: string\n  try {\n    url = resolveModule(ORPHAN_GUARD_MODULE)\n  } catch {\n    return undefined\n  }\n  // a missing preload would stop the application from starting\n  if (!url.startsWith('file:') || !existsSync(fileURLToPath(url))) return undefined\n  // Node.js imports URLs; Bun preloads paths (and ignores data: URLs)\n  const args = runtime === 'node' ? ['--import', url] : ['--preload', fileURLToPath(url)]\n  const value = `${settings.parentPid}:${settings.pollMs}:${settings.killTimeoutMs}`\n  return { args, env: { [ORPHAN_GUARD_ENV]: value } }\n}\n\n/** Reads {@link ORPHAN_GUARD_ENV}: `undefined` when it is missing or malformed. */\nexport function parseOrphanGuard(value: string | undefined): OrphanGuardSettings | undefined {\n  const parts = value?.split(':') ?? []\n  if (parts.length !== 3 || parts.some(part => !/^\\d+$/.test(part))) return undefined\n  const [parentPid = 0, pollMs = 0, killTimeoutMs = 0] = parts.map(Number)\n  if (parentPid <= 0 || pollMs <= 0) return undefined\n  return { parentPid, pollMs, killTimeoutMs }\n}\n"],"mappings":";;;;;;;;AAiBA,MAAa,mBAAmB;;AAGhC,MAAM,sBAAsB;;;;;AA2B5B,SAAgB,YACd,SACA,UACA,iBAA+C,cAAa,YAAY,QAAQ,SAAS,GAChE;CACzB,IAAI;CACJ,IAAI;EACF,MAAM,cAAc,mBAAmB;CACzC,QAAQ;EACN;CACF;CAEA,IAAI,CAAC,IAAI,WAAW,OAAO,KAAK,CAAC,WAAW,cAAc,GAAG,CAAC,GAAG,OAAO,KAAA;CAExE,MAAM,OAAO,YAAY,SAAS,CAAC,YAAY,GAAG,IAAI,CAAC,aAAa,cAAc,GAAG,CAAC;CACtF,MAAM,QAAQ,GAAG,SAAS,UAAU,GAAG,SAAS,OAAO,GAAG,SAAS;CACnE,OAAO;EAAE;EAAM,KAAK,GAAG,mBAAmB,MAAM;CAAE;AACpD;;AAGA,SAAgB,iBAAiB,OAA4D;CAC3F,MAAM,QAAQ,OAAO,MAAM,GAAG,KAAK,CAAC;CACpC,IAAI,MAAM,WAAW,KAAK,MAAM,MAAK,SAAQ,CAAC,QAAQ,KAAK,IAAI,CAAC,GAAG,OAAO,KAAA;CAC1E,MAAM,CAAC,YAAY,GAAG,SAAS,GAAG,gBAAgB,KAAK,MAAM,IAAI,MAAM;CACvE,IAAI,aAAa,KAAK,UAAU,GAAG,OAAO,KAAA;CAC1C,OAAO;EAAE;EAAW;EAAQ;CAAc;AAC5C"}

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@znight/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Znight CLI: scaffold projects, generate code, run dev server and builds",
+  "license": "MIT",
+  "author": "Ugho STEPHAN",
+  "homepage": "https://github.com/znight-org/znight/tree/main/packages/cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/znight-org/znight.git",
+    "directory": "packages/cli"
+  },
+  "bugs": "https://github.com/znight-org/znight/issues",
+  "keywords": ["znight", "cli", "scaffolding", "generator", "dependency-injection", "vite"],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "@znight/source": "./src/index.ts",
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./orphan-guard": {
+      "@znight/source": "./src/dev/orphan-guard.ts",
+      "default": "./dist/dev/orphan-guard.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": ["bin", "dist", "src"],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p test",
+    "test:e2e": "ZNIGHT_CLI_E2E=1 bun test --conditions=@znight/source test/e2e.test.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "@znight/core": "0.1.1",
+    "citty": "^0.2.2",
+    "picocolors": "^1.1.1"
+  },
+  "bin": {
+    "znight": "./bin/znight.mjs"
+  },
+  "devDependencies": {
+    "vite": "8.3.5",
+    "@znight/compiler": "0.1.1",
+    "@znight/openapi": "0.1.1",
+    "@znight/schedule": "0.1.1"
+  },
+  "peerDependencies": {
+    "@znight/compiler": "^0.1.1",
+    "vite": "^8.0.0",
+    "@znight/openapi": "^0.1.1"
+  },
+  "peerDependenciesMeta": {
+    "@znight/compiler": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    },
+    "@znight/openapi": {
+      "optional": true
+    }
+  }
+}

package/src/cli.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * The `znight` binary. Everything lives in `main()`; this file only wires the process: arguments,
+ * exit code, and a safety net for handles left open by third-party code (prompts, watchers).
+ */
+import { main } from './main.ts'
+
+const code = await main(process.argv.slice(2))
+process.exitCode = code
+// let pending output flush, then exit even if a library left a handle open
+setTimeout(() => process.exit(code), 1000).unref()

package/src/command.ts

@@ -0,0 +1,217 @@
+/**
+ * A small command layer over citty's argument parser: strict options (unknown options and extra
+ * arguments are usage errors, with suggestions), `--` pass-through arguments and help rendering
+ * that honours the color settings.
+ */
+import type { ArgDef, ArgsDef, ParsedArgs } from 'citty'
+import type { CliContext } from './context.ts'
+import type { Colors } from './output.ts'
+
+import { parseArgs } from 'citty'
+
+import { UsageError } from './errors.ts'
+import { camelCase, kebabCase, suggest } from './names.ts'
+import { stripAnsi } from './output.ts'
+
+/** What a command receives. */
+export interface CommandRunContext<A extends ArgsDef = ArgsDef> {
+  readonly args: ParsedArgs<A>
+  readonly cli: CliContext
+  /** Arguments of the command as typed (before `--`). */
+  readonly rawArgs: readonly string[]
+  /** Arguments after `--` (forwarded to the application by `dev` and `start`). */
+  readonly passthrough: readonly string[]
+}
+
+/** Whether an option was explicitly given (`--install`, `--no-install`, `--install=false`). */
+export function hasFlag(rawArgs: readonly string[], name: string): boolean {
+  return rawArgs.some(
+    arg =>
+      arg === `--${name}` || arg === `--no-${name}` || arg.startsWith(`--${name}=`) || arg.startsWith(`--no-${name}=`),
+  )
+}
+
+/** Description of a command. */
+export interface CommandMeta {
+  readonly name: string
+  readonly description: string
+  readonly aliases?: readonly string[]
+  /** Usage line after `znight <name>` (default: computed from the arguments). */
+  readonly usage?: string
+  readonly examples?: readonly string[]
+  /** Extra help paragraph printed after the options. */
+  readonly details?: string | ((colors: Colors) => string)
+}
+
+/** Definition of a command: typed arguments and the implementation. */
+export interface CommandDefinition<A extends ArgsDef> {
+  readonly meta: CommandMeta
+  readonly args: A
+  /** Runs the command; the returned number is the exit code (default 0). */
+  run(context: CommandRunContext<A>): number | undefined | Promise<number | undefined>
+}
+
+/** A CLI command, ready to execute. */
+export interface Command {
+  readonly meta: CommandMeta
+  readonly args: ArgsDef
+  /**
+   * Parses `argv` (the arguments after the command name, without `--` pass-through arguments) and
+   * runs the command. Resolves with the exit code.
+   */
+  execute(argv: readonly string[], passthrough: readonly string[], cli: CliContext): Promise<number>
+}
+
+/** Creates a {@link Command}; `args` keep their literal types in `run`. */
+export function defineCommand<const A extends ArgsDef>(definition: CommandDefinition<A>): Command {
+  return {
+    meta: definition.meta,
+    args: definition.args,
+    execute: async (argv, passthrough, cli) => {
+      const args = parseCommandArgs(definition, argv)
+      return (await definition.run({ args, cli, rawArgs: argv, passthrough })) ?? 0
+    },
+  }
+}
+
+/** Parses `argv` (without the command name and without `--` pass-through) for `command`. */
+export function parseCommandArgs<A extends ArgsDef>(
+  command: Pick<CommandDefinition<A>, 'args'>,
+  argv: readonly string[],
+): ParsedArgs<A> {
+  checkOptions(command, argv)
+  let parsed: ParsedArgs<A>
+  try {
+    parsed = parseArgs<A>([...argv], command.args)
+  } catch (error) {
+    throw new UsageError(stripAnsi(error instanceof Error ? error.message : String(error)))
+  }
+  const positionals = Object.values(command.args).filter(arg => arg.type === 'positional').length
+  const extra = parsed._.slice(positionals)
+  if (extra.length > 0) {
+    throw new UsageError(`Unexpected argument${extra.length > 1 ? 's' : ''}: ${extra.join(' ')}`)
+  }
+  return parsed
+}
+
+interface OptionInfo {
+  readonly type: ArgDef['type']
+}
+
+function optionTable(args: ArgsDef): Map<string, OptionInfo> {
+  const table = new Map<string, OptionInfo>([
+    ['help', { type: 'boolean' }],
+    ['h', { type: 'boolean' }],
+  ])
+  for (const [name, def] of Object.entries(args)) {
+    if (def.type === 'positional') continue
+    const info: OptionInfo = { type: def.type }
+    for (const key of [name, kebabCase(name), camelCase(name), ...aliasesOf(def)]) table.set(key, info)
+  }
+  return table
+}
+
+function aliasesOf(def: ArgDef): string[] {
+  if (!('alias' in def) || def.alias === undefined) return []
+  return Array.isArray(def.alias) ? [...def.alias] : [def.alias]
+}
+
+function checkOptions(command: Pick<Command, 'args'>, argv: readonly string[]): void {
+  const table = optionTable(command.args)
+  const longNames = [...table.keys()].filter(name => name.length > 1)
+  for (let index = 0; index < argv.length; index++) {
+    const token = argv[index] ?? ''
+    if (!token.startsWith('-') || token === '-') continue
+    if (token.startsWith('--')) {
+      const [rawName = '', inlineValue] = token.slice(2).split(/=(.*)/s, 2)
+      let info = table.get(rawName)
+      if (info === undefined && rawName.startsWith('no-')) {
+        const negated = table.get(rawName.slice(3))
+        if (negated?.type === 'boolean') info = negated
+      }
+      if (info === undefined) {
+        const candidate = suggest(rawName, longNames)
+        throw new UsageError(
+          `Unknown option --${rawName}`,
+          candidate === undefined ? [] : [`did you mean --${candidate}?`],
+        )
+      }
+      if ((info.type === 'string' || info.type === 'enum') && inlineValue === undefined) index++
+      continue
+    }
+    // short options: -y, -f, or a group of boolean flags (-yf)
+    const letters = token.slice(1)
+    for (const [position, letter] of [...letters].entries()) {
+      const info = table.get(letter)
+      if (info === undefined) throw new UsageError(`Unknown option -${letter}`)
+      if ((info.type === 'string' || info.type === 'enum') && position === letters.length - 1) index++
+    }
+  }
+}
+
+/** Formats the help of a command. */
+export function renderCommandHelp(command: Pick<Command, 'meta' | 'args'>, colors: Colors): string {
+  const { meta } = command
+  const entries = Object.entries(command.args)
+  const positionals = entries.filter(([, def]) => def.type === 'positional')
+  const options = entries.filter(([, def]) => def.type !== 'positional')
+  const usage =
+    meta.usage ??
+    [
+      ...positionals.map(([name, def]) =>
+        def.required === false || def.default !== undefined ? `[${name}]` : `<${name}>`,
+      ),
+      options.length > 0 ? '[options]' : '',
+    ]
+      .filter(Boolean)
+      .join(' ')
+  const lines = [`${colors.bold(`znight ${meta.name}`)} ${colors.dim('—')} ${meta.description}`, '']
+  lines.push(colors.bold('Usage'), `  ${colors.cyan(`znight ${meta.name}${usage === '' ? '' : ` ${usage}`}`)}`, '')
+  if (meta.aliases !== undefined && meta.aliases.length > 0) {
+    lines.push(colors.bold('Aliases'), `  ${meta.aliases.join(', ')}`, '')
+  }
+  if (positionals.length > 0) {
+    lines.push(colors.bold('Arguments'))
+    lines.push(
+      ...table(
+        positionals.map(([name, def]) => [name, def.description ?? ''] as const),
+        colors,
+      ),
+    )
+    lines.push('')
+  }
+  const optionRows = options.map(([name, def]) => [optionLabel(name, def), describeOption(def)] as const)
+  optionRows.push(['-h, --help', 'Show this help'])
+  lines.push(colors.bold('Options'), ...table(optionRows, colors), '')
+  if (meta.details !== undefined) {
+    lines.push(typeof meta.details === 'function' ? meta.details(colors) : meta.details, '')
+  }
+  if (meta.examples !== undefined && meta.examples.length > 0) {
+    lines.push(colors.bold('Examples'), ...meta.examples.map(example => `  ${colors.dim('$')} ${example}`), '')
+  }
+  return lines.join('\n')
+}
+
+function optionLabel(name: string, def: ArgDef): string {
+  const short = aliasesOf(def)
+    .filter(alias => alias.length === 1)
+    .map(alias => `-${alias}, `)
+    .join('')
+  const flag = def.type === 'boolean' && def.default === true ? `--no-${name}` : `--${name}`
+  let value = ''
+  if (def.type === 'enum') value = ` <${(def.options ?? []).join('|')}>`
+  else if (def.type === 'string') value = ` <${def.valueHint ?? name}>`
+  return `${short}${flag}${value}`
+}
+
+function describeOption(def: ArgDef): string {
+  const description = def.description ?? ''
+  if (def.type === 'boolean') return description
+  return def.default === undefined || def.default === '' ? description : `${description} (default: ${def.default})`
+}
+
+/** Two aligned columns. */
+export function table(rows: readonly (readonly [string, string])[], colors: Colors): string[] {
+  const width = Math.max(0, ...rows.map(([left]) => left.length))
+  return rows.map(([left, right]) => `  ${colors.cyan(left.padEnd(width))}  ${right}`.trimEnd())
+}

package/src/commands/build.ts

@@ -0,0 +1,159 @@
+/**
+ * `znight build`: production build with Vite (the `znight()` plugin compiles the container).
+ * `--openapi[=path]` adds the `openapi()` plugin of `@znight/openapi` when the Vite config has none:
+ * the OpenAPI document is emitted after the bundle (`dist/openapi.json` by default), with the
+ * `servers` of `--openapi-prefix` (the `prefix` of `HttpPlugin`) when `@OpenApiDocument` declares none.
+ */
+import type { Plugin } from 'vite'
+import type { Command } from '../command.ts'
+import type { CliContext } from '../context.ts'
+import type { OpenApiVitePluginOptionsLike } from '../integrations/openapi.ts'
+
+import { statSync } from 'node:fs'
+
+import { defineCommand } from '../command.ts'
+import { CliError, UsageError } from '../errors.ts'
+import {
+  createOutputTracker,
+  formatBuildError,
+  runBuild,
+  type ViteConfigLoader,
+  type ViteLogLevel,
+} from '../integrations/vite.ts'
+import { formatBytes, formatDuration } from '../output.ts'
+import { displayPath, parseHttpPrefix, resolveRoot } from './shared.ts'
+
+/** `znight build` */
+export const buildCommand: Command = defineCommand({
+  meta: {
+    name: 'build',
+    description: 'Build the application for production (vite build)',
+    usage: '[options]',
+    examples: [
+      'znight build',
+      'znight build --mode staging',
+      'znight build --openapi   # also dist/openapi.json',
+      'znight build --openapi --openapi-prefix /api   # HttpPlugin.configure({ prefix: "/api" })',
+    ],
+    details: [
+      'Fails on any compiler error. With the defaults of the znight() plugin, src/main.ts is built to dist/main.js.',
+      '--openapi emits the OpenAPI document after the bundle (dist/openapi.json, or --openapi=<path>) with the',
+      'openapi() Vite plugin of @znight/openapi, unless the Vite config already registers it. When HttpPlugin',
+      'has a prefix, pass it with --openapi-prefix: it becomes the servers of the document (unless',
+      '@OpenApiDocument declares servers), like the document the application serves in "build" mode.',
+    ].join('\n'),
+  },
+  args: {
+    root: { type: 'string', valueHint: 'dir', description: 'Project root (default: the current directory)' },
+    config: { type: 'string', valueHint: 'file', description: 'Vite config file (default: vite.config.*)' },
+    mode: { type: 'string', default: 'production', description: 'Vite mode' },
+    'config-loader': {
+      type: 'enum',
+      options: ['bundle', 'runner', 'native'],
+      description: 'How Vite loads the config file (default: bundle)',
+    },
+    'log-level': {
+      type: 'enum',
+      options: ['info', 'warn', 'error', 'silent'],
+      default: 'info',
+      description: 'Vite log level',
+    },
+    openapi: {
+      type: 'boolean',
+      description: 'Also emit the OpenAPI document (dist/openapi.json, or --openapi=<path>; needs @znight/openapi)',
+    },
+    'openapi-prefix': {
+      type: 'string',
+      valueHint: 'path',
+      description: 'With --openapi: the HTTP prefix of HttpPlugin, the servers default of the document (/api)',
+    },
+  },
+  async run({ args, cli, rawArgs }) {
+    const root = resolveRoot(cli, args.root)
+    const openapi = openapiOption(rawArgs, args.openapi)
+    const prefix = parseHttpPrefix(args['openapi-prefix'], 'openapi-prefix')
+    if (prefix !== undefined && openapi === undefined) {
+      throw new UsageError('--openapi-prefix needs --openapi', [`znight build --openapi --openapi-prefix ${prefix}`])
+    }
+    const vite = await cli.services.loadVite(root)
+    const tracker = createOutputTracker(root)
+    const extra: Plugin[] = []
+    if (openapi !== undefined) {
+      const api = await cli.services.loadOpenApiVite(root)
+      const options: OpenApiVitePluginOptionsLike = {
+        ...(openapi === true ? {} : { output: openapi }),
+        ...(prefix === undefined ? {} : { prefix }),
+      }
+      const plugin = api.openapi(options)
+      extra.push(plugin)
+      const given = [
+        ...(options.output === undefined ? [] : [`--openapi=${options.output}`]),
+        ...(options.prefix === undefined ? [] : [`--openapi-prefix ${options.prefix}`]),
+      ]
+      if (given.length > 0) extra.push(ignoredOpenApiOptions(cli, plugin, given))
+    }
+    const started = performance.now()
+    try {
+      await runBuild(vite, {
+        root,
+        configFile: args.config,
+        configLoader: args['config-loader'] as ViteConfigLoader | undefined,
+        mode: args.mode,
+        logLevel: args['log-level'] as ViteLogLevel,
+        plugins: [tracker.plugin, ...extra],
+      })
+    } catch (error) {
+      // like the Vite CLI: the (enhanced) error message carries the location and the code frame
+      cli.reporter.logError(formatBuildError(error))
+      throw new CliError('Build failed', { cause: error })
+    }
+    const entry = tracker.entry()
+    const duration = formatDuration(performance.now() - started)
+    if (entry === undefined) {
+      cli.reporter.success(`Built in ${duration}`)
+      return 0
+    }
+    let size = ''
+    try {
+      size = ` ${cli.colors.dim(formatBytes(statSync(entry).size))}`
+    } catch {
+      size = ''
+    }
+    cli.reporter.success(`Built ${cli.colors.bold(displayPath(entry, cli.cwd))}${size} in ${duration}`)
+    cli.reporter.log(`  ${cli.colors.dim('run it with')} ${cli.colors.cyan('znight start')}`)
+    return 0
+  },
+})
+
+/** `--openapi` (`true`), `--openapi=<path>` (the path), or `undefined`. */
+function openapiOption(rawArgs: readonly string[], parsed: unknown): true | string | undefined {
+  for (const token of rawArgs) {
+    if (token.startsWith('--openapi=')) {
+      const value = token.slice('--openapi='.length)
+      if (value === 'false') return undefined
+      return value === '' || value === 'true' ? true : value
+    }
+    if (token === '--no-openapi') return undefined
+  }
+  return parsed === true || rawArgs.includes('--openapi') ? true : undefined
+}
+
+/**
+ * When the Vite config registers its own `openapi()`, that one emits the document and the copy of the
+ * CLI stays inactive: the options given on the command line (`given`) do not apply. Says so, instead
+ * of emitting a document without the requested output or prefix.
+ */
+function ignoredOpenApiOptions(cli: CliContext, plugin: Plugin, given: readonly string[]): Plugin {
+  return {
+    name: 'znight:cli-openapi-options',
+    apply: 'build',
+    configResolved(config) {
+      const active = config.plugins.find(candidate => candidate.name === plugin.name)
+      if (active === undefined || active === plugin) return
+      cli.reporter.warn(
+        `${given.join(' and ')} ignored: the openapi() plugin of the Vite config emits the document with its own options`,
+        ['set them on openapi() in the Vite config (openapi({ output, prefix })), or remove it from there'],
+      )
+    },
+  }
+}