@simplens/onboard 1.0.0

package/src/index.ts

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import path from 'path';
+import inquirer from 'inquirer';
+import { displayBanner, logSuccess, logError, logInfo, initLogger, logDebug } from './utils.js';
+import { validatePrerequisites } from './validators.js';
+import {
+    promptInfraServices,
+    generateInfraCompose,
+    writeAppCompose,
+} from './infra.js';
+import {
+    promptEnvVariables,
+    generateEnvFile,
+    appendPluginEnv,
+} from './env-config.js';
+import {
+    fetchAvailablePlugins,
+    promptPluginSelection,
+    generatePluginConfig,
+    parseConfigCredentials,
+    promptPluginCredentials,
+} from './plugins.js';
+import {
+    promptStartServices,
+    startInfraServices,
+    waitForInfraHealth,
+    startAppServices,
+    displayServiceStatus,
+} from './services.js';
+
+const program = new Command();
+
+program
+    .name('@simplens/onboard')
+    .description('A CLI tool to setup a SimpleNS instance on your machine/server')
+    .version('1.0.0')
+    .option('--infra', 'Setup infrastructure services (MongoDB, Kafka, Redis, etc.)')
+    .option('--env <mode>', 'Environment setup mode: "default" or "interactive"')
+    .option('--dir <path>', 'Target directory for setup')
+    .parse(process.argv);
+
+const options = program.opts();
+
+/**
+ * Prompt for setup options if not provided via CLI args
+ */
+async function promptSetupOptions(): Promise<{
+    infra: boolean;
+    envMode: 'default' | 'interactive';
+    targetDir: string;
+}> {
+    const answers = await inquirer.prompt([
+        {
+            type: 'confirm',
+            name: 'infra',
+            message: 'Do you want to setup infrastructure services (MongoDB, Kafka, Redis, etc.)?',
+            default: true,
+            when: () => options.infra === undefined,
+        },
+        {
+            type: 'list',
+            name: 'envMode',
+            message: 'Select environment configuration mode:',
+            choices: [
+                { name: 'Default (use preset values, prompt only for critical)', value: 'default' },
+                { name: 'Interactive (prompt for all variables)', value: 'interactive' },
+            ],
+            default: 'default',
+            when: () => !options.env,
+        },
+        {
+            type: 'input',
+            name: 'targetDir',
+            message: 'Target directory for setup:',
+            default: process.cwd(),
+            when: () => !options.dir,
+        },
+    ]);
+
+    return {
+        infra: options.infra !== undefined ? options.infra : answers.infra,
+        envMode: options.env || answers.envMode || 'default',
+        targetDir: options.dir || answers.targetDir || process.cwd(),
+    };
+}
+
+/**
+ * Main onboarding workflow
+ */
+async function main() {
+    try {
+        // Display banner
+        displayBanner();
+
+        // Initialize logger based on CLI flags
+        const opts = program.opts();
+        initLogger({
+            verbose: opts.verbose || false,
+            debug: opts.debug || false,
+            logFile: opts.debug ? path.join(process.cwd(), 'onboard-debug.log') : undefined,
+        });
+
+        logDebug('Logger initialized');
+        logDebug(`CLI options: ${JSON.stringify(opts)}`);
+
+        // Prompt for setup options if not provided
+        const setupOptions = await promptSetupOptions();
+        
+        // Get target directory
+        const targetDir = path.resolve(setupOptions.targetDir);
+        logInfo(`Target directory: ${targetDir}`);
+        logDebug(`Resolved target directory: ${targetDir}`);
+
+        // Step 1: Validate prerequisites
+        await validatePrerequisites();
+
+        // Step 2: Infrastructure setup (if --infra flag is provided)
+        let selectedInfraServices: string[] = [];
+        let infraHost = 'host.docker.internal';
+
+        if (setupOptions.infra) {
+            logInfo('\n🏗️  Infrastructure Setup\n');
+            selectedInfraServices = await promptInfraServices();
+            infraHost = await generateInfraCompose(targetDir, selectedInfraServices);
+        } else {
+            logInfo('\n⏭️  Skipping infrastructure setup (use --infra to enable)');
+        }
+
+        // Always write app docker-compose
+        logInfo('\n📦 Application Services Setup\n');
+        await writeAppCompose(targetDir);
+
+        // Step 3: Environment configuration
+        logInfo('\n⚙️  Environment Configuration\n');
+        const envMode = setupOptions.envMode;
+        const envVars = await promptEnvVariables(envMode, selectedInfraServices, infraHost);
+        await generateEnvFile(targetDir, envVars);
+
+        // Step 4: Plugin installation
+        logInfo('\n🔌 Plugin Installation\n');
+        const availablePlugins = await fetchAvailablePlugins();
+        const selectedPlugins = await promptPluginSelection(availablePlugins);
+
+        if (selectedPlugins.length > 0) {
+            await generatePluginConfig(targetDir, selectedPlugins);
+
+            // Extract and prompt for plugin credentials
+            const configPath = path.join(targetDir, 'simplens.config.yaml');
+            const credentialKeys = await parseConfigCredentials(configPath);
+            
+            if (credentialKeys.length > 0) {
+                const pluginCreds = await promptPluginCredentials(credentialKeys);
+                await appendPluginEnv(targetDir, pluginCreds);
+            }
+        }
+
+        // Step 5: Service orchestration
+        logInfo('\n🚀 Service Orchestration\n');
+        const shouldStart = await promptStartServices();
+
+        if (shouldStart) {
+            // Start infra services first (if --infra was used)
+            if (setupOptions.infra && selectedInfraServices.length > 0) {
+                await startInfraServices(targetDir);
+                await waitForInfraHealth(targetDir);
+            }
+
+            // Start app services
+            await startAppServices(targetDir);
+
+            // Display service status
+            await displayServiceStatus();
+        } else {
+            logInfo('Services not started. You can start them later with:');
+            if (setupOptions.infra) {
+                console.log('  docker-compose -f docker-compose.infra.yaml up -d');
+            }
+            console.log('  docker-compose up -d\n');
+        }
+
+        // Final success message
+        logSuccess('\n🎉 SimpleNS onboarding completed successfully!\n');
+
+    } catch (error: any) {
+        // Import at top of file
+        const { formatErrorForUser } = await import('./types/errors.js');
+        
+        console.log('\n' + formatErrorForUser(error));
+        
+        // Log full error to stderr for debugging
+        if (process.env.DEBUG) {
+            console.error('\nFull error details:');
+            console.error(error);
+        }
+        
+        process.exit(1);
+    }
+}
+
+// Run main function
+main();

