@coffeerunhobby/mcp-ha-connect 0.5.0

package/tests/utils/config-validations.test.ts

@@ -0,0 +1,289 @@
+/**
+ * Configuration validation utilities tests
+ */
+
+import { describe, it, expect } from 'vitest';
+import { isValidBindAddress, isValidOrigin } from '../../src/utils/config-validations.js';
+
+describe('isValidBindAddress', () => {
+  describe('Valid IPv4 addresses', () => {
+    it('should accept localhost 127.0.0.1', () => {
+      expect(isValidBindAddress('127.0.0.1')).toBe(true);
+    });
+
+    it('should accept 0.0.0.0 (all interfaces)', () => {
+      expect(isValidBindAddress('0.0.0.0')).toBe(true);
+    });
+
+    it('should accept private IP 192.168.1.1', () => {
+      expect(isValidBindAddress('192.168.1.1')).toBe(true);
+    });
+
+    it('should accept private IP 10.0.0.1', () => {
+      expect(isValidBindAddress('10.0.0.1')).toBe(true);
+    });
+
+    it('should accept private IP 172.16.0.1', () => {
+      expect(isValidBindAddress('172.16.0.1')).toBe(true);
+    });
+
+    it('should accept maximum octet values 255.255.255.255', () => {
+      expect(isValidBindAddress('255.255.255.255')).toBe(true);
+    });
+
+    it('should accept public IP 8.8.8.8', () => {
+      expect(isValidBindAddress('8.8.8.8')).toBe(true);
+    });
+  });
+
+  describe('Invalid IPv4 addresses', () => {
+    it('should reject octet > 255', () => {
+      expect(isValidBindAddress('256.0.0.1')).toBe(false);
+      expect(isValidBindAddress('192.168.256.1')).toBe(false);
+    });
+
+    it('should reject negative octets', () => {
+      expect(isValidBindAddress('-1.0.0.1')).toBe(false);
+    });
+
+    it('should reject too few octets', () => {
+      expect(isValidBindAddress('192.168.1')).toBe(false);
+    });
+
+    it('should reject too many octets', () => {
+      expect(isValidBindAddress('192.168.1.1.1')).toBe(false);
+    });
+
+    it('should reject non-numeric octets', () => {
+      expect(isValidBindAddress('abc.def.ghi.jkl')).toBe(false);
+    });
+
+    it('should reject empty string', () => {
+      expect(isValidBindAddress('')).toBe(false);
+    });
+
+    it('should reject hostnames', () => {
+      expect(isValidBindAddress('localhost')).toBe(false);
+    });
+  });
+
+  describe('Valid IPv6 addresses', () => {
+    it('should accept localhost ::1', () => {
+      expect(isValidBindAddress('::1')).toBe(true);
+    });
+
+    it('should accept all interfaces ::', () => {
+      expect(isValidBindAddress('::')).toBe(true);
+    });
+
+    it('should accept full IPv6 address', () => {
+      expect(isValidBindAddress('2001:0db8:85a3:0000:0000:8a2e:0370:7334')).toBe(true);
+    });
+
+    it('should accept compressed IPv6 address', () => {
+      expect(isValidBindAddress('2001:db8::1')).toBe(true);
+    });
+
+    it('should accept link-local address', () => {
+      expect(isValidBindAddress('fe80::1')).toBe(true);
+    });
+  });
+
+  describe('Invalid IPv6 addresses', () => {
+    it('should reject malformed IPv6', () => {
+      expect(isValidBindAddress('gggg::1')).toBe(false);
+    });
+
+    it('should use simplified IPv6 validation', () => {
+      // Note: The current implementation uses a simplified IPv6 regex
+      // For strict validation, consider using a more comprehensive validator
+      // This test documents the current behavior
+      expect(isValidBindAddress(':::1')).toBe(true); // Simplified regex accepts this
+    });
+  });
+});
+
+describe('isValidOrigin', () => {
+  describe('Valid origins', () => {
+    it('should accept wildcard *', () => {
+      expect(isValidOrigin('*')).toBe(true);
+    });
+
+    it('should accept localhost', () => {
+      expect(isValidOrigin('localhost')).toBe(true);
+    });
+
+    it('should accept 127.0.0.1', () => {
+      expect(isValidOrigin('127.0.0.1')).toBe(true);
+    });
+
+    it('should accept ::1', () => {
+      expect(isValidOrigin('::1')).toBe(true);
+    });
+
+    it('should accept full URL with http', () => {
+      expect(isValidOrigin('http://localhost:3000')).toBe(true);
+    });
+
+    it('should accept full URL with https', () => {
+      expect(isValidOrigin('https://example.com')).toBe(true);
+    });
+
+    it('should accept URL with port', () => {
+      expect(isValidOrigin('http://192.168.0.10:8080')).toBe(true);
+    });
+
+    it('should accept simple hostname', () => {
+      expect(isValidOrigin('example.com')).toBe(true);
+    });
+
+    it('should accept hostname with subdomain', () => {
+      expect(isValidOrigin('api.example.com')).toBe(true);
+    });
+
+    it('should accept hostname with hyphen', () => {
+      expect(isValidOrigin('my-app.example.com')).toBe(true);
+    });
+
+    it('should accept IP address as origin', () => {
+      expect(isValidOrigin('192.168.1.100')).toBe(true);
+    });
+  });
+
+  describe('Invalid origins', () => {
+    it('should reject empty string', () => {
+      expect(isValidOrigin('')).toBe(false);
+    });
+
+    it('should reject spaces', () => {
+      expect(isValidOrigin('  ')).toBe(false);
+    });
+
+    it('should reject special characters not allowed in hostnames', () => {
+      expect(isValidOrigin('invalid@origin')).toBe(false);
+    });
+
+    it('should reject invalid URL protocol', () => {
+      expect(isValidOrigin('ftp://example.com')).toBe(true); // URL is valid even if protocol is unusual
+    });
+  });
+
+  describe('Edge cases', () => {
+    it('should handle URL with path', () => {
+      expect(isValidOrigin('http://example.com/path')).toBe(true);
+    });
+
+    it('should handle URL with query string', () => {
+      expect(isValidOrigin('http://example.com?query=value')).toBe(true);
+    });
+
+    it('should handle URL with hash', () => {
+      expect(isValidOrigin('http://example.com#hash')).toBe(true);
+    });
+
+    it('should handle mixed case', () => {
+      expect(isValidOrigin('HTTP://EXAMPLE.COM')).toBe(true);
+    });
+
+    it('should handle IPv6 in URL', () => {
+      expect(isValidOrigin('http://[::1]:8080')).toBe(true);
+    });
+  });
+
+  describe('Common use cases', () => {
+    it('should accept development origins', () => {
+      const devOrigins = [
+        'http://mcpserver.10.0.0.18.nip.io:3000',
+        'http://localhost:8080',
+        'http://127.0.0.1:8080',
+        'localhost',
+      ];
+
+      for (const origin of devOrigins) {
+        expect(isValidOrigin(origin)).toBe(true);
+      }
+    });
+
+    it('should accept production origins', () => {
+      const prodOrigins = [
+        'https://example.com',
+        'https://www.example.com',
+        'https://app.example.com',
+      ];
+
+      for (const origin of prodOrigins) {
+        expect(isValidOrigin(origin)).toBe(true);
+      }
+    });
+
+    it('should accept local network origins', () => {
+      const localOrigins = [
+        'http://192.168.0.10:8080',
+        'http://10.0.0.5:3000',
+        '192.168.1.100',
+      ];
+
+      for (const origin of localOrigins) {
+        expect(isValidOrigin(origin)).toBe(true);
+      }
+    });
+  });
+
+  describe('Security considerations', () => {
+    it('should allow restricting to specific domains', () => {
+      const allowedOrigins = [
+        'https://app.example.com',
+        'https://admin.example.com',
+      ];
+
+      const testOrigin = 'https://app.example.com';
+      expect(isValidOrigin(testOrigin)).toBe(true);
+      expect(allowedOrigins).toContain(testOrigin);
+    });
+
+    it('should support localhost-only configuration', () => {
+      const localhostOrigins = [
+        'localhost',
+        '127.0.0.1',
+        '::1',
+      ];
+
+      for (const origin of localhostOrigins) {
+        expect(isValidOrigin(origin)).toBe(true);
+      }
+    });
+
+    it('should support wildcard for development', () => {
+      const allowAll = '*';
+      expect(isValidOrigin(allowAll)).toBe(true);
+    });
+  });
+
+  describe('Integration with config', () => {
+    it('should validate comma-separated origins', () => {
+      const originsString = 'http://mcpserver.10.0.0.18.nip.io:3000,http://192.168.0.10:8080,localhost';
+      const origins = originsString.split(',').map(s => s.trim());
+
+      for (const origin of origins) {
+        expect(isValidOrigin(origin)).toBe(true);
+      }
+    });
+
+    it('should detect invalid origin in list', () => {
+      const originsString = 'http://mcpserver.10.0.0.18.nip.io:3000,invalid@origin,localhost';
+      const origins = originsString.split(',').map(s => s.trim());
+
+      const invalidOrigin = origins.find(origin => !isValidOrigin(origin));
+      expect(invalidOrigin).toBe('invalid@origin');
+    });
+
+    it('should handle whitespace in origin list', () => {
+      const originsString = ' http://mcpserver.10.0.0.18.nip.io:3000 , localhost ';
+      const origins = originsString.split(',').map(s => s.trim()).filter(Boolean);
+
+      for (const origin of origins) {
+        expect(isValidOrigin(origin)).toBe(true);
+      }
+    });
+  });
+});

