@znight/cli 0.0.0-stage → 0.1.0

package/src/integrations/compiler.ts

@@ -0,0 +1,360 @@
+/**
+ * The `@znight/compiler` programmatic API (spec §6.2), loaded lazily: commands that do not compile
+ * (`new`, `g`, `start`) never load it. Commands use {@link CompilerApi} so tests can inject a fake.
+ *
+ * The CLI only relies on the documented shapes below (structural types, no type import from the
+ * compiler), so any `@znight/compiler` of the same major version works.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, relative, resolve } from 'node:path'
+
+import { CliError } from '../errors.ts'
+import { createColors } from '../output.ts'
+import { importFromProject } from './resolve.ts'
+
+/** Location of a diagnostic (`Diagnostic.location`, §6.2). */
+export interface DiagnosticLocation {
+  readonly file: string
+  readonly line: number
+  readonly column: number
+}
+
+/** A compiler diagnostic (§6.2). */
+export interface Diagnostic {
+  readonly code: string
+  readonly severity: 'error' | 'warning'
+  readonly message: string
+  readonly location?: DiagnosticLocation | undefined
+  readonly hints?: readonly string[] | undefined
+  readonly related?: readonly { readonly message: string; readonly location: DiagnosticLocation }[] | undefined
+}
+
+/** A string alias of Vite's `resolve.alias` (`CompileOptions.aliases` of the compiler). */
+export interface StringAliasLike {
+  readonly find: string
+  readonly replacement: string
+}
+
+/**
+ * Compiler options (`ZnightOptions`, §6.2, plus the `CompileOptions` the Vite plugin derives from the
+ * Vite config). The CLI reads `root`, `include` and `outFile`; the others are passed through.
+ */
+export interface ZnightOptions {
+  readonly root?: string | undefined
+  readonly include?: readonly string[] | undefined
+  readonly outFile?: string | undefined
+  /** String aliases of the Vite config (`resolve.alias`). */
+  readonly aliases?: readonly StringAliasLike[] | undefined
+  readonly [option: string]: unknown
+}
+
+/** What the CLI reads from a compile result (`CompileResult`, §6.2). */
+export interface CompileResultLike {
+  /** Content of the generated module (with errors: a module throwing them, or empty). */
+  readonly code: string
+  /** Absolute path of the generated module. */
+  readonly outFile: string
+  readonly diagnostics: readonly Diagnostic[]
+  readonly stats?: { readonly files?: number; readonly providers?: number; readonly durationMs?: number } | undefined
+  /** Files the result depends on (`createCompiler()` results). */
+  readonly watchFiles?: readonly string[] | undefined
+}
+
+/** Result of {@link CompilerApi.generate}. */
+export interface GenerateResultLike extends CompileResultLike {
+  /** Whether the generated module was written (its content changed). */
+  readonly written: boolean
+}
+
+/** Result of {@link CompilerApi.check}. */
+export interface CheckResultLike extends CompileResultLike {
+  /** The generated files on disk are missing or differ from what would be generated. */
+  readonly stale: boolean
+  /**
+   * The generated files that are missing or out of date (the module, and `znight.providers.json` in
+   * library mode). Empty when `stale` is `false`; empty or absent with `stale` when the compiler
+   * does not say which file is stale.
+   */
+  readonly staleFiles?: readonly string[] | undefined
+}
+
+/** Files changed since the previous compile of an {@link IncrementalCompiler}. */
+export interface CompilerChanges {
+  readonly changed?: readonly string[]
+  readonly added?: readonly string[]
+  readonly removed?: readonly string[]
+}
+
+/** Kind of a file system event (`ChangeKind` of the compiler). */
+export type ChangeKind = 'changed' | 'added' | 'removed'
+
+/** A compiler keeping its parse cache between compiles (`createCompiler()`), for watch mode. */
+export interface IncrementalCompiler {
+  /** Compiles (only `changes` are re-read, everything without) and writes the module when it changed. */
+  generate(changes?: CompilerChanges): Promise<GenerateResultLike>
+  /** Whether `file` is the generated module (watchers ignore it). */
+  isOutFile(file: string): boolean
+  /**
+   * Directories where a created or deleted source changes the scan (`includeRoots()` of the
+   * compiler: the bases of the `include` globs in the project and in every source library, known once
+   * compiled), to watch recursively. The project root when the compiler does not tell.
+   */
+  includeRoots(): readonly string[]
+  /**
+   * Whether a file event can change the next compile (`isRelevantChange()` of the compiler): `watched`
+   * are the `watchFiles` of the last compile, `roots` its {@link includeRoots}. When the compiler does
+   * not tell, every event but the generated module is.
+   */
+  isRelevantChange(kind: ChangeKind, file: string, watched: ReadonlySet<string>, roots: readonly string[]): boolean
+}
+
+/** Options of {@link CompilerApi.formatDiagnostics}. */
+export interface FormatDiagnosticsOptions {
+  readonly color?: boolean
+  readonly cwd?: string
+  /** Append the summary line (`Build failed with 2 errors`). */
+  readonly summary?: boolean
+}
+
+/** Options read from `znight.config.*` (`loadZnightConfig()`, §6.3). */
+export interface ZnightConfigLike {
+  /** The config file, `undefined` when the project has none. */
+  readonly file: string | undefined
+  /** Its options, `root` resolved against the config file directory. */
+  readonly options: ZnightOptions
+}
+
+/** The part of `@znight/compiler` used by the CLI. */
+export interface CompilerApi {
+  /** Compiles and writes the generated module when its content changed (`generate()`). */
+  generate(options: ZnightOptions): Promise<GenerateResultLike>
+  /** Compiles without writing and compares with the files on disk (`generate({ check: true })`). */
+  check(options: ZnightOptions): Promise<CheckResultLike>
+  /** An incremental compiler (`createCompiler()`). */
+  createIncremental(options: ZnightOptions): IncrementalCompiler
+  /** Code frames for diagnostics (`formatDiagnostics()`). */
+  formatDiagnostics(diagnostics: readonly Diagnostic[], options?: FormatDiagnosticsOptions): string
+  /**
+   * The options of `znight.config.*` (or of the file named by `ZNIGHT_CONFIG`) in `root`
+   * (`loadZnightConfig()`). Absent for compilers without it.
+   */
+  loadConfig?(root: string): Promise<ZnightConfigLike>
+}
+
+/**
+ * Not a literal in `import()`: the CLI type-checks and bundles without the compiler (an optional
+ * peer dependency), whose version is the project's.
+ */
+const COMPILER_PACKAGE: string = '@znight/compiler'
+
+/** A compile result as returned by any `@znight/compiler` version (extra fields are optional). */
+interface ModuleResult extends CompileResultLike {
+  /** The disk copy of the module (`code` before it existed; they differ in `build` mode only). */
+  readonly diskCode?: string
+  readonly written?: readonly string[]
+  readonly stale?: boolean
+  /** The stale generated files (check mode), when the compiler tells. */
+  readonly staleFiles?: readonly string[]
+  /** Library mode: `znight.providers.json` (`library` of a `CompileResult`). */
+  readonly library?: { readonly file?: unknown; readonly content?: unknown } | undefined
+}
+
+/** The parts of a `ZnightCompiler` (`createCompiler()`) the CLI uses; all optional. */
+export interface ModuleIncrementalCompiler {
+  generate?: (changes?: CompilerChanges, options?: { check?: boolean }) => Promise<ModuleResult>
+  isOutFile?: (file: string) => boolean
+}
+
+/** The shape of the `@znight/compiler` module (every export optional: partial versions are adapted). */
+export interface CompilerModule {
+  compile?: (options?: ZnightOptions) => Promise<ModuleResult>
+  generate?: (options?: ZnightOptions & { check?: boolean }) => Promise<ModuleResult>
+  createCompiler?: (options?: ZnightOptions) => ModuleIncrementalCompiler
+  formatDiagnostics?: (diagnostics: readonly Diagnostic[], options?: FormatDiagnosticsOptions) => string
+  loadZnightConfig?: (cwd?: string) => Promise<ZnightConfigLike>
+  /** The watch roots of a compiler (`includeRoots(compiler)`). */
+  includeRoots?: (compiler: ModuleIncrementalCompiler) => readonly string[]
+  /** Whether a file event can change the next compile of a compiler (`isRelevantChange(compiler, ...)`). */
+  isRelevantChange?: (
+    compiler: ModuleIncrementalCompiler,
+    kind: ChangeKind,
+    file: string,
+    watched: ReadonlySet<string>,
+    roots: readonly string[],
+  ) => boolean
+}
+
+/**
+ * Loads `@znight/compiler` as installed in the project (falls back to the CLI's own peer) and adapts
+ * it to {@link CompilerApi}.
+ */
+export async function loadCompiler(root: string): Promise<CompilerApi> {
+  let module: CompilerModule
+  try {
+    module = (await importFromProject(COMPILER_PACKAGE, root, () => import(COMPILER_PACKAGE))) as CompilerModule
+  } catch (error) {
+    throw new CliError('Cannot load @znight/compiler', {
+      cause: error,
+      hints: ['install it in your project: npm install -D @znight/compiler vite'],
+    })
+  }
+  return adaptCompilerModule(module)
+}
+
+function readText(file: string): string | undefined {
+  try {
+    return readFileSync(file, 'utf8')
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Adapts a loaded compiler module: `generate()` / `generate({ check })` / `createCompiler()` when
+ * available, otherwise the same behaviour built on `compile()`.
+ */
+export function adaptCompilerModule(module: CompilerModule): CompilerApi {
+  const { compile, generate, createCompiler, loadZnightConfig } = module
+  if (typeof compile !== 'function' && typeof generate !== 'function') {
+    throw new CliError('This version of @znight/compiler exposes neither compile() nor generate()', {
+      hints: ['upgrade @znight/compiler to the version of @znight/cli'],
+    })
+  }
+  const format = module.formatDiagnostics ?? fallbackFormatDiagnostics
+
+  /** Pure compile: `compile()`, else `generate({ check: true })` (never writes). */
+  const compileOnly = (options: ZnightOptions): Promise<ModuleResult> =>
+    typeof compile === 'function'
+      ? compile(options)
+      : (generate as NonNullable<CompilerModule['generate']>)({ ...options, check: true })
+
+  /** Write-if-changed on top of a compile result, when the compiler did not write itself. */
+  const written = (result: ModuleResult, before: string | undefined): GenerateResultLike => ({
+    ...result,
+    written: Array.isArray(result.written) ? result.written.length > 0 : before !== readText(result.outFile),
+  })
+
+  const generateOnce = async (options: ZnightOptions): Promise<GenerateResultLike> => {
+    if (typeof generate === 'function') {
+      const before = readText(resolveOutFile(options))
+      return written(await generate(options), before)
+    }
+    const result = await compileOnly(options)
+    const changed = !hasErrors(result.diagnostics) && writeIfChanged(result.outFile, result.diskCode ?? result.code)
+    return { ...result, written: changed }
+  }
+
+  return {
+    generate: generateOnce,
+    check: async options => {
+      const result =
+        typeof generate === 'function' ? await generate({ ...options, check: true }) : await compileOnly(options)
+      const staleFiles = Array.isArray(result.staleFiles) ? result.staleFiles : staleOutputs(result)
+      const stale = typeof result.stale === 'boolean' ? result.stale : staleFiles.length > 0
+      return { ...result, stale, staleFiles: stale ? staleFiles : [] }
+    },
+    createIncremental: options => {
+      const compiler = typeof createCompiler === 'function' ? createCompiler(options) : undefined
+      const incremental = compiler?.generate
+      const outFile = resolveOutFile(options)
+      const isOutFile = (file: string): boolean =>
+        typeof compiler?.isOutFile === 'function' ? compiler.isOutFile(file) : resolve(file) === outFile
+      const { includeRoots, isRelevantChange } = module
+      return {
+        generate: async changes => {
+          if (compiler === undefined || typeof incremental !== 'function') return generateOnce(options)
+          const before = readText(outFile)
+          return written(await incremental.call(compiler, changes), before)
+        },
+        isOutFile,
+        includeRoots: () =>
+          compiler !== undefined && typeof includeRoots === 'function'
+            ? includeRoots(compiler)
+            : [resolve(options.root ?? '.')],
+        isRelevantChange: (kind, file, watched, roots) =>
+          compiler !== undefined && typeof isRelevantChange === 'function'
+            ? isRelevantChange(compiler, kind, file, watched, roots)
+            : !isOutFile(file),
+      }
+    },
+    formatDiagnostics: (diagnostics, options) => format(diagnostics, options),
+    ...(typeof loadZnightConfig === 'function'
+      ? { loadConfig: (root: string): Promise<ZnightConfigLike> => loadZnightConfig(root) }
+      : {}),
+  }
+}
+
+/**
+ * The generated files of a compile result that differ from the disk: the module, and
+ * `znight.providers.json` in library mode. None with errors (nothing would be written).
+ */
+function staleOutputs(result: ModuleResult): string[] {
+  if (hasErrors(result.diagnostics)) return []
+  const outputs: { file: string; content: string }[] = [
+    { file: result.outFile, content: result.diskCode ?? result.code },
+  ]
+  const { file, content } = result.library ?? {}
+  if (typeof file === 'string' && typeof content === 'string') outputs.push({ file, content })
+  return outputs.filter(output => readText(output.file) !== output.content).map(output => output.file)
+}
+
+/** Default `outFile` of the compiler (§6.2). */
+export const DEFAULT_OUT_FILE = 'src/.znight/container.generated.ts'
+
+/** Absolute path of the generated module for `options`. */
+export function resolveOutFile(options: ZnightOptions): string {
+  return resolve(options.root ?? '.', options.outFile ?? DEFAULT_OUT_FILE)
+}
+
+/** Whether a list of diagnostics contains an error. */
+export function hasErrors(diagnostics: readonly Diagnostic[]): boolean {
+  return diagnostics.some(diagnostic => diagnostic.severity === 'error')
+}
+
+/** Writes `content` to `file` unless it already has that exact content. Returns whether it wrote. */
+export function writeIfChanged(file: string, content: string): boolean {
+  if (existsSync(file) && readFileSync(file, 'utf8') === content) return false
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, content)
+  return true
+}
+
+/**
+ * Plain formatter used when the installed compiler has no `formatDiagnostics()`:
+ *
+ * ```
+ * ✗ ZNIGHT001: Missing provider for 'EmailService' required by NotificationService
+ *   --> src/notification/notification.service.ts:12:5
+ *   = hint: Add @Injectable() to EmailService
+ * ```
+ */
+export function fallbackFormatDiagnostics(
+  diagnostics: readonly Diagnostic[],
+  options: FormatDiagnosticsOptions = {},
+): string {
+  const colors = createColors(options.color === true)
+  const blocks: string[] = []
+  for (const diagnostic of diagnostics) {
+    const isError = diagnostic.severity === 'error'
+    const head = isError
+      ? colors.red(`✗ ${diagnostic.code}: ${diagnostic.message}`)
+      : colors.yellow(`! ${diagnostic.code}: ${diagnostic.message}`)
+    const lines = [colors.bold(head)]
+    if (diagnostic.location !== undefined) {
+      lines.push(`  ${colors.cyan('-->')} ${formatLocation(diagnostic.location, options.cwd)}`)
+    }
+    for (const hint of diagnostic.hints ?? []) lines.push(`  ${colors.dim('=')} ${colors.bold('hint:')} ${hint}`)
+    for (const related of diagnostic.related ?? []) {
+      lines.push(
+        `  ${colors.dim('=')} ${colors.bold('note:')} ${related.message} (${formatLocation(related.location, options.cwd)})`,
+      )
+    }
+    blocks.push(lines.join('\n'))
+  }
+  return blocks.join('\n\n')
+}
+
+function formatLocation(location: { file: string; line: number; column: number }, cwd: string | undefined): string {
+  const file = cwd === undefined ? location.file : relative(cwd, location.file).replaceAll('\\', '/')
+  return `${file}:${location.line}:${location.column}`
+}

package/src/integrations/openapi.ts

@@ -0,0 +1,97 @@
+/**
+ * `@znight/openapi`, loaded lazily from the project (an optional peer dependency): `znight openapi`
+ * uses its emission API (`@znight/openapi/emit`), `znight build --openapi` its Vite plugin
+ * (`@znight/openapi/vite`). Commands use the structural types below, so tests can inject fakes.
+ */
+import type { Plugin } from 'vite'
+import type { Diagnostic, ZnightOptions } from './compiler.ts'
+
+import { CliError } from '../errors.ts'
+import { importFromProject } from './resolve.ts'
+
+/** Options of `emitOpenApi()` (`@znight/openapi/emit`). */
+export interface OpenApiEmitOptionsLike {
+  readonly root: string
+  readonly output: readonly string[]
+  readonly check?: boolean
+  readonly prefix?: string
+  readonly runtime?: 'auto' | 'node' | 'bun'
+  readonly converters?: string
+  readonly config?: string
+  readonly configLoader?: string
+  readonly compilerOptions?: ZnightOptions
+}
+
+/** A warning of the assembly. */
+export interface OpenApiWarningLike {
+  readonly code: string
+  readonly message: string
+}
+
+/** What the CLI reads from the result of `emitOpenApi()`. */
+export interface OpenApiEmitResultLike {
+  readonly ok: boolean
+  readonly written: readonly string[]
+  readonly stale: boolean
+  readonly staleFiles: readonly string[]
+  readonly diagnostics: readonly Diagnostic[]
+  readonly warnings: readonly OpenApiWarningLike[]
+  readonly outputs: readonly string[]
+  readonly runtime: 'node' | 'bun'
+  readonly document?: { readonly paths?: Readonly<Record<string, object>> } | undefined
+}
+
+/** `@znight/openapi/emit`. */
+export interface OpenApiEmitApi {
+  emitOpenApi(options: OpenApiEmitOptionsLike): Promise<OpenApiEmitResultLike>
+}
+
+/** Options of the `openapi()` Vite plugin. */
+export interface OpenApiVitePluginOptionsLike {
+  readonly output?: string
+  /** HTTP prefix (`servers` default when `@OpenApiDocument` declares none). */
+  readonly prefix?: string
+}
+
+/** `@znight/openapi/vite`. */
+export interface OpenApiViteApi {
+  openapi(options?: OpenApiVitePluginOptionsLike): Plugin
+}
+
+/** Not literals in `import()`: the CLI builds without `@znight/openapi` (an optional peer). */
+const EMIT_MODULE: string = '@znight/openapi/emit'
+const VITE_MODULE: string = '@znight/openapi/vite'
+
+const MISSING_HINTS = ['install it in your project: npm install @znight/openapi']
+
+/** Loads `@znight/openapi/emit` as installed in the project. */
+export async function loadOpenApiEmit(root: string): Promise<OpenApiEmitApi> {
+  let module: Partial<OpenApiEmitApi>
+  try {
+    module = (await importFromProject(EMIT_MODULE, root, () => import(EMIT_MODULE))) as Partial<OpenApiEmitApi>
+  } catch (error) {
+    throw new CliError('Cannot load @znight/openapi', { cause: error, hints: MISSING_HINTS })
+  }
+  if (typeof module.emitOpenApi !== 'function') {
+    throw new CliError('This version of @znight/openapi has no emitOpenApi()', {
+      hints: ['upgrade @znight/openapi to the version of @znight/cli'],
+    })
+  }
+  return module as OpenApiEmitApi
+}
+
+/** Loads `@znight/openapi/vite` as installed in the project. */
+export async function loadOpenApiVite(root: string): Promise<OpenApiViteApi> {
+  let module: Partial<OpenApiViteApi>
+  try {
+    module = (await importFromProject(VITE_MODULE, root, () => import(VITE_MODULE))) as Partial<OpenApiViteApi>
+  } catch (error) {
+    throw new CliError('Cannot load @znight/openapi', { cause: error, hints: MISSING_HINTS })
+  }
+  if (typeof module.openapi !== 'function') {
+    throw new CliError('This version of @znight/openapi has no openapi() Vite plugin', {
+      hints: ['upgrade @znight/openapi to the version of @znight/cli'],
+    })
+  }
+  return module as OpenApiViteApi
+}

package/src/integrations/process.ts

@@ -0,0 +1,180 @@
+/**
+ * Child processes: the application (`znight dev` / `znight start`) and tools (`git`, package
+ * managers). Behind {@link ProcessService} so that tests can use fake processes.
+ */
+import { type ChildProcess, spawn as nodeSpawn } from 'node:child_process'
+import { constants } from 'node:os'
+
+/** How a child process ended. */
+export interface ExitStatus {
+  /** Exit code, `null` when killed by a signal or when the process could not start. */
+  readonly code: number | null
+  readonly signal: NodeJS.Signals | null
+  /** Spawn failure (`ENOENT`...). */
+  readonly error?: Error | undefined
+}
+
+/** A running child process. */
+export interface ChildHandle {
+  readonly pid: number | undefined
+  /** Sends a signal (to its process group when it runs detached). Returns `false` when it already exited. */
+  kill(signal: NodeJS.Signals): boolean
+  /** Resolves once the process exited (never rejects). */
+  readonly exited: Promise<ExitStatus>
+}
+
+/** Options of {@link ProcessService.spawn}. */
+export interface SpawnOptions {
+  readonly cwd: string
+  readonly env: Readonly<Record<string, string | undefined>>
+  /** Default `'inherit'`. */
+  readonly stdio?: 'inherit' | 'ignore'
+  /**
+   * POSIX only: run the process in its own process group, so that a terminal Ctrl+C reaches the CLI
+   * only (the CLI then forwards exactly one signal). The process is killed when the CLI exits.
+   */
+  readonly detached?: boolean
+}
+
+/** Result of {@link ProcessService.run}. */
+export interface RunResult extends ExitStatus {
+  readonly stdout: string
+  readonly stderr: string
+}
+
+/** Options of {@link ProcessService.run}. */
+export interface RunOptions {
+  readonly cwd: string
+  readonly env: Readonly<Record<string, string | undefined>>
+}
+
+/**
+ * Replaces the current process image (`execve(2)`) after changing the working directory to `cwd`.
+ * `args[0]` is the program name. Never returns on success.
+ */
+export type ExecveFunction = (
+  file: string,
+  args: readonly string[],
+  env: Readonly<Record<string, string>>,
+  cwd: string,
+) => void
+
+/** Process primitives used by the commands. */
+export interface ProcessService {
+  spawn(command: string, args: readonly string[], options: SpawnOptions): ChildHandle
+  /** Runs a command to completion, capturing its output. */
+  run(command: string, args: readonly string[], options: RunOptions): Promise<RunResult>
+  /** `process.execve` when the runtime supports it (POSIX). */
+  readonly execve?: ExecveFunction | undefined
+}
+
+const detachedChildren = new Set<ChildProcess>()
+let exitHookInstalled = false
+
+function killDetachedChildren(): void {
+  for (const child of detachedChildren) {
+    killTree(child, 'SIGKILL', true)
+  }
+}
+
+function killTree(child: ChildProcess, signal: NodeJS.Signals, detached: boolean): boolean {
+  if (child.exitCode !== null || child.signalCode !== null) return false
+  if (detached && child.pid !== undefined && process.platform !== 'win32') {
+    try {
+      process.kill(-child.pid, signal)
+      return true
+    } catch {
+      // the group is gone: fall back to the process itself
+    }
+  }
+  return child.kill(signal)
+}
+
+function cleanEnv(env: Readonly<Record<string, string | undefined>>): Record<string, string> {
+  const result: Record<string, string> = {}
+  for (const [key, value] of Object.entries(env)) {
+    if (value !== undefined) result[key] = value
+  }
+  return result
+}
+
+/** Starts a process with `node:child_process`. */
+export function spawnProcess(command: string, args: readonly string[], options: SpawnOptions): ChildHandle {
+  const detached = options.detached === true && process.platform !== 'win32'
+  const child = nodeSpawn(command, [...args], {
+    cwd: options.cwd,
+    env: cleanEnv(options.env),
+    stdio: options.stdio ?? 'inherit',
+    detached,
+    windowsHide: true,
+  })
+  if (detached) {
+    detachedChildren.add(child)
+    if (!exitHookInstalled) {
+      exitHookInstalled = true
+      process.on('exit', killDetachedChildren)
+    }
+  }
+  const exited = new Promise<ExitStatus>(resolve => {
+    child.once('error', error => {
+      detachedChildren.delete(child)
+      resolve({ code: null, signal: null, error })
+    })
+    child.once('exit', (code, signal) => {
+      detachedChildren.delete(child)
+      resolve({ code, signal })
+    })
+  })
+  return {
+    pid: child.pid,
+    kill: signal => killTree(child, signal, detached),
+    exited,
+  }
+}
+
+/** Runs a command to completion with `node:child_process`, capturing stdout and stderr. */
+export function runProcess(command: string, args: readonly string[], options: RunOptions): Promise<RunResult> {
+  return new Promise<RunResult>(resolve => {
+    const child = nodeSpawn(command, [...args], {
+      cwd: options.cwd,
+      env: cleanEnv(options.env),
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+      // package managers are `.cmd` shims on Windows
+      shell: process.platform === 'win32',
+    })
+    let stdout = ''
+    let stderr = ''
+    child.stdout?.setEncoding('utf8').on('data', (chunk: string) => {
+      stdout += chunk
+    })
+    child.stderr?.setEncoding('utf8').on('data', (chunk: string) => {
+      stderr += chunk
+    })
+    child.once('error', error => resolve({ code: null, signal: null, error, stdout, stderr }))
+    child.once('close', (code, signal) => resolve({ code, signal, stdout, stderr }))
+  })
+}
+
+/** The default {@link ProcessService}. */
+export function createProcessService(): ProcessService {
+  const execve = (process as { execve?: (file: string, args: string[], env: Record<string, string>) => void }).execve
+  return {
+    spawn: spawnProcess,
+    run: runProcess,
+    execve:
+      typeof execve === 'function' && process.platform !== 'win32'
+        ? (file, args, env, cwd) => {
+            process.chdir(cwd)
+            execve.call(process, file, [...args], { ...env })
+          }
+        : undefined,
+  }
+}
+
+/** Exit code of the CLI mirroring a child's exit status (`128 + n` for signals, like shells). */
+export function exitCodeOf(status: ExitStatus): number {
+  if (status.code !== null) return status.code
+  if (status.signal !== null) return 128 + (constants.signals[status.signal] ?? 1)
+  return 1
+}