spindb 0.37.2 → 0.38.0

package/engines/couchdb/restore.ts

@@ -1,290 +0,0 @@
-/**
- * CouchDB restore module
- * Supports JSON-based restore using CouchDB's REST API
- */
-
-import { readFile, open } from 'fs/promises'
-import { existsSync, statSync } from 'fs'
-import { logDebug } from '../../core/error-handler'
-import { couchdbApiRequest } from './api-client'
-import type { BackupFormat, RestoreResult } from '../../types'
-
-// Restore operations may take longer than the default timeout
-const RESTORE_TIMEOUT_MS = 600000 // 10 minutes
-
-type CouchDBBackup = {
-  version: string
-  created: string
-  databases: Array<{
-    name: string
-    docs: unknown[]
-  }>
-}
-
-/**
- * Detect backup format from file
- * CouchDB backups are JSON files
- */
-export async function detectBackupFormat(
-  filePath: string,
-): Promise<BackupFormat> {
-  if (!existsSync(filePath)) {
-    throw new Error(`Backup file not found: ${filePath}`)
-  }
-
-  const stats = statSync(filePath)
-
-  if (stats.isDirectory()) {
-    return {
-      format: 'unknown',
-      description: 'Directory found - CouchDB uses single JSON files',
-      restoreCommand: 'CouchDB requires a single .json file for restore',
-    }
-  }
-
-  // Check file extension
-  if (filePath.endsWith('.json') || filePath.endsWith('.couchdb')) {
-    return {
-      format: 'json',
-      description: 'CouchDB JSON backup',
-      restoreCommand: 'spindb restore handles this automatically',
-    }
-  }
-
-  // Check file contents for JSON structure
-  try {
-    const buffer = Buffer.alloc(100)
-    const fd = await open(filePath, 'r')
-    try {
-      await fd.read(buffer, 0, 100, 0)
-      const content = buffer.toString('utf-8').trim()
-
-      // Check if it looks like our backup format
-      if (content.startsWith('{') && content.includes('"version"')) {
-        return {
-          format: 'json',
-          description: 'CouchDB JSON backup (detected by content)',
-          restoreCommand: 'spindb restore handles this automatically',
-        }
-      }
-    } finally {
-      await fd.close().catch(() => {})
-    }
-  } catch (error) {
-    logDebug(`Error reading backup file header: ${error}`)
-  }
-
-  return {
-    format: 'unknown',
-    description: 'Unknown backup format',
-    restoreCommand: 'Use .json or .couchdb file for restore',
-  }
-}
-
-// Restore options for CouchDB
-export type RestoreOptions = {
-  port: number
-  database?: string
-  flush?: boolean
-}
-
-/**
- * Restore from JSON backup
- *
- * @param backupPath - Path to the backup file
- * @param options - Restore options including port and optional target database
- */
-export async function restoreBackup(
-  backupPath: string,
-  options: RestoreOptions,
-): Promise<RestoreResult> {
-  const { port, database: targetDatabase, flush } = options
-
-  if (!existsSync(backupPath)) {
-    throw new Error(`Backup file not found: ${backupPath}`)
-  }
-
-  // Detect backup format
-  const format = await detectBackupFormat(backupPath)
-  logDebug(`Detected backup format: ${format.format}`)
-
-  if (format.format !== 'json') {
-    throw new Error(
-      `Invalid backup format: ${format.format}. Use .json or .couchdb file for restore.`,
-    )
-  }
-
-  // Read and parse backup file
-  const content = await readFile(backupPath, 'utf-8')
-  let backup: CouchDBBackup
-
-  try {
-    backup = JSON.parse(content) as CouchDBBackup
-  } catch (error) {
-    throw new Error(`Invalid backup file: failed to parse JSON - ${error}`)
-  }
-
-  if (!backup.databases || !Array.isArray(backup.databases)) {
-    throw new Error('Invalid backup file: missing databases array')
-  }
-
-  logDebug(`Restoring ${backup.databases.length} database(s) from backup`)
-
-  let restoredCount = 0
-  const errors: string[] = []
-
-  for (const dbBackup of backup.databases) {
-    // Skip if targeting a specific database and this isn't it
-    if (targetDatabase && dbBackup.name !== targetDatabase) {
-      continue
-    }
-
-    const dbName = dbBackup.name
-    logDebug(
-      `Restoring database: ${dbName} (${dbBackup.docs.length} documents)`,
-    )
-
-    // Check if database exists
-    const checkResponse = await couchdbApiRequest(
-      port,
-      'GET',
-      `/${encodeURIComponent(dbName)}`,
-    )
-
-    if (checkResponse.status === 200) {
-      if (flush) {
-        // Delete existing database
-        const deleteResponse = await couchdbApiRequest(
-          port,
-          'DELETE',
-          `/${encodeURIComponent(dbName)}`,
-        )
-        // Accept 200 (OK) or 202 (Accepted) for async deletes
-        if (deleteResponse.status !== 200 && deleteResponse.status !== 202) {
-          errors.push(
-            `Failed to delete existing database ${dbName}: ${JSON.stringify(deleteResponse.data)}`,
-          )
-          continue
-        }
-      } else {
-        logDebug(`Database ${dbName} exists, merging documents`)
-      }
-    }
-
-    // Create database if it doesn't exist (or was just deleted)
-    if (checkResponse.status === 404 || flush) {
-      const createResponse = await couchdbApiRequest(
-        port,
-        'PUT',
-        `/${encodeURIComponent(dbName)}`,
-      )
-      if (createResponse.status !== 201 && createResponse.status !== 412) {
-        // 412 means database already exists, which is fine
-        errors.push(
-          `Failed to create database ${dbName}: ${JSON.stringify(createResponse.data)}`,
-        )
-        continue
-      }
-    }
-
-    // Prepare documents for bulk insert
-    // Remove _rev to allow inserting as new documents
-    const docsToInsert = dbBackup.docs.map((doc) => {
-      const d = doc as Record<string, unknown>
-      const { _rev: _, ...rest } = d
-      return rest
-    })
-
-    if (docsToInsert.length === 0) {
-      logDebug(`No documents to restore for ${dbName}`)
-      restoredCount++
-      continue
-    }
-
-    // Bulk insert documents
-    const bulkResponse = await couchdbApiRequest(
-      port,
-      'POST',
-      `/${encodeURIComponent(dbName)}/_bulk_docs`,
-      { docs: docsToInsert },
-      RESTORE_TIMEOUT_MS,
-    )
-
-    if (bulkResponse.status !== 201) {
-      errors.push(
-        `Failed to restore documents to ${dbName}: ${JSON.stringify(bulkResponse.data)}`,
-      )
-      continue
-    }
-
-    restoredCount++
-    logDebug(`Restored ${docsToInsert.length} documents to ${dbName}`)
-  }
-
-  const message =
-    `Restored ${restoredCount} database(s)` +
-    (errors.length > 0 ? ` with ${errors.length} error(s)` : '')
-
-  return {
-    format: 'json',
-    stdout: message,
-    stderr: errors.length > 0 ? errors.join('\n') : undefined,
-    code: errors.length > 0 ? 1 : 0,
-  }
-}
-
-/**
- * Parse CouchDB connection string
- * Format: http://host[:port][/database] or https://host[:port][/database]
- */
-export function parseConnectionString(connectionString: string): {
-  host: string
-  port: number
-  protocol: 'http' | 'https'
-  database?: string
-} {
-  if (!connectionString || typeof connectionString !== 'string') {
-    throw new Error(
-      'Invalid CouchDB connection string: expected a non-empty string',
-    )
-  }
-
-  let url: URL
-  try {
-    url = new URL(connectionString)
-  } catch (error) {
-    throw new Error(
-      `Invalid CouchDB connection string: "${connectionString}". ` +
-        `Expected format: http://host[:port][/database]`,
-      { cause: error },
-    )
-  }
-
-  // Validate protocol
-  let protocol: 'http' | 'https'
-  if (url.protocol === 'http:') {
-    protocol = 'http'
-  } else if (url.protocol === 'https:') {
-    protocol = 'https'
-  } else {
-    throw new Error(
-      `Invalid CouchDB connection string: unsupported protocol "${url.protocol}". ` +
-        `Expected "http://" or "https://"`,
-    )
-  }
-
-  const host = url.hostname || '127.0.0.1'
-  const port = parseInt(url.port, 10) || 5984
-
-  // Extract database from pathname (e.g., /mydb)
-  const pathname = url.pathname || ''
-  const database =
-    pathname.length > 1 ? pathname.slice(1).split('/')[0] : undefined
-
-  return {
-    host,
-    port,
-    protocol,
-    database,
-  }
-}

