create-lumina-project 1.0.0

package/bin/cli.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+import fs from 'fs-extra';
+import path from 'path';
+import prompts from 'prompts';
+import { bold, green, cyan, red } from 'kleur/colors';
+import { fileURLToPath } from 'url';
+
+// 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!')));
+
+  // 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 projectPath = path.join(process.cwd(), targetDir);
+
+  // 2. Check if folder exists
+  if (fs.existsSync(projectPath)) {
+    console.log(red(`\n✖ Error: Directory "${targetDir}" already exists.`));
+    process.exit(1);
+  }
+
+  console.log(`\n📂 Creating project in ${green(projectPath)}...`);
+
+  // 3. 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)
+    const gitignorePath = path.join(projectPath, '_gitignore');
+    if (fs.existsSync(gitignorePath)) {
+      fs.renameSync(gitignorePath, path.join(projectPath, '.gitignore'));
+    }
+
+    // 5. 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 });
+
+    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'));
+
+  } catch (error) {
+    console.error(red('Error copying files:'), error);
+  }
+}
+
+init();

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "create-lumina-project",
+  "version": "1.0.0",
+  "author": "Ghost",
+  "description": "Scaffold a modern Node.js API with Lumina architecture.",
+  "type": "module",
+  "bin": {
+    "create-lumina-project": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "dependencies": {
+    "fs-extra": "^11.3.3",
+    "kleur": "^4.1.5",
+    "prompts": "^2.4.2"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GlensonAnsin/lumina.git"
+  },
+  "bugs": {
+    "url": "https://github.com/GlensonAnsin/lumina/issues"
+  },
+  "homepage": "https://github.com/GlensonAnsin/lumina#readme"
+}

package/template/.env.example

@@ -0,0 +1,15 @@
+DB_DIALECT=mysql
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_DATABASE=lumina
+DB_USERNAME=root
+DB_PASSWORD=
+
+JWT_SECRET=secret_key
+JWT_EXPIRES_IN=1d
+
+LOG_LEVEL=
+
+NODE_ENV=development
+
+MAINTENANCE_SECRET=secret_key

package/template/.sequelizerc

@@ -0,0 +1,11 @@
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+export default {
+  'config': path.resolve(__dirname, 'src/config', 'database.ts'),
+  'models-path': path.resolve(__dirname, 'src/models'),
+  'seeders-path': path.resolve(__dirname, 'src/database/seeders'),
+  'migrations-path': path.resolve(__dirname, 'src/database/migrations')
+};

package/template/_gitignore

@@ -0,0 +1,3 @@
+node_modules/
+logs/
+.env

package/template/nodemon.json

@@ -0,0 +1,5 @@
+{
+  "watch": ["src"],
+  "ext": "ts,json",
+  "exec": "tsx src/server.ts" 
+}

package/template/package.json

@@ -0,0 +1,53 @@
+{
+  "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"
+  },
+  "author": "Ghost",
+  "license": "ISC",
+  "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",
+    "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"
+  }
+}

package/template/scripts/create-controller.ts

