create-nexwire 4.3.0 → 4.4.0

package/fastify/src/framework/http/openapi.ts

@@ -0,0 +1,48 @@
+import fs from "node:fs";
+import path from "node:path";
+import swagger from "@fastify/swagger";
+import scalarApiReference from "@scalar/fastify-api-reference";
+import type { FastifyInstance } from "fastify";
+import { jsonSchemaTransform } from "fastify-type-provider-zod";
+import { openApiConfig } from "@/config/index.js";
+
+/**
+ * Why: Registers the OpenAPI document and interactive docs UI.
+ * When: OPEN_API is enabled during app boot.
+ * Where: HTTP app setup, before module routes.
+ * How: `@fastify/swagger` collects route schemas through the Zod transform;
+ *      Scalar renders them at the configured docs path.
+ */
+export function configureOpenApi(app: FastifyInstance) {
+  const { specUrl, docsPath, favicon, ...scalarOptions } = openApiConfig.scalar;
+
+  app.register(swagger, {
+    openapi: {
+      openapi: openApiConfig.version,
+      info: {
+        title: openApiConfig.title,
+        version: openApiConfig.apiVersion,
+        ...(openApiConfig.description ? { description: openApiConfig.description } : {})
+      }
+    },
+    transform: jsonSchemaTransform
+  });
+
+  app.get(specUrl, { schema: { hide: true } }, async () => app.swagger());
+
+  if (favicon) {
+    app.get("/favicon.ico", { schema: { hide: true } }, async (_request, reply) => {
+      const faviconPath = path.join(process.cwd(), favicon);
+      if (!fs.existsSync(faviconPath)) return reply.code(404).send();
+      return reply.type("image/x-icon").send(fs.readFileSync(faviconPath));
+    });
+  }
+
+  app.register(scalarApiReference, {
+    routePrefix: docsPath,
+    configuration: {
+      url: specUrl,
+      ...scalarOptions
+    }
+  });
+}

package/fastify/src/framework/http/ratelimiter.ts

@@ -0,0 +1,47 @@
+import rateLimit from "@fastify/rate-limit";
+import type { FastifyInstance } from "fastify";
+import { openApiConfig, rateLimitConfig } from "@/config/index.js";
+
+const skipPaths = new Set([
+  "/health",
+  "/ready",
+  "/live",
+  "/metrics",
+  openApiConfig.scalar.specUrl,
+  openApiConfig.scalar.docsPath
+]);
+
+function isInfrastructurePath(pathname: string) {
+  return (
+    skipPaths.has(pathname) ||
+    pathname.startsWith(`${openApiConfig.scalar.docsPath}/`) ||
+    pathname.startsWith("/queues") ||
+    pathname.startsWith("/storage") ||
+    pathname.startsWith("/socket.io")
+  );
+}
+
+/**
+ * Why: Protects the API from burst abuse and accidental flooding.
+ * When: Applied globally while the app boots.
+ * Where: App plugin stack.
+ * How: Fastify's rate-limit plugin uses an in-memory store, matching the Express
+ *      engine. Infrastructure paths are excluded so probes and docs stay usable.
+ */
+export function registerRateLimit(app: FastifyInstance) {
+  app.register(rateLimit, {
+    global: true,
+    max: rateLimitConfig.maxRequests,
+    timeWindow: rateLimitConfig.windowMs,
+    enableDraftSpec: true,
+    allowList: (request) => isInfrastructurePath((request.url || "").split("?")[0])
+  });
+}
+
+/**
+ * Stricter limit for the login route. Passed as `config.rateLimit` on the route.
+ */
+export const loginLimiter = {
+  max: rateLimitConfig.loginMaxRequests,
+  timeWindow: rateLimitConfig.windowMs
+};

package/fastify/src/framework/http/security.ts

