@almadar/cli 0.3.2 → 0.3.3

package/shells/typescript-shell/packages/server/src/lib/db.ts

@@ -0,0 +1,130 @@
+/**
+ * Database Configuration
+ * 
+ * Supports both Prisma (SQL) and Firebase Admin (Firestore)
+ * Generated apps can use either depending on the database option
+ */
+
+import admin from 'firebase-admin';
+import { env } from './env.js';
+
+// ============ Firebase Admin / Firestore ============
+
+let firebaseApp: admin.app.App | null = null;
+
+/**
+ * Initialize Firebase Admin SDK
+ */
+function initializeFirebase(): admin.app.App {
+  if (firebaseApp) {
+    return firebaseApp;
+  }
+
+  // Check if already initialized
+  if (admin.apps.length > 0) {
+    firebaseApp = admin.apps[0]!;
+    return firebaseApp;
+  }
+
+  // Check for emulator mode FIRST (no credentials needed)
+  if (env.FIRESTORE_EMULATOR_HOST) {
+    // Emulator mode - no credentials needed
+    firebaseApp = admin.initializeApp({
+      projectId: env.FIREBASE_PROJECT_ID || 'demo-project',
+    });
+    console.log(`🔧 Firebase Admin initialized for emulator: ${env.FIRESTORE_EMULATOR_HOST}`);
+    return firebaseApp;
+  }
+
+  // Production mode - need credentials
+  const serviceAccountPath = env.FIREBASE_SERVICE_ACCOUNT_PATH;
+  
+  if (serviceAccountPath) {
+    // Use service account file
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const serviceAccount = require(serviceAccountPath);
+    firebaseApp = admin.initializeApp({
+      credential: admin.credential.cert(serviceAccount),
+      projectId: env.FIREBASE_PROJECT_ID,
+    });
+  } else if (env.FIREBASE_PROJECT_ID && env.FIREBASE_CLIENT_EMAIL && env.FIREBASE_PRIVATE_KEY) {
+    // Use inline service account credentials
+    firebaseApp = admin.initializeApp({
+      credential: admin.credential.cert({
+        projectId: env.FIREBASE_PROJECT_ID,
+        clientEmail: env.FIREBASE_CLIENT_EMAIL,
+        privateKey: env.FIREBASE_PRIVATE_KEY.replace(/\\n/g, '\n'),
+      }),
+      projectId: env.FIREBASE_PROJECT_ID,
+    });
+  } else if (env.FIREBASE_PROJECT_ID) {
+    // Use application default credentials (for Cloud Run, etc.)
+    firebaseApp = admin.initializeApp({
+      credential: admin.credential.applicationDefault(),
+      projectId: env.FIREBASE_PROJECT_ID,
+    });
+  } else {
+    // Emulator mode - use default credentials
+    firebaseApp = admin.initializeApp({
+      projectId: 'demo-project',
+    });
+  }
+
+  return firebaseApp;
+}
+
+/**
+ * Get Firestore instance
+ */
+export function getFirestore(): admin.firestore.Firestore {
+  const app = initializeFirebase();
+  const db = app.firestore();
+  
+  // Connect to emulator if configured
+  if (env.FIRESTORE_EMULATOR_HOST) {
+    db.settings({
+      host: env.FIRESTORE_EMULATOR_HOST,
+      ssl: false,
+    });
+  }
+  
+  return db;
+}
+
+/**
+ * Get Firebase Auth instance
+ */
+export function getAuth(): admin.auth.Auth {
+  const app = initializeFirebase();
+  return app.auth();
+}
+
+// ============ Prisma (Optional - for SQL databases) ============
+
+// Uncomment if using Prisma with SQL database
+/*
+import { PrismaClient } from '@prisma/client';
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __db: PrismaClient | undefined;
+}
+
+const createPrismaClient = () => {
+  return new PrismaClient({
+    log: env.NODE_ENV === 'development' ? ['query', 'error', 'warn'] : ['error'],
+  });
+};
+
+export const db = globalThis.__db ?? createPrismaClient();
+
+if (env.NODE_ENV !== 'production') {
+  globalThis.__db = db;
+}
+*/
+
+// Re-export admin for convenience
+export { admin };
+
+// Export db instance for handler convenience
+export const db = getFirestore();

