@appinit/cli 1.1.0 → 1.3.0

package/dist/templates/backend-express/.appinit-preview/project/src/middleware/error-handler.ts

@@ -0,0 +1,73 @@
+import type { NextFunction, Request, Response } from "express";
+import { ZodError } from "zod";
+
+import { env } from "../config/env.js";
+import { AppError } from "../errors/app-error.js";
+import { logger } from "../utils/logger.js";
+
+export function errorHandler(
+  err: unknown,
+  _req: Request,
+  res: Response,
+  _next: NextFunction,
+) {
+  /**
+   * Zod validation errors (400)
+   */
+  if (err instanceof ZodError) {
+    const fieldErrors: Record<string, string[]> = {};
+
+    for (const issue of err.issues) {
+      const field = issue.path.join(".") || "root";
+      fieldErrors[field] ??= [];
+      fieldErrors[field].push(issue.message);
+    }
+
+    logger.warn({ fieldErrors }, "Request validation failed");
+
+    return res.status(400).json({
+      error: {
+        code: "VALIDATION_ERROR",
+        message: "Invalid request",
+        fields: fieldErrors,
+      },
+    });
+  }
+  // Normalize error
+  const error =
+    err instanceof AppError
+      ? err
+      : new AppError("Internal server error", {
+          statusCode: 500,
+          code: "INTERNAL_SERVER_ERROR",
+          isOperational: false,
+        });
+
+  // Log full error (always)
+  logger.error(
+    {
+      err,
+      statusCode: error.statusCode,
+      code: error.code,
+    },
+    "Unhandled application error",
+  );
+
+  // Response (safe for clients)
+  const response: Record<string, unknown> = {
+    error: {
+      code: error.code,
+      message: error.message,
+    },
+  };
+
+  // Dev-only details
+  if (env.nodeEnv !== "production") {
+    response.error = {
+      ...(response.error ?? {}),
+      details: err instanceof Error ? err.stack : err,
+    };
+  }
+
+  res.status(error.statusCode).json(response);
+}

package/dist/templates/backend-express/.appinit-preview/project/src/middleware/http-logger.ts

@@ -0,0 +1,5 @@
+import pinoHttp from "pino-http";
+
+import { logger } from "../utils/logger.js";
+
+export const httpLogger = pinoHttp({ logger });

package/dist/templates/backend-express/.appinit-preview/project/src/middleware/validate.ts