@@ -0,0 +1,25 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { securityConfig } from "@/config/index.js";
+
+/**
+ * Why: Sets browser security response headers (CSP, HSTS, X-Frame).
+ * When: Every incoming HTTP request.
+ * Where: App request lifecycle, after CORS and session.
+ * How: All headers disabled when securityConfig.enabled is false.
+ *      HSTS only applied when the request is HTTPS.
+ */
+export async function securityHook(request: FastifyRequest, reply: FastifyReply) {
+  if (!securityConfig.enabled) return;
+
+  reply.header("Content-Security-Policy", securityConfig.csp);
+
+  const forwardedProto = request.headers["x-forwarded-proto"];
+  const isHttps = forwardedProto === "https" || request.protocol === "https";
+  if (securityConfig.hsts && isHttps) {
+    reply.header("Strict-Transport-Security", securityConfig.hstsMaxAge);
+  }
+
+  reply.header("X-Frame-Options", securityConfig.xFrame);
+  reply.header("X-Content-Type-Options", "nosniff");
+  reply.header("Referrer-Policy", "strict-origin-when-cross-origin");
+}

package/fastify/src/framework/http/static.ts

@@ -0,0 +1,83 @@
+import fs from "node:fs";
+import path from "node:path";
+import fastifyStatic from "@fastify/static";
+import type { FastifyInstance } from "fastify";
+
+const publicDir = path.resolve(process.cwd(), "public");
+const storageDir = path.resolve(process.cwd(), "src/storage/app/public");
+
+export function hasUiBuild() {
+  return fs.existsSync(path.join(publicDir, "index.html"));
+}
+
+export function ensurePublicDir() {
+  fs.mkdirSync(publicDir, { recursive: true });
+}
+
+/**
+ * Why: Serves uploaded public files and, when present, the built SPA.
+ * When: App boot.
+ * Where: HTTP app setup.
+ * How: `@fastify/static` mounts storage under `/storage/`; the UI build is
+ *      served with `wildcard: false`, so only real build files get a route. An
+ *      unknown `/api/...` path therefore falls through to the JSON 404 handler
+ *      instead of being swallowed by a catch-all static route.
+ */
+export function registerStatic(app: FastifyInstance) {
+  if (fs.existsSync(storageDir)) {
+    app.register(fastifyStatic, {
+      root: storageDir,
+      prefix: "/storage/",
+      decorateReply: false
+    });
+  }
+
+  if (hasUiBuild()) {
+    app.register(fastifyStatic, { root: publicDir, wildcard: false, redirect: true });
+  }
+}
+
+/**
+ * Why: Identifies paths that must never receive the SPA shell.
+ * When: A request reaches the not-found handler.
+ * Where: SPA fallback resolution.
+ * How: API, storage, queue, socket, and metrics paths all keep JSON 404s.
+ */
+export function isInfrastructurePath(pathname: string) {
+  return (
+    pathname.startsWith("/api") ||
+    pathname.startsWith("/storage") ||
+    pathname.startsWith("/queues") ||
+    pathname.startsWith("/socket.io") ||
+    pathname === "/metrics"
+  );
+}
+
+/**
+ * Why: Decides between the SPA shell and a JSON 404.
+ * When: A request reaches the not-found handler.
+ * Where: `registerSpaFallback`.
+ * How: Only GET requests outside infrastructure paths get the shell, and only
+ *      when a build actually exists.
+ */
+export function resolveSpaFallback(method: string, pathname: string, hasBuild: boolean) {
+  return method === "GET" && !isInfrastructurePath(pathname) && hasBuild ? "spa" : "json";
+}
+
+/**
+ * Why: Falls back to the SPA shell for client-side routes and returns JSON 404
+ *      for API paths.
+ * When: No route or static file matched.
+ * Where: End of the HTTP setup.
+ */
+export function registerSpaFallback(app: FastifyInstance) {
+  app.setNotFoundHandler((request, reply) => {
+    const pathname = (request.url || "").split("?")[0];
+
+    if (resolveSpaFallback(request.method, pathname, hasUiBuild()) === "spa") {
+      return reply.sendFile("index.html");
+    }
+
+    return reply.code(404).send({ message: `Route not found: ${request.method} ${pathname}` });
+  });
+}

