@znight/cli 0.6.6 → 0.7.0

package/README.md

@@ -70,8 +70,9 @@ 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 (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
+the default), the features (`config` and `observability` preselected), the OpenAPI reference UI
+(Scalar, Swagger UI or no 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                                                                                              |
@@ -81,7 +82,7 @@ front; with `--yes` (or without a terminal, e.g. in CI) the defaults are used.
 | `--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)                       |
+| `--openapi-ui <scalar\|swagger\|none>`     | `scalar`                                      | API reference UI served at `/docs` by the `openapi` feature (Scalar, Swagger UI, or `none`)              |
 | `--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)                                           |
@@ -97,9 +98,9 @@ The package manager defaults to the one that launched the CLI (`npx`, `pnpm dlx`
 my-service/
 ├─ src/
 │  ├─ main.ts                    # Application.create() with the plugins, then start()
-│  ├─ api.ts                     # @OpenApiDocument: title, tags of openapi.json   (openapi)
+│  ├─ openapi.ts                 # @OpenApiDocument: info of openapi.json          (openapi)
 │  └─ app/
-│     ├─ app.config.ts           # @Config('app'): PORT, APP_GREETING           (config)
+│     ├─ app.config.ts           # @Config('app'): PORT, APP_GREETING, NODE_ENV (config)
 │     ├─ greeting.schemas.ts     # Zod schema of the request body
 │     ├─ greeting.service.ts     # @Injectable, uses AppConfig and Logger
 │     ├─ greeting.controller.ts  # GET /greetings/:name?excited, POST /greetings (validated body)
@@ -137,13 +138,33 @@ 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`).
-- `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.
+- `observability` adds `@znight/observability`, `pino-pretty` as a dev dependency (it is loaded only
+  in development, so the production image does not ship it) and `ObservabilityPlugin.configure()`
+  first: its logger is named after the project and pretty-printed in development only, JSON
+  otherwise, `metrics: false` and `tracing: false`. With `config`, `AppConfig` gets an `environment`
+  property read from `NODE_ENV` and the options are a function of the container:
+
+  ```ts
+  ObservabilityPlugin.configure(container => ({
+    logging: {
+      name: 'my-service',
+      // human-readable logs in development (`znight dev`), JSON logs in production
+      pretty: container.get(AppConfig).environment === 'development',
+    },
+    metrics: false,
+    tracing: false,
+  }))
+  ```
+
+  Without `config`, the options are an object with `pretty: process.env['NODE_ENV'] ===
+  'development'`. `znight dev` runs the application with `NODE_ENV=development`, `znight start` and
+  the `Dockerfile` with `NODE_ENV=production`.
 - `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).
+  `--openapi-ui`; `OpenApiPlugin.configure()` and no `/docs` with `--openapi-ui none`),
+  `src/openapi.ts` (`@OpenApiDocument({ info: { title, description, version } })`, the title being
+  the project name) 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

package/dist/cli.mjs

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

package/dist/index.d.mts

@@ -542,8 +542,11 @@ type PackageManager = "bun" | "npm" | "pnpm" | "yarn";
 type HttpAdapterName = "node" | "fastify" | "express" | "hono";
 /** Optional features of a new project. */
 type Feature = "config" | "observability" | "messaging" | "schedule" | "openapi" | "graphql" | "websocket";
-/** API reference UIs of `@znight/openapi` (its `ui` option). */
-type OpenApiUiName = "scalar" | "swagger";
+/**
+ * API reference UI of the `openapi` feature: `'scalar'` or `'swagger'` (the `ui` option of
+ * `OpenApiPlugin`), or `'none'` (no `ui` option: `/openapi.json` only).
+ */
+type OpenApiUiName = "scalar" | "swagger" | "none";
 /** Every package manager, in display order. */
 export declare const PACKAGE_MANAGERS: readonly PackageManager[];
 /** Every HTTP adapter, in display order (the default first). */
@@ -560,7 +563,7 @@ 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'`. */
+  /** API reference UI served at `/docs` with the `openapi` feature (`'none'`: no UI). Default: `'scalar'`. */
   readonly openapiUi?: OpenApiUiName;
   /** Generate a multi-stage `Dockerfile` and a `.dockerignore`. Default: `true`. */
   readonly docker?: boolean;

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-CoWyMPKl.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-D_BXiYBu.mjs";

package/dist/{main-CoWyMPKl.mjs → main-D_BXiYBu.mjs}

@@ -2151,7 +2151,11 @@ const FEATURES = [
 	"websocket"
 ];
 /** Every OpenAPI reference UI, in display order (the default first). */
-const OPENAPI_UIS = ["scalar", "swagger"];
+const OPENAPI_UIS = [
+	"scalar",
+	"swagger",
+	"none"
+];
 /** Features selected when none are given. */
 const DEFAULT_FEATURES = ["config", "observability"];
 /** Labels shown by the prompts and the help. */
@@ -2167,14 +2171,15 @@ const FEATURE_LABELS = {
 	observability: "Observability: structured logs, metrics, tracing (@znight/observability)",
 	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)",
+	openapi: "OpenAPI: openapi.json and an optional 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. */
 const OPENAPI_UI_LABELS = {
 	scalar: "Scalar",
-	swagger: "Swagger UI"
+	swagger: "Swagger UI",
+	none: "No UI (openapi.json only)"
 };
 /**
 * Parses `--features` (`config,observability`, `none`, `all`). Returns the features in canonical
@@ -2279,6 +2284,7 @@ const DEPENDENCY_VERSIONS = {
 	graphql: "^17.0.2",
 	hono: "^4.13.14",
 	"light-my-request": "^6.8.0",
+	"pino-pretty": "^13.2.0",
 	typescript: "^7.0.0",
 	vite: "^8.0.0",
 	vitest: "^4.1.0",
@@ -2386,8 +2392,8 @@ function renderProject(options) {
 		});
 	}
 	if (flags.openapi) files.push({
-		path: "src/api.ts",
-		content: apiDocument(options)
+		path: "src/openapi.ts",
+		content: openApiDocument(flags)
 	});
 	if (flags.graphql) {
 		files.push({
@@ -2468,6 +2474,7 @@ function packageJson(options, flags) {
 	};
 	if (flags.bun) devDependencies["@types/bun"] = versionOf("@types/bun");
 	else devDependencies["vitest"] = versionOf("vitest");
+	if (flags.observability) devDependencies["pino-pretty"] = versionOf("pino-pretty");
 	if (flags.adapter === "express") devDependencies["@types/express"] = versionOf("@types/express");
 	if (flags.adapter === "node" || flags.adapter === "express") devDependencies["light-my-request"] = versionOf("light-my-request");
 	const manifest = {
@@ -2689,7 +2696,26 @@ function mainTs(flags) {
 	].filter((line) => line !== void 0);
 	const localImports = ["import { __ZNIGHT_METADATA__ } from './.znight/container.generated.js'", flags.config ? "import { AppConfig } from './app/app.config.js'" : void 0].filter((line) => line !== void 0);
 	const plugins = [];
-	if (flags.observability) plugins.push("    // first, so that its hooks wrap everything: request logs, metrics (with prom-client), traces", "    ObservabilityPlugin.configure({", "      logging: {", `        name: ${quote(flags.name)},`, "      },", "      // metrics: {", "      //   // options of the metrics registry", "      // },", "      // tracing: {", "      //   // options of the tracer", "      // },", "    }),");
+	if (flags.observability) {
+		const logging = [
+			"      logging: {",
+			`        name: ${quote(flags.name)},`,
+			"        // human-readable logs in development (`znight dev`), JSON logs in production",
+			flags.config ? "        pretty: container.get(AppConfig).environment === 'development'," : "        pretty: process.env['NODE_ENV'] === 'development',",
+			"      },",
+			"      metrics: false,",
+			"      tracing: false,"
+		];
+		plugins.push("    // first, so that its hooks wrap everything; metrics (with prom-client) and tracing are off", ...flags.config ? [
+			"    ObservabilityPlugin.configure(container => ({",
+			...logging,
+			"    })),"
+		] : [
+			"    ObservabilityPlugin.configure({",
+			...logging,
+			"    }),"
+		]);
+	}
 	if (flags.config) plugins.push("    // loads .env files and the environment, validates every @Config class before anything starts", "    ConfigPlugin.configure(),");
 	if (flags.messaging) plugins.push("    // in-memory broker for development: use rabbitmq(), sqs() or kafka() in production", "    MessagingPlugin.configure({ driver: memory() }),");
 	if (flags.schedule) plugins.push("    // before HttpPlugin: plugins stop in reverse order, so HTTP stops first, then running jobs drain", "    SchedulePlugin.configure(),");
@@ -2699,7 +2725,7 @@ function mainTs(flags) {
 		const port = "port: Number(process.env.PORT ?? 3000)";
 		plugins.push(adapter === void 0 ? `    HttpPlugin.configure({ ${port} }),` : `    HttpPlugin.configure({ adapter: ${adapter}, ${port} }),`);
 	}
-	if (flags.openapi) plugins.push(`    // GET /openapi.json and the API reference at /docs, with ${OPENAPI_UI_LABELS[flags.openapiUi]} (document options: src/api.ts)`, `    OpenApiPlugin.configure({ ui: ${quote(flags.openapiUi)} }),`);
+	if (flags.openapi) plugins.push(...flags.openapiUi === "none" ? ["    // GET /openapi.json, no API reference UI (document options: src/openapi.ts)", "    OpenApiPlugin.configure(),"] : [`    // GET /openapi.json and the API reference at /docs, with ${OPENAPI_UI_LABELS[flags.openapiUi]} (document options: src/openapi.ts)`, `    OpenApiPlugin.configure({ ui: ${quote(flags.openapiUi)} }),`]);
 	if (flags.graphql) plugins.push("    // POST /graphql, GET /graphql (GraphiQL in development): the schema is derived from the resolvers", "    GraphQLPlugin.configure(),");
 	if (flags.websocket) plugins.push("    // WebSocket gateways on the HTTP server's port (ws on Node.js, Bun's own WebSocket on Bun)", "    WebSocketPlugin.configure(),");
 	return `${imports.join("\n")}
@@ -2746,6 +2772,10 @@ export class AppConfig {
 
   /** Greeting used by GreetingService (APP_GREETING). */
   greeting = 'Hello'
+
+  /** Runtime environment (NODE_ENV): \`znight dev\` sets "development"; unset, the application runs as in production. */
+  @Env('NODE_ENV')
+  environment = 'production'
 }
 `;
 }
@@ -2890,17 +2920,17 @@ export class HeartbeatJobs {
 }
 `;
 }
