create-nexgen 1.0.4

package/template/src/framework/maker-cli/src/levels/level-2/module/index.mjs

@@ -0,0 +1,116 @@
+import { assertName } from "../../level-1/naming.mjs";
+import { runSeed } from "../db/core.mjs";
+import { assertModuleHasSeeders, cleanModuleTrash, deleteModule, deleteNotificationModule, listModules, makeController, makeExampleModule, makeJob, makeModel, makeModule, makeNotificationModule, makeRoute, makeSchedule, makeSeeder, runModuleMigrate } from "./core.mjs";
+
+/** Register module:* subcommands on the CLI program. */
+export function registerModuleCommands(program, rawArgs) {
+  program
+    .command("module:make <name>")
+    .description("Create a module with controller, route, model, and seeder folders")
+    .allowUnknownOption(true)
+    .action(async (name) => makeModule(name));
+  program
+    .command("module:make-notification [name]")
+    .description("Generate notification module (controller, routes, job, bell, page)")
+    .allowUnknownOption(true)
+    .action(async (name) => {
+      const maybeModule = name && !name.startsWith("--") ? name : "";
+      await makeNotificationModule(maybeModule || "notification");
+    });
+  program
+    .command("module:example [name]")
+    .description("Generate one-shot example module with queue/broadcast/scheduler cases")
+    .allowUnknownOption(true)
+    .action(async (name) => makeExampleModule(name || "example"));
+  program
+    .command("module:delete-notification [name]")
+    .description("Remove notification module, bell, and page (moves to trash)")
+    .option("--yes", "Confirm deletion without prompt")
+    .option("--dry-run", "Print what would be deleted without executing")
+    .allowUnknownOption(true)
+    .action(async (name) => {
+      const maybeModule = name && !name.startsWith("--") ? name : "";
+      const flagStart = maybeModule ? 2 : 1;
+      await deleteNotificationModule(maybeModule || "notification", rawArgs.slice(flagStart));
+    });
+  program
+    .command("module:delete <name>")
+    .description("Move a module directory to storage trash (soft delete)")
+    .option("--yes", "Confirm deletion without prompt")
+    .option("--dry-run", "Print what would be deleted without executing")
+    .allowUnknownOption(true)
+    .action(async (name) => deleteModule(name, rawArgs.slice(2)));
+  program
+    .command("module:trash:clean [name]")
+    .description("Permanently remove entries from module trash storage")
+    .option("--yes", "Confirm cleanup without prompt")
+    .option("--dry-run", "Print what would be cleaned without executing")
+    .allowUnknownOption(true)
+    .action(async (name) => {
+      const maybeModule = name && !name.startsWith("--") ? name : "";
+      const flagStart = maybeModule ? 2 : 1;
+      await cleanModuleTrash(maybeModule, rawArgs.slice(flagStart));
+    });
+  program
+    .command("module:make-route <module> [controller]")
+    .description("Generate a route file for an existing module")
+    .option("--force", "Overwrite existing route file")
+    .option("--dry-run", "Print what would be created without executing")
+    .allowUnknownOption(true)
+    .action(async (moduleName, controller) => makeRoute(moduleName, controller, rawArgs.slice(3)));
+  program
+    .command("module:make-controller <module> [name]")
+    .description("Generate a controller for an existing module")
+    .option("--force", "Overwrite existing controller files")
+    .option("--dry-run", "Print what would be created without executing")
+    .allowUnknownOption(true)
+    .action(async (moduleName, name) => makeController(moduleName, name, rawArgs.slice(3)));
+  program
+    .command("module:make-model <module> [name]")
+    .description("Generate a model file for an existing module")
+    .option("--force", "Overwrite existing model file")
+    .option("--dry-run", "Print what would be created without executing")
+    .allowUnknownOption(true)
+    .action(async (moduleName, name) => makeModel(moduleName, name, rawArgs.slice(3)));
+  program
+    .command("module:make-seeder <module> [name]")
+    .description("Generate a seeder file for an existing module model")
+    .option("--force", "Overwrite existing seeder file")
+    .option("--dry-run", "Print what would be created without executing")
+    .allowUnknownOption(true)
+    .action(async (moduleName, name) => makeSeeder(moduleName, name, rawArgs.slice(3)));
+  program
+    .command("module:make-job <module> [name]")
+    .description("Generate a job file for an existing module")
+    .option("--force", "Overwrite existing job file")
+    .option("--dry-run", "Print what would be created without executing")
+    .allowUnknownOption(true)
+    .action(async (moduleName, name) => makeJob(moduleName, name, rawArgs.slice(3)));
+  program
+    .command("module:make-console <module> [name]")
+    .description("Generate a scheduler/console file for an existing module")
+    .option("--force", "Overwrite existing console file")
+    .option("--dry-run", "Print what would be created without executing")
+    .allowUnknownOption(true)
+    .action(async (moduleName, name) => makeSchedule(moduleName, name, rawArgs.slice(3)));
+  program
+    .command("module:list")
+    .description("List all discovered modules")
+    .allowUnknownOption(true)
+    .action(async () => listModules());
+  program
+    .command("module:seed <module>")
+    .description("Run seeders for one module")
+    .allowUnknownOption(true)
+    .action(async (moduleName) => {
+      const normalized = assertName(moduleName, "Module name");
+      await assertModuleHasSeeders(normalized);
+      await runSeed(normalized);
+    });
+  program
+    .command("module:migrate <module>")
+    .description("Generate module-only schema, generate migration, then run migrate")
+    .option("--keep-temp", "Keep temporary schema file after migration")
+    .allowUnknownOption(true)
+    .action(async (moduleName) => runModuleMigrate(moduleName, rawArgs));
+}

