sql-kite 1.0.0

package/src/utils/paths.js

@@ -0,0 +1,71 @@
+import { homedir } from 'os';
+import { join } from 'path';
+import { existsSync, mkdirSync } from 'fs';
+
+export const SQL_KITE_HOME = join(homedir(), '.sql-kite');
+export const RUNTIME_DIR = join(SQL_KITE_HOME, 'runtime');
+export const STUDIO_DIR = join(SQL_KITE_HOME, 'studio');
+export const LOGS_DIR = join(SQL_KITE_HOME, 'logs');
+
+export function getProjectPath(name) {
+  return join(RUNTIME_DIR, name);
+}
+
+export function getProjectDbPath(name) {
+  return join(getProjectPath(name), 'db.sqlite');
+}
+
+export function getProjectMetaPath(name) {
+  return join(getProjectPath(name), '.studio', 'meta.db');
+}
+
+export function getProjectServerInfoPath(name) {
+  return join(getProjectPath(name), '.studio', 'server.json');
+}
+
+export function ensureSqlKiteDirs() {
+  [SQL_KITE_HOME, RUNTIME_DIR, STUDIO_DIR, LOGS_DIR].forEach(dir => {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+  });
+}
+
+export function projectExists(name) {
+  return existsSync(getProjectPath(name));
+}
+
+/**
+ * Validate project name to prevent path traversal attacks
+ * Only allows alphanumeric, hyphens, underscores
+ * @param {string} name - Project name to validate
+ * @returns {{ valid: boolean, error?: string, sanitized?: string }}
+ */
+export function validateProjectName(name) {
+  if (!name || typeof name !== 'string') {
+    return { valid: false, error: 'Project name is required' };
+  }
+
+  const trimmed = name.trim();
+  
+  if (trimmed.length === 0) {
+    return { valid: false, error: 'Project name cannot be empty' };
+  }
+
+  if (trimmed.length > 50) {
+    return { valid: false, error: 'Project name too long (max 50 characters)' };
+  }
+
+  // Block path traversal attempts
+  if (trimmed.includes('..') || trimmed.includes('/') || trimmed.includes('\\')) {
+    return { valid: false, error: 'Project name contains invalid characters (no paths allowed)' };
+  }
+
+  // Only allow alphanumeric, hyphens, underscores
+  const validPattern = /^[a-zA-Z0-9_-]+$/;
+  if (!validPattern.test(trimmed)) {
+    return { valid: false, error: 'Project name can only contain letters, numbers, hyphens, and underscores' };
+  }
+
+  return { valid: true, sanitized: trimmed };
+}

package/src/utils/port-finder.js

