create-nexwire 4.0.0 → 4.1.1

package/hono/src/framework/maker-cli/stubs/service/name.ts.stub

@@ -0,0 +1,65 @@
+import { eq } from "drizzle-orm";
+import { db } from "@/framework/facade.js";
+import { {{tableVariable}} } from "@/modules/{{module}}/database/models/{{controller}}.js";
+
+export const {{controller}}Service = {
+  /**
+   * Why: Returns every {{controller}} row for list screens.
+   * When: Called by the controller's index() handler.
+   * Where: GET /{{controller}} route.
+   */
+  list: async () => {
+    return db.select().from({{tableVariable}});
+  },
+
+  /**
+   * Why: Returns one {{controller}} row by primary key.
+   * When: Called by the controller's show/update/destroy handlers.
+   * Where: Reused across GET/PUT/DELETE /{{controller}}/{id} routes.
+   */
+  findOne: async (id: number) => {
+    const [row] = await db
+      .select()
+      .from({{tableVariable}})
+      .where(eq({{tableVariable}}.id, id))
+      .limit(1);
+    return row ?? null;
+  },
+
+  /**
+   * Why: Persists a new {{controller}} row.
+   * When: Called by the controller's store() handler.
+   * Where: POST /{{controller}} route.
+   */
+  create: async (data: Record<string, unknown>) => {
+    const [row] = await db.insert({{tableVariable}}).values(data).returning();
+    return row;
+  },
+
+  /**
+   * Why: Applies a partial change to one {{controller}} row.
+   * When: Called by the controller's update() handler.
+   * Where: PUT/PATCH /{{controller}}/{id} route.
+   */
+  update: async (id: number, data: Record<string, unknown>) => {
+    const [row] = await db
+      .update({{tableVariable}})
+      .set(data)
+      .where(eq({{tableVariable}}.id, id))
+      .returning();
+    return row ?? null;
+  },
+
+  /**
+   * Why: Removes one {{controller}} row.
+   * When: Called by the controller's destroy() handler.
+   * Where: DELETE /{{controller}}/{id} route.
+   */
+  remove: async (id: number) => {
+    const [row] = await db
+      .delete({{tableVariable}})
+      .where(eq({{tableVariable}}.id, id))
+      .returning();
+    return row ?? null;
+  },
+};

package/hono/src/framework/maker-cli/stubs/type/name.ts.stub

@@ -0,0 +1,22 @@
+/**
+ * Why: Shared TypeScript types for the {{module}} module.
+ * When: Needed by controllers, services, or helpers that must agree on a shape.
+ * Where: src/modules/{{module}}/types/{{name}}.ts
+ */
+
+/** Why: Base shape for every {{name}} record. When: Used as a constraint or return type. Where: This file. */
+export interface {{Name}}Record {
+  id: number;
+}
+
+/** Why: Result shape for a single-item response. When: Returned by show-style handlers. Where: This file. */
+export interface {{Name}}Result {
+  message: string;
+  data: {{Name}}Record;
+}
+
+/** Why: Result shape for list responses. When: Returned by index-style handlers. Where: This file. */
+export interface {{Name}}ListResult {
+  message: string;
+  data: {{Name}}Record[];
+}

package/hono/src/framework/maker-cli/utils/naming.mjs