package/tests/utils/logger.test.ts

@@ -0,0 +1,327 @@
+/**
+ * Logger tests
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { initLogger, setLevel, logger } from '../../src/utils/logger.js';
+import type { LogLevel, LogFormat } from '../../src/utils/logger.js';
+
+describe('Logger', () => {
+  beforeEach(() => {
+    // Reset to default configuration
+    initLogger('info', 'plain', false);
+  });
+
+  describe('initLogger', () => {
+    it('should initialize with default level and format', () => {
+      initLogger('info', 'plain', false);
+
+      // Logger should be initialized without errors
+      expect(logger).toBeDefined();
+      expect(logger.info).toBeDefined();
+      expect(logger.debug).toBeDefined();
+      expect(logger.warn).toBeDefined();
+      expect(logger.error).toBeDefined();
+    });
+
+    it('should support all log levels', () => {
+      const levels: LogLevel[] = ['debug', 'info', 'warn', 'error', 'silent'];
+
+      for (const level of levels) {
+        expect(() => initLogger(level, 'plain', false)).not.toThrow();
+      }
+    });
+
+    it('should support all log formats', () => {
+      const formats: LogFormat[] = ['plain', 'json', 'gcp-json'];
+
+      for (const format of formats) {
+        expect(() => initLogger('info', format, false)).not.toThrow();
+      }
+    });
+
+    it('should configure stderr output when useStderr is true', () => {
+      expect(() => initLogger('info', 'plain', true)).not.toThrow();
+
+      // Logger should be configured to use stderr
+    });
+
+    it('should configure stdout output when useStderr is false', () => {
+      expect(() => initLogger('info', 'plain', false)).not.toThrow();
+
+      // Logger should be configured to use stdout
+    });
+  });
+
+  describe('setLevel', () => {
+    it('should change log level dynamically', () => {
+      initLogger('info', 'plain', false);
+
+      expect(() => setLevel('debug')).not.toThrow();
+      expect(() => setLevel('warn')).not.toThrow();
+      expect(() => setLevel('error')).not.toThrow();
+    });
+
+    it('should accept all valid log levels', () => {
+      const levels: LogLevel[] = ['debug', 'info', 'warn', 'error', 'silent'];
+
+      for (const level of levels) {
+        expect(() => setLevel(level)).not.toThrow();
+      }
+    });
+  });
+
+  describe('Log methods', () => {
+    it('should have debug method', () => {
+      expect(typeof logger.debug).toBe('function');
+      expect(() => logger.debug('Test debug message')).not.toThrow();
+    });
+
+    it('should have info method', () => {
+      expect(typeof logger.info).toBe('function');
+      expect(() => logger.info('Test info message')).not.toThrow();
+    });
+
+    it('should have warn method', () => {
+      expect(typeof logger.warn).toBe('function');
+      expect(() => logger.warn('Test warn message')).not.toThrow();
+    });
+
+    it('should have error method', () => {
+      expect(typeof logger.error).toBe('function');
+      expect(() => logger.error('Test error message')).not.toThrow();
+    });
+  });
+
+  describe('Log with metadata', () => {
+    it('should log with metadata object', () => {
+      const metadata = {
+        userId: 'user-123',
+        requestId: 'req-456',
+        duration: 123,
+      };
+
+      expect(() => logger.info('Test message', metadata)).not.toThrow();
+    });
+
+    it('should handle Error objects in metadata', () => {
+      const error = new Error('Test error');
+      const metadata = {
+        error,
+        context: 'test',
+      };
+
+      expect(() => logger.error('Error occurred', metadata)).not.toThrow();
+    });
+
+    it('should handle nested objects in metadata', () => {
+      const metadata = {
+        config: {
+          baseUrl: 'http://example.com',
+          timeout: 30000,
+        },
+        user: {
+          id: 'user-123',
+          name: 'Test User',
+        },
+      };
+
+      expect(() => logger.info('Complex metadata', metadata)).not.toThrow();
+    });
+
+    it('should handle arrays in metadata', () => {
+      const metadata = {
+        entities: ['light.living_room', 'sensor.temperature'],
+        tags: ['home', 'automation'],
+      };
+
+      expect(() => logger.info('Array metadata', metadata)).not.toThrow();
+    });
+
+    it('should handle empty metadata', () => {
+      expect(() => logger.info('No metadata')).not.toThrow();
+      expect(() => logger.info('Empty metadata', {})).not.toThrow();
+    });
+  });
+
+  describe('Log formats', () => {
+    it('should format plain logs with uppercase level', () => {
+      initLogger('info', 'plain', false);
+
+      // Plain format should use { level: 'INFO' }
+      expect(() => logger.info('Plain format test')).not.toThrow();
+    });
+
+    it('should format JSON logs with standard structure', () => {
+      initLogger('info', 'json', false);
+
+      // JSON format should use standard pino JSON
+      expect(() => logger.info('JSON format test')).not.toThrow();
+    });
+
+    it('should format GCP JSON logs with severity field', () => {
+      initLogger('info', 'gcp-json', false);
+
+      // GCP format should use { severity: 'INFO' }
+      expect(() => logger.info('GCP format test')).not.toThrow();
+    });
+  });
+
+  describe('Severity mapping for GCP format', () => {
+    it('should map debug to DEBUG', () => {
+      const levelToSeverity = {
+        debug: 'DEBUG',
+        info: 'INFO',
+        warn: 'WARNING',
+        error: 'ERROR',
+      };
+
+      expect(levelToSeverity.debug).toBe('DEBUG');
+    });
+
+    it('should map info to INFO', () => {
+      const levelToSeverity = {
+        debug: 'DEBUG',
+        info: 'INFO',
+        warn: 'WARNING',
+        error: 'ERROR',
+      };
+
+      expect(levelToSeverity.info).toBe('INFO');
+    });
+
+    it('should map warn to WARNING', () => {
+      const levelToSeverity = {
+        debug: 'DEBUG',
+        info: 'INFO',
+        warn: 'WARNING',
+        error: 'ERROR',
+      };
+
+      expect(levelToSeverity.warn).toBe('WARNING');
+    });
+
+    it('should map error to ERROR', () => {
+      const levelToSeverity = {
+        debug: 'DEBUG',
+        info: 'INFO',
+        warn: 'WARNING',
+        error: 'ERROR',
+      };
+
+      expect(levelToSeverity.error).toBe('ERROR');
+    });
+  });
+
+  describe('Error metadata normalization', () => {
+    it('should normalize Error to object with message and stack', () => {
+      const error = new Error('Test error');
+      const normalized = {
+        message: error.message,
+        stack: error.stack,
+      };
+
+      expect(normalized.message).toBe('Test error');
+      expect(normalized.stack).toBeDefined();
+    });
+
+    it('should preserve non-Error values', () => {
+      const metadata = {
+        string: 'test',
+        number: 123,
+        boolean: true,
+        null: null,
+        array: [1, 2, 3],
+        object: { key: 'value' },
+      };
+
+      expect(metadata.string).toBe('test');
+      expect(metadata.number).toBe(123);
+      expect(metadata.boolean).toBe(true);
+      expect(metadata.null).toBeNull();
+      expect(metadata.array).toEqual([1, 2, 3]);
+      expect(metadata.object).toEqual({ key: 'value' });
+    });
+  });
+
+  describe('Timestamp format', () => {
+    it('should use ISO time format', () => {
+      // Pino stdTimeFunctions.isoTime produces ISO 8601 timestamps
+      const now = new Date();
+      const isoTime = now.toISOString();
+
+      expect(isoTime).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
+    });
+  });
+
+  describe('Message key', () => {
+    it('should use "message" as the message key', () => {
+      const logEntry = {
+        level: 'INFO',
+        time: '2026-01-08T12:00:00.000Z',
+        message: 'Test message',
+      };
+
+      expect(logEntry.message).toBe('Test message');
+      expect('message' in logEntry).toBe(true);
+    });
+  });
+
+  describe('Base fields', () => {
+    it('should not include base fields like hostname and pid', () => {
+      // baseConfig.base = undefined disables these fields
+      const logEntry = {
+        level: 'INFO',
+        time: '2026-01-08T12:00:00.000Z',
+        message: 'Test message',
+      };
+
+      expect('hostname' in logEntry).toBe(false);
+      expect('pid' in logEntry).toBe(false);
+      expect('name' in logEntry).toBe(false);
+    });
+  });
+
+  describe('Stdio mode behavior', () => {
+    it('should log to stderr in stdio mode to avoid MCP protocol interference', () => {
+      const useStderr = true;
+
+      initLogger('info', 'plain', useStderr);
+
+      // Logger should be configured for stderr
+      expect(() => logger.info('Stdio mode test')).not.toThrow();
+    });
+
+    it('should log to stdout in HTTP mode', () => {
+      const useStderr = false;
+
+      initLogger('info', 'plain', useStderr);
+
+      // Logger should be configured for stdout
+      expect(() => logger.info('HTTP mode test')).not.toThrow();
+    });
+  });
+
+  describe('Environment variable initialization', () => {
+    it('should use MCP_SERVER_LOG_LEVEL from environment by default', () => {
+      // The default instance reads from process.env.MCP_SERVER_LOG_LEVEL
+      const defaultLevel = (process.env.MCP_SERVER_LOG_LEVEL as LogLevel | undefined) ?? 'info';
+
+      expect(['debug', 'info', 'warn', 'error', 'silent']).toContain(defaultLevel);
+    });
+  });
+
+  describe('Multiple logger instances', () => {
+    it('should replace previous instance when reinitializing', () => {
+      initLogger('info', 'plain', false);
+      const firstInit = { ...logger };
+
+      initLogger('debug', 'json', true);
+      const secondInit = { ...logger };
+
+      // Second initialization should replace the first
+      expect(firstInit).toBeDefined();
+      expect(secondInit).toBeDefined();
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["ES2022"],
+    "moduleResolution": "node",
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/vitest.config.ts

@@ -0,0 +1,26 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    reporters: ['basic'],
+    exclude: [
+      '**/node_modules/**',
+      '**/dist/**',
+      '**/example/**',
+    ],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: [
+        'node_modules/',
+        'dist/',
+        'example/',
+        'tests/',
+        '**/*.test.ts',
+        '**/*.config.ts',
+      ],
+    },
+  },
+});