create-nexgen 1.0.4

package/template/src/framework/maker-cli/stubs/deploy/workflow/local.json.stub

@@ -0,0 +1,24 @@
+{
+  "steps": [
+    {
+      "name": "Generate deploy files",
+      "run": "deploy:create --server --force",
+      "enabled": false
+    },
+    {
+      "name": "Start shared infra",
+      "run": "deploy:server",
+      "enabled": true
+    },
+    {
+      "name": "Start app stack",
+      "run": "deploy:app",
+      "enabled": true
+    },
+    {
+      "name": "Import MySQL dump (optional)",
+      "run": "deploy:db:import --file=deploy/nexgen.sql --database=nexgen",
+      "enabled": false
+    }
+  ]
+}

package/template/src/framework/maker-cli/stubs/deploy/workflow/remote.json.stub

@@ -0,0 +1,20 @@
+{
+  "remote": {
+    "host": "127.0.0.1",
+    "user": "deploy",
+    "port": 22,
+    "keyPath": "~/.ssh/id_rsa",
+    "targetPath": "/home/deploy/nexgen"
+  },
+  "upload": {
+    "source": ".",
+    "targetSubPath": "."
+  },
+  "databaseImport": {
+    "enabled": false,
+    "file": "deploy/nexgen.sql",
+    "database": "nexgen",
+    "container": "mysql-global",
+    "user": "root"
+  }
+}

package/template/src/framework/maker-cli/stubs/example/console.ts.stub

@@ -0,0 +1,33 @@
+import { defineSchedule, dispatchEvent } from "@/framework/facade.js";
+
+/**
+ * name: Unique schedule id used as the distributed lock key.
+ * expression: Cron expression that controls when the task runs.
+ * timezone: IANA timezone for cron evaluation (example: "UTC").
+ * runOnInit: Runs once immediately when scheduler starts.
+ * enabled: Enables or disables this schedule without deleting code.
+ * ttlMs: Lock TTL in milliseconds to avoid duplicate execution.
+ */
+defineSchedule({
+  name: "{{module}}:scheduler-tick",
+  expression: "*/30 * * * * *",
+  // timezone: "UTC",
+  runOnInit: true,
+  // enabled: true,
+  // ttlMs: 120000,
+  handler: async () => {
+    /**
+     * dispatchEvent name: Event id to publish to listeners.
+     * payload: Data sent to queue/broadcast consumers.
+     * queue: Optional queue target for async event consumers.
+     * broadcast: Optional realtime fanout (all/users/roles/rooms).
+     */
+    await dispatchEvent("{{module}}.scheduler.tick", {
+      origin: "scheduler",
+      createdAt: new Date().toISOString()
+    }, {
+      queue: "default",
+      broadcast: { all: true }
+    });
+  }
+});

package/template/src/framework/maker-cli/stubs/example/controller.ts.stub

