@erwininteractive/mvc 0.1.1

package/README.md

@@ -0,0 +1,174 @@
+# @erwininteractive/mvc
+
+A lightweight, full-featured MVC framework for Node.js 20+ built with TypeScript.
+
+## Features
+
+- **Express** - Fast, minimal web framework
+- **Prisma** - Modern database ORM with PostgreSQL
+- **EJS + Alpine.js** - Server-side templating with reactive client-side components
+- **Redis Sessions** - Scalable session management
+- **JWT Authentication** - Secure token-based auth with bcrypt password hashing
+- **CLI Tools** - Scaffold apps and generate models/controllers
+
+## Quick Start
+
+### Create a New Application
+
+```bash
+npx @erwininteractive/mvc init myapp
+cd myapp
+cp .env.example .env
+# Edit .env with your database configuration
+npx prisma migrate dev --name init
+npm run dev
+```
+
+### Generate a Model
+
+```bash
+npx erwinmvc generate model Post
+```
+
+This creates a Prisma model and runs migrations.
+
+### Generate a Controller
+
+```bash
+npx erwinmvc generate controller Post
+```
+
+This creates a CRUD controller with routes:
+- `GET /posts` - List all posts
+- `GET /posts/:id` - Show a single post
+- `POST /posts` - Create a post
+- `PUT /posts/:id` - Update a post
+- `DELETE /posts/:id` - Delete a post
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `erwinmvc init <dir>` | Scaffold a new MVC application |
+| `erwinmvc generate model <name>` | Generate a Prisma model |
+| `erwinmvc generate controller <name>` | Generate a CRUD controller |
+
+### Options
+
+**init:**
+- `--skip-install` - Skip running npm install
+- `--skip-prisma` - Skip Prisma client generation
+
+**generate model:**
+- `--skip-migrate` - Skip running Prisma migrate
+
+**generate controller:**
+- `--no-views` - Skip generating EJS views
+
+## Framework API
+
+### App Factory
+
+```typescript
+import { createMvcApp, startServer } from "@erwininteractive/mvc";
+
+const { app, redisClient } = await createMvcApp({
+  viewsPath: "src/views",
+  publicPath: "public",
+});
+
+startServer(app);
+```
+
+### Database
+
+```typescript
+import { getPrismaClient } from "@erwininteractive/mvc";
+
+const prisma = getPrismaClient();
+const users = await prisma.user.findMany();
+```
+
+### Authentication
+
+```typescript
+import {
+  hashPassword,
+  verifyPassword,
+  signToken,
+  verifyToken,
+  authenticate,
+} from "@erwininteractive/mvc";
+
+// Hash a password
+const hash = await hashPassword("secret123");
+
+// Verify a password
+const isValid = await verifyPassword("secret123", hash);
+
+// Sign a JWT
+const token = signToken({ userId: 1, email: "user@example.com" });
+
+// Protect routes with middleware
+app.get("/protected", authenticate, (req, res) => {
+  res.json({ user: req.user });
+});
+```
+
+### Routing
+
+```typescript
+import { registerControllers } from "@erwininteractive/mvc";
+
+// Auto-register all *Controller.ts files
+await registerControllers(app, path.resolve("src/controllers"));
+```
+
+## Environment Variables
+
+Create a `.env` file with:
+
+```env
+DATABASE_URL="postgresql://USER:PASSWORD@localhost:5432/yourdb?schema=public"
+REDIS_URL="redis://localhost:6379"
+JWT_SECRET="your-secret-key"
+SESSION_SECRET="your-session-secret"
+PORT=3000
+NODE_ENV=development
+```
+
+## Project Structure
+
+Generated applications follow this structure:
+
+```
+myapp/
+├── src/
+│   ├── controllers/     # Route controllers
+│   ├── middleware/      # Express middleware
+│   ├── views/           # EJS templates
+│   └── server.ts        # Entry point
+├── prisma/
+│   └── schema.prisma    # Database schema
+├── public/              # Static files
+├── .env.example
+├── package.json
+└── tsconfig.json
+```
+
+## Controller Convention
+
+Controllers export named functions that map to routes:
+
+```typescript
+// src/controllers/PostController.ts
+export async function index(req, res) { /* GET /posts */ }
+export async function show(req, res)  { /* GET /posts/:id */ }
+export async function store(req, res) { /* POST /posts */ }
+export async function update(req, res) { /* PUT /posts/:id */ }
+export async function destroy(req, res) { /* DELETE /posts/:id */ }
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const initApp_1 = require("./generators/initApp");
+const generateModel_1 = require("./generators/generateModel");
+const generateController_1 = require("./generators/generateController");
+const program = new commander_1.Command();
+program
+    .name("erwinmvc")
+    .description("CLI for @erwininteractive/mvc framework")
+    .version("0.1.1");
+// Init command - scaffold a new application
+program
+    .command("init <dir>")
+    .description("Scaffold a new MVC application")
+    .option("--skip-install", "Skip npm install")
+    .option("--with-database", "Include database/Prisma setup")
+    .action(async (dir, options) => {
+    try {
+        await (0, initApp_1.initApp)(dir, options);
+    }
+    catch (err) {
+        console.error("Error:", err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+// Generate command group
+const generate = program
+    .command("generate")
+    .alias("g")
+    .description("Generate models or controllers");
+// Generate model
+generate
+    .command("model <name>")
+    .description("Generate a Prisma model")
+    .option("--skip-migrate", "Skip running Prisma migrate")
+    .action(async (name, options) => {
+    try {
+        await (0, generateModel_1.generateModel)(name, options);
+    }
+    catch (err) {
+        console.error("Error:", err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+// Generate controller
+generate
+    .command("controller <name>")
+    .description("Generate a CRUD controller")
+    .option("--no-views", "Skip generating views")
+    .action(async (name, options) => {
+    try {
+        await (0, generateController_1.generateController)(name, options);
+    }
+    catch (err) {
+        console.error("Error:", err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/framework/App.d.ts

@@ -0,0 +1,38 @@
+import { Express } from "express";
+import { RedisClientType } from "redis";
+import helmet from "helmet";
+import cors from "cors";
+export interface MvcAppOptions {
+    /** Directory for EJS views (default: "src/views") */
+    viewsPath?: string;
+    /** Directory for static files (default: "public") */
+    publicPath?: string;
+    /** Directory for controllers (default: "src/controllers") */
+    controllersPath?: string;
+    /** Enable Redis sessions (default: true if REDIS_URL is set) */
+    enableRedis?: boolean;
+    /** Custom CORS options */
+    corsOptions?: cors.CorsOptions;
+    /** Custom Helmet options */
+    helmetOptions?: Parameters<typeof helmet>[0];
+}
+export interface MvcApp {
+    app: Express;
+    redisClient: RedisClientType | null;
+}
+/**
+ * Create and configure an Express MVC application.
+ *
+ * Includes:
+ * - Helmet for security headers
+ * - CORS support
+ * - JSON and URL-encoded body parsing
+ * - Redis-backed sessions (if REDIS_URL is set)
+ * - EJS view engine
+ * - Static file serving
+ */
+export declare function createMvcApp(options?: MvcAppOptions): Promise<MvcApp>;
+/**
+ * Start the Express server.
+ */
+export declare function startServer(app: Express, port?: number): void;

package/dist/framework/App.js

@@ -0,0 +1,100 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMvcApp = createMvcApp;
+exports.startServer = startServer;
+const express_1 = __importDefault(require("express"));
+const express_session_1 = __importDefault(require("express-session"));
+const redis_1 = require("redis");
+const connect_redis_1 = __importDefault(require("connect-redis"));
+const helmet_1 = __importDefault(require("helmet"));
+const cors_1 = __importDefault(require("cors"));
+const dotenv_1 = __importDefault(require("dotenv"));
+const path_1 = __importDefault(require("path"));
+// Load environment variables
+dotenv_1.default.config();
+/**
+ * Create and configure an Express MVC application.
+ *
+ * Includes:
+ * - Helmet for security headers
+ * - CORS support
+ * - JSON and URL-encoded body parsing
+ * - Redis-backed sessions (if REDIS_URL is set)
+ * - EJS view engine
+ * - Static file serving
+ */
+async function createMvcApp(options = {}) {
+    const { viewsPath = "src/views", publicPath = "public", enableRedis = !!process.env.REDIS_URL, corsOptions = {}, helmetOptions = {}, } = options;
+    const app = (0, express_1.default)();
+    // Security middleware
+    app.use((0, helmet_1.default)(helmetOptions));
+    app.use((0, cors_1.default)(corsOptions));
+    // Body parsing
+    app.use(express_1.default.json());
+    app.use(express_1.default.urlencoded({ extended: true }));
+    // Static files
+    app.use(express_1.default.static(path_1.default.resolve(publicPath)));
+    // Session store (Redis if available, memory otherwise)
+    let redisClient = null;
+    if (enableRedis && process.env.REDIS_URL) {
+        try {
+            redisClient = (0, redis_1.createClient)({ url: process.env.REDIS_URL });
+            await redisClient.connect();
+            const store = new connect_redis_1.default({
+                client: redisClient,
+                prefix: "mvc:",
+            });
+            app.use((0, express_session_1.default)({
+                store,
+                secret: process.env.SESSION_SECRET || "default-secret-change-me",
+                resave: false,
+                saveUninitialized: false,
+                cookie: {
+                    secure: process.env.NODE_ENV === "production",
+                    httpOnly: true,
+                    maxAge: 1000 * 60 * 60 * 24, // 24 hours
+                },
+            }));
+            console.log("Using Redis session store");
+        }
+        catch (err) {
+            console.warn("Failed to connect to Redis, using memory sessions:", err);
+            redisClient = null;
+            setupMemorySessions(app);
+        }
+    }
+    else {
+        // Use memory sessions when Redis is not configured
+        setupMemorySessions(app);
+    }
+    // View engine
+    app.set("view engine", "ejs");
+    app.set("views", path_1.default.resolve(viewsPath));
+    return { app, redisClient };
+}
+/**
+ * Setup memory-based sessions (for development without Redis).
+ */
+function setupMemorySessions(app) {
+    app.use((0, express_session_1.default)({
+        secret: process.env.SESSION_SECRET || "default-secret-change-me",
+        resave: false,
+        saveUninitialized: false,
+        cookie: {
+            secure: process.env.NODE_ENV === "production",
+            httpOnly: true,
+            maxAge: 1000 * 60 * 60 * 24, // 24 hours
+        },
+    }));
+}
+/**
+ * Start the Express server.
+ */
+function startServer(app, port = Number(process.env.PORT) || 3000) {
+    app.listen(port, () => {
+        console.log(`Server listening on port ${port}`);
+    });
+}

package/dist/framework/Auth.d.ts

@@ -0,0 +1,27 @@
+import jwt from "jsonwebtoken";
+import type { Request, Response, NextFunction } from "express";
+/**
+ * Hash a plain text password using bcrypt.
+ */
+export declare function hashPassword(plain: string): Promise<string>;
+/**
+ * Verify a plain text password against a bcrypt hash.
+ */
+export declare function verifyPassword(plain: string, hash: string): Promise<boolean>;
+/**
+ * Sign a JWT token with the given payload.
+ * Token expires in 1 hour by default.
+ */
+export declare function signToken(payload: object, expiresIn?: string | number): string;
+/**
+ * Verify and decode a JWT token.
+ * Returns the decoded payload or throws an error if invalid.
+ */
+export declare function verifyToken(token: string): jwt.JwtPayload | string;
+/**
+ * Express middleware to authenticate requests using JWT Bearer tokens.
+ * Attaches the decoded user payload to req.user on success.
+ */
+export declare function authenticate(req: Request & {
+    user?: jwt.JwtPayload | string;
+}, res: Response, next: NextFunction): void;

package/dist/framework/Auth.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashPassword = hashPassword;
+exports.verifyPassword = verifyPassword;
+exports.signToken = signToken;
+exports.verifyToken = verifyToken;
+exports.authenticate = authenticate;
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+const bcryptjs_1 = __importDefault(require("bcryptjs"));
+/**
+ * Hash a plain text password using bcrypt.
+ */
+async function hashPassword(plain) {
+    const salt = await bcryptjs_1.default.genSalt(10);
+    return bcryptjs_1.default.hash(plain, salt);
+}
+/**
+ * Verify a plain text password against a bcrypt hash.
+ */
+async function verifyPassword(plain, hash) {
+    return bcryptjs_1.default.compare(plain, hash);
+}
+/**
+ * Sign a JWT token with the given payload.
+ * Token expires in 1 hour by default.
+ */
+function signToken(payload, expiresIn = "1h") {
+    const secret = process.env.JWT_SECRET;
+    if (!secret) {
+        throw new Error("JWT_SECRET environment variable is not set");
+    }
+    return jsonwebtoken_1.default.sign(payload, secret, { expiresIn });
+}
+/**
+ * Verify and decode a JWT token.
+ * Returns the decoded payload or throws an error if invalid.
+ */
+function verifyToken(token) {
+    const secret = process.env.JWT_SECRET;
+    if (!secret) {
+        throw new Error("JWT_SECRET environment variable is not set");
+    }
+    return jsonwebtoken_1.default.verify(token, secret);
+}
+/**
+ * Express middleware to authenticate requests using JWT Bearer tokens.
+ * Attaches the decoded user payload to req.user on success.
+ */
+function authenticate(req, res, next) {
+    const header = req.header("Authorization");
+    const token = header?.startsWith("Bearer ") ? header.slice(7) : null;
+    if (!token) {
+        res.status(401).json({ error: "Unauthorized" });
+        return;
+    }
+    try {
+        const decoded = verifyToken(token);
+        req.user = decoded;
+        next();
+    }
+    catch {
+        res.status(401).json({ error: "Invalid token" });
+    }
+}

package/dist/framework/Router.d.ts

@@ -0,0 +1,29 @@
+import type { Express, Request, Response } from "express";
+type RouteHandler = (req: Request, res: Response) => Promise<void> | void;
+interface ControllerModule {
+    index?: RouteHandler;
+    show?: RouteHandler;
+    store?: RouteHandler;
+    update?: RouteHandler;
+    destroy?: RouteHandler;
+    [key: string]: RouteHandler | undefined;
+}
+/**
+ * Register controllers from a directory with convention-based routing.
+ *
+ * Convention:
+ * - GET /<resource> -> index
+ * - GET /<resource>/:id -> show
+ * - POST /<resource> -> store
+ * - PUT /<resource>/:id -> update
+ * - DELETE /<resource>/:id -> destroy
+ *
+ * @param app - Express application instance
+ * @param controllersDir - Absolute path to the controllers directory
+ */
+export declare function registerControllers(app: Express, controllersDir: string): Promise<void>;
+/**
+ * Register a single controller with custom base path.
+ */
+export declare function registerController(app: Express, basePath: string, controller: ControllerModule): void;
+export {};

package/dist/framework/Router.js

@@ -0,0 +1,125 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerControllers = registerControllers;
+exports.registerController = registerController;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+/**
+ * Convert a controller name to a resource path.
+ * e.g., "UserController" -> "users", "PostController" -> "posts"
+ */
+function controllerNameToResource(name) {
+    // Remove "Controller" suffix
+    const baseName = name.replace(/Controller$/, "");
+    // Convert to lowercase and simple pluralization
+    const lower = baseName.toLowerCase();
+    // Simple pluralization: add 's' if not already ending in 's'
+    return lower.endsWith("s") ? lower : lower + "s";
+}
+/**
+ * Register controllers from a directory with convention-based routing.
+ *
+ * Convention:
+ * - GET /<resource> -> index
+ * - GET /<resource>/:id -> show
+ * - POST /<resource> -> store
+ * - PUT /<resource>/:id -> update
+ * - DELETE /<resource>/:id -> destroy
+ *
+ * @param app - Express application instance
+ * @param controllersDir - Absolute path to the controllers directory
+ */
+async function registerControllers(app, controllersDir) {
+    if (!fs_1.default.existsSync(controllersDir)) {
+        console.warn(`Controllers directory not found: ${controllersDir}`);
+        return;
+    }
+    const files = fs_1.default.readdirSync(controllersDir);
+    const controllerFiles = files.filter((f) => f.endsWith("Controller.ts") || f.endsWith("Controller.js"));
+    for (const file of controllerFiles) {
+        const controllerPath = path_1.default.join(controllersDir, file);
+        const controllerName = path_1.default.basename(file, path_1.default.extname(file));
+        const resource = controllerNameToResource(controllerName);
+        try {
+            // Dynamic import for ES modules
+            const controller = await Promise.resolve(`${controllerPath}`).then(s => __importStar(require(s)));
+            // Register routes based on exported functions
+            if (controller.index) {
+                app.get(`/${resource}`, controller.index);
+            }
+            if (controller.show) {
+                app.get(`/${resource}/:id`, controller.show);
+            }
+            if (controller.store) {
+                app.post(`/${resource}`, controller.store);
+            }
+            if (controller.update) {
+                app.put(`/${resource}/:id`, controller.update);
+            }
+            if (controller.destroy) {
+                app.delete(`/${resource}/:id`, controller.destroy);
+            }
+            console.log(`Registered controller: ${controllerName} -> /${resource}`);
+        }
+        catch (err) {
+            console.error(`Failed to load controller ${file}:`, err);
+        }
+    }
+}
+/**
+ * Register a single controller with custom base path.
+ */
+function registerController(app, basePath, controller) {
+    const resource = basePath.startsWith("/") ? basePath : `/${basePath}`;
+    if (controller.index) {
+        app.get(resource, controller.index);
+    }
+    if (controller.show) {
+        app.get(`${resource}/:id`, controller.show);
+    }
+    if (controller.store) {
+        app.post(resource, controller.store);
+    }
+    if (controller.update) {
+        app.put(`${resource}/:id`, controller.update);
+    }
+    if (controller.destroy) {
+        app.delete(`${resource}/:id`, controller.destroy);
+    }
+}

package/dist/framework/db.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Get or create a singleton PrismaClient instance.
+ * Safe for use in long-running Node processes.
+ *
+ * Note: Only call this if your app uses a database.
+ * Throws an error if @prisma/client is not installed.
+ */
+export declare function getPrismaClient(): any;
+/**
+ * Disconnect the Prisma client.
+ * Useful for graceful shutdown.
+ */
+export declare function disconnectPrisma(): Promise<void>;

package/dist/framework/db.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPrismaClient = getPrismaClient;
+exports.disconnectPrisma = disconnectPrisma;
+// Prisma is optional - only loaded when needed
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let prisma = null;
+let PrismaClient = null;
+/**
+ * Get or create a singleton PrismaClient instance.
+ * Safe for use in long-running Node processes.
+ *
+ * Note: Only call this if your app uses a database.
+ * Throws an error if @prisma/client is not installed.
+ */
+function getPrismaClient() {
+    if (!prisma) {
+        if (!PrismaClient) {
+            try {
+                // Dynamic import to make Prisma optional
+                // eslint-disable-next-line @typescript-eslint/no-require-imports
+                PrismaClient = require("@prisma/client").PrismaClient;
+            }
+            catch {
+                throw new Error("Prisma is not installed. Run 'npm install @prisma/client prisma' to use database features.");
+            }
+        }
+        prisma = new PrismaClient();
+    }
+    return prisma;
+}
+/**
+ * Disconnect the Prisma client.
+ * Useful for graceful shutdown.
+ */
+async function disconnectPrisma() {
+    if (prisma) {
+        await prisma.$disconnect();
+        prisma = null;
+    }
+}

package/dist/framework/index.d.ts

@@ -0,0 +1,5 @@
+export { createMvcApp, startServer } from "./App";
+export type { MvcAppOptions, MvcApp } from "./App";
+export { getPrismaClient, disconnectPrisma } from "./db";
+export { hashPassword, verifyPassword, signToken, verifyToken, authenticate, } from "./Auth";
+export { registerControllers, registerController } from "./Router";