spindb 0.6.0 → 0.7.3

package/core/dependency-manager.ts

@@ -43,13 +43,6 @@ export type InstallResult = {
   error?: string
 }
 
-// =============================================================================
-// Package Manager Detection
-// =============================================================================
-
-/**
- * Detect which package manager is available on the current system
- */
 export async function detectPackageManager(): Promise<DetectedPackageManager | null> {
   const { platform } = platformService.getPlatformInfo()
 
@@ -81,13 +74,6 @@ export function getCurrentPlatform(): Platform {
   return platformService.getPlatformInfo().platform as Platform
 }
 
-// =============================================================================
-// Dependency Checking
-// =============================================================================
-
-/**
- * Check if a binary is installed and get its path
- */
 export async function findBinary(
   binary: string,
 ): Promise<{ path: string; version?: string } | null> {
@@ -164,13 +150,6 @@ export async function getAllMissingDependencies(): Promise<Dependency[]> {
   return statuses.filter((s) => !s.installed).map((s) => s.dependency)
 }
 
-// =============================================================================
-// Installation
-// =============================================================================
-
-/**
- * Check if stdin is a TTY (interactive terminal)
- */
 function hasTTY(): boolean {
   return process.stdin.isTTY === true
 }
@@ -362,13 +341,6 @@ export async function installAllDependencies(
   return results
 }
 
-// =============================================================================
-// Manual Installation Instructions
-// =============================================================================
-
-/**
- * Get manual installation instructions for a dependency
- */
 export function getManualInstallInstructions(
   dependency: Dependency,
   platform: Platform = getCurrentPlatform(),
@@ -376,188 +348,53 @@ export function getManualInstallInstructions(
   return dependency.manualInstall[platform] || []
 }
 
-/**
- * Get manual installation instructions for all missing dependencies of an engine
- */
-export function getEngineManualInstallInstructions(
-  engine: string,
-  missingDeps: Dependency[],
-  platform: Platform = getCurrentPlatform(),
-): string[] {
-  // Since all deps usually come from the same package, just get instructions from the first one
-  if (missingDeps.length === 0) return []
-
-  return getManualInstallInstructions(missingDeps[0], platform)
-}
-
-// =============================================================================
-// High-Level API
-// =============================================================================
-
-export type DependencyCheckResult = {
-  engine: string
-  allInstalled: boolean
-  installed: DependencyStatus[]
-  missing: DependencyStatus[]
-}
-
-/**
- * Get a complete dependency report for an engine
- */
-export async function getDependencyReport(
-  engine: string,
-): Promise<DependencyCheckResult> {
-  const statuses = await checkEngineDependencies(engine)
-
-  return {
-    engine,
-    allInstalled: statuses.every((s) => s.installed),
-    installed: statuses.filter((s) => s.installed),
-    missing: statuses.filter((s) => !s.installed),
-  }
-}
-
-/**
- * Get dependency reports for all engines
- */
-export async function getAllDependencyReports(): Promise<
-  DependencyCheckResult[]
-> {
-  const engines = ['postgresql', 'mysql']
-  const reports = await Promise.all(
-    engines.map((engine) => getDependencyReport(engine)),
-  )
-  return reports
-}
-
-// =============================================================================
-// usql (Enhanced Shell) Support
-// =============================================================================
-
-/**
- * Check if usql is installed
- */
 export async function isUsqlInstalled(): Promise<boolean> {
   const status = await checkDependency(usqlDependency)
   return status.installed
 }
 
-/**
- * Get usql dependency status
- */
-export async function getUsqlStatus(): Promise<DependencyStatus> {
-  return checkDependency(usqlDependency)
-}
-
-/**
- * Install usql using the detected package manager
- */
 export async function installUsql(
   packageManager: DetectedPackageManager,
 ): Promise<InstallResult> {
   return installDependency(usqlDependency, packageManager)
 }
 
-/**
- * Get usql manual installation instructions
- */
 export function getUsqlManualInstructions(
   platform: Platform = getCurrentPlatform(),
 ): string[] {
   return getManualInstallInstructions(usqlDependency, platform)
 }
 
-/**
- * Get the usql dependency definition
- */
-export function getUsqlDependency(): Dependency {
-  return usqlDependency
-}
-
-// =============================================================================
-// pgcli (PostgreSQL Enhanced Shell) Support
-// =============================================================================
-
-/**
- * Check if pgcli is installed
- */
 export async function isPgcliInstalled(): Promise<boolean> {
   const status = await checkDependency(pgcliDependency)
   return status.installed
 }
 
-/**
- * Get pgcli dependency status
- */
-export async function getPgcliStatus(): Promise<DependencyStatus> {
-  return checkDependency(pgcliDependency)
-}
-
-/**
- * Install pgcli using the detected package manager
- */
 export async function installPgcli(
   packageManager: DetectedPackageManager,
 ): Promise<InstallResult> {
   return installDependency(pgcliDependency, packageManager)
 }
 
-/**
- * Get pgcli manual installation instructions
- */
 export function getPgcliManualInstructions(
   platform: Platform = getCurrentPlatform(),
 ): string[] {
   return getManualInstallInstructions(pgcliDependency, platform)
 }
 
-/**
- * Get the pgcli dependency definition
- */
-export function getPgcliDependency(): Dependency {
-  return pgcliDependency
-}
-
-// =============================================================================
-// mycli (MySQL Enhanced Shell) Support
-// =============================================================================
-
-/**
- * Check if mycli is installed
- */
 export async function isMycliInstalled(): Promise<boolean> {
   const status = await checkDependency(mycliDependency)
   return status.installed
 }
 
-/**
- * Get mycli dependency status
- */
-export async function getMycliStatus(): Promise<DependencyStatus> {
-  return checkDependency(mycliDependency)
-}
-
-/**
- * Install mycli using the detected package manager
- */
 export async function installMycli(
   packageManager: DetectedPackageManager,
 ): Promise<InstallResult> {
   return installDependency(mycliDependency, packageManager)
 }
 
-/**
- * Get mycli manual installation instructions
- */
 export function getMycliManualInstructions(
   platform: Platform = getCurrentPlatform(),
 ): string[] {
   return getManualInstallInstructions(mycliDependency, platform)
 }
-
-/**
- * Get the mycli dependency definition
- */
-export function getMycliDependency(): Dependency {
-  return mycliDependency
-}

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()