@@ -0,0 +1,239 @@
+import { createServer } from 'net';
+import portRegistry from './port-registry.js';
+
+/**
+ * Port configuration
+ */
+const PORT_CONFIG = {
+  DEFAULT_START: 3000,
+  DEFAULT_END: 3999,
+  FALLBACK_START: 4000,
+  FALLBACK_END: 4999,
+  MAX_ATTEMPTS: 100,
+  SCAN_BATCH_SIZE: 10
+};
+
+/**
+ * Check if a single port is available at OS level
+ */
+async function isPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = createServer();
+
+    const cleanup = () => {
+      server.removeAllListeners();
+    };
+
+    server.once('error', (err) => {
+      cleanup();
+      if (err.code === 'EADDRINUSE' || err.code === 'EACCES') {
+        resolve(false);
+      } else {
+        resolve(false);
+      }
+    });
+
+    server.once('listening', () => {
+      server.close(() => {
+        cleanup();
+        resolve(true);
+      });
+    });
+
+    // Bind to all interfaces to ensure we check properly
+    server.listen(port, '0.0.0.0');
+  });
+}
+
+/**
+ * Find a free port in the given range
+ * Uses intelligent scanning with registry integration
+ */
+async function findFreePortInRange(startPort, endPort, projectName = null) {
+  // Auto-cleanup stale allocations
+  portRegistry.autoCleanup();
+
+  // Get currently allocated ports from registry
+  const allocatedPorts = portRegistry.getAllocatedPorts();
+
+  let attempts = 0;
+  let currentPort = startPort;
+
+  while (currentPort <= endPort && attempts < PORT_CONFIG.MAX_ATTEMPTS) {
+    attempts++;
+
+    // Skip ports already allocated in registry
+    if (allocatedPorts.includes(currentPort)) {
+      currentPort++;
+      continue;
+    }
+
+    // Check if port is available at OS level
+    const available = await isPortAvailable(currentPort);
+
+    if (available) {
+      // Try to reserve in registry if project name provided
+      if (projectName) {
+        const reserved = await portRegistry.reservePort(projectName, currentPort);
+        if (reserved) {
+          return currentPort;
+        }
+        // Port was taken by another process between check and reserve
+        // Continue to next port
+        currentPort++;
+        continue;
+      }
+
+      return currentPort;
+    }
+
+    currentPort++;
+  }
+
+  return null;
+}
+
+/**
+ * Scan multiple ports in parallel (batch scanning)
+ * Much faster for finding free ports in busy systems
+ */
+async function scanPortsBatch(ports) {
+  const results = await Promise.all(
+    ports.map(async (port) => ({
+      port,
+      available: await isPortAvailable(port)
+    }))
+  );
+
+  const availablePort = results.find(r => r.available);
+  return availablePort ? availablePort.port : null;
+}
+
+/**
+ * Find a free port with intelligent strategies
+ *
+ * Strategy:
+ * 1. Check registry for existing project allocation
+ * 2. Try default range (3000-3999) with batch scanning
+ * 3. Fallback to higher range (4000-4999)
+ * 4. Sequential scan as last resort
+ *
+ * @param {number} startPort - Preferred starting port (default: 3000)
+ * @param {string} projectName - Project name for registry tracking (optional)
+ * @returns {Promise<number>} - Free port number
+ */
+export async function findFreePort(startPort = PORT_CONFIG.DEFAULT_START, projectName = null) {
+  try {
+    // Auto-cleanup stale allocations first
+    portRegistry.autoCleanup();
+
+    // If project name provided, check if already has allocated port
+    if (projectName) {
+      const existingPort = portRegistry.getProjectPort(projectName);
+      if (existingPort) {
+        // Verify it's still valid
+        const isValid = await isPortAvailable(existingPort);
+        if (isValid) {
+          return existingPort;
+        }
+        // Port no longer valid, release it
+        portRegistry.releasePort(projectName);
+      }
+    }
+
+    // Strategy 1: Try the requested start port
+    if (startPort >= PORT_CONFIG.DEFAULT_START && startPort <= PORT_CONFIG.DEFAULT_END) {
+      const allocatedPorts = portRegistry.getAllocatedPorts();
+      if (!allocatedPorts.includes(startPort)) {
+        const available = await isPortAvailable(startPort);
+        if (available) {
+          if (projectName) {
+            const reserved = await portRegistry.reservePort(projectName, startPort);
+            if (reserved) return startPort;
+          } else {
+            return startPort;
+          }
+        }
+      }
+    }
+
+    // Strategy 2: Quick batch scan in default range
+    const defaultRangeStart = Math.max(startPort, PORT_CONFIG.DEFAULT_START);
+    const batchPorts = [];
+    for (let i = 0; i < PORT_CONFIG.SCAN_BATCH_SIZE; i++) {
+      const port = defaultRangeStart + i;
+      if (port <= PORT_CONFIG.DEFAULT_END) {
+        batchPorts.push(port);
+      }
+    }
+
+    if (batchPorts.length > 0) {
+      const allocatedPorts = portRegistry.getAllocatedPorts();
+      const freePorts = batchPorts.filter(p => !allocatedPorts.includes(p));
+
+      if (freePorts.length > 0) {
+        const batchResult = await scanPortsBatch(freePorts);
+        if (batchResult) {
+          if (projectName) {
+            const reserved = await portRegistry.reservePort(projectName, batchResult);
+            if (reserved) return batchResult;
+          } else {
+            return batchResult;
+          }
+        }
+      }
+    }
+
+    // Strategy 3: Sequential scan in default range
+    let port = await findFreePortInRange(
+      defaultRangeStart,
+      PORT_CONFIG.DEFAULT_END,
+      projectName
+    );
+    if (port) return port;
+
+    // Strategy 4: Fallback range
+    port = await findFreePortInRange(
+      PORT_CONFIG.FALLBACK_START,
+      PORT_CONFIG.FALLBACK_END,
+      projectName
+    );
+    if (port) return port;
+
+    // Strategy 5: Extended range (5000-9999)
+    port = await findFreePortInRange(5000, 9999, projectName);
+    if (port) return port;
+
+    // No port found
+    throw new Error(
+      'Unable to find a free port. Please ensure you have available ports in range 3000-9999'
+    );
+  } catch (error) {
+    if (error.message.includes('Unable to find')) {
+      throw error;
+    }
+    // Fallback to simple sequential search on unexpected errors
+    return findFreePortInRange(startPort, startPort + 1000, projectName);
+  }
+}
+
+/**
+ * Release a port for a project
+ */
+export function releasePort(projectName) {
+  return portRegistry.releasePort(projectName);
+}
+
+/**
+ * Get port registry status
+ */
+export function getPortStatus() {
+  return portRegistry.getStatus();
+}
+
+/**
+ * Manual cleanup of stale allocations
+ */
+export function cleanupStalePorts() {
+  return portRegistry.cleanup();
+}

