@znight/cli 0.6.2 → 0.6.3

package/README.md

@@ -63,26 +63,30 @@ writes its committed `openapi.json` with `znight openapi` and checks it with `--
 ```sh
 znight new my-service                       # asks the questions below
 znight new my-service --yes                 # defaults, no question
-znight new my-service --pm pnpm --adapter fastify --features config,observability,messaging
-znight new my-worker --yes --features config,schedule,openapi
+znight new my-service --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,openapi --no-docker
 znight new . --yes --no-install             # in the current (empty) directory
 ```
 
-In a terminal, the CLI asks for the name, the package manager, the HTTP adapter, the features,
-and whether to install the dependencies and initialise git. Flags answer the questions up front; with
-`--yes` (or without a terminal, e.g. in CI) the defaults are used.
-
-| Option                                     | Default                                       | Description                                                                      |
-| ------------------------------------------ | --------------------------------------------- | -------------------------------------------------------------------------------- |
-| `[name]`                                   | (asked)                                       | npm package name (`my-service`, `@acme/api`), or `.`                             |
-| `-y, --yes`                                | `false`                                       | Do not ask questions                                                             |
-| `--pm <bun\|npm\|pnpm\|yarn>`              | the one running the CLI, else bun on Bun, npm | Package manager                                                                  |
-| `--adapter <node\|fastify\|express\|hono>` | `node`                                        | HTTP adapter (`node`: the built-in `node:http` server)                           |
-| `--features <list>`                        | `config,observability`                        | `config`, `observability`, `messaging`, `schedule`, `openapi`, or `all` / `none` |
-| `--no-install`                             | install                                       | Do not install the dependencies                                                  |
-| `--no-git`                                 | init                                          | Do not run `git init` (skipped anyway inside a git repository)                   |
-| `--dir <path>`                             | `./<name>` (unscoped)                         | Target directory                                                                 |
-| `--force`                                  | `false`                                       | Write into a non-empty directory (existing files are overwritten)                |
+In a terminal, the CLI asks for the name, the package manager, the HTTP adapter (Fastify first, and
+the default), the features, the OpenAPI reference UI (when `openapi` is selected), whether to add a
+Dockerfile, and whether to install the dependencies and initialise git. Flags answer the questions up
+front; with `--yes` (or without a terminal, e.g. in CI) the defaults are used.
+
+| Option                                     | Default                                       | Description                                                                                              |
+| ------------------------------------------ | --------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `[name]`                                   | (asked)                                       | npm package name (`my-service`, `@acme/api`), or `.`                                                     |
+| `-y, --yes`                                | `false`                                       | Do not ask questions                                                                                     |
+| `--pm <bun\|npm\|pnpm\|yarn>`              | the one running the CLI, else bun on Bun, npm | Package manager                                                                                          |
+| `--adapter <fastify\|node\|express\|hono>` | `fastify`                                     | HTTP adapter (`node`: the built-in `node:http` server)                                                   |
+| `--features <list>`                        | `config,observability`                        | `config`, `observability`, `messaging`, `schedule`, `openapi`, `graphql`, `websocket`, or `all` / `none` |
+| `--openapi-ui <scalar\|swagger>`           | `scalar`                                      | API reference UI served at `/docs` by the `openapi` feature (Scalar or Swagger UI)                       |
+| `--no-docker`                              | Dockerfile                                    | Do not generate the `Dockerfile` and `.dockerignore`                                                     |
+| `--no-install`                             | install                                       | Do not install the dependencies                                                                          |
+| `--no-git`                                 | init                                          | Do not run `git init` (skipped anyway inside a git repository)                                           |
+| `--dir <path>`                             | `./<name>` (unscoped)                         | Target directory                                                                                         |
+| `--force`                                  | `false`                                       | Write into a non-empty directory (existing files are overwritten)                                        |
 
 The package manager defaults to the one that launched the CLI (`npx`, `pnpm dlx`, `yarn dlx`,
 `bunx`). The target directory must be empty (`.git`, `.DS_Store` and editor folders are fine).
@@ -100,17 +104,23 @@ my-service/
 │     ├─ greeting.service.ts     # @Injectable, uses AppConfig and Logger
 │     ├─ greeting.controller.ts  # GET /greetings/:name?excited, POST /greetings (validated body)
 │     ├─ greeting.consumer.ts    # @Consumer('greetings'), POST /greetings/async  (messaging)
+│     ├─ greeting.gateway.ts     # @Gateway('/ws'): a "greet" WebSocket event      (websocket)
+│     ├─ greeting.resolver.ts    # @Resolver: query { greeting(name) }            (graphql)
 │     ├─ health.controller.ts    # GET /health
 │     └─ heartbeat.jobs.ts       # @Cron('* * * * *'): a job every minute          (schedule)
 ├─ test/
 │  ├─ greeting.service.test.ts     # TestBed: real factory, auto-mocked dependencies
 │  ├─ greeting.controller.test.ts  # TestApp: in-memory HTTP requests
+│  ├─ greeting.gateway.test.ts     # TestApp.connect(): in-memory WebSocket         (websocket)
+│  ├─ greeting.resolver.test.ts    # executeOperation(): GraphQL over HTTP          (graphql)
 │  └─ heartbeat.jobs.test.ts       # TestApp + createTestClock(): virtual time      (schedule)
 ├─ vite.config.ts                # plugins: [znight(options)]
 ├─ znight.config.ts              # compiler options, shared by znight(), the Bun preload and znight generate
 ├─ tsconfig.json                 # strict, experimentalDecorators, moduleResolution bundler, noEmit
 ├─ bunfig.toml                   # bun only: preloads @znight/compiler/bun before the tests
 ├─ package.json                  # type module; scripts dev, build, start, generate, typecheck, test
+├─ Dockerfile                    # multi-stage production image                    (docker)
+├─ .dockerignore
 └─ .gitignore                    # node_modules, dist, .znight
 ```
 
