@znight/cli 0.0.0-stage → 0.1.0

package/src/commands/dev.ts

@@ -0,0 +1,249 @@
+/**
+ * `znight dev`: Vite build in watch mode (no Vite dev server) and a full restart of the application
+ * process after every successful rebuild — no partial hot replacement of providers: a restart is
+ * fast and always consistent. A failed build keeps the last good process running, and so does a
+ * failed compilation: in watch mode the `znight()` plugin does not fail the build (the bundle
+ * contains a module throwing the diagnostics), so its result (`plugin.api.result`) is checked
+ * before restarting.
+ */
+import type { Command } from '../command.ts'
+import type { CliContext } from '../context.ts'
+import type { Diagnostic } from '../integrations/compiler.ts'
+import type { BuildWatcher, ViteConfigLoader, ViteLogLevel, WatcherEvent } from '../integrations/vite.ts'
+
+import { resolve } from 'node:path'
+
+import { defineCommand } from '../command.ts'
+import { ORPHAN_GUARD_POLL_MS, orphanGuard } from '../dev/orphan.ts'
+import { AppSupervisor } from '../dev/supervisor.ts'
+import { CliError } from '../errors.ts'
+import { fallbackFormatDiagnostics } from '../integrations/compiler.ts'
+import { exitCodeOf } from '../integrations/process.ts'
+import { createOutputTracker, formatBuildError, watchBuild } from '../integrations/vite.ts'
+import { formatDuration, plural } from '../output.ts'
+import { type RuntimeOption, resolveRuntime, runtimeArguments, runtimeExecutable } from '../runtime.ts'
+import { displayPath, onTermination, parseNonNegativeInteger, resolveRoot } from './shared.ts'
+
+/** Clears the terminal and its scrollback. */
+const CLEAR_SCREEN = '\x1b[2J\x1b[3J\x1b[H'
+
+/** `znight dev` */
+export const devCommand: Command = defineCommand({
+  meta: {
+    name: 'dev',
+    description: 'Build in watch mode and restart the application after every successful rebuild',
+    usage: '[options] [-- <application arguments>]',
+    examples: ['znight dev', 'znight dev --runtime bun --clear', 'znight dev --inspect -- --verbose'],
+    details: [
+      'Uses "vite build --watch" with the project Vite config (the znight() plugin regenerates the container).',
+      'On every successful build the application receives SIGTERM, gets --kill-timeout ms to stop gracefully',
+      '(then SIGKILL), and a new process starts. A failed build or compilation (ZNIGHT errors) keeps the',
+      'last good process running.',
+    ].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: 'development', description: 'Vite mode' },
+    'config-loader': {
+      type: 'enum',
+      options: ['bundle', 'runner', 'native'],
+      description: 'How Vite loads the config file (default: bundle)',
+    },
+    runtime: {
+      type: 'enum',
+      options: ['auto', 'node', 'bun'],
+      default: 'auto',
+      description: 'Runtime of the application (auto: the runtime running the CLI)',
+    },
+    entry: { type: 'string', valueHint: 'file', description: 'File to run (default: the entry chunk of the build)' },
+    inspect: { type: 'boolean', description: 'Start the application with --inspect (debugger)' },
+    clear: { type: 'boolean', description: 'Clear the screen before each rebuild' },
+    debounce: { type: 'string', valueHint: 'ms', default: '100', description: 'Delay before restarting after a build' },
+    'kill-timeout': {
+      type: 'string',
+      valueHint: 'ms',
+      default: '5000',
+      description: 'Time the application gets to stop after SIGTERM before SIGKILL',
+    },
+    'log-level': {
+      type: 'enum',
+      options: ['info', 'warn', 'error', 'silent'],
+      default: 'warn',
+      description: 'Vite log level',
+    },
+  },
+  async run({ args, cli, passthrough }) {
+    const root = resolveRoot(cli, args.root)
+    const debounceMs = parseNonNegativeInteger(args.debounce, 'debounce', 100)
+    const killTimeoutMs = parseNonNegativeInteger(args['kill-timeout'], 'kill-timeout', 5000)
+    const runtime = resolveRuntime(args.runtime as RuntimeOption, cli.runtime)
+    const executable = runtimeExecutable(runtime, cli.runtime, cli.env)
+    if (executable === undefined) {
+      throw new CliError(`Cannot find "${runtime}" in PATH`, { hints: ['install it, or choose another --runtime'] })
+    }
+    const logLevel = args['log-level'] as ViteLogLevel
+    const { colors, reporter } = cli
+    // before Vite runs: its build sets process.env.NODE_ENV (to "production") when it is not set
+    const env = { ...cli.env }
+    // the application runs detached: it stops by itself when the CLI dies without stopping it (kill -9)
+    const guard = orphanGuard(runtime, { parentPid: process.pid, pollMs: ORPHAN_GUARD_POLL_MS, killTimeoutMs })
+    const runtimeArgs = runtimeArguments(runtime, [
+      ...(guard?.args ?? []),
+      ...(args.inspect === true ? ['--inspect'] : []),
+    ])
+    const vite = await cli.services.loadVite(root)
+    const tracker = createOutputTracker(root)
+    let entry: string | undefined
+
+    const supervisor = new AppSupervisor({
+      debounceMs,
+      killTimeoutMs,
+      spawn: () => {
+        const file = entry ?? resolve(root, 'dist/main.js')
+        return cli.services.processes.spawn(executable, [...runtimeArgs, file, ...passthrough], {
+          cwd: root,
+          env: { ...env, ...guard?.env, NODE_ENV: env['NODE_ENV'] ?? 'development' },
+          detached: true,
+        })
+      },
+      events: {
+        onStart: (child, restart) => {
+          const file = displayPath(entry ?? resolve(root, 'dist/main.js'), cli.cwd)
+          reporter.info(
+            `${restart ? 'Restarted' : 'Started'} ${colors.bold(file)} ${colors.dim(`(${runtime}, pid ${child.pid ?? '?'})`)}`,
+          )
+        },
+        onStop: (_status, forced) => {
+          if (forced) reporter.warn(`The application did not stop within ${killTimeoutMs}ms: killed`)
+        },
+        onExit: status => {
+          if (status.error !== undefined) {
+            reporter.error(`Cannot start ${runtime}: ${status.error.message}`)
+            return
+          }
+          const code = exitCodeOf(status)
+          const message = `The application exited with code ${code}${status.signal === null ? '' : ` (${status.signal})`}`
+          if (code === 0) reporter.info(`${message}. Waiting for changes...`)
+          else reporter.error(`${message}. Waiting for changes...`)
+        },
+        onError: error =>
+          reporter.error(`Cannot start the application: ${error instanceof Error ? error.message : String(error)}`),
+      },
+    })
+
+    const state = { failed: false, first: true, started: 0 }
+    const onEvent = (event: WatcherEvent): void => {
+      switch (event.code) {
+        case 'START':
+          state.failed = false
+          state.started = performance.now()
+          if (!state.first) {
+            if (args.clear === true && cli.stdout.isTTY === true) cli.stdout.write(CLEAR_SCREEN)
+            reporter.info(colors.dim('Change detected, rebuilding...'))
+          }
+          break
+        case 'ERROR':
+          state.failed = true
+          state.first = false
+          // Vite closes the build of BUNDLE_END itself, not the one of ERROR
+          void Promise.resolve()
+            .then(() => event.result?.close())
+            .catch(() => undefined)
+          // Vite logs build errors itself, unless it is silenced
+          if (logLevel === 'silent') reporter.logError(formatBuildError(event.error))
+          reporter.error(
+            `Build failed. ${supervisor.running ? 'The last good build keeps running. ' : ''}Waiting for changes...`,
+          )
+          break
+        case 'END': {
+          state.first = false
+          if (state.failed) break
+          // the bundle was written, but with a failed compile it throws the diagnostics at startup
+          const compile = tracker.compile()
+          if (compile !== undefined && !compile.ok) {
+            // a restart still pending for a previous build would run this broken output
+            supervisor.cancelRestart()
+            const errors = compile.diagnostics.filter(diagnostic => diagnostic.severity === 'error').length
+            // the znight() plugin prints the diagnostics through the Vite logger, unless it is silenced
+            const printed = logLevel === 'silent' ? printDiagnostics(cli, root, compile.diagnostics) : Promise.resolve()
+            void printed.then(() =>
+              reporter.error(
+                `Compilation failed with ${plural(errors, 'error')}. ${supervisor.running ? 'The last good build keeps running. ' : ''}Waiting for changes...`,
+              ),
+            )
+            break
+          }
+          entry = args.entry === undefined ? (tracker.entry() ?? entry) : resolve(root, args.entry)
+          reporter.success(`Built in ${formatDuration(performance.now() - (tracker.startedAt() ?? state.started))}`)
+          supervisor.scheduleRestart()
+          break
+        }
+        default:
+          break
+      }
+    }
+
+    reporter.info(
+      `${colors.bold('znight dev')} ${colors.dim(`v${cli.version}`)} — vite build --watch, ${runtime} runtime`,
+    )
+    let watcher: BuildWatcher
+    try {
+      watcher = await watchBuild(vite, {
+        root,
+        configFile: args.config,
+        configLoader: args['config-loader'] as ViteConfigLoader | undefined,
+        mode: args.mode,
+        logLevel,
+        plugins: [tracker.plugin],
+      })
+    } catch (error) {
+      if (error instanceof CliError) throw error
+      // configuration errors (the config file does not load, invalid options...)
+      reporter.logError(formatBuildError(error))
+      throw new CliError('Cannot start the Vite build', { cause: error })
+    }
+    watcher.on('event', onEvent)
+    return waitForTermination(cli, watcher, supervisor)
+  },
+})
+
+/** Prints compiler diagnostics with the project's `formatDiagnostics()` (a built-in formatter otherwise). */
+async function printDiagnostics(cli: CliContext, root: string, diagnostics: readonly Diagnostic[]): Promise<void> {
+  if (diagnostics.length === 0) return
+  const options = { color: cli.colors.isColorSupported, cwd: root, summary: false }
+  let text: string
+  try {
+    text = (await cli.services.loadCompiler(root)).formatDiagnostics(diagnostics, options)
+  } catch {
+    text = fallbackFormatDiagnostics(diagnostics, options)
+  }
+  cli.reporter.logError(text.trimEnd())
+}
+
+function waitForTermination(cli: CliContext, watcher: BuildWatcher, supervisor: AppSupervisor): Promise<number> {
+  return new Promise<number>(resolveExit => {
+    const dispose = onTermination(
+      cli,
+      signal => {
+        // SIGHUP: the terminal is gone, nothing can be printed
+        if (signal !== 'SIGHUP') cli.reporter.info(cli.colors.dim('Stopping... (press Ctrl+C again to force)'))
+        void (async () => {
+          try {
+            await watcher.close()
+          } finally {
+            // the application stops gracefully on SIGINT or SIGTERM
+            await supervisor.stop(signal === 'SIGINT' ? 'SIGINT' : 'SIGTERM')
+            dispose()
+            resolveExit(0)
+          }
+        })()
+      },
+      () => {
+        supervisor.kill()
+        dispose()
+        resolveExit(130)
+      },
+    )
+  })
+}

