create-nexwire 4.2.5 → 4.4.0

package/fastify/src/framework/support/cookie.ts

@@ -0,0 +1,71 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { appConfig, cookieConfig, jwtConfig } from "@/config/index.js";
+
+function originOf(url?: string) {
+  if (!url) return "";
+  try {
+    return new URL(url).origin;
+  } catch {
+    return "";
+  }
+}
+
+function needsCrossSiteCookie() {
+  const appOrigin = originOf(appConfig.url);
+  const frontendOrigin = originOf(appConfig.frontendUrl);
+  return Boolean(appOrigin && frontendOrigin && appOrigin !== frontendOrigin);
+}
+
+function baseOptions() {
+  const crossSiteCookie = needsCrossSiteCookie();
+  const sameSite: "none" | "lax" = crossSiteCookie ? "none" : "lax";
+  return {
+    httpOnly: true,
+    secure: crossSiteCookie,
+    sameSite,
+    path: "/"
+  };
+}
+
+/** Reads a signed cookie, returning the value only when the signature is valid. */
+function readSigned(request: FastifyRequest, name: string) {
+  const raw = request.cookies?.[name];
+  if (!raw) return undefined;
+  const result = request.unsignCookie(raw);
+  return result.valid ? result.value : undefined;
+}
+
+export const cookie = {
+  async setAuth(reply: FastifyReply, token: string) {
+    reply.setCookie(`${cookieConfig.name}_access`, token, {
+      ...baseOptions(),
+      // @fastify/cookie expects maxAge in seconds.
+      maxAge: jwtConfig.accessExpirySeconds,
+      signed: true
+    });
+  },
+
+  async setRefresh(reply: FastifyReply, token: string, maxAge?: number) {
+    reply.setCookie(`${cookieConfig.name}_refresh`, token, {
+      ...baseOptions(),
+      maxAge: typeof maxAge === "number" ? maxAge : jwtConfig.refreshExpirySeconds,
+      signed: true
+    });
+  },
+
+  async getAuth(request: FastifyRequest) {
+    return readSigned(request, `${cookieConfig.name}_access`);
+  },
+
+  async getRefresh(request: FastifyRequest) {
+    return readSigned(request, `${cookieConfig.name}_refresh`);
+  },
+
+  deleteAuth(reply: FastifyReply) {
+    reply.clearCookie(`${cookieConfig.name}_access`, { path: "/" });
+  },
+
+  deleteRefresh(reply: FastifyReply) {
+    reply.clearCookie(`${cookieConfig.name}_refresh`, { path: "/" });
+  }
+};

package/fastify/src/framework/support/jwt.ts

@@ -0,0 +1,33 @@
+import { randomUUID } from "node:crypto";
+import jwtLib from "jsonwebtoken";
+import { jwtConfig } from "@/config/index.js";
+
+export const jwt = {
+  async generateToken(payload: any, type: "access" | "refresh", expirySeconds?: number) {
+    const now = Math.floor(Date.now() / 1000);
+    const exp =
+      now +
+      (typeof expirySeconds === "number"
+        ? expirySeconds
+        : type === "refresh"
+          ? jwtConfig.refreshExpirySeconds
+          : jwtConfig.accessExpirySeconds);
+    const secret = type === "refresh" ? jwtConfig.refreshSecret : jwtConfig.accessSecret;
+    const jti = type === "refresh" ? randomUUID() : undefined;
+
+    const tokenPayload = { ...payload, type, iat: now, exp, ...(jti ? { jti } : {}) };
+    const token = await jwtLib.sign(tokenPayload, secret, { algorithm: jwtConfig.algorithm });
+
+    return { token, jti, exp };
+  },
+
+  async verifyToken(token: string, type: "access" | "refresh") {
+    try {
+      const secret = type === "refresh" ? jwtConfig.refreshSecret : jwtConfig.accessSecret;
+      const payload = (await jwtLib.verify(token, secret, { algorithms: [jwtConfig.algorithm] })) as Record<string, unknown>;
+      return payload.type === type ? payload : null;
+    } catch {
+      return null;
+    }
+  }
+};

package/fastify/src/framework/support/lifecycle.ts

