create-nexwire 4.2.2 → 4.2.3

package/express/src/framework/kernel.ts

@@ -1,52 +1,54 @@
-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 { notFound, onError } from "@/framework/http/logger.js";
-import { ensurePublicDir, hasUiBuild, uiIndexMiddleware, uiStaticMiddleware } from "@/framework/http/static.js";
-import { registerModuleRoutes } from "@/framework/modules/routes.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 bootQueueJobs();
-  await registerModuleRoutes(app);
-
-  const queueDashboard = await setupQueueDashboard();
-  if (typeof queueDashboard.route === "function") {
-    queueDashboard.route(app);
-  } else {
-    app.use(queueDashboard.basePath, queueDashboard.route);
-  }
-
-  if (appConfig.uiEnabled) {
-    ensurePublicDir();
-  }
-
-  if (appConfig.uiEnabled && hasUiBuild()) {
-    app.use(uiStaticMiddleware);
-    app.get("*", uiIndexMiddleware);
-  }
-
-  app.use(notFound);
-  app.use(onError);
-
-  return { app, bullBoard: queueDashboard };
-}
+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 { notFound, onError } from "@/framework/http/logger.js";
+import { ensurePublicDir, hasUiBuild, uiIndexMiddleware, uiStaticMiddleware } 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();
+  if (typeof queueDashboard.route === "function") {
+    queueDashboard.route(app);
+  } else {
+    app.use(queueDashboard.basePath, queueDashboard.route);
+  }
+
+  if (appConfig.uiEnabled) {
+    ensurePublicDir();
+  }
+
+  if (appConfig.uiEnabled && hasUiBuild()) {
+    app.use(uiStaticMiddleware);
+    app.get("*", uiIndexMiddleware);
+  }
+
+  app.use(notFound);
+  app.use(onError);
+
+  return { app, bullBoard: queueDashboard };
+}

package/express/src/framework/maker-cli/index.mjs

@@ -5,6 +5,7 @@ import { config } from "dotenv";
 import { registerDbCommands } from "./db/index.mjs";
 import { registerMiddlewareCommands } from "./middleware/index.mjs";
 import { registerModuleCommands } from "./module/index.mjs";
+import { registerProviderCommands } from "./provider/index.mjs";
 import { registerRuntimeCommands } from "./runtime/index.mjs";
 import { configureGroupedHelp, makerCommandPrefix, showHelp } from "./utils/help.mjs";
 import { registerProjectCommands } from "./utils/project-commands.mjs";
