@xbg.solutions/create-backend 1.0.0

package/src/project-template/__examples__/user.model.ts

@@ -0,0 +1,221 @@
+/**
+ * Example Data Model: User Management
+ * This demonstrates how to define entities for code generation
+ */
+
+import { DataModelSpecification } from '../functions/src/generator/types';
+
+export const UserManagementModel: DataModelSpecification = {
+  entities: {
+    User: {
+      description: 'Application user with authentication and profile',
+
+      fields: {
+        userUID: {
+          type: 'uuid',
+          primaryKey: true,
+          generated: true,
+          description: 'Unique user identifier',
+        },
+        email: {
+          type: 'email',
+          unique: true,
+          required: true,
+          description: 'User email address',
+        },
+        displayName: {
+          type: 'string',
+          required: false,
+          maxLength: 100,
+          description: 'User display name',
+        },
+        role: {
+          type: 'enum',
+          values: ['admin', 'member', 'guest'],
+          default: 'member',
+          required: true,
+          description: 'User role for access control',
+        },
+        isActive: {
+          type: 'boolean',
+          default: true,
+          required: true,
+          description: 'Whether user account is active',
+        },
+        emailVerified: {
+          type: 'boolean',
+          default: false,
+          required: true,
+          description: 'Whether email has been verified',
+        },
+        lastLoginAt: {
+          type: 'timestamp',
+          nullable: true,
+          description: 'Last login timestamp',
+        },
+        profileImageUrl: {
+          type: 'url',
+          nullable: true,
+          description: 'URL to profile image',
+        },
+      },
+
+      relationships: {
+        organizations: {
+          type: 'many-to-many',
+          entity: 'Organization',
+          through: 'UserOrganization',
+          cascadeDelete: false,
+          description: 'Organizations the user belongs to',
+        },
+        createdLists: {
+          type: 'one-to-many',
+          entity: 'List',
+          foreignKey: 'ownerUID',
+          cascadeDelete: true,
+          description: 'Lists created by the user',
+        },
+      },
+
+      access: {
+        create: ['public'], // Anyone can register
+        read: ['self', 'admin', 'organization-member'],
+        update: ['self', 'admin'],
+        delete: ['admin'],
+      },
+
+      validation: {
+        email: 'Must be unique valid email address',
+        role: 'Members cannot promote themselves to admin',
+        displayName: 'Must be alphanumeric with spaces, max 100 characters',
+      },
+
+      indexes: [
+        { fields: ['email'], unique: true },
+        { fields: ['role', 'isActive'] },
+        { fields: ['createdAt'] },
+      ],
+
+      businessRules: [
+        'Email must be verified before account activation',
+        'Deleted users retain data for 30 days (soft delete)',
+        'Admin role requires two-factor authentication',
+        'Users must have at least one active organization',
+      ],
+    },
+
+    Organization: {
+      description: 'Organization or team entity',
+
+      fields: {
+        organizationUID: {
+          type: 'uuid',
+          primaryKey: true,
+          generated: true,
+        },
+        name: {
+          type: 'string',
+          required: true,
+          minLength: 2,
+          maxLength: 100,
+        },
+        slug: {
+          type: 'string',
+          unique: true,
+          required: true,
+          pattern: '^[a-z0-9-]+$',
+        },
+        description: {
+          type: 'string',
+          nullable: true,
+          maxLength: 500,
+        },
+        ownerUID: {
+          type: 'reference',
+          required: true,
+          description: 'Reference to User who owns this organization',
+        },
+        isActive: {
+          type: 'boolean',
+          default: true,
+        },
+      },
+
+      relationships: {
+        members: {
+          type: 'many-to-many',
+          entity: 'User',
+          through: 'UserOrganization',
+          cascadeDelete: false,
+        },
+        owner: {
+          type: 'many-to-one',
+          entity: 'User',
+          foreignKey: 'ownerUID',
+        },
+      },
+
+      access: {
+        create: ['authenticated'],
+        read: ['member', 'admin'],
+        update: ['owner', 'admin'],
+        delete: ['owner', 'admin'],
+      },
+
+      validation: {
+        slug: 'Must be unique URL-safe identifier',
+        name: 'Must be unique within user account',
+      },
+
+      indexes: [
+        { fields: ['slug'], unique: true },
+        { fields: ['ownerUID'] },
+        { fields: ['isActive'] },
+      ],
+
+      businessRules: [
+        'Organization slug must be unique globally',
+        'Owner cannot leave their own organization',
+        'Deleting organization removes all member associations',
+      ],
+    },
+  },
+
+  workflows: {
+    userRegistration: {
+      trigger: 'USER_CREATED',
+      description: 'Handle new user registration',
+      steps: [
+        'sendVerificationEmail',
+        'createDefaultPreferences',
+        'trackRegistrationEvent',
+        'assignDefaultRole',
+      ],
+      conditions: {
+        sendVerificationEmail: 'email is not verified',
+      },
+    },
+
+    organizationCreation: {
+      trigger: 'ORGANIZATION_CREATED',
+      description: 'Handle new organization creation',
+      steps: [
+        'addOwnerAsMember',
+        'createDefaultSettings',
+        'sendWelcomeEmail',
+      ],
+    },
+
+    accountDeletion: {
+      trigger: 'manual',
+      description: 'Handle user account deletion',
+      steps: [
+        'validatePermissions',
+        'exportUserData',
+        'softDeleteAccount',
+        'scheduleDataPurge',
+        'notifyAdministrators',
+      ],
+    },
+  },
+};

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

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+/**
+ * Deployment Script
+ * Automates Firebase Functions deployment with safety checks
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  green: '\x1b[32m',
+  blue: '\x1b[34m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+};
+
+console.log(`
+${colors.bright}${colors.blue}╔════════════════════════════════════════════════════════════╗
+║                                                            ║
+║   🚀 Backend Boilerplate Deployment                       ║
+║                                                            ║
+╚════════════════════════════════════════════════════════════╝${colors.reset}
+`);
+
+function runCommand(command, description) {
+  console.log(`${colors.blue}▶ ${description}...${colors.reset}`);
+  try {
+    execSync(command, {
+      cwd: path.join(__dirname, '../functions'),
+      stdio: 'inherit',
+    });
+    console.log(`${colors.green}✅ ${description} complete${colors.reset}\n`);
+    return true;
+  } catch (error) {
+    console.error(`${colors.red}❌ ${description} failed${colors.reset}\n`);
+    return false;
+  }
+}
+
+async function deploy() {
+  // Check environment
+  const envPath = path.join(__dirname, '../functions/.env');
+  if (!fs.existsSync(envPath)) {
+    console.error(`${colors.red}❌ .env file not found. Run 'npm run setup' first.${colors.reset}\n`);
+    process.exit(1);
+  }
+
+  // Run linter
+  if (!runCommand('npm run lint', 'Linting code')) {
+    console.error(`${colors.yellow}⚠️  Fix linting errors before deploying${colors.reset}\n`);
+    process.exit(1);
+  }
+
+  // Run build
+  if (!runCommand('npm run build', 'Building TypeScript')) {
+    console.error(`${colors.red}❌ Build failed. Cannot deploy.${colors.reset}\n`);
+    process.exit(1);
+  }
+
+  // Run tests (if they exist)
+  const testScript = path.join(__dirname, '../functions/package.json');
+  if (fs.existsSync(testScript)) {
+    const pkg = JSON.parse(fs.readFileSync(testScript, 'utf-8'));
+    if (pkg.scripts && pkg.scripts.test) {
+      console.log(`${colors.blue}▶ Running tests...${colors.reset}`);
+      try {
+        execSync('npm test', {
+          cwd: path.join(__dirname, '../functions'),
+          stdio: 'inherit',
+        });
+        console.log(`${colors.green}✅ Tests passed${colors.reset}\n`);
+      } catch (error) {
+        console.error(`${colors.red}❌ Tests failed${colors.reset}\n`);
+        const proceed = process.argv.includes('--force');
+        if (!proceed) {
+          console.log(`Use ${colors.yellow}--force${colors.reset} to deploy anyway\n`);
+          process.exit(1);
+        }
+      }
+    }
+  }
+
+  // Deploy to Firebase
+  console.log(`${colors.bright}${colors.blue}Deploying to Firebase...${colors.reset}\n`);
+
+  try {
+    execSync('firebase deploy --only functions', {
+      cwd: path.join(__dirname, '..'),
+      stdio: 'inherit',
+    });
+
+    console.log(`
+${colors.green}${colors.bright}✅ Deployment successful!${colors.reset}
+
+${colors.bright}Next steps:${colors.reset}
+  - Verify deployment in Firebase Console
+  - Test API endpoints
+  - Monitor logs with 'npm run logs'
+
+${colors.green}🎉 Your backend is live!${colors.reset}
+`);
+  } catch (error) {
+    console.error(`\n${colors.red}❌ Deployment failed${colors.reset}\n`);
+    process.exit(1);
+  }
+}
+
+deploy().catch((error) => {
+  console.error(`\n${colors.red}❌ Error: ${error.message}${colors.reset}\n`);
+  process.exit(1);
+});

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

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+/**
+ * Code Generation Script
+ * Generates entities, repositories, services, and controllers from data model specifications
+ *
+ * Uses the code generator from @xbg/backend-core
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+// Colors for console output
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  green: '\x1b[32m',
+  blue: '\x1b[34m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+};
+
+console.log(`
+${colors.bright}${colors.blue}╔════════════════════════════════════════════════════════════╗
+║                                                            ║
+║   XBG Backend Code Generator                               ║
+║                                                            ║
+╚════════════════════════════════════════════════════════════╝${colors.reset}
+`);
+
+// Import generator from @xbg/backend-core package
+let createGenerator;
+try {
+  ({ createGenerator } = require('@xbg/backend-core'));
+} catch (error) {
+  console.error(`${colors.red}❌ @xbg/backend-core not installed. Run 'npm install' first.${colors.reset}`);
+  process.exit(1);
+}
+
+// Get model file from command line arguments
+const modelFile = process.argv[2];
+
+if (!modelFile) {
+  console.error(`${colors.red}❌ Usage: npm run generate <model-file>${colors.reset}`);
+  console.log(`\nExample: npm run generate __examples__/user.model.js\n`);
+  process.exit(1);
+}
+
+const modelPath = path.resolve(modelFile);
+
+if (!fs.existsSync(modelPath)) {
+  console.error(`${colors.red}❌ Model file not found: ${modelPath}${colors.reset}\n`);
+  process.exit(1);
+}
+
+console.log(`${colors.blue}Loading model: ${modelPath}${colors.reset}\n`);
+
+// Load the model
+let model;
+try {
+  if (modelPath.endsWith('.ts')) {
+    console.log(`${colors.yellow}TypeScript models need to be compiled first${colors.reset}`);
+    console.log(`   Please create a .js version or use the compiled output\n`);
+    process.exit(1);
+  }
+
+  model = require(modelPath);
+
+  // Handle both default and named exports
+  const modelData = model.default || model.UserManagementModel || model;
+
+  if (!modelData || !modelData.entities) {
+    throw new Error('Invalid model format. Expected object with "entities" property');
+  }
+
+  console.log(`${colors.green}Model loaded successfully${colors.reset}\n`);
+  console.log(`${colors.bright}Entities found:${colors.reset}`);
+  Object.keys(modelData.entities).forEach((name) => {
+    console.log(`  - ${name}`);
+  });
+  console.log('');
+
+  // Create generator - templates come from @xbg/backend-core package
+  const outputDir = path.join(__dirname, '../functions/src/generated');
+  const generator = createGenerator(outputDir);
+
+  // Generate code for each entity
+  console.log(`${colors.bright}${colors.blue}Generating code...${colors.reset}\n`);
+
+  for (const [entityName, spec] of Object.entries(modelData.entities)) {
+    console.log(`${colors.blue}Generating ${entityName}...${colors.reset}`);
+    generator.generateEntity(entityName, spec);
+  }
+
+  // Generate barrel exports
+  console.log('');
+  generator.generateBarrelExports();
+
+  console.log(`
+${colors.green}${colors.bright}Code generation complete!${colors.reset}
+
+${colors.bright}Generated files:${colors.reset}
+  - entities/     Entity classes with validation
+  - repositories/ Database access layer
+  - services/     Business logic layer
+  - controllers/  HTTP request handlers
+
+${colors.bright}Next steps:${colors.reset}
+  1. Review generated code in functions/src/generated/
+  2. Customize business logic in service classes
+  3. Add custom routes in controller classes
+  4. Update functions/src/index.ts to register controllers
+  5. Run 'npm run build' to compile
+  6. Run 'npm start' to test locally
+`);
+} catch (error) {
+  console.error(`\n${colors.red}Error: ${error.message}${colors.reset}\n`);
+  if (error.stack) {
+    console.error(error.stack);
+  }
+  process.exit(1);
+}