@@ -0,0 +1,35 @@
+const shutdownSignals = ["SIGINT", "SIGTERM"] as const;
+export type ShutdownSignal = (typeof shutdownSignals)[number];
+
+type ShutdownHandler = (signal: ShutdownSignal) => Promise<void>;
+
+/**
+ * Why: Avoid duplicated graceful-shutdown wiring across runtime entrypoints.
+ * When: Server/worker/scheduler need signal handling.
+ * Where: Runtime bootstrap files.
+ * How: Registers SIGINT/SIGTERM handlers and forwards signal to async callback.
+ */
+export function registerShutdownSignals(handler: ShutdownHandler) {
+  for (const signal of shutdownSignals) {
+    process.on(signal, () => {
+      void handler(signal);
+    });
+  }
+}
+
+/**
+ * Why: Keep comma-separated CLI/env parsing consistent.
+ * When: Runtime options are provided as a single CSV string.
+ * Where: Worker and other entrypoints.
+ * How: Trims tokens, removes blanks, and falls back when empty.
+ */
+export function parseCsvOrFallback(value: string | undefined, fallback: string[]) {
+  if (!value) return fallback;
+
+  const parsed = value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+
+  return parsed.length ? parsed : fallback;
+}

package/fastify/src/framework/support/logger.ts

@@ -0,0 +1,148 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Writable } from "node:stream";
+import pino from "pino";
+import { appConfig, loggingConfig } from "@/config/index.js";
+
+const logDir = path.resolve(process.cwd(), "src", "storage", "logs");
+const MAX_FILE_BYTES = 10 * 1024 * 1024;
+
+if (!fs.existsSync(logDir)) {
+  fs.mkdirSync(logDir, { recursive: true });
+}
+
+const LEVEL_COLORS: Record<number, string> = {
+  10: "\x1b[90m",
+  20: "\x1b[90m",
+  30: "\x1b[32m",
+  40: "\x1b[33m",
+  50: "\x1b[31m",
+  60: "\x1b[31m"
+};
+
+const RESET = "\x1b[0m";
+
+function formatLine(chunk: string, colorize: boolean): string {
+  const line = chunk.trim();
+  if (!line) return "";
+
+  let record: Record<string, unknown>;
+  try {
+    record = JSON.parse(line);
+  } catch {
+    return colorize ? line : `${line}\n`;
+  }
+
+  const time = typeof record.time === "number" ? new Date(record.time) : new Date(String(record.time));
+  const timestamp = Number.isNaN(time.getTime()) ? "" : `[${time.toLocaleTimeString("en-GB", { hour12: false })}] `;
+  const levelNumber = typeof record.level === "number" ? record.level : 30;
+  const label = pino.levels.labels[levelNumber] ?? "info";
+  const message = typeof record.msg === "string" ? record.msg : "";
+
+  const ignored = new Set(["time", "level", "msg", "pid", "hostname", "service"]);
+  const meta: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(record)) {
+    if (!ignored.has(key)) meta[key] = value;
+  }
+
+  const level = colorize ? `${LEVEL_COLORS[levelNumber] ?? ""}${label}${RESET}` : label;
+  const metaString = Object.keys(meta).length ? `\n${JSON.stringify(meta, null, 2)}` : "";
+  return `${timestamp}${level} -> ${message}${metaString}\n`;
+}
+
+function consoleWriter() {
+  return new Writable({
+    write(chunk, _encoding, callback) {
+      const text = formatLine(chunk.toString("utf8"), true);
+      if (text) process.stdout.write(text);
+      callback();
+    }
+  });
+}
+
+function rotate(filePath: string, maxFiles: number) {
+  for (let index = maxFiles - 1; index >= 1; index--) {
+    const from = `${filePath}.${index}`;
+    const to = `${filePath}.${index + 1}`;
+    if (fs.existsSync(from)) fs.renameSync(from, to);
+  }
+  if (fs.existsSync(filePath)) fs.renameSync(filePath, `${filePath}.1`);
+}
+
+function fileWriter(filePath: string, maxFiles: number) {
+  let bytes = 0;
+
+  return new Writable({
+    write(chunk, _encoding, callback) {
+      const text = formatLine(chunk.toString("utf8"), false);
+      bytes += Buffer.byteLength(text);
+      if (bytes >= MAX_FILE_BYTES) {
+        rotate(filePath, maxFiles);
+        bytes = 0;
+      }
+      try {
+        fs.appendFileSync(filePath, text);
+      } catch {
+        // best-effort file logging
+      }
+      callback();
+    }
+  });
+}
+
+const base = pino(
+  {
+    level: loggingConfig.level,
+    base: { service: appConfig.name },
+    timestamp: pino.stdTimeFunctions.isoTime
+  },
+  pino.multistream([
+    { stream: consoleWriter(), level: loggingConfig.level },
+    { stream: fileWriter(path.join(logDir, "app.log"), 5), level: "info" },
+    { stream: fileWriter(path.join(logDir, "fatal.log"), 3), level: "error" }
+  ])
+);
+
+type CompatLogger = {
+  fatal: (message: string, meta?: Record<string, unknown>) => void;
+  error: (message: string, meta?: Record<string, unknown>) => void;
+  warn: (message: string, meta?: Record<string, unknown>) => void;
+  info: (message: string, meta?: Record<string, unknown>) => void;
+  debug: (message: string, meta?: Record<string, unknown>) => void;
+  trace: (message: string, meta?: Record<string, unknown>) => void;
+  child: (bindings: Record<string, unknown>) => CompatLogger;
+};
+
+function compat(child: pino.Logger): CompatLogger {
+  const wrap = (log: (obj: object, msg?: string, ...args: unknown[]) => void) => (message: string, meta?: Record<string, unknown>) =>
+    log.call(child, meta ?? {}, message);
+
+  return {
+    fatal: wrap(child.fatal),
+    error: wrap(child.error),
+    warn: wrap(child.warn),
+    info: wrap(child.info),
+    debug: wrap(child.debug),
+    trace: wrap(child.trace),
+    child: (bindings) => compat(child.child(bindings))
+  };
+}
+
+/**
+ * Why: Shared structured logger for app/runtime/framework internals.
+ * When: Any code needs operational logs or error reporting.
+ * Where: Imported across framework and modules.
+ * How: Emits JSON via pino to a color console sink plus rotating app/fatal
+ *      files, keeping the legacy `(message, meta)` call signature.
+ */
+export const logger: CompatLogger = compat(base);
+
+process.on("uncaughtException", (error) => {
+  logger.error("Uncaught exception", { error: { name: error.name, message: error.message, stack: error.stack } });
+  process.exit(1);
+});
+
+process.on("unhandledRejection", (reason) => {
+  const error = reason instanceof Error ? reason : new Error(String(reason));
+  logger.error("Unhandled rejection", { error: { name: error.name, message: error.message, stack: error.stack } });
+});