package/shells/typescript-shell/packages/server/src/lib/env.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import dotenv from 'dotenv';
+
+// Load environment variables
+dotenv.config();
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  PORT: z
+    .string()
+    .default('3030')
+    .transform((val) => parseInt(val, 10)),
+  CORS_ORIGIN: z
+    .string()
+    .default('http://localhost:5173')
+    .transform((val) => (val.includes(',') ? val.split(',').map((s) => s.trim()) : val)),
+  
+  // Database (Prisma/SQL) - optional
+  DATABASE_URL: z.string().optional(),
+  
+  // Firebase/Firestore configuration
+  FIREBASE_PROJECT_ID: z.string().optional(),
+  FIREBASE_CLIENT_EMAIL: z.string().optional(),
+  FIREBASE_PRIVATE_KEY: z.string().optional(),
+  FIREBASE_SERVICE_ACCOUNT_PATH: z.string().optional(),
+  FIRESTORE_EMULATOR_HOST: z.string().optional(),
+  FIREBASE_AUTH_EMULATOR_HOST: z.string().optional(),
+  
+  // API configuration
+  API_PREFIX: z.string().default('/api'),
+
+  // Mock data configuration
+  USE_MOCK_DATA: z.string().default('true').transform((v) => v === 'true'),
+  MOCK_SEED: z
+    .string()
+    .optional()
+    .transform((v) => (v ? parseInt(v, 10) : undefined)),
+});
+
+const parsed = envSchema.safeParse(process.env);
+
+if (!parsed.success) {
+  console.error('❌ Invalid environment variables:', parsed.error.flatten().fieldErrors);
+  throw new Error('Invalid environment variables');
+}
+
+export const env = parsed.data;

package/shells/typescript-shell/packages/server/src/lib/eventBus.ts

@@ -0,0 +1,80 @@
+/**
+ * Server EventBus - Singleton for server-side cross-trait communication
+ *
+ * This EventBus enables:
+ * - Server-side trait event emission after CRUD operations
+ * - Server-side trait listeners responding to events
+ * - Cross-client event broadcast via WebSocket
+ *
+ * @packageDocumentation
+ */
+
+type EventHandler = (payload: unknown, meta?: Record<string, unknown>) => void;
+
+/**
+ * Simple EventBus implementation for server-side events
+ */
+class EventBus {
+  private handlers: Map<string, Set<EventHandler>> = new Map();
+  private debug: boolean;
+
+  constructor(options?: { debug?: boolean }) {
+    this.debug = options?.debug ?? false;
+  }
+
+  on(event: string, handler: EventHandler): () => void {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, new Set());
+    }
+    this.handlers.get(event)!.add(handler);
+
+    // Return unsubscribe function
+    return () => {
+      this.handlers.get(event)?.delete(handler);
+    };
+  }
+
+  off(event: string, handler: EventHandler): void {
+    this.handlers.get(event)?.delete(handler);
+  }
+
+  emit(event: string, payload?: unknown, meta?: Record<string, unknown>): void {
+    if (this.debug) {
+      console.log(`[EventBus] Emitting ${event}:`, payload);
+    }
+
+    const handlers = this.handlers.get(event);
+    if (handlers) {
+      handlers.forEach(handler => {
+        try {
+          handler(payload, meta);
+        } catch (err) {
+          console.error(`[EventBus] Error in handler for ${event}:`, err);
+        }
+      });
+    }
+  }
+
+  clear(): void {
+    this.handlers.clear();
+  }
+}
+
+/**
+ * Singleton EventBus instance for server-side event communication.
+ */
+export const serverEventBus = new EventBus({
+  debug: process.env.NODE_ENV === 'development',
+});
+
+/**
+ * Type-safe event emission helper
+ */
+export function emitEntityEvent(
+  entityType: string,
+  action: 'CREATED' | 'UPDATED' | 'DELETED',
+  payload: Record<string, unknown>
+): void {
+  const eventType = `${entityType.toUpperCase()}_${action}`;
+  serverEventBus.emit(eventType, payload, { orbital: entityType });
+}