@@ -42,6 +43,7 @@ try {
 
   registerMiddlewareCommands(program, args);
   registerModuleCommands(program, args);
+  registerProviderCommands(program, args);
   registerDeployCommands(program, args);
   registerDbCommands(program, args);
   registerRuntimeCommands(program, args);

package/express/src/framework/maker-cli/module/core.mjs

@@ -45,6 +45,11 @@ const STUBS = {
   facade: {
     named: "facade/name.ts.stub"
   },
+  provider: {
+    named: "provider/name.ts.stub",
+    module: "provider/module.ts.stub",
+    moduleBarrel: "provider/module-barrel.ts.stub"
+  },
   helper: {
     named: "helper/name.ts.stub"
   },
@@ -739,6 +744,31 @@ export async function makeLocalMiddleware(rawModule, rawNameOrFlag, extraFlags =
   await writeFileSafe(path.join(root, `middlewares/${name}.ts`), content, flags, "Middleware file");
 }
 
+/**
+ * Generate a provider file for an existing module.
+ *
+ * The file lands in the module's providers/ folder, which the framework
+ * imports at boot just like src/providers/. That is what lets a module offer
+ * an implementation to the whole application without the application knowing
+ * anything about the module's internals.
+ */
+export async function makeModuleProvider(rawModule, rawNameOrFlag, extraFlags = []) {
+  const { moduleName, leaf } = resolveModuleRef(rawModule, rawNameOrFlag, extraFlags);
+  const { name, flags } = parseNameArg(rawNameOrFlag, extraFlags, "Provider name", leaf);
+  const root = await assertModuleExists(moduleName);
+  const filePath = path.join(root, `providers/${name}.ts`);
+  if (hasFlag(flags, "--dry-run")) {
+    console.log(`Would create provider file: ${path.relative(process.cwd(), filePath)}`);
+    return;
+  }
+  const content = await stub(STUBS.provider.module, {
+    module: moduleName,
+    name,
+    camel: camelCase(name)
+  });
+  await writeFileSafe(filePath, content, flags, "Provider file");
+}
+
 /** Generate a types file for an existing module. */
 export async function makeType(rawModule, rawNameOrFlag, extraFlags = []) {
   const { moduleName, leaf } = resolveModuleRef(rawModule, rawNameOrFlag, extraFlags);

package/express/src/framework/maker-cli/module/index.mjs

@@ -12,6 +12,7 @@ import {
   makeLocalMiddleware,
   makeModel,
   makeModule,
+  makeModuleProvider,
   makeModules,
   makeNotificationModule,
   makeRoute,
@@ -28,7 +29,7 @@ import {
 export function registerModuleCommands(program, rawArgs) {
   program
     .command("module:make <names...>")
-    .description("Create one or more modules with facade, schema, service, controller, route, model, and seeder folders")
+    .description("Create one or more modules with facade, providers, schema, service, controller, route, model, and seeder folders")
     .option("--path <panel>", "Nest the module(s) under a panel folder (e.g. --path=admin)")
     .option("--force", "Overwrite the files of modules that already exist")
     .allowUnknownOption(true)
@@ -128,6 +129,14 @@ export function registerModuleCommands(program, rawArgs) {
     .option("--path <panel>", "Address a module inside a panel folder (e.g. --path=admin)")
     .allowUnknownOption(true)
     .action(async (moduleName, name) => makeLocalMiddleware(moduleName, name, rawArgs.slice(name ? 3 : 2)));
+  program
+    .command("module:make-provider <module> [name]")
+    .description("Generate a provider file in the module's providers folder")
+    .option("--force", "Overwrite existing provider file")
+    .option("--dry-run", "Print what would be created without executing")
+    .option("--path <panel>", "Address a module inside a panel folder (e.g. --path=admin)")
+    .allowUnknownOption(true)
+    .action(async (moduleName, name) => makeModuleProvider(moduleName, name, rawArgs.slice(name ? 3 : 2)));
   program
     .command("module:make-type <module> [name]")
     .description("Generate a types file for an existing module")

package/express/src/framework/maker-cli/provider/core.mjs

@@ -0,0 +1,49 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { hasFlag } from "../utils/flags.mjs";
+import { assertName, camelCase } from "../utils/naming.mjs";
+
+const stubsRoot = path.resolve(import.meta.dirname, "../stubs");
+
+/** Read a stub file and replace {{key}} placeholders, removing unfilled ones. */
+async function stub(name, values = {}) {
+  let content = await fs.readFile(path.join(stubsRoot, name), "utf8");
+  for (const [key, value] of Object.entries(values)) {
+    content = content.replaceAll(`{{${key}}}`, String(value));
+  }
+  return content.replace(/\{\{[A-Z0-9_]+\}\}/g, "");
+}
+
+/**
+ * Why: Generates the app-wide provider file.
+ * When: A developer wants to plug an implementation into the whole app.
+ * Where: src/providers/<name>.ts - imported automatically at boot.
+ * How: Writes the stub and prints how to reach the provider from anywhere.
+ */
+export async function makeProvider(rawName, flags = []) {
+  const name = assertName(rawName, "Provider name");
+  const camel = camelCase(name);
+  const dryRun = hasFlag(flags, "--dry-run");
+  const force = hasFlag(flags, "--force") || hasFlag(flags, "--yes");
+
+  const filePath = path.resolve(process.cwd(), "src/providers", `${name}.ts`);
+  if (dryRun) {
+    console.log(`Would create provider file: ${path.relative(process.cwd(), filePath)}`);
+    return;
+  }
+
+  let exists = false;
+  try {
+    await fs.access(filePath);
+    exists = true;
+  } catch {}
+  if (exists && !force) {
+    throw new Error(`Provider already exists: ${path.relative(process.cwd(), filePath)}. Re-run with --force to overwrite.`);
+  }
+
+  const content = await stub("provider/name.ts.stub", { name, camel });
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, content);
+  console.log(`Provider ready: ${path.relative(process.cwd(), filePath)}`);
+  console.log(`It is imported at boot. Reach it with: getProvider("${name}")`);
+}

package/express/src/framework/maker-cli/provider/index.mjs

@@ -0,0 +1,12 @@
+import { makeProvider } from "./core.mjs";
+
+/** Register provider:* subcommands on the CLI program. */
+export function registerProviderCommands(program, rawArgs) {
+  program
+    .command("provider:make <name>")
+    .description("Generate a provider file in src/providers")
+    .option("--force", "Overwrite existing provider file")
+    .option("--dry-run", "Print what would be created without executing")
+    .allowUnknownOption(true)
+    .action(async (name) => makeProvider(name, rawArgs.filter((arg) => arg.startsWith("--"))));
+}

package/express/src/framework/maker-cli/stubs/notification/controller.ts.stub

@@ -1,77 +1,77 @@
-import { and, count, desc, eq, sql } from "drizzle-orm";
-import type { Request, Response } from "express";
-import { db } from "@/framework/facade.js";
-import { notifications } from "@/modules/auth/database/models/notifications.js";
-
-type AuthRequest = Request & { auth: { id: number } };
-
-export const list = async (req: AuthRequest, res: Response) => {
-  const userId = req.auth.id;
-  const page = Math.max(1, Number(req.query.page) || 1);
-  const perPage = Math.min(50, Math.max(1, Number(req.query.perPage) || 20));
-
-  const unread = await db.select({ count: count() }).from(notifications)
-    .where(and(eq(notifications.userId, userId), sql`${notifications.readAt} IS NULL`));
-  const total = await db.select({ count: count() }).from(notifications)
-    .where(eq(notifications.userId, userId));
-  const rows = await db.select().from(notifications)
-    .where(eq(notifications.userId, userId))
-    .orderBy(desc(notifications.createdAt))
-    .limit(perPage)
-    .offset((page - 1) * perPage);
-
-  res.json({
-    data: rows.map(normalize),
-    total: total[0].count,
-    unread: unread[0].count,
-    page,
-    perPage
-  });
-};
-
-export const unreadCount = async (req: AuthRequest, res: Response) => {
-  const userId = req.auth.id;
-  const rows = await db.select({ count: count() }).from(notifications)
-    .where(and(eq(notifications.userId, userId), sql`${notifications.readAt} IS NULL`));
-  res.json({ count: rows[0].count });
-};
-
-export const markRead = async (req: AuthRequest, res: Response) => {
-  const id = Number(req.params.id);
-  await db.update(notifications)
-    .set({ readAt: sql`now()` })
-    .where(and(eq(notifications.id, id), eq(notifications.userId, req.auth.id)));
-  res.json({ ok: true });
-};
-
-export const markAllRead = async (req: AuthRequest, res: Response) => {
-  await db.update(notifications)
-    .set({ readAt: sql`now()` })
-    .where(and(eq(notifications.userId, req.auth.id), sql`${notifications.readAt} IS NULL`));
-  res.json({ ok: true });
-};
-
-export const remove = async (req: AuthRequest, res: Response) => {
-  const id = Number(req.params.id);
-  await db.delete(notifications)
-    .where(and(eq(notifications.id, id), eq(notifications.userId, req.auth.id)));
-  res.json({ ok: true });
-};
-
-function normalize(row: typeof notifications.$inferSelect) {
-  let parsed: unknown = null;
-  if (row.data) {
-    try { parsed = JSON.parse(row.data); } catch {}
-  }
-  return {
-    id: row.id,
-    userId: row.userId,
-    type: row.type,
-    title: row.title,
-    body: row.body,
-    data: parsed,
-    link: row.link,
-    readAt: row.readAt?.toISOString() || null,
-    createdAt: row.createdAt.toISOString(),
-  };
-}
+import { and, count, desc, eq, sql } from "drizzle-orm";
+import type { Request, Response } from "express";
+import { db } from "@/framework/facade.js";
+import { notifications } from "@/modules/auth/database/models/notification.js";
+
+type AuthRequest = Request & { auth: { id: number } };
+
+export const list = async (req: AuthRequest, res: Response) => {
+  const userId = req.auth.id;
+  const page = Math.max(1, Number(req.query.page) || 1);
+  const perPage = Math.min(50, Math.max(1, Number(req.query.perPage) || 20));
+
+  const unread = await db.select({ count: count() }).from(notifications)
+    .where(and(eq(notifications.userId, userId), sql`${notifications.readAt} IS NULL`));
+  const total = await db.select({ count: count() }).from(notifications)
+    .where(eq(notifications.userId, userId));
+  const rows = await db.select().from(notifications)
+    .where(eq(notifications.userId, userId))
+    .orderBy(desc(notifications.createdAt))
+    .limit(perPage)
+    .offset((page - 1) * perPage);
+
+  res.json({
+    data: rows.map(normalize),
+    total: total[0].count,
+    unread: unread[0].count,
+    page,
+    perPage
+  });
+};
+
+export const unreadCount = async (req: AuthRequest, res: Response) => {
+  const userId = req.auth.id;
+  const rows = await db.select({ count: count() }).from(notifications)
+    .where(and(eq(notifications.userId, userId), sql`${notifications.readAt} IS NULL`));
+  res.json({ count: rows[0].count });
+};
+
+export const markRead = async (req: AuthRequest, res: Response) => {
+  const id = Number(req.params.id);
+  await db.update(notifications)
+    .set({ readAt: sql`now()` })
+    .where(and(eq(notifications.id, id), eq(notifications.userId, req.auth.id)));
+  res.json({ ok: true });
+};
+
+export const markAllRead = async (req: AuthRequest, res: Response) => {
+  await db.update(notifications)
+    .set({ readAt: sql`now()` })
+    .where(and(eq(notifications.userId, req.auth.id), sql`${notifications.readAt} IS NULL`));
+  res.json({ ok: true });
+};
+
+export const remove = async (req: AuthRequest, res: Response) => {
+  const id = Number(req.params.id);
+  await db.delete(notifications)
+    .where(and(eq(notifications.id, id), eq(notifications.userId, req.auth.id)));
+  res.json({ ok: true });
+};
+
+function normalize(row: typeof notifications.$inferSelect) {
+  let parsed: unknown = null;
+  if (row.data) {
+    try { parsed = JSON.parse(row.data); } catch {}
+  }
+  return {
+    id: row.id,
+    userId: row.userId,
+    type: row.type,
+    title: row.title,
+    body: row.body,
+    data: parsed,
+    link: row.link,
+    readAt: row.readAt?.toISOString() || null,
+    createdAt: row.createdAt.toISOString(),
+  };
+}

package/express/src/framework/maker-cli/stubs/provider/module-barrel.ts.stub

@@ -0,0 +1,19 @@
+/**
+ * Providers for the {{module}} module.
+ *
+ * This file is imported automatically at boot, so whatever it registers is
+ * available to the whole application. Use this to plug implementations (e.g.
+ * auth, payments) into the app - not to export the module's API to other
+ * modules (that is what facade.ts is for):
+ *
+ *   import { registerProvider } from "@/framework/facade.js";
+ *
+ *   registerProvider("{{module}}", { ... });
+ *
+ * A module with more than one provider keeps them in providers/*.ts instead -
+ * those files are imported at boot too.
+ *
+ * Rule: a module never imports another module's provider implementation.
+ */
+
+export {};

package/express/src/framework/maker-cli/stubs/provider/module.ts.stub

@@ -0,0 +1,21 @@
+import { registerProvider } from "@/framework/facade.js";
+
+/**
+ * Why: Plugs the {{name}} implementation into the application.
+ * When: Imported automatically at boot from each module's providers folder.
+ * Where: src/modules/{{module}}/providers/{{name}}.ts
+ *
+ * Reach it from anywhere in the app:
+ *
+ *   import { getProvider } from "@/framework/facade.js";
+ *   const {{camel}} = getProvider<typeof {{camel}}Provider>("{{name}}");
+ *
+ * Rule: a provider never imports another module's provider implementation.
+ */
+export const {{camel}}Provider = {
+  async handle(input: unknown) {
+    return input;
+  }
+};
+
+registerProvider("{{name}}", {{camel}}Provider);

package/express/src/framework/maker-cli/stubs/provider/name.ts.stub

@@ -0,0 +1,21 @@
+import { registerProvider } from "@/framework/facade.js";
+
+/**
+ * Why: Plugs the {{name}} implementation into the application.
+ * When: Imported automatically at boot from src/providers/.
+ * Where: src/providers/{{name}}.ts
+ *
+ * Reach it from anywhere in the app:
+ *
+ *   import { getProvider } from "@/framework/facade.js";
+ *   const {{camel}} = getProvider<typeof {{camel}}Provider>("{{name}}");
+ *
+ * Rule: a provider never imports another provider's implementation.
+ */
+export const {{camel}}Provider = {
+  async handle(input: unknown) {
+    return input;
+  }
+};
+
+registerProvider("{{name}}", {{camel}}Provider);

package/express/src/framework/maker-cli/utils/help.mjs

@@ -89,7 +89,11 @@ const COMMAND_GROUPS = [
     // `module:make-middleware` writes inside one module and applies only to it.
     // In the same section the two look interchangeable, which is exactly the
     // mistake a developer is about to make.
-    commands: ["middleware:make"]
+    //
+    // `provider:make` follows the same split: it writes to src/providers and
+    // applies to the whole app, `module:make-provider` writes inside one
+    // module and applies only to it.
+    commands: ["middleware:make", "provider:make"]
   },
   {
     title: "Generators - modules",
@@ -107,6 +111,7 @@ const COMMAND_GROUPS = [
       "module:make-test",
       "module:make-helper",
       "module:make-middleware",
+      "module:make-provider",
       "module:make-type"
     ]
   },

package/express/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 {