@simplens/onboard 1.0.0

package/dist/validators.js

@@ -0,0 +1,180 @@
+import { execa } from 'execa';
+import { logSuccess, logWarning } from './utils.js';
+import { DockerNotInstalledError, DockerNotRunningError, DockerPermissionError, } from './types/errors.js';
+import { VALIDATION } from './config/constants.js';
+/**
+ * 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() {
+    try {
+        await execa('docker', ['--version']);
+    }
+    catch (error) {
+        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() {
+    try {
+        await execa('docker', ['ps']);
+    }
+    catch (error) {
+        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() {
+    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() {
+    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, value) {
+    // 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;
+}
+//# sourceMappingURL=validators.js.map

package/dist/validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.js","sourceRoot":"","sources":["../src/validators.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@simplens/onboard",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "simplens-onboard": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage"
+  },
+  "keywords": [
+    "simplens",
+    "notification",
+    "cli",
+    "onboard",
+    "setup"
+  ],
+  "author": "SimpleNS Team",
+  "license": "ISC",
+  "description": "CLI tool to setup SimpleNS instance on any AMD64 machine",
+  "devDependencies": {
+    "@types/figlet": "^1.7.0",
+    "@types/inquirer": "^9.0.7",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.19.30",
+    "@vitest/ui": "^4.0.18",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^14.0.2",
+    "execa": "^8.0.1",
+    "figlet": "^1.10.0",
+    "inquirer": "^9.2.12",
+    "js-yaml": "^4.1.0",
+    "ora": "^7.0.1"
+  }
+}

package/src/__tests__/errors.test.ts

@@ -0,0 +1,187 @@
+import { describe, it, expect } from 'vitest';
+import {
+    OnboardingError,
+    DockerNotInstalledError,
+    DockerNotRunningError,
+    DockerPermissionError,
+    DockerComposeError,
+    FileSystemError,
+    DirectoryNotWritableError,
+    isOnboardingError,
+    formatErrorForUser,
+} from '../types/errors.js';
+
+describe('error types', () => {
+    describe('OnboardingError', () => {
+        it('should create error with code and message', () => {
+            const error = new OnboardingError('TEST_CODE', 'Test message');
+
+            expect(error.code).toBe('TEST_CODE');
+            expect(error.message).toBe('Test message');
+            expect(error.name).toBe('OnboardingError');
+        });
+
+        it('should include troubleshooting when provided', () => {
+            const error = new OnboardingError(
+                'TEST_CODE',
+                'Test message',
+                'Try this fix'
+            );
+
+            expect(error.troubleshooting).toBe('Try this fix');
+        });
+
+        it('should have proper stack trace', () => {
+            const error = new OnboardingError('TEST', 'message');
+
+            expect(error.stack).toBeDefined();
+            expect(error.stack).toContain('OnboardingError');
+        });
+    });
+
+    describe('DockerNotInstalledError', () => {
+        it('should have correct message and troubleshooting', () => {
+            const error = new DockerNotInstalledError();
+
+            expect(error.message).toContain('not installed');
+            expect(error.troubleshooting).toContain('https://docs.docker.com/get-docker/');
+            expect(error.name).toBe('DockerNotInstalledError');
+        });
+    });
+
+    describe('DockerNotRunningError', () => {
+        it('should have correct message and troubleshooting', () => {
+            const error = new DockerNotRunningError();
+
+            expect(error.message).toContain('not running');
+            expect(error.troubleshooting).toContain('Docker daemon');
+            expect(error.name).toBe('DockerNotRunningError');
+        });
+    });
+
+    describe('DockerPermissionError', () => {
+        it('should have correct message and troubleshooting', () => {
+            const error = new DockerPermissionError();
+
+            expect(error.message).toContain('Permission denied');
+            expect(error.troubleshooting).toContain('usermod');
+            expect(error.name).toBe('DockerPermissionError');
+        });
+    });
+
+    describe('DockerComposeError', () => {
+        it('should include operation in message', () => {
+            const error = new DockerComposeError('start services');
+
+            expect(error.message).toContain('start services');
+            expect(error.name).toBe('DockerComposeError');
+        });
+
+        it('should use custom troubleshooting when provided', () => {
+            const error = new DockerComposeError('pull images', 'Check network connection');
+
+            expect(error.troubleshooting).toBe('Check network connection');
+        });
+
+        it('should have default troubleshooting', () => {
+            const error = new DockerComposeError('operation');
+
+            expect(error.troubleshooting).toContain('docker-compose logs');
+        });
+    });
+
+    describe('FileSystemError', () => {
+        it('should include path in error', () => {
+            const error = new FileSystemError(
+                'Cannot write',
+                '/path/to/file',
+                'Check permissions'
+            );
+
+            expect(error.path).toBe('/path/to/file');
+            expect(error.troubleshooting).toBe('Check permissions');
+        });
+    });
+
+    describe('DirectoryNotWritableError', () => {
+        it('should include path in message and error', () => {
+            const error = new DirectoryNotWritableError('/opt/app');
+
+            expect(error.message).toContain('/opt/app');
+            expect(error.path).toBe('/opt/app');
+            expect(error.troubleshooting).toContain('permissions');
+        });
+    });
+
+    describe('isOnboardingError', () => {
+        it('should return true for OnboardingError instances', () => {
+            const error = new OnboardingError('CODE', 'message');
+
+            expect(isOnboardingError(error)).toBe(true);
+        });
+
+        it('should return true for subclasses of OnboardingError', () => {
+            const error = new DockerNotInstalledError();
+
+            expect(isOnboardingError(error)).toBe(true);
+        });
+
+        it('should return false for regular Error', () => {
+            const error = new Error('regular error');
+
+            expect(isOnboardingError(error)).toBe(false);
+        });
+
+        it('should return false for non-error values', () => {
+            expect(isOnboardingError('string')).toBe(false);
+            expect(isOnboardingError(null)).toBe(false);
+            expect(isOnboardingError(undefined)).toBe(false);
+            expect(isOnboardingError({})).toBe(false);
+        });
+    });
+
+    describe('formatErrorForUser', () => {
+        it('should format OnboardingError with troubleshooting', () => {
+            const error = new OnboardingError(
+                'TEST',
+                'Something went wrong',
+                'Try this fix'
+            );
+
+            const formatted = formatErrorForUser(error);
+
+            expect(formatted).toContain('❌ Something went wrong');
+            expect(formatted).toContain('💡 Troubleshooting:');
+            expect(formatted).toContain('Try this fix');
+        });
+
+        it('should format OnboardingError without troubleshooting', () => {
+            const error = new OnboardingError('TEST', 'Something went wrong');
+
+            const formatted = formatErrorForUser(error);
+
+            expect(formatted).toBe('❌ Something went wrong');
+            expect(formatted).not.toContain('Troubleshooting');
+        });
+
+        it('should format regular Error', () => {
+            const error = new Error('Regular error message');
+
+            const formatted = formatErrorForUser(error);
+
+            expect(formatted).toContain('Unexpected error');
+            expect(formatted).toContain('Regular error message');
+        });
+
+        it('should handle non-Error values', () => {
+            const formatted = formatErrorForUser('some string');
+
+            expect(formatted).toBe('❌ An unknown error occurred');
+        });
+
+        it('should handle null/undefined', () => {
+            expect(formatErrorForUser(null)).toBe('❌ An unknown error occurred');
+            expect(formatErrorForUser(undefined)).toBe('❌ An unknown error occurred');
+        });
+    });
+});

package/src/__tests__/utils.test.ts

@@ -0,0 +1,142 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'fs';
+import os from 'os';
+import path from 'path';
+import {
+    fileExists,
+    writeFile,
+    readFile,
+    appendFile,
+} from '../utils.js';
+
+describe('utils - file operations', () => {
+    let tempDir: string;
+
+    beforeEach(async () => {
+        // Create a temporary directory for tests
+        tempDir = path.join(os.tmpdir(), `onboard-test-${Date.now()}`);
+        await fs.mkdir(tempDir, { recursive: true });
+    });
+
+    afterEach(async () => {
+        // Clean up temporary directory
+        try {
+            await fs.rm(tempDir, { recursive: true, force: true });
+        } catch (error) {
+            // Ignore cleanup errors
+        }
+    });
+
+    describe('fileExists', () => {
+        it('should return true for existing file', async () => {
+            const filePath = path.join(tempDir, 'test.txt');
+            await fs.writeFile(filePath, 'content');
+
+            expect(await fileExists(filePath)).toBe(true);
+        });
+
+        it('should return false for non-existing file', async () => {
+            const filePath = path.join(tempDir, 'nonexistent.txt');
+
+            expect(await fileExists(filePath)).toBe(false);
+        });
+
+        it('should return true for existing directory', async () => {
+            expect(await fileExists(tempDir)).toBe(true);
+        });
+    });
+
+    describe('writeFile', () => {
+        it('should write content to file', async () => {
+            const filePath = path.join(tempDir, 'write-test.txt');
+            const content = 'Hello, World!';
+
+            await writeFile(filePath, content);
+
+            const written = await fs.readFile(filePath, 'utf-8');
+            expect(written).toBe(content);
+        });
+
+        it('should create parent directories if they do not exist', async () => {
+            const filePath = path.join(tempDir, 'nested', 'dir', 'file.txt');
+            const content = 'Nested content';
+
+            await writeFile(filePath, content);
+
+            expect(await fileExists(filePath)).toBe(true);
+            const written = await fs.readFile(filePath, 'utf-8');
+            expect(written).toBe(content);
+        });
+
+        it('should overwrite existing file', async () => {
+            const filePath = path.join(tempDir, 'overwrite.txt');
+            
+            await fs.writeFile(filePath, 'original');
+            await writeFile(filePath, 'new content');
+
+            const written = await fs.readFile(filePath, 'utf-8');
+            expect(written).toBe('new content');
+        });
+    });
+
+    describe('readFile', () => {
+        it('should read file content', async () => {
+            const filePath = path.join(tempDir, 'read-test.txt');
+            const content = 'File content to read';
+            await fs.writeFile(filePath, content);
+
+            const read = await readFile(filePath);
+
+            expect(read).toBe(content);
+        });
+
+        it('should throw error for non-existing file', async () => {
+            const filePath = path.join(tempDir, 'nonexistent.txt');
+
+            await expect(readFile(filePath)).rejects.toThrow();
+        });
+
+        it('should handle UTF-8 content', async () => {
+            const filePath = path.join(tempDir, 'utf8.txt');
+            const content = 'Hello 世界 🌍';
+            await fs.writeFile(filePath, content);
+
+            const read = await readFile(filePath);
+
+            expect(read).toBe(content);
+        });
+    });
+
+    describe('appendFile', () => {
+        it('should append content to existing file', async () => {
+            const filePath = path.join(tempDir, 'append-test.txt');
+            await fs.writeFile(filePath, 'Line 1\n');
+
+            await appendFile(filePath, 'Line 2\n');
+
+            const content = await fs.readFile(filePath, 'utf-8');
+            expect(content).toBe('Line 1\nLine 2\n');
+        });
+
+        it('should create file if it does not exist', async () => {
+            const filePath = path.join(tempDir, 'new-append.txt');
+
+            await appendFile(filePath, 'First line\n');
+
+            expect(await fileExists(filePath)).toBe(true);
+            const content = await fs.readFile(filePath, 'utf-8');
+            expect(content).toBe('First line\n');
+        });
+
+        it('should handle multiple appends', async () => {
+            const filePath = path.join(tempDir, 'multi-append.txt');
+
+            await appendFile(filePath, 'Line 1\n');
+            await appendFile(filePath, 'Line 2\n');
+            await appendFile(filePath, 'Line 3\n');
+
+            const content = await fs.readFile(filePath, 'utf-8');
+            expect(content).toBe('Line 1\nLine 2\nLine 3\n');
+        });
+    });
+});