-function apiDocument(options) {
+function openApiDocument(flags) {
 	return `import { OpenApiDocument } from '@znight/openapi'
 
-/**
- * ${options.name}
- *
- * The HTTP API of ${options.name}. Title and description of the OpenAPI document come from this
- * comment, the version from package.json.
- */
+// Options of the OpenAPI document (${flags.openapiUi === "none" ? "GET /openapi.json" : "GET /openapi.json, the API reference at /docs"}), read by the
+// compiler. The class is a marker: it is never instantiated.
 @OpenApiDocument({
-  tags: [{ name: 'Greeting', description: 'Greetings' }],
+  info: {
+    title: ${quote(flags.name)},
+    description: ${quote(`The HTTP API of ${flags.name}.`)},
+    version: '1.0.0',
+  },
 })
 export class Api {}
 `;
@@ -3151,10 +3181,10 @@ function readme(options, flags) {
 	const features = [
 		`- **HTTP** with \`@znight/http\` (${flags.adapter === "node" ? "built-in node:http server" : `${flags.adapter} adapter`})`,
 		flags.config ? "- **Configuration** with `@znight/config` (`src/app/app.config.ts`, `.env` files)" : void 0,
-		flags.observability ? "- **Observability** with `@znight/observability` (structured logs, metrics, traces)" : void 0,
+		flags.observability ? "- **Observability** with `@znight/observability` (structured logs: pretty-printed by `pino-pretty` in development, JSON in production; metrics and tracing are off in `src/main.ts`)" : void 0,
 		flags.messaging ? "- **Messaging** with `@znight/messaging` (in-memory broker in `src/main.ts`)" : void 0,
 		flags.schedule ? "- **Scheduled jobs** with `@znight/schedule` (`src/app/heartbeat.jobs.ts`)" : void 0,
-		flags.openapi ? `- **OpenAPI** with \`@znight/openapi\` (\`/openapi.json\`, ${OPENAPI_UI_LABELS[flags.openapiUi]} API reference at \`/docs\`, options in \`src/api.ts\`)` : void 0,
+		flags.openapi ? `- **OpenAPI** with \`@znight/openapi\` (\`/openapi.json\`, ${flags.openapiUi === "none" ? "" : `${OPENAPI_UI_LABELS[flags.openapiUi]} API reference at \`/docs\`, `}options in \`src/openapi.ts\`)` : void 0,
 		flags.graphql ? "- **GraphQL** with `@znight/graphql` (code-first: the schema is derived from `src/app/greeting.resolver.ts`)" : void 0,
 		flags.websocket ? "- **WebSocket** with `@znight/websocket` (`src/app/greeting.gateway.ts`, on the HTTP port at `/ws`)" : void 0
 	].filter((line) => line !== void 0);
@@ -3172,7 +3202,7 @@ function readme(options, flags) {
 	const tree = [
 		"src/",
 		"├─ main.ts                    # Application.create() + plugins + start()",
-		flags.openapi ? "├─ api.ts                     # @OpenApiDocument: title, tags, security of openapi.json" : void 0,
+		flags.openapi ? "├─ openapi.ts                 # @OpenApiDocument: title, description, version of openapi.json" : void 0,
 		"├─ .znight/                   # generated DI container (git-ignored)",
 		"└─ app/",
 		...app.map((line, index) => `   ${index === app.length - 1 ? "└─" : "├─"} ${line}`),
@@ -3184,9 +3214,9 @@ function readme(options, flags) {
 	const configNote = flags.config ? `
 ## Configuration
 
-\`AppConfig\` (\`src/app/app.config.ts\`) reads \`PORT\` and \`APP_GREETING\` from the environment or from
-\`.env\` / \`.env.local\` files. Missing or invalid values stop the application at boot with every
-problem listed.${flags.bun ? `
+\`AppConfig\` (\`src/app/app.config.ts\`) reads \`PORT\`, \`APP_GREETING\` and \`NODE_ENV\` from the environment
+or from \`.env\` / \`.env.local\` files. Missing or invalid values stop the application at boot with
+every problem listed.${flags.bun ? `
 
 \`bunfig.toml\` turns Bun's own \`.env\` loading off (\`env = false\`): the files are read by
 \`@znight/config\`, the same way on Node.js and Bun.` : ""}
@@ -3230,7 +3260,7 @@ ${flags.openapi ? `| \`${run("openapi")}\` | Write \`openapi.json\` (commit it;
 ${run("dev")}
 curl localhost:3000/health
 curl localhost:3000/greetings/Ada?excited=true
-curl -X POST localhost:3000/greetings -H 'content-type: application/json' -d '{"name":"Grace"}'${flags.openapi ? "\ncurl localhost:3000/openapi.json        # the API reference is at http://localhost:3000/docs" : ""}${flags.graphql ? `\ncurl localhost:3000/graphql -H 'content-type: application/json' -d '{"query":"{ greeting(name: \\"Ada\\") { message } }"}'` : ""}
+curl -X POST localhost:3000/greetings -H 'content-type: application/json' -d '{"name":"Grace"}'${flags.openapi ? `\ncurl localhost:3000/openapi.json${flags.openapiUi === "none" ? "" : "        # the API reference is at http://localhost:3000/docs"}` : ""}${flags.graphql ? `\ncurl localhost:3000/graphql -H 'content-type: application/json' -d '{"query":"{ greeting(name: \\"Ada\\") { message } }"}'` : ""}
 \`\`\`
 
 ## Project structure
@@ -3311,8 +3341,12 @@ const newCommand = defineCommand({
 		},
 		"openapi-ui": {
 			type: "enum",
-			options: ["scalar", "swagger"],
-			description: "API reference UI of the openapi feature, served at /docs (default: scalar)"
+			options: [
+				"scalar",
+				"swagger",
+				"none"
+			],
+			description: "API reference UI of the openapi feature, served at /docs, or none (default: scalar)"
 		},
 		docker: {
 			type: "boolean",
@@ -4262,4 +4296,4 @@ function stackOf(error) {
 }
 export { CancelledError as _, planSchematic as a, UsageError as b, FEATURES as c, AppSupervisor as d, createContext as f, defineCommand as g, loadCompiler as h, findSchematic as i, HTTP_ADAPTERS as l, adaptCompilerModule as m, main as n, renderProject as o, cliVersion as p, SCHEMATICS as r, DEFAULT_FEATURES as s, COMMANDS as t, PACKAGE_MANAGERS as u, CliError as v, ExitCode as y };
 
-//# sourceMappingURL=main-CoWyMPKl.mjs.map
+//# sourceMappingURL=main-D_BXiYBu.mjs.map