zudojs-cli 2.0.1 → 2.1.1

package/dist/src/templates/backendApp/parts/config.template.js

@@ -0,0 +1,118 @@
+/**
+ * zudojs-cli — Generated `src/configs/index.ts` and `.env.example`.
+ *
+ * Configuration is read from the environment through @zudojs/config and
+ * returned as one frozen, typed object. `zudojs add <feature>` inserts that
+ * feature's section between the `config` markers and its variables into
+ * `.env.example`, so the two stay in sync.
+ */
+import { renderMarkerBlock, MARKERS } from "../../../wiring/index.js";
+/** Variables every generated app reads. */
+export function baseEnvVariables(port) {
+    return [
+        { name: "NODE_ENV", value: "development" },
+        { name: "HOST", value: "0.0.0.0" },
+        { name: "PORT", value: String(port) },
+        {
+            name: "CORS_ORIGINS",
+            value: "",
+            comment: "Comma-separated origins allowed to call the API from a browser (empty: none)",
+        },
+        { name: "RATE_LIMIT_WINDOW_MS", value: "60000", comment: "Requests allowed per client per window" },
+        { name: "RATE_LIMIT_MAX", value: "300" },
+    ];
+}
+/** Renders `.env.example` lines for `variables`. */
+export function renderEnvVariables(variables) {
+    return variables
+        .map((v) => `${v.comment ? `# ${v.comment}\n` : ""}${v.name}=${v.value}`)
+        .join("\n");
+}
+/**
+ * Renders `src/configs/index.ts`. `sections` are single-line object entries
+ * (for example `redis: Object.freeze({ url: text(config, "redis_url", "...") }),`)
+ * placed between the config markers.
+ */
+export function renderConfigFile(options) {
+    return `import { ConfigurationError } from "@zudojs/errors";
+import {
+  createConfigManager,
+  createEnvironmentConfigSource,
+  type ConfigManager,
+} from "@zudojs/config";
+
+const DEFAULT_PORT = ${options.defaultPort};
+
+/** Loads \`.env\` into process.env when it exists; real variables win. */
+function loadDotEnv(): void {
+  try {
+    process.loadEnvFile(".env");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+}
+
+/** A string setting, or \`fallback\` when the variable is unset. */
+export function text(config: ConfigManager, key: string, fallback: string): string {
+  return config.string(key, fallback) ?? fallback;
+}
+
+/** A comma-separated list setting. */
+export function list(config: ConfigManager, key: string): readonly string[] {
+  return (config.string(key, "") ?? "")
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+}
+
+/** A non-negative integer setting; anything else is a configuration error. */
+export function int(config: ConfigManager, key: string, fallback: number): number {
+  const raw = config.string(key);
+  if (raw === undefined || raw.trim() === "") return fallback;
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new ConfigurationError(\`\${key.toUpperCase()} must be a non-negative integer, got "\${raw}".\`);
+  }
+  return value;
+}
+
+/** PORT, refusing anything that is not a TCP port. */
+function port(config: ConfigManager): number {
+  const raw = config.string("port");
+  if (raw === undefined || raw.trim() === "") return DEFAULT_PORT;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0 || value > 65535) {
+    throw new ConfigurationError(\`PORT must be an integer between 0 and 65535, got "\${raw}".\`);
+  }
+  return value;
+}
+
+/**
+ * Reads the application configuration from the environment (and \`.env\`).
+ * \`zudojs add <feature>\` adds the feature's settings between the markers.
+ */
+export async function loadConfig(env: NodeJS.ProcessEnv = process.env) {
+  if (env === process.env) loadDotEnv();
+  const config = createConfigManager({
+    sources: [createEnvironmentConfigSource({ env })],
+  });
+  await config.load();
+
+  return Object.freeze({
+    nodeEnv: text(config, "node_env", "development"),
+    host: text(config, "host", "0.0.0.0"),
+    port: port(config),
+    corsOrigins: list(config, "cors_origins"),
+    rateLimit: Object.freeze({
+      windowMs: int(config, "rate_limit_window_ms", 60_000),
+      max: int(config, "rate_limit_max", 300),
+    }),
+${renderMarkerBlock(MARKERS.config, options.sections, "    ")}
+  });
+}
+
+/** The loaded configuration. */
+export type AppConfig = Awaited<ReturnType<typeof loadConfig>>;
+`;
+}
+//# sourceMappingURL=config.template.js.map

package/dist/src/templates/backendApp/parts/httpUtils.template.d.ts

@@ -0,0 +1,10 @@
+/**
+ * zudojs-cli — Generated `src/utils/http.ts`.
+ *
+ * The small helpers every generated controller and the server use: JSON
+ * responses, schema-issue responses, JSON body reading, mapping exposed
+ * 4xx errors to responses, and the @zudojs/security default headers.
+ */
+/** Renders `src/utils/http.ts`. */
+export declare function renderHttpUtils(): string;
+//# sourceMappingURL=httpUtils.template.d.ts.map

package/dist/src/templates/backendApp/parts/httpUtils.template.js

@@ -0,0 +1,103 @@
+/**
+ * zudojs-cli — Generated `src/utils/http.ts`.
+ *
+ * The small helpers every generated controller and the server use: JSON
+ * responses, schema-issue responses, JSON body reading, mapping exposed
+ * 4xx errors to responses, and the @zudojs/security default headers.
+ */
+/** Renders `src/utils/http.ts`. */
+export function renderHttpUtils() {
+    return `import {
+  badRequest,
+  createResponseContext,
+  type HttpMiddleware,
+  type HttpResponseContext,
+  type HttpRouterContext,
+} from "@zudojs/http";
+import type { SchemaIssue } from "@zudojs/schema";
+import { generateSecurityHeaders } from "@zudojs/security";
+
+/** A JSON response with \`status\`. */
+export function json(status: number, data: unknown): HttpResponseContext {
+  return createResponseContext({ status }).json(data);
+}
+
+/** A response with no body (for example 204). */
+export function empty(status: number): HttpResponseContext {
+  return createResponseContext({ status });
+}
+
+/** 400 listing where the input failed validation, without echoing it back. */
+export function validationFailed(issues: readonly SchemaIssue[]): HttpResponseContext {
+  return json(400, {
+    error: "Validation failed",
+    issues: issues.map((issue) => ({
+      path: issue.path.map(String).join("."),
+      message: issue.message,
+    })),
+  });
+}
+
+/**
+ * The request body parsed as JSON; \`undefined\` when there is none.
+ * Malformed JSON is answered with 400.
+ */
+export function readJsonBody(ctx: HttpRouterContext): unknown {
+  const body: unknown = ctx.request.body;
+  if (body === undefined || body === null) return undefined;
+  const text =
+    body instanceof Uint8Array
+      ? new TextDecoder().decode(body)
+      : typeof body === "string"
+        ? body
+        : undefined;
+  if (text === undefined) return body;
+  if (text.trim() === "") return undefined;
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    throw badRequest("The request body is not valid JSON.");
+  }
+}
+
+/**
+ * The response for an error that carries an exposed 4xx status
+ * (NotFoundError, badRequest(), ...). Anything else is left to the server,
+ * which answers a generic 500 and never leaks the message.
+ */
+export function errorResponse(error: unknown): HttpResponseContext | undefined {
+  if (typeof error !== "object" || error === null) return undefined;
+  const candidate = error as {
+    readonly statusCode?: unknown;
+    readonly expose?: unknown;
+    readonly message?: unknown;
+    readonly code?: unknown;
+  };
+  const status = candidate.statusCode;
+  if (typeof status !== "number" || status < 400 || status > 499) return undefined;
+  if (candidate.expose !== true || typeof candidate.message !== "string") return undefined;
+  return json(status, {
+    error: candidate.message,
+    ...(typeof candidate.code === "string" ? { code: candidate.code } : {}),
+  });
+}
+
+/**
+ * Adds the @zudojs/security default headers (CSP, HSTS, nosniff,
+ * X-Frame-Options DENY, ...) to every response that does not set its own:
+ * the /docs page, for instance, sends a CSP that allows its assets.
+ */
+export function securityHeaders(): HttpMiddleware {
+  const defaults = Object.entries(generateSecurityHeaders());
+  return async (_context, next) => {
+    const response = (await next()).clone();
+    const present = new Set(Object.keys(response.headers).map((name) => name.toLowerCase()));
+    for (const [name, value] of defaults) {
+      if (!present.has(name.toLowerCase())) response.setHeader(name, value);
+    }
+    return response;
+  };
+}
+`;
+}
+//# sourceMappingURL=httpUtils.template.js.map

package/dist/src/templates/backendApp/parts/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * zudojs-cli — Pieces of a generated backend app: configuration, route and
+ * container wiring, integrations and HTTP helpers.
+ */
+export * from "./config.template.js";
+export * from "./httpUtils.template.js";
+export * from "./integrations.template.js";
+export * from "./wiring.template.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/templates/backendApp/parts/index.js

@@ -0,0 +1,9 @@
+/**
+ * zudojs-cli — Pieces of a generated backend app: configuration, route and
+ * container wiring, integrations and HTTP helpers.
+ */
+export * from "./config.template.js";
+export * from "./httpUtils.template.js";
+export * from "./integrations.template.js";
+export * from "./wiring.template.js";
+//# sourceMappingURL=index.js.map

package/dist/src/templates/backendApp/parts/integrations.template.d.ts

@@ -0,0 +1,16 @@
+/**
+ * zudojs-cli — Generated `src/integrations/`.
+ *
+ * An integration is a client with a lifecycle (Redis, a database, a
+ * WebSocket server, a mail transport). `integrations/index.ts` lists them
+ * between markers; `integration.ts` runs the list as one runtime module,
+ * so they start with `runtime.start()` and stop, in reverse, with
+ * `runtime.stop()`. `zudojs add <feature>` writes `integrations/<name>.ts`
+ * and registers it.
+ */
+import type { MarkerLines } from "./wiring.template.js";
+/** Renders `src/integrations/index.ts`. */
+export declare function renderIntegrationsIndex(lines: MarkerLines): string;
+/** Renders `src/integrations/integration.ts`. */
+export declare function renderIntegrationContract(): string;
+//# sourceMappingURL=integrations.template.d.ts.map

package/dist/src/templates/backendApp/parts/integrations.template.js

@@ -0,0 +1,115 @@
+/**
+ * zudojs-cli — Generated `src/integrations/`.
+ *
+ * An integration is a client with a lifecycle (Redis, a database, a
+ * WebSocket server, a mail transport). `integrations/index.ts` lists them
+ * between markers; `integration.ts` runs the list as one runtime module,
+ * so they start with `runtime.start()` and stop, in reverse, with
+ * `runtime.stop()`. `zudojs add <feature>` writes `integrations/<name>.ts`
+ * and registers it.
+ */
+import { MARKERS, renderMarkerBlock } from "../../../wiring/index.js";
+/** Renders `src/integrations/index.ts`. */
+export function renderIntegrationsIndex(lines) {
+    return `import type { Integration } from "./integration.js";
+${renderMarkerBlock(MARKERS.integrationImports, lines.imports)}
+
+export {
+  IntegrationsModule,
+  checkIntegrations,
+  drainIntegrations,
+  type Integration,
+  type IntegrationContext,
+} from "./integration.js";
+
+/**
+ * Started with the runtime in this order and stopped in reverse.
+ * \`zudojs add <feature>\` adds entries between the markers.
+ */
+export const integrations: readonly Integration[] = [
+${renderMarkerBlock(MARKERS.integrations, lines.entries, "  ")}
+];
+`;
+}
+/** Renders `src/integrations/integration.ts`. */
+export function renderIntegrationContract() {
+    return `import type { Server } from "node:http";
+
+import { BaseModule, type ModuleContext } from "@zudojs/core";
+
+import type { AppConfig } from "../configs/index.js";
+
+/** What an integration receives when it starts. */
+export interface IntegrationContext {
+  readonly config: AppConfig;
+  readonly logger: ModuleContext["logger"];
+  /** The Node HTTP server, for integrations that attach to it (WebSockets). */
+  readonly httpServer?: Server;
+}
+
+/** A client or server with a lifecycle, started and stopped with the runtime. */
+export interface Integration {
+  readonly name: string;
+  start(context: IntegrationContext): Promise<void>;
+  stop(): Promise<void>;
+  /** Called when shutdown begins, before HTTP stops: close long-lived connections. */
+  drain?(): Promise<void>;
+  /** Whether the integration is healthy; reported by /health. */
+  health?(): Promise<boolean>;
+}
+
+/** Runs the integrations as one runtime module. */
+export class IntegrationsModule extends BaseModule {
+  public readonly id = "integrations";
+  public readonly name = "integrations";
+  private readonly started: Integration[] = [];
+
+  public constructor(
+    private readonly entries: readonly Integration[],
+    private readonly startContext: Omit<IntegrationContext, "logger">,
+  ) {
+    super({ version: "0.1.0" });
+  }
+
+  public override async onInitialize(context: ModuleContext): Promise<void> {
+    for (const integration of this.entries) {
+      await integration.start({ ...this.startContext, logger: context.logger });
+      this.started.push(integration);
+      context.logger.info(\`\${integration.name} started\`);
+    }
+  }
+
+  public override async onShutdown(context: ModuleContext): Promise<void> {
+    for (const integration of [...this.started].reverse()) {
+      try {
+        await integration.stop();
+      } catch (error) {
+        context.logger.error(\`\${integration.name} failed to stop\`, { error });
+      }
+    }
+    this.started.length = 0;
+  }
+}
+
+/** Lets each integration close long-lived connections before HTTP stops. */
+export async function drainIntegrations(integrations: readonly Integration[]): Promise<void> {
+  for (const integration of integrations) {
+    await integration.drain?.().catch(() => undefined);
+  }
+}
+
+/** Health of every integration that reports one. */
+export async function checkIntegrations(
+  integrations: readonly Integration[],
+): Promise<Record<string, "up" | "down">> {
+  const checks: Record<string, "up" | "down"> = {};
+  for (const integration of integrations) {
+    if (integration.health === undefined) continue;
+    const healthy = await integration.health().catch(() => false);
+    checks[integration.name] = healthy ? "up" : "down";
+  }
+  return checks;
+}
+`;
+}
+//# sourceMappingURL=integrations.template.js.map

package/dist/src/templates/backendApp/parts/wiring.template.d.ts

@@ -0,0 +1,26 @@
+/**
+ * zudojs-cli — Generated route registration and composition root.
+ *
+ * - `src/routes/index.ts` exports `registerRoutes(router, deps)`: /health
+ *   plus every resource (and module) between the `routes` markers.
+ * - `src/modules/<name>/routes/index.ts` does the same for one module.
+ * - `src/container.ts` constructs every controller, service and repository
+ *   in one place, between the `container` markers.
+ */
+/** Lines a template pre-fills between a pair of markers. */
+export interface MarkerLines {
+    readonly imports: readonly string[];
+    readonly entries: readonly string[];
+}
+/** Renders `src/routes/index.ts`. */
+export declare function renderRoutesIndex(lines: MarkerLines): string;
+/**
+ * Renders `routes/index.ts` of a module: `register<Module>ModuleRoutes`.
+ * `containerFromHere` is the import path of `container.js`.
+ */
+export declare function renderModuleRoutesIndex(functionName: string, containerFromHere: string, lines?: MarkerLines): string;
+/** Renders `src/routes/health.routes.ts`. */
+export declare function renderHealthRoutes(): string;
+/** Renders `src/container.ts`. */
+export declare function renderContainer(lines: MarkerLines): string;
+//# sourceMappingURL=wiring.template.d.ts.map

package/dist/src/templates/backendApp/parts/wiring.template.js

@@ -0,0 +1,111 @@
+/**
+ * zudojs-cli — Generated route registration and composition root.
+ *
+ * - `src/routes/index.ts` exports `registerRoutes(router, deps)`: /health
+ *   plus every resource (and module) between the `routes` markers.
+ * - `src/modules/<name>/routes/index.ts` does the same for one module.
+ * - `src/container.ts` constructs every controller, service and repository
+ *   in one place, between the `container` markers.
+ */
+import { MARKERS, renderMarkerBlock } from "../../../wiring/index.js";
+/** Renders `src/routes/index.ts`. */
+export function renderRoutesIndex(lines) {
+    return `import type { HttpRouter } from "@zudojs/http";
+
+import type { AppDependencies } from "../container.js";
+import { registerHealthRoutes } from "./health.routes.js";
+${renderMarkerBlock(MARKERS.routeImports, lines.imports)}
+
+/**
+ * Registers every route of the application. \`zudojs generate resource\`
+ * and \`zudojs generate module\` add their registrations between the markers.
+ */
+export function registerRoutes(router: HttpRouter, deps: AppDependencies): void {
+  registerHealthRoutes(router, deps.health);
+${renderMarkerBlock(MARKERS.routes, lines.entries, "  ")}
+}
+`;
+}
+/**
+ * Renders `routes/index.ts` of a module: `register<Module>ModuleRoutes`.
+ * `containerFromHere` is the import path of `container.js`.
+ */
+export function renderModuleRoutesIndex(functionName, containerFromHere, lines = { imports: [], entries: [] }) {
+    return `import type { HttpRouter } from "@zudojs/http";
+
+import type { AppDependencies } from "${containerFromHere}";
+${renderMarkerBlock(MARKERS.routeImports, lines.imports)}
+
+/** Registers this module's routes; called from the app's routes/index.ts. */
+export function ${functionName}(router: HttpRouter, deps: AppDependencies): void {
+  void deps;
+${renderMarkerBlock(MARKERS.routes, lines.entries, "  ")}
+}
+`;
+}
+/** Renders `src/routes/health.routes.ts`. */
+export function renderHealthRoutes() {
+    return `import type { HttpRouter } from "@zudojs/http";
+
+import { json } from "../utils/http.js";
+
+/** What /health reports. */
+export interface HealthReport {
+  readonly ready: boolean;
+  readonly checks: Readonly<Record<string, "up" | "down">>;
+}
+
+/** Computes the current {@link HealthReport}. */
+export type HealthCheck = () => Promise<HealthReport>;
+
+/**
+ * GET /health: 200 when the runtime is running and every integration is
+ * up, 503 otherwise. Hidden from the OpenAPI document.
+ */
+export function registerHealthRoutes(router: HttpRouter, check: HealthCheck): void {
+  router.get(
+    "/health",
+    async () => {
+      const report = await check();
+      return json(report.ready ? 200 : 503, {
+        status: report.ready ? "ok" : "unavailable",
+        checks: report.checks,
+        timestamp: new Date().toISOString(),
+      });
+    },
+    { openapi: false },
+  );
+}
+`;
+}
+/** Renders `src/container.ts`. */
+export function renderContainer(lines) {
+    return `import type { HealthCheck } from "./routes/health.routes.js";
+${renderMarkerBlock(MARKERS.containerImports, lines.imports)}
+
+/** Options for {@link createDependencies}. */
+export interface DependencyOptions {
+  /** Readiness for /health; server.ts passes the runtime's. */
+  readonly health?: HealthCheck;
+}
+
+/**
+ * The composition root: every controller, service and repository is
+ * constructed here, once. \`zudojs generate resource\` adds entries between
+ * the markers; swap an implementation (e.g. a database repository) here.
+ */
+export function createDependencies(options: DependencyOptions = {}) {
+  const health: HealthCheck =
+    options.health ?? (async () => ({ ready: true, checks: {} }));
+
+  return {
+    health,
+${renderMarkerBlock(MARKERS.container, lines.entries, "    ")}
+  };
+}
+
+/** Everything route registration receives. */
+export type AppDependencies = ReturnType<typeof createDependencies>;
+`;
+}
+//# sourceMappingURL=wiring.template.js.map