package/engines/couchdb/version-maps.ts

@@ -1,78 +0,0 @@
-/**
- * CouchDB Version Maps
- *
- * TEMPORARY: This version map will be replaced by the hostdb npm package once published.
- * Until then, manually keep this in sync with robertjbass/hostdb releases.json:
- * https://github.com/robertjbass/hostdb/blob/main/releases.json
- *
- * When updating versions:
- * 1. Check hostdb releases.json for available versions
- * 2. Update COUCHDB_VERSION_MAP to match
- */
-
-import { logDebug } from '../../core/error-handler'
-
-/**
- * Map of major CouchDB versions to their latest stable patch versions.
- * Must match versions available in hostdb releases.json.
- */
-export const COUCHDB_VERSION_MAP: Record<string, string> = {
-  // 1-part: major version -> latest
-  '3': '3.5.1',
-  // 2-part: major.minor -> latest patch
-  '3.5': '3.5.1',
-  // 3-part: exact version (identity mapping)
-  '3.5.1': '3.5.1',
-}
-
-/**
- * Supported major CouchDB versions (1-part format).
- * Used for grouping and display purposes.
- */
-export const SUPPORTED_MAJOR_VERSIONS = ['3']
-
-/**
- * Get the full version string for a major version.
- *
- * @param majorVersion - Major version (e.g., '3')
- * @returns Full version string (e.g., '3.5.1') or null if not supported
- */
-export function getFullVersion(majorVersion: string): string | null {
-  return COUCHDB_VERSION_MAP[majorVersion] || null
-}
-
-/**
- * Normalize a version string to X.Y.Z format.
- *
- * @param version - Version string (e.g., '3', '3.5', '3.5.1')
- * @returns Normalized version (e.g., '3.5.1')
- */
-export function normalizeVersion(version: string): string {
-  // If it's in the version map (major, major.minor, or full version), return the mapped value
-  // Note: Full versions have identity mappings (e.g., '3.5.1' => '3.5.1')
-  const fullVersion = COUCHDB_VERSION_MAP[version]
-  if (fullVersion) {
-    return fullVersion
-  }
-
-  // Unknown version - warn and return as-is
-  // This may cause download failures if the version doesn't exist in hostdb
-  const parts = version.split('.')
-
-  // Validate format: must be 1-3 numeric segments (e.g., "3", "3.5", "3.5.1")
-  const isValidFormat =
-    parts.length >= 1 &&
-    parts.length <= 3 &&
-    parts.every((p) => /^\d+$/.test(p))
-
-  if (!isValidFormat) {
-    logDebug(
-      `CouchDB version '${version}' has invalid format, may not be available in hostdb`,
-    )
-  } else {
-    logDebug(
-      `CouchDB version '${version}' not in version map, may not be available in hostdb`,
-    )
-  }
-  return version
-}