package/shells/typescript-shell/packages/server/src/lib/index.ts

@@ -0,0 +1,10 @@
+export { env } from './env.js';
+export { getFirestore, getAuth, admin } from './db.js';
+export { logger } from './logger.js';
+export { serverEventBus, emitEntityEvent } from './eventBus.js';
+export {
+  setupEventBroadcast,
+  getWebSocketServer,
+  closeWebSocketServer,
+  getConnectedClientCount,
+} from './websocket.js';

package/shells/typescript-shell/packages/server/src/lib/logger.ts

@@ -0,0 +1,48 @@
+import { env } from './env.js';
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+const colors = {
+  debug: '\x1b[36m', // Cyan
+  info: '\x1b[32m', // Green
+  warn: '\x1b[33m', // Yellow
+  error: '\x1b[31m', // Red
+  reset: '\x1b[0m',
+};
+
+const shouldLog = (level: LogLevel): boolean => {
+  const levels: LogLevel[] = ['debug', 'info', 'warn', 'error'];
+  const minLevel = env.NODE_ENV === 'production' ? 'info' : 'debug';
+  return levels.indexOf(level) >= levels.indexOf(minLevel);
+};
+
+const formatMessage = (level: LogLevel, message: string, meta?: unknown): string => {
+  const timestamp = new Date().toISOString();
+  const color = colors[level];
+  const prefix = `${color}[${level.toUpperCase()}]${colors.reset}`;
+  const metaStr = meta ? ` ${JSON.stringify(meta)}` : '';
+  return `${timestamp} ${prefix} ${message}${metaStr}`;
+};
+
+export const logger = {
+  debug: (message: string, meta?: unknown) => {
+    if (shouldLog('debug')) {
+      console.log(formatMessage('debug', message, meta));
+    }
+  },
+  info: (message: string, meta?: unknown) => {
+    if (shouldLog('info')) {
+      console.log(formatMessage('info', message, meta));
+    }
+  },
+  warn: (message: string, meta?: unknown) => {
+    if (shouldLog('warn')) {
+      console.warn(formatMessage('warn', message, meta));
+    }
+  },
+  error: (message: string, meta?: unknown) => {
+    if (shouldLog('error')) {
+      console.error(formatMessage('error', message, meta));
+    }
+  },
+};

package/shells/typescript-shell/packages/server/src/lib/websocket.ts

