create-nexwire 4.3.0 → 4.4.0

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

@@ -0,0 +1,201 @@
+import fs from "node:fs";
+import fsPromises from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { writeFileAlways, writeFileIfMissing } from "./file-ops.mjs";
+import { PROJECT_COMMAND_FLAG } from "./help.mjs";
+
+/**
+ * Where a project keeps its own maker commands.
+ *
+ * Deliberately outside `src/`. Anything under `src/framework/` is copied into
+ * the published package by `scripts/sync-template.mjs`, so a developer edit
+ * 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.
+ *
+ * This file is yours. Nothing in nexwire writes to it, and no framework update
+ * will touch it. Whatever you export here is registered on the maker CLI
+ * alongside the built-in commands:
+ *
+ *   maker example:hello          run your command
+ *   maker --help                 every command, yours included
+ *
+ * \`program\` is the same commander object the built-in commands are built with,
+ * so \`.command()\`, \`.description()\`, \`.option()\` and \`.action()\` behave exactly
+ * as they do in nexwire's own commands.
+ *
+ * Three things worth knowing:
+ *
+ *   - A name that collides with a framework command is ignored, and you are told
+ *     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.
+ *   - 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.
+ */
+
+export default function register(program) {
+  program
+    .command("example:hello <name>")
+    .description("Example command - replace or delete this")
+    .option("--loud", "Shout the greeting")
+    .action((name, options) => {
+      const greeting = \`Hello, \${name}!\`;
+      console.log(options.loud ? greeting.toUpperCase() : greeting);
+    });
+}
+`;
+
+/**
+ * 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 - 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
+ *      command it did not write. That refusal is re-thrown here with the file
+ *      name attached, because commander's own message does not say which file
+ *      asked for the name.
+ */
+export async function registerProjectCommands(program, rawArgs, cwd = process.cwd()) {
+  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 (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
+  // load has to say so, or the developer goes looking for a bug in their own
+  // 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 ${rel}: ${error?.message || error}`, { cause: error });
+  }
+
+  const register = module.default ?? module.register;
+
+  if (typeof register !== "function") {
+    throw new TypeError(
+      `${rel} must export a default function (program, args) => void. Found: ${typeof register}.`
+    );
+  }
+
+  const before = new Set(program.commands);
+
+  try {
+    await register(program, rawArgs);
+  } catch (error) {
+    throw new Error(`Could not register commands from ${rel}: ${error?.message || error}`, {
+      cause: error
+    });
+  }
+
+  const added = [];
+
+  for (const command of program.commands) {
+    if (before.has(command)) continue;
+    // Tagged so `maker --help` files these under "Your commands" beside
+    // `maker:init`, rather than in the section for unclassified commands.
+    command[PROJECT_COMMAND_FLAG] = true;
+    added.push(command.name());
+  }
+
+  return { loaded: true, file, added };
+}
+
+/**
+ * Why: Creates maker/commands.mjs so a project can add its own commands.
+ * When: A developer runs `maker maker:init`.
+ * Where: utils/project-commands.mjs.
+ * How: Writes the template with the same no-clobber default as every other
+ *      generator, so an existing file is left alone unless --force is given.
+ */
+export async function initProjectCommands(cwd = process.cwd(), { force = false } = {}) {
+  const file = path.resolve(cwd, PROJECT_COMMANDS_PATH);
+
+  if (force) {
+    await writeFileAlways(file, PROJECT_COMMANDS_TEMPLATE);
+    return { file, created: false, overwritten: true };
+  }
+
+  await fsPromises.mkdir(path.dirname(file), { recursive: true });
+  const created = await writeFileIfMissing(file, PROJECT_COMMANDS_TEMPLATE);
+  return { file, created, overwritten: false };
+}

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

@@ -0,0 +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 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/fastify/src/framework/modules/routes.ts

@@ -0,0 +1,31 @@
+import type { FastifyInstance } from "fastify";
+import { discoverModuleFiles, importFile, moduleNameFromPath } from "@/framework/modules/discover.js";
+
+/**
+ * Why: Discovers and mounts every module route plugin.
+ * When: Kernel boot, after the HTTP app exists.
+ * Where: Framework startup.
+ * How: Each `modules/<name>/routes/*.ts` default export is a Fastify plugin,
+ *      registered under `/api/<module-name>`.
+ */
+export async function registerModuleRoutes(app: FastifyInstance) {
+  const files = await discoverModuleFiles("**/routes/*.{ts,js}");
+
+  for (const file of files) {
+    const route = await importFile(file);
+
+    if (!route.default) {
+      throw new Error(`Route file ${file} has no default export`);
+    }
+
+    // Optional Guard: Ensure it's a Fastify plugin function
+    if (typeof route.default !== "function") {
+      throw new Error(`Route file ${file} must export a Fastify plugin as default`);
+    }
+
+    const prefix = `/api/${moduleNameFromPath(file)}`;
+    await app.register(route.default, { prefix });
+  }
+
+  return files.length;
+}

package/fastify/src/framework/notification/channels/broadcast.ts

@@ -0,0 +1,15 @@
+import { dispatchEvent } from "@/framework/events/dispatcher.js";
+import type { NotificationChannel } from "@/framework/notification/contracts.js";
+
+export const broadcastChannel: NotificationChannel = {
+  name: "broadcast",
+  async send(target, notification, options) {
+    if (!options.broadcast) return false;
+
+    await dispatchEvent("notification.created", notification, {
+      broadcast: { users: [target.id] }
+    });
+
+    return true;
+  }
+};

package/fastify/src/framework/notification/channels/mail.ts

@@ -0,0 +1,42 @@
+import { dispatchEvent } from "@/framework/events/dispatcher.js";
+import type { NotificationChannel } from "@/framework/notification/contracts.js";
+import { resolveAuthProvider } from "@/framework/providers/adapter.js";
+import { redisClientIfReady } from "@/framework/redis/client.js";
+import { mail } from "@/framework/support/mail.js";
+
+function escapeHtml(str: string) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+export const mailChannel: NotificationChannel = {
+  name: "mail",
+  async send(target, notification, options) {
+    if (!options.mail) return false;
+
+    let to = options.mail.to || null;
+    if (!to) {
+      try {
+        const provider = await resolveAuthProvider();
+        if (provider?.getUserContact) {
+          const contact = await provider.getUserContact(target.id);
+          if (contact?.email) to = contact.email as string;
+        }
+      } catch {}
+    }
+
+    if (!to) return false;
+
+    const subject = options.mail.subject || notification.title;
+    const html =
+      options.mail.html ||
+      `<h2>${escapeHtml(notification.title)}</h2>${notification.body ? `<p>${escapeHtml(notification.body)}</p>` : ""}`;
+
+    if (redisClientIfReady()) {
+      await dispatchEvent("notification:mail", { to, subject, html }, { queue: "mail" });
+    } else {
+      await mail.sendMail({ to, subject, html });
+    }
+
+    return true;
+  }
+};

package/fastify/src/framework/notification/contracts.ts

@@ -0,0 +1,29 @@
+import type { NotifiableTarget, NotificationRecord } from "@/framework/providers/contracts.js";
+
+export type NotificationTarget = number | string | NotifiableTarget;
+export type NormalizedTarget = { type: string; id: number | string };
+
+export type NotificationOptions = {
+  type?: string;
+  title: string;
+  body?: string;
+  link?: string;
+  data?: Record<string, unknown>;
+
+  // Built-in Channels
+  broadcast?: boolean;
+  mail?: {
+    to?: string;
+    subject?: string;
+    html?: string;
+  };
+
+  // Extensible: Add any custom channel options here (e.g., sms, push, discord)
+  sms?: { to?: string; message?: string };
+  push?: { token?: string; payload?: any };
+};
+
+export interface NotificationChannel {
+  name: string;
+  send(target: NormalizedTarget, notification: NotificationRecord, options: NotificationOptions): Promise<boolean>;
+}

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

@@ -0,0 +1,59 @@
+import type { NormalizedTarget, NotificationOptions, NotificationTarget } from "@/framework/notification/contracts.js";
+import { getChannels } from "@/framework/notification/registry.js";
+import { resolveNotificationProvider } from "@/framework/providers/adapter.js";
+import type { NotificationRecord } from "@/framework/providers/contracts.js";
+
+let missingProviderWarned = false;
+
+/** Turn the public target argument into the polymorphic owner pair. */
+function normalizeTarget(target: NotificationTarget): NormalizedTarget {
+  if (target !== null && typeof target === "object") {
+    return {
+      type: String(target.type || "user").trim() || "user",
+      id: target.id
+    };
+  }
+  return { type: "user", id: target as number | string };
+}
+
+/**
+ * Why: Persists a notification to the database and triggers all active channels.
+ * When: A feature wants to record something for a user.
+ * Where: Application code, through the framework facade.
+ * How: The provider owns database storage. The channels handle delivery (mail, sms, ws).
+ */
+export async function notify(target: NotificationTarget, options: NotificationOptions): Promise<NotificationRecord | null> {
+  const provider = await resolveNotificationProvider();
+  if (!provider) {
+    if (!missingProviderWarned) {
+      missingProviderWarned = true;
+      console.warn(
+        '[notification] skipped: no notification provider is registered. Run "bun maker module:make-notification notification" then "bun maker module:migrate notification", or register a provider in src/providers/.'
+      );
+    }
+    return null;
+  }
+
+  const normalizedTarget = normalizeTarget(target);
+
+  // 1. Save to Database via the Provider
+  const normalized = await provider.create(normalizedTarget, {
+    type: options.type,
+    title: options.title,
+    body: options.body ?? null,
+    link: options.link ?? null,
+    data: options.data ?? null
+  });
+
+  // 2. Dispatch to all registered channels in parallel
+  const channels = getChannels();
+  await Promise.allSettled(
+    channels.map((channel) =>
+      channel.send(normalizedTarget, normalized, options).catch((err) => {
+        console.error(`[notification] Channel ${channel.name} failed:`, err);
+      })
+    )
+  );
+
+  return normalized;
+}

package/fastify/src/framework/notification/registry.ts

@@ -0,0 +1,15 @@
+import type { NotificationChannel } from "@/framework/notification/contracts.js";
+
+const channels = new Map<string, NotificationChannel>();
+
+export function registerChannel(channel: NotificationChannel) {
+  channels.set(channel.name, channel);
+}
+
+export function getChannels(): NotificationChannel[] {
+  return Array.from(channels.values());
+}
+
+export function clearChannels() {
+  channels.clear();
+}

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

@@ -0,0 +1,149 @@
+import { eq } from "drizzle-orm";
+import { db } from "@/framework/database/connection.js";
+import type { AuthProvider, NotificationProvider } from "./contracts.js";
+import { loadProviders } from "./loader.js";
+import { getAuthProvider, getNotificationProvider } 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;
+
+    // Define the core logic as standalone functions to avoid `this` context issues
+    const getUserById = async (id: number | string) => {
+      try {
+        const user = await (db.query.users.findFirst as any)?.({
+          where: eq(users.id, id as any),
+          with: { role: true }
+        });
+        if (user) return user;
+      } catch {}
+      try {
+        const rows = await db
+          .select()
+          .from(users)
+          .where(eq(users.id, id as any));
+        return rows?.[0] ?? null;
+      } catch {
+        return null;
+      }
+    };
+
+    const provider: AuthProvider = {
+      getUserById,
+      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 | string) {
+        try {
+          await db.delete(refreshTokens).where(eq(refreshTokens.id, tokenId as any));
+        } catch {}
+      },
+      async revokeRefreshToken(tokenId: number | string) {
+        try {
+          await db.delete(refreshTokens).where(eq(refreshTokens.id, tokenId as any));
+        } 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 | string) {
+        try {
+          // Use the standalone function instead of `this.getUserById`
+          const user = await 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;
+        }
+      }
+    };
+
+    defaultProvider = provider;
+    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;
+}
+
+/**
+ * Why: Resolves the notification storage provider.
+ * When: `notify()` persists a notification; the HTTP handlers read it back.
+ * Where: Notification runtime and the generated notification controller.
+ * How: Provider files are loaded first, so a project can replace the store from
+ *      `src/providers/` or a module provider folder. The notification module is
+ *      opt-in, so an absent provider is a normal state: callers warn once
+ *      (runtime) or answer 503 (HTTP) instead of throwing.
+ */
+export async function resolveNotificationProvider(): Promise<NotificationProvider | null> {
+  await loadProviders();
+  return getNotificationProvider();
+}