spindb 0.7.0 → 0.7.3

package/core/error-handler.ts

@@ -17,10 +17,6 @@ function getSpinDBRoot(): string {
   return join(home, '.spindb')
 }
 
-// =============================================================================
-// Types
-// =============================================================================
-
 export type ErrorSeverity = 'fatal' | 'error' | 'warning' | 'info'
 
 export type SpinDBErrorInfo = {
@@ -31,10 +27,6 @@ export type SpinDBErrorInfo = {
   context?: Record<string, unknown>
 }
 
-// =============================================================================
-// Error Codes
-// =============================================================================
-
 export const ErrorCodes = {
   // Port errors
   PORT_IN_USE: 'PORT_IN_USE',
@@ -83,10 +75,6 @@ export const ErrorCodes = {
 
 export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes]
 
-// =============================================================================
-// SpinDBError Class
-// =============================================================================
-
 export class SpinDBError extends Error {
   public readonly code: string
   public readonly severity: ErrorSeverity
@@ -131,13 +119,6 @@ export class SpinDBError extends Error {
   }
 }
 
-// =============================================================================
-// Logging Functions
-// =============================================================================
-
-/**
- * Get the path to the log file
- */
 function getLogPath(): string {
   return join(getSpinDBRoot(), 'spindb.log')
 }
@@ -264,13 +245,6 @@ export function logDebug(
   })
 }
 