package/src/commands/generate.ts

@@ -0,0 +1,304 @@
+/**
+ * `znight generate`: writes the DI container module (`src/.znight/container.generated.ts`) with the
+ * compiler, checks that it is up to date (`--check`, for CI) or keeps it up to date (`--watch`, for
+ * `tsc --watch` and editors).
+ */
+import type { Command } from '../command.ts'
+import type { CliContext } from '../context.ts'
+import type {
+  CheckResultLike,
+  CompileResultLike,
+  CompilerApi,
+  GenerateResultLike,
+  IncrementalCompiler,
+  ZnightConfigLike,
+  ZnightOptions,
+} from '../integrations/compiler.ts'
+
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { defineCommand } from '../command.ts'
+import { CliError, errorMessage } from '../errors.ts'
+import { hasErrors } from '../integrations/compiler.ts'
+import { findViteConfig, readZnightPluginOptions, type ViteConfigLoader } from '../integrations/vite.ts'
+import {
+  changeKind,
+  classifyChanges,
+  realPath,
+  TargetWatchers,
+  toPosixPath,
+  watchTargets,
+} from '../integrations/watch.ts'
+import { formatDuration, plural } from '../output.ts'
+import { displayPath, onTermination, resolveRoot } from './shared.ts'
+
+/** `znight generate` */
+export const generateCommand: Command = defineCommand({
+  meta: {
+    name: 'generate',
+    description: 'Generate the dependency injection container (src/.znight/container.generated.ts)',
+    usage: '[options]',
+    examples: ['znight generate', 'znight generate --check   # in CI, before tsc', 'znight generate --watch'],
+    details: [
+      'The compiler options are read from znight.config.* (or the file named by ZNIGHT_CONFIG), the file',
+      'shared with the Bun preload; without one, from the znight() plugin of vite.config.ts, so that the',
+      'generated file is the same as the one of the Vite build. --config reads the given Vite config.',
+      '"znight generate <schematic> <name>" is an alias of "znight g <schematic> <name>".',
+    ].join('\n'),
+  },
+  args: {
+    check: {
+      type: 'boolean',
+      description: 'Do not write: exit with code 1 when the generated file is missing or out of date',
+    },
+    watch: { type: 'boolean', alias: 'w', description: 'Regenerate on every change' },
+    root: { type: 'string', valueHint: 'dir', description: 'Project root (default: the current directory)' },
+    config: {
+      type: 'string',
+      valueHint: 'file',
+      description: 'Vite config file to read the znight() options from (instead of znight.config.*)',
+    },
+    'config-loader': {
+      type: 'enum',
+      options: ['bundle', 'runner', 'native'],
+      description: 'How Vite loads the config file (default: bundle)',
+    },
+  },
+  async run({ args, cli }) {
+    const root = resolveRoot(cli, args.root)
+    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)
+    if (args.check === true) return check(cli, compiler, options)
+    if (args.watch === true) return watch(cli, compiler, options)
+    const result = await generateOnce(cli, compiler, options)
+    return hasErrors(result.diagnostics) ? 1 : 0
+  },
+})
+
+/**
+ * The compiler options, with `root`: those of `znight.config.*` when the project has one (unless a
+ * Vite config is given with `--config`), else those of `znight()` in the Vite config (when exposed),
+ * else the defaults.
+ */
+export async function compilerOptions(
+  cli: CliContext,
+  compiler: CompilerApi,
+  root: string,
+  configFile: string | undefined,
+  configLoader: ViteConfigLoader | undefined,
+): Promise<ZnightOptions> {
+  if (configFile === undefined) {
+    const shared = await znightConfigOptions(compiler, root)
+    if (shared !== undefined) return shared
+  }
+  let options: ZnightOptions | undefined
+  // no Vite config: nothing to read, do not even load Vite
+  if (findViteConfig(root, configFile) === undefined) return { root }
+  try {
+    const vite = await cli.services.loadVite(root)
+    const lookup = await readZnightPluginOptions(vite, root, configFile, configLoader)
+    if (lookup !== undefined && !lookup.found) {
+      cli.reporter.warn(`${displayPath(lookup.configFile, cli.cwd)} does not register the znight() plugin`)
+    }
+    options = lookup?.options
+  } catch (error) {
+    if (configFile !== undefined) {
+      throw new CliError(`Cannot load the Vite config ${configFile}`, { cause: error, hints: [errorMessage(error)] })
+    }
+    cli.reporter.warn(
+      `Cannot read the znight() options from the Vite config, using the defaults: ${errorMessage(error)}`,
+    )
+  }
+  return { ...options, root: resolve(root, options?.root ?? '.') }
+}
+
+/** Options of `znight.config.*` (`loadZnightConfig()` of the compiler), `undefined` without the file. */
+async function znightConfigOptions(compiler: CompilerApi, root: string): Promise<ZnightOptions | undefined> {
+  if (compiler.loadConfig === undefined) return undefined
+  let config: ZnightConfigLike
+  try {
+    config = await compiler.loadConfig(root)
+  } catch (error) {
+    throw new CliError('Cannot load the Znight config (znight.config.*)', {
+      cause: error,
+      hints: [errorMessage(error)],
+    })
+  }
+  if (config.file === undefined) return undefined
+  // `logLevel` is an option of the Bun preload only
+  const { logLevel: _preloadLogLevel, ...options } = config.options
+  return { ...options, root: resolve(root, options.root ?? '.') }
+}
+
+function printDiagnostics(cli: CliContext, compiler: CompilerApi, result: CompileResultLike, root: string): void {
+  if (result.diagnostics.length === 0) return
+  const text = compiler.formatDiagnostics(result.diagnostics, {
+    color: cli.colors.isColorSupported,
+    cwd: root,
+    summary: false,
+  })
+  cli.reporter.logError(text.trimEnd())
+  cli.reporter.logError()
+}
+
+function statsOf(result: CompileResultLike, elapsedMs: number): string {
+  const parts: string[] = []
+  if (result.stats?.providers !== undefined) parts.push(plural(result.stats.providers, 'provider'))
+  if (result.stats?.files !== undefined) parts.push(plural(result.stats.files, 'file'))
+  parts.push(formatDuration(result.stats?.durationMs ?? elapsedMs))
+  return parts.join(', ')
+}
+
+function failure(cli: CliContext, result: CompileResultLike): void {
+  const errors = result.diagnostics.filter(diagnostic => diagnostic.severity === 'error').length
+  cli.reporter.error(`Generation failed with ${plural(errors, 'error')}`)
+}
+
+/** Prints the outcome of a generation. */
+function report(
+  cli: CliContext,
+  compiler: CompilerApi,
+  result: GenerateResultLike,
+  root: string,
+  elapsed: number,
+): void {
+  printDiagnostics(cli, compiler, result, root)
+  if (hasErrors(result.diagnostics)) {
+    failure(cli, result)
+    return
+  }
+  const file = displayPath(result.outFile, cli.cwd)
+  cli.reporter.success(
+    `${result.written ? 'Generated' : 'Up to date:'} ${cli.colors.bold(file)} ${cli.colors.dim(`(${statsOf(result, elapsed)})`)}`,
+  )
+}
+
+async function generateOnce(
+  cli: CliContext,
+  compiler: CompilerApi,
+  options: ZnightOptions,
+): Promise<GenerateResultLike> {
+  const started = performance.now()
+  const result = await compiler.generate(options)
+  report(cli, compiler, result, options.root ?? cli.cwd, performance.now() - started)
+  return result
+}
+
+/**
+ * The generated files `--check` reports, the module first: those the compiler says are stale (the
+ * module when it does not say which), and the module when it is missing.
+ */
+function staleFilesOf(result: CheckResultLike): string[] {
+  const stale = new Set<string>()
+  if (!existsSync(result.outFile)) stale.add(result.outFile)
+  if (result.stale) {
+    const files = result.staleFiles ?? []
+    for (const file of files.length > 0 ? files : [result.outFile]) stale.add(file)
+  }
+  return [...stale].sort((a, b) => Number(b === result.outFile) - Number(a === result.outFile))
+}
+
+async function check(cli: CliContext, compiler: CompilerApi, options: ZnightOptions): Promise<number> {
+  const root = options.root ?? cli.cwd
+  const started = performance.now()
+  const result = await compiler.check(options)
+  printDiagnostics(cli, compiler, result, root)
+  if (hasErrors(result.diagnostics)) {
+    failure(cli, result)
+    return 1
+  }
+  const file = displayPath(result.outFile, cli.cwd)
+  const stale = staleFilesOf(result)
+  for (const path of stale) {
+    const shown = displayPath(path, cli.cwd)
+    // the other generated file is the library manifest (`dist/znight.providers.json`)
+    const hint =
+      path === result.outFile
+        ? 'run "znight generate" (it is git-ignored: generate it before tsc and tests)'
+        : 'run "znight generate" after the build: a build cleaning dist/ (tsdown, tsc --build --clean...) deletes it'
+    if (existsSync(path)) cli.reporter.error(`${shown} is out of date`, ['run "znight generate"'])
+    else cli.reporter.error(`${shown} is missing`, [hint])
+  }
+  if (stale.length > 0) return 1
+  cli.reporter.success(
+    `${cli.colors.bold(file)} is up to date ${cli.colors.dim(`(${statsOf(result, performance.now() - started)})`)}`,
+  )
+  return 0
+}
+
+/** What the watcher knows about the last compile. */
+interface WatchState {
+  /** Files the last compile depends on (`watchFiles`): absolute, real, POSIX-style. */
+  readonly known: ReadonlySet<string>
+  /** Directories where a created or deleted source changes the scan (`includeRoots()`). */
+  readonly roots: readonly string[]
+}
+
+async function watch(cli: CliContext, compiler: CompilerApi, options: ZnightOptions): Promise<number> {
+  const root = options.root ?? cli.cwd
+  const realRoot = realPath(root)
+  const incremental: IncrementalCompiler = compiler.createIncremental(options)
+  let state: WatchState = { known: new Set(), roots: [] }
+  let pending = new Set<string>()
+  let running = false
+  let timer: ReturnType<typeof setTimeout> | undefined
+
+  // which events matter is the compiler's call: the CLI only tells their kind, which fs.watch does not
+  const watchers = new TargetWatchers(cli.services.watch, file => {
+    const path = realPath(file)
+    if (!incremental.isRelevantChange(changeKind(path, state.known), path, state.known, state.roots)) return
+    pending.add(path)
+    if (timer !== undefined) clearTimeout(timer)
+    timer = setTimeout(() => {
+      timer = undefined
+      void run(false)
+    }, 50)
+  })
+
+  const run = async (initial: boolean): Promise<void> => {
+    if (running) return
+    running = true
+    let first = initial
+    try {
+      do {
+        const files = pending
+        pending = new Set()
+        const started = performance.now()
+        let known = state.known
+        try {
+          const result = await incremental.generate(first ? undefined : classifyChanges(files, state.known))
+          if (result.watchFiles !== undefined) {
+            known = new Set(result.watchFiles.map(file => toPosixPath(resolve(file))))
+          }
+          report(cli, compiler, result, root, performance.now() - started)
+        } catch (error) {
+          cli.reporter.error(`Generation failed: ${errorMessage(error)}`)
+        }
+        // the include directories of the source libraries are known once compiled
+        state = { known, roots: incremental.includeRoots().map(realPath) }
+        watchers.update(watchTargets(realRoot, state.roots, state.known), files)
+        first = false
+      } while (pending.size > 0)
+    } finally {
+      running = false
+    }
+  }
+
+  await run(true)
+  cli.reporter.info(cli.colors.dim('Watching for changes... (Ctrl+C to stop)'))
+
+  return new Promise<number>(resolveExit => {
+    const dispose = onTermination(
+      cli,
+      () => {
+        if (timer !== undefined) clearTimeout(timer)
+        watchers.close()
+        dispose()
+        resolveExit(0)
+      },
+      () => undefined,
+    )
+  })
+}