create-rebe 1.0.0

package/template/package.json

@@ -0,0 +1,82 @@
+{
+    "name": "rebe",
+    "version": "1.0.0",
+    "description": "Ready-to-use Node.js backend framework. One process serves a JSON API, Socket.IO, cron jobs, and an in-process queue on a layered config/core/app architecture, with JWT auth, Sequelize, Winston logging, and centralized configuration.",
+    "license": "MIT",
+    "author": "Refkinscallv <refkinscallv@gmail.com>",
+    "type": "commonjs",
+    "main": "index.js",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/refkinscallv/rebe.git"
+    },
+    "bugs": {
+        "url": "https://github.com/refkinscallv/rebe/issues"
+    },
+    "homepage": "https://github.com/refkinscallv/rebe#readme",
+    "engines": {
+        "node": ">=20.9.0"
+    },
+    "keywords": [
+        "rebe",
+        "backend",
+        "framework",
+        "boilerplate",
+        "express",
+        "socket.io",
+        "cron",
+        "queue",
+        "jwt",
+        "sequelize"
+    ],
+    "scripts": {
+        "test": "jest",
+        "test:watch": "jest --watch",
+        "test:coverage": "jest --coverage",
+        "cli": "node ./scripts/cli.js",
+        "start": "node .",
+        "dev": "nodemon",
+        "format": "prettier --write ."
+    },
+    "_moduleAliases": {
+        "@config": "config",
+        "@core": "core",
+        "@app": "app",
+        "@http": "app/http",
+        "@routes": "app/routes",
+        "@jobs": "app/jobs",
+        "@queue": "app/queue",
+        "@socket": "app/socket",
+        "@hooks": "app/hooks",
+        "@database": "database",
+        "@storage": "storage"
+    },
+    "devDependencies": {
+        "jest": "^30.4.2",
+        "nodemon": "^3.1.14",
+        "prettier": "^3.8.4"
+    },
+    "dependencies": {
+        "@refkinscallv/express-routing": "^3.2.0",
+        "axios": "^1.17.0",
+        "bcrypt": "^6.0.0",
+        "compression": "^1.8.1",
+        "cors": "^2.8.6",
+        "dotenv": "^17.4.2",
+        "express": "^5.2.1",
+        "express-rate-limit": "^8.5.2",
+        "helmet": "^8.2.0",
+        "ioredis": "^5.11.1",
+        "jsonwebtoken": "^9.0.3",
+        "module-alias": "^2.3.4",
+        "multer": "^2.1.1",
+        "mysql2": "^3.22.5",
+        "node-cron": "^4.2.1",
+        "nodemailer": "^8.0.10",
+        "sequelize": "^6.37.8",
+        "socket.io": "^4.8.3",
+        "winston": "^3.19.0",
+        "winston-daily-rotate-file": "^5.0.0",
+        "zod": "^4.4.3"
+    }
+}

