@almadar/cli 1.0.5 → 1.0.7

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

@@ -1,22 +0,0 @@
-# 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

@@ -1,41 +0,0 @@
-{
-  "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

@@ -1,23 +0,0 @@
-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

@@ -1,53 +0,0 @@
-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

@@ -1,10 +0,0 @@
-# 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

@@ -1,60 +0,0 @@
-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

@@ -1,357 +0,0 @@
-# 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
-```