@simplens/onboard 1.0.0

package/src/services.ts

@@ -0,0 +1,190 @@
+import inquirer from 'inquirer';
+import { execa } from 'execa';
+import ora from 'ora';
+import { logInfo, logSuccess, logError, logWarning } from './utils.js';
+import chalk from 'chalk';
+import { HEALTH_CHECK, SERVICE_PORTS, getServiceURL } from './config/constants.js';
+
+/**
+ * Prompts user whether to start the services immediately after setup.
+ * 
+ * @returns `true` if user wants to start services, `false` otherwise
+ * 
+ * @example
+ * ```ts
+ * if (await promptStartServices()) {
+ *   await startInfraServices(targetDir);
+ * }
+ * ```
+ */
+export async function promptStartServices(): Promise<boolean> {
+    const answer = await inquirer.prompt<{ start: boolean }>([
+        {
+            type: 'confirm',
+            name: 'start',
+            message: 'Do you want to start the services now?',
+            default: true,
+        },
+    ]);
+
+    return answer.start;
+}
+
+/**
+ * Starts infrastructure services using docker-compose.
+ * Runs `docker-compose -f docker-compose.infra.yaml up -d` in the target directory.
+ * 
+ * @param targetDir - Directory containing docker-compose.infra.yaml
+ * @throws Error if docker-compose command fails
+ * 
+ * @example
+ * ```ts
+ * await startInfraServices('/opt/simplens');
+ * ```
+ */
+export async function startInfraServices(targetDir: string): Promise<void> {
+    logInfo('Starting infrastructure services...');
+
+    const spinner = ora('Starting docker-compose.infra.yaml...').start();
+
+    try {
+        await execa(
+            'docker-compose',
+            ['-f', 'docker-compose.infra.yaml', 'up', '-d'],
+            { cwd: targetDir }
+        );
+        spinner.succeed('Infrastructure services started');
+    } catch (error: any) {
+        spinner.fail('Failed to start infrastructure services');
+        throw error;
+    }
+}
+
+/**
+ * Waits for infrastructure services to become healthy.
+ * Polls Docker health checks for up to 60 seconds (30 retries × 2s).
+ * 
+ * @param targetDir - Directory where services are running
+ * 
+ * @remarks
+ * Checks for healthy containers running MongoDB or Redis.
+ * Configuration: 30 max retries, 2000ms delay between retries.
+ * 
+ * @example
+ * ```ts
+ * await startInfraServices(targetDir);
+ * await waitForInfraHealth(targetDir); // Wait for services to be ready
+ * ```
+ */
+export async function waitForInfraHealth(targetDir: string): Promise<void> {
+    logInfo('Waiting for infrastructure services to be healthy...');
+
+    const spinner = ora('Checking service health...').start();
+
+    // Wait for mongo, redis health checks
+    const maxRetries = HEALTH_CHECK.MAX_RETRIES;
+    const retryDelay = HEALTH_CHECK.RETRY_DELAY_MS;
+
+    for (let i = 0; i < maxRetries; i++) {
+        try {
+            // Check if containers are healthy
+            const { stdout } = await execa('docker', ['ps', '--filter', 'health=healthy', '--format', '{{.Names}}']);
+            const healthyContainers = stdout.split('\n').filter(Boolean);
+
+            // Check for critical services
+            const hasMongoOrRedis = healthyContainers.some(name => 
+                name.includes('mongo') || name.includes('redis')
+            );
+
+            if (hasMongoOrRedis) {
+                spinner.succeed('Infrastructure services are healthy');
+                return;
+            }
+
+            spinner.text = `Waiting for services... (${i + 1}/${maxRetries})`;
+            await sleep(retryDelay);
+        } catch (error) {
+            spinner.text = `Checking health... (${i + 1}/${maxRetries})`;
+            await sleep(retryDelay);
+        }
+    }
+
+    spinner.warn('Health check timed out, but services may still be starting');
+    logWarning('You may need to wait a bit longer for all services to be ready.');
+}
+
+/**
+ * Start application services
+ */
+export async function startAppServices(targetDir: string): Promise<void> {
+    logInfo('Starting application services...');
+
+    const spinner = ora('Starting docker-compose.yaml...').start();
+
+    try {
+        await execa(
+            'docker-compose',
+            ['up', '-d'],
+            { cwd: targetDir }
+        );
+        spinner.succeed('Application services started');
+    } catch (error: any) {
+        spinner.fail('Failed to start application services');
+        throw error;
+    }
+}
+
+/**
+ * Display service status and URLs
+ */
+export async function displayServiceStatus(): Promise<void> {
+    console.log('\n' + chalk.green('═'.repeat(60)));
+    console.log(chalk.green.bold('  ✅ Services Started Successfully!'));
+    console.log(chalk.green('═'.repeat(60)) + '\n');
+
+    try {
+        // Get running containers
+        const { stdout } = await execa('docker', ['ps', '--format', '{{.Names}}']);
+        const containers = stdout.split('\n').filter(Boolean);
+
+        console.log(chalk.cyan.bold('🔗 Access URLs:\n'));
+
+        // Display URLs for known services
+        if (containers.some(c => c.includes('api'))) {
+            console.log(`  ${chalk.bold('API Server:')}      ${chalk.underline(getServiceURL('API'))}`);
+            console.log(`  ${chalk.bold('API Health:')}     ${chalk.underline(getServiceURL('API') + '/health')}\n`);
+        }
+
+        if (containers.some(c => c.includes('dashboard'))) {
+            console.log(`  ${chalk.bold('Dashboard:')}      ${chalk.underline(getServiceURL('DASHBOARD'))}\n`);
+        }
+
+        if (containers.some(c => c.includes('kafka-ui'))) {
+            console.log(`  ${chalk.bold('Kafka UI:')}       ${chalk.underline(getServiceURL('KAFKA_UI'))}\n`);
+        }
+
+        if (containers.some(c => c.includes('grafana'))) {
+            console.log(`  ${chalk.bold('Grafana:')}        ${chalk.underline(getServiceURL('GRAFANA'))}`);
+            console.log(`  ${chalk.gray('(default login: admin/admin)')}\n`);
+        }
+
+        console.log(chalk.cyan.bold('📦 Running Containers:\n'));
+        for (const container of containers) {
+            console.log(`  ${chalk.green('✓')} ${container}`);
+        }
+
+        console.log('\n' + chalk.cyan('To view logs:') + ' docker-compose logs -f');
+        console.log(chalk.cyan('To stop services:') + ' docker-compose down\n');
+        console.log(chalk.green('═'.repeat(60)) + '\n');
+
+    } catch (error) {
+        logWarning('Could not fetch container status');
+    }
+}
+
+/**
+ * Helper: Sleep for specified milliseconds
+ */
+function sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}