package/engines/couchdb/version-validator.ts

@@ -1,111 +0,0 @@
-/**
- * CouchDB Version Validator
- *
- * Utilities for parsing, validating, and comparing CouchDB versions.
- */
-
-import { COUCHDB_VERSION_MAP, SUPPORTED_MAJOR_VERSIONS } from './version-maps'
-
-/**
- * Parsed CouchDB version
- */
-export type ParsedVersion = {
-  major: number
-  minor: number
-  patch: number
-  full: string
-}
-
-/**
- * Parse a CouchDB version string into components.
- *
- * @param version - Version string (e.g., '3.5.1')
- * @returns Parsed version object or null if invalid
- */
-export function parseVersion(version: string): ParsedVersion | null {
-  const match = version.match(/^(\d+)\.(\d+)\.(\d+)$/)
-  if (!match) {
-    return null
-  }
-
-  const [, major, minor, patch] = match
-  return {
-    major: parseInt(major, 10),
-    minor: parseInt(minor, 10),
-    patch: parseInt(patch, 10),
-    full: version,
-  }
-}
-
-/**
- * Check if a version string is supported.
- *
- * @param version - Version string (e.g., '3', '3.5', '3.5.1')
- * @returns true if the version is supported
- */
-export function isVersionSupported(version: string): boolean {
-  // Check if it's in the version map
-  if (COUCHDB_VERSION_MAP[version]) {
-    return true
-  }
-
-  // Check if major version is supported
-  const parts = version.split('.')
-  const major = parts[0]
-  return SUPPORTED_MAJOR_VERSIONS.includes(major)
-}
-
-/**
- * Get the major version from a version string.
- *
- * @param version - Version string (e.g., '3.5.1')
- * @returns Major version string (e.g., '3')
- */
-export function getMajorVersion(version: string): string {
-  const parts = version.split('.')
-  return parts[0]
-}
-
-/**
- * Compare two version strings.
- *
- * @param a - First version string
- * @param b - Second version string
- * @returns -1 if a < b, 0 if a == b, 1 if a > b
- */
-export function compareVersions(a: string, b: string): number {
-  const parsedA = parseVersion(a)
-  const parsedB = parseVersion(b)
-
-  if (!parsedA || !parsedB) {
-    // Fall back to string comparison for invalid versions
-    return a.localeCompare(b)
-  }
-
-  if (parsedA.major !== parsedB.major) {
-    return parsedA.major - parsedB.major
-  }
-  if (parsedA.minor !== parsedB.minor) {
-    return parsedA.minor - parsedB.minor
-  }
-  return parsedA.patch - parsedB.patch
-}
-
-/**
- * Check if two versions are compatible for backup/restore operations.
- * CouchDB versions within the same major version are generally compatible.
- *
- * @param sourceVersion - Source version
- * @param targetVersion - Target version
- * @returns true if versions are compatible
- */
-export function isVersionCompatible(
-  sourceVersion: string,
-  targetVersion: string,
-): boolean {
-  const sourceMajor = getMajorVersion(sourceVersion)
-  const targetMajor = getMajorVersion(targetVersion)
-
-  // Same major version is compatible
-  return sourceMajor === targetMajor
-}