package/template/src/framework/maker-cli/src/levels/level-2/runtime/build-frontend.mjs

@@ -0,0 +1,16 @@
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const isFalse = (v) => v === "false";
+
+const envFile = resolve(process.cwd(), ".env");
+const fileDisabled = existsSync(envFile) && /^FRONTEND=false\s*$/m.test(readFileSync(envFile, "utf-8"));
+
+if (isFalse(process.env.FRONTEND) || fileDisabled) {
+  console.log("Frontend build skipped (FRONTEND=false)");
+  mkdirSync("public", { recursive: true });
+  process.exit(0);
+}
+
+execSync("vite build --config src/resources/vite.config.ts", { stdio: "inherit" });

package/template/src/framework/maker-cli/src/levels/level-2/runtime/core.mjs

@@ -0,0 +1,311 @@
+import { spawn } from "node:child_process";
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { glob } from "glob";
+import { getOption, hasFlag } from "../../level-1/flags.mjs";
+import { localBin, packageScript, runCommand, runNodeScript } from "../../level-1/process.mjs";
+
+/** Parse --with or --view flags to determine which dev tools to launch. */
+function parseWithOptions(flags = []) {
+  const supported = new Set(["redis", "maildev", "studio", "bullmq"]);
+  const selected = new Set();
+
+  for (const raw of [getOption(flags, "--with"), getOption(flags, "--view")]) {
+    if (!raw) continue;
+    for (const item of raw.split(",")) {
+      const key = item.trim().toLowerCase();
+      if (!key) continue;
+
+      const normalized = key === "queue" ? "bullmq" : key;
+      if (!supported.has(normalized)) {
+        console.warn(`[dev] Unknown --with option '${key}' (supported: redis, maildev, studio, bullmq)`);
+        continue;
+      }
+
+      selected.add(normalized);
+    }
+  }
+
+  return selected;
+}
+
+/** Build a list of dev UI tools to launch based on flags and with-options. */
+function devViewList(flags = [], withOptions = new Set()) {
+  const selected = new Set(withOptions);
+  if (hasFlag(flags, "--with-redis-view")) selected.add("redis");
+  if (hasFlag(flags, "--with-maildev")) selected.add("maildev");
+  if (hasFlag(flags, "--with-db-studio")) selected.add("studio");
+  return Array.from(selected);
+}
+
+/** Build redis-commander CLI arguments from REDIS_URL env. */
+function redisConnectionArgs() {
+  const redisUrl = new URL(process.env.REDIS_URL || "redis://127.0.0.1:6379");
+  const result = [
+    "--port",
+    process.env.REDIS_COMMANDER_PORT || "1369",
+    "--redis-host",
+    redisUrl.hostname || "127.0.0.1",
+    "--redis-port",
+    redisUrl.port || "6379"
+  ];
+
+  if (redisUrl.password) result.push("--redis-password", decodeURIComponent(redisUrl.password));
+  return result;
+}
+
+/** Run the full dev stack: API, frontend, queue worker, and optional UI tools. */
+async function runDevStack(flags = []) {
+  const commands = [
+    { label: "api", args: ["serve", "--src"], required: true, hint: "http://localhost:3000" }
+  ];
+
+  if (process.env.FRONTEND !== "false") {
+    commands.push({ label: "frontend", args: ["frontend:dev"], required: true, hint: "http://localhost:5173" });
+  }
+
+  if (process.env.REDIS !== "false") {
+    commands.push({ label: "queue-worker", args: ["queue:work", "--queue=default,mail", "--quiet", "--src"], required: false });
+  }
+
+  const withOptions = parseWithOptions(flags);
+  const views = devViewList(flags, withOptions);
+  const enableRedisView =
+    process.env.REDIS !== "false" &&
+    (hasFlag(flags, "--with-redis-view") || withOptions.has("redis"));
+  const enableMaildev = hasFlag(flags, "--with-maildev") || withOptions.has("maildev");
+  const enableDbStudio = hasFlag(flags, "--with-db-studio") || withOptions.has("studio");
+
+  if (enableRedisView) {
+    commands.push({ label: "redis-view", args: ["redis:view", "--quiet"], required: false, hint: "http://localhost:1369" });
+  }
+  if (enableMaildev) {
+    commands.push({ label: "maildev-view", args: ["maildev:view", "--quiet"], required: false, hint: "http://localhost:1080" });
+  }
+  if (enableDbStudio) {
+    commands.push({ label: "db-studio", args: ["db:studio", "--quiet"], required: false, hint: "https://local.drizzle.studio" });
+  }
+
+  const children = [];
+  let shuttingDown = false;
+  let settled = false;
+
+  const killAll = () => {
+    for (const child of children) {
+      if (child.killed) continue;
+      try {
+        child.kill("SIGTERM");
+      } catch {}
+    }
+  };
+
+  const shutdown = () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    killAll();
+  };
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
+  await new Promise((resolve, reject) => {
+    for (const command of commands) {
+      const extraEnv =
+        command.label === "api"
+          ? { NEXGEN_DEV_VIEWS: views.join(","), NEXGEN_FRONTEND_URL: "http://localhost:5173" }
+          : {};
+      const child = spawn(process.execPath, [process.argv[1], ...command.args], {
+        stdio: command.label === "api" || command.label === "queue-worker" ? "inherit" : ["ignore", "pipe", "inherit"],
+        env: { ...process.env, ...extraEnv }
+      });
+      children.push(child);
+
+      child.on("exit", (code, signal) => {
+        if (settled) return;
+        if (!shuttingDown && (code !== null || signal !== null)) {
+          if (command.required) {
+            settled = true;
+            shutdown();
+            reject(new Error(`${command.label} exited (${signal || code})`));
+            return;
+          }
+          if (code !== 0 || signal) {
+            console.warn(`[dev] Optional process '${command.label}' exited (${signal || code}); continuing`);
+          }
+        }
+
+        const allExited = children.every((item) => item.exitCode !== null || item.signalCode !== null);
+        if (allExited) {
+          settled = true;
+          resolve();
+        }
+      });
+
+      child.on("error", (error) => {
+        if (settled) return;
+        settled = true;
+        shutdown();
+        reject(error);
+      });
+    }
+
+
+  }).finally(() => {
+    process.off("SIGINT", shutdown);
+    process.off("SIGTERM", shutdown);
+    killAll();
+  });
+}
+
+/** Run a runtime command: dev, serve, queue:work, queue:clear, schedule:work. */
+export async function runRuntime(commandName, rawArgs = []) {
+  const prod = rawArgs.includes("--prod");
+  const forceSrc = rawArgs.includes("--src");
+  const watch = rawArgs.includes("--watch");
+  const runtimeArg = rawArgs.find((arg) => arg.startsWith("--runtime="));
+  const runtime = runtimeArg ? runtimeArg.split("=")[1].trim().toLowerCase() : "node";
+
+  if (!["node", "bun"].includes(runtime)) {
+    throw new Error(`Invalid runtime '${runtime}'. Supported values: node, bun`);
+  }
+
+  const runtimeArgs = rawArgs.filter(
+    (arg, i) => i > 0 && !arg.startsWith("--runtime=") && arg !== "--prod" && arg !== "--src"
+  );
+  const hasDistServer = fsSync.existsSync(path.resolve(process.cwd(), "dist/src/framework/server.js"));
+  const hasDistWorker = fsSync.existsSync(path.resolve(process.cwd(), "dist/src/framework/queue/worker.js"));
+  const hasDistScheduler = fsSync.existsSync(
+    path.resolve(process.cwd(), "dist/src/framework/scheduler/run.js")
+  );
+
+  if (commandName === "dev") {
+    await runDevStack(rawArgs.slice(1));
+    return;
+  }
+
+  if (commandName === "serve") {
+    if (!forceSrc && (prod || hasDistServer)) {
+      const entry = path.resolve(process.cwd(), "dist/src/framework/server.js");
+      const command = runtime === "bun" ? "bun" : process.execPath;
+      await runCommand(command, [entry, ...runtimeArgs]);
+      return;
+    }
+
+    const useWatch = watch || (!prod && forceSrc);
+    const tsxWatchIgnore = [
+      "--include",
+      "src/**/*.ts",
+      "--include",
+      "src/framework/maker-cli/src/**/*.mjs",
+      "--exclude",
+      "src/storage/**",
+      "--exclude",
+      "src/storage/logs/**",
+      "--exclude",
+      "src/storage/tmp/**",
+      "--exclude",
+      "src/database/migrations/**",
+      "--exclude",
+      "src/database/schema.ts",
+      "--exclude",
+      "public/**",
+      "--exclude",
+      "dist/**",
+      "--exclude",
+      ".git/**",
+      "--exclude",
+      "node_modules/**",
+      "--exclude",
+      "**/.DS_Store",
+      "--exclude",
+      "**/Thumbs.db",
+      "--exclude",
+      "**/*.log"
+    ];
+    const tsxArgs = useWatch
+      ? ["watch", ...tsxWatchIgnore, "src/framework/server.ts", ...runtimeArgs]
+      : ["src/framework/server.ts", ...runtimeArgs];
+    await runCommand(localBin("tsx"), tsxArgs);
+    return;
+  }
+
+  if (commandName === "queue:work") {
+    if (!forceSrc && (prod || hasDistWorker)) {
+      const entry = path.resolve(process.cwd(), "dist/src/framework/queue/worker.js");
+      const command = runtime === "bun" ? "bun" : process.execPath;
+      await runCommand(command, [entry, ...runtimeArgs]);
+      return;
+    }
+
+    await runNodeScript(packageScript("tsx", "dist/cli.mjs"), ["src/framework/queue/worker.ts", ...rawArgs.slice(1)]);
+    return;
+  }
+
+  if (commandName === "queue:clear") {
+    await runNodeScript(packageScript("tsx", "dist/cli.mjs"), ["src/framework/queue/clear.ts"]);
+    return;
+  }
+
+  if (commandName === "schedule:work") {
+    if (!forceSrc && (prod || hasDistScheduler)) {
+      const entry = path.resolve(process.cwd(), "dist/src/framework/scheduler/run.js");
+      const command = runtime === "bun" ? "bun" : process.execPath;
+      await runCommand(command, [entry, ...runtimeArgs]);
+      return;
+    }
+
+    await runNodeScript(packageScript("tsx", "dist/cli.mjs"), [
+      "src/framework/scheduler/run.ts",
+      ...rawArgs.slice(1)
+    ]);
+  }
+}
+
+/** Launch a UI tool: maildev or redis-commander. */
+export async function runUi(commandName) {
+  if (commandName === "maildev:view") {
+    await runCommand(localBin("maildev"), [
+      "--smtp",
+      process.env.MAIL_PORT || process.env.MAILDEV_SMTP_PORT || "1025",
+      "--web",
+      process.env.MAILDEV_WEB_PORT || "1080"
+    ]);
+    return;
+  }
+
+  if (commandName === "redis:view") {
+    await runCommand(localBin("redis-commander"), redisConnectionArgs());
+  }
+}
+
+/** Start Vite dev server for a specific config file. */
+export async function runVite(configPath) {
+  await runCommand(localBin("vite"), ["--config", configPath]);
+}
+
+/** Clear Vite cache directories. */
+export async function clearViteCache() {
+  const dirs = [
+    path.resolve(process.cwd(), "node_modules/.vite"),
+    path.resolve(process.cwd(), "src/resources/node_modules/.vite")
+  ];
+
+  for (const dir of dirs) {
+    await fs.rm(dir, { recursive: true, force: true }).catch(() => {});
+  }
+
+  const strayCaches = await glob("**/.vite", {
+    cwd: process.cwd(),
+    nodir: false,
+    ignore: ["**/node_modules/**/.vite/**", "**/.git/**"],
+    windowsPathsNoEscape: true
+  });
+
+  for (const rel of strayCaches) {
+    const fullPath = path.resolve(process.cwd(), rel);
+    await fs.rm(fullPath, { recursive: true, force: true }).catch(() => {});
+  }
+
+  console.log("Vite cache cleared.");
+}