package/src/templates.ts

@@ -0,0 +1,203 @@
+// Docker Compose templates as constants
+
+export const INFRA_COMPOSE_TEMPLATE = `# ============================================
+# INFRA_HOST: Set this in .env to your machine's IP/hostname when running
+#             infrastructure on a separate system from application services.
+#             Default: host.docker.internal (for same-system deployment)
+# ============================================
+
+services:
+  # ============================================
+  # Infrastructure Services
+  # ============================================
+  mongo:
+    image: mongo:7.0
+    container_name: mongo
+    command: [ "--replSet", "rs0", "--bind_ip_all", "--port", "27017" ]
+    ports:
+      - 27017:27017
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    healthcheck:
+      test: echo "try { rs.status() } catch (err) { rs.initiate({_id:'rs0',members:[{_id:0,host:'{{INFRA_HOST}}:27017'}]}) }" | mongosh --port 27017 --quiet
+      interval: 5s
+      timeout: 30s
+      start_period: 0s
+      start_interval: 1s
+      retries: 30
+    volumes:
+      - "mongo_data:/data/db"
+      - "mongo_config:/data/configdb"
+
+  kafka:
+    image: apache/kafka-native
+    container_name: kafka
+    ports:
+      - "9092:9092"
+    environment:
+      # Configure listeners for both docker and host communication
+      KAFKA_LISTENERS: CONTROLLER://localhost:9091,HOST://0.0.0.0:9092,DOCKER://0.0.0.0:9093
+      KAFKA_ADVERTISED_LISTENERS: HOST://{{INFRA_HOST}}:9092,DOCKER://kafka:9093
+      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:PLAINTEXT,DOCKER:PLAINTEXT,HOST:PLAINTEXT
+
+      # Settings required for KRaft mode
+      KAFKA_NODE_ID: 1
+      KAFKA_PROCESS_ROLES: broker,controller
+      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
+      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@localhost:9091
+
+      # Listener to use for broker-to-broker communication
+      KAFKA_INTER_BROKER_LISTENER_NAME: DOCKER
+
+      # Required for a single node cluster
+      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
+
+      # Disable auto-topic creation - API server will create topics with correct partitions
+      KAFKA_AUTO_CREATE_TOPICS_ENABLE: "false"
+    volumes:
+      - "kafka_data:/var/lib/kafka/data"
+
+  kafka-ui:
+    image: kafbat/kafka-ui:main
+    container_name: kafka-ui
+    ports:
+      - 8080:8080
+    environment:
+      DYNAMIC_CONFIG_ENABLED: "true"
+      KAFKA_CLUSTERS_0_NAME: local
+      KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: kafka:9093
+    depends_on:
+      - kafka
+
+  redis:
+    image: redis:7-alpine
+    container_name: redis
+    ports:
+      - "6379:6379"
+    command: redis-server --appendonly yes
+    volumes:
+      - "redis_data:/data"
+    healthcheck:
+      test: [ "CMD", "redis-cli", "ping" ]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  # ============================================
+  # Observability Services
+  # ============================================
+
+  loki:
+    image: grafana/loki:2.9.0
+    container_name: loki
+    ports:
+      - "3100:3100"
+    command: -config.file=/etc/loki/local-config.yaml
+    volumes:
+      - "loki_data:/loki"
+    healthcheck:
+      test: [ "CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:3100/ready || exit 1" ]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  grafana:
+    image: grafana/grafana:10.2.0
+    container_name: grafana
+    ports:
+      - "3001:3000"
+    environment:
+      - GF_PATHS_PROVISIONING=/etc/grafana/provisioning
+      - GF_AUTH_ANONYMOUS_ENABLED=true
+      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
+      - GF_SECURITY_ADMIN_PASSWORD=admin
+    volumes:
+      - "grafana_data:/var/lib/grafana"
+    depends_on:
+      loki:
+        condition: service_healthy
+
+volumes:
+  mongo_data:
+  mongo_config:
+  kafka_data:
+  redis_data:
+  loki_data:
+  grafana_data:
+`;
+
+export const APP_COMPOSE_TEMPLATE = `services:
+  api:
+    image: ghcr.io/simplenotificationsystem/simplens-core:latest
+    container_name: api
+    ports:
+      - 3000:3000
+    env_file:
+      - .env
+    volumes:
+      - plugin-data:/app/.plugins
+      - ./simplens.config.yaml:/app/simplens.config.yaml:ro
+    command: [ "node", "dist/api/server.js" ]
+    restart: unless-stopped
+    healthcheck:
+      test: [ "CMD", "node", "-e", "require('http').get('http://localhost:3000/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))" ]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 10s
+
+  worker:
+    image: ghcr.io/simplenotificationsystem/simplens-core:latest
+    env_file:
+      - .env
+    command: [ "node", "dist/workers/worker.js" ]
+    restart: unless-stopped
+
+  notification_processor:
+    image: ghcr.io/simplenotificationsystem/simplens-core:latest
+    env_file:
+      - .env
+    volumes:
+      - plugin-data:/app/.plugins
+      - ./simplens.config.yaml:/app/simplens.config.yaml:ro
+    command: [ "node", "dist/processors/unified/unified.processor.js" ]
+    depends_on:
+      api:
+        condition: service_healthy
+    restart: unless-stopped
+
+  delayed_processor:
+    image: ghcr.io/simplenotificationsystem/simplens-core:latest
+    env_file:
+      - .env
+    command: [ "node", "dist/processors/delayed/delayed.processor.js" ]
+    restart: unless-stopped
+
+  recovery:
+    image: ghcr.io/simplenotificationsystem/simplens-core:latest
+    env_file:
+      - .env
+    command: [ "node", "dist/workers/recovery/recovery.service.js" ]
+    restart: unless-stopped
+
+  dashboard:
+    image: ghcr.io/simplenotificationsystem/simplens-dashboard:latest
+    ports:
+      - 3002:3002
+    container_name: dashboard
+    env_file:
+      - .env
+    environment:
+      PORT: \${DASHBOARD_PORT:-3002}
+      API_BASE_URL: http://api:\${PORT:-3000}
+      WEBHOOK_HOST: dashboard
+      WEBHOOK_PORT: \${DASHBOARD_PORT:-3002}
+    restart: unless-stopped
+
+volumes:
+  plugin-data:
+
+networks:
+  default:
+    name: simplens
+`;

