@simplens/onboard 1.0.0

package/src/utils/logger.ts

@@ -0,0 +1,118 @@
+import chalk from 'chalk';
+import { appendFile as fsAppendFile } from 'fs/promises';
+import path from 'path';
+import { FILES } from '../config/constants.js';
+
+/**
+ * Logging level
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+/**
+ * Logger configuration
+ */
+interface LoggerConfig {
+    verbose: boolean;
+    debug: boolean;
+    logFile?: string;
+}
+
+let loggerConfig: LoggerConfig = {
+    verbose: false,
+    debug: false,
+};
+
+/**
+ * Initialize logger with configuration
+ */
+export function initLogger(config: Partial<LoggerConfig>): void {
+    loggerConfig = { ...loggerConfig, ...config };
+}
+
+/**
+ * Get current logger configuration
+ */
+export function getLoggerConfig(): Readonly<LoggerConfig> {
+    return { ...loggerConfig };
+}
+
+/**
+ * Write log message to file if configured
+ */
+async function writeToLogFile(level: LogLevel, message: string): Promise<void> {
+    if (!loggerConfig.logFile) return;
+    
+    try {
+        const timestamp = new Date().toISOString();
+        const logEntry = `[${timestamp}] [${level.toUpperCase()}] ${message}\n`;
+        await fsAppendFile(loggerConfig.logFile, logEntry, 'utf-8');
+    } catch (error) {
+        // Silently fail on log file errors
+    }
+}
+
+/**
+ * Log debug message (only shown with --debug flag)
+ */
+export function logDebug(message: string): void {
+    if (loggerConfig.debug) {
+        console.log(chalk.gray(`🔧 ${message}`));
+    }
+    writeToLogFile('debug', message);
+}
+
+/**
+ * Log verbose message (shown with --verbose or --debug)
+ */
+export function logVerbose(message: string): void {
+    if (loggerConfig.verbose || loggerConfig.debug) {
+        console.log(chalk.cyan(`ℹ️  ${message}`));
+    }
+    writeToLogFile('info', message);
+}
+
+/**
+ * Log info message (always displayed)
+ */
+export function logInfo(message: string): void {
+    console.log(chalk.blue(`ℹ️  ${message}`));
+    writeToLogFile('info', message);
+}
+
+/**
+ * Log success message (always displayed)
+ */
+export function logSuccess(message: string): void {
+    console.log(chalk.green(`✅ ${message}`));
+    writeToLogFile('info', message);
+}
+
+/**
+ * Log warning message (always displayed)
+ */
+export function logWarning(message: string): void {
+    console.log(chalk.yellow(`⚠️  ${message}`));
+    writeToLogFile('warn', message);
+}
+
+/**
+ * Log error message (always displayed)
+ */
+export function logError(message: string): void {
+    console.log(chalk.red(`❌ ${message}`));
+    writeToLogFile('error', message);
+}
+
+/**
+ * Log command execution (debug level)
+ */
+export function logCommand(command: string, args: string[]): void {
+    logDebug(`Executing: ${command} ${args.join(' ')}`);
+}
+
+/**
+ * Log file operation (debug level)
+ */
+export function logFileOperation(operation: string, filePath: string): void {
+    logDebug(`${operation}: ${filePath}`);
+}

package/src/utils.ts