package/engines/duckdb/README.md

@@ -1,154 +0,0 @@
-# DuckDB Engine Implementation
-
-## Overview
-
-DuckDB is an embedded OLAP (analytical) database. Like SQLite, it's file-based with no server process. DuckDB is optimized for analytical queries and columnar storage.
-
-## Platform Support
-
-| Platform | Architecture | Status | Notes |
-|----------|--------------|--------|-------|
-| darwin | x64 | Supported | Uses hostdb binaries |
-| darwin | arm64 | Supported | Uses hostdb binaries (Apple Silicon) |
-| linux | x64 | Supported | Uses hostdb binaries |
-| linux | arm64 | Supported | Uses hostdb binaries |
-| win32 | x64 | Supported | Uses hostdb binaries |
-
-## Binary Packaging
-
-### Archive Format
-- **Unix (macOS/Linux)**: `tar.gz`
-- **Windows**: `zip`
-
-### Archive Structure - FLAT (No bin/ Subdirectory)
-
-Like SQLite, DuckDB archives have a **flat structure**:
-
-```
-duckdb              # Main CLI binary
-```
-
-The `BaseEmbeddedBinaryManager` handles moving this to `bin/` during extraction.
-
-### Version Map Sync
-
-```typescript
-export const DUCKDB_VERSION_MAP: Record<string, string> = {
-  '1': '1.4.3',
-}
-```
-
-## Implementation Details
-
-### Binary Manager
-
-DuckDB uses `BaseEmbeddedBinaryManager` with the same file-based model as SQLite.
-
-### Version Parsing
-
-- **Version output format**: `v1.4.3 abcdef123`
-- **Parse pattern**: `/v?(\d+\.\d+\.\d+)/`
-
-### File-Based Model
-
-Same as SQLite:
-- **No start/stop**: No-ops
-- **No port**: Port is always 0
-- **No container directory**: Data in user's project directory
-- **Registry tracking**: `~/.spindb/config.json` tracks files
-
-### Attach/Detach Commands
-
-- `spindb attach <path>` - Register existing DuckDB file
-- `spindb detach <name>` - Unregister (keeps file)
-
-### Connection String Format
-
-```
-duckdb:/path/to/database.duckdb
-```
-
-Or simply the file path.
-
-## Backup & Restore
-
-### Backup Formats
-
-| Format | Extension | Tool | Notes |
-|--------|-----------|------|-------|
-| sql | `.sql` | Custom export | SQL statements |
-| binary | `.duckdb` | File copy | Direct file copy |
-
-### OLAP Considerations
-
-DuckDB backups may be larger than equivalent SQLite backups due to columnar storage format. Binary backup preserves columnar layout for fast analytical queries.
-
-## Integration Test Notes
-
-### Test Fixtures
-
-Located in `tests/fixtures/duckdb/seeds/`:
-- Test data for OLAP operations
-
-### No Port Allocation
-
-Like SQLite, no server means no ports.
-
-## Docker E2E Test Notes
-
-DuckDB Docker E2E tests verify:
-- File operations
-- SQL execution
-- Backup/restore
-- Attach/detach workflow
-
-## Known Issues & Gotchas
-
-### 1. Flat Archive Structure
-
-Same as SQLite - binaries at root, not in `bin/`.
-
-### 2. OLAP vs OLTP
-
-DuckDB is optimized for analytical (OLAP) workloads:
-- Fast columnar scans
-- Efficient aggregations
-- May be slower for single-row operations
-
-### 3. Memory Usage
-
-DuckDB uses memory aggressively for performance. Large analytical queries may consume significant RAM.
-
-### 4. File Extensions
-
-DuckDB databases typically use `.duckdb` or `.db` extension. The engine accepts any extension.
-
-### 5. Concurrent Access
-
-DuckDB allows multiple readers but only one writer. Similar to SQLite's locking model.
-
-### 6. Extensions
-
-DuckDB supports extensions (parquet, httpfs, etc.). Extension loading requires the binary to be in a writable location.
-
-## DuckDB vs SQLite
-
-| Feature | DuckDB | SQLite |
-|---------|--------|--------|
-| Workload | OLAP (analytical) | OLTP (transactional) |
-| Storage | Columnar | Row-based |
-| Large scans | Very fast | Slower |
-| Single rows | Slower | Very fast |
-| Memory | Aggressive | Conservative |
-
-## CI/CD Notes
-
-### GitHub Actions Cache Step
-
-```yaml
-- name: Cache DuckDB binaries
-  uses: actions/cache@v4
-  with:
-    path: ~/.spindb/bin/duckdb-*
-    key: duckdb-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('engines/duckdb/version-maps.ts') }}
-```