-// =============================================================================
-// Error Creation Helpers
-// =============================================================================
-
-/**
- * Create a port-in-use error with helpful suggestion
- */
 export function createPortInUseError(port: number): SpinDBError {
   return new SpinDBError(
     ErrorCodes.PORT_IN_USE,

package/core/platform-service.ts

@@ -17,13 +17,47 @@ import { existsSync } from 'fs'
 
 const execAsync = promisify(exec)
 
-// =============================================================================
-// Types
-// =============================================================================
-
 export type Platform = 'darwin' | 'linux' | 'win32'
 export type Architecture = 'arm64' | 'x64'
 
+/**
+ * Options for resolving home directory under sudo
+ */
+export type ResolveHomeDirOptions = {
+  sudoUser: string | null
+  getentResult: string | null
+  platform: 'darwin' | 'linux'
+  defaultHome: string
+}
+
+/**
+ * Resolve the correct home directory, handling sudo scenarios.
+ * This is extracted as a pure function for testability.
+ *
+ * When running under sudo, we need to use the original user's home directory,
+ * not root's home. This prevents ~/.spindb from being created in /root/.
+ */
+export function resolveHomeDir(options: ResolveHomeDirOptions): string {
+  const { sudoUser, getentResult, platform, defaultHome } = options
+
+  // Not running under sudo - use default
+  if (!sudoUser) {
+    return defaultHome
+  }
+
+  // Try to parse home from getent passwd output
+  // Format: username:password:uid:gid:gecos:home:shell
+  if (getentResult) {
+    const parts = getentResult.trim().split(':')
+    if (parts.length >= 6 && parts[5]) {
+      return parts[5]
+    }
+  }
+
+  // Fallback to platform-specific default
+  return platform === 'darwin' ? `/Users/${sudoUser}` : `/home/${sudoUser}`
+}
+
 export type PlatformInfo = {
   platform: Platform
   arch: Architecture
@@ -54,10 +88,6 @@ export type PackageManagerInfo = {
   updateCommand: string
 }
 
-// =============================================================================
-// Abstract Base Class
-// =============================================================================
-
 export abstract class BasePlatformService {
   protected cachedPlatformInfo: PlatformInfo | null = null
 
@@ -165,33 +195,31 @@ export abstract class BasePlatformService {
   }
 }
 
-// =============================================================================
-// Darwin (macOS) Implementation
-// =============================================================================
-
 class DarwinPlatformService extends BasePlatformService {
   getPlatformInfo(): PlatformInfo {
     if (this.cachedPlatformInfo) return this.cachedPlatformInfo
 
     const sudoUser = process.env.SUDO_USER || null
-    let homeDir: string
 
+    // Try to get home from getent passwd (may fail on macOS)
+    let getentResult: string | null = null
     if (sudoUser) {
-      // Running under sudo - get original user's home
       try {
-        const result = execSync(`getent passwd ${sudoUser}`, {
+        getentResult = execSync(`getent passwd ${sudoUser}`, {
           encoding: 'utf-8',
         })
-        const parts = result.trim().split(':')
-        homeDir =
-          parts.length >= 6 && parts[5] ? parts[5] : `/Users/${sudoUser}`
       } catch {
-        homeDir = `/Users/${sudoUser}`
+        // getent may not be available on macOS
       }
-    } else {
-      homeDir = homedir()
     }
 
+    const homeDir = resolveHomeDir({
+      sudoUser,
+      getentResult,
+      platform: 'darwin',
+      defaultHome: homedir(),
+    })
+
     this.cachedPlatformInfo = {
       platform: 'darwin',
       arch: osArch() as Architecture,
@@ -309,31 +337,31 @@ class DarwinPlatformService extends BasePlatformService {
   }
 }
 
-// =============================================================================
-// Linux Implementation
-// =============================================================================
-
 class LinuxPlatformService extends BasePlatformService {
   getPlatformInfo(): PlatformInfo {
     if (this.cachedPlatformInfo) return this.cachedPlatformInfo
 
     const sudoUser = process.env.SUDO_USER || null
-    let homeDir: string
 
+    // Try to get home from getent passwd
+    let getentResult: string | null = null
     if (sudoUser) {
       try {
-        const result = execSync(`getent passwd ${sudoUser}`, {
+        getentResult = execSync(`getent passwd ${sudoUser}`, {
           encoding: 'utf-8',
         })
-        const parts = result.trim().split(':')
-        homeDir = parts.length >= 6 && parts[5] ? parts[5] : `/home/${sudoUser}`
       } catch {
-        homeDir = `/home/${sudoUser}`
+        // getent failed
       }
-    } else {
-      homeDir = homedir()
     }
 
+    const homeDir = resolveHomeDir({
+      sudoUser,
+      getentResult,
+      platform: 'linux',
+      defaultHome: homedir(),
+    })
+
     // Check if running in WSL
     let isWSL = false
     try {
@@ -494,10 +522,6 @@ class LinuxPlatformService extends BasePlatformService {
   }
 }
 
-// =============================================================================
-// Windows Implementation (Stub for future support)
-// =============================================================================
-
 class Win32PlatformService extends BasePlatformService {
   getPlatformInfo(): PlatformInfo {
     if (this.cachedPlatformInfo) return this.cachedPlatformInfo
@@ -608,10 +632,6 @@ class Win32PlatformService extends BasePlatformService {
   }
 }
 
-// =============================================================================
-// Factory and Singleton
-// =============================================================================
-
 /**
  * Create the appropriate platform service for the current OS
  */

package/core/start-with-retry.ts

@@ -9,12 +9,9 @@ import { portManager } from './port-manager'
 import { containerManager } from './container-manager'
 import { logWarning, logDebug } from './error-handler'
 import type { BaseEngine } from '../engines/base-engine'
+import { getEngineDefaults } from '../config/defaults'
 import type { ContainerConfig } from '../types'
 
-// =============================================================================
-// Types
-// =============================================================================
-
 export type StartWithRetryOptions = {
   engine: BaseEngine
   config: ContainerConfig
@@ -29,13 +26,6 @@ export type StartWithRetryResult = {
   error?: Error
 }
 
-// =============================================================================
-// Port Error Detection
-// =============================================================================
-
-/**
- * Check if an error is a port-in-use error
- */
 function isPortInUseError(err: unknown): boolean {
   const message = (err as Error)?.message?.toLowerCase() || ''
   return (
@@ -47,10 +37,6 @@ function isPortInUseError(err: unknown): boolean {
   )
 }
 
-// =============================================================================
-// Start with Retry Implementation
-// =============================================================================
-
 /**
  * Start a database container with automatic port retry on conflict
  *
@@ -129,20 +115,9 @@ export async function startWithRetry(
   }
 }
 
-/**
- * Get the port range for an engine
- */
 function getEnginePortRange(engine: string): { start: number; end: number } {
-  // Import defaults dynamically to avoid circular dependency
-  // These are the standard ranges from config/defaults.ts
-  if (engine === 'postgresql') {
-    return { start: 5432, end: 5500 }
-  }
-  if (engine === 'mysql') {
-    return { start: 3306, end: 3400 }
-  }
-  // Default fallback range
-  return { start: 5432, end: 6000 }
+  const engineDefaults = getEngineDefaults(engine)
+  return engineDefaults.portRange
 }
 
 /**

package/core/transaction-manager.ts

@@ -7,19 +7,11 @@
 
 import { logError, logDebug, ErrorCodes } from './error-handler'
 
-// =============================================================================
-// Types
-// =============================================================================
-
 export type RollbackAction = {
   description: string
   execute: () => Promise<void>
 }
 
-// =============================================================================
-// Transaction Manager Implementation
-// =============================================================================
-
 /**
  * Manages a stack of rollback actions for transactional operations.
  *

package/engines/base-engine.ts

@@ -151,4 +151,14 @@ export abstract class BaseEngine {
     outputPath: string,
     options: BackupOptions,
   ): Promise<BackupResult>
+
+  /**
+   * Run a SQL file or inline SQL statement against the database
+   * @param container - The container configuration
+   * @param options - Options including file path or SQL statement, and target database
+   */
+  abstract runScript(
+    container: ContainerConfig,
+    options: { file?: string; sql?: string; database?: string },
+  ): Promise<void>
 }

package/engines/mysql/binary-detection.ts

@@ -4,6 +4,7 @@
  */
 
 import { exec } from 'child_process'
+import { existsSync } from 'fs'
 import { promisify } from 'util'
 import { platformService } from '../../core/platform-service'
 
@@ -129,7 +130,6 @@ export async function detectInstalledVersions(): Promise<
       '/usr/local/opt/mysql@8.4/bin/mysqld',
     ]
 
-    const { existsSync } = await import('fs')
     for (const path of homebrewPaths) {
       if (existsSync(path)) {
         const version = await getMysqlVersion(path)

package/engines/mysql/index.ts

@@ -5,7 +5,7 @@
 
 import { spawn, exec } from 'child_process'
 import { promisify } from 'util'
-import { existsSync } from 'fs'
+import { existsSync, createReadStream } from 'fs'
 import { mkdir, writeFile, readFile, unlink } from 'fs/promises'
 import { join } from 'path'
 import { BaseEngine } from '../base-engine'
@@ -289,8 +289,9 @@ export class MySQLEngine extends BaseEngine {
         // Write PID file manually since we're running detached
         try {
           await writeFile(pidFile, String(proc.pid))
-        } catch {
+        } catch (error) {
           // PID file might be written by mysqld itself
+          logDebug(`Could not write PID file (mysqld may write it): ${error}`)
         }
 
         // Wait for MySQL to be ready
@@ -842,6 +843,81 @@ export class MySQLEngine extends BaseEngine {
   ): Promise<BackupResult> {
     return createBackup(container, outputPath, options)
   }
+
+  /**
+   * Run a SQL file or inline SQL statement against the database
+   * CLI wrapper: mysql -h 127.0.0.1 -P {port} -u root {db} < {file}
+   * CLI wrapper: mysql -h 127.0.0.1 -P {port} -u root {db} -e "{sql}"
+   */
+  async runScript(
+    container: ContainerConfig,
+    options: { file?: string; sql?: string; database?: string },
+  ): Promise<void> {
+    const { port } = container
+    const db = options.database || container.database || 'mysql'
+
+    const mysql = await getMysqlClientPath()
+    if (!mysql) {
+      throw new Error(
+        'mysql client not found. Install MySQL client tools:\n' +
+          '  macOS: brew install mysql-client\n' +
+          '  Ubuntu/Debian: sudo apt install mysql-client',
+      )
+    }
+
+    const args = [
+      '-h',
+      '127.0.0.1',
+      '-P',
+      String(port),
+      '-u',
+      engineDef.superuser,
+      db,
+    ]
+
+    if (options.sql) {
+      // For inline SQL, use -e flag
+      args.push('-e', options.sql)
+      return new Promise((resolve, reject) => {
+        const proc = spawn(mysql, args, { stdio: 'inherit' })
+
+        proc.on('error', reject)
+        proc.on('close', (code) => {
+          if (code === 0) {
+            resolve()
+          } else {
+            reject(new Error(`mysql exited with code ${code}`))
+          }
+        })
+      })
+    } else if (options.file) {
+      // For file input, pipe the file to mysql stdin
+      return new Promise((resolve, reject) => {
+        const fileStream = createReadStream(options.file!)
+        const proc = spawn(mysql, args, {
+          stdio: ['pipe', 'inherit', 'inherit'],
+        })
+
+        fileStream.pipe(proc.stdin)
+
+        fileStream.on('error', (err) => {
+          proc.kill()
+          reject(err)
+        })
+
+        proc.on('error', reject)
+        proc.on('close', (code) => {
+          if (code === 0) {
+            resolve()
+          } else {
+            reject(new Error(`mysql exited with code ${code}`))
+          }
+        })
+      })
+    } else {
+      throw new Error('Either file or sql option must be provided')
+    }
+  }
 }
 
 export const mysqlEngine = new MySQLEngine()

package/engines/postgresql/index.ts

@@ -457,6 +457,55 @@ export class PostgreSQLEngine extends BaseEngine {
   ): Promise<BackupResult> {
     return createBackup(container, outputPath, options)
   }
+
+  /**
+   * Run a SQL file or inline SQL statement against the database
+   * CLI wrapper: psql -h 127.0.0.1 -p {port} -U postgres -d {db} -f {file}
+   * CLI wrapper: psql -h 127.0.0.1 -p {port} -U postgres -d {db} -c "{sql}"
+   */
+  async runScript(
+    container: ContainerConfig,
+    options: { file?: string; sql?: string; database?: string },
+  ): Promise<void> {
+    const { port } = container
+    const db = options.database || container.database || 'postgres'
+    const psqlPath = await this.getPsqlPath()
+
+    const args = [
+      '-h',
+      '127.0.0.1',
+      '-p',
+      String(port),
+      '-U',
+      defaults.superuser,
+      '-d',
+      db,
+    ]
+
+    if (options.file) {
+      args.push('-f', options.file)
+    } else if (options.sql) {
+      args.push('-c', options.sql)
+    } else {
+      throw new Error('Either file or sql option must be provided')
+    }
+
+    return new Promise((resolve, reject) => {
+      const proc = spawn(psqlPath, args, { stdio: 'inherit' })
+
+      proc.on('error', (err: NodeJS.ErrnoException) => {
+        reject(err)
+      })
+
+      proc.on('close', (code) => {
+        if (code === 0) {
+          resolve()
+        } else {
+          reject(new Error(`psql exited with code ${code}`))
+        }
+      })
+    })
+  }
 }
 
 export const postgresqlEngine = new PostgreSQLEngine()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spindb",
-  "version": "0.7.0",
+  "version": "0.7.3",
   "description": "Spin up local database containers without Docker. A DBngin-like CLI for PostgreSQL and MySQL.",
   "type": "module",
   "bin": {