package/fastify/src/framework/support/mail.ts

@@ -0,0 +1,56 @@
+import nodemailer from "nodemailer";
+import { mailConfig } from "@/config/index.js";
+import { createCircuitBreaker, isCircuitBreakerError } from "@/framework/circuit-breaker/cb.js";
+import { logger } from "@/framework/support/logger.js";
+
+type MailPayload = {
+  to: string;
+  subject: string;
+  html?: string;
+  text?: string;
+};
+
+const transport = nodemailer.createTransport({
+  host: mailConfig.host,
+  port: mailConfig.port,
+  secure: mailConfig.encryption === "ssl",
+  auth: mailConfig.username ? { user: mailConfig.username, pass: mailConfig.password } : undefined
+});
+
+const mailBreaker = createCircuitBreaker({ name: "SMTP Mail" });
+
+export const mail = {
+  /**
+   * Why: Sends transactional email through configured SMTP transport.
+   * When: Features need notifications/password reset/signup email.
+   * Where: Jobs and event handlers.
+   * How: Uses nodemailer transport and respects the fail-silent setting.
+   */
+  async sendMail(payload: MailPayload) {
+    try {
+      return await mailBreaker.exec(() =>
+        transport.sendMail({
+          from: mailConfig.fromAddress,
+          ...payload
+        })
+      );
+    } catch (error) {
+      // Distinguish between a Circuit Breaker rejection and an actual SMTP failure
+      if (isCircuitBreakerError(error)) {
+        logger.warn("Mail send skipped: Circuit breaker is open", {
+          to: payload.to,
+          subject: payload.subject
+        });
+      } else {
+        logger.error("Mail send failed", {
+          to: payload.to,
+          subject: payload.subject,
+          error: error instanceof Error ? error.message : error
+        });
+      }
+
+      if (!mailConfig.failSilent) throw error;
+      return null;
+    }
+  }
+};

package/fastify/src/framework/support/password.ts

