create-nexwire 4.0.0

package/hono/src/config/app.ts

@@ -0,0 +1,41 @@
+import { env } from "@/env.js";
+
+/**
+ * Why: Central, code-visible application identity and runtime settings.
+ * When: Server boot, route metadata, OpenAPI titles, and URL resolution.
+ * Where: src/config/app.ts.
+ * How: App-related values intentionally stay in .env so each deployment can
+ *      set them without touching code. Feature toggles (openApi, ui)
+ *      are plain literals you can flip here.
+ */
+export const appConfig = {
+  name: env.APP_NAME,
+  environment: env.APP_ENV,
+  port: env.APP_PORT,
+  url: env.APP_URL,
+  /**
+   * frontendUrl
+   * Why: Tells the API where the SPA/UI lives when it is NOT served from
+   *      the API's own origin.
+   * When: Only set this when the UI runs on a different domain or port
+   *      than the API. Leave empty when the API serves the built SPA itself.
+   * How: Socket.IO adds it to the allowed CORS origins, and auth/session
+   *      cookies switch to SameSite=None + Secure when this origin differs
+   *      from appConfig.url (cross-site cookie handling).
+   */
+  frontendUrl: env.FRONTEND_URL,
+  openApiEnabled: env.OPEN_API,
+  /**
+   * uiEnabled
+   * Why: API-only switch. When false the API never serves the UI build:
+   *      the public dir is not prepared and the `/*` static + SPA-index
+   *      middlewares are not mounted — use this for pure API deployments.
+   * When: Set UI=false in .env for API-only mode; keep true when the API
+   *      should serve the built SPA.
+   * How: kernel.ts gates ensurePublicDir() and the static/SPA middlewares;
+   *      server.ts logs the enabled/disabled status.
+   */
+  uiEnabled: env.UI
+};
+
+export type AppConfig = typeof appConfig;

package/hono/src/config/auth.ts

@@ -0,0 +1,12 @@
+/**
+ * Why: Account/authentication policy settings.
+ * When: Register, login, and email verification flows.
+ * Where: src/config/auth.ts.
+ * How: Plain literals. `requireEmailVerification` adds a verify-email step
+ *      before a new account can log in.
+ */
+export const authConfig = {
+  requireEmailVerification: false
+};
+
+export type AuthConfig = typeof authConfig;

package/hono/src/config/cache.ts

@@ -0,0 +1,16 @@
+import { redisConfig } from "./redis.js";
+
+/**
+ * Why: Redis cache TTL defaults and key namespace.
+ * When: Cache helpers store values with an implicit expiry.
+ * Where: src/config/cache.ts.
+ * How: `ttlSeconds` is a plain literal; `keyPrefix` is derived from the
+ *      shared `REDIS_PREFIX` so cache keys stay in one namespace
+ *      (`nexwire:cache:*` by default).
+ */
+export const cacheConfig = {
+  ttlSeconds: 3600,
+  keyPrefix: `${redisConfig.prefix}:cache`
+};
+
+export type CacheConfig = typeof cacheConfig;

package/hono/src/config/cookie.ts

@@ -0,0 +1,15 @@
+import { env } from "@/env.js";
+
+/**
+ * Why: Auth/session cookie naming and signing.
+ * When: Setting, reading, and clearing signed auth cookies.
+ * Where: src/config/cookie.ts.
+ * How: `name` is a plain literal you can change here. `secret` is
+ *      confidential and stays in .env (`COOKIE_SECRET`).
+ */
+export const cookieConfig = {
+  name: "nexwire",
+  secret: env.COOKIE_SECRET
+};
+
+export type CookieConfig = typeof cookieConfig;

package/hono/src/config/cors.ts

@@ -0,0 +1,12 @@
+/**
+ * Why: CORS policy for the HTTP server.
+ * When: Global CORS middleware processes cross-origin requests.
+ * Where: src/config/cors.ts.
+ * How: `origin` accepts `"*"` for any origin or a comma-separated allow-list.
+ *      `"*"` reflects the request origin (required for credentialed requests).
+ */
+export const corsConfig = {
+  origin: "*"
+};
+
+export type CorsConfig = typeof corsConfig;