package/src/types/domain.ts

@@ -0,0 +1,127 @@
+/**
+ * Domain type definitions for the onboarding system
+ */
+
+/**
+ * Plugin information returned by config-gen
+ */
+export interface PluginInfo {
+    /** Package name (e.g., '@simplens/nodemailer-gmail') */
+    package: string;
+    /** Display name */
+    name: string;
+    /** Description of what the plugin does */
+    description: string;
+}
+
+/**
+ * Infrastructure service option
+ */
+export interface InfraService {
+    /** Display name (e.g., 'MongoDB (Database)') */
+    name: string;
+    /** Service identifier (e.g., 'mongo') */
+    value: string;
+    /** Whether checked by default */
+    checked: boolean;
+}
+
+/**
+ * Environment variable definition
+ */
+export interface EnvVariable {
+    /** Environment variable key */
+    key: string;
+    /** Current or default value */
+    value: string;
+    /** Optional description/comment */
+    description?: string;
+    /** Whether this variable is required */
+    required: boolean;
+}
+
+/**
+ * Setup options provided via CLI or prompts
+ */
+export interface SetupOptions {
+    /** Whether to setup infrastructure services */
+    infra: boolean;
+    /** Environment configuration mode */
+    envMode: 'default' | 'interactive';
+    /** Target directory for setup */
+    targetDir: string;
+}
+
+/**
+ * Service definition for docker-compose generation
+ */
+export interface ServiceDefinition {
+    /** Service identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Docker compose YAML block */
+    dockerCompose: string;
+    /** Required volumes */
+    volumes: string[];
+    /** Service dependencies */
+    dependencies?: string[];
+    /** Whether service has health check */
+    healthCheck?: boolean;
+}
+
+/**
+ * SimplensConfig YAML structure
+ */
+export interface SimplensConfig {
+    providers: ProviderConfig[];
+}
+
+/**
+ * Provider configuration in simplens.config.yaml
+ */
+export interface ProviderConfig {
+    /** Package name */
+    package: string;
+    /** Provider ID */
+    id: string;
+    /** Required credentials as key-value pairs */
+    credentials: Record<string, string>;
+    /** Optional configuration */
+    optionalConfig?: Record<string, string | number | boolean>;
+}
+
+/**
+ * Docker compose file structure (simplified)
+ */
+export interface DockerComposeFile {
+    services: Record<string, DockerService>;
+    volumes?: Record<string, DockerVolume>;
+    networks?: Record<string, DockerNetwork>;
+}
+
+export interface DockerService {
+    image: string;
+    container_name?: string;
+    ports?: string[];
+    environment?: Record<string, string> | string[];
+    volumes?: string[];
+    command?: string | string[];
+    depends_on?: string[] | Record<string, { condition: string }>;
+    healthcheck?: {
+        test: string | string[];
+        interval?: string;
+        timeout?: string;
+        retries?: number;
+        start_period?: string;
+    };
+}
+
+export interface DockerVolume {
+    driver?: string;
+    driver_opts?: Record<string, string>;
+}
+
+export interface DockerNetwork {
+    driver?: string;
+}