package/fastify/src/framework/http/validation.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+
+/**
+ * Why: Documents the error contract Fastify actually returns for bad input.
+ * When: Any route declares a 422 response.
+ * Where: Route schemas, alongside the body/params schema that can fail.
+ * How: Fastify serializes error responses through the route's response schema,
+ *      so a 422 must be described as the Zod error shape — not `{ message }`.
+ */
+export const ValidationErrorSchema = z.object({
+  success: z.literal(false),
+  error: z.object({
+    name: z.string(),
+    issues: z.array(
+      z.object({
+        path: z.array(z.union([z.string(), z.number()])),
+        message: z.string(),
+        code: z.string()
+      })
+    )
+  })
+});
+
+/**
+ * Why: Validates data outside of Fastify's route schema pipeline.
+ * When: Controllers or services need to parse a payload by hand (e.g. a value
+ *       built at runtime rather than read straight from the request).
+ * Where: Anywhere the framework exposes a manual parse boundary.
+ * How: Throws an Error with `statusCode = 422`; the global error handler turns
+ *      it into the same `{ success:false, error:{ name, issues } }` contract the
+ *      route-level validator produces.
+ */
+export async function validate<T extends z.ZodType>(schema: T, data: unknown): Promise<z.infer<T>> {
+  const result = await schema.safeParseAsync(data);
+
+  if (!result.success) {
+    const error = new Error("Validation failed") as Error & {
+      statusCode: number;
+      success: boolean;
+      error: { name: string; issues: z.core.$ZodIssue[] };
+    };
+    error.statusCode = 422;
+    error.success = false;
+    error.error = { name: result.error.name, issues: result.error.issues };
+    throw error;
+  }
+
+  return result.data;
+}

package/fastify/src/framework/kernel.ts

@@ -0,0 +1,43 @@
+import { appConfig } from "@/config/index.js";
+import { validateConfig } from "@/config/validate.js";
+import { initDatabase } from "@/framework/database/connection.js";
+import { createHttpApp } from "@/framework/http/app.js";
+import { ensurePublicDir, registerSpaFallback } from "@/framework/http/static.js";
+import { registerModuleRoutes } from "@/framework/modules/routes.js";
+import { loadProviders } from "@/framework/providers/loader.js";
+import { bootQueueJobs } from "@/framework/queue/queue.js";
+import { setupQueueDashboard } from "@/framework/queue/ui.js";
+import { initRedis } from "@/framework/redis/client.js";
+import { storage } from "@/framework/storage/storage.js";
+
+/**
+ * Why: Assembles app kernel and boots all framework dependencies.
+ * When: HTTP server startup.
+ * Where: Called by server runtime entrypoint.
+ * How: Initializes storage/db/redis/queues/events/routes and optional UI.
+ */
+export async function createKernel() {
+  validateConfig();
+
+  await storage.init();
+
+  await initRedis();
+
+  const app = createHttpApp();
+
+  await initDatabase();
+  await loadProviders();
+  await bootQueueJobs();
+  await registerModuleRoutes(app);
+
+  const queueDashboard = await setupQueueDashboard();
+  await queueDashboard.route(app);
+
+  if (appConfig.uiEnabled) {
+    ensurePublicDir();
+  }
+
+  registerSpaFallback(app);
+
+  return { app, bullBoard: queueDashboard };
+}

package/fastify/src/framework/maker-cli/db/core.mjs