@@ -0,0 +1,17 @@
+import type { NextFunction, Request, Response } from "express";
+import type { ZodSchema } from "zod";
+
+export const validate =
+  <T>(schema: ZodSchema<T>) =>
+  (req: Request, _res: Response, next: NextFunction) => {
+    try {
+      schema.parse({
+        body: req.body,
+        query: req.query,
+        params: req.params,
+      });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  };

package/dist/templates/backend-express/.appinit-preview/project/src/routes/health.ts

@@ -0,0 +1,13 @@
+import { Router } from "express";
+
+export const router = Router();
+
+router.get("/", (_req, res) => {
+  res.status(200).json({ status: "ok" });
+});
+
+router.get("/ready", (_req, res) => {
+  res.status(200).json({ ready: true });
+});
+
+export { router as healthRouter };

package/dist/templates/backend-express/.appinit-preview/project/src/routes/users.ts

@@ -0,0 +1,12 @@
+import { Router } from "express";
+
+import { validate } from "../middleware/validate";
+import { createUserSchema } from "../schema/create-user.schema";
+
+const router = Router();
+
+router.post("/", validate(createUserSchema), (_req, res) => {
+  res.status(201).json({ ok: true });
+});
+
+export { router as userRouter };

package/dist/templates/backend-express/.appinit-preview/project/src/schema/create-user.schema.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+
+export const createUserSchema = z.object({
+  body: z.object({
+    email: z.email(),
+    password: z.string().min(8),
+  }),
+});

package/dist/templates/backend-express/.appinit-preview/project/src/server.ts

@@ -0,0 +1,54 @@
+import { app } from "./app";
+import { logger } from "./utils/logger";
+
+// Assuming the Pino logger from before
+
+const PORT = process.env.PORT || 3001;
+
+const server = app.listen(PORT, () => {
+  logger.info(`🚀 Server version 1.0.0 started`);
+  logger.info(`📡 Listening on http://localhost:${PORT}`);
+  logger.info(`🌍 Environment: ${process.env.NODE_ENV || "development"}`);
+});
+
+/**
+ * GRACEFUL SHUTDOWN LOGIC
+ * Ensures the server closes existing connections before exiting.
+ */
+const shutdown = (signal: string) => {
+  logger.info(`${signal} received. Starting graceful shutdown...`);
+
+  server.close(() => {
+    logger.info("⛔ HTTP server closed.");
+
+    // Close database connections here (e.g., prisma.$disconnect() or mongoose.connection.close())
+
+    process.exit(0);
+  });
+
+  // Force close after 10 seconds if graceful shutdown fails
+  setTimeout(() => {
+    logger.error(
+      "Could not close connections in time, forcefully shutting down",
+    );
+    process.exit(1);
+  }, 10000);
+};
+
+// Listen for termination signals
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+process.on("SIGINT", () => shutdown("SIGINT"));
+
+/**
+ * UNHANDLED REJECTION/EXCEPTION CATCHING
+ * Prevents the process from crashing silently.
+ */
+process.on("unhandledRejection", (reason, promise) => {
+  logger.fatal({ promise, reason }, "Unhandled Rejection at Promise");
+  throw reason; // Let uncaughtException handle it
+});
+
+process.on("uncaughtException", (error) => {
+  logger.fatal(error, "Uncaught Exception thrown");
+  process.exit(1);
+});

package/dist/templates/backend-express/.appinit-preview/project/src/utils/logger.ts

@@ -0,0 +1,21 @@
+import pino from "pino";
+
+import { env } from "../config/env.js";
+
+const isProduction = process.env.NODE_ENV === "production";
+
+export const logger = pino({
+  level: env.logLevel,
+  // Redact sensitive data from logs for security
+  redact: ["req.headers.authorization", "password", "confirmPassword"],
+  transport: isProduction
+    ? undefined // In production, output raw JSON for Datadog/ELK
+    : {
+        target: "pino-pretty",
+        options: {
+          colorize: true,
+          translateTime: "SYS:standard",
+          ignore: "pid,hostname",
+        },
+      },
+});

package/dist/templates/backend-express/.appinit-preview/project/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    /* Language & runtime */
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+
+    /* Project structure */
+    "rootDir": "src",
+    "outDir": "dist",
+
+    /* Interop & correctness */
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+
+    /* Safety */
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "noEmitOnError": true,
+
+    /* DX & production debugging */
+    "sourceMap": true,
+
+    /* Node environment */
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "__tests__"]
+}

package/dist/templates/backend-express/.appinit-preview/project/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    globals: true,
+    clearMocks: true,
+    restoreMocks: true,
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "html"],
+      exclude: ["dist", "node_modules"],
+    },
+  },
+});

package/dist/templates/backend-express/README.md

@@ -0,0 +1,107 @@
+# Backend Express — Reference Template (ATS 1.0)
+
+**Template ID:** backend.backend-express.basic  
+**Status:** Reference Template  
+**ATS Version:** 1.0  
+**Purpose:** Canonical backend baseline for AppInit OS
+
+---
+
+## What This Template Is
+
+This template is the **reference backend implementation** for ATS 1.0.
+
+It demonstrates:
+
+- correct ATS 1.0 structure
+- deterministic rendering
+- proper variable defaults
+- correct Doctor interaction
+- clean author vs user separation
+
+All future backend templates **must align with this structure unless explicitly justified**.
+
+---
+
+## Scope (LOCKED)
+
+Included:
+
+- Node.js runtime
+- Express
+- TypeScript
+- Minimal production-ready structure
+- Deterministic configuration
+- Tests
+- Linting and formatting
+
+Explicitly NOT included:
+
+- Authentication
+- Databases / ORM
+- Docker orchestration
+- Deployment presets
+- Cloud configuration
+- Monorepo support
+
+If you need these features, use this template as a base and extend externally.
+
+---
+
+## ATS Guarantees
+
+This template guarantees:
+
+- `appinit template generate` runs with **no prompts**
+- defaults are sufficient and deterministic
+- output of `template generate` matches `appinit create`
+- no runtime execution during authoring
+- no SDK internals leakage
+
+If any of these guarantees break, the template is considered invalid.
+
+---
+
+## Doctor Interaction
+
+- Doctor runs in **strict** mode during `template generate`
+- Doctor runs in **advisory** mode during `template dev`
+- Doctor never mutates output
+
+Doctor warnings should be treated as **author guidance**, not failures.
+
+---
+
+## Why This Template Exists
+
+This template exists to:
+
+- calibrate ATS 1.0 behavior
+- serve as a structural reference
+- reduce ambiguity for template authors
+- provide a stable baseline for backend projects
+
+This is a **boring template by design**.
+
+---
+
+## ⚙️ Template Engine
+
+The rendering engine is defined in **`template.config.ts`**, not dynamically.
+
+### Engine: `liquid`
+
+When `engine: "liquid"` is used:
+
+- LiquidJS syntax is available
+- Supports interpolation, conditionals, loops, filters
+
+Examples:
+
+```liquid
+{{ projectName }}
+
+{% if useTypeScript %}
+  // TypeScript-only code
+{% endif %}
+```