package/src/infra.ts

@@ -0,0 +1,300 @@
+import inquirer from 'inquirer';
+import { detectOS } from './validators.js';
+import { INFRA_COMPOSE_TEMPLATE, APP_COMPOSE_TEMPLATE } from './templates.js';
+import { writeFile, logInfo, logSuccess, logWarning } from './utils.js';
+import path from 'path';
+import type { InfraService } from './types/domain.js';
+
+const INFRA_SERVICES: InfraService[] = [
+    { name: 'MongoDB (Database)', value: 'mongo', checked: true },
+    { name: 'Kafka (Message Queue)', value: 'kafka', checked: true },
+    { name: 'Kafka UI (Dashboard)', value: 'kafka-ui', checked: true },
+    { name: 'Redis (Cache)', value: 'redis', checked: true },
+    { name: 'Loki (Log Aggregation)', value: 'loki', checked: false },
+    { name: 'Grafana (Observability Dashboard)', value: 'grafana', checked: false },
+];
+
+/**
+ * Prompts user to select which infrastructure services to deploy.
+ * Services include MongoDB, Kafka, Redis, Loki, and Grafana.
+ * 
+ * @returns Array of selected service IDs (e.g., ['mongo', 'kafka', 'redis'])
+ * @throws Error if no services are selected
+ * 
+ * @example
+ * ```ts
+ * const services = await promptInfraServices();
+ * // Returns: ['mongo', 'kafka', 'kafka-ui', 'redis']
+ * ```
+ */
+export async function promptInfraServices(): Promise<string[]> {
+    const answer = await inquirer.prompt<{ services: string[] }>([
+        {
+            type: 'checkbox',
+            name: 'services',
+            message: 'Select infrastructure services to run:',
+            choices: INFRA_SERVICES,
+            validate: (input: string[]) => {
+                if (input.length === 0) {
+                    return 'Please select at least one service';
+                }
+                return true;
+            },
+        },
+    ]);
+
+    return answer.services;
+}
+
+/**
+ * Get infrastructure host based on OS
+ */
+export function getInfraHost(): string {
+    // const os = detectOS();
+
+    // if (os === 'linux') {
+    //     logWarning('Linux detected: host.docker.internal does not work by default.');
+        
+    //     const answer = await inquirer.prompt<{ hostChoice: string; customHost?: string }>([
+    //         {
+    //             type: 'list',
+    //             name: 'hostChoice',
+    //             message: 'Select host configuration:',
+    //             choices: [
+    //                 { name: 'Use Docker bridge IP (172.17.0.1)', value: '172.17.0.1' },
+    //                 { name: 'Enter custom IP/hostname', value: 'custom' },
+    //             ],
+    //         },
+    //         {
+    //             type: 'input',
+    //             name: 'customHost',
+    //             message: 'Enter your machine IP or hostname:',
+    //             when: (answers) => answers.hostChoice === 'custom',
+    //             validate: (input: string) => {
+    //                 if (!input || input.trim().length === 0) {
+    //                     return 'Please enter a valid IP or hostname';
+    //                 }
+    //                 return true;
+    //             },
+    //         },
+    //     ]);
+
+    //     return answer.hostChoice === 'custom' ? answer.customHost! : answer.hostChoice;
+    // }
+
+    // For Windows, linux and macOS, use host.docker.internal
+    return 'host.docker.internal';
+}
+
+/**
+ * Service chunk definitions - each service as a complete block
+ */
+const SERVICE_CHUNKS: Record<string, string> = {
+    'mongo': `  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': `  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': `  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': `  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`,
+    
+    'loki': `  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': `  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`,
+};
+
+/**
+ * Service-to-volumes mapping
+ */
+const SERVICE_VOLUMES: Record<string, string[]> = {
+    'mongo': ['mongo_data', 'mongo_config'],
+    'kafka': ['kafka_data'],
+    'kafka-ui': [],
+    'redis': ['redis_data'],
+    'loki': ['loki_data'],
+    'grafana': ['grafana_data'],
+};
+
+/**
+ * Build docker-compose content from selected services
+ */
+function buildInfraCompose(selectedServices: string[]): string {
+    // Header
+    const header = `# ============================================
+# 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
+  # ============================================`;
+    
+    // Assemble selected service chunks
+    const serviceBlocks: string[] = [];
+    for (const service of selectedServices) {
+        if (SERVICE_CHUNKS[service]) {
+            serviceBlocks.push(SERVICE_CHUNKS[service]);
+        }
+    }
+    
+    // Collect volumes for selected services
+    const volumeSet = new Set<string>();
+    for (const service of selectedServices) {
+        const volumes = SERVICE_VOLUMES[service] || [];
+        volumes.forEach(v => volumeSet.add(v));
+    }
+    
+    // Build volumes section
+    const volumeLines: string[] = ['', 'volumes:'];
+    for (const volume of Array.from(volumeSet).sort()) {
+        volumeLines.push(`  ${volume}:`);
+    }
+    
+    // Build networks section with custom default network name
+    const networkLines: string[] = ['', 'networks:', '  default:', '    name: simplens'];
+    
+    // Combine all parts
+    return [
+        header,
+        serviceBlocks.join('\n\n'),
+        volumeLines.join('\n'),
+        networkLines.join('\n'),
+    ].join('\n');
+}
+
+/**
+ * Replace INFRA_HOST placeholder in template
+ */
+export function replaceInfraHost(template: string, infraHost: string): string {
+    return template.replace(/\{\{INFRA_HOST\}\}/g, infraHost);
+}
+
+/**
+ * Generate and write docker-compose.infra.yaml
+ */
+export async function generateInfraCompose(
+    targetDir: string,
+    selectedServices: string[]
+): Promise<string> {
+    logInfo('Generating docker-compose.infra.yaml...');
+
+    // Get infrastructure host
+    const infraHost = getInfraHost();
+    logSuccess(`Using infrastructure host: ${infraHost}`);
+
+    // Build compose content from service chunks
+    let infraContent = buildInfraCompose(selectedServices);
+    
+    // Replace host placeholder
+    infraContent = replaceInfraHost(infraContent, infraHost);
+
+    // Write infrastructure compose file
+    const infraPath = path.join(targetDir, 'docker-compose.infra.yaml');
+    await writeFile(infraPath, infraContent);
+    logSuccess('Generated docker-compose.infra.yaml');
+
+    // Return infraHost for env configuration
+    return infraHost;
+}
+
+/**
+ * Write app docker-compose.yaml
+ */
+export async function writeAppCompose(targetDir: string): Promise<void> {
+    const appPath = path.join(targetDir, 'docker-compose.yaml');
+    await writeFile(appPath, APP_COMPOSE_TEMPLATE);
+    logSuccess('Generated docker-compose.yaml');
+}