package/template/scripts/cli.js

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+
+'use strict'
+
+require('dotenv').config()
+
+const fs = require('fs')
+const path = require('path')
+const crypto = require('crypto')
+const { execSync } = require('child_process')
+
+// Display name is driven by APP_NAME (no hardcoded brand). Falls back to 'rebe'
+// when .env is not present yet (e.g. before `setup`).
+const APP_NAME = (process.env.APP_NAME || 'rebe').toUpperCase()
+
+class Log {
+	static colors = {
+		reset: '\x1b[0m',
+		red: '\x1b[31m',
+		green: '\x1b[32m',
+		yellow: '\x1b[33m',
+		blue: '\x1b[34m',
+		cyan: '\x1b[36m',
+		white: '\x1b[37m',
+		gray: '\x1b[90m',
+	}
+
+	static color(color, message) {
+		return `${this.colors[color]}${message}${this.colors.reset}`
+	}
+
+	static info(message) {
+		console.log(this.color('blue', `[INFO] ${message}`))
+	}
+
+	static success(message) {
+		console.log(this.color('green', `[ OK ] ${message}`))
+	}
+
+	static warn(message) {
+		console.log(this.color('yellow', `[WARN] ${message}`))
+	}
+
+	static error(message) {
+		console.log(this.color('red', `[FAIL] ${message}`))
+	}
+
+	static line() {
+		console.log(this.color('gray', '────────────────────────────────────────'))
+	}
+
+	static banner() {
+		const width = 38
+		const title = `${APP_NAME} CLI`
+		const padTotal = Math.max(0, width - title.length)
+		const left = Math.floor(padTotal / 2)
+		const centered = ' '.repeat(left) + title + ' '.repeat(padTotal - left)
+
+		console.log()
+		console.log(this.color('cyan', `╔${'═'.repeat(width)}╗`))
+		console.log(this.color('cyan', `║${centered}║`))
+		console.log(this.color('cyan', `╚${'═'.repeat(width)}╝`))
+		console.log()
+	}
+}
+
+const command = process.argv[2]
+const args = process.argv.slice(3)
+
+function generateKey(bytes = 32) {
+	return crypto.randomBytes(bytes).toString('hex')
+}
+
+function getEnvPath() {
+	return path.join(process.cwd(), '.env')
+}
+
+function updateEnv(key, value) {
+	const envPath = getEnvPath()
+
+	if (!fs.existsSync(envPath)) {
+		Log.error('.env file not found')
+		process.exit(1)
+	}
+
+	let content = fs.readFileSync(envPath, 'utf8')
+
+	const regex = new RegExp(`^${key}=.*$`, 'm')
+
+	if (regex.test(content)) {
+		content = content.replace(regex, `${key}=${value}`)
+	} else {
+		content += `\n${key}=${value}`
+	}
+
+	fs.writeFileSync(envPath, content)
+
+	return value
+}
+
+function help() {
+	Log.banner()
+
+	console.log(Log.color('yellow', 'Usage'))
+	Log.line()
+
+	console.log('  npm run cli -- setup')
+	console.log('  npm run cli -- help')
+	console.log('  npm run cli -- key:generate')
+	console.log('  npm run cli -- key:jwt')
+	console.log('  npm run cli -- key:jwt --refresh')
+
+	console.log()
+
+	console.log(Log.color('yellow', 'Commands'))
+	Log.line()
+
+	console.log('  setup')
+	console.log(Log.color('gray', '      Initialize project'))
+
+	console.log()
+
+	console.log('  help')
+	console.log(Log.color('gray', '      Show help information'))
+
+	console.log()
+
+	console.log('  key:generate')
+	console.log(Log.color('gray', '      Generate APP_KEY'))
+
+	console.log()
+
+	console.log('  key:jwt')
+	console.log(Log.color('gray', '      Generate JWT_SECRET'))
+
+	console.log()
+
+	console.log('  key:jwt --refresh')
+	console.log(Log.color('gray', '      Generate JWT_REFRESH_SECRET'))
+
+	console.log()
+}
+
+function setup() {
+	Log.banner()
+
+	const examplePath = path.join(process.cwd(), '.env.example')
+	const envPath = path.join(process.cwd(), '.env')
+
+	if (!fs.existsSync(examplePath)) {
+		Log.error('.env.example not found')
+		process.exit(1)
+	}
+
+	if (!fs.existsSync(envPath)) {
+		fs.copyFileSync(examplePath, envPath)
+		Log.success('.env created')
+	} else {
+		Log.warn('.env already exists')
+	}
+
+	try {
+		Log.info('Updating package.json dependencies...')
+		execSync('npx npm-check-updates -u', {
+			stdio: 'inherit',
+		})
+
+		Log.info('Installing dependencies...')
+		execSync('npm install', {
+			stdio: 'inherit',
+		})
+
+		generateAppKey()
+		generateJwtSecret()
+		generateJwtRefreshSecret()
+
+		Log.success('Setup completed')
+	} catch (error) {
+		Log.error(error.message)
+		process.exit(1)
+	}
+}
+
+function generateAppKey() {
+	Log.banner()
+
+	const key = generateKey(32)
+
+	updateEnv('APP_KEY', key)
+
+	Log.success('APP_KEY generated')
+	console.log()
+	console.log(Log.color('cyan', key))
+	console.log()
+}
+
+function generateJwtSecret() {
+	Log.banner()
+
+	const key = generateKey(64)
+
+	updateEnv('JWT_SECRET', key)
+
+	Log.success('JWT_SECRET generated')
+	console.log()
+	console.log(Log.color('cyan', key))
+	console.log()
+}
+
+function generateJwtRefreshSecret() {
+	Log.banner()
+
+	const key = generateKey(64)
+
+	updateEnv('JWT_REFRESH_SECRET', key)
+
+	Log.success('JWT_REFRESH_SECRET generated')
+	console.log()
+	console.log(Log.color('cyan', key))
+	console.log()
+}
+
+switch (command) {
+	case undefined:
+	case 'help': {
+		help()
+		break
+	}
+
+	case 'setup': {
+		setup()
+		break
+	}
+
+	case 'key:generate': {
+		generateAppKey()
+		break
+	}
+
+	case 'key:jwt': {
+		if (args.includes('--refresh')) {
+			generateJwtRefreshSecret()
+		} else {
+			generateJwtSecret()
+		}
+
+		break
+	}
+
+	default: {
+		Log.banner()
+		Log.error(`Unknown command '${command}'`)
+		console.log()
+		Log.info(`Run: npm run cli -- help`)
+		console.log()
+		process.exit(1)
+	}
+}