package/src/types/errors.ts

@@ -0,0 +1,173 @@
+/**
+ * Custom error types for better error handling and troubleshooting
+ */
+
+/**
+ * Base error class for all onboarding errors
+ */
+export class OnboardingError extends Error {
+    constructor(
+        public readonly code: string,
+        message: string,
+        public readonly troubleshooting?: string
+    ) {
+        super(message);
+        this.name = 'OnboardingError';
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+
+/**
+ * Docker-related errors
+ */
+export class DockerError extends OnboardingError {
+    constructor(message: string, troubleshooting?: string) {
+        super('DOCKER_ERROR', message, troubleshooting);
+        this.name = 'DockerError';
+    }
+}
+
+export class DockerNotInstalledError extends DockerError {
+    constructor() {
+        super(
+            'Docker is not installed on this system',
+            'Please install Docker from: https://docs.docker.com/get-docker/'
+        );
+        this.name = 'DockerNotInstalledError';
+    }
+}
+
+export class DockerNotRunningError extends DockerError {
+    constructor() {
+        super(
+            'Docker daemon is not running',
+            'Please start Docker Desktop or Docker daemon, then try again'
+        );
+        this.name = 'DockerNotRunningError';
+    }
+}
+
+export class DockerPermissionError extends DockerError {
+    constructor() {
+        super(
+            'Permission denied when accessing Docker',
+            'Try running with sudo or add your user to the docker group:\n' +
+            '  sudo usermod -aG docker $USER\n' +
+            '  Then log out and log back in'
+        );
+        this.name = 'DockerPermissionError';
+    }
+}
+
+export class DockerComposeError extends DockerError {
+    constructor(operation: string, details?: string) {
+        super(
+            `Failed to ${operation} with docker-compose`,
+            details || 'Check docker-compose logs for more details:\n  docker-compose logs'
+        );
+        this.name = 'DockerComposeError';
+    }
+}
+
+/**
+ * File system errors
+ */
+export class FileSystemError extends OnboardingError {
+    constructor(message: string, public readonly path: string, troubleshooting?: string) {
+        super('FILESYSTEM_ERROR', message, troubleshooting);
+        this.name = 'FileSystemError';
+    }
+}
+
+export class DirectoryNotWritableError extends FileSystemError {
+    constructor(path: string) {
+        super(
+            `Directory is not writable: ${path}`,
+            path,
+            'Check directory permissions or choose a different directory'
+        );
+        this.name = 'DirectoryNotWritableError';
+    }
+}
+
+export class FileNotFoundError extends FileSystemError {
+    constructor(path: string) {
+        super(
+            `File not found: ${path}`,
+            path,
+            'Ensure the file exists or check the path'
+        );
+        this.name = 'FileNotFoundError';
+    }
+}
+
+/**
+ * Configuration errors
+ */
+export class ConfigurationError extends OnboardingError {
+    constructor(message: string, troubleshooting?: string) {
+        super('CONFIG_ERROR', message, troubleshooting);
+        this.name = 'ConfigurationError';
+    }
+}
+
+export class InvalidEnvironmentValueError extends ConfigurationError {
+    constructor(key: string, value: string, expectedFormat: string) {
+        super(
+            `Invalid value for ${key}: ${value}`,
+            `Expected format: ${expectedFormat}`
+        );
+        this.name = 'InvalidEnvironmentValueError';
+    }
+}
+
+export class PluginConfigurationError extends ConfigurationError {
+    constructor(pluginName: string, details: string) {
+        super(
+            `Failed to configure plugin ${pluginName}`,
+            details
+        );
+        this.name = 'PluginConfigurationError';
+    }
+}
+
+/**
+ * Service health errors
+ */
+export class ServiceHealthError extends OnboardingError {
+    constructor(serviceName: string, timeout: number) {
+        super(
+            'SERVICE_HEALTH_ERROR',
+            `Service '${serviceName}' did not become healthy within ${timeout}ms`,
+            `Check service logs:\n  docker-compose logs ${serviceName}\n\n` +
+            'Or check container status:\n  docker ps -a'
+        );
+        this.name = 'ServiceHealthError';
+    }
+}
+
+/**
+ * Type guard to check if an error is an OnboardingError
+ */
+export function isOnboardingError(error: unknown): error is OnboardingError {
+    return error instanceof OnboardingError;
+}
+
+/**
+ * Format error for user display
+ */
+export function formatErrorForUser(error: unknown): string {
+    if (isOnboardingError(error)) {
+        let message = `❌ ${error.message}`;
+        if (error.troubleshooting) {
+            message += `\n\n💡 Troubleshooting:\n${error.troubleshooting}`;
+        }
+        return message;
+    }
+    
+    if (error instanceof Error) {
+        return `❌ Unexpected error: ${error.message}`;
+    }
+    
+    return `❌ An unknown error occurred`;
+}

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export * from './errors.js';
+export * from './domain.js';

package/src/utils/index.ts

@@ -0,0 +1 @@
+export * from './logger.js';