package/hono/src/config/database.ts

@@ -0,0 +1,29 @@
+import { env } from "@/env.js";
+
+/**
+ * Why: Database connection settings for Drizzle.
+ * When: Database bootstrap and dialect detection.
+ * Where: src/config/database.ts.
+ * How: The connection URL contains credentials, so it stays in .env
+ *      (`DATABASE_URL`). Dialect is derived from the URL prefix.
+ */
+export const databaseConfig = {
+  url: env.DATABASE_URL
+};
+
+export type DatabaseConfig = typeof databaseConfig;
+
+/**
+ * Why: Maps a connection URL to its Drizzle dialect.
+ * When: Selecting the pool driver and dialect-specific branching.
+ * Where: Framework database connection helpers.
+ * How: Matches the URL prefix; anything that isn't mysql/postgres is sqlite.
+ */
+export function detectDialectFrom(url: string): "sqlite" | "mysql" | "postgresql" {
+  const value = url.toLowerCase();
+  if (value.startsWith("mysql")) return "mysql";
+  if (value.startsWith("postgres")) return "postgresql";
+  return "sqlite";
+}
+
+export const databaseDialect = detectDialectFrom(databaseConfig.url);

package/hono/src/config/index.ts

@@ -0,0 +1,83 @@
+import { type AppConfig, appConfig } from "./app.js";
+import { type AuthConfig, authConfig } from "./auth.js";
+import { type CacheConfig, cacheConfig } from "./cache.js";
+import { type CookieConfig, cookieConfig } from "./cookie.js";
+import { type CorsConfig, corsConfig } from "./cors.js";
+import { type DatabaseConfig, databaseConfig } from "./database.js";
+import { type JwtConfig, jwtConfig } from "./jwt.js";
+import { type LoggingConfig, loggingConfig } from "./logging.js";
+import { type MailConfig, mailConfig } from "./mail.js";
+import { type OpenApiConfig, openApiConfig } from "./openapi.js";
+import { type QueueConfig, queueConfig } from "./queue.js";
+import { type RateLimitConfig, rateLimitConfig } from "./rateLimit.js";
+import { type RealtimeConfig, realtimeConfig } from "./realtime.js";
+import { type RedisConfig, redisConfig } from "./redis.js";
+import { type SecurityConfig, securityConfig } from "./security.js";
+import { type SessionConfig, sessionConfig } from "./session.js";
+import { type StorageConfig, storageConfig } from "./storage.js";
+
+export { appConfig } from "./app.js";
+export { authConfig } from "./auth.js";
+export { cacheConfig } from "./cache.js";
+export { cookieConfig } from "./cookie.js";
+export { corsConfig } from "./cors.js";
+export { databaseConfig } from "./database.js";
+export { jwtConfig } from "./jwt.js";
+export { loggingConfig } from "./logging.js";
+export { mailConfig } from "./mail.js";
+export { openApiConfig } from "./openapi.js";
+export { queueConfig } from "./queue.js";
+export { rateLimitConfig } from "./rateLimit.js";
+export { realtimeConfig } from "./realtime.js";
+export { redisConfig } from "./redis.js";
+export { securityConfig } from "./security.js";
+export { sessionConfig } from "./session.js";
+export { storageConfig } from "./storage.js";
+
+/**
+ * Why: Single import point for every config domain.
+ * When: Application code needs configuration values.
+ * Where: Imported as `import { config } from "@/config/index.js"`.
+ * How: Aggregates per-domain config objects; individual files remain the
+ *      place to edit each setting.
+ */
+export const config = {
+  app: appConfig,
+  auth: authConfig,
+  cache: cacheConfig,
+  cookie: cookieConfig,
+  cors: corsConfig,
+  database: databaseConfig,
+  jwt: jwtConfig,
+  logging: loggingConfig,
+  mail: mailConfig,
+  openApi: openApiConfig,
+  queue: queueConfig,
+  rateLimit: rateLimitConfig,
+  realtime: realtimeConfig,
+  redis: redisConfig,
+  session: sessionConfig,
+  security: securityConfig,
+  storage: storageConfig
+} as const;
+
+export type Config = typeof config;
+export type {
+  AppConfig,
+  AuthConfig,
+  CacheConfig,
+  CookieConfig,
+  CorsConfig,
+  DatabaseConfig,
+  JwtConfig,
+  LoggingConfig,
+  MailConfig,
+  OpenApiConfig,
+  QueueConfig,
+  RateLimitConfig,
+  RealtimeConfig,
+  RedisConfig,
+  SecurityConfig,
+  SessionConfig,
+  StorageConfig
+};