package/src/utils/port-registry.js

@@ -0,0 +1,233 @@
+import { join } from 'path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, readdirSync } from 'fs';
+import { RUNTIME_DIR } from './paths.js';
+import { createServer } from 'net';
+
+const REGISTRY_FILE = join(RUNTIME_DIR, '.port-registry.json');
+const LOCK_TIMEOUT = 5000; // 5 seconds
+
+/**
+ * Port Registry - Manages port allocation across all SQL Kite projects
+ *
+ * Features:
+ * - Centralized port tracking
+ * - Atomic port allocation
+ * - Conflict detection
+ * - Automatic cleanup of stale allocations
+ * - Fast port validation
+ */
+
+class PortRegistry {
+  constructor() {
+    this.ensureRegistryFile();
+  }
+
+  ensureRegistryFile() {
+    if (!existsSync(RUNTIME_DIR)) {
+      mkdirSync(RUNTIME_DIR, { recursive: true });
+    }
+    if (!existsSync(REGISTRY_FILE)) {
+      this.writeRegistry({ ports: {}, last_cleanup: Date.now() });
+    }
+  }
+
+  readRegistry() {
+    try {
+      const data = readFileSync(REGISTRY_FILE, 'utf-8');
+      return JSON.parse(data);
+    } catch (e) {
+      // Corrupted registry, recreate
+      this.writeRegistry({ ports: {}, last_cleanup: Date.now() });
+      return { ports: {}, last_cleanup: Date.now() };
+    }
+  }
+
+  writeRegistry(data) {
+    writeFileSync(REGISTRY_FILE, JSON.stringify(data, null, 2));
+  }
+
+  /**
+   * Get all currently allocated ports
+   */
+  getAllocatedPorts() {
+    const registry = this.readRegistry();
+    return Object.values(registry.ports).map(entry => entry.port);
+  }
+
+  /**
+   * Check if a port is allocated to any project
+   */
+  isPortAllocated(port) {
+    const allocatedPorts = this.getAllocatedPorts();
+    return allocatedPorts.includes(port);
+  }
+
+  /**
+   * Get port for a specific project
+   */
+  getProjectPort(projectName) {
+    const registry = this.readRegistry();
+    return registry.ports[projectName]?.port || null;
+  }
+
+  /**
+   * Reserve a port for a project atomically
+   */
+  async reservePort(projectName, port) {
+    const registry = this.readRegistry();
+
+    // Check if project already has a port
+    if (registry.ports[projectName]) {
+      const existingPort = registry.ports[projectName].port;
+      // Verify the existing port is still valid
+      const isValid = await this.isPortActuallyFree(existingPort);
+      if (isValid) {
+        return existingPort;
+      }
+      // Stale allocation, remove it
+      delete registry.ports[projectName];
+    }
+
+    // Check if port is already allocated
+    const allocatedPorts = Object.values(registry.ports).map(e => e.port);
+    if (allocatedPorts.includes(port)) {
+      return null; // Port already taken
+    }
+
+    // Verify port is actually free at OS level
+    const isFree = await this.isPortActuallyFree(port);
+    if (!isFree) {
+      return null;
+    }
+
+    // Reserve the port
+    registry.ports[projectName] = {
+      port,
+      allocated_at: Date.now(),
+      pid: process.pid
+    };
+
+    this.writeRegistry(registry);
+    return port;
+  }
+
+  /**
+   * Release a port for a project
+   */
+  releasePort(projectName) {
+    const registry = this.readRegistry();
+    if (registry.ports[projectName]) {
+      delete registry.ports[projectName];
+      this.writeRegistry(registry);
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Check if a port is actually free at OS level
+   */
+  async isPortActuallyFree(port) {
+    return new Promise((resolve) => {
+      const server = createServer();
+
+      server.once('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+          resolve(false);
+        } else {
+          resolve(false);
+        }
+      });
+
+      server.once('listening', () => {
+        server.close(() => {
+          resolve(true);
+        });
+      });
+
+      server.listen(port, '0.0.0.0');
+    });
+  }
+
+  /**
+   * Cleanup stale port allocations
+   * Checks if server.json files exist for allocated projects
+   */
+  cleanup() {
+    const registry = this.readRegistry();
+    const projects = Object.keys(registry.ports);
+    let cleanedCount = 0;
+
+    for (const projectName of projects) {
+      const serverInfoPath = join(RUNTIME_DIR, projectName, '.studio', 'server.json');
+
+      // If server.json doesn't exist, the port allocation is stale
+      if (!existsSync(serverInfoPath)) {
+        delete registry.ports[projectName];
+        cleanedCount++;
+      } else {
+        // Verify the server is actually running
+        try {
+          const serverInfo = JSON.parse(readFileSync(serverInfoPath, 'utf-8'));
+          try {
+            // Check if process exists (signal 0 doesn't kill, just checks)
+            process.kill(serverInfo.pid, 0);
+          } catch (e) {
+            // Process doesn't exist, cleanup
+            delete registry.ports[projectName];
+            unlinkSync(serverInfoPath);
+            cleanedCount++;
+          }
+        } catch (e) {
+          // Corrupted server.json
+          delete registry.ports[projectName];
+          cleanedCount++;
+        }
+      }
+    }
+
+    registry.last_cleanup = Date.now();
+    this.writeRegistry(registry);
+
+    return cleanedCount;
+  }
+
+  /**
+   * Auto cleanup if last cleanup was more than 1 hour ago
+   */
+  autoCleanup() {
+    const registry = this.readRegistry();
+    const ONE_HOUR = 60 * 60 * 1000;
+
+    if (!registry.last_cleanup || (Date.now() - registry.last_cleanup) > ONE_HOUR) {
+      return this.cleanup();
+    }
+
+    return 0;
+  }
+
+  /**
+   * Get registry status
+   */
+  getStatus() {
+    const registry = this.readRegistry();
+    return {
+      total_allocations: Object.keys(registry.ports).length,
+      allocations: registry.ports,
+      last_cleanup: registry.last_cleanup
+    };
+  }
+
+  /**
+   * Force clear all allocations (dangerous - for debugging only)
+   */
+  clearAll() {
+    this.writeRegistry({ ports: {}, last_cleanup: Date.now() });
+  }
+}
+
+// Singleton instance
+const portRegistry = new PortRegistry();
+
+export default portRegistry;
+export { PortRegistry };