create-nexwire 4.0.0

package/express/src/framework/maker-cli/runtime/index.mjs

@@ -0,0 +1,104 @@
+import { clearViteCache, runRuntime, runTest, runTestCoverage, runTestUI, runTestWatch, runUi, runVite } 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 UI plus optional workers/tools")
+    .option("--view <tools>", "Comma-separated UI tools to launch (redis,maildev,studio)")
+    .option("--viewer <tools>", "Alias for --view (npm expands --view to --viewer)")
+    .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("ui:dev")
+    .description("Start Vue 3 UI 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());
+  program
+    .command("test")
+    .description("Run Vitest backend tests")
+    .allowUnknownOption(true)
+    .action(async () => {
+      const args = process.argv.slice(3);
+      await runTest(args);
+    });
+  program
+    .command("test:watch")
+    .description("Run Vitest backend tests in watch mode")
+    .allowUnknownOption(true)
+    .action(async () => {
+      const args = process.argv.slice(3);
+      await runTestWatch(args);
+    });
+  program
+    .command("test:coverage")
+    .description("Run Vitest backend tests with code coverage")
+    .allowUnknownOption(true)
+    .action(async () => {
+      const args = process.argv.slice(3);
+      await runTestCoverage(args);
+    });
+  program
+    .command("test:ui")
+    .description("Run Vitest backend tests in UI mode")
+    .allowUnknownOption(true)
+    .action(async () => {
+      const args = process.argv.slice(3);
+      await runTestUI(args);
+    });
+}

package/express/src/framework/maker-cli/runtime/redis-commander-patch.cjs

@@ -0,0 +1,20 @@
+// Why: Redis Commander 0.4.5 bundles legacy `connect`/`serve-static`/`send`
+//      whose `SendStream#isFresh` reads `http.ServerResponse#_headers`, which
+//      Node removed in v15. Without this shim it crashes with:
+//        TypeError: Cannot read properties of undefined (reading 'last-modified')
+// When: Loaded via `node --require` before Redis Commander starts.
+// Where: maker-cli redis:view launcher.
+// How: Re-exposes `_headers` on the ServerResponse prototype, backed by the
+//      modern `getHeaders()` API. Safe on older Node too (getHeaders is the
+//      same data `_headers` used to return).
+const http = require("node:http");
+
+if (!("_headers" in http.ServerResponse.prototype)) {
+  Object.defineProperty(http.ServerResponse.prototype, "_headers", {
+    configurable: true,
+    enumerable: false,
+    get() {
+      return this.getHeaders();
+    }
+  });
+}

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