@@ -0,0 +1,503 @@
+import type { Handler } from "hono";
+import crypto from "node:crypto";
+import { cache, dispatchCommand, dispatchEvent, session, storage } from "@/framework/facade.js";
+
+/**
+ * Example controller guide:
+ * - c.req.valid("json"): reads validated JSON payload from route schema.
+ * - dispatchEvent(name, payload, options): emits domain events.
+ * - dispatchCommand(name, payload, { async, queue }): queues command-style work.
+ * - storage.generateForDownload(...): creates one-time temp download token.
+ * - storage.consumeGenerated(token): reads temp file and deletes it.
+ * - cache.put/get/remember: lightweight state for async flows (PDF status).
+ */
+
+type PdfRequest = {
+  title: string;
+  rows: number;
+  chunkSize: number;
+};
+
+function pdfStatusKey(requestId: string) {
+  return "{{module}}:pdf:status:" + requestId;
+}
+
+/**
+ * Why: Demonstrates event dispatch with both queue and websocket broadcast.
+ * When: Use as the baseline event example for async + realtime flow.
+ * Where: POST /{{module}}/event.
+ */
+export const fire: Handler = async (c: any) => {
+  // Route validates body using ExampleEventSchema in route stub.
+  const body = c.req.valid("json");
+
+  // Session example: keeps last payload for this visitor/session.
+  await session.put(c.get("sessionId"), "lastExampleEvent", body);
+
+  // Event options shown here:
+  // - queue: true -> send to default async event queue
+  // - broadcast: { all: true } -> fanout to realtime listeners
+  await dispatchEvent("{{module}}.created", body, {
+    queue: true,
+    broadcast: { all: true }
+  });
+
+  return c.json({ message: "Event dispatched", data: body }, 202);
+};
+
+/**
+ * Why: Demonstrates command-style background processing via queue.
+ * When: Use when work should run asynchronously and return 202 immediately.
+ * Where: POST /{{module}}/queue/command.
+ */
+export const queueCommand: Handler = async (c: any) => {
+  const body = c.req.valid("json");
+
+  // Command options:
+  // - async: true -> run in worker, do not block request
+  // - queue: "default" -> explicit queue channel
+  await dispatchCommand("{{module}}.process", body, {
+    async: true,
+    queue: "default"
+  });
+
+  return c.json({ message: "Queue command dispatched", data: body }, 202);
+};
+
+/**
+ * Why: Demonstrates queued events without realtime fanout.
+ * When: Use when consumers should process event in workers only.
+ * Where: POST /{{module}}/event/queued.
+ */
+export const fireQueued: Handler = async (c: any) => {
+  const body = c.req.valid("json");
+
+  await dispatchEvent("{{module}}.created", body, {
+    queue: "default"
+  });
+
+  return c.json({ message: "Queued event dispatched", data: body }, 202);
+};
+
+/**
+ * Why: Demonstrates one event feeding both queue workers and broadcast listeners.
+ * When: Use when background processing and client updates are both needed.
+ * Where: POST /{{module}}/event/queued-broadcast.
+ */
+export const fireQueuedBroadcast: Handler = async (c: any) => {
+  const body = c.req.valid("json");
+
+  await dispatchEvent("{{module}}.created", body, {
+    queue: "default",
+    broadcast: { all: true }
+  });
+
+  return c.json({ message: "Queued broadcast event dispatched", data: body }, 202);
+};
+
+/**
+ * Why: Demonstrates broadcast-only realtime events.
+ * When: Use for transient notifications with no worker processing.
+ * Where: POST /{{module}}/event/broadcast.
+ */
+export const fireBroadcast: Handler = async () => {
+  const payload = {
+    message: "Examples broadcast fired",
+    firedAt: new Date().toISOString()
+  };
+
+  await dispatchEvent("{{module}}.realtime", payload, {
+    broadcast: { all: true }
+  });
+
+  return Response.json({ message: "Broadcast event dispatched", data: payload });
+};
+
+/**
+ * Why: Demonstrates multipart upload with storage facade.
+ * When: Use when API accepts binary files from forms/clients.
+ * Where: POST /{{module}}/upload.
+ */
+export const upload: Handler = async (c) => {
+  // parseBody() is used for multipart/form-data requests.
+  const body = await c.req.parseBody();
+  const file = body.file;
+
+  if (!(file instanceof File)) {
+    return c.json({ message: "File is required" }, 422);
+  }
+
+  // Writes to public disk. Name is auto-generated when omitted.
+  const path = await storage.disk("public").putFile("uploads", file);
+
+  return c.json({
+    message: "File uploaded successfully",
+    path,
+    url: storage.disk("public").url(path)
+  });
+};
+
+/**
+ * Why: Demonstrates Excel import by reading uploaded workbook rows.
+ * When: Use when clients submit .xlsx files for server-side processing.
+ * Where: POST /{{module}}/import/excel.
+ */
+export const importExcel: Handler = async (c) => {
+  let ExcelJS: any;
+  try {
+    ({ default: ExcelJS } = await import("exceljs"));
+  } catch {
+    return c.json({ message: "Missing optional dependency 'exceljs'. Install with: bun add exceljs" }, 500);
+  }
+
+  const body = await c.req.parseBody();
+  const file = body.file;
+
+  if (!(file instanceof File)) {
+    return c.json({ message: "File is required" }, 422);
+  }
+
+  const buffer = Buffer.from(await file.arrayBuffer());
+  const workbook = new ExcelJS.Workbook();
+  await workbook.xlsx.load(buffer);
+
+  const sheet = workbook.worksheets[0];
+  if (!sheet) {
+    return c.json({ message: "Workbook has no sheets" }, 422);
+  }
+
+  const headerRow = sheet.getRow(1);
+  const headers = headerRow.values
+    .slice(1)
+    .map((v: unknown) => String(v || "").trim());
+
+  const rows: Record<string, string | number | null>[] = [];
+  sheet.eachRow((row: any, rowNumber: number) => {
+    if (rowNumber === 1) return;
+    const values = row.values.slice(1);
+    const record: Record<string, string | number | null> = {};
+    for (let i = 0; i < headers.length; i++) {
+      const key = headers[i] || `column_${i + 1}`;
+      const value = values[i];
+      record[key] = value == null ? null : (typeof value === "object" && "text" in (value as any) ? String((value as any).text) : value);
+    }
+    rows.push(record);
+  });
+
+  return c.json({
+    message: "Excel imported",
+    data: {
+      sheetName: sheet.name,
+      headers,
+      totalRows: rows.length,
+      preview: rows.slice(0, 20)
+    }
+  });
+};
+
+/**
+ * Why: Demonstrates short-lived generated downloads with one-time token consume.
+ * When: Use for temporary export artifacts that should not persist.
+ * Where: POST /{{module}}/download/generate.
+ */
+export const generateDownload: Handler = async () => {
+  // Any generated content can be stored as one-time download token.
+  const csv = ["id,title", "1,nexgen report", "2,generated and temporary"].join("\n");
+  const token = await storage.generateForDownload({
+    prefix: "{{module}}-report",
+    extension: "csv",
+    data: csv
+  });
+
+  return Response.json({
+    message: "Temporary file generated",
+    token,
+    downloadUrl: `/{{module}}/download/${encodeURIComponent(token)}`
+  });
+};
+
+/**
+ * Why: Consumes a temporary token and returns the generated CSV file.
+ * When: Called after generateDownload to perform one-time download.
+ * Where: GET /{{module}}/download/{token}.
+ */
+export const downloadGenerated: Handler = async (c) => {
+  const token = decodeURIComponent(c.req.param("token"));
+
+  try {
+    // consumeGenerated() returns bytes and removes temp file immediately.
+    const file = await storage.consumeGenerated(token);
+    return new Response(file, {
+      status: 200,
+      headers: {
+        "content-type": "text/csv; charset=utf-8",
+        "content-disposition": "attachment; filename={{module}}-report.csv"
+      }
+    });
+  } catch {
+    return c.json({ message: "Download token expired or invalid" }, 404);
+  }
+};
+
+/**
+ * Why: Demonstrates styled Excel export generation and temporary delivery.
+ * When: Use when spreadsheet output with formatting/totals is needed.
+ * Where: POST /{{module}}/download/excel/generate.
+ */
+export const generateExcelDownload: Handler = async (c: any) => {
+  let ExcelJS: any;
+  try {
+    ({ default: ExcelJS } = await import("exceljs"));
+  } catch {
+    return c.json({ message: "Missing optional dependency 'exceljs'. Install with: bun add exceljs" }, 500);
+  }
+
+  const body = c.req.valid("json") as { title: string };
+  // remember(key, ttl, factory) caches expensive work for repeated requests.
+  const rows = await cache.remember("{{module}}:index", 60, async () => [
+    { id: 1, title: "nexgen framework ready" },
+    { id: 2, title: "modules are auto-discovered" }
+  ]);
+
+  const workbook = new ExcelJS.Workbook();
+  const sheet = workbook.addWorksheet("Examples");
+  sheet.mergeCells("A1:C1");
+  sheet.getCell("A1").value = body.title;
+  sheet.getCell("A1").font = { bold: true, size: 14, color: { argb: "FFFFFFFF" } };
+  sheet.getCell("A1").alignment = { horizontal: "center", vertical: "middle" };
+  sheet.getCell("A1").fill = { type: "pattern", pattern: "solid", fgColor: { argb: "FF1F4E78" } };
+
+  sheet.addRow(["ID", "Title", "Length"]);
+  const header = sheet.getRow(2);
+  header.font = { bold: true, color: { argb: "FFFFFFFF" } };
+  header.alignment = { horizontal: "center" };
+  header.fill = { type: "pattern", pattern: "solid", fgColor: { argb: "FF2E75B6" } };
+
+  for (const row of rows) {
+    sheet.addRow([row.id, row.title, row.title.length]);
+  }
+
+  const dataStart = 3;
+  const dataEnd = dataStart + rows.length - 1;
+  const subtotalRow = dataEnd + 1;
+  const grandTotalRow = subtotalRow + 1;
+
+  sheet.getCell(`A${subtotalRow}`).value = "Subtotal";
+  sheet.getCell(`B${subtotalRow}`).value = rows.length;
+  sheet.getCell(`C${subtotalRow}`).value = { formula: `SUM(C${dataStart}:C${dataEnd})` };
+  sheet.getCell(`A${grandTotalRow}`).value = "Grand Total";
+  sheet.getCell(`B${grandTotalRow}`).value = rows.length;
+  sheet.getCell(`C${grandTotalRow}`).value = { formula: `SUM(C${dataStart}:C${dataEnd})` };
+
+  for (const rowNumber of [subtotalRow, grandTotalRow]) {
+    const row = sheet.getRow(rowNumber);
+    row.font = { bold: true };
+    row.fill = { type: "pattern", pattern: "solid", fgColor: { argb: rowNumber === grandTotalRow ? "FFFCE4D6" : "FFE2EFDA" } };
+  }
+
+  sheet.columns = [{ width: 10 }, { width: 48 }, { width: 14 }];
+  sheet.views = [{ state: "frozen", ySplit: 2 }];
+
+  sheet.eachRow((row) => {
+    row.eachCell((cell) => {
+      cell.border = {
+        top: { style: "thin", color: { argb: "FFBFBFBF" } },
+        left: { style: "thin", color: { argb: "FFBFBFBF" } },
+        bottom: { style: "thin", color: { argb: "FFBFBFBF" } },
+        right: { style: "thin", color: { argb: "FFBFBFBF" } }
+      };
+    });
+  });
+
+  const buffer = Buffer.from(await workbook.xlsx.writeBuffer());
+  const token = await storage.generateForDownload({
+    prefix: "{{module}}-report",
+    extension: "xlsx",
+    data: buffer
+  });
+
+  return c.json({
+    message: "Excel generated",
+    token,
+    downloadUrl: `/{{module}}/download/excel/${encodeURIComponent(token)}`
+  });
+};
+
+/**
+ * Why: Consumes a temporary token and returns the generated XLSX file.
+ * When: Called after generateExcelDownload for one-time Excel download.
+ * Where: GET /{{module}}/download/excel/{token}.
+ */
+export const downloadGeneratedExcel: Handler = async (c) => {
+  const token = decodeURIComponent(c.req.param("token"));
+
+  try {
+    const file = await storage.consumeGenerated(token);
+    return new Response(file, {
+      status: 200,
+      headers: {
+        "content-type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        "content-disposition": "attachment; filename={{module}}-report.xlsx"
+      }
+    });
+  } catch {
+    return c.json({ message: "Download token expired or invalid" }, 404);
+  }
+};
+
+/**
+ * Why: Starts hybrid PDF generation for heavy design + large data.
+ * When: Use when reports should be rendered with HTML/CSS and processed in background.
+ * Where: POST /{{module}}/download/pdf/generate.
+ */
+export const generatePdfDownload: Handler = async (c: any) => {
+  const body = c.req.valid("json") as PdfRequest;
+  const requestId = crypto.randomUUID();
+
+  // Queue mode path: store status in cache, then worker updates it.
+  if (cache.isAvailable()) {
+    await cache.put(pdfStatusKey(requestId), {
+      state: "pending",
+      createdAt: new Date().toISOString(),
+      mode: "queued"
+    }, 1800);
+
+    await dispatchCommand("{{module}}.pdf.generate", {
+      requestId,
+      ...body
+    }, {
+      async: true,
+      queue: "default"
+    });
+
+    return c.json({
+      message: "PDF generation queued",
+      requestId,
+      mode: "queued",
+      statusUrl: `/{{module}}/download/pdf/${requestId}`,
+      downloadUrl: `/{{module}}/download/pdf/${requestId}`
+    }, 202);
+  }
+
+  const token = await generatePdfToken(body);
+  return c.json({
+    message: "PDF generated",
+    requestId,
+    mode: "inline",
+    statusUrl: `/{{module}}/download/pdf/${requestId}`,
+    downloadUrl: `/{{module}}/download/pdf/${encodeURIComponent(token)}`
+  }, 202);
+};
+
+/**
+ * Why: Polls queued PDF status, then serves one-time PDF download when ready.
+ * When: Use after generatePdfDownload returns queued request id.
+ * Where: GET /{{module}}/download/pdf/{requestId}.
+ */
+export const downloadGeneratedPdf: Handler = async (c) => {
+  const requestId = decodeURIComponent(c.req.param("requestId"));
+
+  if (cache.isAvailable()) {
+    // Status API contract:
+    // - pending -> return 202
+    // - ready + token -> return file
+    // - failed -> return 500 with message
+    const status = await cache.get<{ state: string; token?: string; message?: string }>(pdfStatusKey(requestId));
+
+    if (!status) return c.json({ message: "Unknown PDF request id" }, 404);
+    if (status.state === "pending") return c.json({ message: "PDF is still generating", state: "pending" }, 202);
+    if (status.state === "failed") return c.json({ message: status.message || "PDF generation failed" }, 500);
+
+    if (status.token) {
+      try {
+        const file = await storage.consumeGenerated(status.token);
+        await cache.forget(pdfStatusKey(requestId));
+        return new Response(file, {
+          status: 200,
+          headers: {
+            "content-type": "application/pdf",
+            "content-disposition": "attachment; filename={{module}}-report.pdf"
+          }
+        });
+      } catch {
+        return c.json({ message: "PDF token expired or invalid" }, 404);
+      }
+    }
+  }
+
+  try {
+    const file = await storage.consumeGenerated(requestId);
+    return new Response(file, {
+      status: 200,
+      headers: {
+        "content-type": "application/pdf",
+        "content-disposition": "attachment; filename={{module}}-report.pdf"
+      }
+    });
+  } catch {
+    return c.json({ message: "PDF token expired or invalid" }, 404);
+  }
+};
+
+export async function generatePdfToken(payload: PdfRequest) {
+  let chromium: any;
+  try {
+    ({ chromium } = await import("playwright"));
+  } catch {
+    throw new Error("Missing optional dependency 'playwright'. Install with: bun add playwright and run: bunx playwright install chromium");
+  }
+  const browser = await chromium.launch({ headless: true });
+
+  try {
+    const page = await browser.newPage();
+    await page.setContent(buildPdfHtml(payload), { waitUntil: "networkidle" });
+    const pdf = await page.pdf({
+      format: "A4",
+      printBackground: true,
+      margin: { top: "16mm", right: "12mm", bottom: "16mm", left: "12mm" }
+    });
+
+    return await storage.generateForDownload({
+      prefix: "{{module}}-report",
+      extension: "pdf",
+      data: pdf
+    });
+  } finally {
+    await browser.close();
+  }
+}
+
+function buildPdfHtml(payload: PdfRequest) {
+  const rows = Array.from({ length: payload.rows }, (_, i) => ({
+    id: i + 1,
+    label: `Record ${i + 1}`,
+    value: ((i + 1) * 17) % 1000
+  }));
+  const chunks: typeof rows[] = [];
+
+  for (let i = 0; i < rows.length; i += payload.chunkSize) {
+    chunks.push(rows.slice(i, i + payload.chunkSize));
+  }
+
+  const sections = chunks.map((chunk, index) => {
+    const trs = chunk.map(item => `<tr><td>${item.id}</td><td>${item.label}</td><td>${item.value}</td></tr>`).join("");
+    return `<section class="page"><h2>Batch ${index + 1}</h2><table><thead><tr><th>ID</th><th>Label</th><th>Value</th></tr></thead><tbody>${trs}</tbody></table></section>`;
+  }).join("");
+
+  return `<!doctype html><html><head><meta charset="utf-8" /><style>
+  body{font-family:Arial,sans-serif;color:#1f2937;margin:0}
+  .hero{padding:24px;background:linear-gradient(120deg,#0f766e,#1d4ed8);color:#fff}
+  .hero h1{margin:0 0 4px 0;font-size:22px}
+  .hero p{margin:0;font-size:12px;opacity:.9}
+  .page{padding:16px 20px;page-break-after:always}
+  .page:last-child{page-break-after:auto}
+  h2{margin:0 0 10px 0;font-size:14px;color:#0f172a}
+  table{width:100%;border-collapse:collapse;font-size:11px}
+  th,td{border:1px solid #cbd5e1;padding:6px}
+  th{background:#e2e8f0;text-align:left}
+  tr:nth-child(even){background:#f8fafc}
+  </style></head><body>
+  <div class="hero"><h1>${payload.title}</h1><p>Rows: ${payload.rows} | Chunk size: ${payload.chunkSize}</p></div>
+  ${sections}
+  </body></html>`;
+}