package/hono/src/config/jwt.ts

@@ -0,0 +1,19 @@
+import { env } from "@/env.js";
+
+/**
+ * Why: JWT signing and lifetime settings.
+ * When: Access/refresh token generation and verification.
+ * Where: src/config/jwt.ts.
+ * How: Signing secrets are confidential and stay in .env. Expiries are plain
+ *      literals you can tune here (seconds).
+ */
+export const jwtConfig = {
+  accessSecret: env.JWT_ACCESS_SECRET,
+  refreshSecret: env.JWT_REFRESH_SECRET,
+  accessExpirySeconds: 900,
+  refreshExpirySeconds: 3600,
+  refreshRememberExpirySeconds: 2592000,
+  algorithm: "HS256" as const
+};
+
+export type JwtConfig = typeof jwtConfig;

package/hono/src/config/logging.ts

@@ -0,0 +1,13 @@
+/**
+ * Why: Logging behavior shared by the framework logger and HTTP request log.
+ * When: Logger bootstrap and global HTTP middleware.
+ * Where: src/config/logging.ts.
+ * How: Plain literals — edit directly. `httpRequests` mirrors the old
+ *      `LOG_HTTP` switch: set `false` to quiet per-request console logs.
+ */
+export const loggingConfig = {
+  level: "info",
+  httpRequests: true
+};
+
+export type LoggingConfig = typeof loggingConfig;

package/hono/src/config/mail.ts

@@ -0,0 +1,24 @@
+import { env } from "@/env.js";
+
+/**
+ * Why: SMTP mail transport settings.
+ * When: Transactional mail (signup, reset, verify) is sent.
+ * Where: src/config/mail.ts.
+ * How: Host, ports, encryption, from address and fail-silent are plain
+ *      literals. Username/password are credentials and stay in .env.
+ */
+export const mailConfig = {
+  host: "127.0.0.1",
+  port: 1089,
+  encryption: "none",
+  username: env.MAIL_USERNAME,
+  password: env.MAIL_PASSWORD,
+  fromAddress: "no-reply@example.com",
+  failSilent: true,
+  maildev: {
+    smtpPort: 1089,
+    webPort: 1080
+  }
+};
+
+export type MailConfig = typeof mailConfig;

package/hono/src/config/openapi.ts

