create-nexwire 4.2.2 → 4.2.4

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"
   },
@@ -68,6 +73,8 @@ const STUBS = {
     },
     routeApi: "notification/route.api.ts.stub",
     routePlain: "notification/route.plain.ts.stub",
+    model: "notification/model.ts.stub",
+    provider: "notification/provider.ts.stub",
     job: "notification/job.ts.stub"
   },
   test: {
@@ -157,6 +164,28 @@ function parsePanelPath(flags) {
   return segments.join("/");
 }
 
+/**
+ * Parse `--notifiable=<type>` into the owner class written into the generated
+ * controller. Accepts both `--notifiable=user` and `--notifiable user`, and
+ * defaults to `user` so the common case needs no flag.
+ */
+function parseNotifiable(flags) {
+  const matches = flags
+    .map((flag, index) => ({ flag, index }))
+    .filter(({ flag }) => typeof flag === "string" && flag.startsWith("--notifiable"));
+  if (matches.length === 0) return "user";
+  if (matches.length > 1) throw new Error("--notifiable can only be given once.");
+
+  const [{ flag, index }] = matches;
+  let raw = flag.slice("--notifiable".length).replace(/^=/, "").trim();
+  if (!raw && typeof flags[index + 1] === "string" && !flags[index + 1].startsWith("--")) raw = flags[index + 1].trim();
+  if (!raw) throw new Error("--notifiable needs a value, e.g. --notifiable=user");
+  if (!/^[a-z0-9][a-z0-9_-]*$/.test(raw)) {
+    throw new Error(`Invalid --notifiable value "${raw}". Use lowercase letters, numbers, dashes and underscores.`);
+  }
+  return raw;
+}
+
 /** True when the path is a directory holding at least one entry. */
 async function dirHasFiles(target) {
   try {
@@ -167,6 +196,24 @@ async function dirHasFiles(target) {
   }
 }
 
+/**
+ * Path of the notification store already shipped by any module, or "".
+ *
+ * The table/model/provider is a singleton: two modules shipping it would
+ * generate the same `notifications` table twice and register two providers for
+ * one contract. `module:make-notification` therefore writes the store only when
+ * no module owns it yet, and otherwise adds just another HTTP surface over it.
+ */
+async function findNotificationStore() {
+  const backendSrc = path.resolve(process.cwd(), "src");
+  const files = await glob("modules/**/database/models/notification.{ts,js}", {
+    cwd: backendSrc,
+    nodir: true,
+    windowsPathsNoEscape: true
+  });
+  return files.sort()[0] ? path.join(backendSrc, files.sort()[0]) : "";
+}
+
 /**
  * Resolve the module a subcommand targets.
  *
@@ -287,8 +334,8 @@ async function serviceFile(moduleName, controllerName, withModel) {
 
 /** Build the full default scaffold for module:make. */
 async function moduleFiles(moduleName, openApi) {
-    const name = leafName(moduleName);
-    const vars = moduleFileVars(moduleName, name);
+  const name = leafName(moduleName);
+  const vars = moduleFileVars(moduleName, name);
   const controllerStub = openApi ? STUBS.controller.openapi : STUBS.controller.plain;
   return {
     "facade.ts": await stub(STUBS.facade.named, vars),
@@ -304,15 +351,15 @@ async function moduleFiles(moduleName, openApi) {
  * module, so the controller and schema it just created are known to exist.
  */
 async function routeTemplate(moduleName, controllerName = moduleName) {
-    const controller = leafName(controllerName);
-    const routeStub = openApiEnabled() ? STUBS.route.api : STUBS.route.plain;
-    return await stub(routeStub, {
-      module: moduleName,
-      controller,
-      ClassName: pascal(controller),
-      ModuleClass: moduleLabel(moduleName)
-    });
-  }
+  const controller = leafName(controllerName);
+  const routeStub = openApiEnabled() ? STUBS.route.api : STUBS.route.plain;
+  return await stub(routeStub, {
+    module: moduleName,
+    controller,
+    ClassName: pascal(controller),
+    ModuleClass: moduleLabel(moduleName)
+  });
+}
 
 /**
  * Generate a barebone route file that wires to nothing. module:make-route uses
@@ -320,13 +367,13 @@ async function routeTemplate(moduleName, controllerName = moduleName) {
  */
 async function standaloneRouteTemplate(moduleName, routeName) {
   const routeStub = openApiEnabled() ? STUBS.route.standaloneApi : STUBS.route.standalonePlain;
-return await stub(routeStub, {
-      module: moduleName,
-      controller: routeName,
-      ClassName: pascal(routeName),
-      ModuleClass: moduleLabel(moduleName)
-    });
-  }
+  return await stub(routeStub, {
+    module: moduleName,
+    controller: routeName,
+    ClassName: pascal(routeName),
+    ModuleClass: moduleLabel(moduleName)
+  });
+}
 
 /** Generate a named model file for a module. */
 async function namedModelTemplate(moduleName, name, dialect) {
@@ -506,7 +553,7 @@ export async function makeRoute(rawModule, rawControllerOrFlag, extraFlags = [])
   try {
     await fs.access(routePath);
     exists = true;
-  } catch {}
+  } catch { }
   if (exists && !force)
     throw new Error(`Route file already exists: ${path.relative(process.cwd(), routePath)}. Re-run with --force to overwrite.`);
   await fs.mkdir(path.dirname(routePath), { recursive: true });
@@ -514,32 +561,57 @@ export async function makeRoute(rawModule, rawControllerOrFlag, extraFlags = [])
   console.log(`Route ready: ${path.relative(process.cwd(), routePath)}`);
 }
 
-/** Generate a notification module with controller, routes, and job. */
+/**
+ * Generate the notification HTTP surface, plus the shared store the first time.
+ *
+ * The controller/schema/routes are always written: they are what lets a project
+ * expose `/api/notification/*` for a panel. The model, provider and mail job are
+ * written only when no module already ships the store, because the store is a
+ * singleton — a second copy would create a duplicate `notifications` table and
+ * register a second provider for the same contract.
+ */
 export async function makeNotificationModule(rawName = "notification", flags = []) {
-    const { moduleName, leaf } = resolveModuleRef(rawName, flags);
-    const root = moduleRoot(moduleName);
-    const force = hasFlag(flags, "--force") || hasFlag(flags, "--yes");
-    if (!force && (await dirHasFiles(root))) {
-      throw new Error(`Module already exists: src/modules/${moduleName}. Re-run with --force to overwrite its files.`);
-    }
-    const openApi = openApiEnabled();
-
-    await writeFiles(root, {
-      [`controllers/${leaf}.ts`]: await stub(STUBS.notification.controller, {
-        module: moduleName
-      }),
-      [`schemas/${leaf}.ts`]: await stub(openApi ? STUBS.notification.schema.openapi : STUBS.notification.schema.plain, {
-        module: moduleName
-      }),
-      "routes/index.ts": await stub(openApi ? STUBS.notification.routeApi : STUBS.notification.routePlain, { module: moduleName }),
-      [`jobs/${leaf}.ts`]: await stub(STUBS.notification.job, { module: moduleName })
-    });
+  const { moduleName, leaf } = resolveModuleRef(rawName, flags);
+  const root = moduleRoot(moduleName);
+  const force = hasFlag(flags, "--force") || hasFlag(flags, "--yes");
+  if (!force && (await dirHasFiles(root))) {
+    throw new Error(`Module already exists: src/modules/${moduleName}. Re-run with --force to overwrite its files.`);
+  }
+  const openApi = openApiEnabled();
+  const notifiable = parseNotifiable(flags);
+  const vars = { module: moduleName, leaf, notifiable };
 
-    console.log(`Notification module ready: ${moduleName}`);
-    if (panelOf(moduleName)) console.log(`Panel: ${panelOf(moduleName)}  ->  /api/${moduleName}`);
-    console.log(`Route style: ${openApi ? "openapi" : "plain"}`);
-    console.log("See docs (packages/docs/guide/notification.md) for Vue UI integration.");
+  const files = {
+    [`controllers/${leaf}.ts`]: await stub(STUBS.notification.controller, vars),
+    [`schemas/${leaf}.ts`]: await stub(openApi ? STUBS.notification.schema.openapi : STUBS.notification.schema.plain, vars),
+    "routes/index.ts": await stub(openApi ? STUBS.notification.routeApi : STUBS.notification.routePlain, vars)
+  };
+
+  const existingStore = await findNotificationStore();
+  const ownsStore = existingStore ? path.resolve(existingStore).startsWith(root + path.sep) : false;
+  const writesStore = !existingStore || (force && ownsStore);
+
+  if (writesStore) {
+    files["database/models/notification.ts"] = await stub(STUBS.notification.model, vars);
+    files["providers/notification.ts"] = await stub(STUBS.notification.provider, vars);
+    files["jobs/mail.ts"] = await stub(STUBS.notification.job, vars);
+  }
+
+  await writeFiles(root, files);
+
+  console.log(`Notification module ready: ${moduleName}`);
+  if (writesStore) {
+    console.log("Notification store included: model, provider, mail job");
+    const panelFlag = panelOf(moduleName) ? ` --path=${panelOf(moduleName)}` : "";
+    console.log(`Next: bun maker module:migrate ${leaf}${panelFlag}`);
+  } else {
+    console.log(`Notification store reused: ${path.relative(process.cwd(), existingStore)}`);
   }
+  if (panelOf(moduleName)) console.log(`Panel: ${panelOf(moduleName)}  ->  /api/${moduleName}`);
+  console.log(`Notifiable type: ${notifiable}`);
+  console.log(`Route style: ${openApi ? "openapi" : "plain"}`);
+  console.log("See docs (packages/docs/guide/notification.md) for usage and UI integration.");
+}
 
 /** Soft-delete a module by moving it to storage trash. */
 export async function deleteModule(rawName, flags = []) {
@@ -684,9 +756,7 @@ export async function makeController(rawModule, rawControllerOrFlag, extraFlags
   const { name, flags } = parseNameArg(rawControllerOrFlag, extraFlags, "Controller name", leaf);
   const root = await assertModuleExists(moduleName);
   const lower = name.toLowerCase();
-  const hasService =
-    (await pathExists(path.join(root, "services", `${lower}.ts`))) ||
-    (await pathExists(legacyPath(root, "services", lower)));
+  const hasService = (await pathExists(path.join(root, "services", `${lower}.ts`))) || (await pathExists(legacyPath(root, "services", lower)));
   const content = await controllerFile(moduleName, name, openApiEnabled(), hasService);
   await writeFileSafe(path.join(root, `controllers/${lower}.ts`), content, flags, "Controller file");
 }
@@ -710,8 +780,7 @@ export async function makeService(rawModule, rawNameOrFlag, extraFlags = []) {
   const { name, flags } = parseNameArg(rawNameOrFlag, extraFlags, "Service name", leaf);
   const root = await assertModuleExists(moduleName);
   const lower = name.toLowerCase();
-  const withModel =
-    hasFlag(flags, "--with-model") || (await pathExists(path.join(root, "database", "models", `${lower}.ts`)));
+  const withModel = hasFlag(flags, "--with-model") || (await pathExists(path.join(root, "database", "models", `${lower}.ts`)));
   const content = await serviceFile(moduleName, name, withModel);
   await writeFileSafe(path.join(root, `services/${lower}.ts`), content, flags, "Service file");
 }
@@ -739,6 +808,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);
@@ -926,8 +1020,16 @@ export async function generateSchema(options = {}) {
   if (!options.silent) console.log(`Generated database schema with ${files.length} model file(s)`);
 }
 
-/** Generate a temporary schema file for a single module (used for module:generate/migrate). */
-async function generateModuleSchemaTemp(moduleName) {
+/**
+ * Generate and run migrations that include a module.
+ *
+ * Drizzle diffs the schema against the last snapshot, so generating from a
+ * module-only schema would emit `DROP TABLE` for every other module (auth
+ * included). The full schema is used instead: it adds the module's tables and
+ * keeps the rest of the database intact.
+ */
+export async function runModuleMigrate(rawModuleName, rawArgs = []) {
+  const { moduleName } = resolveModuleRef(rawModuleName, rawArgs);
   await assertModuleExists(moduleName);
   const backendSrc = path.resolve(process.cwd(), "src");
   const files = await glob(`modules/${moduleName}/database/models/*.{ts,js}`, {
@@ -936,47 +1038,13 @@ async function generateModuleSchemaTemp(moduleName) {
     windowsPathsNoEscape: true
   });
   if (!files.length) throw new Error(`No model files found for module '${moduleName}'.`);
-  const exports = [];
-  const tempDir = path.resolve(process.cwd(), "src/storage/tmp");
-  await fs.mkdir(tempDir, { recursive: true });
-  // Flatten the panel path: "admin/testme" must not become a nested
-  // storage/tmp/schema.admin/testme.<ts>.ts path.
-  const slug = moduleName.replaceAll("/", "-");
-  const tempSchemaPath = path.join(tempDir, `schema.${slug}.${Date.now()}.ts`);
-  const tempSchemaDir = path.dirname(tempSchemaPath);
-  for (const file of files.sort()) {
-    const absoluteFile = path.join(backendSrc, file);
-    const relativePath = path
-      .relative(tempSchemaDir, absoluteFile)
-      .replace(/\\/g, "/")
-      .replace(/\.(ts|js)$/, ".ts");
-    const importPath = relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
-    exports.push(`export * from "${importPath}";`);
-  }
-  await fs.writeFile(tempSchemaPath, `${exports.join("\n")}\n`);
-  return { tempSchemaPath, modelCount: files.length };
-}
-
-/** Generate and run migrations for a single module using a temporary schema. */
-export async function runModuleMigrate(rawModuleName, rawArgs = []) {
-  const { moduleName } = resolveModuleRef(rawModuleName, rawArgs);
   await syncMigrationDialect();
   await ensureMigrationMeta();
   await ensureDatabaseDirectory();
-  const keepTemp = rawArgs.includes("--keep-temp");
-  const { tempSchemaPath, modelCount } = await generateModuleSchemaTemp(moduleName);
-  const drizzleSchemaPath = `./${path.relative(process.cwd(), tempSchemaPath).replace(/\\/g, "/")}`;
-  const previousSchema = process.env.DRIZZLE_SCHEMA;
-  try {
-    process.env.DRIZZLE_SCHEMA = drizzleSchemaPath;
-    await runNodeScript(packageScript("drizzle-kit", "bin.cjs"), await drizzleGenerateArgs());
-    await runNodeScript(packageScript("drizzle-kit", "bin.cjs"), ["migrate"]);
-    console.log(`Module migration complete: ${moduleName} (${modelCount} model file(s))`);
-  } finally {
-    if (previousSchema == null) delete process.env.DRIZZLE_SCHEMA;
-    else process.env.DRIZZLE_SCHEMA = previousSchema;
-    if (!keepTemp) await fs.rm(tempSchemaPath, { force: true }).catch(() => {});
-  }
+  await generateSchema();
+  await runNodeScript(packageScript("drizzle-kit", "bin.cjs"), await drizzleGenerateArgs());
+  await runNodeScript(packageScript("drizzle-kit", "bin.cjs"), ["migrate"]);
+  console.log(`Module migration complete: ${moduleName} (${files.length} model file(s))`);
 }
 
 /** Generate a unit test file for a module. */

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)
@@ -38,8 +39,9 @@ export function registerModuleCommands(program, rawArgs) {
     });
   program
     .command("module:make-notification [name]")
-    .description("Generate notification backend module (controller, routes, job)")
+    .description("Generate the notification HTTP module, and the shared store the first time")
     .option("--path <panel>", "Nest the module under a panel folder (e.g. --path=admin)")
+    .option("--notifiable <type>", "Owner type recorded with each notification (default: user)")
     .option("--force", "Overwrite the files of a module that already exists")
     .allowUnknownOption(true)
     .action(async (name) => {
@@ -128,6 +130,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")
@@ -186,8 +196,7 @@ export function registerModuleCommands(program, rawArgs) {
     });
   program
     .command("module:migrate <module>")
-    .description("Generate module-only schema, generate migration, then run migrate")
-    .option("--keep-temp", "Keep temporary schema file after migration")
+    .description("Generate and run a migration that includes the module")
     .option("--path <panel>", "Address a module inside a panel folder (e.g. --path=admin)")
     .allowUnknownOption(true)
     .action(async (moduleName) => runModuleMigrate(moduleName, rawArgs));

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,76 @@
-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 type { Request, Response } from "express";
+import { HttpStatusCodes, resolveNotificationProvider } from "@/framework/facade.js";
+import type { NotifiableTarget } from "@/framework/providers/contracts.js";
+
+/** Read the authenticated owner. A missing auth context means the request is anonymous. */
+function targetFrom(res: Response): NotifiableTarget | null {
+  const auth = (res.locals as any)?.auth;
+  if (!auth || auth.id === undefined || auth.id === null) return null;
+  return { type: "{{notifiable}}", id: auth.id };
+}
+
+function unavailable(res: Response) {
+  return res.status(HttpStatusCodes.SERVICE_UNAVAILABLE).json({
+    message: "Notification provider not available. Restore src/modules/notification or register one in src/providers/."
+  });
+}
+
+function unauthorized(res: Response) {
+  return res.status(HttpStatusCodes.UNAUTHORIZED).json({ message: "Unauthorized" });
+}
+
+export const list = async (req: Request, res: Response) => {
+  const provider = await resolveNotificationProvider();
+  if (!provider) return unavailable(res);
+
+  const target = targetFrom(res);
+  if (!target) return unauthorized(res);
+
+  const page = Math.max(1, Number(req.query.page) || 1);
+  const perPage = Math.min(50, Math.max(1, Number(req.query.perPage) || 20));
+
+  return res.json(await provider.list(target, { page, perPage }));
+};
+
+export const unreadCount = async (_req: Request, res: Response) => {
+  const provider = await resolveNotificationProvider();
+  if (!provider) return unavailable(res);
+
+  const target = targetFrom(res);
+  if (!target) return unauthorized(res);
+
+  return res.json({ count: await provider.unreadCount(target) });
+};
+
+export const markRead = async (req: Request, res: Response) => {
+  const provider = await resolveNotificationProvider();
+  if (!provider) return unavailable(res);
+
+  const target = targetFrom(res);
+  if (!target) return unauthorized(res);
+
+  await provider.markRead(target, String(req.params.id));
+  return res.json({ ok: true });
+};
+
+export const markAllRead = async (_req: Request, res: Response) => {
+  const provider = await resolveNotificationProvider();
+  if (!provider) return unavailable(res);
+
+  const target = targetFrom(res);
+  if (!target) return unauthorized(res);
+
+  await provider.markAllRead(target);
+  return res.json({ ok: true });
+};
+
+export const remove = async (req: Request, res: Response) => {
+  const provider = await resolveNotificationProvider();
+  if (!provider) return unavailable(res);
+
+  const target = targetFrom(res);
+  if (!target) return unauthorized(res);
+
+  await provider.remove(target, String(req.params.id));
+  return res.json({ ok: true });
+};

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

@@ -1,13 +1,11 @@
-import { shouldQueue } from "@/framework/queue/queue.js";
-import { logger } from "@/framework/support/logger.js";
-import { mail } from "@/framework/support/mail.js";
-
-shouldQueue("{{module}}:mail", "mail", async (job) => {
-  const { to, subject, html } = job.data;
-
-  await mail.sendMail({ to, subject, html });
-  logger.info("Notification mail sent", { to, subject });
-
-  return { ok: true };
-});
-
+import { mail, shouldQueue } from "@/framework/facade.js";
+import { logger } from "@/framework/support/logger.js";
+
+shouldQueue("notification:mail", "mail", async (job) => {
+  const { to, subject, html } = job.data;
+
+  await mail.sendMail({ to, subject, html });
+  logger.info("Notification mail sent", { to, subject });
+
+  return { ok: true };
+});