package/template/src/framework/maker-cli/src/levels/level-2/runtime/index.mjs

@@ -0,0 +1,71 @@
+import { runRuntime, runUi, runVite, clearViteCache } from "./core.mjs";
+
+/** Register runtime commands (dev, serve, queue, schedule, UI tools) on the CLI program. */
+export function registerRuntimeCommands(program, rawArgs) {
+  program
+    .command("dev")
+    .description("Start API + Vue 3 frontend plus optional workers/tools")
+    .option("--view <tools>", "Comma-separated UI tools to launch (redis,maildev,studio,bullmq)")
+    .option("--with <tools>", "Alias for --view")
+    .option("--with-redis-view", "Launch Redis Commander")
+    .option("--with-maildev", "Launch MailDev")
+    .option("--with-db-studio", "Launch Drizzle Studio")
+    .allowUnknownOption(true)
+    .action(async () => runRuntime("dev", rawArgs));
+  program
+    .command("serve")
+    .description("Start HTTP server (dist first if built, else src)")
+    .option("--prod", "Run production build")
+    .option("--runtime <name>", "Runtime: node or bun", "node")
+    .option("--watch", "Watch for file changes (src mode)")
+    .option("--src", "Force source mode even if dist exists")
+    .allowUnknownOption(true)
+    .action(async () => runRuntime("serve", rawArgs));
+  program
+    .command("queue:work")
+    .description("Start queue worker (dist first if built, else src)")
+    .option("--queue <name>", "Queue name", "default")
+    .option("--prod", "Run production build")
+    .option("--runtime <name>", "Runtime: node or bun", "node")
+    .option("--src", "Force source mode even if dist exists")
+    .allowUnknownOption(true)
+    .action(async () => runRuntime("queue:work", rawArgs));
+  program
+    .command("queue:clear")
+    .description("Clear all queue keys")
+    .allowUnknownOption(true)
+    .action(async () => runRuntime("queue:clear", rawArgs));
+  program
+    .command("schedule:work")
+    .description("Start scheduler worker (dist first if built, else src)")
+    .option("--prod", "Run production build")
+    .option("--runtime <name>", "Runtime: node or bun", "node")
+    .option("--src", "Force source mode even if dist exists")
+    .allowUnknownOption(true)
+    .action(async () => runRuntime("schedule:work", rawArgs));
+  program
+    .command("maildev:view")
+    .description("Start MailDev SMTP and web UI")
+    .allowUnknownOption(true)
+    .action(async () => runUi("maildev:view"));
+  program
+    .command("redis:view")
+    .description("Start Redis Commander UI")
+    .allowUnknownOption(true)
+    .action(async () => runUi("redis:view"));
+  program
+    .command("frontend:dev")
+    .description("Start Vue 3 frontend from src/resources")
+    .allowUnknownOption(true)
+    .action(async () => runVite("src/resources/vite.config.ts"));
+  program
+    .command("admin:dev")
+    .description("Start admin UI dev server")
+    .allowUnknownOption(true)
+    .action(async () => runVite("src/resources/vite.config.ts"));
+  program
+    .command("vite:cache:clear")
+    .description("Clear Vite cache folders (cross-platform)")
+    .allowUnknownOption(true)
+    .action(async () => clearViteCache());
+}

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