@@ -1,13 +1,56 @@
-/** Validate that a name value exists and return it trimmed+lowercased. Throws if empty. */
-export function assertName(value, label) {
-  if (!value) {
-    throw new Error(`${label} is required.`);
-  }
-
-  return value.trim().toLowerCase();
-}
-
-/** Convert a kebab-case or snake_case string to PascalCase. */
-export function pascal(input) {
-  return input.replace(/(^\w|[-_]\w)/g, (part) => part.replace(/[-_]/g, "").toUpperCase());
-}
+/**
+ * A name is safe when it can be used as a folder name, a URL segment, a table
+ * name and a TypeScript identifier without further quoting.
+ *
+ * Kebab-case, snake_case and camelCase all pass: `pascal` already folds `-` and
+ * `_`, and names are lowercased before this test. What fails is anything that
+ * would produce uncompilable code - spaces and dots break the generated
+ * `@/modules/...` import, a leading digit breaks the identifier.
+ */
+const NAME_PATTERN = /^[a-z][a-z0-9_-]*$/;
+
+/**
+ * Best-effort readable repair of a rejected name, used only in error text.
+ * Returns "" when no safe suggestion exists (e.g. a leading digit cannot be
+ * reordered without guessing the developer's intent).
+ */
+function suggestName(value) {
+  const cleaned = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/-{2,}/g, "-")
+    .replace(/^[-_]+|[-_]+$/g, "");
+  if (!cleaned || !/^[a-z]/.test(cleaned)) return "";
+  return cleaned;
+}
+
+/**
+ * Validate that a name value exists and is safe to use.
+ * Throws with the exact command to run instead when the value is unusable.
+ */
+export function assertName(value, label) {
+  if (!value) {
+    throw new Error(`${label} is required.`);
+  }
+
+  const name = value.trim().toLowerCase();
+  if (NAME_PATTERN.test(name)) return name;
+
+  const suggestion = suggestName(value);
+  const reason = /^[0-9]/.test(name)
+    ? "must start with a lowercase letter"
+    : "may only contain lowercase letters, numbers, dashes and underscores";
+  throw new Error(`Invalid ${label.toLowerCase()}: "${value}" - a name ${reason}.${suggestion ? ` Use "${suggestion}" instead.` : ""}`);
+}
+
+/** Convert a kebab-case or snake_case string to PascalCase. */
+export function pascal(input) {
+  return input.replace(/(^\w|[-_]\w)/g, (part) => part.replace(/[-_]/g, "").toUpperCase());
+}
+
+/** Convert a kebab-case or snake_case string to camelCase. */
+export function camelCase(input) {
+  const p = pascal(input);
+  return p.charAt(0).toLowerCase() + p.slice(1);
+}

package/hono/src/framework/modules/discover.ts

@@ -1,54 +1,57 @@
-import fs from "node:fs";
-import path from "node:path";
-import { pathToFileURL } from "node:url";
-import { glob } from "glob";
-
-function resolveModulesPath() {
-  const cwd = process.cwd();
-  const srcModules = path.resolve(cwd, "src/modules");
-  const distModules = path.resolve(cwd, "dist/src/modules");
-  const entry = String(process.argv[1] || "");
-  const runningDist = /[\\/]dist[\\/]/.test(entry);
-
-  if (runningDist && fs.existsSync(distModules)) return distModules;
-  return srcModules;
-}
-
-export const modulesPath = resolveModulesPath();
-
-/**
- * Why: Finds module files by glob from active src/dist modules path.
- * When: Framework needs module routes/jobs/seeders/schedules discovery.
- * Where: Route registrar, queue boot, scheduler boot, seeding.
- * How: Runs glob with absolute paths and stable sorting.
- */
-export async function discoverModuleFiles(pattern: string) {
-  const files = await glob(pattern, {
-    cwd: modulesPath,
-    absolute: true,
-    nodir: true,
-    windowsPathsNoEscape: true
-  });
-
-  return files.sort();
-}
-
-/**
- * Why: Derives module folder name from absolute discovered file path.
- * When: Mounting route prefixes and grouping module assets.
- * Where: Route registration logic.
- * How: Computes relative path and returns first segment.
- */
-export function moduleNameFromPath(filePath: string) {
-  return path.relative(modulesPath, filePath).split(path.sep)[0];
-}
-
-/**
- * Why: Dynamically imports a discovered module file.
- * When: Bootstrapping pluggable module artifacts.
- * Where: Discovery consumers across framework.
- * How: Converts file path to file URL and imports it.
- */
-export async function importFile(filePath: string) {
-  return await import(pathToFileURL(filePath).href);
-}
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { glob } from "glob";
+
+function resolveModulesPath() {
+  const cwd = process.cwd();
+  const srcModules = path.resolve(cwd, "src/modules");
+  const distModules = path.resolve(cwd, "dist/src/modules");
+  const entry = String(process.argv[1] || "");
+  const runningDist = /[\\/]dist[\\/]/.test(entry);
+
+  if (runningDist && fs.existsSync(distModules)) return distModules;
+  return srcModules;
+}
+
+export const modulesPath = resolveModulesPath();
+
+/**
+ * Why: Finds module files by glob from active src/dist modules path.
+ * When: Framework needs module routes/jobs/seeders/schedules discovery.
+ * Where: Route registrar, queue boot, scheduler boot, seeding.
+ * How: Runs glob with absolute paths and stable sorting.
+ */
+export async function discoverModuleFiles(pattern: string) {
+  const files = await glob(pattern, {
+    cwd: modulesPath,
+    absolute: true,
+    nodir: true,
+    windowsPathsNoEscape: true
+  });
+
+  return files.sort();
+}
+
+/**
+ * Why: Derives the module name from an absolute discovered file path.
+ * When: Mounting route prefixes and grouping module assets.
+ * Where: Route registration logic.
+ * How: Strips the artifact folder (e.g. `routes/`), keeping any panel segment so
+ * `admin/post/routes/index.ts` resolves to `admin/post` rather than `admin`.
+ * Returns POSIX separators because the result is used as a URL prefix.
+ */
+export function moduleNameFromPath(filePath: string) {
+  const relative = path.relative(modulesPath, filePath);
+  return path.dirname(path.dirname(relative)).split(path.sep).join("/");
+}
+
+/**
+ * Why: Dynamically imports a discovered module file.
+ * When: Bootstrapping pluggable module artifacts.
+ * Where: Discovery consumers across framework.
+ * How: Converts file path to file URL and imports it.
+ */
+export async function importFile(filePath: string) {
+  return await import(pathToFileURL(filePath).href);
+}