package/template/src/framework/maker-cli/stubs/example/job.ts.stub

@@ -0,0 +1,74 @@
+import { cache, dispatchEvent, shouldQueue } from "@/framework/facade.js";
+import { generatePdfToken } from "@/modules/{{module}}/controllers/{{module}}.controller.js";
+
+/**
+ * event: Event name this worker listens to.
+ * queue: Queue name where jobs are consumed from.
+ * handler: Async processor that receives `job.data`.
+ */
+shouldQueue("{{module}}.process", "default", async (job) => {
+  const waitSeconds = Number(job.data.waitSeconds || 1);
+  await new Promise(resolve => setTimeout(resolve, waitSeconds * 1000));
+
+  await cache.put("{{module}}:last-command-job", {
+    payload: job.data,
+    handledAt: new Date().toISOString()
+  }, 120);
+
+  /**
+   * dispatchEvent name: Event id to publish to listeners.
+   * payload: Data sent to queue/broadcast consumers.
+   * queue: Optional queue target for async event consumers.
+   * broadcast: Optional realtime fanout (all/users/roles/rooms).
+   */
+  await dispatchEvent("{{module}}.process.finished", {
+    ...job.data,
+    handledAt: new Date().toISOString()
+  }, {
+    broadcast: { all: true }
+  });
+
+  return { ok: true, mode: "queue" };
+});
+
+shouldQueue("{{module}}.created", "default", async (job) => {
+  await cache.put("{{module}}:last-created-event", job.data, 120);
+  return { ok: true, mode: "event-queue" };
+});
+
+shouldQueue("{{module}}.scheduler.tick", "default", async (job) => {
+  await cache.put("{{module}}:last-scheduler-job", job.data, 120);
+  return { ok: true, mode: "scheduler-queue" };
+});
+
+shouldQueue("{{module}}.pdf.generate", "default", async (job) => {
+  const requestId = String(job.data.requestId || "");
+
+  if (!requestId) {
+    return { ok: false, mode: "pdf-queue", message: "Missing requestId" };
+  }
+
+  const key = `{{module}}:pdf:status:${requestId}`;
+
+  try {
+    const token = await generatePdfToken({
+      title: String(job.data.title || "Example PDF Report"),
+      rows: Number(job.data.rows || 1000),
+      chunkSize: Number(job.data.chunkSize || 250)
+    });
+
+    await cache.put(key, {
+      state: "ready",
+      token,
+      readyAt: new Date().toISOString()
+    }, 1800);
+
+    return { ok: true, mode: "pdf-queue" };
+  } catch (error) {
+    await cache.put(key, {
+      state: "failed",
+      message: error instanceof Error ? error.message : "Unknown error"
+    }, 1800);
+    return { ok: false, mode: "pdf-queue" };
+  }
+});