create-lumina-project 1.0.1 → 1.1.1

package/bin/cli.js

@@ -3,70 +3,148 @@
 import fs from 'fs-extra';
 import path from 'path';
 import prompts from 'prompts';
-import { bold, green, cyan, red } from 'kleur/colors';
+import { bold, green, cyan, red, yellow } from 'kleur/colors';
 import { fileURLToPath } from 'url';
+import { exec } from 'child_process';
+import util from 'util';
+import ora from 'ora';
+
+const execAsync = util.promisify(exec);
 
 // Get current directory of the script
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 async function init() {
-  console.log(bold(cyan('\n🚀 Welcome to the Lumina Installer!')));
+  console.log(`\n${bold(cyan('🚀 Welcome to the Lumina Installer!'))}\n`);
 
   // 1. Ask for Project Name
   let targetDir = process.argv[2];
 
   if (!targetDir) {
-    const response = await prompts({
-      type: 'text',
-      name: 'projectName',
-      message: 'What is your project name?',
-      initial: 'my-lumina-app'
-    });
-
-    if (!response.projectName) {
-      console.log(red('✖ Operation cancelled'));
-      process.exit(1);
-    }
-    targetDir = response.projectName;
+    const response = await prompts(
+      {
+        type: 'text',
+        name: 'projectName',
+        message: 'What is your project name?',
+        initial: 'my-lumina-app',
+        validate: (name) => {
+          if (!name.trim()) return 'Project name cannot be empty.';
+          if (!/^[a-z0-9-_]+$/.test(name)) {
+            return 'Project name can only contain lowercase letters, numbers, dashes, and underscores.';
+          }
+          return true;
+        }
+      },
+      {
+        onCancel: () => {
+          console.log(red('✖ Operation cancelled'));
+          process.exit(1);
+        }
+      }
+    );
+
+    targetDir = response.projectName.trim();
   }
 
-  const projectPath = path.join(process.cwd(), targetDir);
+  const projectPath = path.resolve(process.cwd(), targetDir);
 
   // 2. Check if folder exists
   if (fs.existsSync(projectPath)) {
     console.log(red(`\n✖ Error: Directory "${targetDir}" already exists.`));
     process.exit(1);
   }
+  
+  // 3. Prompt for extra setups (git and npm install)
+  const setupPreferences = await prompts(
+    [
+      {
+        type: 'confirm',
+        name: 'initGit',
+        message: 'Initialize a new git repository?',
+        initial: true
+      },
+      {
+        type: 'confirm',
+        name: 'installDeps',
+        message: 'Install dependencies automatically?',
+        initial: true
+      }
+    ],
+    {
+      onCancel: () => {
+        console.log(red('✖ Operation cancelled'));
+        process.exit(1);
+      }
+    }
+  );
 
-  console.log(`\n📂 Creating project in ${green(projectPath)}...`);
+  console.log(''); // Blank space for readability
 
-  // 3. Copy Template
+  const copySpinner = ora(`📂 Creating project in ${green(projectPath)}...`).start();
+
+  // 4. Copy Template
   const templateDir = path.resolve(__dirname, '../template');
   
   try {
     await fs.copy(templateDir, projectPath);
     
-    // 4. Rename _gitignore to .gitignore (npm usually strips .gitignore from published packages)
+    // 5. Rename _gitignore to .gitignore
     const gitignorePath = path.join(projectPath, '_gitignore');
     if (fs.existsSync(gitignorePath)) {
       fs.renameSync(gitignorePath, path.join(projectPath, '.gitignore'));
     }
 
-    // 5. Update package.json name
+    // 6. Update package.json name
     const pkgPath = path.join(projectPath, 'package.json');
-    const pkg = await fs.readJson(pkgPath);
-    pkg.name = targetDir;
-    await fs.writeJson(pkgPath, pkg, { spaces: 2 });
+    if (fs.existsSync(pkgPath)) {
+      const pkg = await fs.readJson(pkgPath);
+      pkg.name = path.basename(projectPath);
+      await fs.writeJson(pkgPath, pkg, { spaces: 2 });
+    }
 
-    console.log(green('\n✅ Project setup complete!'));
-    console.log('\nTo get started run:');
-    console.log(cyan(`  cd ${targetDir}`));
-    console.log(cyan('  npm install'));
-    console.log(cyan('  npm run dev'));
+    copySpinner.succeed(green('Project template copied successfully!'));
+
+    // 7. Initialize Git
+    if (setupPreferences.initGit) {
+      const gitSpinner = ora('Initializing git repository...').start();
+      try {
+        await execAsync('git init', { cwd: projectPath });
+        // Optional: add initial commit but usually people prefer to do it themselves or standard tooling just inits
+        gitSpinner.succeed(green('Git repository initialized.'));
+      } catch (error) {
+        gitSpinner.fail(yellow('Failed to initialize git repository (is git installed?)'));
+      }
+    }
+
+    // 8. Install Dependencies
+    if (setupPreferences.installDeps) {
+      const depsSpinner = ora('Installing dependencies (this might take a few minutes)...').start();
+      try {
+        await execAsync('npm install', { cwd: projectPath });
+        depsSpinner.succeed(green('Dependencies installed successfully!'));
+      } catch (error) {
+        depsSpinner.fail(red('Failed to install dependencies. You can run "npm install" manually later.'));
+      }
+    }
+
+    // 9. Success message & Next steps
+    console.log(`\n${bold(green('✅ All done! Project setup complete.'))}`);
+    console.log('\nTo get started run:\n');
+    
+    const cdCmd = projectPath === process.cwd() ? '' : `cd ${targetDir}`;
+    if (cdCmd) console.log(cyan(`  ${cdCmd}`));
+    
+    if (!setupPreferences.installDeps) {
+      console.log(cyan('  npm install'));
+    }
+    
+    console.log(cyan('  npm run dev\n'));
 
   } catch (error) {
-    console.error(red('Error copying files:'), error);
+    copySpinner.fail(red('Error copying files:'));
+    console.error(error);
+    process.exit(1);
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-lumina-project",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "author": "Glenson Ansin",
   "description": "Scaffold a modern Node.js API with Lumina architecture.",
   "type": "module",
@@ -14,6 +14,7 @@
   "dependencies": {
     "fs-extra": "^11.3.3",
     "kleur": "^4.1.5",
+    "ora": "^9.3.0",
     "prompts": "^2.4.2"
   },
   "license": "MIT",

package/template/.env.example

@@ -17,6 +17,7 @@ JWT_EXPIRES_IN=1d
 # Application
 NODE_ENV=development
 APP_PORT=3000
+CORS_ORIGIN=http://localhost:3000
 
 # Logging
 LOG_LEVEL=info

package/template/package.json

@@ -1,55 +1,60 @@
-{
-  "name": "lumina",
-  "version": "1.0.0",
-  "description": "",
-  "main": "server.ts",
-  "scripts": {
-    "dev": "nodemon --exec tsx server.ts",
-    "build": "tsc",
-    "start": "node dist/server.js",
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "migrate": "tsx scripts/migrate.ts up",
-    "migrate:undo": "tsx scripts/migrate.ts down",
-    "migrate:reset": "tsx scripts/migrate.ts reset",
-    "db:seed": "tsx scripts/seed.ts",
-    "down": "tsx scripts/maintenance.ts down",
-    "up": "tsx scripts/maintenance.ts up",
-    "create:model": "tsx scripts/create-model.ts",
-    "create:migration": "tsx scripts/create-migration.ts",
-    "create:controller": "tsx scripts/create-controller.ts",
-    "create:factory": "tsx scripts/create-factory.ts",
-    "key:generate": "tsx scripts/generate-keys.ts"
-  },
-  "private": true,
-  "type": "module",
-  "dependencies": {
-    "@faker-js/faker": "^10.2.0",
-    "bcrypt": "^6.0.0",
-    "bcryptjs": "^3.0.3",
-    "cors": "^2.8.6",
-    "dotenv": "^17.2.3",
-    "express": "^5.2.1",
-    "express-rate-limit": "^8.2.1",
-    "helmet": "^8.1.0",
-    "jsonwebtoken": "^9.0.3",
-    "multer": "^2.0.2",
-    "mysql2": "^3.16.2",
-    "nodemon": "^3.1.11",
-    "pg": "^8.18.0",
-    "pg-hstore": "^2.3.4",
-    "sequelize": "^6.37.7",
-    "sequelize-cli": "^6.6.5",
-    "umzug": "^3.8.2",
-    "winston": "^3.19.0",
-    "zod": "^4.3.6"
-  },
-  "devDependencies": {
-    "@types/bcrypt": "^6.0.0",
-    "@types/cors": "^2.8.19",
-    "@types/express": "^5.0.6",
-    "@types/jsonwebtoken": "^9.0.10",
-    "@types/multer": "^2.0.0",
-    "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
-  }
-}
+{
+  "name": "lumina",
+  "version": "1.0.0",
+  "description": "",
+  "main": "server.ts",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "nodemon --exec tsx server.ts",
+    "build": "tsc",
+    "start": "node dist/server.js",
+    "test": "vitest run",
+    "migrate": "tsx scripts/migrate.ts up",
+    "migrate:undo": "tsx scripts/migrate.ts down",
+    "migrate:reset": "tsx scripts/migrate.ts reset",
+    "db:seed": "tsx scripts/seed.ts",
+    "down": "tsx scripts/maintenance.ts down",
+    "up": "tsx scripts/maintenance.ts up",
+    "create:model": "tsx scripts/create-model.ts",
+    "create:migration": "tsx scripts/create-migration.ts",
+    "create:controller": "tsx scripts/create-controller.ts",
+    "create:factory": "tsx scripts/create-factory.ts",
+    "key:generate": "tsx scripts/generate-keys.ts"
+  },
+  "dependencies": {
+    "bcrypt": "^6.0.0",
+    "bcryptjs": "^3.0.3",
+    "compression": "^1.8.1",
+    "cookie-parser": "^1.4.7",
+    "cors": "^2.8.6",
+    "dotenv": "^17.2.3",
+    "express": "^5.2.1",
+    "express-rate-limit": "^8.2.1",
+    "helmet": "^8.1.0",
+    "jsonwebtoken": "^9.0.3",
+    "multer": "^2.0.2",
+    "mysql2": "^3.16.2",
+    "nodemon": "^3.1.11",
+    "pg": "^8.18.0",
+    "pg-hstore": "^2.3.4",
+    "sequelize": "^6.37.7",
+    "sequelize-cli": "^6.6.5",
+    "umzug": "^3.8.2",
+    "winston": "^3.19.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@faker-js/faker": "^10.3.0",
+    "@types/bcrypt": "^6.0.0",
+    "@types/compression": "^1.8.1",
+    "@types/cookie-parser": "^1.4.10",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/multer": "^2.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}

package/template/public/js/status.js

@@ -0,0 +1,53 @@
+async function fetchStatus() {
+    try {
+        const res = await fetch('/status/json');
+        const data = await res.json();
+
+        // Status
+        const heroEl = document.getElementById('statusHero');
+        const heroText = document.getElementById('statusHeroText');
+        const appStatus = document.getElementById('appStatus');
+        const isUp = data.status === 'UP';
+
+        heroEl.className = 'status-hero ' + (isUp ? 'up' : 'down');
+        heroText.textContent = isUp ? 'All Systems Operational' : 'System Degraded';
+        appStatus.textContent = data.status;
+        appStatus.className = 'info-value ' + (isUp ? 'status-up' : 'status-down');
+
+        // Environment
+        document.getElementById('appEnv').textContent = data.environment || 'unknown';
+
+        // Uptime
+        if (data.uptime !== undefined) {
+            document.getElementById('appUptime').textContent = formatUptime(data.uptime);
+        }
+
+        // Memory
+        if (data.memoryMB !== undefined) {
+            document.getElementById('appMemory').textContent = data.memoryMB + ' MB';
+        }
+
+        // Timestamp
+        document.getElementById('lastChecked').textContent = 'Checked ' + new Date().toLocaleTimeString();
+    } catch (err) {
+        document.getElementById('statusHero').className = 'status-hero down';
+        document.getElementById('statusHeroText').textContent = 'Unable to Reach Server';
+    }
+}
+
+function formatUptime(seconds) {
+    const d = Math.floor(seconds / 86400);
+    const h = Math.floor((seconds % 86400) / 3600);
+    const m = Math.floor((seconds % 3600) / 60);
+    const s = Math.floor(seconds % 60);
+    const parts = [];
+    if (d > 0) parts.push(d + 'd');
+    if (h > 0) parts.push(h + 'h');
+    if (m > 0) parts.push(m + 'm');
+    parts.push(s + 's');
+    return parts.join(' ');
+}
+
+// Fetch immediately, then refresh every 30s
+fetchStatus();
+setInterval(fetchStatus, 30000);

package/template/server.ts

@@ -1,6 +1,8 @@
 import express, { Application } from 'express';
 import cors from 'cors';
 import helmet from 'helmet';
+import compression from 'compression';
+import cookieParser from 'cookie-parser';
 import path from 'path';
 import db from './src/models/index.js';
 import RouteService from './src/services/RouteService.js';
@@ -8,23 +10,28 @@ import ExceptionHandler from './src/exceptions/Handler.js';
 import Logger from './src/utils/Logger.js';
 import Limiter from './src/middlewares/Limiter.js';
 import Maintenance from './src/middlewares/Maintenance.js';
-import dotenv from 'dotenv';
-
-dotenv.config();
+import RequestLogger from './src/middlewares/RequestLogger.js';
+import env from './src/config/env.js';
 
 const app: Application = express();
-const PORT = process.env.APP_PORT || 3000;
+const PORT = env.APP_PORT;
 
 // ==========================
 // Global Middleware
 // ==========================
 app.use(Maintenance.handle);
 app.use(helmet({ crossOriginResourcePolicy: false }));
-app.use(cors());
-app.use(express.json());
-app.use(express.urlencoded({ extended: true }));
+app.use(cors({
+  origin: env.CORS_ORIGIN,
+  credentials: true,
+}));
+app.use(compression());
+app.use(cookieParser());
+app.use(express.json({ limit: '10kb' }));
+app.use(express.urlencoded({ extended: true, limit: '10kb' }));
 app.use(express.static(path.join(process.cwd(), 'public')));
 app.use(Limiter.global);
+app.use(RequestLogger.handle);
 
 // ==========================
 // Register Routes
@@ -45,13 +52,15 @@ app.use(ExceptionHandler.handle);
 // ==========================
 // Start Server
 // ==========================
+let server: ReturnType<typeof app.listen>;
+
 const start = async () => {
   try {
     // Test Database Connection
     await db.connect();
 
     // Start Listening
-    app.listen(PORT, () => {
+    server = app.listen(PORT, () => {
       Logger.info(`Server running on http://localhost:${PORT}`);
     });
   } catch (error) {
@@ -60,4 +69,37 @@ const start = async () => {
   }
 };
 
+// ==========================
+// Graceful Shutdown
+// ==========================
+const shutdown = async (signal: string) => {
+  Logger.info(`${signal} received. Shutting down gracefully...`);
+
+  if (server) {
+    server.close(async () => {
+      Logger.info('HTTP server closed.');
+
+      try {
+        await db.sequelize.close();
+        Logger.info('Database connection closed.');
+      } catch (error) {
+        Logger.error('Error closing database connection:', error);
+      }
+
+      process.exit(0);
+    });
+
+    // Force shutdown after 10 seconds
+    setTimeout(() => {
+      Logger.error('Forced shutdown after timeout.');
+      process.exit(1);
+    }, 10000);
+  } else {
+    process.exit(0);
+  }
+};
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+
 start();

package/template/src/config/database.ts

@@ -1,8 +1,6 @@
 import { Options } from 'sequelize';
 import Logger from '../utils/Logger.js';
-import dotenv from 'dotenv';
-
-dotenv.config();
+import env from './env.js';
 
 class DatabaseConfig {
   public development: Options;
@@ -19,18 +17,18 @@ class DatabaseConfig {
    * Helper to generate config based on the environment.
    * This reduces repetition.
    */
-  private getEnvironmentConfig(env: 'development' | 'test' | 'production' = 'development'): Options {
-    const isTest = env === 'test';
-    const isProd = env === 'production';
-    const useSSL = process.env.DB_SSL === 'true';
+  private getEnvironmentConfig(envName: 'development' | 'test' | 'production' = 'development'): Options {
+    const isTest = envName === 'test';
+    const isProd = envName === 'production';
+    const useSSL = env.DB_SSL === 'true';
 
     return {
-      username: process.env.DB_USERNAME,
-      password: process.env.DB_PASSWORD,
-      database: isTest ? process.env.DB_DATABASE_TEST : process.env.DB_DATABASE,
-      host: process.env.DB_HOST,
-      port: Number(process.env.DB_PORT) || 3306,
-      dialect: (process.env.DB_DIALECT as any) || 'mysql',
+      username: env.DB_USERNAME,
+      password: env.DB_PASSWORD,
+      database: isTest ? env.DB_DATABASE_TEST : env.DB_DATABASE,
+      host: env.DB_HOST,
+      port: env.DB_PORT,
+      dialect: env.DB_DIALECT as any,
       dialectOptions: useSSL ? {
         ssl: {
           require: true,

package/template/src/config/env.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+/**
+ * Centralized Environment Validation
+ * 
+ * Validates all required environment variables at startup
+ * and exports a typed `env` object for use throughout the app.
+ */
+const envSchema = z.object({
+  // Application
+  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
+  APP_PORT: z.coerce.number().default(3000),
+
+  // Database
+  DB_DIALECT: z.enum(['mysql', 'postgres', 'mariadb', 'sqlite']).default('mysql'),
+  DB_HOST: z.string().min(1, 'DB_HOST is required'),
+  DB_PORT: z.coerce.number().default(3306),
+  DB_DATABASE: z.string().min(1, 'DB_DATABASE is required'),
+  DB_DATABASE_TEST: z.string().optional(),
+  DB_USERNAME: z.string().min(1, 'DB_USERNAME is required'),
+  DB_PASSWORD: z.string().default(''),
+  DB_SSL: z.string().optional(),
+
+  // JWT
+  JWT_SECRET: z.string().min(16, 'JWT_SECRET must be at least 16 characters for security'),
+  JWT_EXPIRES_IN: z.string().default('15m'),
+  JWT_REFRESH_EXPIRES_IN: z.string().default('7d'),
+
+  // CORS
+  CORS_ORIGIN: z.string().default('http://localhost:3000'),
+
+  // Logging
+  LOG_LEVEL: z.string().default('info'),
+
+  // Maintenance
+  MAINTENANCE_SECRET: z.string().optional(),
+});
+
+const parsed = envSchema.safeParse(process.env);
+
+if (!parsed.success) {
+  console.error('❌ Invalid environment variables:');
+  for (const issue of parsed.error.issues) {
+    console.error(`   ${issue.path.join('.')}: ${issue.message}`);
+  }
+  process.exit(1);
+}
+
+const env = parsed.data;
+
+export default env;

package/template/src/controllers/AuthController.ts

@@ -13,6 +13,36 @@ class AuthController {
     }
   }
 
+  public async refresh(req: Request, res: Response) {
+    try {
+      const { refreshToken } = req.body;
+
+      if (!refreshToken) {
+        return ApiResponse.error(res, 'Refresh token is required', 400);
+      }
+
+      const result = await AuthService.refresh(refreshToken);
+      return ApiResponse.success(res, result, 'Token refreshed successfully');
+    } catch (error: any) {
+      return ApiResponse.error(res, error.message, 401);
+    }
+  }
+
+  public async logout(req: Request, res: Response) {
+    try {
+      const { refreshToken } = req.body;
+
+      if (!refreshToken) {
+        return ApiResponse.error(res, 'Refresh token is required', 400);
+      }
+
+      await AuthService.logout(refreshToken);
+      return ApiResponse.success(res, null, 'Logged out successfully');
+    } catch (error: any) {
+      return ApiResponse.error(res, error.message, 500);
+    }
+  }
+
   public async me(req: Request, res: Response) {
     return ApiResponse.success(res, req.user);
   }

package/template/src/database/migrations/20260222151300-create_refresh_tokens.js

@@ -0,0 +1,63 @@
+import { DataTypes } from 'sequelize';
+
+class CreateRefreshTokensTable {
+  /**
+   * Run the migrations.
+   */
+  async up(queryInterface, Sequelize) {
+    await queryInterface.createTable('refresh_tokens', {
+      id: {
+        allowNull: false,
+        autoIncrement: true,
+        primaryKey: true,
+        type: DataTypes.BIGINT,
+      },
+      user_id: {
+        type: DataTypes.BIGINT,
+        allowNull: false,
+        references: {
+          model: 'users',
+          key: 'id',
+        },
+        onUpdate: 'CASCADE',
+        onDelete: 'CASCADE',
+      },
+      token: {
+        type: DataTypes.STRING(512),
+        allowNull: false,
+        unique: true,
+      },
+      expires_at: {
+        type: DataTypes.DATE,
+        allowNull: false,
+      },
+      revoked: {
+        type: DataTypes.BOOLEAN,
+        allowNull: false,
+        defaultValue: false,
+      },
+      created_at: {
+        allowNull: false,
+        type: DataTypes.DATE,
+        defaultValue: Sequelize.literal('CURRENT_TIMESTAMP'),
+      },
+      updated_at: {
+        allowNull: false,
+        type: DataTypes.DATE,
+        defaultValue: Sequelize.literal('CURRENT_TIMESTAMP'),
+      },
+    });
+
+    await queryInterface.addIndex('refresh_tokens', ['token']);
+    await queryInterface.addIndex('refresh_tokens', ['user_id']);
+  }
+
+  /**
+   * Reverse the migrations.
+   */
+  async down(queryInterface) {
+    await queryInterface.dropTable('refresh_tokens');
+  }
+}
+
+export default new CreateRefreshTokensTable();