@@ -0,0 +1,105 @@
+import chalk from 'chalk';
+import { execa } from 'execa';
+import fs from 'fs/promises';
+import path from 'path';
+import figlet from 'figlet';
+
+// Re-export logger functions for backward compatibility
+export {
+    logSuccess,
+    logError,
+    logWarning,
+    logInfo,
+    logDebug,
+    logVerbose,
+    logCommand,
+    logFileOperation,
+    initLogger,
+    getLoggerConfig,
+} from './utils/logger.js';
+
+/**
+ * Display SimpleNS banner in blue using figlet
+ */
+export function displayBanner(): void {
+    const simpleNS = figlet.textSync('SimpleNS', {
+        font: 'Standard',
+        horizontalLayout: 'default',
+    });
+    
+    const onboard = figlet.textSync('Onboard', {
+        font: 'Standard',
+        horizontalLayout: 'default',
+    });
+
+    console.log(chalk.blue(simpleNS));
+    console.log(chalk.blue(onboard));
+    console.log('');
+}
+
+/**
+ * Execute a shell command with error handling
+ */
+export async function executeCommand(
+    command: string,
+    args: string[],
+    options?: { cwd?: string; silent?: boolean }
+): Promise<{ stdout: string; stderr: string }> {
+    // Import dynamically to avoid circular dependency
+    const { logCommand } = await import('./utils/logger.js');
+    
+    logCommand(command, args);
+    
+    try {
+        const result = await execa(command, args, {
+            cwd: options?.cwd || process.cwd(),
+            stdio: options?.silent ? 'pipe' : 'inherit',
+        });
+        return { stdout: result.stdout, stderr: result.stderr };
+    } catch (error: any) {
+        throw new Error(`Command failed: ${command} ${args.join(' ')}\n${error.message}`);
+    }
+}
+
+/**
+ * Check if file exists
+ */
+export async function fileExists(filePath: string): Promise<boolean> {
+    try {
+        await fs.access(filePath);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Write file content
+ */
+export async function writeFile(filePath: string, content: string): Promise<void> {
+    const { logFileOperation } = await import('./utils/logger.js');
+    
+    logFileOperation('Writing file', filePath);
+    
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(filePath, content, 'utf-8');
+}
+
+/**
+ * Read file content
+ */
+export async function readFile(filePath: string): Promise<string> {
+    return await fs.readFile(filePath, 'utf-8');
+}
+
+/**
+ * Append content to file
+ */
+export async function appendFile(filePath: string, content: string): Promise<void> {
+    // Ensure parent directory exists, similar to writeFile
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
+    
+    await fs.appendFile(filePath, content, 'utf-8');
+}

package/src/validators.ts

@@ -0,0 +1,192 @@
+import { execa } from 'execa';
+import { logError, logSuccess, logWarning } from './utils.js';
+import {
+    DockerNotInstalledError,
+    DockerNotRunningError,
+    DockerPermissionError,
+} from './types/errors.js';
+import { VALIDATION } from './config/constants.js';
+
+export type OSType = 'windows' | 'linux' | 'darwin';
+
+/**
+ * Checks if Docker is installed on the system by running `docker --version`.
+ * 
+ * @throws {DockerNotInstalledError} When Docker is not found in PATH or not installed
+ * 
+ * @example
+ * ```ts
+ * try {
+ *   await checkDockerInstalled();
+ *   console.log('Docker is available');
+ * } catch (error) {
+ *   // Handle DockerNotInstalledError
+ * }
+ * ```
+ */
+export async function checkDockerInstalled(): Promise<void> {
+    try {
+        await execa('docker', ['--version']);
+    } catch (error: any) {
+        throw new DockerNotInstalledError();
+    }
+}
+
+/**
+ * Checks if the Docker daemon is running by executing `docker ps`.
+ * Provides specific error types based on the failure reason.
+ * 
+ * @throws {DockerPermissionError} When user lacks permissions to access Docker socket
+ * @throws {DockerNotRunningError} When Docker daemon is not running or unreachable
+ * 
+ * @example
+ * ```ts
+ * try {
+ *   await checkDockerRunning();
+ * } catch (error) {
+ *   if (error instanceof DockerPermissionError) {
+ *     // Guide user to add sudo or docker group
+ *   }
+ * }
+ * ```
+ */
+export async function checkDockerRunning(): Promise<void> {
+    try {
+        await execa('docker', ['ps']);
+    } catch (error: any) {
+        const errorMessage = error.message?.toLowerCase() || '';
+        
+        if (errorMessage.includes('permission denied') || errorMessage.includes('eacces')) {
+            throw new DockerPermissionError();
+        }
+        
+        if (errorMessage.includes('cannot connect') || errorMessage.includes('is the docker daemon running')) {
+            throw new DockerNotRunningError();
+        }
+        
+        // Generic docker error
+        throw new DockerNotRunningError();
+    }
+}
+
+/**
+ * Detects the operating system platform.
+ * 
+ * @returns OS type: 'windows', 'darwin' (macOS), or 'linux'
+ * @note Defaults to 'linux' for unknown platforms
+ * 
+ * @example
+ * ```ts
+ * const os = detectOS();
+ * if (os === 'linux') {
+ *   // Linux-specific configuration
+ * }
+ * ```
+ */
+export function detectOS(): OSType {
+    const platform = process.platform;
+    if (platform === 'win32') return 'windows';
+    if (platform === 'linux') return 'linux';
+    if (platform === 'darwin') return 'darwin';
+    return 'linux'; // Default fallback
+}
+
+/**
+ * Validates all system prerequisites before starting the onboarding process.
+ * Checks Docker installation, daemon status, and detects the operating system.
+ * 
+ * @throws {DockerNotInstalledError} If Docker is not installed
+ * @throws {DockerNotRunningError} If Docker daemon is not running  
+ * @throws {DockerPermissionError} If user lacks Docker permissions
+ * 
+ * @example
+ * ```ts
+ * try {
+ *   await validatePrerequisites();
+ *   // Proceed with setup
+ * } catch (error) {
+ *   // Handle prerequisite errors
+ * }
+ * ```
+ */
+export async function validatePrerequisites(): Promise<void> {
+    console.log('\n🔍 Checking prerequisites...\n');
+
+    // Check Docker installation
+    try {
+        await checkDockerInstalled();
+        logSuccess('Docker is installed');
+    } catch (error) {
+        // Error will be caught by main() and displayed with troubleshooting
+        throw error;
+    }
+
+    // Check Docker daemon
+    try {
+        await checkDockerRunning();
+        logSuccess('Docker daemon is running');
+    } catch (error) {
+        // Error will be caught by main() and displayed with troubleshooting
+        throw error;
+    }
+
+    // Detect OS
+    const os = detectOS();
+    logSuccess(`Detected OS: ${os}`);
+
+    if (os === 'linux') {
+        logWarning('Linux detected: You may need to provide your machine IP for infra services.');
+    }
+}
+
+/**
+ * Validates environment variable values based on the variable name/type.
+ * Performs format-specific validation for URLs, ports, and security credentials.
+ * 
+ * @param key - Environment variable name (e.g., 'MONGO_URI', 'PORT', 'API_KEY')
+ * @param value - Value to validate
+ * @returns `true` if valid, `false` otherwise
+ * 
+ * @remarks
+ * Validation rules:
+ * - URLs: Must contain protocol (mongodb://, redis://)
+ * - Ports: Must be 1-65535
+ * - Secrets/Keys/Passwords: Must be at least 8 characters
+ * 
+ * @example
+ * ```ts
+ * validateEnvValue('MONGO_URI', 'mongodb://localhost:27017'); // true
+ * validateEnvValue('PORT', '3000'); // true
+ * validateEnvValue('API_KEY', 'short'); // false (too short)
+ * ```
+ */
+export function validateEnvValue(key: string, value: string): boolean {
+    // URL validation
+    if (key.includes('URL') || key.includes('URI')) {
+        if (!value) return false;
+        // Basic URL format check
+        if (key === 'MONGO_URI' && !value.includes('mongodb://')) {
+            return false;
+        }
+        if (key === 'REDIS_URL' && !value.includes('redis://')) {
+            return false;
+        }
+    }
+
+    // Port validation
+    if (key.includes('PORT')) {
+        const port = parseInt(value, 10);
+        if (isNaN(port) || port < VALIDATION.PORT_MIN || port > VALIDATION.PORT_MAX) {
+            return false;
+        }
+    }
+
+    // API Key validation (should not be empty for security)
+    if (key.includes('API_KEY') || key.includes('SECRET') || key.includes('PASSWORD')) {
+        if (!value || value.length < VALIDATION.MIN_PASSWORD_LENGTH) {
+            return false;
+        }
+    }
+
+    return true;
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: [
+        'node_modules/**',
+        'dist/**',
+        '**/*.test.ts',
+        '**/*.spec.ts',
+        'src/templates.ts', // Large constant file
+      ],
+    },
+    testTimeout: 10000,
+  },
+});