@@ -0,0 +1,55 @@
+import type { Handler } from "hono";
+
+/**
+ * Why: Returns collection response shape for list pages.
+ * When: Used by GET list endpoint.
+ * Where: GET /{{controller}} route.
+ */
+export const index: Handler = async (c: any) => {
+  return c.json({ message: "{{controller}} list fetched successfully", data: [] });
+};
+
+/**
+ * Why: Returns one resource by validated route id.
+ * When: Used by detail screens or fetch-by-id calls.
+ * Where: GET /{{controller}}/{id} route.
+ */
+export const show: Handler = async (c: any) => {
+  const params = c.req.valid("param");
+
+  return c.json({ message: "{{controller}} fetched successfully", data: { id: params.id, name: "" } });
+};
+
+/**
+ * Why: Creates a new resource from validated request body.
+ * When: Used by create form submissions.
+ * Where: POST /{{controller}} route.
+ */
+export const store: Handler = async (c: any) => {
+  c.req.valid("json");
+
+  return c.json({ message: "{{controller}} created successfully" }, 201);
+};
+
+/**
+ * Why: Updates an existing resource using id + body validation.
+ * When: Used by edit/update form submissions.
+ * Where: PUT/PATCH /{{controller}}/{id} route.
+ */
+export const update: Handler = async (c: any) => {
+  c.req.valid("param");
+  c.req.valid("json");
+
+  return c.json({ message: "{{controller}} updated successfully" });
+};
+
+/**
+ * Why: Deletes one resource by validated route id.
+ * When: Used by delete actions.
+ * Where: DELETE /{{controller}}/{id} route.
+ */
+export const destroy: Handler = async (c: any) => {
+  c.req.valid("param");
+
+  return c.json({ message: "{{controller}} deleted successfully" });
+};