package/template/tests/common.test.js

@@ -0,0 +1,45 @@
+'use strict'
+
+const Common = require('@core/common.core')
+
+describe('Common env readers', () => {
+	test('getEnvBool parses truthy and falls back', () => {
+		process.env.X_BOOL = 'yes'
+		expect(Common.getEnvBool('X_BOOL')).toBe(true)
+		expect(Common.getEnvBool('X_MISSING', false)).toBe(false)
+	})
+
+	test('getEnvInt parses and falls back on non-numeric', () => {
+		process.env.X_INT = '42'
+		expect(Common.getEnvInt('X_INT')).toBe(42)
+		process.env.X_INT = 'nope'
+		expect(Common.getEnvInt('X_INT', 7)).toBe(7)
+	})
+
+	test('getEnvArray trims and drops empties', () => {
+		process.env.X_ARR = 'a, b ,c,'
+		expect(Common.getEnvArray('X_ARR')).toEqual(['a', 'b', 'c'])
+	})
+})
+
+describe('Common helpers', () => {
+	test('isEmpty', () => {
+		expect(Common.isEmpty('')).toBe(true)
+		expect(Common.isEmpty([])).toBe(true)
+		expect(Common.isEmpty({})).toBe(true)
+		expect(Common.isEmpty([1])).toBe(false)
+		expect(Common.isEmpty('x')).toBe(false)
+	})
+
+	test('attempt returns [err, result]', async () => {
+		const [e1, r1] = await Common.attempt(() => 5)
+		expect(e1).toBeNull()
+		expect(r1).toBe(5)
+
+		const [e2, r2] = await Common.attempt(() => {
+			throw new Error('boom')
+		})
+		expect(e2).toBeInstanceOf(Error)
+		expect(r2).toBeNull()
+	})
+})

package/template/tests/crypt-hash-storage.test.js

