@xbg.solutions/create-backend 1.0.0

package/src/project-template/__scripts__/validate.js

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+
+/**
+ * Configuration Validation Script
+ * Validates that the backend project is properly configured
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  blue: '\x1b[34m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m',
+};
+
+const CHECK_MARK = '✓';
+const CROSS_MARK = '✗';
+const WARNING_MARK = '⚠';
+
+let errors = 0;
+let warnings = 0;
+let checks = 0;
+
+function printHeader(title) {
+  console.log(`\n${colors.bright}${colors.blue}${title}${colors.reset}`);
+  console.log(`${colors.dim}${'─'.repeat(60)}${colors.reset}`);
+}
+
+function printSuccess(message) {
+  checks++;
+  console.log(`${colors.green}${CHECK_MARK}${colors.reset} ${message}`);
+}
+
+function printWarning(message) {
+  checks++;
+  warnings++;
+  console.log(`${colors.yellow}${WARNING_MARK}${colors.reset} ${message}`);
+}
+
+function printError(message) {
+  checks++;
+  errors++;
+  console.log(`${colors.red}${CROSS_MARK}${colors.reset} ${message}`);
+}
+
+function fileExists(filePath) {
+  return fs.existsSync(path.join(__dirname, '..', filePath));
+}
+
+function readEnvFile() {
+  const envPath = path.join(__dirname, '../functions/.env');
+  if (!fs.existsSync(envPath)) {
+    return null;
+  }
+
+  const envContent = fs.readFileSync(envPath, 'utf8');
+  const env = {};
+
+  envContent.split('\n').forEach(line => {
+    const trimmed = line.trim();
+    if (trimmed && !trimmed.startsWith('#')) {
+      const [key, ...valueParts] = trimmed.split('=');
+      env[key.trim()] = valueParts.join('=').trim();
+    }
+  });
+
+  return env;
+}
+
+function checkCommand(command, name) {
+  try {
+    execSync(`which ${command}`, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function runCommand(command, cwd) {
+  try {
+    execSync(command, {
+      cwd: cwd || path.join(__dirname, '../functions'),
+      stdio: 'pipe',
+      encoding: 'utf8',
+    });
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+console.log(`
+${colors.bright}${colors.blue}╔════════════════════════════════════════════════════════════╗
+║                                                            ║
+║   🔍 Backend Boilerplate Validation                       ║
+║                                                            ║
+╚════════════════════════════════════════════════════════════╝${colors.reset}
+`);
+
+// Check prerequisites
+printHeader('Prerequisites');
+
+if (checkCommand('node', 'Node.js')) {
+  const nodeVersion = execSync('node --version', { encoding: 'utf8' }).trim();
+  printSuccess(`Node.js installed (${nodeVersion})`);
+
+  // Check Node.js version
+  const majorVersion = parseInt(nodeVersion.slice(1).split('.')[0]);
+  if (majorVersion < 22) {
+    printWarning(`Node.js version ${nodeVersion} is below recommended 22+`);
+  }
+} else {
+  printError('Node.js not found - install from https://nodejs.org');
+}
+
+if (checkCommand('npm', 'npm')) {
+  const npmVersion = execSync('npm --version', { encoding: 'utf8' }).trim();
+  printSuccess(`npm installed (v${npmVersion})`);
+} else {
+  printError('npm not found');
+}
+
+if (checkCommand('firebase', 'Firebase CLI')) {
+  const firebaseVersion = execSync('firebase --version', { encoding: 'utf8' }).trim();
+  printSuccess(`Firebase CLI installed (${firebaseVersion})`);
+} else {
+  printWarning('Firebase CLI not found - install with: npm install -g firebase-tools');
+}
+
+// Check project structure
+printHeader('Project Structure');
+
+const requiredFiles = [
+  'functions/package.json',
+  'functions/tsconfig.json',
+  'functions/src/index.ts',
+  'firebase.json',
+  '.firebaserc',
+];
+
+requiredFiles.forEach(file => {
+  if (fileExists(file)) {
+    printSuccess(`Found ${file}`);
+  } else {
+    printError(`Missing required file: ${file}`);
+  }
+});
+
+const requiredDirs = [
+  'functions/src/config',
+  'functions/src/base',
+  'functions/src/middleware',
+  'functions/src/utilities',
+  '__scripts__',
+  '__docs__',
+  '__examples__',
+];
+
+requiredDirs.forEach(dir => {
+  if (fileExists(dir)) {
+    printSuccess(`Found directory: ${dir}`);
+  } else {
+    printWarning(`Directory not found: ${dir}`);
+  }
+});
+
+// Check environment configuration
+printHeader('Environment Configuration');
+
+const env = readEnvFile();
+
+if (env) {
+  printSuccess('.env file exists');
+
+  // Check for required environment variables
+  const requiredVars = [
+    'APP_NAME',
+    'NODE_ENV',
+    'FIREBASE_PROJECT_ID',
+    'API_BASE_PATH',
+  ];
+
+  const optionalVars = [
+    'CORS_ORIGINS',
+    'LOG_LEVEL',
+    'RATE_LIMIT_ENABLED',
+  ];
+
+  requiredVars.forEach(varName => {
+    if (env[varName]) {
+      if (env[varName].includes('FIXME') || env[varName].includes('your-')) {
+        printWarning(`${varName} is set but contains placeholder value`);
+      } else {
+        printSuccess(`${varName} is configured`);
+      }
+    } else {
+      printError(`Missing required environment variable: ${varName}`);
+    }
+  });
+
+  optionalVars.forEach(varName => {
+    if (env[varName]) {
+      printSuccess(`${varName} is configured`);
+    } else {
+      printWarning(`Optional variable ${varName} not set`);
+    }
+  });
+
+} else {
+  printError('.env file not found - run: npm run setup');
+}
+
+// Check dependencies
+printHeader('Dependencies');
+
+const packageJsonPath = path.join(__dirname, '../functions/package.json');
+if (fs.existsSync(packageJsonPath)) {
+  printSuccess('package.json found');
+
+  const nodeModulesPath = path.join(__dirname, '../functions/node_modules');
+  if (fs.existsSync(nodeModulesPath)) {
+    printSuccess('node_modules directory exists');
+  } else {
+    printError('node_modules not found - run: npm install');
+  }
+} else {
+  printError('package.json not found');
+}
+
+// Check TypeScript compilation
+printHeader('TypeScript Compilation');
+
+console.log(`${colors.dim}Running TypeScript compiler check...${colors.reset}`);
+if (runCommand('npx tsc --noEmit')) {
+  printSuccess('TypeScript compilation check passed');
+} else {
+  printWarning('TypeScript compilation has errors - run: npm run build');
+}
+
+// Check linting (if requested)
+const skipLint = process.argv.includes('--skip-lint');
+if (!skipLint) {
+  printHeader('Code Quality');
+
+  console.log(`${colors.dim}Running ESLint...${colors.reset}`);
+  if (runCommand('npm run lint')) {
+    printSuccess('ESLint passed');
+  } else {
+    printWarning('ESLint found issues - run: npm run lint:fix');
+  }
+}
+
+// Check tests (if requested)
+const skipTests = process.argv.includes('--skip-tests');
+if (!skipTests) {
+  printHeader('Tests');
+
+  console.log(`${colors.dim}Running test suite...${colors.reset}`);
+  if (runCommand('npm test')) {
+    printSuccess('All tests passed');
+  } else {
+    printError('Some tests failed - run: npm test');
+  }
+}
+
+// Check build (if requested)
+const skipBuild = process.argv.includes('--skip-build');
+if (!skipBuild) {
+  printHeader('Build');
+
+  console.log(`${colors.dim}Running production build...${colors.reset}`);
+  if (runCommand('npm run build')) {
+    printSuccess('Production build succeeded');
+  } else {
+    printError('Build failed - check TypeScript errors');
+  }
+}
+
+// Firebase configuration
+printHeader('Firebase Configuration');
+
+const firebaseRcPath = path.join(__dirname, '../.firebaserc');
+if (fs.existsSync(firebaseRcPath)) {
+  try {
+    const firebaseRc = JSON.parse(fs.readFileSync(firebaseRcPath, 'utf8'));
+    if (firebaseRc.projects && firebaseRc.projects.default) {
+      printSuccess(`Firebase project: ${firebaseRc.projects.default}`);
+    } else {
+      printWarning('Firebase project not configured in .firebaserc');
+    }
+  } catch {
+    printError('Could not parse .firebaserc file');
+  }
+} else {
+  printError('.firebaserc not found - run: firebase init');
+}
+
+// Summary
+printHeader('Summary');
+
+console.log(`
+${colors.bright}Validation Results:${colors.reset}
+  ${colors.green}${CHECK_MARK} ${checks - errors - warnings} checks passed${colors.reset}
+  ${warnings > 0 ? `${colors.yellow}${WARNING_MARK} ${warnings} warnings${colors.reset}` : ''}
+  ${errors > 0 ? `${colors.red}${CROSS_MARK} ${errors} errors${colors.reset}` : ''}
+`);
+
+if (errors === 0 && warnings === 0) {
+  console.log(`${colors.green}${colors.bright}✨ All checks passed! Your project is properly configured.${colors.reset}\n`);
+  process.exit(0);
+} else if (errors === 0) {
+  console.log(`${colors.yellow}${colors.bright}⚠️  Validation completed with warnings. Review warnings above.${colors.reset}\n`);
+  process.exit(0);
+} else {
+  console.log(`${colors.red}${colors.bright}❌ Validation failed. Fix the errors above before proceeding.${colors.reset}\n`);
+  console.log(`${colors.dim}Tip: Run ${colors.bright}npm run setup${colors.reset}${colors.dim} to configure the project automatically.${colors.reset}\n`);
+  process.exit(1);
+}

package/src/project-template/firebase.json

@@ -0,0 +1,32 @@
+{
+  "firestore": {
+    "rules": "firestore.rules"
+  },
+  "functions": {
+    "source": "functions",
+    "runtime": "nodejs22",
+    "ignore": [
+      "node_modules",
+      ".git",
+      "firebase-debug.log",
+      "firebase-debug.*.log"
+    ],
+    "predeploy": [
+      "npm --prefix \"$RESOURCE_DIR\" run lint",
+      "npm --prefix \"$RESOURCE_DIR\" run build"
+    ]
+  },
+  "emulators": {
+    "functions": {
+      "port": 5001
+    },
+    "firestore": {
+      "port": 8080
+    },
+    "ui": {
+      "enabled": true,
+      "port": 4000
+    },
+    "singleProjectMode": true
+  }
+}

package/src/project-template/firestore.rules

@@ -0,0 +1,12 @@
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    // Deny all client SDK access by default.
+    // This backend uses the Admin SDK (which bypasses rules).
+    // These rules act as defense-in-depth against accidental
+    // client-side database exposure.
+    match /{document=**} {
+      allow read, write: if false;
+    }
+  }
+}

package/src/project-template/functions/jest.config.js

@@ -0,0 +1,49 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src'],
+  testMatch: [
+    '**/__tests__/**/*.test.ts',
+    '**/?(*.)+(spec|test).ts'
+  ],
+  transform: {
+    '^.+\\.ts$': 'ts-jest',
+  },
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts',
+    '!src/**/__tests__/**',
+    '!src/index.ts',
+    '!src/server.ts',
+    '!src/generated/**',
+  ],
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov', 'html'],
+  coverageThreshold: {
+    global: {
+      branches: 70,
+      functions: 70,
+      lines: 70,
+      statements: 70,
+    },
+  },
+  setupFilesAfterEnv: ['<rootDir>/src/__tests__/setup.ts'],
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/src/$1',
+    '^@utilities/(.*)$': '<rootDir>/src/utilities/$1',
+    '^@base/(.*)$': '<rootDir>/src/base/$1',
+    '^@middleware/(.*)$': '<rootDir>/src/middleware/$1',
+    '^@config/(.*)$': '<rootDir>/src/config/$1',
+    '^@generated/(.*)$': '<rootDir>/src/generated/$1',
+  },
+  globals: {
+    'ts-jest': {
+      tsconfig: {
+        esModuleInterop: true,
+        allowSyntheticDefaultImports: true,
+      },
+    },
+  },
+  testTimeout: 10000,
+  verbose: true,
+};