@@ -0,0 +1,54 @@
+import { appConfig } from "./app.js";
+
+/**
+ * Why: OpenAPI documentation settings — API metadata and Scalar UI presentation.
+ * When: OPEN_API=true during app boot.
+ * Where: src/config/openapi.ts.
+ * How: Edit this file to customise your API title, version, description,
+ *      and the Scalar docs UI appearance.
+ */
+export const openApiConfig = {
+  /** OpenAPI spec version */
+  version: "3.0.0",
+
+  /** API title shown in docs and the /doc spec */
+  title: `${appConfig.name} API`,
+
+  /** API version shown in docs */
+  apiVersion: "1.0.0",
+
+  /** Optional description shown in the /doc spec */
+  description: "",
+
+  /** Scalar docs UI settings */
+  scalar: {
+    /** URL path to the OpenAPI JSON spec */
+    specUrl: "/doc",
+
+    /** URL path to the interactive docs UI */
+    docsPath: "/api-docs",
+
+    /** UI layout: "classic" or "modern" */
+    layout: "classic" as const,
+
+    /** UI theme: "default", "moon", "purple", "solarized", "bluePlanet", "fastify", "kepler", "mars", "nebula", "none" */
+    theme: "moon" as const,
+
+    /** HTML page title for the /api-docs page */
+    pageTitle: `${appConfig.name} API`,
+
+    /** Favicon file (project-relative) served at /favicon.ico for the /api-docs page */
+    favicon: "src/resources/src/assets/images/favicon/favicon.ico",
+
+    /** Default HTTP client shown in code examples */
+    defaultHttpClient: {
+      targetKey: "js" as const,
+      clientKey: "fetch" as const
+    },
+
+    /** Expand all tags on load */
+    defaultOpenAllTags: true
+  }
+} as const;
+
+export type OpenApiConfig = typeof openApiConfig;

package/hono/src/config/queue.ts

@@ -0,0 +1,30 @@
+import { redisConfig } from "./redis.js";
+
+/**
+ * Why: Queue workers, concurrency, and BullMQ key namespaces.
+ * When: The queue facade bootstraps workers and the dashboard connects.
+ * Where: src/config/queue.ts.
+ * How: `queues` lists which queue names get a worker by default (default,
+ *      mail, maintenance). `concurrency` caps parallel jobs per worker.
+ *      Key prefixes derive from the shared `REDIS_PREFIX`.
+ */
+export const queueConfig = {
+  queues: ["default", "mail", "maintenance"],
+  concurrency: 10,
+  /**
+   * autoPruneQueues
+   * Why: Automatically deletes phantom queues (Redis keys for queue names that
+   *      no longer exist in `queues`) when a queue worker boots. Safe because
+   *      only empty, unconfigured queues are removed, and BullMQ recreates a
+   *      queue's keys on demand if code still dispatches to it.
+   * When: Set false to disable automatic pruning and rely on manual
+   *      `queue:clear` instead.
+   */
+  autoPruneQueues: true,
+  prefix: `${redisConfig.prefix}:queue`,
+  durablePrefix: `${redisConfig.prefix}:durable`,
+  queueUi: "/queues",
+  allowedEmails: ""
+};
+
+export type QueueConfig = typeof queueConfig;

package/hono/src/config/rateLimit.ts

@@ -0,0 +1,17 @@
+import { redisConfig } from "./redis.js";
+
+/**
+ * Why: HTTP rate limiting policy and Redis key namespace.
+ * When: Global and login-specific rate limiters are built.
+ * Where: src/config/rateLimit.ts.
+ * How: Limits are plain literals; `keyPrefix` is derived from the shared
+ *      `REDIS_PREFIX` (`nexwire:rl:*` by default).
+ */
+export const rateLimitConfig = {
+  windowMs: 60000,
+  maxRequests: 500,
+  loginMaxRequests: 60,
+  keyPrefix: `${redisConfig.prefix}:rl`
+};
+
+export type RateLimitConfig = typeof rateLimitConfig;

package/hono/src/config/realtime.ts

@@ -0,0 +1,15 @@
+import { env } from "@/env.js";
+
+/**
+ * Why: Realtime (Socket.IO) settings.
+ * When: The realtime server bootstraps and registers its HTTP path.
+ * Where: src/config/realtime.ts.
+ * How: Reads `SOCKET` from env. `enabled` flips the WebSocket server
+ *      on/off; the admin UI is served when the environment is not production.
+ */
+export const realtimeConfig = {
+  enabled: env.SOCKET,
+  path: "/socket.io"
+};
+
+export type RealtimeConfig = typeof realtimeConfig;

package/hono/src/config/redis.ts