@@ -0,0 +1,44 @@
+'use strict'
+
+const Common = require('@core/common.core')
+
+describe('Crypt', () => {
+	test('encrypt/decrypt roundtrip for strings and objects', () => {
+		const enc = Common.Crypt.encrypt('hello')
+		expect(Common.Crypt.decrypt(enc)).toBe('hello')
+
+		const encObj = Common.Crypt.encrypt({ a: 1, b: 'two' })
+		expect(Common.Crypt.decrypt(encObj, true)).toEqual({ a: 1, b: 'two' })
+	})
+
+	test('tampered ciphertext fails authentication', () => {
+		const enc = Common.Crypt.encrypt('hello')
+		const tampered = Buffer.from(enc, 'base64')
+		tampered[tampered.length - 1] ^= 0xff
+		expect(() => Common.Crypt.decrypt(tampered.toString('base64'))).toThrow()
+	})
+})
+
+describe('Hash', () => {
+	test('make/check bcrypt', async () => {
+		const hashed = await Common.Hash.make('password123')
+		expect(await Common.Hash.check('password123', hashed)).toBe(true)
+		expect(await Common.Hash.check('wrong', hashed)).toBe(false)
+	})
+
+	test('equals is constant-time and length-aware', () => {
+		expect(Common.Hash.equals('abc', 'abc')).toBe(true)
+		expect(Common.Hash.equals('abc', 'abd')).toBe(false)
+		expect(Common.Hash.equals('abc', 'abcd')).toBe(false)
+	})
+})
+
+describe('Storage', () => {
+	test('path stays inside the storage root', () => {
+		expect(Common.Storage.path('uploads/file.txt')).toContain('storage')
+	})
+
+	test('rejects path traversal', () => {
+		expect(() => Common.Storage.path('../../etc/passwd')).toThrow()
+	})
+})

package/template/tests/jwt.test.js

@@ -0,0 +1,45 @@
+'use strict'
+
+const Jwt = require('@core/jwt.core')
+
+describe('Jwt', () => {
+	test('sign/verify roundtrip', () => {
+		const token = Jwt.sign({ sub: 1, role: 'admin' })
+		const payload = Jwt.verify(token)
+		expect(payload.sub).toBe(1)
+		expect(payload.role).toBe('admin')
+	})
+
+	test('tryVerify reports invalid tokens without throwing', () => {
+		const result = Jwt.tryVerify('not.a.real.token')
+		expect(result.valid).toBe(false)
+		expect(result.payload).toBeNull()
+		expect(result.error).toBeInstanceOf(Error)
+	})
+
+	test('fromHeader extracts a bearer token', () => {
+		expect(Jwt.fromHeader('Bearer abc.def')).toBe('abc.def')
+		expect(Jwt.fromHeader('bearer xyz')).toBe('xyz')
+		expect(Jwt.fromHeader('Basic abc')).toBeNull()
+		expect(Jwt.fromHeader(undefined)).toBeNull()
+	})
+
+	test('issue returns an access + refresh pair', () => {
+		const issued = Jwt.issue({ sub: 7 })
+		expect(issued.tokenType).toBe('Bearer')
+		expect(typeof issued.accessToken).toBe('string')
+		expect(Jwt.verify(issued.accessToken).sub).toBe(7)
+		expect(Jwt.verifyRefresh(issued.refreshToken).sub).toBe(7)
+	})
+
+	test('expiresAt / isExpired', () => {
+		const token = Jwt.sign({ sub: 1 })
+		expect(Jwt.expiresAt(token)).toBeInstanceOf(Date)
+		expect(Jwt.isExpired(token)).toBe(false)
+	})
+
+	test('the access secret does not verify a refresh token', () => {
+		const issued = Jwt.issue({ sub: 1 })
+		expect(() => Jwt.verify(issued.refreshToken)).toThrow()
+	})
+})

package/template/tests/register.test.js

@@ -0,0 +1,55 @@
+'use strict'
+
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+const Register = require('@core/register.core')
+
+function tempModule(content) {
+	const file = path.join(os.tmpdir(), `rebe-reg-${Date.now()}-${Math.random().toString(16).slice(2)}.js`)
+	fs.writeFileSync(file, content)
+	return file
+}
+
+describe('Register', () => {
+	test('path resolves under the project root', () => {
+		expect(Register.path('app', 'jobs', 'register.job.js')).toBe(path.resolve(process.cwd(), 'app', 'jobs', 'register.job.js'))
+	})
+
+	test('require returns null for a missing optional file', () => {
+		expect(Register.require(path.join(os.tmpdir(), 'definitely-missing-xyz.js'))).toBeNull()
+	})
+
+	test('require throws for a missing required file', () => {
+		expect(() => Register.require(path.join(os.tmpdir(), 'missing-required.js'), { optional: false })).toThrow()
+	})
+
+	test('invoke calls a function export with args', async () => {
+		const file = tempModule('module.exports = (x) => x * 2')
+		await expect(Register.invoke(file, [21])).resolves.toBe(42)
+		fs.unlinkSync(file)
+	})
+
+	test('invoke supports the { register } shape', async () => {
+		const file = tempModule('module.exports = { register: (x) => x + 1 }')
+		await expect(Register.invoke(file, [41])).resolves.toBe(42)
+		fs.unlinkSync(file)
+	})
+
+	test('invoke rejects an invalid export shape', async () => {
+		const file = tempModule('module.exports = 123')
+		await expect(Register.invoke(file)).rejects.toThrow()
+		fs.unlinkSync(file)
+	})
+
+	test('object validates handler keys are functions', () => {
+		const ok = tempModule('module.exports = { before: () => {}, after: () => {} }')
+		expect(Register.object(ok, ['before', 'after', 'shutdown'])).toBeTruthy()
+		fs.unlinkSync(ok)
+
+		const bad = tempModule('module.exports = { before: 5 }')
+		expect(() => Register.object(bad, ['before'])).toThrow()
+		fs.unlinkSync(bad)
+	})
+})