@@ -0,0 +1,89 @@
+import fs from 'fs';
+import path from 'path';
+import Logger from '../src/utils/Logger.js';
+
+class ControllerGenerator {
+  private controllerName: string;
+  private stubPath: string;
+  private controllersDir: string;
+  private targetPath: string;
+
+  constructor() {
+    // 1. Get Argument
+    const rawName = process.argv[2];
+
+    // 2. Validate & Format
+    if (rawName) {
+      this.controllerName = this.formatName(rawName);
+    } else {
+      this.controllerName = '';
+    }
+
+    // 3. Define Paths
+    this.stubPath = path.join(process.cwd(), 'scripts', 'stubs', 'controller.stub');
+    this.controllersDir = path.join(process.cwd(), 'src', 'controllers');
+
+    this.targetPath = this.controllerName 
+      ? path.join(this.controllersDir, `${this.controllerName}.ts`) 
+      : '';
+  }
+
+  /**
+   * Helper: Ensures strict PascalCase and appends 'Controller' if missing.
+   * "user" -> "UserController"
+   * "ProductController" -> "ProductController"
+   */
+  private formatName(str: string): string {
+    let name = str.charAt(0).toUpperCase() + str.slice(1);
+    
+    // Append 'Controller' if user forgot it
+    if (!name.endsWith('Controller')) {
+      name += 'Controller';
+    }
+    
+    return name;
+  }
+
+  public run(): void {
+    if (!this.validateInput()) return;
+
+    if (this.controllerExists()) {
+      Logger.error(`Controller "${this.controllerName}" already exists at src/controllers/${this.controllerName}.ts`);
+      process.exit(1);
+    }
+
+    this.createFile();
+  }
+
+  private validateInput(): boolean {
+    if (!this.controllerName) {
+      Logger.error('Please provide a controller name.');
+      console.log('\nUsage: npm run make:controller <Name>');
+      console.log('Example: npm run make:controller ProductController\n');
+      process.exit(1);
+    }
+    return true;
+  }
+
+  private controllerExists(): boolean {
+    return fs.existsSync(this.targetPath);
+  }
+
+  private createFile(): void {
+    try {
+      let content = fs.readFileSync(this.stubPath, 'utf-8');
+
+      // Replace Placeholder
+      content = content.replace(/{{ControllerName}}/g, this.controllerName);
+
+      fs.writeFileSync(this.targetPath, content);
+
+      Logger.info(`Controller Created: src/controllers/${this.controllerName}.ts`);
+    } catch (error) {
+      Logger.error('Failed to create controller:', error);
+      process.exit(1);
+    }
+  }
+}
+
+new ControllerGenerator().run();

package/template/scripts/create-factory.ts

@@ -0,0 +1,98 @@
+import fs from 'fs';
+import path from 'path';
+import Logger from '../src/utils/Logger.js';
+
+class FactoryGenerator {
+  private factoryName: string;
+  private modelName: string;
+  private stubPath: string;
+  private factoriesDir: string;
+  private targetPath: string;
+
+  constructor() {
+    // 1. Get Argument
+    const rawName = process.argv[2];
+
+    // 2. Validate & Format
+    if (rawName) {
+      this.factoryName = this.formatFactoryName(rawName);
+      this.modelName = this.guessModelName(this.factoryName);
+    } else {
+      this.factoryName = '';
+      this.modelName = '';
+    }
+
+    // 3. Define Paths
+    this.stubPath = path.join(process.cwd(), 'scripts', 'stubs', 'factory.stub');
+    this.factoriesDir = path.join(process.cwd(), 'src', 'database', 'factories');
+
+    this.targetPath = this.factoryName 
+      ? path.join(this.factoriesDir, `${this.factoryName}.ts`) 
+      : '';
+  }
+
+  /**
+   * Ensures 'Factory' suffix and PascalCase.
+   * "product" -> "ProductFactory"
+   */
+  private formatFactoryName(str: string): string {
+    let name = str.charAt(0).toUpperCase() + str.slice(1);
+    if (!name.endsWith('Factory')) {
+      name += 'Factory';
+    }
+    return name;
+  }
+
+  /**
+   * Guesses model name by removing 'Factory'.
+   * "ProductFactory" -> "Product"
+   */
+  private guessModelName(factoryName: string): string {
+    return factoryName.replace('Factory', '');
+  }
+
+  public run(): void {
+    if (!this.validateInput()) return;
+
+    if (this.factoryExists()) {
+      Logger.error(`Factory "${this.factoryName}" already exists.`);
+      process.exit(1);
+    }
+
+    this.createFile();
+  }
+
+  private validateInput(): boolean {
+    if (!this.factoryName) {
+      Logger.error('Please provide a factory name.');
+      console.log('\nUsage: npm run make:factory <Name>');
+      console.log('Example: npm run make:factory Product\n');
+      process.exit(1);
+    }
+    return true;
+  }
+
+  private factoryExists(): boolean {
+    return fs.existsSync(this.targetPath);
+  }
+
+  private createFile(): void {
+    try {
+      let content = fs.readFileSync(this.stubPath, 'utf-8');
+
+      // Replace Placeholders
+      // Regex /g ensures it replaces ALL instances (e.g. extending Factory<Model> AND importing Model)
+      content = content.replace(/{{FactoryName}}/g, this.factoryName);
+      content = content.replace(/{{ModelName}}/g, this.modelName);
+
+      fs.writeFileSync(this.targetPath, content);
+
+      Logger.info(`Factory Created: src/database/factories/${this.factoryName}.ts`);
+    } catch (error) {
+      Logger.error('Failed to create factory:', error);
+      process.exit(1);
+    }
+  }
+}
+
+new FactoryGenerator().run();

