spindb 0.3.5 → 0.4.0

package/README.md

@@ -51,6 +51,8 @@ spindb connect mydb
 | `spindb delete [name]` | Delete a container |
 | `spindb config show` | Show configuration |
 | `spindb config detect` | Auto-detect PostgreSQL tools |
+| `spindb deps check` | Check status of client tools |
+| `spindb deps install` | Install missing client tools |
 
 ## How It Works
 
@@ -71,15 +73,50 @@ Data is stored in `~/.spindb/`:
 
 ## PostgreSQL Client Tools
 
-SpinDB bundles the PostgreSQL **server** (postgres, pg_ctl, initdb) but not client tools (psql, pg_dump, pg_restore). For `connect` and `restore` commands, you need PostgreSQL client tools installed:
+SpinDB bundles the PostgreSQL **server** (postgres, pg_ctl, initdb) but not client tools (psql, pg_dump, pg_restore). For `connect` and `restore` commands, you need PostgreSQL client tools installed.
+
+### Automatic Installation
+
+SpinDB can check and install client tools automatically:
+
+```bash
+# Check status of all client tools
+spindb deps check
+
+# Install missing tools (uses Homebrew, apt, yum, dnf, or pacman)
+spindb deps install
+
+# Install for a specific engine
+spindb deps install --engine postgresql
+spindb deps install --engine mysql
+
+# Install all missing dependencies for all engines
+spindb deps install --all
+
+# List all supported dependencies
+spindb deps list
+```
+
+### Manual Installation
+
+If automatic installation doesn't work, install manually:
 
 ```bash
 # macOS (Homebrew)
-brew install libpq
-brew link --force libpq
+brew install postgresql@17
+brew link --overwrite postgresql@17
 
 # Ubuntu/Debian
-apt install postgresql-client
+sudo apt install postgresql-client
+
+# CentOS/RHEL
+sudo yum install postgresql
+
+# Fedora
+sudo dnf install postgresql
+
+# Arch
+sudo pacman -S postgresql-libs
 
 # Or use Postgres.app (macOS)
 # Client tools are automatically detected
@@ -123,16 +160,33 @@ spindb create mydb --database my_app_db
 # Connection string: postgresql://postgres@localhost:5432/my_app_db
 ```
 
-### Restore a backup
+### Create and restore in one command
 
 ```bash
-# Start the container first
-spindb start mydb
+# Create a container and restore from a dump file
+spindb create mydb --from ./backup.dump
+
+# Create a container and pull from a remote database
+spindb create mydb --from "postgresql://user:pass@remote-host:5432/production_db"
+
+# With specific version and database name
+spindb create mydb --pg-version 17 --database myapp --from ./backup.dump
+```
 
-# Restore (supports .sql, custom format, and tar format)
+The `--from` option auto-detects whether the location is a file path or connection string.
+
+### Restore to an existing container
+
+```bash
+# Restore from a dump file (supports .sql, custom format, and tar format)
 spindb restore mydb ./backup.dump -d myapp
+
+# Or pull directly from a remote database
+spindb restore mydb --from-url "postgresql://user:pass@remote-host:5432/production_db" -d myapp
 ```
 