@@ -0,0 +1,23 @@
+import bcrypt from "bcryptjs";
+
+export const password = {
+  /**
+   * Why: Hashes plaintext password before persistence.
+   * When: Registration and password reset flows.
+   * Where: Auth controllers/seeders.
+   * How: Uses bcrypt with cost factor 10.
+   */
+  async hashPassword(inputPassword: string) {
+    return await bcrypt.hash(inputPassword, 10);
+  },
+
+  /**
+   * Why: Compares plaintext password to stored hash.
+   * When: Login/authentication checks.
+   * Where: Auth controllers/middleware.
+   * How: Uses bcrypt secure compare.
+   */
+  async verifyPassword(inputPassword: string, hashedPassword: string) {
+    return await bcrypt.compare(inputPassword, hashedPassword);
+  }
+};

package/fastify/src/framework/support/status-codes.ts

@@ -0,0 +1,75 @@
+// 1xx Informational
+export const CONTINUE = 100;
+export const SWITCHING_PROTOCOLS = 101;
+export const PROCESSING = 102;
+export const EARLY_HINTS = 103;
+
+// 2xx Success
+export const OK = 200;
+export const CREATED = 201;
+export const ACCEPTED = 202;
+export const NON_AUTHORITATIVE_INFORMATION = 203;
+export const NO_CONTENT = 204;
+export const RESET_CONTENT = 205;
+export const PARTIAL_CONTENT = 206;
+export const MULTI_STATUS = 207;
+export const ALREADY_REPORTED = 208;
+export const IM_USED = 226;
+
+// 3xx Redirection
+export const MULTIPLE_CHOICES = 300;
+export const MOVED_PERMANENTLY = 301;
+export const FOUND = 302;
+export const MOVED_TEMPORARILY = 302;
+export const SEE_OTHER = 303;
+export const NOT_MODIFIED = 304;
+export const USE_PROXY = 305;
+export const TEMPORARY_REDIRECT = 307;
+export const PERMANENT_REDIRECT = 308;
+
+// 4xx Client Error
+export const BAD_REQUEST = 400;
+export const UNAUTHORIZED = 401;
+export const PAYMENT_REQUIRED = 402;
+export const FORBIDDEN = 403;
+export const NOT_FOUND = 404;
+export const METHOD_NOT_ALLOWED = 405;
+export const NOT_ACCEPTABLE = 406;
+export const PROXY_AUTHENTICATION_REQUIRED = 407;
+export const REQUEST_TIMEOUT = 408;
+export const CONFLICT = 409;
+export const GONE = 410;
+export const LENGTH_REQUIRED = 411;
+export const PRECONDITION_FAILED = 412;
+export const PAYLOAD_TOO_LARGE = 413;
+export const REQUEST_TOO_LONG = 413;
+export const URI_TOO_LONG = 414;
+export const REQUEST_URI_TOO_LONG = 414;
+export const UNSUPPORTED_MEDIA_TYPE = 415;
+export const RANGE_NOT_SATISFIABLE = 416;
+export const REQUESTED_RANGE_NOT_SATISFIABLE = 416;
+export const EXPECTATION_FAILED = 417;
+export const IM_A_TEAPOT = 418;
+export const MISDIRECTED_REQUEST = 421;
+export const UNPROCESSABLE_ENTITY = 422;
+export const LOCKED = 423;
+export const FAILED_DEPENDENCY = 424;
+export const TOO_EARLY = 425;
+export const UPGRADE_REQUIRED = 426;
+export const PRECONDITION_REQUIRED = 428;
+export const TOO_MANY_REQUESTS = 429;
+export const REQUEST_HEADER_FIELDS_TOO_LARGE = 431;
+export const UNAVAILABLE_FOR_LEGAL_REASONS = 451;
+
+// 5xx Server Error
+export const INTERNAL_SERVER_ERROR = 500;
+export const NOT_IMPLEMENTED = 501;
+export const BAD_GATEWAY = 502;
+export const SERVICE_UNAVAILABLE = 503;
+export const GATEWAY_TIMEOUT = 504;
+export const HTTP_VERSION_NOT_SUPPORTED = 505;
+export const VARIANT_ALSO_NEGOTIATES = 506;
+export const INSUFFICIENT_STORAGE = 507;
+export const LOOP_DETECTED = 508;
+export const NOT_EXTENDED = 510;
+export const NETWORK_AUTHENTICATION_REQUIRED = 511;

package/fastify/src/framework/support/upload.ts