package/dist/templates/backend-express/appinit.template.json

@@ -0,0 +1,25 @@
+{
+  "schemaVersion": 1,
+  "id": "backend.backend-express.basic",
+  "version": "0.1.0",
+  "kind": "project",
+  "atsVersion": "1.0",
+  "name": "Express Backend",
+  "description": "TypeScript backend starter using Express.",
+  "category": "backend",
+  "language": "typescript",
+  "packageName": "@appinit/template-backend-express",
+  "renderer": {
+    "engine": "liquid"
+  },
+  "paths": {
+    "template": "template",
+    "variables": "variables"
+  },
+  "tags": [
+    "backend",
+    "api",
+    "express",
+    "typescript"
+  ]
+}

package/dist/templates/backend-express/docs/README.md

@@ -0,0 +1,11 @@
+# backend-express Template
+
+This is a **backend AppInit template**.
+
+## What you should add
+- Files inside /template
+- Variables in /variables
+- Optional hooks in /hooks
+
+This scaffold does NOT include framework code.
+You are expected to add it.

package/dist/templates/backend-express/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "@appinit/template-backend-express",
+  "private": true,
+  "version": "0.1.0"
+}

package/dist/templates/backend-express/template/.env.example

@@ -0,0 +1,4 @@
+NODE_ENV=development
+PORT=3001
+LOG_LEVEL=debug
+CORS_ORIGIN=*

package/dist/templates/backend-express/template/.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

package/dist/templates/backend-express/template/.prettierignore

@@ -0,0 +1,3 @@
+# Ignore artifacts:
+build
+coverage

package/dist/templates/backend-express/template/.prettierrc

@@ -0,0 +1,28 @@
+{
+  "arrowParens": "always",
+  "bracketSameLine": false,
+  "objectWrap": "preserve",
+  "bracketSpacing": true,
+  "semi": true,
+  "experimentalOperatorPosition": "end",
+  "experimentalTernaries": false,
+  "singleQuote": false,
+  "jsxSingleQuote": false,
+  "quoteProps": "as-needed",
+  "trailingComma": "all",
+  "singleAttributePerLine": false,
+  "htmlWhitespaceSensitivity": "css",
+  "vueIndentScriptAndStyle": false,
+  "proseWrap": "preserve",
+  "endOfLine": "lf",
+  "insertPragma": false,
+  "printWidth": 80,
+  "requirePragma": false,
+  "tabWidth": 2,
+  "useTabs": false,
+  "embeddedLanguageFormatting": "auto",
+  "importOrder": ["^@core/(.*)$", "^@server/(.*)$", "^@ui/(.*)$", "^[./]"],
+  "importOrderSeparation": true,
+  "importOrderSortSpecifiers": true,
+  "plugins": ["@trivago/prettier-plugin-sort-imports"]
+}

package/dist/templates/backend-express/template/.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "eslint.format.enable": false,
+  "prettier.requireConfig": true
+}

package/dist/templates/backend-express/template/Dockerfile

@@ -0,0 +1,14 @@
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+EXPOSE 3001
+CMD ["node", "dist/server.js"]

package/dist/templates/backend-express/template/README.md__tmpl

@@ -0,0 +1,26 @@
+# ⚛️ backend-express
+
+This project was generated using **AppInit 1.0**.
+
+## 🚀 Quick Start
+
+```bash
+pnpm install
+pnpm dev
+```
+
+## 🛠️ Stack Configuration
+
+- **Framework**: React 18+ (Vite)
+- **Engine Used**: %%engine%%
+- **Generated At**: %%timestamp%%
+
+## 📂 Project Structure
+
+- `src/`: Your React components and logic.
+- `public/`: Static assets (images, icons).
+- `tailwind.config.js`: Styling configuration.
+
+---
+
+_Built with speed using the AppInit Scaffolding Engine._