@@ -0,0 +1,47 @@
+import type { Request, Response } from "express";
+import { HttpStatusCodes } from "@/framework/facade.js";
+
+/**
+ * Why: Returns collection response shape for list pages.
+ * When: Used by GET list endpoint.
+ * Where: GET /{{controller}} route.
+ */
+export const index = async (_req: Request, res: Response) => {
+  res.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 = async (req: Request, res: Response) => {
+  res.json({ message: "{{controller}} fetched successfully", data: { id: req.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 = async (_req: Request, res: Response) => {
+  res.status(HttpStatusCodes.CREATED).json({ message: "{{controller}} created successfully" });
+};
+
+/**
+ * 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 = async (_req: Request, res: Response) => {
+  res.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 = async (_req: Request, res: Response) => {
+  res.json({ message: "{{controller}} deleted successfully" });
+};

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

@@ -0,0 +1,48 @@
+import type { Request, Response } from "express";
+import { HttpStatusCodes } from "@/framework/facade.js";
+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 = async (_req: Request, res: Response) => {
+  res.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 = async (req: Request, res: Response) => {
+  res.json({ message: "{{controller}} fetched successfully", data: { id: req.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 = async (_req: Request, res: Response) => {
+  res.status(HttpStatusCodes.CREATED).json({ message: "{{controller}} created successfully" });
+};
+
+/**
+ * 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 = async (_req: Request, res: Response) => {
+  res.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 = async (_req: Request, res: Response) => {
+  res.json({ message: "{{controller}} deleted successfully" });
+};

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

@@ -0,0 +1,54 @@
+import type { Request, Response } from "express";
+import { HttpStatusCodes } from "@/framework/facade.js";
+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 = async (_req: Request, res: Response) => {
+  res.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 = async (req: Request, res: Response) => {
+  const params = await validate({{ClassName}}IdParamsSchema, req.params);
+  res.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 = async (req: Request, res: Response) => {
+  await validate(Create{{ClassName}}Schema, req.body);
+  res.status(HttpStatusCodes.CREATED).json({ message: "{{controller}} created successfully" });
+};
+
+/**
+ * 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 = async (req: Request, res: Response) => {
+  await validate({{ClassName}}IdParamsSchema, req.params);
+  await validate(Update{{ClassName}}Schema, req.body);
+  res.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 = async (req: Request, res: Response) => {
+  await validate({{ClassName}}IdParamsSchema, req.params);
+  res.json({ message: "{{controller}} deleted successfully" });
+};

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

@@ -0,0 +1,14 @@
+import { z } from "@/framework/facade.js";
+
+export const Create{{ClassName}}Schema = z.object({
+  name: z.string().min(1)
+});
+
+export const Update{{ClassName}}Schema = z.object({
+  name: z.string().min(1)
+});
+
+export const {{ClassName}}IdParamsSchema = z.object({
+  id: z.coerce.number().int().positive()
+});
+

package/express/src/framework/maker-cli/stubs/controller/schema.ts.stub

@@ -0,0 +1,33 @@
+import { z } from "@/framework/facade.js";
+
+export const {{ClassName}}ItemSchema = z.object({
+  id: z.number(),
+  name: z.string()
+});
+
+export const Create{{ClassName}}Schema = z.object({
+  name: z.string().min(1)
+});
+
+export const Update{{ClassName}}Schema = z.object({
+  name: z.string().min(1)
+});
+
+export const {{ClassName}}IdParamsSchema = z.object({
+  id: z.coerce.number().int().positive()
+});
+
+export const {{ClassName}}ListResponseSchema = z.object({
+  message: z.string(),
+  data: z.array({{ClassName}}ItemSchema)
+});
+
+export const {{ClassName}}ResponseSchema = z.object({
+  message: z.string(),
+  data: {{ClassName}}ItemSchema
+});
+
+export const {{ClassName}}MessageSchema = z.object({
+  message: z.string()
+});
+

package/express/src/framework/maker-cli/stubs/deploy/Dockerfile.bun.stub

@@ -0,0 +1,52 @@
+ARG BUN_VERSION=1.4.0
+FROM oven/bun:${BUN_VERSION}-slim AS builder
+
+WORKDIR /app
+
+ENV APP_URL=http://localhost:3000
+ARG UI=true
+ENV UI=${UI}
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+  ca-certificates \
+  python3 \
+  make \
+  g++ \
+  && rm -rf /var/lib/apt/lists/*
+
+COPY package.json bun.lockb* bun.lock* package-lock.json* ./
+RUN bun install --frozen-lockfile
+
+COPY . .
+RUN cp deploy/.env .env || true
+RUN bun src/framework/maker-cli/index.mjs db:schema
+RUN bun run build
+
+FROM oven/bun:${BUN_VERSION}-slim AS runner
+
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV APP_URL=http://localhost:3000
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+  supervisor \
+  ca-certificates \
+  && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package.json ./package.json
+COPY --from=builder /app/drizzle.config.ts ./drizzle.config.ts
+COPY --from=builder /app/tsconfig.json ./tsconfig.json
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/public ./public
+COPY --from=builder /app/src ./src
+COPY --from=builder /app/deploy/scripts ./deploy/scripts
+COPY --from=builder /app/deploy/.env ./.env
+
+COPY deploy/supervisor/supervisord.conf /etc/supervisor/conf.d/supervisord.conf
+
+EXPOSE 3000
+
+CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]
+

package/express/src/framework/maker-cli/stubs/deploy/Dockerfile.pnpm.stub

@@ -0,0 +1,55 @@
+ARG NODE_VERSION=24
+FROM node:${NODE_VERSION}-bookworm-slim AS builder
+
+ARG PNPM_VERSION=10.33.2
+ARG UI=true
+ENV UI=${UI}
+
+WORKDIR /app
+
+ENV APP_URL=http://localhost:3000
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates \
+    python3 \
+    make \
+    g++ \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN corepack enable && corepack prepare pnpm@${PNPM_VERSION} --activate
+
+COPY package.json pnpm-lock.yaml* ./
+RUN if [ -f pnpm-lock.yaml ]; then pnpm install --frozen-lockfile; else pnpm install --no-frozen-lockfile; fi
+
+COPY . .
+RUN node src/framework/maker-cli/index.mjs db:schema
+RUN pnpm run build
+
+FROM node:${NODE_VERSION}-bookworm-slim AS runner
+
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV APP_URL=http://localhost:3000
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    supervisor \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package.json ./package.json
+COPY --from=builder /app/drizzle.config.ts ./drizzle.config.ts
+COPY --from=builder /app/tsconfig.json ./tsconfig.json
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/public ./public
+COPY --from=builder /app/src ./src
+COPY --from=builder /app/deploy/scripts ./deploy/scripts
+COPY --from=builder /app/deploy/.env ./.env
+
+COPY deploy/supervisor/supervisord.conf /etc/supervisor/conf.d/supervisord.conf
+
+EXPOSE 3000
+
+CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]
+

package/express/src/framework/maker-cli/stubs/deploy/Dockerfile.stub

@@ -0,0 +1,51 @@
+ARG NODE_VERSION=24
+FROM node:${NODE_VERSION}-bookworm-slim AS builder
+
+WORKDIR /app
+
+ENV APP_URL=http://localhost:3000
+ARG UI=true
+ENV UI=${UI}
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates \
+    python3 \
+    make \
+    g++ \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY package.json package-lock.json* ./
+RUN if [ -f package-lock.json ]; then npm ci --legacy-peer-deps || npm install --legacy-peer-deps; else npm install --legacy-peer-deps; fi
+
+COPY . .
+RUN node src/framework/maker-cli/index.mjs db:schema
+RUN npm run build
+
+FROM node:${NODE_VERSION}-bookworm-slim AS runner
+
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV APP_URL=http://localhost:3000
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    supervisor \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package.json ./package.json
+COPY --from=builder /app/drizzle.config.ts ./drizzle.config.ts
+COPY --from=builder /app/tsconfig.json ./tsconfig.json
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/public ./public
+COPY --from=builder /app/src ./src
+COPY --from=builder /app/deploy/scripts ./deploy/scripts
+COPY --from=builder /app/deploy/.env ./.env
+
+COPY deploy/supervisor/supervisord.conf /etc/supervisor/conf.d/supervisord.conf
+
+EXPOSE 3000
+
+CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]
+

package/express/src/framework/maker-cli/stubs/deploy/Dockerfile.yarn.stub

@@ -0,0 +1,55 @@
+ARG NODE_VERSION=24
+FROM node:${NODE_VERSION}-bookworm-slim AS builder
+
+ARG YARN_VERSION=1.22.22
+ARG UI=true
+ENV UI=${UI}
+
+WORKDIR /app
+
+ENV APP_URL=http://localhost:3000
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates \
+    python3 \
+    make \
+    g++ \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN corepack enable && corepack prepare yarn@${YARN_VERSION} --activate
+
+COPY package.json yarn.lock* ./
+RUN yarn install --immutable
+
+COPY . .
+RUN node src/framework/maker-cli/index.mjs db:schema
+RUN yarn build
+
+FROM node:${NODE_VERSION}-bookworm-slim AS runner
+
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV APP_URL=http://localhost:3000
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    supervisor \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package.json ./package.json
+COPY --from=builder /app/drizzle.config.ts ./drizzle.config.ts
+COPY --from=builder /app/tsconfig.json ./tsconfig.json
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/public ./public
+COPY --from=builder /app/src ./src
+COPY --from=builder /app/deploy/scripts ./deploy/scripts
+COPY --from=builder /app/deploy/.env ./.env
+
+COPY deploy/supervisor/supervisord.conf /etc/supervisor/conf.d/supervisord.conf
+
+EXPOSE 3000
+
+CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]
+

package/express/src/framework/maker-cli/stubs/deploy/README.stub

@@ -0,0 +1,59 @@
+# Deploy
+
+Generated from current project .env.
+
+- Database mode: {{DATABASE_MODE}}
+- Redis enabled: {{REDIS_STATUS}}
+- Runtime: {{RUNTIME_NAME}}
+
+## Prerequisites
+
+- External docker networks exist:
+
+```bash
+docker network create nginx-proxy || true
+docker network create infra || true
+```
+
+- Proxy stack from `server-setup` is running (jwilder + letsencrypt companion).
+
+## Start app stack
+
+```bash
+docker compose --env-file deploy/server/.env --env-file deploy/.env -f deploy/docker-compose.yml up -d --build
+```
+
+Equivalent maker command:
+
+```bash
+bun maker deploy:workflow --app-only
+```
+
+## DB Import
+
+Import SQL dump into local Docker container (auto-detects MySQL or PostgreSQL):
+
+```bash
+bun maker deploy:db:import --file=deploy/nexwire.sql --database=nexwire
+```
+
+PostgreSQL restores into a fresh database by default (drops and recreates the
+target database first). Pass `--no-drop` to keep the existing database.
+
+Import SQL dump into remote Docker container (auto-detects MySQL or PostgreSQL):
+
+```bash
+bun maker deploy:db:import:remote --config=deploy/workflow.remote.json --file=deploy/nexwire.sql --database=nexwire
+```
+
+## Runtime
+
+Supervisor starts:
+
+- API: `maker serve --prod --runtime={{RUNTIME_NAME}}`
+{{QUEUE_LINE}}- Scheduler: `maker schedule:work --prod --runtime={{RUNTIME_NAME}}`
+
+{{REDIS_NOTE}}
+
+This deploy style follows `server-setup` and `statistic_postgre` patterns (external `nginx-proxy` + `infra` networks).
+

package/express/src/framework/maker-cli/stubs/deploy/compose/mysql.server.stub

@@ -0,0 +1,45 @@
+name: ${COMPOSE_PROJECT_NAME:-nexwire}
+
+services:
+  app:
+    build:
+      context: ..
+      dockerfile: deploy/Dockerfile
+      args:
+        UI: ${UI}
+    container_name: ${APP_NAME:-nexwire}-app
+    restart: unless-stopped
+    working_dir: /app
+    ports:
+      - "${APP_PORT:-3000}:3000"
+    expose:
+      - "3000"
+    env_file:
+      - .env
+    environment:
+      APP_ENV: production
+      APP_PORT: 3000
+      APP_URL: ${APP_URL:-http://localhost:3000}
+      DATABASE_URL: ${DATABASE_URL}
+{{REDIS_ENV_LINE}}      APP_HOST: ${APP_HOST:-localhost}
+      VIRTUAL_HOST: ${VIRTUAL_HOST:-}
+      VIRTUAL_PORT: ${VIRTUAL_PORT:-3000}
+      LETSENCRYPT_HOST: ${LETSENCRYPT_HOST:-}
+      LETSENCRYPT_EMAIL: ${LETSENCRYPT_EMAIL:-}
+    volumes:
+      - app-storage:/app/src/storage
+    networks:
+      - infra
+      - nginx-proxy
+
+volumes:
+  app-storage:
+
+networks:
+  infra:
+    external: true
+    name: infra
+  nginx-proxy:
+    external: true
+    name: nginx-proxy
+