spindb 0.9.2 → 0.10.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/spindb.svg)](https://www.npmjs.com/package/spindb)
 [![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](LICENSE)
-[![Platform: macOS | Linux](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux-lightgrey.svg)](#supported-platforms)
+[![Platform: macOS | Linux | Windows](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)](#supported-platforms)
 
 **Local databases without the Docker baggage.**
 
@@ -140,9 +140,11 @@ That's it. Your database is running on `localhost:5432`, and your data persists
 | Versions | 14, 15, 16, 17 |
 | Default port | 5432 |
 | Default user | `postgres` |
-| Binary source | [zonky.io](https://github.com/zonkyio/embedded-postgres-binaries) |
+| Binary source | [zonky.io](https://github.com/zonkyio/embedded-postgres-binaries) (macOS/Linux), [EDB](https://www.enterprisedb.com/) (Windows) |
 
-SpinDB downloads PostgreSQL server binaries automatically. These are pre-compiled binaries from the zonky.io project, hosted on Maven Central. They're extracted from official PostgreSQL distributions and work on macOS and Linux (x64 and ARM64).
+SpinDB downloads PostgreSQL server binaries automatically:
+- **macOS/Linux:** Pre-compiled binaries from the zonky.io project, hosted on Maven Central
+- **Windows:** Official binaries from EnterpriseDB (EDB)
 
 **Why download binaries instead of using system PostgreSQL?** You might want PostgreSQL 14 for one project and 17 for another. SpinDB lets you run different versions side-by-side without conflicts.
 
@@ -170,6 +172,12 @@ brew install mysql
 # Ubuntu/Debian
 sudo apt install mysql-server
 
+# Windows (Chocolatey)
+choco install mysql
+
+# Windows (winget)
+winget install Oracle.MySQL
+
 # Check if SpinDB can find MySQL
 spindb deps check --engine mysql
 ```
@@ -561,11 +569,11 @@ When you stop a container:
 
 ### Binary Sources
 
-**PostgreSQL:** Server binaries are downloaded from [zonky.io/embedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres-binaries), a project that packages official PostgreSQL releases for embedding in applications. The binaries are hosted on Maven Central and support:
-- macOS (Apple Silicon and Intel)
-- Linux (x64 and ARM64)
+**PostgreSQL:** Server binaries are downloaded automatically:
+- **macOS/Linux:** From [zonky.io/embedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres-binaries), hosted on Maven Central
+- **Windows:** From [EnterpriseDB (EDB)](https://www.enterprisedb.com/download-postgresql-binaries), official PostgreSQL distributions
 
-**MySQL:** Uses your system's MySQL installation. SpinDB detects binaries from Homebrew, apt, pacman, or custom paths.
+**MySQL:** Uses your system's MySQL installation. SpinDB detects binaries from Homebrew (macOS), apt/pacman (Linux), or Chocolatey/winget/Scoop (Windows).
 
 ---
 
@@ -577,15 +585,14 @@ When you stop a container:
 | macOS | Intel (x64) | ✅ Supported |
 | Linux | x64 | ✅ Supported |
 | Linux | ARM64 | ✅ Supported |
-| Windows | Any | ❌ Not supported |
+| Windows | x64 | ✅ Supported |
 
-**Why no Windows?** The zonky.io project doesn't provide Windows binaries for PostgreSQL. Windows support would require a different binary source and significant testing.
+Windows uses EnterpriseDB (EDB) official binaries for PostgreSQL. MySQL and SQLite require system installations via Chocolatey, winget, or Scoop.
 
 ---
 
 ## Limitations
 
-- **No Windows support** - zonky.io doesn't provide Windows PostgreSQL binaries
 - **Client tools required** - `psql` and `mysql` must be installed separately for some operations
 - **Local only** - Databases bind to `127.0.0.1`; remote connections planned for v1.1
 - **MySQL requires system install** - Unlike PostgreSQL, we don't download MySQL binaries
@@ -653,16 +660,15 @@ rm -rf ~/.spindb
 
 ## Contributing
 
-See [CLAUDE.md](CLAUDE.md) for development setup and architecture documentation.
+Note: This repo currently assumes `pnpm` for running tests. `npm test` will shell out to `pnpm` and fail if `pnpm` isn't installed.
 
-### Running Tests
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and distribution info.
 
-```bash
-pnpm test           # All tests
-pnpm test:unit      # Unit tests only
-pnpm test:pg        # PostgreSQL integration
-pnpm test:mysql     # MySQL integration
-```
+See [ARCHITECTURE.md](ARCHITECTURE.md) for project architecture and comprehensive CLI command examples.
+
+See [CLAUDE.md](CLAUDE.md) for AI-assisted development context.
+
+See [ENGINES.md](ENGINES.md) for detailed engine documentation (backup formats, planned engines, etc.).
 
 ---
 

package/cli/commands/attach.ts

@@ -0,0 +1,108 @@
+import { Command } from 'commander'
+import { existsSync } from 'fs'
+import { resolve, basename } from 'path'
+import chalk from 'chalk'
+import { sqliteRegistry } from '../../engines/sqlite/registry'
+import { containerManager } from '../../core/container-manager'
+import { deriveContainerName } from '../../engines/sqlite/scanner'
+import { uiSuccess, uiError } from '../ui/theme'
+
+export const attachCommand = new Command('attach')
+  .description('Register an existing SQLite database with SpinDB')
+  .argument('<path>', 'Path to SQLite database file')
+  .option('-n, --name <name>', 'Container name (defaults to filename)')
+  .option('--json', 'Output as JSON')
+  .action(
+    async (
+      path: string,
+      options: { name?: string; json?: boolean },
+    ): Promise<void> => {
+      try {
+        const absolutePath = resolve(path)
+
+        // Verify file exists
+        if (!existsSync(absolutePath)) {
+          if (options.json) {
+            console.log(
+              JSON.stringify({ success: false, error: 'File not found' }),
+            )
+          } else {
+            console.error(uiError(`File not found: ${absolutePath}`))
+          }
+          process.exit(1)
+        }
+
+        // Check if already registered
+        if (await sqliteRegistry.isPathRegistered(absolutePath)) {
+          const entry = await sqliteRegistry.getByPath(absolutePath)
+          if (options.json) {
+            console.log(
+              JSON.stringify({
+                success: false,
+                error: 'Already registered',
+                existingName: entry?.name,
+              }),
+            )
+          } else {
+            console.error(
+              uiError(`File is already registered as "${entry?.name}"`),
+            )
+          }
+          process.exit(1)
+        }
+
+        // Determine container name
+        const containerName =
+          options.name || deriveContainerName(basename(absolutePath))
+
+        // Check if container name exists
+        if (await containerManager.exists(containerName)) {
+          if (options.json) {
+            console.log(
+              JSON.stringify({
+                success: false,
+                error: 'Container name already exists',
+              }),
+            )
+          } else {
+            console.error(uiError(`Container "${containerName}" already exists`))
+          }
+          process.exit(1)
+        }
+
+        // Register the file
+        await sqliteRegistry.add({
+          name: containerName,
+          filePath: absolutePath,
+          created: new Date().toISOString(),
+        })
+
+        if (options.json) {
+          console.log(
+            JSON.stringify({
+              success: true,
+              name: containerName,
+              filePath: absolutePath,
+            }),
+          )
+        } else {
+          console.log(
+            uiSuccess(
+              `Registered "${basename(absolutePath)}" as "${containerName}"`,
+            ),
+          )
+          console.log()
+          console.log(chalk.gray('  Connect with:'))
+          console.log(chalk.cyan(`    spindb connect ${containerName}`))
+        }
+      } catch (error) {
+        const e = error as Error
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: e.message }))
+        } else {
+          console.error(uiError(e.message))
+        }
+        process.exit(1)
+      }
+    },
+  )

package/cli/commands/create.ts

@@ -100,6 +100,12 @@ async function createSqliteContainer(
         restoreSpinner.succeed('Backup restored successfully')
       } catch (error) {
         restoreSpinner.fail('Failed to restore backup')
+        // Clean up the created container on restore failure
+        try {
+          await containerManager.delete(containerName, { force: true })
+        } catch {
+          // Ignore cleanup errors - still throw the original restore error
+        }
         throw error
       }
     }
@@ -282,6 +288,7 @@ export const createCommand = new Command('create')
         console.log()
 
         const dbEngine = getEngine(engine)
+        const isPostgreSQL = engine === Engine.PostgreSQL
 
         // SQLite has a simplified flow (no port, no start/stop)
         if (engine === Engine.SQLite) {
@@ -316,6 +323,60 @@ export const createCommand = new Command('create')
           }
         }
 
+        const portSpinner = createSpinner('Finding available port...')
+        portSpinner.start()
+
+        let port: number
+        if (options.port) {
+          port = parseInt(options.port, 10)
+          const available = await portManager.isPortAvailable(port)
+          if (!available) {
+            portSpinner.fail(`Port ${port} is already in use`)
+            process.exit(1)
+          }
+          portSpinner.succeed(`Using port ${port}`)
+        } else {
+          const { port: foundPort, isDefault } =
+            await portManager.findAvailablePort({
+              preferredPort: engineDefaults.defaultPort,
+              portRange: engineDefaults.portRange,
+            })
+          port = foundPort
+          if (isDefault) {
+            portSpinner.succeed(`Using default port ${port}`)
+          } else {
+            portSpinner.warn(
+              `Default port ${engineDefaults.defaultPort} is in use, using port ${port}`,
+            )
+          }
+        }
+
+        // For PostgreSQL, download binaries FIRST - they include client tools (psql, pg_dump, etc.)
+        // This avoids requiring a separate system installation of client tools
+        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 }) => {
+              binarySpinner.text = message
+            })
+            binarySpinner.succeed(
+              `${dbEngine.displayName} ${version} binaries downloaded`,
+            )
+          }
+        }
+
+        // Check dependencies (all engines need this)
+        // For PostgreSQL, this runs AFTER binary download so client tools are available
         const depsSpinner = createSpinner('Checking required tools...')
         depsSpinner.start()
 
@@ -350,54 +411,29 @@ export const createCommand = new Command('create')
           depsSpinner.succeed('Required tools available')
         }
 
-        const portSpinner = createSpinner('Finding available port...')
-        portSpinner.start()
+        // For MySQL (and other non-PostgreSQL server DBs), download binaries after dep check
+        if (!isPostgreSQL) {
+          const binarySpinner = createSpinner(
+            `Checking ${dbEngine.displayName} ${version} binaries...`,
+          )
+          binarySpinner.start()
 
-        let port: number
-        if (options.port) {
-          port = parseInt(options.port, 10)
-          const available = await portManager.isPortAvailable(port)
-          if (!available) {
-            portSpinner.fail(`Port ${port} is already in use`)
-            process.exit(1)
-          }
-          portSpinner.succeed(`Using port ${port}`)
-        } else {
-          const { port: foundPort, isDefault } =
-            await portManager.findAvailablePort({
-              preferredPort: engineDefaults.defaultPort,
-              portRange: engineDefaults.portRange,
-            })
-          port = foundPort
-          if (isDefault) {
-            portSpinner.succeed(`Using default port ${port}`)
+          const isInstalled = await dbEngine.isBinaryInstalled(version)
+          if (isInstalled) {
+            binarySpinner.succeed(
+              `${dbEngine.displayName} ${version} binaries ready (cached)`,
+            )
           } else {
-            portSpinner.warn(
-              `Default port ${engineDefaults.defaultPort} is in use, using port ${port}`,
+            binarySpinner.text = `Downloading ${dbEngine.displayName} ${version} binaries...`
+            await dbEngine.ensureBinaries(version, ({ message }) => {
+              binarySpinner.text = message
+            })
+            binarySpinner.succeed(
+              `${dbEngine.displayName} ${version} binaries downloaded`,
             )
           }
         }
 
-        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 }) => {
-            binarySpinner.text = message
-          })
-          binarySpinner.succeed(
-            `${dbEngine.displayName} ${version} binaries downloaded`,
-          )
-        }
-
         while (await containerManager.exists(containerName)) {
           console.log(
             chalk.yellow(`  Container "${containerName}" already exists.`),

package/cli/commands/detach.ts

@@ -0,0 +1,100 @@
+import { Command } from 'commander'
+import chalk from 'chalk'
+import { sqliteRegistry } from '../../engines/sqlite/registry'
+import { containerManager } from '../../core/container-manager'
+import { promptConfirm } from '../ui/prompts'
+import { uiSuccess, uiError, uiWarning } from '../ui/theme'
+import { Engine } from '../../types'
+
+export const detachCommand = new Command('detach')
+  .description('Unregister a SQLite database from SpinDB (keeps file on disk)')
+  .argument('<name>', 'Container name')
+  .option('-f, --force', 'Skip confirmation prompt')
+  .option('--json', 'Output as JSON')
+  .action(
+    async (
+      name: string,
+      options: { force?: boolean; json?: boolean },
+    ): Promise<void> => {
+      try {
+        // Get container config
+        const config = await containerManager.getConfig(name)
+
+        if (!config) {
+          if (options.json) {
+            console.log(
+              JSON.stringify({ success: false, error: 'Container not found' }),
+            )
+          } else {
+            console.error(uiError(`Container "${name}" not found`))
+          }
+          process.exit(1)
+        }
+
+        // Verify it's a SQLite container
+        if (config.engine !== Engine.SQLite) {
+          if (options.json) {
+            console.log(
+              JSON.stringify({
+                success: false,
+                error:
+                  'Not a SQLite container. Use "spindb delete" for server databases.',
+              }),
+            )
+          } else {
+            console.error(uiError(`"${name}" is not a SQLite container`))
+            console.log(
+              chalk.gray(
+                '  Use "spindb delete" for server databases (PostgreSQL, MySQL)',
+              ),
+            )
+          }
+          process.exit(1)
+        }
+
+        // Confirm unless --force
+        if (!options.force && !options.json) {
+          const confirmed = await promptConfirm(
+            `Detach "${name}" from SpinDB? (file will be kept on disk)`,
+            true,
+          )
+          if (!confirmed) {
+            console.log(uiWarning('Cancelled'))
+            return
+          }
+        }
+
+        const entry = await sqliteRegistry.get(name)
+        const filePath = entry?.filePath
+
+        // Remove from registry only (not the file)
+        await sqliteRegistry.remove(name)
+
+        if (options.json) {
+          console.log(
+            JSON.stringify({
+              success: true,
+              name,
+              filePath,
+            }),
+          )
+        } else {
+          console.log(uiSuccess(`Detached "${name}" from SpinDB`))
+          if (filePath) {
+            console.log(chalk.gray(`  File remains at: ${filePath}`))
+          }
+          console.log()
+          console.log(chalk.gray('  Re-attach with:'))
+          console.log(chalk.cyan(`    spindb attach ${filePath || '<path>'}`))
+        }
+      } catch (error) {
+        const e = error as Error
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: e.message }))
+        } else {
+          console.error(uiError(e.message))
+        }
+        process.exit(1)
+      }
+    },
+  )

package/cli/commands/doctor.ts

@@ -141,8 +141,9 @@ async function checkContainers(): Promise<HealthCheckResult> {
 async function checkSqliteRegistry(): Promise<HealthCheckResult> {
   try {
     const entries = await sqliteRegistry.list()
+    const ignoredFolders = await sqliteRegistry.listIgnoredFolders()
 
-    if (entries.length === 0) {
+    if (entries.length === 0 && ignoredFolders.length === 0) {
       return {
         name: 'SQLite Registry',
         status: 'ok',
@@ -153,11 +154,18 @@ async function checkSqliteRegistry(): Promise<HealthCheckResult> {
     const orphans = await sqliteRegistry.findOrphans()
 
     if (orphans.length > 0) {
+      const details = [
+        ...orphans.map((o) => `"${o.name}" → ${o.filePath}`),
+        ...(ignoredFolders.length > 0
+          ? [`${ignoredFolders.length} folder(s) ignored`]
+          : []),
+      ]
+
       return {
         name: 'SQLite Registry',
         status: 'warning',
         message: `${orphans.length} orphaned entr${orphans.length === 1 ? 'y' : 'ies'} found`,
-        details: orphans.map((o) => `"${o.name}" → ${o.filePath}`),
+        details,
         action: {
           label: 'Remove orphaned entries from registry',
           handler: async () => {
@@ -168,10 +176,16 @@ async function checkSqliteRegistry(): Promise<HealthCheckResult> {
       }
     }
 
+    const details = [`${entries.length} database(s) registered, all files exist`]
+    if (ignoredFolders.length > 0) {
+      details.push(`${ignoredFolders.length} folder(s) ignored`)
+    }
+
     return {
       name: 'SQLite Registry',
       status: 'ok',
       message: `${entries.length} database(s) registered, all files exist`,
+      details: ignoredFolders.length > 0 ? details : undefined,
     }
   } catch (error) {
     return {

package/cli/commands/edit.ts

@@ -521,6 +521,11 @@ export const editCommand = new Command('edit')
           spinner.start()
 
           try {
+            // Track if we need to delete source file after registry update
+            // (for cross-device moves where rename doesn't work)
+            let needsSourceCleanup = false
+            const originalPath = config.database
+
             // Try rename first (fast, same filesystem)
             try {
               renameSync(config.database, newPath)
@@ -531,8 +536,8 @@ export const editCommand = new Command('edit')
                 try {
                   // Copy file preserving mode/permissions
                   copyFileSync(config.database, newPath)
-                  // Only delete source after successful copy
-                  unlinkSync(config.database)
+                  // Don't delete source yet - wait for registry update to succeed
+                  needsSourceCleanup = true
                 } catch (copyErr) {
                   // Clean up partial target on failure
                   if (existsSync(newPath)) {
@@ -555,6 +560,11 @@ export const editCommand = new Command('edit')
             })
             await sqliteRegistry.update(containerName, { filePath: newPath })
 
+            // Now safe to delete source file for cross-device moves
+            if (needsSourceCleanup && existsSync(originalPath)) {
+              unlinkSync(originalPath)
+            }
+
             spinner.succeed(`Database relocated to ${newPath}`)
           } catch (error) {
             spinner.fail('Failed to relocate database')

package/cli/commands/engines.ts

@@ -3,6 +3,10 @@ import chalk from 'chalk'
 import { rm } from 'fs/promises'
 import inquirer from 'inquirer'
 import { containerManager } from '../../core/container-manager'
+import { getEngine } from '../../engines'
+import { binaryManager } from '../../core/binary-manager'
+import { paths } from '../../config/paths'
+import { platformService } from '../../core/platform-service'
 import { promptConfirm } from '../ui/prompts'
 import { createSpinner } from '../ui/spinner'
 import { uiError, uiWarning, uiInfo, formatBytes } from '../ui/theme'
@@ -14,6 +18,7 @@ import {
   type InstalledMysqlEngine,
   type InstalledSqliteEngine,
 } from '../helpers'
+import { Engine } from '../../types'
 
 /**
  * Pad string to width, accounting for emoji taking 2 display columns
@@ -279,3 +284,59 @@ enginesCommand
       }
     },
   )
+
+// Download subcommand
+enginesCommand
+  .command('download <engine> <version>')
+  .description('Download engine binaries (PostgreSQL only)')
+  .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 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.`),
+        )
+        return
+      }
+
+      const spinner = createSpinner(
+        `Downloading PostgreSQL ${version} binaries...`,
+      )
+      spinner.start()
+
+      await engine.ensureBinaries(version, ({ message }) => {
+        spinner.text = message
+      })
+
+      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}`))
+    } catch (error) {
+      const e = error as Error
+      console.error(uiError(e.message))
+      process.exit(1)
+    }
+  })