package/engines/duckdb/binary-manager.ts

@@ -1,45 +0,0 @@
-/**
- * DuckDB Binary Manager
- *
- * Handles downloading, extracting, and managing DuckDB binaries from hostdb.
- * Unlike other engines, DuckDB is an embedded database (not a server).
- * This manager handles the duckdb CLI tool.
- */
-
-import {
-  BaseEmbeddedBinaryManager,
-  type EmbeddedBinaryManagerConfig,
-} from '../../core/base-embedded-binary-manager'
-import { getBinaryUrl } from './binary-urls'
-import { normalizeVersion } from './version-maps'
-import { Engine, type Platform, type Arch } from '../../types'
-
-class DuckDBBinaryManager extends BaseEmbeddedBinaryManager {
-  protected readonly config: EmbeddedBinaryManagerConfig = {
-    engine: Engine.DuckDB,
-    engineName: 'duckdb',
-    displayName: 'DuckDB',
-    primaryBinary: 'duckdb',
-    executableNames: ['duckdb'],
-  }
-
-  protected getBinaryUrlFromModule(
-    version: string,
-    platform: Platform,
-    arch: Arch,
-  ): string {
-    return getBinaryUrl(version, platform, arch)
-  }
-
-  protected normalizeVersionFromModule(version: string): string {
-    return normalizeVersion(version)
-  }
-
-  protected parseVersionFromOutput(stdout: string): string | null {
-    // Extract version from output like "v1.4.3 abcdef123"
-    const match = stdout.match(/v?(\d+\.\d+\.\d+)/)
-    return match?.[1] ?? null
-  }
-}
-
-export const duckdbBinaryManager = new DuckDBBinaryManager()

package/engines/duckdb/hostdb-releases.ts

@@ -1,23 +0,0 @@
-/**
- * hostdb Releases Module for DuckDB
- *
- * Fetches DuckDB binary information from the hostdb repository at
- * https://github.com/robertjbass/hostdb
- */
-
-import { createHostdbReleases } from '../../core/hostdb-releases-factory'
-import { DUCKDB_VERSION_MAP, SUPPORTED_MAJOR_VERSIONS } from './version-maps'
-import { duckdbBinaryManager } from './binary-manager'
-import { Engine } from '../../types'
-
-const hostdbReleases = createHostdbReleases({
-  engine: Engine.DuckDB,
-  displayName: 'DuckDB',
-  versionMap: DUCKDB_VERSION_MAP,
-  supportedMajorVersions: SUPPORTED_MAJOR_VERSIONS,
-  groupingStrategy: 'single-digit',
-  listInstalled: () => duckdbBinaryManager.listInstalled(),
-})
-
-export const fetchAvailableVersions = hostdbReleases.fetchAvailableVersions
-export const getLatestVersion = hostdbReleases.getLatestVersion