@znight/cli 0.6.2 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@znight/cli",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Znight CLI: scaffold projects, generate code, run dev server and builds",
   "license": "MIT",
   "author": "Ugho STEPHAN",
@@ -41,7 +41,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.8.1",
-    "@znight/core": "0.6.2",
+    "@znight/core": "0.6.3",
     "citty": "^0.2.2",
     "picocolors": "^1.1.1"
   },
@@ -50,14 +50,14 @@
   },
   "devDependencies": {
     "vite": "8.3.5",
-    "@znight/compiler": "0.6.2",
-    "@znight/openapi": "0.6.2",
-    "@znight/schedule": "0.6.2"
+    "@znight/compiler": "0.6.3",
+    "@znight/openapi": "0.6.3",
+    "@znight/schedule": "0.6.3"
   },
   "peerDependencies": {
-    "@znight/compiler": "^0.6.2",
+    "@znight/compiler": "^0.6.3",
     "vite": "^8.0.0",
-    "@znight/openapi": "^0.6.2"
+    "@znight/openapi": "^0.6.3"
   },
   "peerDependenciesMeta": {
     "@znight/compiler": {

package/src/commands/dev.ts

@@ -16,7 +16,7 @@ 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 { CliError, errorMessage } from '../errors.ts'
 import { fallbackFormatDiagnostics } from '../integrations/compiler.ts'
 import { exitCodeOf } from '../integrations/process.ts'
 import { createOutputTracker, formatBuildError, watchBuild } from '../integrations/vite.ts'
@@ -221,6 +221,16 @@ async function printDiagnostics(cli: CliContext, root: string, diagnostics: read
   cli.reporter.logError(text.trimEnd())
 }
 
+/**
+ * The signal stopping the application when the CLI received `signal`. On Windows the application
+ * shares the console: it received Ctrl+C and the console closing itself, and `kill()` would be a
+ * forced termination, so it is only waited for (`null`).
+ */
+function stopSignal(cli: CliContext, signal: NodeJS.Signals): NodeJS.Signals | null {
+  if (cli.runtime.platform === 'win32' && (signal === 'SIGINT' || signal === 'SIGHUP')) return null
+  return signal === 'SIGINT' ? 'SIGINT' : 'SIGTERM'
+}
+
 function waitForTermination(cli: CliContext, watcher: BuildWatcher, supervisor: AppSupervisor): Promise<number> {
   return new Promise<number>(resolveExit => {
     const dispose = onTermination(
@@ -229,14 +239,21 @@ function waitForTermination(cli: CliContext, watcher: BuildWatcher, supervisor:
         // 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 () => {
+          // the application stops gracefully on SIGINT or SIGTERM; stop() refuses new starts right
+          // away, so a restart still debounced cannot start while Vite closes its watcher
+          const stopped = supervisor.stop(stopSignal(cli, signal))
           try {
             await watcher.close()
-          } finally {
-            // the application stops gracefully on SIGINT or SIGTERM
-            await supervisor.stop(signal === 'SIGINT' ? 'SIGINT' : 'SIGTERM')
-            dispose()
-            resolveExit(0)
+          } catch (error) {
+            cli.reporter.error(`Cannot close the Vite build watcher: ${errorMessage(error)}`)
+          }
+          try {
+            await stopped
+          } catch (error) {
+            cli.reporter.error(`Cannot stop the application: ${errorMessage(error)}`)
           }
+          dispose()
+          resolveExit(0)
         })()
       },
       () => {

package/src/commands/generate.ts

@@ -248,11 +248,14 @@ async function watch(cli: CliContext, compiler: CompilerApi, options: ZnightOpti
   const incremental: IncrementalCompiler = compiler.createIncremental(options)
   let state: WatchState = { known: new Set(), roots: [] }
   let pending = new Set<string>()
-  let running = false
+  let running: Promise<void> | undefined
+  // set on Ctrl+C: a generation in flight must neither watch again nor loop
+  let closed = 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 => {
+    if (closed) return
     const path = realPath(file)
     if (!incremental.isRelevantChange(changeKind(path, state.known), path, state.known, state.roots)) return
     pending.add(path)
@@ -263,33 +266,36 @@ async function watch(cli: CliContext, compiler: CompilerApi, options: ZnightOpti
     }, 50)
   })
 
-  const run = async (initial: boolean): Promise<void> => {
-    if (running) return
-    running = true
+  const run = (initial: boolean): Promise<void> => {
+    if (running !== undefined || closed) return running ?? Promise.resolve()
+    running = generations(initial).finally(() => {
+      running = undefined
+    })
+    return running
+  }
+
+  const generations = async (initial: boolean): Promise<void> => {
     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)}`)
+    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))))
         }
-        // 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
-    }
+        report(cli, compiler, result, root, performance.now() - started)
+      } catch (error) {
+        cli.reporter.error(`Generation failed: ${errorMessage(error)}`)
+      }
+      if (closed) return
+      // 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 && !closed)
   }
 
   await run(true)
@@ -299,10 +305,13 @@ async function watch(cli: CliContext, compiler: CompilerApi, options: ZnightOpti
     const dispose = onTermination(
       cli,
       () => {
+        closed = true
         if (timer !== undefined) clearTimeout(timer)
         watchers.close()
         dispose()
-        resolveExit(0)
+        // the generation in flight finishes writing its files first
+        const exit = (): void => resolveExit(0)
+        void (running ?? Promise.resolve()).then(exit, exit)
       },
       () => undefined,
     )

package/src/commands/new.ts

@@ -2,7 +2,7 @@
 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 type { Feature, HttpAdapterName, OpenApiUiName, PackageManager } from '../scaffold/options.ts'
 
 import { basename, resolve } from 'node:path'
 
@@ -12,12 +12,16 @@ import { toPackageName, unscopedName, validatePackageName } from '../names.ts'
 import { initGit, installDependencies, targetState, writeProject } from '../scaffold/create.ts'
 import {
   ADAPTER_LABELS,
+  DEFAULT_ADAPTER,
   DEFAULT_FEATURES,
+  DEFAULT_OPENAPI_UI,
   detectPackageManager,
   FEATURE_LABELS,
   FEATURES,
   HTTP_ADAPTERS,
   installCommand,
+  OPENAPI_UI_LABELS,
+  OPENAPI_UIS,
   PACKAGE_MANAGERS,
   parseFeatures,
   runScript,
@@ -34,7 +38,8 @@ export const newCommand: Command = defineCommand({
     aliases: ['create', 'init'],
     examples: [
       'znight new my-service',
-      'znight new my-service --yes --pm pnpm --adapter fastify --features config,observability,messaging',
+      'znight new my-service --yes --pm pnpm --adapter hono --features config,observability,messaging',
+      'znight new my-api --yes --features config,observability,openapi,graphql,websocket --openapi-ui swagger',
       'znight new my-worker --yes --features config,schedule',
       'znight new . --yes --no-install',
     ],
@@ -53,15 +58,21 @@ export const newCommand: Command = defineCommand({
     },
     adapter: {
       type: 'enum',
-      options: ['node', 'fastify', 'express', 'hono'],
-      description: 'HTTP adapter (default: node, the built-in node:http server)',
+      options: ['fastify', 'node', 'express', 'hono'],
+      description: 'HTTP adapter (default: fastify; node is 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)',
+        'Comma-separated features: config, observability, messaging, schedule, openapi, graphql, websocket, or "all" / "none" (default: config,observability)',
     },
+    'openapi-ui': {
+      type: 'enum',
+      options: ['scalar', 'swagger'],
+      description: 'API reference UI of the openapi feature, served at /docs (default: scalar)',
+    },
+    docker: { type: 'boolean', default: true, description: 'Do not generate a Dockerfile' },
     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>)' },
@@ -112,10 +123,24 @@ export const newCommand: Command = defineCommand({
       (await prompts?.select({
         message: 'HTTP adapter?',
         choices: HTTP_ADAPTERS.map(value => ({ value, label: ADAPTER_LABELS[value] })),
-        initialValue: 'node',
+        initialValue: DEFAULT_ADAPTER,
       })) ??
-      'node'
+      DEFAULT_ADAPTER
     const features = await chooseFeatures(options.features, prompts)
+    const openapiUi: OpenApiUiName =
+      options['openapi-ui'] ??
+      (features.includes('openapi')
+        ? await prompts?.select({
+            message: 'OpenAPI reference UI (served at /docs)?',
+            choices: OPENAPI_UIS.map(value => ({ value, label: OPENAPI_UI_LABELS[value] })),
+            initialValue: DEFAULT_OPENAPI_UI,
+          })
+        : undefined) ??
+      DEFAULT_OPENAPI_UI
+    const docker =
+      prompts === undefined || hasFlag(rawArgs, 'docker')
+        ? options.docker !== false
+        : await prompts.confirm({ message: 'Add a Dockerfile (production image)?', initialValue: true })
     const install =
       prompts === undefined || hasFlag(rawArgs, 'install')
         ? options.install !== false
@@ -126,7 +151,15 @@ export const newCommand: Command = defineCommand({
         : await prompts.confirm({ message: 'Initialise a git repository?', initialValue: true })
 
     // files
-    const files = renderProject({ name, packageManager, adapter, features, znightVersion: cli.version })
+    const files = renderProject({
+      name,
+      packageManager,
+      adapter,
+      features,
+      openapiUi,
+      docker,
+      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(', ')}` : ''})`

package/src/commands/start.ts

@@ -2,7 +2,8 @@
  * `znight start`: runs the production build with Node.js (or Bun). On POSIX the CLI process is
  * replaced by the runtime (`execve`): same PID, signals and exit code are native (ideal as a
  * container entry point). Elsewhere the application runs as a child process; signals are forwarded
- * and its exit code is returned.
+ * (except, on Windows, Ctrl+C and the console closing, which reach it directly) and its exit code is
+ * returned.
  */
 import type { Command } from '../command.ts'
 
@@ -63,8 +64,12 @@ export const startCommand: Command = defineCommand({
       return 0
     }
     const child = processes.spawn(executable, argv, { cwd: root, env, detached: true })
+    // on Windows the application shares the console: Ctrl+C and the console closing reach it
+    // directly, and child.kill() would be TerminateProcess, cutting its graceful shutdown short
+    const consoleEvent = (signal: NodeJS.Signals): boolean =>
+      cli.runtime.platform === 'win32' && (signal === 'SIGINT' || signal === 'SIGHUP')
     const forward = (signal: NodeJS.Signals) => (): void => {
-      child.kill(signal)
+      if (!consoleEvent(signal)) child.kill(signal)
     }
     const listeners = (['SIGINT', 'SIGTERM', 'SIGHUP'] as const).map(signal => [signal, forward(signal)] as const)
     for (const [signal, listener] of listeners) cli.signals.on(signal, listener)

package/src/dev/supervisor.ts

@@ -3,7 +3,8 @@
  * after each successful build. Stopping sends SIGTERM, waits for the exit and sends SIGKILL after a
  * timeout. Restarts are serialised and coalesced: a burst of builds causes one restart with the
  * latest output. A failed build simply does not schedule a restart (and cancels a pending one when
- * its output is broken), so the last good process keeps running.
+ * its output is broken, even one already stopping the previous process), so nothing starts until a
+ * build compiles.
  */
 import type { ChildHandle, ExitStatus } from '../integrations/process.ts'
 
@@ -41,6 +42,12 @@ export class AppSupervisor {
   #debounce: ReturnType<typeof setTimeout> | undefined
   #queue: Promise<void> = Promise.resolve()
   #queued = false
+  /** A restart is stopping the previous process before starting the next one. */
+  #restarting = false
+  /** Bumped by {@link cancelRestart}: a restart requested in an older epoch does not start. */
+  #epoch = 0
+  /** Epoch of the latest restart request. */
+  #requested = 0
   #closed = false
   #started = 0
 
@@ -77,14 +84,18 @@ export class AppSupervisor {
   }
 
   /**
-   * Cancels a restart scheduled by {@link scheduleRestart} and not started yet (the output it would
-   * run turned out to be broken, e.g. a failed compilation). Returns whether one was pending.
+   * Cancels the restarts that did not start their process yet (the output they would run turned out
+   * to be broken, e.g. a failed compilation): scheduled, queued, or stopping the previous process
+   * (which still stops). Returns whether one was pending.
    */
   cancelRestart(): boolean {
-    if (this.#debounce === undefined) return false
-    clearTimeout(this.#debounce)
-    this.#debounce = undefined
-    return true
+    const pending = this.#debounce !== undefined || this.#queued || this.#restarting
+    if (this.#debounce !== undefined) {
+      clearTimeout(this.#debounce)
+      this.#debounce = undefined
+    }
+    this.#epoch++
+    return pending
   }
 
   /**
@@ -93,14 +104,23 @@ export class AppSupervisor {
    */
   restart(): Promise<void> {
     if (this.#closed) return this.#queue
+    this.#requested = this.#epoch
     if (this.#queued) return this.#queue
     this.#queued = true
     this.#queue = this.#queue
       .then(async () => {
         this.#queued = false
-        if (this.#closed) return
-        await this.#stopCurrent('SIGTERM')
-        if (this.#closed) return
+        // cancelled while it waited for the previous restart
+        if (this.#closed || this.#requested !== this.#epoch) return
+        const epoch = this.#epoch
+        this.#restarting = true
+        try {
+          await this.#stopCurrent('SIGTERM')
+        } finally {
+          this.#restarting = false
+        }
+        // cancelled while the previous process was stopping
+        if (this.#closed || epoch !== this.#epoch) return
         this.#startNew()
       })
       .catch((error: unknown) => {
@@ -111,8 +131,12 @@ export class AppSupervisor {
     return this.#queue
   }
 
-  /** Stops the current process with `signal` (SIGKILL after the timeout) and refuses new starts. */
-  async stop(signal: NodeJS.Signals = 'SIGTERM'): Promise<void> {
+  /**
+   * Stops the current process with `signal` (SIGKILL after the timeout) and refuses new starts.
+   * `null`: the process already received the signal (a console Ctrl+C on Windows, where `kill()` is
+   * a forced termination): it is only waited for, then SIGKILLed after the timeout.
+   */
+  async stop(signal: NodeJS.Signals | null = 'SIGTERM'): Promise<void> {
     this.#closed = true
     if (this.#debounce !== undefined) {
       clearTimeout(this.#debounce)
@@ -149,13 +173,13 @@ export class AppSupervisor {
     this.#events.onStart?.(child, restart)
   }
 
-  async #stopCurrent(signal: NodeJS.Signals): Promise<void> {
+  async #stopCurrent(signal: NodeJS.Signals | null): Promise<void> {
     const child = this.#current
     if (child === undefined) return
     this.#current = undefined
     this.#stopping.add(child)
     try {
-      child.kill(signal)
+      if (signal !== null) child.kill(signal)
       let timer: ReturnType<typeof setTimeout> | undefined
       const timeout = new Promise<'timeout'>(resolve => {
         timer = setTimeout(() => resolve('timeout'), this.#killTimeoutMs)

package/src/scaffold/options.ts

@@ -7,24 +7,44 @@ export type PackageManager = 'bun' | 'npm' | 'pnpm' | 'yarn'
 export type HttpAdapterName = 'node' | 'fastify' | 'express' | 'hono'
 
 /** Optional features of a new project. */
-export type Feature = 'config' | 'observability' | 'messaging' | 'schedule' | 'openapi'
+export type Feature = 'config' | 'observability' | 'messaging' | 'schedule' | 'openapi' | 'graphql' | 'websocket'
+
+/** API reference UIs of `@znight/openapi` (its `ui` option). */
+export type OpenApiUiName = 'scalar' | 'swagger'
 
 /** Every package manager, in display order. */
 export const PACKAGE_MANAGERS: readonly PackageManager[] = ['bun', 'npm', 'pnpm', 'yarn']
 
-/** Every HTTP adapter, in display order. */
-export const HTTP_ADAPTERS: readonly HttpAdapterName[] = ['node', 'fastify', 'express', 'hono']
+/** Every HTTP adapter, in display order (the default first). */
+export const HTTP_ADAPTERS: readonly HttpAdapterName[] = ['fastify', 'node', 'express', 'hono']
+
+/** HTTP adapter used when none is given. */
+export const DEFAULT_ADAPTER: HttpAdapterName = 'fastify'
 
 /** Every feature, in display (and canonical) order. */
-export const FEATURES: readonly Feature[] = ['config', 'observability', 'messaging', 'schedule', 'openapi']
+export const FEATURES: readonly Feature[] = [
+  'config',
+  'observability',
+  'messaging',
+  'schedule',
+  'openapi',
+  'graphql',
+  'websocket',
+]
+
+/** Every OpenAPI reference UI, in display order (the default first). */
+export const OPENAPI_UIS: readonly OpenApiUiName[] = ['scalar', 'swagger']
+
+/** OpenAPI reference UI used when none is given. */
+export const DEFAULT_OPENAPI_UI: OpenApiUiName = 'scalar'
 
 /** Features selected when none are given. */
 export const DEFAULT_FEATURES: readonly Feature[] = ['config', 'observability']
 
 /** Labels shown by the prompts and the help. */
 export const ADAPTER_LABELS: Readonly<Record<HttpAdapterName, string>> = {
-  node: 'node:http (built-in, zero dependency)',
   fastify: 'Fastify',
+  node: 'node:http (built-in, zero dependency)',
   express: 'Express',
   hono: 'Hono',
 }
@@ -36,6 +56,14 @@ export const FEATURE_LABELS: Readonly<Record<Feature, string>> = {
   messaging: 'Messaging: message consumers and publishing (@znight/messaging)',
   schedule: 'Schedule: cron, interval and timeout jobs (@znight/schedule)',
   openapi: 'OpenAPI: openapi.json and an API reference at /docs (@znight/openapi)',
+  graphql: 'GraphQL: code-first schema derived from the TypeScript types (@znight/graphql)',
+  websocket: 'WebSocket: gateways served on the HTTP port (@znight/websocket)',
+}
+
+/** Labels shown by the prompts. */
+export const OPENAPI_UI_LABELS: Readonly<Record<OpenApiUiName, string>> = {
+  scalar: 'Scalar',
+  swagger: 'Swagger UI',
 }
 
 /** Everything that determines the files of a new project. */
@@ -46,6 +74,10 @@ export interface ProjectOptions {
   readonly adapter: HttpAdapterName
   /** Selected features, in canonical order. */
   readonly features: readonly Feature[]
+  /** API reference UI served at `/docs` with the `openapi` feature. Default: `'scalar'`. */
+  readonly openapiUi?: OpenApiUiName
+  /** Generate a multi-stage `Dockerfile` and a `.dockerignore`. Default: `true`. */
+  readonly docker?: boolean
   /** Version range base of the `@znight/*` packages (the CLI version). */
   readonly znightVersion: string
 }