@@ -0,0 +1,181 @@
+import path from "node:path";
+import type { FastifyRequest } from "fastify";
+import type { MultipartFile } from "@fastify/multipart";
+
+export type UploadedFile = {
+  fieldname: string;
+  originalname: string;
+  encoding: string;
+  mimetype: string;
+  size: number;
+  buffer: Buffer;
+};
+
+export type UploadOptions = {
+  /**
+   * Form field name that carries the file(s). Matches the client's FormData key.
+   */
+  field: string;
+  /**
+   * When set, accepts an array of up to `multiple` files on that field.
+   * Omit for a single-file upload (exposed as `request.upload`).
+   */
+  multiple?: number;
+  /**
+   * Maximum allowed file size in bytes. Defaults to unlimited.
+   */
+  maxSize?: number;
+  /**
+   * Allowed file extensions (lowercase, with dot), e.g. [".xlsx", ".xlsb"].
+   * Rejects others with a 422 message.
+   */
+  allowedExtensions?: string[];
+  /**
+   * Allowed MIME types, e.g. ["application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"].
+   * When provided alongside extensions, a file must satisfy both.
+   */
+  allowedMimeTypes?: string[];
+};
+
+export type UploadFieldsSpec = Array<{ name: string; maxCount?: number }>;
+
+type UploadRules = Omit<UploadOptions, "field" | "multiple">;
+
+function humanSize(bytes: number): string {
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  let i = 0;
+  let size = bytes;
+  while (size >= 1024 && i < units.length - 1) {
+    size /= 1024;
+    i += 1;
+  }
+  return `${Math.round(size * 100) / 100} ${units[i]}`;
+}
+
+function validationError(message: string) {
+  const error = new Error(message) as Error & { statusCode: number };
+  error.statusCode = 422;
+  return error;
+}
+
+function checkRules(file: MultipartFile, rules: UploadRules) {
+  const ext = path.extname(file.filename).toLowerCase();
+  if (rules.allowedExtensions?.length && !rules.allowedExtensions.includes(ext)) {
+    throw validationError(`File must be ${rules.allowedExtensions.join(" or ")}`);
+  }
+  if (rules.allowedMimeTypes?.length && !rules.allowedMimeTypes.includes(file.mimetype)) {
+    throw validationError(`File type ${file.mimetype} is not allowed`);
+  }
+}
+
+async function toUpload(file: MultipartFile, rules: UploadRules): Promise<UploadedFile> {
+  checkRules(file, rules);
+
+  let buffer: Buffer;
+  try {
+    buffer = await file.toBuffer();
+  } catch {
+    throw validationError(`File size must be less than ${humanSize(rules.maxSize ?? 0)}`);
+  }
+
+  if (typeof rules.maxSize === "number" && buffer.length > rules.maxSize) {
+    throw validationError(`File size must be less than ${humanSize(rules.maxSize)}`);
+  }
+
+  return {
+    fieldname: file.fieldname,
+    originalname: file.filename,
+    encoding: file.encoding,
+    mimetype: file.mimetype,
+    size: buffer.length,
+    buffer
+  };
+}
+
+function rethrowMultipart(error: unknown, maxCount: number, rules: UploadRules): never {
+  const code = (error as { code?: string })?.code;
+  if (code === "FST_REQ_FILE_TOO_LARGE") {
+    throw validationError(`File size must be less than ${humanSize(rules.maxSize ?? 0)}`);
+  }
+  if (code === "FST_FILES_LIMIT" || code === "FST_PARTS_LIMIT") {
+    throw validationError(`Too many files, max ${maxCount} allowed`);
+  }
+  throw error;
+}
+
+/**
+ * Why: Parses multipart uploads into memory as a reusable Fastify preHandler.
+ * When: Any route needs to accept file uploads (single, multiple, or labeled fields).
+ * Where: Route files via `preHandler: upload({...})`.
+ * How: Wraps `@fastify/multipart` so handlers receive `request.upload` /
+ *      `request.uploads` buffers and size/extension/MIME rules are enforced;
+ *      failures are normalized into readable 422 errors before the handler runs.
+ */
+export function upload(options: UploadOptions) {
+  const { field, multiple, ...rules } = options;
+  const maxCount = multiple ?? 1;
+
+  return async function uploadPreHandler(request: FastifyRequest) {
+    try {
+      if (multiple) {
+        const files: UploadedFile[] = [];
+        for await (const file of request.files({ limits: { files: maxCount, fileSize: rules.maxSize } })) {
+          if (file.fieldname !== field) continue;
+          if (files.length >= maxCount) break;
+          files.push(await toUpload(file, rules));
+        }
+        if (files.length === 0) throw validationError("File required");
+        request.uploads = files;
+        return;
+      }
+
+      const file = await request.file({ limits: { fileSize: rules.maxSize } });
+      if (!file || file.fieldname !== field) throw validationError("File required");
+      request.upload = await toUpload(file, rules);
+    } catch (error) {
+      if ((error as { statusCode?: number })?.statusCode === 422) throw error;
+      rethrowMultipart(error, maxCount, rules);
+    }
+  };
+}
+
+/**
+ * Why: Parses multipart forms carrying multiple labeled file fields at once.
+ * When: A form uploads several different inputs (e.g. avatar + document) in one request.
+ * Where: Route files via `preHandler: fields([{ name: "avatar" }, { name: "docs", maxCount: 5 }])`.
+ * How: Iterates every uploaded file and groups it by field, enforcing per-field
+ *      max counts and the shared size/MIME/extension rules.
+ */
+export function fields(spec: UploadFieldsSpec, options: UploadRules = {}) {
+  const limits = new Map(spec.map((entry) => [entry.name, entry.maxCount ?? 1]));
+  const total = spec.reduce((sum, entry) => sum + (entry.maxCount ?? 1), 0);
+
+  return async function fieldsPreHandler(request: FastifyRequest) {
+    const grouped: Record<string, UploadedFile[]> = {};
+    let totalReceived = 0;
+
+    try {
+      for await (const file of request.files({ limits: { files: total, fileSize: options.maxSize } })) {
+        const maxCount = limits.get(file.fieldname);
+        if (maxCount === undefined) continue;
+
+        const bucket = (grouped[file.fieldname] ??= []);
+        if (bucket.length >= maxCount) {
+          throw validationError(`Too many files for ${file.fieldname}, max ${maxCount} allowed`);
+        }
+        if (totalReceived >= total) {
+          throw validationError(`Too many files, max ${total} allowed`);
+        }
+
+        bucket.push(await toUpload(file, options));
+        totalReceived += 1;
+      }
+    } catch (error) {
+      if ((error as { statusCode?: number })?.statusCode === 422) throw error;
+      rethrowMultipart(error, total, options);
+    }
+
+    if (totalReceived === 0) throw validationError("File required");
+    request.uploads = grouped;
+  };
+}