package/src/plugins.ts

@@ -0,0 +1,190 @@
+import inquirer from 'inquirer';
+import { execa } from 'execa';
+import yaml from 'js-yaml';
+import { readFile, logInfo, logSuccess, logError, logWarning } from './utils.js';
+import path from 'path';
+import type { PluginInfo, SimplensConfig } from './types/domain.js';
+
+/**
+ * Fetches available SimpleNS plugins using the config-gen CLI tool.
+ * Falls back to default plugins if fetching fails.
+ * 
+ * @returns Array of available plugin information
+ * 
+ * @remarks
+ * Uses `npx @simplens/config-gen list --official` to fetch plugins.
+ * Default fallback plugins: mock, nodemailer-gmail, resend
+ * 
+ * @example
+ * ```ts
+ * const plugins = await fetchAvailablePlugins();
+ * // Returns: [{ package: '@simplens/mock', name: 'Mock Provider', ... }, ...]
+ * ```
+ */
+export async function fetchAvailablePlugins(): Promise<PluginInfo[]> {
+    logInfo('Fetching available plugins...');
+
+    try {
+        // Execute config-gen list command
+        const { stdout } = await execa('npx', ['@simplens/config-gen', 'list', '--official'], {
+            stdio: 'pipe',
+        });
+
+        // Parse output to extract plugins
+        // Expected format: "  @simplens/package-name      Plugin Name"
+        const plugins: PluginInfo[] = [];
+        const lines = stdout.split('\n');
+
+        for (const line of lines) {
+            // Match plugin lines (starts with @simplens/)
+            const match = line.match(/^\s+(@simplens\/[\w-]+)\s+(.+)$/);
+            if (match) {
+                const [, packageName, rest] = match;
+                // Extract name and description
+                const parts = rest.split(/\s{2,}/); // Split by multiple spaces
+                plugins.push({
+                    package: packageName.trim(),
+                    name: parts[0]?.trim() || packageName,
+                    description: parts[1]?.trim() || '',
+                });
+            }
+        }
+
+        logSuccess(`Found ${plugins.length} available plugins`);
+        return plugins;
+    } catch (error: any) {
+        logWarning('Could not fetch plugins list. Using defaults.');
+        // Return default plugins as fallback
+        return [
+            { package: '@simplens/mock', name: 'Mock Provider', description: 'Mock notification provider for testing' },
+            { package: '@simplens/nodemailer-gmail', name: 'Gmail', description: 'Send emails via Gmail' },
+            { package: '@simplens/resend', name: 'Resend', description: 'Send emails via Resend' },
+        ];
+    }
+}
+
+/**
+ * Prompt user to select plugins
+ */
+export async function promptPluginSelection(availablePlugins: PluginInfo[]): Promise<string[]> {
+    if (availablePlugins.length === 0) {
+        logWarning('No plugins available to select.');
+        return [];
+    }
+
+    const answer = await inquirer.prompt<{ plugins: string[] }>([
+        {
+            type: 'checkbox',
+            name: 'plugins',
+            message: 'Select plugins to install:',
+            choices: availablePlugins.map(p => ({
+                name: `${p.name} (${p.package}) - ${p.description}`,
+                value: p.package,
+                checked: p.package === '@simplens/mock', // Mock checked by default
+            })),
+        },
+    ]);
+
+    return answer.plugins;
+}
+
+/**
+ * Generate plugin configuration using config-gen
+ */
+export async function generatePluginConfig(
+    targetDir: string,
+    selectedPlugins: string[]
+): Promise<void> {
+    if (selectedPlugins.length === 0) {
+        logInfo('No plugins selected, skipping config generation.');
+        return;
+    }
+
+    logInfo(`Generating configuration for ${selectedPlugins.length} plugin(s)...`);
+
+    try {
+        const configPath = path.join(targetDir, 'simplens.config.yaml');
+        
+        // Execute config-gen for all selected plugins
+        // Use relative path to avoid WSL path issues when npx runs Windows binaries
+        await execa(
+            'npx',
+            ['@simplens/config-gen', 'gen', ...selectedPlugins, '-o', 'simplens.config.yaml'],
+            { cwd: targetDir, stdio: 'inherit' }
+        );
+
+        logSuccess('Generated simplens.config.yaml');
+    } catch (error: any) {
+        logError('Failed to generate plugin configuration');
+        throw error;
+    }
+}
+
+/**
+ * Parse simplens.config.yaml to extract credential keys
+ */
+export async function parseConfigCredentials(configPath: string): Promise<string[]> {
+    try {
+        const content = await readFile(configPath);
+        const config: any = yaml.load(content);
+
+        const credentialKeys = new Set<string>();
+
+        // Extract credential keys from providers (ONLY from credentials, not optionalConfig)
+        if (config.providers && Array.isArray(config.providers)) {
+            for (const provider of config.providers) {
+                if (provider.credentials && typeof provider.credentials === 'object') {
+                    for (const [key, value] of Object.entries(provider.credentials)) {
+                        // Extract env var name from ${ENV_VAR} format
+                        if (typeof value === 'string' && value.startsWith('${') && value.endsWith('}')) {
+                            const envVar = value.slice(2, -1);
+                            credentialKeys.add(envVar);
+                        }
+                    }
+                }
+                // NOTE: We intentionally skip optionalConfig - those are optional!
+            }
+        }
+
+        return Array.from(credentialKeys);
+    } catch (error) {
+        logWarning('Could not parse config file for credentials');
+        return [];
+    }
+}
+
+/**
+ * Prompt for plugin-specific credentials
+ */
+export async function promptPluginCredentials(credentialKeys: string[]): Promise<Map<string, string>> {
+    if (credentialKeys.length === 0) {
+        logInfo('No plugin credentials required.');
+        return new Map();
+    }
+
+    logInfo('Configuring plugin credentials...');
+
+    const result = new Map<string, string>();
+
+    for (const key of credentialKeys) {
+        const answer = await inquirer.prompt<{ value: string }>([
+            {
+                type: key.toLowerCase().includes('password') || key.toLowerCase().includes('key') 
+                    ? 'password' 
+                    : 'input',
+                name: 'value',
+                message: `${key}:`,
+                validate: (input: string) => {
+                    if (!input || input.trim().length === 0) {
+                        return `${key} is required`;
+                    }
+                    return true;
+                },
+            },
+        ]);
+        result.set(key, answer.value);
+    }
+
+    logSuccess('Plugin credentials configured');
+    return result;
+}