create-nexwire 4.2.1 → 4.2.3

package/hono/src/framework/maker-cli/utils/project-commands.mjs

@@ -13,8 +13,16 @@ import { PROJECT_COMMAND_FLAG } from "./help.mjs";
  * there would be overwritten on the next framework update - and `src/modules/`
  * is swept by the route, job and seeder globs. The project root is the one
  * place nothing else owns.
+ *
+ * Two names are read: commands.mjs (plain JavaScript, loaded by plain node)
+ * and commands.ts (TypeScript, loaded through tsx). The .mjs is the incumbent
+ * and wins if a project keeps both.
  */
 export const PROJECT_COMMANDS_PATH = "maker/commands.mjs";
+export const PROJECT_COMMANDS_TS_PATH = "maker/commands.ts";
+
+/** Process-global so a re-evaluated module cannot register tsx twice. */
+const TSX_REGISTERED = "__nexwireMakerTsxRegistered";
 
 const PROJECT_COMMANDS_TEMPLATE = `/**
  * Your project's maker commands.
@@ -36,8 +44,11 @@ const PROJECT_COMMANDS_TEMPLATE = `/**
  *     which one. Rename yours; the built-in stays.
  *   - An error in this file is reported, never swallowed. If your commands stop
  *     appearing, the fault is here rather than in your command code.
- *   - Import your own code with a normal relative path, e.g.
- *       import { sendInvoice } from "../src/invoices/send.js";
+ *   - This file runs as plain JavaScript under plain Node, so it cannot import
+ *     your TypeScript source or use your tsconfig path alias. If a command
+ *     needs either, name this file maker/commands.ts instead and delete this
+ *     one - nexwire loads that file through tsx, with your tsconfig applied.
+ *     For editor type support, create maker/tsconfig.json as shown in the docs.
  *
  * Replace or delete the example below once you have a command of your own.
  */
