spindb 0.10.1 → 0.10.3

package/README.md

@@ -283,9 +283,22 @@ spindb stop mydb
 
 ```bash
 spindb delete mydb
-spindb delete mydb --force    # Skip confirmation
+spindb delete mydb --yes      # Skip confirmation prompt
+spindb delete mydb --force    # Force stop if running
+spindb delete mydb -fy        # Both: force stop + skip confirmation
 ```
 
+<details>
+<summary>All options</summary>
+
+| Option | Description |
+|--------|-------------|
+| `--force`, `-f` | Force stop if container is running before deleting |
+| `--yes`, `-y` | Skip confirmation prompt (for scripts/automation) |
+| `--json`, `-j` | Output result as JSON |
+
+</details>
+
 ### Data Operations
 
 #### `connect` - Open database shell
@@ -345,13 +358,41 @@ spindb backup mydb --sql
 spindb backup mydb --dump
 ```
 
+<details>
+<summary>All options</summary>
+
+| Option | Description |
+|--------|-------------|
+| `--database`, `-d` | Database to backup (defaults to primary) |
+| `--name`, `-n` | Custom backup filename (without extension) |
+| `--output`, `-o` | Output directory (defaults to current directory) |
+| `--format` | Output format: `sql` or `dump` |
+| `--sql` | Shorthand for `--format sql` |
+| `--dump` | Shorthand for `--format dump` |
+| `--json`, `-j` | Output result as JSON |
+
+</details>
+
 #### `restore` - Restore from backup
 
 ```bash
 spindb restore mydb backup.dump
 spindb restore mydb backup.sql --database my_app