package/template/scripts/create-migration.ts

@@ -0,0 +1,98 @@
+import fs from 'fs';
+import path from 'path';
+import Logger from '../src/utils/Logger.js';
+
+class MigrationGenerator {
+  private nameArgument: string;
+  private migrationName: string;
+  private className: string;
+  private tableName: string;
+  private migrationsDir: string;
+  private stubPath: string;
+
+  constructor() {
+    this.nameArgument = process.argv[2];
+    this.migrationsDir = path.join(process.cwd(), 'src', 'database', 'migrations');
+    this.stubPath = path.join(process.cwd(), 'scripts', 'stubs', 'migration.stub');
+    
+    // Initialize properties safely
+    this.migrationName = '';
+    this.className = '';
+    this.tableName = 'table_name';
+  }
+
+  public run(): void {
+    if (!this.validateInput()) return;
+
+    this.parseNameArgument();
+    this.createMigrationFile();
+  }
+
+  private validateInput(): boolean {
+    if (!this.nameArgument) {
+      Logger.error('Please provide a migration name.');
+      console.log('\nUsage: npm run make:migration <name>');
+      console.log('Example: npm run make:migration create_products_table\n');
+      process.exit(1);
+    }
+    return true;
+  }
+
+  /**
+   * Transforms input "create_products_table" into:
+   * ClassName: CreateProductsTable
+   * TableName: products (tries to guess it)
+   */
+  private parseNameArgument(): void {
+    this.migrationName = this.nameArgument.toLowerCase();
+
+    // 1. Generate Class Name (PascalCase)
+    this.className = this.migrationName
+      .split('_')
+      .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+      .join('');
+
+    // 2. Guess Table Name
+    const match = this.migrationName.match(/create_(.+)_table/);
+    if (match && match[1]) {
+      this.tableName = match[1];
+    } else {
+      this.tableName = this.migrationName;
+    }
+  }
+
+  /**
+   * Generates YYYYMMDDHHMMSS format
+   */
+  private getTimestamp(): string {
+    const now = new Date();
+    return now.toISOString().replace(/[-T:.Z]/g, '').slice(0, 14);
+  }
+
+  private createMigrationFile(): void {
+    try {
+      // 1. Generate Filename with Timestamp
+      const timestamp = this.getTimestamp();
+      const fileName = `${timestamp}-create_${this.migrationName}.js`;
+      const targetPath = path.join(this.migrationsDir, fileName);
+
+      // 2. Read Stub
+      let content = fs.readFileSync(this.stubPath, 'utf-8');
+
+      // 3. Replace Placeholders
+      content = content.replace(/{{ClassName}}/g, this.className);
+      content = content.replace(/{{TableName}}/g, this.tableName);
+
+      // 4. Write File
+      fs.writeFileSync(targetPath, content);
+
+      Logger.info(`Migration Created: src/database/migrations/${fileName}`);
+      
+    } catch (error) {
+      Logger.error('Failed to create migration:', error);
+      process.exit(1);
+    }
+  }
+}
+
+new MigrationGenerator().run();

package/template/scripts/create-model.ts