@@ -0,0 +1,18 @@
+import { env } from "@/env.js";
+
+/**
+ * Why: Redis connection and namespace settings.
+ * When: Cache, session, queue, events, and the queue dashboard bootstrap.
+ * Where: src/config/redis.ts.
+ * How: `prefix` is shared by cache/session/queue/events, so it stays in .env
+ *      (`REDIS_PREFIX`) and every namespace derives from it here. `enabled`
+ *      and the commander port are literals you can change here.
+ */
+export const redisConfig = {
+  enabled: env.REDIS,
+  url: env.REDIS_URL,
+  prefix: env.REDIS_PREFIX,
+  commanderPort: 1369
+};
+
+export type RedisConfig = typeof redisConfig;

package/hono/src/config/security.ts

@@ -0,0 +1,44 @@
+// config/security.ts
+import { env } from "@/env.js";
+
+const isProd = env.APP_ENV === "production";
+
+/**
+ * Dev CSP is intentionally lax so HMR / inline bootstrap scripts work.
+ * Prod CSP is strict and blocks unsafe-inline.
+ *
+ * NOTE: if you serve a bundled SPA (Vite/Next) in prod, you MUST add
+ * either a nonce, a hash, or 'unsafe-inline' to script-src — otherwise
+ * the inline bootstrap script will be blocked, exactly as you saw.
+ */
+const csp = isProd
+  ? [
+      "default-src 'self'",
+      "script-src 'self' https://cdn.jsdelivr.net",         // Scalar UI loads its bundle from jsdelivr CDN
+      "style-src 'self' https://cdn.jsdelivr.net 'unsafe-inline'",
+      "img-src 'self' data: blob: https://cdn.jsdelivr.net",
+      "font-src 'self' data: https://cdn.jsdelivr.net https://fonts.scalar.com",
+      "connect-src 'self' https://cdn.jsdelivr.net https://api.scalar.com",
+      "frame-ancestors 'none'",
+      "base-uri 'self'",
+      "form-action 'self'"
+    ].join("; ")
+  : [
+      "default-src 'self'",
+      "script-src 'self' 'unsafe-inline' 'unsafe-eval' https://cdn.jsdelivr.net",
+      "style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net",
+      "img-src 'self' data: blob: https://cdn.jsdelivr.net",
+      "font-src 'self' data: https://cdn.jsdelivr.net https://fonts.scalar.com",
+      "connect-src 'self' ws: wss: https://cdn.jsdelivr.net https://api.scalar.com",   // HMR websocket + Scalar
+      "frame-ancestors 'none'"
+    ].join("; ");
+
+export const securityConfig = {
+  enabled: env.SECURITY_HEADERS,
+  csp,
+  hsts: env.APP_ENV === "production",
+  hstsMaxAge: "max-age=31536000; includeSubDomains",
+  xFrame: "DENY"
+};
+
+export type SecurityConfig = typeof securityConfig;

package/hono/src/config/session.ts

@@ -0,0 +1,17 @@
+import { cookieConfig } from "./index.js";
+import { redisConfig } from "./redis.js";
+
+/**
+ * Why: Server-side session cookie and lifetime settings.
+ * When: Session middleware creates/refreshes sessions for each request.
+ * Where: src/config/session.ts.
+ * How: `cookieName` and `ttlSeconds` are plain literals; `keyPrefix` is
+ *      derived from the shared `REDIS_PREFIX` (`nexwire:session:*` by default).
+ */
+export const sessionConfig = {
+  cookieName: `${cookieConfig.name}_session`,
+  ttlSeconds: 7200,
+  keyPrefix: `${redisConfig.prefix}:session`
+};
+
+export type SessionConfig = typeof sessionConfig;

package/hono/src/config/storage.ts

