@almadar/cli 0.3.2 → 0.3.3

package/shells/typescript-shell/packages/server/.env.example

@@ -0,0 +1,22 @@
+# Shell Server Environment Variables
+
+# Firebase Configuration
+FIREBASE_PROJECT_ID=your-project-id
+FIREBASE_CLIENT_EMAIL=your-client-email
+FIREBASE_PRIVATE_KEY="your-private-key"
+
+# External Service API Keys
+# YouTube Data API v3 (for youtube integrator)
+YOUTUBE_API_KEY=your-youtube-api-key
+
+# Stripe (for payment integrator)
+# STRIPE_SECRET_KEY=sk_test_...
+
+# Twilio (for messaging integrator)
+# TWILIO_ACCOUNT_SID=your-account-sid
+# TWILIO_AUTH_TOKEN=your-auth-token
+# TWILIO_PHONE_NUMBER=+1234567890
+
+# Email Service (SendGrid/Resend)
+# EMAIL_API_KEY=your-email-api-key
+# EMAIL_FROM_ADDRESS=noreply@example.com

package/shells/typescript-shell/packages/server/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@almadar/server",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "nodemon --watch src --watch ../shared/src --ext ts,js,json --exec tsx src/index.ts",
+    "build": "tsc -b",
+    "bundle": "esbuild src/index.ts --bundle --platform=node --target=node20 --format=esm --outfile=dist/index.js --alias:@almadar/shared=../shared/src/index.ts --external:express --external:cors --external:helmet --external:zod --external:dotenv --external:firebase-admin --external:@faker-js/faker",
+    "start": "node dist/index.js",
+    "clean": "rm -rf dist",
+    "test": "vitest --run",
+    "test:coverage": "vitest --coverage",
+    "lint": "eslint src/"
+  },
+  "dependencies": {
+    "@almadar/shared": "*",
+    "@faker-js/faker": "^9.3.0",
+    "ws": "^8.18.0",
+    "express": "^4.21.0",
+    "cors": "^2.8.5",
+    "helmet": "^8.0.0",
+    "zod": "^3.24.0",
+    "dotenv": "^16.4.0",
+    "firebase-admin": "^12.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/cors": "^2.8.17",
+    "@types/ws": "^8.5.0",
+    "@types/node": "^20.0.0",
+    "esbuild": "^0.27.2",
+    "typescript": "^5.3.0",
+    "tsx": "^4.19.0",
+    "nodemon": "^3.0.2",
+    "vitest": "^2.1.0",
+    "@vitest/coverage-v8": "^2.1.0",
+    "supertest": "^7.0.0",
+    "@types/supertest": "^6.0.0"
+  }
+}

package/shells/typescript-shell/packages/server/src/__tests__/integration.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+
+/**
+ * Integration Tests
+ *
+ * This file is regenerated by the Almadar Compiler when compiling a schema.
+ * It will contain CRUD and workflow tests for all entities defined in your schema.
+ */
+
+describe('Integration Tests', () => {
+  beforeAll(() => {
+    // Setup test environment
+  });
+
+  afterAll(() => {
+    // Cleanup
+  });
+
+  it('placeholder test - regenerate by compiling your schema', () => {
+    // Tests will be generated based on your schema entities
+    expect(true).toBe(true);
+  });
+});

package/shells/typescript-shell/packages/server/src/app.ts

@@ -0,0 +1,53 @@
+import express from 'express';
+import cors from 'cors';
+import helmet from 'helmet';
+import { env } from '@/lib';
+import { errorHandler, notFoundHandler } from '@/middleware/errorHandler';
+import { logger } from '@/lib/logger';
+import { registerRoutes } from './routes.js';
+import { initializeMockData } from './seedMockData.js';
+
+export const app = express();
+
+// Security middleware
+app.use(helmet());
+app.use(cors({ origin: env.CORS_ORIGIN }));
+
+// Body parsing
+app.use(express.json());
+app.use(express.urlencoded({ extended: true }));
+
+// Request logging in development
+if (env.NODE_ENV === 'development') {
+  app.use((req, _res, next) => {
+    logger.debug(`${req.method} ${req.path}`);
+    next();
+  });
+}
+
+// Initialize mock data if enabled
+if (env.USE_MOCK_DATA) {
+  logger.info('Mock mode enabled - initializing in-memory data store');
+  initializeMockData().catch((error) => {
+    logger.error('Failed to initialize mock data:', error);
+  });
+}
+
+// Health check endpoint
+app.get('/health', (_req, res) => {
+  res.json({
+    status: 'ok',
+    timestamp: new Date().toISOString(),
+    environment: env.NODE_ENV,
+    mockMode: env.USE_MOCK_DATA,
+  });
+});
+
+// Register all API routes
+registerRoutes(app);
+
+// 404 handler for unmatched routes
+app.use(notFoundHandler);
+
+// Global error handler (must be last)
+app.use(errorHandler);