+spindb restore mydb --from-url "postgresql://user:pass@host/db"
 ```
 
+<details>
+<summary>All options</summary>
+
+| Option | Description |
+|--------|-------------|
+| `--database`, `-d` | Target database name |
+| `--from-url` | Pull data from a remote database connection string |
+| `--force`, `-f` | Overwrite existing database without confirmation |
+| `--json`, `-j` | Output result as JSON |
+
+</details>
+
 ### Container Management
 
 #### `list` - List all containers

package/cli/commands/create.ts

@@ -376,28 +376,26 @@ export const createCommand = new Command('create')
           }
         }
 
-        // For PostgreSQL, download binaries FIRST - they include client tools (psql, pg_dump, etc.)
-        // This avoids requiring a separate system installation of client tools
+        // For PostgreSQL, ensure binaries FIRST - they include client tools (psql, pg_dump, etc.)
+        // ensureBinaries also registers tool paths in config cache so getMissingDependencies can find them
         if (isPostgreSQL) {
           const binarySpinner = createSpinner(
             `Checking ${dbEngine.displayName} ${version} binaries...`,
           )
           binarySpinner.start()
 
-          const isInstalled = await dbEngine.isBinaryInstalled(version)
-          if (isInstalled) {
-            binarySpinner.succeed(
-              `${dbEngine.displayName} ${version} binaries ready (cached)`,
-            )
-          } else {
-            binarySpinner.text = `Downloading ${dbEngine.displayName} ${version} binaries...`
-            await dbEngine.ensureBinaries(version, ({ message }) => {
+          // Always call ensureBinaries - it handles cached binaries gracefully
+          // and registers client tool paths in config (needed for dependency checks)
+          await dbEngine.ensureBinaries(version, ({ stage, message }) => {
+            if (stage === 'cached') {
+              binarySpinner.text = `${dbEngine.displayName} ${version} binaries ready (cached)`
+            } else {
               binarySpinner.text = message
-            })
-            binarySpinner.succeed(
-              `${dbEngine.displayName} ${version} binaries downloaded`,
-            )
-          }
+            }
+          })
+          binarySpinner.succeed(
+            `${dbEngine.displayName} ${version} binaries ready`,
+          )
         }
 
         // Check dependencies (all engines need this)

package/cli/commands/engines.ts

@@ -7,9 +7,16 @@ import { getEngine } from '../../engines'
 import { binaryManager } from '../../core/binary-manager'
 import { paths } from '../../config/paths'
 import { platformService } from '../../core/platform-service'
+import {
+  detectPackageManager,
+  checkEngineDependencies,
+  installEngineDependencies,
+  getManualInstallInstructions,
+  getCurrentPlatform,
+} from '../../core/dependency-manager'
 import { promptConfirm } from '../ui/prompts'
 import { createSpinner } from '../ui/spinner'
-import { uiError, uiWarning, uiInfo, formatBytes } from '../ui/theme'
+import { uiError, uiWarning, uiInfo, uiSuccess, formatBytes } from '../ui/theme'
 import { getEngineIcon, ENGINE_ICONS } from '../constants'
 import {
   getInstalledEngines,
@@ -250,6 +257,80 @@ async function deleteEngine(
   }
 }
 
+// Install an engine via system package manager
+async function installEngineViaPackageManager(
+  engine: string,
+  displayName: string,
+): Promise<void> {
+  // Check if already installed
+  const statuses = await checkEngineDependencies(engine)
+  const allInstalled = statuses.every((s) => s.installed)
+
+  if (allInstalled) {
+    console.log(uiInfo(`${displayName} is already installed.`))
+    for (const status of statuses) {
+      if (status.path) {
+        console.log(chalk.gray(`  ${status.dependency.binary}: ${status.path}`))
+      }
+    }
+    return
+  }
+
+  // Detect package manager
+  const packageManager = await detectPackageManager()
+
+  if (!packageManager) {
+    console.error(uiError('No supported package manager found.'))
+    console.log()
+    console.log(chalk.yellow('Manual installation instructions:'))
+    const platform = getCurrentPlatform()
+    const missingDeps = statuses.filter((s) => !s.installed)
+    for (const status of missingDeps) {
+      const instructions = getManualInstallInstructions(
+        status.dependency,
+        platform,
+      )
+      console.log(chalk.gray(`  ${status.dependency.name}:`))
+      for (const instruction of instructions) {
+        console.log(chalk.gray(`    ${instruction}`))
+      }
+    }
+    process.exit(1)
+  }
+
+  console.log(uiInfo(`Installing ${displayName} via ${packageManager.name}...`))
+  console.log()
+
+  // Install missing dependencies
+  const results = await installEngineDependencies(engine, packageManager)
+
+  // Report results
+  const succeeded = results.filter((r) => r.success)
+  const failed = results.filter((r) => !r.success)
+
+  if (succeeded.length > 0) {
+    console.log()
+    console.log(uiSuccess(`${displayName} installed successfully.`))
+
+    // Show installed paths
+    const newStatuses = await checkEngineDependencies(engine)
+    for (const status of newStatuses) {
+      if (status.installed && status.path) {
+        console.log(chalk.gray(`  ${status.dependency.binary}: ${status.path}`))
+      }
+    }
+  }
+
+  if (failed.length > 0) {
+    console.log()
+    console.error(uiError('Some components failed to install:'))
+    for (const result of failed) {
+      console.error(chalk.red(`  ${result.dependency.name}: ${result.error}`))
+    }
+    process.exit(1)
+  }
+}
+
 // Main engines command
 export const enginesCommand = new Command('engines')
   .description('Manage installed database engines')
@@ -287,53 +368,74 @@ enginesCommand
 
 // Download subcommand
 enginesCommand
-  .command('download <engine> <version>')
-  .description('Download engine binaries (PostgreSQL only)')
-  .action(async (engineName: string, version: string) => {
+  .command('download <engine> [version]')
+  .description('Download/install engine binaries')
+  .action(async (engineName: string, version?: string) => {
     try {
-      // Validate engine name
-      const validEngines = ['postgresql', 'pg', 'postgres']
-      if (!validEngines.includes(engineName.toLowerCase())) {
-        console.error(
-          uiError(
-            `Only PostgreSQL binaries can be downloaded. MySQL and SQLite use system installations.`,
-          ),
-        )
-        process.exit(1)
-      }
+      const normalizedEngine = engineName.toLowerCase()
+
+      // PostgreSQL: download binaries
+      if (['postgresql', 'pg', 'postgres'].includes(normalizedEngine)) {
+        if (!version) {
+          console.error(uiError('PostgreSQL requires a version (e.g., 17)'))
+          process.exit(1)
+        }
 
-      const engine = getEngine(Engine.PostgreSQL)
+        const engine = getEngine(Engine.PostgreSQL)
 
-      // Check if already installed
-      const isInstalled = await engine.isBinaryInstalled(version)
-      if (isInstalled) {
-        console.log(
-          uiInfo(`PostgreSQL ${version} binaries are already installed.`),
+        const spinner = createSpinner(
+          `Checking PostgreSQL ${version} binaries...`,
         )
+        spinner.start()
+
+        // Always call ensureBinaries - it handles cached binaries gracefully
+        // and registers client tool paths in config (needed for dependency checks)
+        let wasCached = false
+        await engine.ensureBinaries(version, ({ stage, message }) => {
+          if (stage === 'cached') {
+            wasCached = true
+            spinner.text = `PostgreSQL ${version} binaries ready (cached)`
+          } else {
+            spinner.text = message
+          }
+        })
+
+        if (wasCached) {
+          spinner.succeed(`PostgreSQL ${version} binaries already installed`)
+        } else {
+          spinner.succeed(`PostgreSQL ${version} binaries downloaded`)
+        }
+
+        // Show the path for reference
+        const { platform, arch } = platformService.getPlatformInfo()
+        const fullVersion = binaryManager.getFullVersion(version)
+        const binPath = paths.getBinaryPath({
+          engine: 'postgresql',
+          version: fullVersion,
+          platform,
+          arch,
+        })
+        console.log(chalk.gray(`  Location: ${binPath}`))
         return
       }
 
-      const spinner = createSpinner(
-        `Downloading PostgreSQL ${version} binaries...`,
-      )
-      spinner.start()
-
-      await engine.ensureBinaries(version, ({ message }) => {
-        spinner.text = message
-      })
+      // MySQL and SQLite: install via system package manager
+      if (['mysql', 'mariadb'].includes(normalizedEngine)) {
+        await installEngineViaPackageManager('mysql', 'MySQL')
+        return
+      }
 
-      spinner.succeed(`PostgreSQL ${version} binaries downloaded`)
+      if (['sqlite', 'sqlite3'].includes(normalizedEngine)) {
+        await installEngineViaPackageManager('sqlite', 'SQLite')
+        return
+      }
 
-      // Show the path for reference
-      const { platform, arch } = platformService.getPlatformInfo()
-      const fullVersion = binaryManager.getFullVersion(version)
-      const binPath = paths.getBinaryPath({
-        engine: 'postgresql',
-        version: fullVersion,
-        platform,
-        arch,
-      })
-      console.log(chalk.gray(`  Location: ${binPath}`))
+      console.error(
+        uiError(
+          `Unknown engine "${engineName}". Supported: postgresql, mysql, sqlite`,
+        ),
+      )
+      process.exit(1)
     } catch (error) {
       const e = error as Error
       console.error(uiError(e.message))

package/cli/ui/prompts.ts

@@ -608,18 +608,36 @@ export async function promptInstallDependencies(
   const engineDeps = getEngineDependencies(engine)
   const engineName = engineDeps?.displayName || engine
 
-  const { shouldInstall } = await inquirer.prompt<{ shouldInstall: string }>([
-    {
-      type: 'list',
-      name: 'shouldInstall',
-      message: `Would you like to install ${engineName} client tools now?`,
-      choices: [
-        { name: 'Yes, install now', value: 'yes' },
-        { name: 'No, I will install manually', value: 'no' },
-      ],
-      default: 'yes',
-    },
-  ])
+  // In CI environments (no TTY or CI env var), auto-install without prompting
+  const isCI = !!(
+    process.env.CI ||
+    process.env.GITHUB_ACTIONS ||
+    !process.stdin.isTTY
+  )
+
+  let shouldInstall = 'yes'
+
+  if (!isCI) {
+    const response = await inquirer.prompt<{ shouldInstall: string }>([
+      {
+        type: 'list',
+        name: 'shouldInstall',
+        message: `Would you like to install ${engineName} client tools now?`,
+        choices: [
+          { name: 'Yes, install now', value: 'yes' },
+          { name: 'No, I will install manually', value: 'no' },
+        ],
+        default: 'yes',
+      },
+    ])
+    shouldInstall = response.shouldInstall
+  } else {
+    console.log(
+      chalk.gray(
+        `  CI environment detected - auto-installing ${engineName} client tools...`,
+      ),
+    )
+  }
 
   if (shouldInstall === 'no') {
     console.log()

package/cli/ui/theme.ts

@@ -1,8 +1,5 @@
 import chalk from 'chalk'
 
-/**
- * Color theme for spindb CLI
- */
 export const theme = {
   // Brand colors
   primary: chalk.cyan,
@@ -45,9 +42,6 @@ export const theme = {
   },
 }
 
-/**
- * Format a header box
- */
 export function header(text: string): string {
   const line = '─'.repeat(text.length + 4)
   return `