@@ -0,0 +1,161 @@
+/**
+ * WebSocket Event Broadcast - Cross-client event synchronization
+ *
+ * Broadcasts server-side events to all connected clients via WebSocket.
+ * This enables real-time updates across multiple browser clients.
+ *
+ * @packageDocumentation
+ */
+
+import { WebSocketServer, WebSocket, type RawData } from 'ws';
+import type { Server, IncomingMessage } from 'http';
+import { serverEventBus } from './eventBus.js';
+import { logger } from './logger.js';
+
+/**
+ * Event structure for broadcasting
+ */
+interface BroadcastEvent {
+  type: string;
+  payload?: unknown;
+  timestamp?: number;
+  source?: Record<string, unknown>;
+}
+
+/**
+ * WebSocket server instance (singleton)
+ */
+let wss: WebSocketServer | null = null;
+
+/**
+ * Setup WebSocket server for event broadcasting.
+ *
+ * Listens to all server events via wildcard and broadcasts to connected clients.
+ *
+ * @param server - HTTP server to attach WebSocket to
+ * @param path - WebSocket endpoint path (default: '/ws/events')
+ *
+ * @example
+ * ```typescript
+ * import { createServer } from 'http';
+ * import { setupEventBroadcast } from '@/lib/websocket';
+ *
+ * const server = createServer(app);
+ * setupEventBroadcast(server);
+ * ```
+ */
+export function setupEventBroadcast(server: Server, path: string = '/ws/events'): WebSocketServer {
+  if (wss) {
+    logger.warn('[WebSocket] Server already initialized');
+    return wss;
+  }
+
+  wss = new WebSocketServer({ server, path });
+
+  logger.info(`[WebSocket] Server listening at ${path}`);
+
+  // Handle new connections
+  wss.on('connection', (ws: WebSocket, req: IncomingMessage) => {
+    const clientId = req.headers['sec-websocket-key'] || 'unknown';
+    logger.debug(`[WebSocket] Client connected: ${clientId}`);
+
+    // Send welcome message
+    ws.send(
+      JSON.stringify({
+        type: 'CONNECTED',
+        timestamp: Date.now(),
+        message: 'Connected to event stream',
+      })
+    );
+
+    // Handle client messages (for future bidirectional communication)
+    ws.on('message', (data: RawData) => {
+      try {
+        const message = JSON.parse(data.toString());
+        logger.debug(`[WebSocket] Received from ${clientId}:`, message);
+
+        // Handle client-to-server events if needed
+        if (message.type && message.payload) {
+          // Emit to server event bus with client source
+          serverEventBus.emit(message.type, message.payload, {
+            orbital: 'client',
+            entity: clientId,
+          });
+        }
+      } catch (error) {
+        logger.error(`[WebSocket] Failed to parse message:`, error);
+      }
+    });
+
+    ws.on('close', () => {
+      logger.debug(`[WebSocket] Client disconnected: ${clientId}`);
+    });
+
+    ws.on('error', (error: Error) => {
+      logger.error(`[WebSocket] Client error:`, error);
+    });
+  });
+
+  // Subscribe to all server events and broadcast to clients
+  serverEventBus.on('*', (event: unknown) => {
+    if (!wss) return;
+
+    const typedEvent = event as BroadcastEvent;
+    const message = JSON.stringify({
+      type: typedEvent.type,
+      payload: typedEvent.payload,
+      timestamp: typedEvent.timestamp,
+      source: typedEvent.source,
+    });
+
+    let broadcastCount = 0;
+    wss.clients.forEach((client: WebSocket) => {
+      if (client.readyState === WebSocket.OPEN) {
+        client.send(message);
+        broadcastCount++;
+      }
+    });
+
+    if (broadcastCount > 0) {
+      logger.debug(`[WebSocket] Broadcast ${typedEvent.type} to ${broadcastCount} client(s)`);
+    }
+  });
+
+  return wss;
+}
+
+/**
+ * Get the WebSocket server instance (for testing or advanced usage)
+ */
+export function getWebSocketServer(): WebSocketServer | null {
+  return wss;
+}
+
+/**
+ * Close the WebSocket server
+ */
+export function closeWebSocketServer(): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (!wss) {
+      resolve();
+      return;
+    }
+
+    wss.close((err?: Error) => {
+      if (err) {
+        reject(err);
+      } else {
+        wss = null;
+        resolve();
+      }
+    });
+  });
+}
+
+/**
+ * Get connected client count
+ */
+export function getConnectedClientCount(): number {
+  if (!wss) return 0;
+  return wss.clients.size;
+}

package/shells/typescript-shell/packages/server/src/middleware/authenticateFirebase.ts

@@ -0,0 +1,29 @@
+import { NextFunction, Request, Response } from 'express';
+import { getAuth } from '../lib/db.js';
+
+const BEARER_PREFIX = 'Bearer ';
+
+export async function authenticateFirebase(req: Request, res: Response, next: NextFunction) {
+  try {
+    const authorization = req.headers.authorization;
+
+    if (!authorization || !authorization.startsWith(BEARER_PREFIX)) {
+      return res.status(401).json({ error: 'Authorization header missing or malformed' });
+    }
+
+    const token = authorization.slice(BEARER_PREFIX.length);
+    const decodedToken = await getAuth().verifyIdToken(token);
+
+    req.firebaseUser = decodedToken;
+    res.locals.firebaseUser = decodedToken;
+
+    return next();
+  } catch (error) {
+    console.error('Firebase authentication failed:', error);
+    return res.status(401).json({ error: 'Unauthorized' });
+  }
+}
+
+export default authenticateFirebase;
+
+