@@ -0,0 +1,291 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { glob } from "glob";
+import { databaseNameFromUrl, databaseUrl, detectDialect, parsedDatabaseUrl, sqlitePathFromUrl } from "../utils/env-db.mjs";
+import { packageScript, runCommand, runNodeScript } from "../utils/process.mjs";
+
+/** Detect SQL dialect from raw SQL content by matching against known syntax hints. */
+export function detectMigrationDialectFromSql(sql = "") {
+  const source = sql.toLowerCase();
+  if (!source.trim()) return "unknown";
+
+  const postgresHints = ["generated always as identity", "bigserial", "serial", "timestamp with time zone", "public."];
+  const mysqlHints = ["auto_increment", "engine=", "`"];
+  const sqliteHints = ["autoincrement", "pragma"];
+
+  if (postgresHints.some((hint) => source.includes(hint))) return "postgresql";
+  // SQLite output quotes identifiers with backticks too, so the distinctive
+  // hints must be tested before the MySQL ones or every SQLite migration is
+  // misread as MySQL and the history is reset on the next generate.
+  if (sqliteHints.some((hint) => source.includes(hint))) return "sqlite";
+  if (mysqlHints.some((hint) => source.includes(hint))) return "mysql";
+  return "unknown";
+}
+
+/** List existing migration .sql files for the current dialect, sorted. */
+export async function migrationFiles() {
+  const files = await glob(`src/database/migrations/${detectDialect()}/*.sql`, {
+    cwd: process.cwd(),
+    nodir: true,
+    windowsPathsNoEscape: true
+  });
+  return files.sort();
+}
+
+/** Generate drizzle-kit CLI args for migration generation. Uses --name init for the first migration. */
+export async function drizzleGenerateArgs() {
+  const files = await migrationFiles();
+  if (!files.length) return ["generate", "--name", "init"];
+  return ["generate"];
+}
+
+/** Create MySQL database if it does not exist. Uses DATABASE_URL credentials. */
+async function ensureMysqlDatabaseExists() {
+  const targetUrl = parsedDatabaseUrl();
+  const database = databaseNameFromUrl(targetUrl);
+  if (!targetUrl || !database) return;
+  const mysql = await import("mysql2/promise");
+  const connection = await mysql.createConnection({
+    host: targetUrl.hostname,
+    port: targetUrl.port ? Number(targetUrl.port) : 3306,
+    user: decodeURIComponent(targetUrl.username || "root"),
+    password: decodeURIComponent(targetUrl.password || ""),
+    database: "mysql",
+    ssl: targetUrl.searchParams.get("ssl") === "true" ? {} : undefined
+  });
+  try {
+    const [rows] = await connection.query("SELECT SCHEMA_NAME as name FROM information_schema.SCHEMATA WHERE SCHEMA_NAME = ?", [database]);
+    const exists = Array.isArray(rows) && rows.length > 0;
+    if (!exists) {
+      const safe = database.replace(/`/g, "``");
+      await connection.query(`CREATE DATABASE \`${safe}\``);
+      console.log(`Created MySQL database: ${database}`);
+    }
+  } finally {
+    await connection.end();
+  }
+}
+
+/** Create Postgres database if it does not exist. Uses DATABASE_URL credentials. */
+async function ensurePostgresDatabaseExists() {
+  const targetUrl = parsedDatabaseUrl();
+  const database = databaseNameFromUrl(targetUrl);
+  if (!targetUrl || !database) return;
+  const postgres = (await import("postgres")).default;
+  const admin = postgres({
+    host: targetUrl.hostname,
+    port: targetUrl.port ? Number(targetUrl.port) : 5432,
+    user: decodeURIComponent(targetUrl.username || "postgres"),
+    password: decodeURIComponent(targetUrl.password || ""),
+    database: "postgres",
+    ssl: targetUrl.searchParams.get("ssl") === "true" ? "require" : false
+  });
+  try {
+    const rows = await admin.unsafe("SELECT 1 FROM pg_database WHERE datname = $1", [database]);
+    if (!rows.length) {
+      const safe = database.replace(/"/g, '""');
+      await admin.unsafe(`CREATE DATABASE "${safe}"`);
+      console.log(`Created Postgres database: ${database}`);
+    }
+  } finally {
+    await admin.end();
+  }
+}
+
+/** Ensure the database exists for the current DATABASE_URL dialect. Creates it if missing (MySQL/Postgres). */
+export async function ensureDatabaseExists() {
+  const dialect = detectDialect();
+  if (dialect === "sqlite") {
+    await ensureDatabaseDirectory();
+    return;
+  }
+  if (dialect === "mysql") {
+    await ensureMysqlDatabaseExists();
+    return;
+  }
+  if (dialect === "postgresql") {
+    await ensurePostgresDatabaseExists();
+  }
+}
+
+/** Resolve the filesystem path for the SQLite database file. */
+function sqliteDatabasePath() {
+  return path.resolve(process.cwd(), sqlitePathFromUrl(databaseUrl()));
+}
+
+/** Delete and recreate the SQLite database file. */
+async function resetSqliteDatabase() {
+  const file = sqliteDatabasePath();
+  await fs.rm(file, { force: true });
+  await fs.mkdir(path.dirname(file), { recursive: true });
+}
+
+/** Drop and recreate the MySQL database. */
+async function resetMysqlDatabase() {
+  const targetUrl = parsedDatabaseUrl();
+  const database = databaseNameFromUrl(targetUrl);
+  if (!targetUrl || !database) return;
+  const mysql = await import("mysql2/promise");
+  const connection = await mysql.createConnection({
+    host: targetUrl.hostname,
+    port: targetUrl.port ? Number(targetUrl.port) : 3306,
+    user: decodeURIComponent(targetUrl.username || "root"),
+    password: decodeURIComponent(targetUrl.password || ""),
+    database: "mysql",
+    ssl: targetUrl.searchParams.get("ssl") === "true" ? {} : undefined
+  });
+  try {
+    const safe = database.replace(/`/g, "``");
+    await connection.query(`DROP DATABASE IF EXISTS \`${safe}\``);
+    await connection.query(`CREATE DATABASE \`${safe}\``);
+  } finally {
+    await connection.end();
+  }
+}
+
+/** Drop and recreate the Postgres database. Terminates active connections first. */
+async function resetPostgresDatabase() {
+  const targetUrl = parsedDatabaseUrl();
+  const database = databaseNameFromUrl(targetUrl);
+  if (!targetUrl || !database) return;
+  const postgres = (await import("postgres")).default;
+  const admin = postgres({
+    host: targetUrl.hostname,
+    port: targetUrl.port ? Number(targetUrl.port) : 5432,
+    user: decodeURIComponent(targetUrl.username || "postgres"),
+    password: decodeURIComponent(targetUrl.password || ""),
+    database: "postgres",
+    ssl: targetUrl.searchParams.get("ssl") === "true" ? "require" : false
+  });
+  try {
+    const safe = database.replace(/"/g, '""');
+    await admin.unsafe("SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = $1 AND pid <> pg_backend_pid()", [database]);
+    await admin.unsafe(`DROP DATABASE IF EXISTS "${safe}"`);
+    await admin.unsafe(`CREATE DATABASE "${safe}"`);
+  } finally {
+    await admin.end();
+  }
+}
+
+/** Drop and recreate the database for the current dialect. */
+export async function resetDatabase() {
+  const dialect = detectDialect();
+  if (dialect === "sqlite") return await resetSqliteDatabase();
+  if (dialect === "mysql") return await resetMysqlDatabase();
+  if (dialect === "postgresql") return await resetPostgresDatabase();
+}
+
+/** Check if the database has existing app tables (excluding drizzle meta tables). */
+export async function hasExistingAppTables() {
+  const dialect = detectDialect();
+  if (dialect === "sqlite") {
+    const libsql = await import("@libsql/client");
+    const file = sqliteDatabasePath();
+    const client = libsql.createClient({ url: `file:${file.replace(/\\/g, "/")}` });
+    try {
+      const result = await client.execute(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name != '__drizzle_migrations'"
+      );
+      return result.rows.length > 0;
+    } finally {
+      client.close();
+    }
+  }
+
+  if (dialect === "mysql") {
+    const mysql = await import("mysql2/promise");
+    const connection = await mysql.createConnection(databaseUrl());
+    try {
+      const [rows] = await connection.query(
+        "SELECT table_name as name FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name != '__drizzle_migrations'"
+      );
+      return Array.isArray(rows) && rows.length > 0;
+    } finally {
+      await connection.end();
+    }
+  }
+
+  const postgres = (await import("postgres")).default;
+  const client = postgres(databaseUrl());
+  try {
+    const rows = await client.unsafe("SELECT tablename FROM pg_tables WHERE schemaname = 'public' AND tablename != '__drizzle_migrations'");
+    return rows.length > 0;
+  } finally {
+    await client.end();
+  }
+}
+
+/** Run the application seed script via tsx or Bun. */
+export async function runSeed(moduleName = "") {
+  const seedArgs = ["src/framework/database/seed.ts"];
+  if (moduleName) seedArgs.push(`--module=${moduleName}`);
+  if (process.versions?.bun) {
+    await runCommand("bun", seedArgs);
+    return;
+  }
+  await runNodeScript(packageScript("tsx", "dist/cli.mjs"), seedArgs);
+}
+
+/** Ensure the SQLite database directory exists. No-op for MySQL/Postgres. */
+export async function ensureDatabaseDirectory() {
+  if (detectDialect() !== "sqlite") return;
+  const file = path.resolve(process.cwd(), sqlitePathFromUrl(databaseUrl()));
+  await fs.mkdir(path.dirname(file), { recursive: true });
+}
+
+/** Ensure the drizzle migration meta directory and _journal.json exist. */
+export async function ensureMigrationMeta() {
+  const migrationRoot = path.resolve(process.cwd(), "src/database/migrations", detectDialect());
+  const metaRoot = path.join(migrationRoot, "meta");
+  const journalPath = path.join(metaRoot, "_journal.json");
+  await fs.mkdir(metaRoot, { recursive: true });
+  try {
+    await fs.access(journalPath);
+  } catch {
+    const dialect = detectDialect();
+    const journalDialect = dialect === "postgresql" ? "postgresql" : dialect;
+    await fs.writeFile(
+      journalPath,
+      `{
+  "version": "7",
+  "dialect": "${journalDialect}",
+  "entries": []
+}
+`
+    );
+  }
+}
+
+/** Sync the migration dialect to match the current DATABASE_URL. Resets migrations if dialect changed. */
+export async function syncMigrationDialect() {
+  async function existingMigrationDialect() {
+    const files = await migrationFiles();
+    if (!files.length) return null;
+    const first = await fs.readFile(path.resolve(process.cwd(), files[0]), "utf8");
+    return detectMigrationDialectFromSql(first);
+  }
+
+  async function resetMigrationFiles() {
+    const migrationRoot = path.resolve(process.cwd(), "src/database/migrations", detectDialect());
+    const dialect = detectDialect();
+    const journalDialect = dialect === "postgresql" ? "postgresql" : dialect;
+    await fs.rm(migrationRoot, { recursive: true, force: true });
+    await fs.mkdir(path.join(migrationRoot, "meta"), { recursive: true });
+    await fs.writeFile(
+      path.join(migrationRoot, "meta", "_journal.json"),
+      `{
+  "version": "7",
+  "dialect": "${journalDialect}",
+  "entries": []
+}
+`
+    );
+    console.log("Reset existing migration files due to dialect change.");
+  }
+
+  const target = detectDialect();
+  const current = await existingMigrationDialect();
+  if (!current || current === "unknown" || current === target) return;
+  console.log(`Migration dialect changed (${current} -> ${target}). Regenerating migration files for current DATABASE_URL.`);
+  await resetMigrationFiles();
+}