@@ -127,12 +137,32 @@ my-service/
 - `schedule` adds `@znight/schedule`, `SchedulePlugin.configure()` **before** `HttpPlugin` (plugins
   stop in reverse order: HTTP stops taking requests first, then running jobs drain), a sample job
   and its test on a virtual clock (`createTestClock()` of `@znight/schedule/testing`).
-- `openapi` adds `@znight/openapi`, `OpenApiPlugin.configure()` after `HttpPlugin` (`/openapi.json`
-  and the API reference at `/docs`), `src/api.ts` (`@OpenApiDocument`) and the `openapi` /
-  `openapi:check` scripts (commit `openapi.json`, check it in CI).
-- The `TestApp` test configures `ObservabilityPlugin` with `metrics: { server: false }`: with
-  `prom-client` installed, the metrics server (`:9464`) would collide with `znight dev` or with other
-  test files running in parallel.
+- `observability` adds `@znight/observability` and `ObservabilityPlugin.configure()` first, its
+  logger named after the project (`logging: { name: '<name>' }`), with the `metrics` and `tracing`
+  options as commented-out placeholders.
+- `openapi` adds `@znight/openapi`, `OpenApiPlugin.configure({ ui })` after `HttpPlugin`
+  (`/openapi.json` and the API reference at `/docs`, `ui: 'scalar'` or `'swagger'` from
+  `--openapi-ui`), `src/api.ts` (`@OpenApiDocument`) and the `openapi` / `openapi:check` scripts
+  (commit `openapi.json`, check it in CI).
+- `graphql` adds `@znight/graphql` and `graphql`, `GraphQLPlugin.configure()` after `HttpPlugin`
+  (`POST /graphql`, GraphiQL on `GET /graphql` in development), a code-first resolver
+  (`src/app/greeting.resolver.ts`: the schema is derived from its types) and its test
+  (`executeOperation()` of `@znight/graphql/testing`).
+- `websocket` adds `@znight/websocket` and `ws` (the transport of the `node:http` based servers; Bun
+  provides its own), `WebSocketPlugin.configure()` after `HttpPlugin`, a gateway on `/ws`
+  (`src/app/greeting.gateway.ts`, a validated `greet` event with a reply) and its test
+  (`TestApp.connect()`).
+- The `TestApp` tests configure `ObservabilityPlugin` with `metrics: false`: with `prom-client`
+  installed, the metrics server (`:9464`) would collide with `znight dev` or with other test files
+  running in parallel, and any metrics option object requires `prom-client`.
+- The `Dockerfile` (unless `--no-docker`) is multi-stage: a `deps` stage installs the production
+  dependencies only from the lockfile, a `build` stage installs everything and runs the build (the
+  compiler runs there), and the runtime stage (`node:24-slim`, or `oven/bun:1-slim` for Bun projects)
+  copies `dist/` and the production `node_modules`, sets `NODE_ENV=production`, runs as the image's
+  non-root user, exposes port 3000, probes `GET /health` in its `HEALTHCHECK` and starts the bundle in
+  exec form (`node --enable-source-maps dist/main.js`, `bun --no-env-file dist/main.js`). Installs are
+  frozen, so the lockfile must exist (install the dependencies first); pnpm and yarn come from
+  Corepack. `.dockerignore` leaves out `node_modules`, `dist`, `.znight`, `.env` files and `.git`.
 
 ## `znight generate`
 