package/shells/typescript-shell/packages/server/src/features/.gitkeep

@@ -0,0 +1,10 @@
+# Graph-generated feature modules will be created here
+# Example structure:
+# features/
+#   patients/
+#     patients.controller.ts
+#     patients.service.ts
+#     patients.repository.ts
+#     patients.schema.ts
+#     patients.routes.ts
+#     index.ts

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

@@ -0,0 +1,60 @@
+import { createServer } from 'http';
+import { app } from './app';
+import { env, setupEventBroadcast } from '@/lib';
+import { logger } from '@/lib/logger';
+import type { Socket } from 'net';
+
+// Create HTTP server from Express app
+const server = createServer(app);
+
+// Setup WebSocket for cross-client event broadcast
+setupEventBroadcast(server);
+
+server.listen(env.PORT, '0.0.0.0', () => {
+  logger.info(`🚀 Server running at http://localhost:${env.PORT}`);
+  logger.info(`📝 Environment: ${env.NODE_ENV}`);
+  logger.info(`🔌 WebSocket events at ws://localhost:${env.PORT}/ws/events`);
+});
+
+// Track connections for graceful shutdown
+const connections = new Set<Socket>();
+
+server.on('connection', (conn: Socket) => {
+  connections.add(conn);
+  conn.on('close', () => connections.delete(conn));
+});
+
+// Graceful shutdown
+const shutdown = (signal: string) => {
+  logger.info(`\n${signal} received, shutting down gracefully...`);
+
+  server.close(() => {
+    logger.info('HTTP server closed');
+    process.exit(0);
+  });
+
+  // Force close connections after timeout
+  setTimeout(() => {
+    logger.warn('Forcing connections closed...');
+    connections.forEach((conn) => conn.destroy());
+  }, 5000);
+
+  // Force exit after longer timeout
+  setTimeout(() => {
+    logger.error('Forced exit');
+    process.exit(1);
+  }, 10000);
+};
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+// Note: SIGHUP is not handled to prevent issues with background processes
+
+process.on('uncaughtException', (err) => {
+  logger.error('Uncaught exception:', err);
+  shutdown('UNCAUGHT_EXCEPTION');
+});
+
+process.on('unhandledRejection', (reason) => {
+  logger.error('Unhandled rejection:', reason);
+});

package/shells/typescript-shell/packages/server/src/integrators/INTEGRATORS.md