package/template/tests/setup.js

@@ -0,0 +1,11 @@
+'use strict'
+
+// Deterministic environment for the test run. Set before any config/core module is
+// required (setupFiles runs before the test files load). Independent of .env.
+process.env.APP_ENV = process.env.APP_ENV || 'test'
+process.env.APP_NAME = process.env.APP_NAME || 'TestApp'
+process.env.APP_KEY = process.env.APP_KEY || 'test_app_key_0123456789abcdef0123456789abcdef'
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'test_jwt_secret_value'
+process.env.JWT_REFRESH_SECRET = process.env.JWT_REFRESH_SECRET || 'test_jwt_refresh_secret_value'
+process.env.BCRYPT_SALT_ROUNDS = process.env.BCRYPT_SALT_ROUNDS || '4'
+process.env.LOG_LEVEL = process.env.LOG_LEVEL || 'error'

package/template/tests/validator.test.js

@@ -0,0 +1,65 @@
+'use strict'
+
+const { z } = require('zod')
+const Validator = require('@core/validator.core')
+
+function mockRes() {
+	return {
+		statusCode: 200,
+		body: null,
+		status(code) {
+			this.statusCode = code
+			return this
+		},
+		json(body) {
+			this.body = body
+			return this
+		},
+	}
+}
+
+describe('Validator.make', () => {
+	const schema = z.object({ email: z.string().email(), password: z.string().min(6) })
+
+	test('passes valid input, strips unknown keys, replaces req.body', () => {
+		const req = { body: { email: 'a@b.com', password: 'secret1', extra: 'drop-me' } }
+		const res = mockRes()
+		let nextCalled = false
+
+		Validator.make(schema).handle({ req, res, next: () => (nextCalled = true) })
+
+		expect(nextCalled).toBe(true)
+		expect(req.body).toEqual({ email: 'a@b.com', password: 'secret1' })
+		expect(req.validated.body).toEqual({ email: 'a@b.com', password: 'secret1' })
+	})
+
+	test('rejects invalid input with the 422 envelope', () => {
+		const req = { body: { email: 'nope', password: '1' } }
+		const res = mockRes()
+
+		Validator.make(schema).handle({
+			req,
+			res,
+			next: () => {
+				throw new Error('next must not be called on validation failure')
+			},
+		})
+
+		expect(res.statusCode).toBe(422)
+		expect(res.body.status).toBe(false)
+		expect(res.body.code).toBe(422)
+		expect(Array.isArray(res.body.errors)).toBe(true)
+		expect(res.body.errors.map((e) => e.field)).toEqual(expect.arrayContaining(['email', 'password']))
+	})
+
+	test('validates a non-body source without mutating req.body', () => {
+		const querySchema = z.object({ page: z.coerce.number() })
+		const req = { query: { page: '3' }, body: { keep: true } }
+		const res = mockRes()
+
+		Validator.make(querySchema, 'query').handle({ req, res, next: () => {} })
+
+		expect(req.validated.query).toEqual({ page: 3 })
+		expect(req.body).toEqual({ keep: true })
+	})
+})