@@ -0,0 +1,105 @@
+import fs from 'fs';
+import path from 'path';
+import Logger from '../src/utils/Logger.js';
+
+class ModelGenerator {
+  private modelName: string;
+  private stubPath: string;
+  private modelsDir: string;
+  private targetPath: string;
+
+  constructor() {
+    // 1. Initialize Inputs
+    const rawName = process.argv[2];
+
+    if (rawName) {
+      this.modelName = this.formatName(rawName);
+    } else {
+      this.modelName = '';
+    }
+    
+    // 2. Define Paths
+    this.stubPath = path.join(process.cwd(), 'scripts', 'stubs', 'model.stub');
+    this.modelsDir = path.join(process.cwd(), 'src', 'models');
+    
+    // Only define target path if model name exists
+    this.targetPath = this.modelName 
+      ? path.join(this.modelsDir, `${this.modelName}.ts`) 
+      : '';
+  }
+
+  /**
+   * Main entry point to run the generator.
+   */
+  public run(): void {
+    if (!this.validateInput()) {
+      return;
+    }
+
+    if (this.modelExists()) {
+      Logger.error(`Model "${this.modelName}" already exists at src/models/${this.modelName}.ts`);
+      process.exit(1);
+    }
+
+    this.createFile();
+  }
+
+  /**
+   * Validates command line arguments.
+   */
+  private validateInput(): boolean {
+    if (!this.modelName) {
+      Logger.error('Please provide a model name.');
+      console.log('\nUsage: npm run make:model <ModelName>');
+      console.log('Example: npm run make:model Product\n');
+      process.exit(1);
+    }
+    return true;
+  }
+
+  /**
+   * Checks if the file already exists.
+   */
+  private modelExists(): boolean {
+    return fs.existsSync(this.targetPath);
+  }
+
+  /**
+   * Helper to capitalize the first letter of a string.
+   */
+  private formatName(str: string): string {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+  }
+
+  /**
+   * Helper to pluralize table name (User -> users).
+   */
+  private getTableName(): string {
+    return this.modelName.toLowerCase() + 's';
+  }
+
+  /**
+   * Reads stub, replaces placeholders, and writes the file.
+   */
+  private createFile(): void {
+    try {
+      // Read Stub
+      let content = fs.readFileSync(this.stubPath, 'utf-8');
+
+      // Replace Placeholders
+      const tableName = this.getTableName();
+      content = content.replace(/{{ModelName}}/g, this.modelName);
+      content = content.replace(/{{TableName}}/g, tableName);
+
+      // Write File
+      fs.writeFileSync(this.targetPath, content);
+
+      Logger.info(`Model Created: src/models/${this.modelName}.ts`);
+    } catch (error) {
+      Logger.error('Failed to create model:', error);
+      process.exit(1);
+    }
+  }
+}
+
+new ModelGenerator().run();

package/template/scripts/maintenance.ts

@@ -0,0 +1,73 @@
+import fs from 'fs';
+import path from 'path';
+import Logger from '../src/utils/Logger.js';
+
+class MaintenanceManager {
+  private lockFile: string;
+  private action: string;
+
+  constructor() {
+    this.lockFile = path.join(process.cwd(), 'maintenance.lock');
+    // Get the command line argument (e.g., 'up' or 'down')
+    this.action = process.argv[2];
+  }
+
+  /**
+   * The main entry point for the script.
+   */
+  public run(): void {
+    switch (this.action) {
+      case 'down':
+        this.enableMaintenance();
+        break;
+      case 'up':
+        this.disableMaintenance();
+        break;
+      default:
+        this.showUsage();
+        break;
+    }
+  }
+
+  /**
+   * Puts the application into maintenance mode.
+   */
+  private enableMaintenance(): void {
+    try {
+      fs.writeFileSync(this.lockFile, 'MAINTENANCE_MODE_ACTIVE');
+      Logger.info('Application is now in MAINTENANCE MODE (503).');
+      Logger.info('Run "npm run up" to bring it back online.');
+    } catch (error) {
+      Logger.error('Failed to enable maintenance mode:', error);
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Brings the application back online.
+   */
+  private disableMaintenance(): void {
+    try {
+      if (fs.existsSync(this.lockFile)) {
+        fs.unlinkSync(this.lockFile);
+        Logger.info('Application is now LIVE.');
+      } else {
+        Logger.warn('Application was already live.');
+      }
+    } catch (error) {
+      Logger.error('Failed to disable maintenance mode:', error);
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Shows help instructions.
+   */
+  private showUsage(): void {
+    Logger.info('\nUsage:');
+    Logger.info('  npm run down  -> Put server in maintenance mode');
+    Logger.info('  npm run up    -> Bring server back online\n');
+  }
+}
+
+new MaintenanceManager().run();