@@ -0,0 +1,22 @@
+import { env } from "@/env.js";
+
+/**
+ * Why: File storage settings for local and S3 backends.
+ * When: Storage facade bootstrap and file operations.
+ * Where: src/config/storage.ts.
+ * How: Driver, disk, region and TTL are plain literals you can change here.
+ *      Credentials (access key, secret) are confidential and stay in .env.
+ */
+export const storageConfig = {
+  driver: "local",
+  defaultDisk: "public",
+  bucket: "",
+  region: "us-east-1",
+  endpoint: "",
+  forcePathStyle: false,
+  signedUrlTtlSeconds: 900,
+  accessKeyId: env.STORAGE_ACCESS_KEY_ID,
+  secretAccessKey: env.STORAGE_SECRET_ACCESS_KEY
+};
+
+export type StorageConfig = typeof storageConfig;

package/hono/src/config/validate.ts

@@ -0,0 +1,40 @@
+import { databaseConfig } from "./database.js";
+import { mailConfig } from "./mail.js";
+import { redisConfig } from "./redis.js";
+import { storageConfig } from "./storage.js";
+
+/**
+ * Why: Validates that resolved configs are internally consistent at startup.
+ * When: Called before any framework subsystem initializes.
+ * Where: kernel.ts, before storage.init() and initRedis().
+ * How: Checks cross-config dependencies and throws clear errors for inconsistencies.
+ */
+export function validateConfig(): void {
+  if (!databaseConfig.url) {
+    throw new Error("DATABASE_URL is required but is empty");
+  }
+
+  if (storageConfig.driver === "s3") {
+    if (!storageConfig.bucket) {
+      throw new Error("STORAGE_BUCKET is required when storage driver is s3");
+    }
+    if (!storageConfig.accessKeyId || !storageConfig.secretAccessKey) {
+      throw new Error("STORAGE_ACCESS_KEY_ID and STORAGE_SECRET_ACCESS_KEY are required when storage driver is s3");
+    }
+  }
+
+  if (redisConfig.enabled) {
+    try {
+      const url = new URL(redisConfig.url);
+      if (!url.hostname || url.port === "") {
+        throw new Error(`REDIS_URL is invalid: "${redisConfig.url}" — must include host and port`);
+      }
+    } catch (error) {
+      throw new Error(`REDIS_URL is invalid: "${redisConfig.url}" — ${error instanceof Error ? error.message : error}`);
+    }
+  }
+
+  if (!mailConfig.failSilent && !mailConfig.username) {
+    throw new Error("MAIL_USERNAME is required when MAIL_FAIL_SILENT is false");
+  }
+}

package/hono/src/database/migrations/sqlite/0000_init.sql

@@ -0,0 +1,61 @@
+CREATE TABLE `notifications` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`user_id` integer NOT NULL,
+	`type` text NOT NULL,
+	`title` text NOT NULL,
+	`body` text,
+	`data` text,
+	`link` text,
+	`read_at` integer,
+	`created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL,
+	FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON UPDATE cascade ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE TABLE `roles` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`name` text NOT NULL,
+	`created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL,
+	`updated_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `roles_name_unique` ON `roles` (`name`);--> statement-breakpoint
+CREATE TABLE `email_verification_tokens` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`email` text NOT NULL,
+	`token` text NOT NULL,
+	`expires_at` integer NOT NULL,
+	`created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `password_reset_tokens` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`email` text NOT NULL,
+	`token` text NOT NULL,
+	`expires_at` integer NOT NULL,
+	`created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `refresh_tokens` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`user_id` integer,
+	`jti` text NOT NULL,
+	`revoked` integer DEFAULT false,
+	`expires_at` integer NOT NULL,
+	`created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL,
+	FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON UPDATE cascade ON DELETE set null
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `refresh_tokens_jti_unique` ON `refresh_tokens` (`jti`);--> statement-breakpoint
+CREATE TABLE `users` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`name` text NOT NULL,
+	`email` text NOT NULL,
+	`password` text NOT NULL,
+	`role_id` integer,
+	`email_verified_at` integer,
+	`created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL,
+	`updated_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL,
+	FOREIGN KEY (`role_id`) REFERENCES `roles`(`id`) ON UPDATE cascade ON DELETE set null
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `users_email_unique` ON `users` (`email`);