package/template/src/framework/maker-cli/stubs/controller/openapi.with-model.ts.stub

@@ -0,0 +1,56 @@
+import type { Handler } from "hono";
+import { {{tableVariable}} } from "@/modules/{{module}}/database/models/{{controller}}.js";
+
+/**
+ * Why: Returns collection response shape for list pages.
+ * When: Used by GET list endpoint.
+ * Where: GET /{{controller}} route.
+ */
+export const index: Handler = async (c: any) => {
+  return c.json({ message: "{{controller}} list fetched successfully", data: [] });
+};
+
+/**
+ * Why: Returns one resource by validated route id.
+ * When: Used by detail screens or fetch-by-id calls.
+ * Where: GET /{{controller}}/{id} route.
+ */
+export const show: Handler = async (c: any) => {
+  const params = c.req.valid("param");
+
+  return c.json({ message: "{{controller}} fetched successfully", data: { id: params.id, name: "" } });
+};
+
+/**
+ * Why: Creates a new resource from validated request body.
+ * When: Used by create form submissions.
+ * Where: POST /{{controller}} route.
+ */
+export const store: Handler = async (c: any) => {
+  c.req.valid("json");
+
+  return c.json({ message: "{{controller}} created successfully" }, 201);
+};
+
+/**
+ * Why: Updates an existing resource using id + body validation.
+ * When: Used by edit/update form submissions.
+ * Where: PUT/PATCH /{{controller}}/{id} route.
+ */
+export const update: Handler = async (c: any) => {
+  c.req.valid("param");
+  c.req.valid("json");
+
+  return c.json({ message: "{{controller}} updated successfully" });
+};
+
+/**
+ * Why: Deletes one resource by validated route id.
+ * When: Used by delete actions.
+ * Where: DELETE /{{controller}}/{id} route.
+ */
+export const destroy: Handler = async (c: any) => {
+  c.req.valid("param");
+
+  return c.json({ message: "{{controller}} deleted successfully" });
+};

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

