create-nexwire 4.0.0

package/express/src/framework/maker-cli/utils/file-ops.mjs

@@ -0,0 +1,30 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/** Write a file only if it does not already exist. Returns true if created. */
+export async function writeFileIfMissing(filePath, content) {
+  try {
+    await fs.access(filePath);
+    console.log(`Skipped existing: ${path.relative(process.cwd(), filePath)}`);
+    return false;
+  } catch {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, content);
+    console.log(`Created: ${path.relative(process.cwd(), filePath)}`);
+    return true;
+  }
+}
+
+/** Write a file, overwriting if it exists. */
+export async function writeFileAlways(filePath, content) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, content);
+  console.log(`Updated: ${path.relative(process.cwd(), filePath)}`);
+}
+
+/** Write multiple files under a root directory using writeFileAlways. */
+export async function writeFiles(root, files) {
+  for (const [relativePath, content] of Object.entries(files)) {
+    await writeFileAlways(path.join(root, relativePath), content);
+  }
+}

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

@@ -0,0 +1,14 @@
+/** Check if a specific flag name exists in the flags array. */
+export function hasFlag(flags, name) {
+  return flags.includes(name);
+}
+
+/** Extract the value of a --key=value flag from the flags array. Returns fallback if not found. */
+export function getOption(flags = [], name, fallback = "") {
+  const item = flags.find((flag) => flag.startsWith(`${name}=`));
+  return item ? item.slice(name.length + 1) : fallback;
+}
+
+export function stripWorkflowFlags(flags = []) {
+  return flags.filter((flag) => !["--server-only", "--app-only", "--refresh", "--dry-run"].includes(flag) && !flag.startsWith("--config="));
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Why: Detects the package manager used to run the CLI, for help usage text.
+ * When: Building the program name shown in the "Usage:" line.
+ * Where: Maker CLI entry flow.
+ * How: Reads npm config user-agent and maps to the corresponding prefix string.
+ */
+export function makerCommandPrefix() {
+  const ua = String(process.env.npm_config_user_agent || "").toLowerCase();
+  if (ua.startsWith("pnpm/")) return "pnpm";
+  if (ua.startsWith("yarn/")) return "yarn";
+  if (ua.startsWith("bun/")) return "bun";
+  if (ua.startsWith("npm/")) return "npm run";
+  return "";
+}
+
+/**
+ * Why: Overrides Commander's help so the subcommand listing shows the actual
+ * long flags (e.g. `--app-only|--server-only|--dev`) instead of a generic
+ * `[options]` marker.
+ * When: Building the CLI program before commands are registered.
+ * Where: Maker CLI entry flow.
+ * How: Injects a custom `subcommandTerm` via `configureHelp`.
+ */
+export function configureDeployHelp(program) {
+  program.configureHelp({
+    subcommandTerm(cmd) {
+      const flags = cmd.options
+        .map((option) => option.flags.split(" ")[0])
+        .filter((flag) => flag.startsWith("--"))
+        .join("|");
+      const args = cmd.registeredArguments.map((arg) => humanReadableArgName(arg)).join(" ");
+      return cmd.name() + (flags ? ` [${flags}]` : "") + (args ? ` ${args}` : "");
+    }
+  });
+}
+
+function humanReadableArgName(arg) {
+  const nameOutput = arg.name() + (arg.variadic === true ? "..." : "");
+  return arg.required ? `<${nameOutput}>` : `[${nameOutput}]`;
+}
+
+/**
+ * Why: Shows commander-generated help for the maker CLI program.
+ * When: CLI runs without a valid command.
+ * Where: Maker CLI entry flow and error handlers.
+ * How: Delegates to commander's outputHelp for consistent automatically-synced output.
+ */
+export function showHelp(program) {
+  program.outputHelp();
+}

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

@@ -0,0 +1,13 @@
+/** Validate that a name value exists and return it trimmed+lowercased. Throws if empty. */
+export function assertName(value, label) {
+  if (!value) {
+    throw new Error(`${label} is required.`);
+  }
+
+  return value.trim().toLowerCase();
+}
+
+/** Convert a kebab-case or snake_case string to PascalCase. */
+export function pascal(input) {
+  return input.replace(/(^\w|[-_]\w)/g, (part) => part.replace(/[-_]/g, "").toUpperCase());
+}

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

@@ -0,0 +1,52 @@
+import { spawn } from "node:child_process";
+import fsSync from "node:fs";
+import path from "node:path";
+
+/** Run a Node.js script as a child process using the current Node executable. */
+export async function runNodeScript(script, args = [], options = {}) {
+  await new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [script, ...args], {
+      stdio: options.silent ? "ignore" : "inherit"
+    });
+    child.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`${script} ${args.join(" ")} failed with code ${code}`))));
+    child.on("error", reject);
+  });
+}
+
+/** Resolve the path to a script inside a package in node_modules. */
+export function packageScript(packageName, scriptPath) {
+  return path.resolve(process.cwd(), "node_modules", packageName, scriptPath);
+}
+
+/** Find a local .bin executable (handles OS extensions like .cmd on Windows). */
+export function localBin(name) {
+  const extensions = process.platform === "win32" ? [".cmd", ".exe", ".ps1", ""] : [""];
+
+  for (const extension of extensions) {
+    const candidate = path.resolve(process.cwd(), "node_modules", ".bin", `${name}${extension}`);
+    if (fsSync.existsSync(candidate)) return candidate;
+  }
+
+  throw new Error(`Missing local binary: ${name}. Install project dependencies first.`);
+}
+
+/** Run an arbitrary command as a child process. Uses shell mode for Windows scripts. */
+export async function runCommand(commandName, commandArgs = [], options = {}) {
+  await new Promise((resolve, reject) => {
+    const isWindowsScript = process.platform === "win32" && /\.(cmd|ps1)$/i.test(commandName);
+    const child = isWindowsScript
+      ? spawn([commandName, ...commandArgs].map((part) => (/\s/.test(part) ? `"${part.replace(/"/g, '\\"')}"` : part)).join(" "), {
+          shell: true,
+          stdio: options.silent ? "ignore" : "inherit"
+        })
+      : spawn(commandName, commandArgs, {
+          shell: false,
+          stdio: options.silent ? "ignore" : "inherit"
+        });
+
+    child.on("exit", (code) =>
+      code === 0 ? resolve() : reject(new Error(`${commandName} ${commandArgs.join(" ")} failed with code ${code}`))
+    );
+    child.on("error", reject);
+  });
+}

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

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