@@ -283,7 +313,8 @@ restart is fast and always consistent.
 5. `Ctrl+C` (or `SIGTERM`, `SIGHUP` when the terminal is closed, `Ctrl+\` / `SIGQUIT`) → the
    watcher closes and the application stops gracefully (`SIGINT` after `Ctrl+C`, `SIGTERM` otherwise);
    a second signal kills it. The application runs in its own session and process group, so it
-   receives exactly one signal, and never the terminal's.
+   receives exactly one signal, and never the terminal's. On Windows it shares the console, which
+   delivers `Ctrl+C` to it: the CLI waits for it to stop (`SIGKILL` after `--kill-timeout`).
 6. The CLI dies without stopping it (`kill -9`, the OOM killer) → the application stops by itself
    (`SIGTERM`, then `SIGKILL` after `--kill-timeout`) within half a second instead of keeping its
    port: the CLI preloads a small guard into it (`--import` on Node.js, `--preload` on Bun) that
@@ -370,7 +401,9 @@ Runs the production build with `NODE_ENV=production` (unless set). On Linux and
 **replaces itself** with the runtime (`execve`): same PID, signals and exit code go straight to the
 application, which makes `znight start` a good container entry point. Elsewhere the application runs
 as a child process: `SIGINT`, `SIGTERM` and `SIGHUP` are forwarded and its exit code is returned
-(`128 + n` when it is killed by a signal).
+(`128 + n` when it is killed by a signal). On Windows, `Ctrl+C` and the console closing are not
+forwarded: the application shares the console and receives them itself, while forwarding would
+terminate it at once (Windows has no graceful `kill()`).
 
 | Option                        | Default                         | Description                                     |
 | ----------------------------- | ------------------------------- | ----------------------------------------------- |

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as main } from "./main-DUyElIVZ.mjs";
+import { n as main } from "./main-CLoS12u4.mjs";
 // src/cli.ts
 /**
 * The `znight` binary. Everything lives in `main()`; this file only wires the process: arguments,

package/dist/index.d.mts

@@ -510,8 +510,9 @@ export declare class AppSupervisor {
   /** Restarts after `debounceMs`; calls in between postpone it. */
   scheduleRestart(): void;
   /**
-   * 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;
   /**
@@ -519,8 +520,12 @@ export declare class AppSupervisor {
    * requested while another one is waiting to run is merged with it.
    */
   restart(): Promise<void>;
-  /** Stops the current process with `signal` (SIGKILL after the timeout) and refuses new starts. */
-  stop(signal?: NodeJS.Signals): 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.
+   */
+  stop(signal?: NodeJS.Signals | null): Promise<void>;
   /** Immediately SIGKILLs every process (a second Ctrl+C). */
   kill(): void;
 }
@@ -530,10 +535,12 @@ type PackageManager = "bun" | "npm" | "pnpm" | "yarn";
 /** HTTP adapters of `@znight/http`. */
 type HttpAdapterName = "node" | "fastify" | "express" | "hono";
 /** Optional features of a new project. */
-type Feature = "config" | "observability" | "messaging" | "schedule" | "openapi";
+type Feature = "config" | "observability" | "messaging" | "schedule" | "openapi" | "graphql" | "websocket";
+/** API reference UIs of `@znight/openapi` (its `ui` option). */
+type OpenApiUiName = "scalar" | "swagger";
 /** Every package manager, in display order. */
 export declare const PACKAGE_MANAGERS: readonly PackageManager[];
-/** Every HTTP adapter, in display order. */
+/** Every HTTP adapter, in display order (the default first). */
 export declare const HTTP_ADAPTERS: readonly HttpAdapterName[];
 /** Every feature, in display (and canonical) order. */
 export declare const FEATURES: readonly Feature[];
@@ -547,6 +554,10 @@ 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;
 }

package/dist/index.mjs

@@ -1 +1 @@
-export { d as AppSupervisor, t as COMMANDS, _ as CancelledError, v as CliError, s as DEFAULT_FEATURES, y as ExitCode, c as FEATURES, l as HTTP_ADAPTERS, u as PACKAGE_MANAGERS, r as SCHEMATICS, b as UsageError, m as adaptCompilerModule, p as cliVersion, f as createContext, g as defineCommand, i as findSchematic, h as loadCompiler, n as main, a as planSchematic, o as renderProject } from "./main-DUyElIVZ.mjs";
+export { d as AppSupervisor, t as COMMANDS, _ as CancelledError, v as CliError, s as DEFAULT_FEATURES, y as ExitCode, c as FEATURES, l as HTTP_ADAPTERS, u as PACKAGE_MANAGERS, r as SCHEMATICS, b as UsageError, m as adaptCompilerModule, p as cliVersion, f as createContext, g as defineCommand, i as findSchematic, h as loadCompiler, n as main, a as planSchematic, o as renderProject } from "./main-CLoS12u4.mjs";