package/src/project-template/functions/src/index.ts

@@ -0,0 +1,46 @@
+/**
+ * Firebase Functions Entry Point
+ * Exports HTTP functions for Firebase deployment
+ */
+
+import * as functions from 'firebase-functions';
+import { createApp } from '@xbg/backend-core';
+import { logger } from '@xbg/utils-logger';
+
+// Import controllers here as they are created
+// import { UserController } from './generated/controllers/UserController';
+
+/**
+ * Initialize controllers
+ * Add your generated or custom controllers here
+ */
+function initializeControllers(): Array<{ getRouter: () => any; getBasePath: () => string }> {
+  const controllers: Array<{ getRouter: () => any; getBasePath: () => string }> = [];
+
+  // Example:
+  // const userController = new UserController(userService, '/users');
+  // controllers.push(userController);
+
+  return controllers;
+}
+
+/**
+ * Create Express app with controllers
+ */
+const expressApp = createApp({
+  controllers: initializeControllers(),
+});
+
+/**
+ * Export as Firebase HTTPS Function
+ */
+export const api = functions.https.onRequest(expressApp);
+
+/**
+ * Export for local development
+ */
+export { expressApp };
+
+logger.info('Firebase Functions initialized', {
+  environment: process.env.NODE_ENV || 'development',
+});

package/src/project-template/functions/tsconfig.json

@@ -0,0 +1,38 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "noImplicitReturns": true,
+    "noUnusedLocals": true,
+    "outDir": "lib",
+    "sourceMap": true,
+    "strict": true,
+    "target": "es2017",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "forceConsistentCasingInFileNames": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictBindCallApply": true,
+    "strictPropertyInitialization": true,
+    "noImplicitThis": true,
+    "alwaysStrict": true,
+    "noFallthroughCasesInSwitch": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "baseUrl": "."
+  },
+  "compileOnSave": true,
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "**/*.spec.ts",
+    "**/*.test.ts"
+  ]
+}