@@ -54,14 +65,47 @@ export default function register(program) {
 }
 `;
 
+/**
+ * Why: Plain node cannot import TypeScript, so maker/commands.ts needs tsx
+ *      registered before it is imported. Registered at most once per process
+ *      and never unregistered: two overlapping registrations corrupt the
+ *      loader, and commands routinely import more TypeScript at action time,
+ *      long after this function returns. The flag lives on globalThis because
+ *      this module can be evaluated more than once in one process (vitest's
+ *      per-file isolation) while the loader hooks are process-wide.
+ * When: Only when the project's file is TypeScript - maker/commands.mjs never
+ *      pays for tsx being installed.
+ * Where: utils/project-commands.mjs.
+ */
+async function registerTsLoader(rel) {
+  if (globalThis[TSX_REGISTERED]) return;
+
+  try {
+    const { register } = await import("tsx/esm/api");
+    register();
+  } catch (error) {
+    throw new Error(
+      `${rel} needs tsx to load TypeScript, but it could not be registered: ${error?.message || error}. tsx ships as a devDependency of every nexwire project - run npm install, or rename the file to ${PROJECT_COMMANDS_PATH}.`,
+      { cause: error }
+    );
+  }
+
+  globalThis[TSX_REGISTERED] = true;
+}
+
 /**
  * Why: Registers the commands a project defined for itself.
  * When: Every maker invocation, right after the framework's own registrars.
  * Where: Maker CLI entry flow, from utils/project-commands.mjs.
- * How: Imports maker/commands.mjs resolved from process.cwd() - not from
- *      import.meta.dirname, which points inside node_modules and would find the
- *      framework's own directory instead of the project. Absent is silent and
- *      free; broken is loud, because a developer's commands silently not
+ * How: Imports maker/commands.mjs - or maker/commands.ts, loaded through tsx,
+ *      which resolves the project's tsconfig path aliases - resolved from
+ *      process.cwd(), not from import.meta.dirname, which points inside
+ *      node_modules and would find the framework's own directory instead of the
+ *      project. If a project keeps both files the .mjs wins and the .ts file is
+ *      skipped with a warning naming it, so neither file is ever silently dead:
+ *      a project that already runs must not be re-registered by a file that
+ *      appeared later, and a file that is skipped must say so. Absent is silent
+ *      and free; broken is loud, because a developer's commands silently not
  *      existing is a far worse experience than an error message. A name that
  *      collides with a framework command is refused by commander itself, which
  *      is the right outcome: the built-in wins and the project cannot shadow a
@@ -70,10 +114,23 @@ export default function register(program) {
  *      asked for the name.
  */
 export async function registerProjectCommands(program, rawArgs, cwd = process.cwd()) {
-  const file = path.resolve(cwd, PROJECT_COMMANDS_PATH);
+  const mjsFile = path.resolve(cwd, PROJECT_COMMANDS_PATH);
+  const tsFile = path.resolve(cwd, PROJECT_COMMANDS_TS_PATH);
+  const hasMjs = fs.existsSync(mjsFile);
+  const hasTs = fs.existsSync(tsFile);
+
+  if (!hasMjs && !hasTs) {
+    return { loaded: false, file: mjsFile, added: [] };
+  }
+
+  const isTs = !hasMjs && hasTs;
+  const file = isTs ? tsFile : mjsFile;
+  const rel = isTs ? PROJECT_COMMANDS_TS_PATH : PROJECT_COMMANDS_PATH;
 
-  if (!fs.existsSync(file)) {
-    return { loaded: false, file, added: [] };
+  if (hasMjs && hasTs) {
+    console.warn(
+      `${PROJECT_COMMANDS_TS_PATH} is ignored because ${PROJECT_COMMANDS_PATH} exists. Keep one - delete the file you are not using.`
+    );
   }
 
   // Not wrapped in a bare try/catch on purpose. A file that exists but fails to
@@ -81,18 +138,22 @@ export async function registerProjectCommands(program, rawArgs, cwd = process.cw
   // command that is actually in this loader. The catches below only attach the
   // file name, because an error from inside the project file otherwise reads as
   // if it came from the framework.
+  if (isTs) {
+    await registerTsLoader(rel);
+  }
+
   let module;
   try {
     module = await import(pathToFileURL(file).href);
   } catch (error) {
-    throw new Error(`Could not load ${PROJECT_COMMANDS_PATH}: ${error?.message || error}`, { cause: error });
+    throw new Error(`Could not load ${rel}: ${error?.message || error}`, { cause: error });
   }
 
   const register = module.default ?? module.register;
 
   if (typeof register !== "function") {
     throw new TypeError(
-      `${PROJECT_COMMANDS_PATH} must export a default function (program, args) => void. Found: ${typeof register}.`
+      `${rel} must export a default function (program, args) => void. Found: ${typeof register}.`
     );
   }
 
@@ -101,7 +162,7 @@ export async function registerProjectCommands(program, rawArgs, cwd = process.cw
   try {
     await register(program, rawArgs);
   } catch (error) {
-    throw new Error(`Could not register commands from ${PROJECT_COMMANDS_PATH}: ${error?.message || error}`, {
+    throw new Error(`Could not register commands from ${rel}: ${error?.message || error}`, {
       cause: error
     });
   }

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

@@ -1,10 +1,27 @@
 import { eq } from "drizzle-orm";
 import { db } from "@/framework/database/connection.js";
 import { dispatchEvent } from "@/framework/events/dispatcher.js";
+import { resolveAuthProvider } from "@/framework/providers/adapter.js";
 import { redisClientIfReady } from "@/framework/redis/client.js";
 import { mail } from "@/framework/support/mail.js";
-import { notifications } from "@/modules/auth/database/models/notification.js";
-import { users } from "@/modules/auth/database/models/user.js";
+
+let notifications: any = null;
+let modelsLoaded = false;
+let modelsLoadAttempted = false;
+
+async function loadNotificationModel() {
+  if (modelsLoaded) return true;
+  if (modelsLoadAttempted) return false;
+  modelsLoadAttempted = true;
+  try {
+    const notificationMod = await import("@/modules/auth/database/models/notification.js").catch(() => null);
+    if (notificationMod?.notifications) notifications = notificationMod.notifications;
+    modelsLoaded = !!notifications;
+    return modelsLoaded;
+  } catch {
+    return false;
+  }
+}
 
 /** Extra JSON metadata attached to the notification (e.g. entity IDs, links). */
 export type NotificationOptions = {
@@ -22,6 +39,8 @@ export type NotificationOptions = {
   broadcast?: boolean;
   /** Email delivery options */
   mail?: {
+    /** Explicit recipient. Skips the auth provider contact lookup. */
+    to?: string;
     subject?: string;
     html?: string;
   };
@@ -29,6 +48,13 @@ export type NotificationOptions = {
 
 /** Create a notification and persist it to the database. Optionally broadcast via Socket.IO and/or send by email. */
 export async function notify(userId: number, options: NotificationOptions) {
+  const ok = await loadNotificationModel();
+  if (!ok || !notifications) {
+    console.warn(
+      "[notification] skipped: notification model not available (@/modules/auth/database/models/notification.js). Delete or replace auth/notification without breaking framework."
+    );
+    return null;
+  }
   const insertResult = await db.insert(notifications).values({
     userId,
     type: options.type || "info",
@@ -63,9 +89,39 @@ async function sendMailChannel(
   notification: { id: number; title: string; body: string | null },
   options: NotificationOptions
 ) {
-  const [user] = await db.select({ email: users.email, name: users.name }).from(users).where(eq(users.id, userId));
+  let to: string | null = (options.mail as any)?.to || null;
+  let name: string | null = null;
+
+  if (!to) {
+    try {
+      const provider = await resolveAuthProvider();
+      if (provider?.getUserContact) {
+        const contact = await provider.getUserContact(userId);
+        if (contact?.email) {
+          to = contact.email as string;
+          name = (contact.name as string) || null;
+        }
+      }
+    } catch {}
+  }
+
+  if (!to) {
+    try {
+      const userMod = await import("@/modules/auth/database/models/user.js").catch(() => null);
+      if (userMod?.users) {
+        const [user] = await db
+          .select({ email: userMod.users.email, name: (userMod.users as any).name })
+          .from(userMod.users)
+          .where(eq(userMod.users.id, userId));
+        if (user?.email) {
+          to = user.email as string;
+          name = (user as any).name || null;
+        }
+      }
+    } catch {}
+  }
 
-  if (!user?.email) return;
+  if (!to) return;
 
   const subject = options.mail?.subject || notification.title;
   const html = options.mail?.html || defaultMailHtml(notification.title, notification.body);
@@ -74,14 +130,14 @@ async function sendMailChannel(
     await dispatchEvent(
       "notification:mail",
       {
-        to: user.email,
+        to,
         subject,
         html
       },
       { queue: "mail" }
     );
   } else {
-    await mail.sendMail({ to: user.email, subject, html });
+    await mail.sendMail({ to, subject, html });
   }
 }
 
@@ -95,7 +151,7 @@ function escapeHtml(str: string) {
 }
 
 /** Convert a DB row into the normalized response shape, parsing the `data` JSON column. */
-function normalize(row: typeof notifications.$inferSelect) {
+function normalize(row: any) {
   let parsed: unknown = null;
   if (row.data) {
     try {

package/hono/src/framework/providers/adapter.ts

@@ -0,0 +1,125 @@
+import { eq } from "drizzle-orm";
+import { db } from "@/framework/database/connection.js";
+import type { AuthProvider } from "./contracts.js";
+import { loadProviders } from "./loader.js";
+import { getAuthProvider } from "./registry.js";
+
+let defaultProvider: AuthProvider | null = null;
+let defaultLoadAttempted = false;
+
+/**
+ * Why: Builds the built-in auth provider from the default auth module.
+ * When: No custom provider was registered by the application.
+ * Where: Auth provider adapter.
+ * How: Lazily imports the default user/refresh-token models. When the default
+ *      auth module was deleted or replaced, no provider is produced.
+ */
+async function loadDefaultProvider(): Promise<AuthProvider | null> {
+  if (defaultProvider) return defaultProvider;
+  if (defaultLoadAttempted) return null;
+  defaultLoadAttempted = true;
+  try {
+    const userMod = await import("@/modules/auth/database/models/user.js").catch(() => null);
+    if (!userMod?.users || !userMod?.refreshTokens) return null;
+
+    const users = userMod.users;
+    const refreshTokens = userMod.refreshTokens;
+
+    defaultProvider = {
+      async getUserById(id: number) {
+        try {
+          const user = await (db.query.users.findFirst as any)?.({
+            where: eq(users.id, id),
+            with: { role: true }
+          });
+          if (user) return user;
+        } catch {}
+        try {
+          const rows = await db.select().from(users).where(eq(users.id, id));
+          return rows?.[0] ?? null;
+        } catch {
+          return null;
+        }
+      },
+      async findRefreshToken(jti: string) {
+        try {
+          const token = await (db.query.refreshTokens.findFirst as any)?.({
+            where: eq(refreshTokens.jti, jti)
+          });
+          if (token) return token;
+        } catch {}
+        try {
+          const rows = await db.select().from(refreshTokens).where(eq(refreshTokens.jti, jti));
+          return rows?.[0] ?? null;
+        } catch {
+          return null;
+        }
+      },
+      async deleteRefreshToken(tokenId: number) {
+        try {
+          await db.delete(refreshTokens).where(eq(refreshTokens.id, tokenId));
+        } catch {}
+      },
+      async revokeRefreshToken(tokenId: number) {
+        try {
+          await db.delete(refreshTokens).where(eq(refreshTokens.id, tokenId));
+        } catch {}
+      },
+      async getAuthContext(user: any, payload?: any) {
+        try {
+          if (user?.role && typeof user.role === "object") {
+            return {
+              ...(payload || {}),
+              id: user.id,
+              email: user.email,
+              roleId: user.role?.id ?? null,
+              role: user.role?.name ?? null,
+              ...user
+            };
+          }
+        } catch {}
+        return {
+          ...(payload || {}),
+          id: user.id,
+          email: user.email,
+          roleId: user.roleId ?? null,
+          role: user.role ?? null,
+          ...user
+        };
+      },
+      async getUserContact(userId: number) {
+        try {
+          const user = await this.getUserById(userId);
+          if (!user) return null;
+          return {
+            email: user.email ?? null,
+            name: user.name ?? user.fullName ?? user.username ?? null,
+            phone: user.phone ?? user.phoneNumber ?? null
+          };
+        } catch {
+          return null;
+        }
+      }
+    };
+    return defaultProvider;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Why: Resolves the auth provider the framework should use.
+ * When: The auth middleware or the notification mailer needs user data.
+ * Where: Auth provider adapter.
+ * How: Application providers are loaded first, so a file in `src/providers/`
+ *      wins. Otherwise the built-in provider from the default auth module is
+ *      used. When neither exists the framework degrades gracefully.
+ */
+export async function resolveAuthProvider(): Promise<AuthProvider | null> {
+  await loadProviders();
+  const registered = getAuthProvider();
+  if (registered) return registered;
+  const def = await loadDefaultProvider();
+  if (def) return def;
+  return null;
+}

package/hono/src/framework/providers/contracts.ts

@@ -0,0 +1,56 @@
+/**
+ * Why: Defines the shapes a pluggable provider has to satisfy.
+ * When: A developer replaces a framework default (auth today, payments later).
+ * Where: Imported through the framework facade, never from framework internals.
+ * How: Interfaces stay deliberately loose so custom user shapes pass through.
+ */
+
+/** Registry key of the built-in auth provider contract. */
+export const AUTH_PROVIDER_KEY = "auth";
+
+/**
+ * Registry key for any provider implementation.
+ *
+ * `string & {}` keeps the literal keys above discoverable by editors while
+ * still accepting any custom key, so a project can register its own contracts
+ * (payments, otp, storage, ...) without the framework having to know them.
+ */
+export type ProviderKey = typeof AUTH_PROVIDER_KEY | (string & {});
+
+export interface AuthProviderUser {
+  id: number;
+  email?: string | null;
+  [key: string]: any;
+}
+
+export interface AuthProviderRefreshToken {
+  id: number;
+  jti: string;
+  revoked?: boolean | null;
+  expiresAt?: Date | string | null;
+  userId?: number | null;
+  [key: string]: any;
+}
+
+export interface AuthUserContext {
+  id: number;
+  email?: string | null;
+  roleId?: number | null;
+  role?: string | null;
+  [key: string]: any;
+}
+
+export interface AuthUserContact {
+  email?: string | null;
+  name?: string | null;
+  phone?: string | null;
+}
+
+export interface AuthProvider {
+  getUserById(id: number): Promise<AuthProviderUser | null>;
+  findRefreshToken(jti: string): Promise<AuthProviderRefreshToken | null>;
+  revokeRefreshToken?(tokenId: number): Promise<void>;
+  deleteRefreshToken?(tokenId: number): Promise<void>;
+  getAuthContext?(user: AuthProviderUser, payload?: any): Promise<AuthUserContext | any>;
+  getUserContact?(userId: number): Promise<AuthUserContact | null>;
+}

package/hono/src/framework/providers/loader.ts

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { glob } from "glob";
+import { discoverModuleFiles } from "@/framework/modules/discover.js";
+import { logger } from "@/framework/support/logger.js";
+
+/**
+ * Why: Finds the app-level provider folder for the running code.
+ * When: Providers are loaded at boot.
+ * Where: Provider loader.
+ * How: Mirrors the module discovery rule — `src/providers` in development,
+ *      `dist/src/providers` when the compiled server is the entrypoint.
+ */
+function resolveProvidersPath() {
+  const cwd = process.cwd();
+  const srcProviders = path.resolve(cwd, "src/providers");
+  const distProviders = path.resolve(cwd, "dist/src/providers");
+  const entry = String(process.argv[1] || "");
+  const runningDist = /[\\/]dist[\\/]/.test(entry);
+
+  if (runningDist && fs.existsSync(distProviders)) return distProviders;
+  return srcProviders;
+}
+
+export const providersPath = resolveProvidersPath();
+
+let loadPromise: Promise<number> | null = null;
+let loading = false;
+
+/**
+ * Why: Collects every provider file that should run at boot.
+ * When: The loader runs.
+ * Where: Provider loader.
+ * How: Globs `src/providers/**` for app-wide providers, and
+ *      `src/modules/**\/providers.ts` plus `src/modules/**\/providers/*.ts` for
+ *      module-scoped ones. Tests and declaration files are ignored.
+ */
+async function collectProviderFiles(): Promise<string[]> {
+  const files: string[] = [];
+
+  if (fs.existsSync(providersPath)) {
+    const appFiles = await glob("**/*.{ts,js,mjs}", {
+      cwd: providersPath,
+      absolute: true,
+      nodir: true,
+      ignore: ["**/__tests__/**", "**/*.d.ts", "**/*.test.*", "**/*.spec.*"],
+      windowsPathsNoEscape: true
+    });
+    files.push(...appFiles);
+  }
+
+  try {
+    // A module plugs its own implementation in either from a single file
+    // (providers.ts) or from a folder (providers/*.ts). Both are imported.
+    const moduleFiles = await discoverModuleFiles("**/providers.{ts,js}");
+    const moduleProviderFiles = await discoverModuleFiles("**/providers/*.{ts,js}");
+    files.push(...moduleFiles, ...moduleProviderFiles);
+  } catch {}
+
+  return [...new Set(files)].sort();
+}
+
+/**
+ * Why: Imports each discovered provider file so its registration runs.
+ * When: The loader runs.
+ * Where: Provider loader.
+ * How: Imports in sorted order; a broken file is logged and skipped instead of
+ *      taking the whole application down.
+ */
+async function loadProviderFiles(): Promise<number> {
+  const files = await collectProviderFiles();
+
+  for (const file of files) {
+    try {
+      await import(pathToFileURL(file).href);
+    } catch (error) {
+      logger.warn("Provider file failed to load", {
+        file,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+
+  return files.length;
+}
+
+/**
+ * Why: Runs the application's provider files exactly once.
+ * When: The kernel boots, and on the first provider lookup.
+ * Where: Kernel startup and the auth provider adapter.
+ * How: Caches the promise so repeated lookups cost nothing. A provider file
+ *      that itself asks for a provider during load gets an immediate answer
+ *      instead of deadlocking on its own load.
+ */
+export async function loadProviders(): Promise<number> {
+  if (loading) return 0;
+  if (!loadPromise) {
+    loading = true;
+    loadPromise = loadProviderFiles().finally(() => {
+      loading = false;
+    });
+  }
+  return loadPromise;
+}

package/hono/src/framework/providers/registry.ts

@@ -0,0 +1,62 @@
+import { AUTH_PROVIDER_KEY, type AuthProvider, type ProviderKey } from "./contracts.js";
+
+/**
+ * Why: Holds the app-wide provider implementations in one place.
+ * When: A provider file in `src/providers/` (or a module's `providers.ts`)
+ *       registers its implementation at boot.
+ * Where: Read by the framework through `resolve*Provider()` helpers.
+ * How: A plain key/value map. No container, no decorators, no auto-wiring.
+ */
+const registry = new Map<string, unknown>();
+
+/**
+ * Why: Registers a provider implementation under a key.
+ * When: A provider file runs at boot and claims a contract.
+ * Where: Application code, through the framework facade.
+ * How: Stores the implementation and returns it so it can be inlined.
+ */
+export function registerProvider<T>(key: ProviderKey, implementation: T): T {
+  registry.set(key, implementation);
+  return implementation;
+}
+
+/** Returns the registered implementation for a key, or null when absent. */
+export function getProvider<T = unknown>(key: ProviderKey): T | null {
+  const found = registry.get(key);
+  return (found as T) ?? null;
+}
+
+/** Reports whether a provider is registered for a key. */
+export function hasProvider(key: ProviderKey): boolean {
+  return registry.has(key);
+}
+
+/** Removes a registered provider. Mainly useful in tests. */
+export function clearProvider(key: ProviderKey): void {
+  registry.delete(key);
+}
+
+/** Lists every registered provider key, sorted for stable output. */
+export function listProviders(): string[] {
+  return [...registry.keys()].sort();
+}
+
+/** Registers the auth provider that the framework's auth middleware uses. */
+export function registerAuthProvider(provider: AuthProvider): AuthProvider {
+  return registerProvider(AUTH_PROVIDER_KEY, provider);
+}
+
+/** Returns the registered auth provider, or null when none was registered. */
+export function getAuthProvider(): AuthProvider | null {
+  return getProvider<AuthProvider>(AUTH_PROVIDER_KEY);
+}
+
+/** Reports whether a custom auth provider is registered. */
+export function hasAuthProvider(): boolean {
+  return hasProvider(AUTH_PROVIDER_KEY);
+}
+
+/** Removes the registered auth provider. Mainly useful in tests. */
+export function clearAuthProvider(): void {
+  clearProvider(AUTH_PROVIDER_KEY);
+}