package/hono/src/framework/notification/index.ts

@@ -3,7 +3,7 @@ import { db } from "@/framework/database/connection.js";
 import { dispatchEvent } from "@/framework/events/dispatcher.js";
 import { redisClientIfReady } from "@/framework/redis/client.js";
 import { mail } from "@/framework/support/mail.js";
-import { notifications } from "@/modules/auth/database/models/notifications.js";
+import { notifications } from "@/modules/auth/database/models/notification.js";
 import { users } from "@/modules/auth/database/models/user.js";
 
 /** Extra JSON metadata attached to the notification (e.g. entity IDs, links). */

package/hono/src/framework/realtime/broadcast.ts

@@ -1,46 +1,46 @@
-import { env } from "@/env.js";
-import { socketServer } from "@/framework/realtime/index.js";
-import { redisClientIfReady } from "@/framework/redis/client.js";
-
-export type BroadcastOptions = {
-  users?: Array<string | number>;
-  roles?: string[];
-  rooms?: string[];
-  auth?: boolean;
-  all?: boolean;
-};
-
-/**
- * Why: Emits realtime events to targeted audiences.
- * When: Domain events need websocket fan-out.
- * Where: Event dispatcher and module jobs.
- * How: Emits via Socket.IO if available; otherwise relays through Redis pub/sub
- *      so the main process (which has Socket.IO) can broadcast it.
- */
-function emitViaIo(event: string, payload: any, options: BroadcastOptions) {
-  const io = socketServer();
-  if (!io) return;
-
-  if (options.all) io.emit(event, payload);
-  if (options.auth) io.to("auth").emit(event, payload);
-
-  for (const user of options.users || []) io.to(`user:${user}`).emit(event, payload);
-  for (const role of options.roles || []) io.to(`role:${role}`).emit(event, payload);
-  for (const room of options.rooms || []) io.to(room).emit(event, payload);
-}
-
-export function broadcast(event: string, payload: any, options: BroadcastOptions = {}) {
-  const io = socketServer();
-
-  if (io) {
-    emitViaIo(event, payload, options);
-    return;
-  }
-
-  // No Socket.IO in this process — relay through Redis so the main process can broadcast
-  const redis = redisClientIfReady();
-  if (!redis) return;
-
-  const channel = `${env.REDIS_PREFIX}:broadcast`;
-  redis.publish(channel, JSON.stringify({ event, payload, options }));
-}
+import { env } from "@/env.js";
+import { socketServer } from "@/framework/realtime/socket.js";
+import { redisClientIfReady } from "@/framework/redis/client.js";
+
+export type BroadcastOptions = {
+  users?: Array<string | number>;
+  roles?: string[];
+  rooms?: string[];
+  auth?: boolean;
+  all?: boolean;
+};
+
+/**
+ * Why: Emits realtime events to targeted audiences.
+ * When: Domain events need websocket fan-out.
+ * Where: Event dispatcher and module jobs.
+ * How: Emits via Socket.IO if available; otherwise relays through Redis pub/sub
+ *      so the main process (which has Socket.IO) can broadcast it.
+ */
+function emitViaIo(event: string, payload: any, options: BroadcastOptions) {
+  const io = socketServer();
+  if (!io) return;
+
+  if (options.all) io.emit(event, payload);
+  if (options.auth) io.to("auth").emit(event, payload);
+
+  for (const user of options.users || []) io.to(`user:${user}`).emit(event, payload);
+  for (const role of options.roles || []) io.to(`role:${role}`).emit(event, payload);
+  for (const room of options.rooms || []) io.to(room).emit(event, payload);
+}
+
+export function broadcast(event: string, payload: any, options: BroadcastOptions = {}) {
+  const io = socketServer();
+
+  if (io) {
+    emitViaIo(event, payload, options);
+    return;
+  }
+
+  // No Socket.IO in this process — relay through Redis so the main process can broadcast
+  const redis = redisClientIfReady();
+  if (!redis) return;
+
+  const channel = `${env.REDIS_PREFIX}:broadcast`;
+  redis.publish(channel, JSON.stringify({ event, payload, options }));
+}