@@ -0,0 +1,357 @@
+# Shell Integrators Development Guide
+
+> Guide for implementing new service integrators in the KFlow shell.
+
+---
+
+## Overview
+
+Integrators are the shell-side implementation of service traits. They handle external API calls and emit events back to the trait state machine via the event bus, completing the "closed circuit" pattern.
+
+```
+Trait (call_service) → Integrator (execute) → External API → EventBus (emit)
+```
+
+---
+
+## Architecture
+
+### The ServiceIntegrator Interface
+
+Every integrator must implement the `ServiceIntegrator` interface:
+
+```typescript
+interface ServiceIntegrator {
+  name: string;
+  description: string;
+  actions: IntegratorAction[];
+  execute(
+    action: string,
+    params: Record<string, unknown>,
+    eventBus: EventBus,
+    callbacks: { onSuccess: string; onError: string }
+  ): Promise<void>;
+}
+```
+
+### The EventBus Interface
+
+Integrators emit events back to the trait state machine:
+
+```typescript
+interface EventBus {
+  emit(event: string, payload?: unknown): void;
+}
+```
+
+---
+
+## Creating a New Integrator
+
+### Step 1: Add Metadata (Shared Package)
+
+First, add your integrator to the metadata in `packages/shared/src/integrators/integrator-library.ts`:
+
+```typescript
+export const INTEGRATOR_METADATA: Record<string, IntegratorMeta> = {
+  // ... existing integrators
+
+  weather: {
+    name: 'weather',
+    description: 'Weather API - get forecasts and current conditions',
+    category: 'custom',
+    actions: [
+      {
+        name: 'getCurrentWeather',
+        description: 'Get current weather for a location',
+        params: [
+          { name: 'location', type: 'string', required: true, description: 'City name or coordinates' },
+        ],
+        responseShape: { temp: 'number', conditions: 'string', humidity: 'number' },
+      },
+      {
+        name: 'getForecast',
+        description: 'Get 5-day forecast',
+        params: [
+          { name: 'location', type: 'string', required: true },
+          { name: 'days', type: 'number', required: false },
+        ],
+        responseShape: { days: 'array' },
+      },
+    ],
+  },
+};
+```
+
+### Step 2: Add Compiler Mapping
+
+Add the mapping in `packages/compiler/src/v2/generators/services/ServiceToIntegrator.ts`:
+
+```typescript
+export const SERVICE_TO_INTEGRATOR: Record<string, IntegratorMapping> = {
+  // ... existing mappings
+
+  weather: {
+    integrator: 'weatherIntegrator',
+    importPath: '@/integrators/weather',
+  },
+};
+```
+
+### Step 3: Implement the Integrator (Shell)
+
+Create the implementation file in `shell/packages/server/src/integrators/`:
+
+```typescript
+// weather.ts
+import { ServiceIntegrator, EventBus, IntegratorAction } from './types.js';
+
+const API_BASE = 'https://api.weather.example.com/v1';
+const API_KEY = process.env.WEATHER_API_KEY;
+
+export const weatherIntegrator: ServiceIntegrator = {
+  name: 'weather',
+  description: 'Weather API - get forecasts and current conditions',
+
+  actions: [
+    {
+      name: 'getCurrentWeather',
+      description: 'Get current weather for a location',
+      params: [
+        { name: 'location', type: 'string', required: true },
+      ],
+    },
+    {
+      name: 'getForecast',
+      description: 'Get 5-day forecast',
+      params: [
+        { name: 'location', type: 'string', required: true },
+        { name: 'days', type: 'number', required: false },
+      ],
+    },
+  ],
+
+  async execute(
+    action: string,
+    params: Record<string, unknown>,
+    eventBus: EventBus,
+    callbacks: { onSuccess: string; onError: string }
+  ): Promise<void> {
+    try {
+      let result: unknown;
+
+      switch (action) {
+        case 'getCurrentWeather':
+          result = await getCurrentWeather(params.location as string);
+          break;
+        case 'getForecast':
+          result = await getForecast(params.location as string, params.days as number);
+          break;
+        default:
+          throw new Error(`Unknown action: ${action}`);
+      }
+
+      // Emit success event back to trait state machine
+      eventBus.emit(callbacks.onSuccess, result);
+    } catch (error) {
+      // Emit error event back to trait state machine
+      eventBus.emit(callbacks.onError, {
+        code: 'WEATHER_API_ERROR',
+        message: error instanceof Error ? error.message : 'Unknown error',
+        action,
+      });
+    }
+  },
+};
+
+// Private helper functions
+async function getCurrentWeather(location: string): Promise<object> {
+  const response = await fetch(`${API_BASE}/current?q=${encodeURIComponent(location)}&key=${API_KEY}`);
+  if (!response.ok) throw new Error(`API error: ${response.status}`);
+  return response.json();
+}
+
+async function getForecast(location: string, days = 5): Promise<object> {
+  const response = await fetch(`${API_BASE}/forecast?q=${encodeURIComponent(location)}&days=${days}&key=${API_KEY}`);
+  if (!response.ok) throw new Error(`API error: ${response.status}`);
+  return response.json();
+}
+```
+
+### Step 4: Register the Integrator
+
+Add the integrator to `shell/packages/server/src/integrators/index.ts`:
+
+```typescript
+export { youtubeIntegrator } from './youtube.js';
+export { weatherIntegrator } from './weather.js';
+// Export new integrators here
+```
+
+And register it in `registry.ts`:
+
+```typescript
+import { weatherIntegrator } from './weather.js';
+
+// In the registration section:
+registry.register(weatherIntegrator);
+```
+
+### Step 5: Add Environment Variable
+
+Add the required API key to `.env.example`:
+
+```bash
+WEATHER_API_KEY=your-api-key-here
+```
+
+---
+
+## Best Practices
+
+### Error Handling
+
+Always emit error events with structured payloads:
+
+```typescript
+eventBus.emit(callbacks.onError, {
+  code: 'SPECIFIC_ERROR_CODE',    // Machine-readable code
+  message: 'Human-readable message',  // User-friendly message
+  action,                         // Which action failed
+  details: { ... },               // Optional debugging info
+});
+```
+
+### Retry Logic
+
+For transient failures, implement retry with exponential backoff:
+
+```typescript
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  maxAttempts = 3,
+  baseDelay = 1000
+): Promise<T> {
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (attempt === maxAttempts) throw error;
+      await sleep(baseDelay * Math.pow(2, attempt - 1));
+    }
+  }
+  throw new Error('Unreachable');
+}
+```
+
+### Timeout Handling
+
+Always set timeouts for external API calls:
+
+```typescript
+const controller = new AbortController();
+const timeout = setTimeout(() => controller.abort(), 10000); // 10s timeout
+
+try {
+  const response = await fetch(url, { signal: controller.signal });
+  // ...
+} finally {
+  clearTimeout(timeout);
+}
+```
+
+### Validation
+
+Validate required parameters before making API calls:
+
+```typescript
+if (!params.location) {
+  eventBus.emit(callbacks.onError, {
+    code: 'MISSING_PARAMETER',
+    message: 'Location is required',
+    action,
+  });
+  return;
+}
+```
+
+---
+
+## Testing
+
+### Unit Tests
+
+Create `__tests__/{integrator}.test.ts` with mocked API responses:
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import { weatherIntegrator } from '../weather.js';
+
+describe('weatherIntegrator', () => {
+  it('should emit success on valid response', async () => {
+    const mockEventBus = { emit: vi.fn() };
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ temp: 72 }),
+    });
+    global.fetch = mockFetch;
+
+    await weatherIntegrator.execute(
+      'getCurrentWeather',
+      { location: 'San Francisco' },
+      mockEventBus,
+      { onSuccess: 'WEATHER_LOADED', onError: 'WEATHER_FAILED' }
+    );
+
+    expect(mockEventBus.emit).toHaveBeenCalledWith('WEATHER_LOADED', { temp: 72 });
+  });
+});
+```
+
+### Closed-Circuit Tests
+
+Test the event flow pattern:
+
+```typescript
+describe('closed-circuit pattern', () => {
+  it('should complete the circuit on success', async () => {
+    const events: string[] = [];
+    const eventBus = { emit: (e: string) => events.push(e) };
+
+    await weatherIntegrator.execute(
+      'getCurrentWeather',
+      { location: 'NYC' },
+      eventBus,
+      { onSuccess: 'WEATHER_LOADED', onError: 'WEATHER_FAILED' }
+    );
+
+    expect(events).toContain('WEATHER_LOADED');
+    expect(events).not.toContain('WEATHER_FAILED');
+  });
+});
+```
+
+---
+
+## Existing Integrators
+
+| Integrator | File | Actions |
+|------------|------|---------|
+| YouTube | `youtube.ts` | `search`, `getVideo`, `getChannel` |
+
+---
+
+## File Structure
+
+```
+shell/packages/server/src/integrators/
+├── INTEGRATORS.md          # This guide
+├── types.ts                # ServiceIntegrator, EventBus interfaces
+├── registry.ts             # Integrator registration and lookup
+├── index.ts                # Exports
+├── youtube.ts              # YouTube Data API integrator
+├── __tests__/
+│   ├── types.test.ts
+│   ├── registry.test.ts
+│   └── youtube.test.ts
+```