package/shells/typescript-shell/packages/server/src/middleware/errorHandler.ts

@@ -0,0 +1,135 @@
+import { Request, Response, NextFunction } from 'express';
+import { ZodError } from 'zod';
+import { logger } from '@/lib/logger';
+
+/**
+ * Base application error class
+ */
+export class AppError extends Error {
+  constructor(
+    public statusCode: number,
+    public message: string,
+    public code?: string
+  ) {
+    super(message);
+    this.name = 'AppError';
+  }
+}
+
+/**
+ * 404 Not Found error
+ */
+export class NotFoundError extends AppError {
+  constructor(message: string = 'Resource not found') {
+    super(404, message, 'NOT_FOUND');
+  }
+}
+
+/**
+ * 400 Bad Request / Validation error
+ */
+export class ValidationError extends AppError {
+  constructor(message: string = 'Validation failed') {
+    super(400, message, 'VALIDATION_ERROR');
+  }
+}
+
+/**
+ * 401 Unauthorized error
+ */
+export class UnauthorizedError extends AppError {
+  constructor(message: string = 'Unauthorized') {
+    super(401, message, 'UNAUTHORIZED');
+  }
+}
+
+/**
+ * 403 Forbidden error
+ */
+export class ForbiddenError extends AppError {
+  constructor(message: string = 'Forbidden') {
+    super(403, message, 'FORBIDDEN');
+  }
+}
+
+/**
+ * 409 Conflict error
+ */
+export class ConflictError extends AppError {
+  constructor(message: string = 'Resource conflict') {
+    super(409, message, 'CONFLICT');
+  }
+}
+
+/**
+ * Global error handler middleware
+ */
+export const errorHandler = (
+  err: Error,
+  _req: Request,
+  res: Response,
+  _next: NextFunction
+): void => {
+  logger.error('Error:', { name: err.name, message: err.message, stack: err.stack });
+
+  // Zod validation errors
+  if (err instanceof ZodError) {
+    res.status(400).json({
+      success: false,
+      error: 'Validation failed',
+      code: 'VALIDATION_ERROR',
+      details: err.errors.map((e) => ({
+        path: e.path.join('.'),
+        message: e.message,
+      })),
+    });
+    return;
+  }
+
+  // Custom application errors
+  if (err instanceof AppError) {
+    res.status(err.statusCode).json({
+      success: false,
+      error: err.message,
+      code: err.code,
+    });
+    return;
+  }
+
+  // Firebase/Firestore errors
+  if (err.name === 'FirebaseError' || err.name === 'FirestoreError') {
+    res.status(500).json({
+      success: false,
+      error: 'Database error',
+      code: 'DATABASE_ERROR',
+    });
+    return;
+  }
+
+  // Unknown errors
+  res.status(500).json({
+    success: false,
+    error: 'Internal server error',
+    code: 'INTERNAL_ERROR',
+  });
+};
+
+/**
+ * Async handler wrapper to catch errors in async route handlers
+ */
+export const asyncHandler =
+  (fn: (req: Request, res: Response, next: NextFunction) => Promise<unknown>) =>
+  (req: Request, res: Response, next: NextFunction) => {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+
+/**
+ * 404 handler for unmatched routes
+ */
+export const notFoundHandler = (req: Request, res: Response): void => {
+  res.status(404).json({
+    success: false,
+    error: `Route ${req.method} ${req.path} not found`,
+    code: 'ROUTE_NOT_FOUND',
+  });
+};

package/shells/typescript-shell/packages/server/src/middleware/index.ts

@@ -0,0 +1,15 @@
+export {
+  errorHandler,
+  notFoundHandler,
+  asyncHandler,
+  AppError,
+  NotFoundError,
+  ValidationError,
+  UnauthorizedError,
+  ForbiddenError,
+  ConflictError,
+} from './errorHandler';
+
+export { validateBody, validateQuery, validateParams } from './validation';
+
+export { authenticateFirebase } from './authenticateFirebase.js';