package/dist/templates/backend-express/template/eslint.config.js

@@ -0,0 +1,76 @@
+import js from "@eslint/js";
+import tsPlugin from "@typescript-eslint/eslint-plugin";
+import tsParser from "@typescript-eslint/parser";
+import prettier from "eslint-config-prettier";
+
+export default [
+  // ─────────────────────────────────────────────
+  // Global ignores (ESLint v9 way)
+  // ─────────────────────────────────────────────
+  {
+    ignores: ["dist/**", "node_modules/**", "coverage/**"],
+  },
+
+  // ─────────────────────────────────────────────
+  // Base JS rules
+  // ─────────────────────────────────────────────
+  js.configs.recommended,
+
+  // ─────────────────────────────────────────────
+  // TypeScript (Node backend)
+  // ─────────────────────────────────────────────
+  {
+    files: ["src/**/*.ts"],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        project: "./tsconfig.json",
+        sourceType: "module",
+      },
+      globals: {
+        process: "readonly",
+        console: "readonly",
+        setTimeout: "readonly",
+        clearTimeout: "readonly",
+      },
+    },
+    plugins: {
+      "@typescript-eslint": tsPlugin,
+    },
+    rules: {
+      /* Disable base JS rules */
+      "no-undef": "off",
+      "no-unused-vars": "off",
+
+      /* TypeScript correctness */
+      "@typescript-eslint/no-unused-vars": [
+        "warn",
+        { argsIgnorePattern: "^_" },
+      ],
+      "@typescript-eslint/no-floating-promises": "error",
+      "@typescript-eslint/no-misused-promises": "error",
+
+      /* Production discipline */
+      "no-console": "error",
+      "no-debugger": "error",
+
+      /* Reality */
+      "@typescript-eslint/no-explicit-any": "off",
+    },
+  },
+
+  // ─────────────────────────────────────────────
+  // Allow console ONLY in env bootstrap
+  // ─────────────────────────────────────────────
+  {
+    files: ["src/config/env.ts"],
+    rules: {
+      "no-console": "off",
+    },
+  },
+
+  // ─────────────────────────────────────────────
+  // Disable formatting rules (Prettier owns formatting)
+  // ─────────────────────────────────────────────
+  prettier,
+];

package/dist/templates/backend-express/template/nodemon.json

@@ -0,0 +1,8 @@
+{
+  "watch": ["src"],
+  "ext": "ts",
+  "ignore": ["dist", "node_modules"],
+  "exec": "tsx src/server.ts",
+  "signal": "SIGTERM",
+  "delay": "100"
+}

package/dist/templates/backend-express/template/package.json__tmpl

@@ -0,0 +1,69 @@
+{
+  "name": "{{ projectName }}",
+  "description": "{{ description | default: 'Backend API built with AppInit' }}",
+  "author": "{{ author }}",
+  "license": "{{ licenseType }}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "nodemon",
+    "clean": "rimraf dist",
+    "build": "npm run clean && tsc",
+    "start": "node dist/server.js",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:watch": "vitest watch",
+    "test:coverage": "vitest run --coverage",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "**/*": "prettier --write --ignore-unknown"
+  },
+  "main": "index.js",
+  "keywords": [],
+  "dependencies": {
+    "compression": "^1.8.1",
+    "cors": "^2.8.5",
+    "dotenv": "^17.2.3",
+    "express": "^5.2.1",
+    "helmet": "^8.1.0",
+    "http-errors": "^2.0.1",
+    "pino": "^10.1.0",
+    "pino-http": "^11.0.0",
+    "uuid": "^13.0.0",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@trivago/prettier-plugin-sort-imports": "^6.0.0",
+    "@types/compression": "^1.8.1",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/morgan": "^1.9.10",
+    "@types/node": "^25.0.2",
+    "@types/supertest": "^6.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.50.0",
+    "@typescript-eslint/parser": "^8.50.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "morgan": "^1.10.1",
+    "nodemon": "^3.1.11",
+    "pino-pretty": "^13.1.3",
+    "prettier": "3.7.4",
+    "rimraf": "^6.1.2",
+    "supertest": "^7.1.4",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}