package/hono/src/framework/server.ts

@@ -148,7 +148,7 @@ export async function startServer(): Promise<ServerHandle> {
   const socketLine = !realtimeConfig.enabled
     ? "Realtime (Socket.IO) disabled"
     : realtime
-      ? `Realtime (Socket.IO) enabled: ${socketAdmin.enabled ? "Admin UI: https://admin.socket.io" : ""} ${"| " + serverUrl(server, WS_PATH).replace(/^http/, "ws")}`
+      ? `Realtime (Socket.IO) enabled: ${socketAdmin.enabled ? "Admin UI: https://admin.socket.io" : ""}${socketAdmin.enabled ? " | " : " "}${serverUrl(server, WS_PATH).replace(/^http/, "ws")}`
       : "Realtime (Socket.IO) unavailable";
   console.log(!realtimeConfig.enabled ? chalk.gray(socketLine) : realtime ? chalk.green(socketLine) : chalk.yellow(socketLine));
 

package/hono/src/framework/session/session.ts

@@ -1,116 +1,121 @@
-import { randomUUID } from "node:crypto";
-import type { Context, Next } from "hono";
-import { getCookie, setCookie } from "hono/cookie";
-import { appConfig, redisConfig, sessionConfig } from "@/config/index.js";
-import { redisClientIfReady } from "@/framework/redis/client.js";
-
-/** Extract origin from a URL string. Returns empty string on invalid/missing input. */
-function originOf(url?: string) {
-  if (!url) return "";
-  try {
-    return new URL(url).origin;
-  } catch {
-    return "";
-  }
-}
-
-/** Returns true when FRONTEND_URL and APP_URL point to different origins — requires SameSite=None; Secure for session cookies. */
-function needsCrossSiteCookie() {
-  const appOrigin = originOf(appConfig.url);
-  const frontendOrigin = originOf(appConfig.frontendUrl);
-  return Boolean(appOrigin && frontendOrigin && appOrigin !== frontendOrigin);
-}
-
-/** Builds the Redis key for a session id using the configured prefix. */
-function sessionKey(id: string) {
-  return `${sessionConfig.keyPrefix}:${id}`;
-}
-
-/**
- * Global middleware that ensures every request has a session cookie.
- * - Reads existing session cookie from request.
- * - If missing: generates a UUID, sets a new cookie (SameSite=None; Secure if cross-origin, else Lax).
- * - Stores sessionId in Hono context (`c.get("sessionId")`).
- * - Refreshes the Redis session TTL on every request.
- */
-export async function sessionMiddleware(c: Context, next: Next) {
-  let sessionId = getCookie(c, sessionConfig.cookieName);
-
-  if (!sessionId) {
-    sessionId = randomUUID();
-    const crossSiteCookie = needsCrossSiteCookie();
-    setCookie(c, sessionConfig.cookieName, sessionId, {
-      httpOnly: true,
-      sameSite: crossSiteCookie ? "None" : "Lax",
-      secure: crossSiteCookie,
-      path: "/",
-      maxAge: sessionConfig.ttlSeconds
-    });
-  }
-
-  c.set("sessionId", sessionId);
-  await session.refresh(sessionId);
-  await next();
-}
-
-/** Redis-backed server-side session store. Each session is a namespaced JSON document with configurable TTL. */
-export const session = {
-  /** Create a new session document in Redis. Returns the generated session id, or empty string when Redis is unavailable. */
-  async start(data: Record<string, unknown> = {}) {
-    const client = redisClientIfReady();
-    if (!client) return "";
-
-    const id = randomUUID();
-    await client.set(sessionKey(id), JSON.stringify(data), "EX", sessionConfig.ttlSeconds);
-    return id;
-  },
-
-  /** Get the full session payload for a given id. Returns null when session doesn't exist or Redis is unavailable. */
-  async all<T = Record<string, unknown>>(id: string): Promise<T | null> {
-    const client = redisClientIfReady();
-    if (!client) return null;
-
-    const data = await client.get(sessionKey(id));
-    return data ? JSON.parse(data) : null;
-  },
-
-  /** Read a single key from the session payload. Returns null if the key or session doesn't exist. */
-  async get<T>(id: string, key: string): Promise<T | null> {
-    const data = await session.all<Record<string, T>>(id);
-    return data?.[key] ?? null;
-  },
-
-  /** Write or update a single key in the session payload. Rewrites the entire document with a fresh TTL. Returns false when Redis is unavailable. */
-  async put(id: string, key: string, value: unknown) {
-    const client = redisClientIfReady();
-    if (!client) return false;
-
-    const data = (await session.all<Record<string, unknown>>(id)) || {};
-    data[key] = value;
-    await client.set(sessionKey(id), JSON.stringify(data), "EX", sessionConfig.ttlSeconds);
-    return true;
-  },
-
-  /** Extend the TTL of an existing session. Called automatically by sessionMiddleware. Returns false when Redis is unavailable. */
-  async refresh(id: string) {
-    const client = redisClientIfReady();
-    if (!client) return false;
-
-    await client.expire(sessionKey(id), sessionConfig.ttlSeconds);
-    return true;
-  },
-
-  /** Delete a session document from Redis. Use on logout or session expiry. Returns false when Redis is unavailable. */
-  async destroy(id: string) {
-    const client = redisClientIfReady();
-    if (!client) return false;
-
-    await client.del(sessionKey(id));
-    return true;
-  },
-
-  /** Returns true when Redis is enabled and the Redis client is ready — guards against using session store without Redis. */
-  isAvailable() {
-    return redisConfig.enabled && redisClientIfReady() !== null;
-  }
-};
+import { randomUUID } from "node:crypto";
+import type { Context, Next } from "hono";
+import { getCookie, setCookie } from "hono/cookie";
+import { appConfig, redisConfig, sessionConfig } from "@/config/index.js";
+import { redisClientIfReady } from "@/framework/redis/client.js";
+
+/** Extract origin from a URL string. Returns empty string on invalid/missing input. */
+function originOf(url?: string) {
+  if (!url) return "";
+  try {
+    return new URL(url).origin;
+  } catch {
+    return "";
+  }
+}
+
+/** Returns true when FRONTEND_URL and APP_URL point to different origins — requires SameSite=None; Secure for session cookies. */
+function needsCrossSiteCookie() {
+  const appOrigin = originOf(appConfig.url);
+  const frontendOrigin = originOf(appConfig.frontendUrl);
+  return Boolean(appOrigin && frontendOrigin && appOrigin !== frontendOrigin);
+}
+
+/** Builds the Redis key for a session id using the configured prefix. */
+function sessionKey(id: string) {
+  return `${sessionConfig.keyPrefix}:${id}`;
+}
+
+/**
+ * Global middleware that ensures every request has a session cookie.
+ * - Reads existing session cookie from request.
+ * - If missing: generates a UUID, sets a new cookie (SameSite=None; Secure if cross-origin, else Lax).
+ * - Stores sessionId in Hono context (`c.get("sessionId")`).
+ * - Refreshes the Redis session TTL on every request.
+ */
+export async function sessionMiddleware(c: Context, next: Next) {
+  let sessionId = getCookie(c, sessionConfig.cookieName);
+
+  if (!sessionId) {
+    sessionId = randomUUID();
+    const crossSiteCookie = needsCrossSiteCookie();
+    setCookie(c, sessionConfig.cookieName, sessionId, {
+      httpOnly: true,
+      sameSite: crossSiteCookie ? "None" : "Lax",
+      secure: crossSiteCookie,
+      path: "/",
+      maxAge: sessionConfig.ttlSeconds
+    });
+  }
+
+  c.set("sessionId", sessionId);
+  await session.refresh(sessionId);
+  await next();
+}
+
+/** Redis-backed server-side session store. Each session is a namespaced JSON document with configurable TTL. */
+export const session = {
+  /** Create a new session document in Redis. Returns the generated session id, or empty string when Redis is unavailable. */
+  async start(data: Record<string, unknown> = {}) {
+    const client = redisClientIfReady();
+    if (!client) return "";
+
+    const id = randomUUID();
+    await client.set(sessionKey(id), JSON.stringify(data), "EX", sessionConfig.ttlSeconds);
+    return id;
+  },
+
+  /** Get the full session payload for a given id. Returns null when session doesn't exist or Redis is unavailable. */
+  async all<T = Record<string, unknown>>(id: string): Promise<T | null> {
+    const client = redisClientIfReady();
+    if (!client) return null;
+
+    const data = await client.get(sessionKey(id));
+    return data ? JSON.parse(data) : null;
+  },
+
+  /** Read a single key from the session payload. Returns null if the key or session doesn't exist. */
+  async get<T>(id: string, key: string): Promise<T | null> {
+    const data = await session.all<Record<string, T>>(id);
+    return data?.[key] ?? null;
+  },
+
+  /** Write or update a single key in the session payload. Rewrites the entire document with a fresh TTL. Returns false when Redis is unavailable. */
+  async set(id: string, key: string, value: unknown) {
+    const client = redisClientIfReady();
+    if (!client) return false;
+
+    const data = (await session.all<Record<string, unknown>>(id)) || {};
+    data[key] = value;
+    await client.set(sessionKey(id), JSON.stringify(data), "EX", sessionConfig.ttlSeconds);
+    return true;
+  },
+
+  /** @deprecated Use set() instead. */
+  async put(id: string, key: string, value: unknown) {
+    return this.set(id, key, value);
+  },
+
+  /** Extend the TTL of an existing session. Called automatically by sessionMiddleware. Returns false when Redis is unavailable. */
+  async refresh(id: string) {
+    const client = redisClientIfReady();
+    if (!client) return false;
+
+    await client.expire(sessionKey(id), sessionConfig.ttlSeconds);
+    return true;
+  },
+
+  /** Delete a session document from Redis. Use on logout or session expiry. Returns false when Redis is unavailable. */
+  async destroy(id: string) {
+    const client = redisClientIfReady();
+    if (!client) return false;
+
+    await client.del(sessionKey(id));
+    return true;
+  },
+
+  /** Returns true when Redis is enabled and the Redis client is ready — guards against using session store without Redis. */
+  isAvailable() {
+    return redisConfig.enabled && redisClientIfReady() !== null;
+  }
+};

package/hono/src/middlewares/auth-middleware.ts

@@ -1,6 +1,6 @@
 import { eq } from "drizzle-orm";
 import type { Context, Next } from "hono";
-import { cookie, db, jwt, HttpStatusCodes } from "@/framework/facade.js";
+import { cookie, db, HttpStatusCodes, jwt } from "@/framework/facade.js";
 import { refreshTokens, users } from "@/modules/auth/database/models/user.js";
 
 export async function authMiddleware(c: Context, next: Next) {