@@ -57,61 +51,37 @@ ${chalk.cyan('└' + line + '┘')}
 `.trim()
 }
 
-/**
- * Format a success message
- */
 export function uiSuccess(message: string): string {
   return `${theme.icons.success} ${message}`
 }
 
-/**
- * Format an error message
- */
 export function uiError(message: string): string {
   return `${theme.icons.error} ${chalk.red(message)}`
 }
 
-/**
- * Format a warning message
- */
 export function uiWarning(message: string): string {
   return `${theme.icons.warning} ${chalk.yellow(message)}`
 }
 
-/**
- * Format an info message
- */
 export function uiInfo(message: string): string {
   return `${theme.icons.info} ${message}`
 }
 
-/**
- * Format a key-value pair
- */
 export function keyValue(key: string, value: string): string {
   return `${chalk.gray(key + ':')} ${value}`
 }
 
-/**
- * Strip ANSI escape codes to get actual string length
- */
 function stripAnsi(str: string): string {
   // eslint-disable-next-line no-control-regex
   return str.replace(/\x1B\[[0-9;]*m/g, '')
 }
 
-/**
- * Pad a string (accounting for ANSI codes) to a specific visible width
- */
 function padToWidth(str: string, width: number): string {
   const visibleLength = stripAnsi(str).length
   const padding = Math.max(0, width - visibleLength)
   return str + ' '.repeat(padding)
 }
 
-/**
- * Create a box with dynamic width based on content
- */
 export function box(lines: string[], padding: number = 2): string {
   // Calculate max visible width
   const maxWidth = Math.max(...lines.map((line) => stripAnsi(line).length))
@@ -136,9 +106,6 @@ export function box(lines: string[], padding: number = 2): string {
   return boxLines.join('\n')
 }
 
-/**
- * Format a connection string box
- */
 export function connectionBox(
   name: string,
   connectionString: string,
@@ -156,9 +123,6 @@ export function connectionBox(
   return box(lines)
 }
 
-/**
- * Format bytes into human-readable format (B, KB, MB, GB)
- */
 export function formatBytes(bytes: number): string {
   if (bytes === 0) return '0 B'
   const units = ['B', 'KB', 'MB', 'GB', 'TB']

package/core/binary-manager.ts

@@ -399,20 +399,197 @@ export class BinaryManager {
     onProgress?: ProgressCallback,
   ): Promise<string> {
     const fullVersion = this.getFullVersion(version)
+    let binPath: string
+
     if (await this.isInstalled(version, platform, arch)) {
       onProgress?.({
         stage: 'cached',
         message: 'Using cached PostgreSQL binaries',
       })
-      return paths.getBinaryPath({
+      binPath = paths.getBinaryPath({
         engine: 'postgresql',
         version: fullVersion,
         platform,
         arch,
       })
+    } else {
+      binPath = await this.download(version, platform, arch, onProgress)
+    }
+
+    // On Linux, zonky.io binaries don't include client tools (psql, pg_dump)
+    // Download them separately from the PostgreSQL apt repository
+    if (platform === 'linux') {
+      await this.ensureClientTools(binPath, version, onProgress)
     }
 
-    return this.download(version, platform, arch, onProgress)
+    return binPath
+  }
+
+  /**
+   * Ensure PostgreSQL client tools are available on Linux
+   * Downloads from PostgreSQL apt repository if missing
+   */
+  private async ensureClientTools(
+    binPath: string,
+    version: string,
+    onProgress?: ProgressCallback,
+  ): Promise<void> {
+    const clientTools = ['psql', 'pg_dump', 'pg_restore', 'pg_dumpall']
+    const binDir = join(binPath, 'bin')
+
+    // Check if client tools already exist
+    const missingTools = clientTools.filter(
+      (tool) => !existsSync(join(binDir, tool)),
+    )
+
+    if (missingTools.length === 0) {
+      return // All client tools already present
+    }
+
+    onProgress?.({
+      stage: 'downloading',
+      message: 'Downloading PostgreSQL client tools...',
+    })
+
+    const majorVersion = version.split('.')[0]
+    const tempDir = join(paths.bin, `temp-client-${majorVersion}`)
+
+    try {
+      await mkdir(tempDir, { recursive: true })
+
+      // Get the latest client package version from apt repository
+      const debUrl = await this.getClientPackageUrl(majorVersion)
+      const debFile = join(tempDir, 'postgresql-client.deb')
+
+      // Download the .deb package
+      const response = await fetch(debUrl)
+      if (!response.ok) {
+        throw new Error(`Failed to download client tools: ${response.status}`)
+      }
+
+      const fileStream = createWriteStream(debFile)
+      // @ts-expect-error - response.body is ReadableStream
+      await pipeline(response.body, fileStream)
+
+      onProgress?.({
+        stage: 'extracting',
+        message: 'Extracting PostgreSQL client tools...',
+      })
+
+      // Extract .deb using ar (available on Linux)
+      await execAsync(`ar -x "${debFile}"`, { cwd: tempDir })
+
+      // Find and extract data.tar.xz or data.tar.zst
+      const dataFile = await this.findDataTar(tempDir)
+      if (!dataFile) {
+        throw new Error('Could not find data archive in .deb package')
+      }
+
+      // Determine compression type and extract
+      const extractDir = join(tempDir, 'extracted')
+      await mkdir(extractDir, { recursive: true })
+
+      if (dataFile.endsWith('.xz')) {
+        await execAsync(`tar -xJf "${dataFile}" -C "${extractDir}"`)
+      } else if (dataFile.endsWith('.zst')) {
+        await execAsync(`tar --zstd -xf "${dataFile}" -C "${extractDir}"`)
+      } else if (dataFile.endsWith('.gz')) {
+        await execAsync(`tar -xzf "${dataFile}" -C "${extractDir}"`)
+      } else {
+        await execAsync(`tar -xf "${dataFile}" -C "${extractDir}"`)
+      }
+
+      // Copy client tools to the bin directory
+      const clientBinDir = join(
+        extractDir,
+        'usr',
+        'lib',
+        'postgresql',
+        majorVersion,
+        'bin',
+      )
+
+      if (existsSync(clientBinDir)) {
+        for (const tool of clientTools) {
+          const srcPath = join(clientBinDir, tool)
+          const destPath = join(binDir, tool)
+          if (existsSync(srcPath) && !existsSync(destPath)) {
+            await cp(srcPath, destPath)
+            await chmod(destPath, 0o755)
+          }
+        }
+      }
+
+      onProgress?.({
+        stage: 'complete',
+        message: 'PostgreSQL client tools installed',
+      })
+    } finally {
+      // Clean up temp directory
+      await rm(tempDir, { recursive: true, force: true })
+    }
+  }
+
+  /**
+   * Get the download URL for PostgreSQL client package from apt repository
+   */
+  private async getClientPackageUrl(majorVersion: string): Promise<string> {
+    const baseUrl = 'https://apt.postgresql.org/pub/repos/apt/pool/main/p'
+    const packageDir = `postgresql-${majorVersion}`
+    const indexUrl = `${baseUrl}/${packageDir}/`
+
+    try {
+      const response = await fetch(indexUrl)
+      if (!response.ok) {
+        throw new Error(`Failed to fetch package index: ${response.status}`)
+      }
+
+      const html = await response.text()
+
+      // Find the latest postgresql-client package for amd64
+      // Pattern: postgresql-client-17_17.x.x-x.pgdg+1_amd64.deb
+      const pattern = new RegExp(
+        `href="(postgresql-client-${majorVersion}_[^"]+_amd64\\.deb)"`,
+        'g',
+      )
+
+      const matches: string[] = []
+      let match
+      while ((match = pattern.exec(html)) !== null) {
+        // Skip debug symbols and snapshot versions
+        if (!match[1].includes('dbgsym') && !match[1].includes('~')) {
+          matches.push(match[1])
+        }
+      }
+
+      if (matches.length === 0) {
+        throw new Error(
+          `No client package found for PostgreSQL ${majorVersion}`,
+        )
+      }
+
+      // Sort to get the latest version and return the URL
+      matches.sort().reverse()
+      const latestPackage = matches[0]
+
+      return `${indexUrl}${latestPackage}`
+    } catch (error) {
+      const err = error as Error
+      throw new Error(`Failed to get client package URL: ${err.message}`)
+    }
+  }
+
+  /**
+   * Find data.tar.* file in extracted .deb
+   */
+  private async findDataTar(dir: string): Promise<string | null> {
+    const entries = await readdir(dir)
+    for (const entry of entries) {
+      if (entry.startsWith('data.tar')) {
+        return join(dir, entry)
+      }
+    }
+    return null
   }
 }