+The interactive menu (`spindb` → "Restore backup") also offers an option to create a new container as part of the restore flow.
+
 ### Clone for testing
 
 ```bash

package/cli/commands/create.ts

@@ -1,12 +1,43 @@
 import { Command } from 'commander'
+import { existsSync } from 'fs'
+import { rm } from 'fs/promises'
 import chalk from 'chalk'
 import { containerManager } from '../../core/container-manager'
 import { portManager } from '../../core/port-manager'
 import { getEngine } from '../../engines'
 import { defaults } from '../../config/defaults'
-import { promptCreateOptions } from '../ui/prompts'
+import {
+  promptCreateOptions,
+  promptInstallDependencies,
+} from '../ui/prompts'
 import { createSpinner } from '../ui/spinner'
 import { header, error, connectionBox } from '../ui/theme'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { spawn } from 'child_process'
+import { platform } from 'os'
+
+/**
+ * Detect if a location string is a connection string or a file path
+ */
+function detectLocationType(
+  location: string,
+): 'connection' | 'file' | 'not_found' {
+  // Check if it's a connection string
+  if (
+    location.startsWith('postgresql://') ||
+    location.startsWith('postgres://')
+  ) {
+    return 'connection'
+  }
+
+  // Check if file exists
+  if (existsSync(location)) {
+    return 'file'
+  }
+
+  return 'not_found'
+}
 
 export const createCommand = new Command('create')
   .description('Create a new database container')
@@ -20,6 +51,10 @@ export const createCommand = new Command('create')
   .option('-d, --database <database>', 'Database name')
   .option('-p, --port <port>', 'Port number')
   .option('--no-start', 'Do not start the container after creation')
+  .option(
+    '--from <location>',
+    'Restore from a dump file or connection string after creation',
+  )
   .action(
     async (
       name: string | undefined,
@@ -29,8 +64,11 @@ export const createCommand = new Command('create')
         database?: string
         port?: string
         start: boolean
+        from?: string
       },
     ) => {
+      let tempDumpPath: string | null = null
+
       try {
         let containerName = name
         let engine = options.engine
@@ -49,6 +87,37 @@ export const createCommand = new Command('create')
         // Default database name to container name if not specified
         database = database ?? containerName
 
+        // Validate --from location if provided
+        let restoreLocation: string | null = null
+        let restoreType: 'connection' | 'file' | null = null
+
+        if (options.from) {
+          const locationType = detectLocationType(options.from)
+
+          if (locationType === 'not_found') {
+            console.error(error(`Location not found: ${options.from}`))
+            console.log(
+              chalk.gray(
+                '  Provide a valid file path or connection string (postgresql://...)',
+              ),
+            )
+            process.exit(1)
+          }
+
+          restoreLocation = options.from
+          restoreType = locationType
+
+          // If using --from, we must start the container
+          if (options.start === false) {
+            console.error(
+              error(
+                'Cannot use --no-start with --from (restore requires running container)',
+              ),
+            )
+            process.exit(1)
+          }
+        }
+
         console.log(header('Creating Database Container'))
         console.log()
 
@@ -145,6 +214,84 @@ export const createCommand = new Command('create')
 
             dbSpinner.succeed(`Database "${database}" created`)
           }
+
+          // Handle --from restore if specified
+          if (restoreLocation && restoreType && config) {
+            let backupPath: string
+
+            if (restoreType === 'connection') {
+              // Create dump from remote database
+              const timestamp = Date.now()
+              tempDumpPath = join(tmpdir(), `spindb-dump-${timestamp}.dump`)
+
+              const dumpSpinner = createSpinner(
+                'Creating dump from remote database...',
+              )
+              dumpSpinner.start()
+
+              try {
+                await dbEngine.dumpFromConnectionString(
+                  restoreLocation,
+                  tempDumpPath,
+                )
+                dumpSpinner.succeed('Dump created from remote database')
+                backupPath = tempDumpPath
+              } catch (err) {
+                const e = err as Error
+                dumpSpinner.fail('Failed to create dump')
+
+                // Check if this is a missing tool error
+                if (
+                  e.message.includes('pg_dump not found') ||
+                  e.message.includes('ENOENT')
+                ) {
+                  await promptInstallDependencies('pg_dump')
+                  process.exit(1)
+                }
+
+                console.log()
+                console.error(error('pg_dump error:'))
+                console.log(chalk.gray(`  ${e.message}`))
+                process.exit(1)
+              }
+            } else {
+              backupPath = restoreLocation
+            }
+
+            // Detect backup format
+            const detectSpinner = createSpinner('Detecting backup format...')
+            detectSpinner.start()
+
+            const format = await dbEngine.detectBackupFormat(backupPath)
+            detectSpinner.succeed(`Detected: ${format.description}`)
+
+            // Restore backup
+            const restoreSpinner = createSpinner('Restoring backup...')
+            restoreSpinner.start()
+
+            const result = await dbEngine.restore(config, backupPath, {
+              database,
+              createDatabase: false, // Already created above
+            })
+
+            if (result.code === 0 || !result.stderr) {
+              restoreSpinner.succeed('Backup restored successfully')
+            } else {
+              restoreSpinner.warn('Restore completed with warnings')
+              if (result.stderr) {
+                console.log(chalk.yellow('\n  Warnings:'))
+                const lines = result.stderr.split('\n').slice(0, 5)
+                lines.forEach((line) => {
+                  if (line.trim()) {
+                    console.log(chalk.gray(`    ${line}`))
+                  }
+                })
+                if (result.stderr.split('\n').length > 5) {
+                  console.log(chalk.gray('    ...'))
+                }
+              }
+            }
+          }
         }
 
         // Show success message
@@ -157,12 +304,67 @@ export const createCommand = new Command('create')
           console.log()
           console.log(chalk.gray('  Connect with:'))
           console.log(chalk.cyan(`  spindb connect ${containerName}`))
+
+          // Copy connection string to clipboard
+          if (options.start !== false) {
+            try {
+              const cmd = platform() === 'darwin' ? 'pbcopy' : 'xclip'
+              const args =
+                platform() === 'darwin' ? [] : ['-selection', 'clipboard']
+
+              await new Promise<void>((resolve, reject) => {
+                const proc = spawn(cmd, args, {
+                  stdio: ['pipe', 'inherit', 'inherit'],
+                })
+                proc.stdin?.write(connectionString)
+                proc.stdin?.end()
+                proc.on('close', (code) => {
+                  if (code === 0) resolve()
+                  else
+                    reject(
+                      new Error(`Clipboard command exited with code ${code}`),
+                    )
+                })
+                proc.on('error', reject)
+              })
+
+              console.log(chalk.gray('  Connection string copied to clipboard'))
+            } catch {
+              // Ignore clipboard errors
+            }
+          }
+
           console.log()
         }
       } catch (err) {
         const e = err as Error
+
+        // Check if this is a missing tool error
+        if (
+          e.message.includes('pg_restore not found') ||
+          e.message.includes('psql not found') ||
+          e.message.includes('pg_dump not found')
+        ) {
+          const missingTool = e.message.includes('pg_restore')
+            ? 'pg_restore'
+            : e.message.includes('pg_dump')
+              ? 'pg_dump'
+              : 'psql'
+          await promptInstallDependencies(missingTool)
+          process.exit(1)
+        }
+
         console.error(error(e.message))
         process.exit(1)
+      } finally {
+        // Clean up temp file if we created one
+        if (tempDumpPath) {
+          try {
+            await rm(tempDumpPath, { force: true })
+          } catch {
+            // Ignore cleanup errors
+          }
+        }
       }
     },
   )

package/cli/commands/deps.ts

@@ -0,0 +1,326 @@
+import { Command } from 'commander'
+import chalk from 'chalk'
+import { header, success, warning, error } from '../ui/theme'
+import { createSpinner } from '../ui/spinner'
+import {
+  detectPackageManager,
+  checkEngineDependencies,
+  getMissingDependencies,
+  getAllMissingDependencies,
+  installEngineDependencies,
+  installAllDependencies,
+  getManualInstallInstructions,
+  getCurrentPlatform,
+  type DependencyStatus,
+} from '../../core/dependency-manager'
+import {
+  engineDependencies,
+  getEngineDependencies,
+} from '../../config/os-dependencies'
+
+/**
+ * Format dependency status for display
+ */
+function formatStatus(status: DependencyStatus): string {
+  const { dependency, installed, path, version } = status
+
+  if (installed) {
+    const versionStr = version ? ` (${version})` : ''
+    const pathStr = path ? chalk.gray(` → ${path}`) : ''
+    return `  ${chalk.green('✓')} ${dependency.name}${versionStr}${pathStr}`
+  } else {
+    return `  ${chalk.red('✗')} ${dependency.name} ${chalk.gray('- not installed')}`
+  }
+}
+
+export const depsCommand = new Command('deps').description(
+  'Manage OS-level database client dependencies',
+)
+
+// =============================================================================
+// deps check
+// =============================================================================
+
+depsCommand
+  .command('check')
+  .description('Check status of database client tools')
+  .option('-e, --engine <engine>', 'Check dependencies for a specific engine')
+  .option('-a, --all', 'Check all dependencies for all engines')
+  .action(async (options: { engine?: string; all?: boolean }) => {
+    console.log(header('Dependency Status'))
+    console.log()
+
+    // Detect package manager
+    const packageManager = await detectPackageManager()
+    if (packageManager) {
+      console.log(`  Package Manager: ${chalk.cyan(packageManager.name)}`)
+    } else {
+      console.log(`  Package Manager: ${chalk.yellow('Not detected')}`)
+    }
+    console.log()
+
+    if (options.all || (!options.engine && !options.all)) {
+      // Check all engines
+      for (const engineConfig of engineDependencies) {
+        console.log(chalk.bold(`${engineConfig.displayName}:`))
+
+        const statuses = await checkEngineDependencies(engineConfig.engine)
+        for (const status of statuses) {
+          console.log(formatStatus(status))
+        }
+
+        const installed = statuses.filter((s) => s.installed).length
+        const total = statuses.length
+        if (installed === total) {
+          console.log(chalk.green(`  All ${total} dependencies installed`))
+        } else {
+          console.log(
+            chalk.yellow(`  ${installed}/${total} dependencies installed`),
+          )
+        }
+        console.log()
+      }
+    } else if (options.engine) {
+      // Check specific engine
+      const engineConfig = getEngineDependencies(options.engine)
+      if (!engineConfig) {
+        console.error(error(`Unknown engine: ${options.engine}`))
+        console.log(
+          chalk.gray(
+            `  Available engines: ${engineDependencies.map((e) => e.engine).join(', ')}`,
+          ),
+        )
+        process.exit(1)
+      }
+
+      console.log(chalk.bold(`${engineConfig.displayName}:`))
+
+      const statuses = await checkEngineDependencies(options.engine)
+      for (const status of statuses) {
+        console.log(formatStatus(status))
+      }
+
+      const installed = statuses.filter((s) => s.installed).length
+      const total = statuses.length
+      console.log()
+      if (installed === total) {
+        console.log(success(`All ${total} dependencies installed`))
+      } else {
+        console.log(warning(`${installed}/${total} dependencies installed`))
+        console.log()
+        console.log(
+          chalk.gray(`  Run: spindb deps install --engine ${options.engine}`),
+        )
+      }
+    }
+  })
+
+// =============================================================================
+// deps install
+// =============================================================================
+
+depsCommand
+  .command('install')
+  .description('Install missing database client tools')
+  .option(
+    '-e, --engine <engine>',
+    'Install dependencies for a specific engine (e.g., postgresql, mysql)',
+  )
+  .option('-a, --all', 'Install all missing dependencies for all engines')
+  .action(async (options: { engine?: string; all?: boolean }) => {
+    // Detect package manager first
+    const packageManager = await detectPackageManager()
+
+    if (!packageManager) {
+      console.log(error('No supported package manager detected'))
+      console.log()
+
+      const platform = getCurrentPlatform()
+      if (platform === 'darwin') {
+        console.log(chalk.gray('  macOS: Install Homebrew first:'))
+        console.log(
+          chalk.cyan(
+            '    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"',
+          ),
+        )
+      } else {
+        console.log(
+          chalk.gray('  Supported package managers: apt, yum, dnf, pacman'),
+        )
+      }
+      process.exit(1)
+    }
+
+    console.log(header('Installing Dependencies'))
+    console.log()
+    console.log(`  Using: ${chalk.cyan(packageManager.name)}`)
+    console.log()
+
+    if (options.all) {
+      // Install all missing dependencies
+      const missing = await getAllMissingDependencies()
+
+      if (missing.length === 0) {
+        console.log(success('All dependencies are already installed'))
+        return
+      }
+
+      console.log(`  Missing: ${missing.map((d) => d.name).join(', ')}`)
+      console.log()
+
+      const spinner = createSpinner('Installing dependencies...')
+      spinner.start()
+
+      const results = await installAllDependencies(packageManager)
+
+      const succeeded = results.filter((r) => r.success)
+      const failed = results.filter((r) => !r.success)
+
+      if (failed.length === 0) {
+        spinner.succeed('All dependencies installed successfully')
+      } else {
+        spinner.warn('Some dependencies failed to install')
+        console.log()
+        for (const f of failed) {
+          console.log(error(`  ${f.dependency.name}: ${f.error}`))
+        }
+      }
+
+      if (succeeded.length > 0) {
+        console.log()
+        console.log(success(`Installed: ${succeeded.map((r) => r.dependency.name).join(', ')}`))
+      }
+    } else if (options.engine) {
+      // Install dependencies for specific engine
+      const engineConfig = getEngineDependencies(options.engine)
+      if (!engineConfig) {
+        console.error(error(`Unknown engine: ${options.engine}`))
+        console.log(
+          chalk.gray(
+            `  Available engines: ${engineDependencies.map((e) => e.engine).join(', ')}`,
+          ),
+        )
+        process.exit(1)
+      }
+
+      const missing = await getMissingDependencies(options.engine)
+
+      if (missing.length === 0) {
+        console.log(
+          success(`All ${engineConfig.displayName} dependencies are installed`),
+        )
+        return
+      }
+
+      console.log(`  Engine: ${chalk.cyan(engineConfig.displayName)}`)
+      console.log(`  Missing: ${missing.map((d) => d.name).join(', ')}`)
+      console.log()
+
+      const spinner = createSpinner(
+        `Installing ${engineConfig.displayName} dependencies...`,
+      )
+      spinner.start()
+
+      const results = await installEngineDependencies(
+        options.engine,
+        packageManager,
+      )
+
+      const succeeded = results.filter((r) => r.success)
+      const failed = results.filter((r) => !r.success)
+
+      if (failed.length === 0) {
+        spinner.succeed(
+          `${engineConfig.displayName} dependencies installed successfully`,
+        )
+      } else {
+        spinner.warn('Some dependencies failed to install')
+        console.log()
+        for (const f of failed) {
+          console.log(error(`  ${f.dependency.name}: ${f.error}`))
+        }
+
+        // Show manual instructions
+        console.log()
+        console.log(chalk.gray('  Manual installation:'))
+        const instructions = getManualInstallInstructions(
+          missing[0],
+          getCurrentPlatform(),
+        )
+        for (const instruction of instructions) {
+          console.log(chalk.gray(`    ${instruction}`))
+        }
+      }
+
+      if (succeeded.length > 0) {
+        console.log()
+        console.log(success(`Installed: ${succeeded.map((r) => r.dependency.name).join(', ')}`))
+      }
+    } else {
+      // Default: install PostgreSQL dependencies (most common use case)
+      console.log(
+        chalk.gray(
+          '  No engine specified, defaulting to PostgreSQL. Use --all for all engines.',
+        ),
+      )
+      console.log()
+
+      const missing = await getMissingDependencies('postgresql')
+
+      if (missing.length === 0) {
+        console.log(success('All PostgreSQL dependencies are installed'))
+        return
+      }
+
+      console.log(`  Missing: ${missing.map((d) => d.name).join(', ')}`)
+      console.log()
+
+      const spinner = createSpinner('Installing PostgreSQL dependencies...')
+      spinner.start()
+
+      const results = await installEngineDependencies('postgresql', packageManager)
+
+      const succeeded = results.filter((r) => r.success)
+      const failed = results.filter((r) => !r.success)
+
+      if (failed.length === 0) {
+        spinner.succeed('PostgreSQL dependencies installed successfully')
+      } else {
+        spinner.warn('Some dependencies failed to install')
+        console.log()
+        for (const f of failed) {
+          console.log(error(`  ${f.dependency.name}: ${f.error}`))
+        }
+      }
+
+      if (succeeded.length > 0) {
+        console.log()
+        console.log(success(`Installed: ${succeeded.map((r) => r.dependency.name).join(', ')}`))
+      }
+    }
+  })
+
+// =============================================================================
+// deps list
+// =============================================================================
+
+depsCommand
+  .command('list')
+  .description('List all supported dependencies')
+  .action(async () => {
+    console.log(header('Supported Dependencies'))
+    console.log()
+
+    for (const engineConfig of engineDependencies) {
+      console.log(chalk.bold(`${engineConfig.displayName}:`))
+
+      for (const dep of engineConfig.dependencies) {
+        console.log(`  ${chalk.cyan(dep.name)} - ${dep.description}`)
+      }
+      console.log()
+    }
+
+    console.log(chalk.gray('Use: spindb deps check'))
+    console.log(chalk.gray('     spindb deps install --engine <engine>'))
+    console.log(chalk.gray('     spindb deps install --all'))
+  })