package/express/src/framework/modules/routes.ts

@@ -0,0 +1,21 @@
+import type { Express } from "express";
+import { registerRouterOpenApi } from "@/framework/http/router.js";
+import { discoverModuleFiles, importFile, moduleNameFromPath } from "@/framework/modules/discover.js";
+
+export async function registerModuleRoutes(app: Express) {
+  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`);
+    }
+
+    const prefix = `/api/${moduleNameFromPath(file)}`;
+    registerRouterOpenApi(route.default, prefix);
+    app.use(prefix, route.default);
+  }
+
+  return files.length;
+}

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

@@ -0,0 +1,116 @@
+import { eq } from "drizzle-orm";
+import { db } from "@/framework/database/connection.js";
+import { dispatchEvent } from "@/framework/events/dispatcher.js";
+import { redisClientIfReady } from "@/framework/redis/client.js";
+import { mail } from "@/framework/support/mail.js";
+import { notifications } from "@/modules/auth/database/models/notifications.js";
+import { users } from "@/modules/auth/database/models/user.js";
+
+/** Extra JSON metadata attached to the notification (e.g. entity IDs, links). */
+export type NotificationOptions = {
+  /** Notification category key (default: "info") */
+  type?: string;
+  /** Notification title */
+  title: string;
+  /** Notification body text */
+  body?: string;
+  /** Optional click-through URL */
+  link?: string;
+  /** Arbitrary JSON payload stored in `data` column */
+  data?: Record<string, unknown>;
+  /** Whether to broadcast the notification to the user's socket in realtime */
+  broadcast?: boolean;
+  /** Email delivery options */
+  mail?: {
+    subject?: string;
+    html?: string;
+  };
+};
+
+/** 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 insertResult = await db.insert(notifications).values({
+    userId,
+    type: options.type || "info",
+    title: options.title,
+    body: options.body || null,
+    link: options.link || null,
+    data: options.data ? JSON.stringify(options.data) : null
+  });
+
+  const insertedId = Number((insertResult as any)[0]?.insertId ?? (insertResult as any).insertId ?? (insertResult as any).lastInsertRowid);
+  if (!insertedId) throw new Error("Failed to create notification");
+
+  const [row] = await db.select().from(notifications).where(eq(notifications.id, insertedId));
+  const normalized = normalize(row);
+
+  if (options.broadcast) {
+    await dispatchEvent("notification.created", normalized, {
+      broadcast: { users: [userId] }
+    });
+  }
+
+  if (options.mail) {
+    await sendMailChannel(userId, normalized, options);
+  }
+
+  return normalized;
+}
+
+/** Deliver an email notification, either queued (if Redis is available) or direct. */
+async function sendMailChannel(
+  userId: number,
+  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));
+
+  if (!user?.email) return;
+
+  const subject = options.mail?.subject || notification.title;
+  const html = options.mail?.html || defaultMailHtml(notification.title, notification.body);
+
+  if (redisClientIfReady()) {
+    await dispatchEvent(
+      "notification:mail",
+      {
+        to: user.email,
+        subject,
+        html
+      },
+      { queue: "mail" }
+    );
+  } else {
+    await mail.sendMail({ to: user.email, subject, html });
+  }
+}
+
+/** Generate a basic HTML email body from title and body text. */
+function defaultMailHtml(title: string, body: string | null) {
+  return `<h2>${escapeHtml(title)}</h2>${body ? `<p>${escapeHtml(body)}</p>` : ""}`;
+}
+
+function escapeHtml(str: string) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/** Convert a DB row into the normalized response shape, parsing the `data` JSON column. */
+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/queue/clear.ts

@@ -0,0 +1,22 @@
+import { clearQueue } from "@/framework/queue/queue.js";
+import { closeRedis, initRedis, redisError, redisReady } from "@/framework/redis/client.js";
+import { logger } from "@/framework/support/logger.js";
+
+/**
+ * Why: Clears Redis queue keys used by BullMQ runtime.
+ * When: CLI executes `queue:clear` maintenance command.
+ * Where: Framework queue maintenance script.
+ * How: Initializes Redis, skips safely if unavailable, then deletes prefixed keys.
+ */
+await initRedis();
+if (!redisReady()) {
+  logger.warn("Queue clear skipped because Redis is unavailable", {
+    error: redisError()
+  });
+  process.exit(0);
+}
+
+await clearQueue();
+console.log("Queue cleared");
+await closeRedis();
+process.exit(0);