@@ -0,0 +1,57 @@
+import type { Handler } from "hono";
+import { validate } from "@/framework/facade.js";
+import { Create{{ClassName}}Schema, Update{{ClassName}}Schema, {{ClassName}}IdParamsSchema } from "@/modules/{{module}}/controllers/{{controller}}.schema.js";
+
+/**
+ * Why: Returns collection response shape for list pages.
+ * When: Used by GET list endpoint.
+ * Where: GET /{{controller}} route.
+ */
+export const index: Handler = async (c: any) => {
+  return c.json({ message: "{{controller}} list fetched successfully", data: [] });
+};
+
+/**
+ * Why: Returns one resource by validated route id.
+ * When: Used by detail screens or fetch-by-id calls.
+ * Where: GET /{{controller}}/{id} route.
+ */
+export const show: Handler = async (c: any) => {
+  const params = await validate({{ClassName}}IdParamsSchema, c.req.param());
+
+  return c.json({ message: "{{controller}} fetched successfully", data: { id: params.id, name: "" } });
+};
+
+/**
+ * Why: Creates a new resource from validated request body.
+ * When: Used by create form submissions.
+ * Where: POST /{{controller}} route.
+ */
+export const store: Handler = async (c: any) => {
+  await validate(Create{{ClassName}}Schema, await c.req.json());
+
+  return c.json({ message: "{{controller}} created successfully" }, 201);
+};
+
+/**
+ * Why: Updates an existing resource using id + body validation.
+ * When: Used by edit/update form submissions.
+ * Where: PUT/PATCH /{{controller}}/{id} route.
+ */
+export const update: Handler = async (c: any) => {
+  await validate({{ClassName}}IdParamsSchema, c.req.param());
+  await validate(Update{{ClassName}}Schema, await c.req.json());
+
+  return c.json({ message: "{{controller}} updated successfully" });
+};
+
+/**
+ * Why: Deletes one resource by validated route id.
+ * When: Used by delete actions.
+ * Where: DELETE /{{controller}}/{id} route.
+ */
+export const destroy: Handler = async (c: any) => {
+  await validate({{ClassName}}IdParamsSchema, c.req.param());
+
+  return c.json({ message: "{{controller}} deleted successfully" });
+};