package/fastify/src/framework/support/url.ts

@@ -0,0 +1,41 @@
+import { appConfig } from "@/config/index.js";
+import { hasUiBuild } from "@/framework/http/static.js";
+
+export const urls = {
+  /**
+   * Why: Returns normalized app base URL without trailing slash.
+   * When: Building absolute links.
+   * Where: Mail/reset URL generation.
+   * How: Trims trailing slash from the configured app URL.
+   */
+  appUrl() {
+    return appConfig.url.replace(/\/$/, "");
+  },
+
+  /**
+   * Why: Builds absolute URL pointing at the SPA page that handles the path.
+   * When: Creating links for emails / external callbacks (reset, verify).
+   * Where: Auth/password reset and integrations.
+   * How: Three independent knobs decide the origin —
+   *      appConfig.frontendUrl: the SPA is a separate build/origin (dev Vite
+   *          dev server, or a separately deployed SPA). Link there.
+   *      appConfig.uiEnabled + hasUiBuild(): the framework serves the built
+   *          SPA itself, so the page resolves to the app origin.
+   *      appConfig.uiEnabled + no UI build: the Vite dev server is still
+   *          running (UI not built yet) — use the origin the maker-cli
+   *          injected (NEXWIRE_FRONTEND_URL, dev Vite dev server).
+   *      When BOTH origin knobs are unset (API-only mode) there is no SPA to
+   *          point at — fall back to the app URL so the link is valid.
+   */
+  url(path = "") {
+    const base =
+      appConfig.frontendUrl ||                                // explicit SPA origin — wins
+      (appConfig.uiEnabled
+        ? hasUiBuild()
+          ? urls.appUrl()                                     // built SPA, framework serves it — same origin
+          : process.env.NEXWIRE_FRONTEND_URL || urls.appUrl()  // dev Vite dev server — injected by maker-cli
+        : appConfig.url);                                     // API-only
+    if (!path) return base;
+    return `${base}${path.startsWith("/") ? path : `/${path}`}`;
+  }
+};