spindb 0.37.2 → 0.38.0

package/engines/sqlite/registry.ts

@@ -1,198 +0,0 @@
-/**
- * SQLite Registry Manager
- *
- * Unlike PostgreSQL/MySQL which store containers in ~/.spindb/containers/,
- * SQLite databases are stored in user project directories. This registry
- * tracks the file paths of all SQLite databases managed by SpinDB.
- *
- * The registry is now stored in ~/.spindb/config.json under registry.sqlite
- */
-
-import { existsSync } from 'fs'
-import { configManager } from '../../core/config-manager'
-import type { SQLiteEngineRegistry, SQLiteRegistryEntry } from '../../types'
-
-/**
- * SQLite Registry Manager
- * Manages the registry that tracks external SQLite database files
- * Data is stored in config.json under registry.sqlite
- */
-class SQLiteRegistryManager {
-  /**
-   * Load the registry from config.json
-   * Returns an empty registry if none exists
-   */
-  async load(): Promise<SQLiteEngineRegistry> {
-    return configManager.getSqliteRegistry()
-  }
-
-  // Save the registry to config.json
-  async save(registry: SQLiteEngineRegistry): Promise<void> {
-    await configManager.saveSqliteRegistry(registry)
-  }
-
-  /**
-   * Add a new entry to the registry
-   * @throws Error if a container with the same name or file path already exists
-   */
-  async add(entry: SQLiteRegistryEntry): Promise<void> {
-    const registry = await this.load()
-
-    // Check for duplicate name
-    if (registry.entries.some((e) => e.name === entry.name)) {
-      throw new Error(`SQLite container "${entry.name}" already exists`)
-    }
-
-    // Check for duplicate file path
-    if (registry.entries.some((e) => e.filePath === entry.filePath)) {
-      throw new Error(
-        `SQLite container for path "${entry.filePath}" already exists`,
-      )
-    }
-
-    registry.entries.push(entry)
-    await this.save(registry)
-  }
-
-  /**
-   * Get an entry by name
-   * Returns null if not found
-   */
-  async get(name: string): Promise<SQLiteRegistryEntry | null> {
-    const registry = await this.load()
-    return registry.entries.find((e) => e.name === name) || null
-  }
-
-  /**
-   * Remove an entry by name
-   * Returns true if the entry was found and removed, false otherwise
-   */
-  async remove(name: string): Promise<boolean> {
-    const registry = await this.load()
-    const index = registry.entries.findIndex((e) => e.name === name)
-
-    if (index === -1) {
-      return false
-    }
-
-    registry.entries.splice(index, 1)
-    await this.save(registry)
-    return true
-  }
-
-  /**
-   * Update an existing entry
-   * Returns true if the entry was found and updated, false otherwise
-   */
-  async update(
-    name: string,
-    updates: Partial<Omit<SQLiteRegistryEntry, 'name'>>,
-  ): Promise<boolean> {
-    const registry = await this.load()
-    const entry = registry.entries.find((e) => e.name === name)
-
-    if (!entry) {
-      return false
-    }
-
-    Object.assign(entry, updates)
-    await this.save(registry)
-    return true
-  }
-
-  // List all entries in the registry
-  async list(): Promise<SQLiteRegistryEntry[]> {
-    const registry = await this.load()
-    return registry.entries
-  }
-
-  // Check if a container with the given name exists
-  async exists(name: string): Promise<boolean> {
-    const entry = await this.get(name)
-    return entry !== null
-  }
-
-  // Find orphaned entries (where the file no longer exists)
-  async findOrphans(): Promise<SQLiteRegistryEntry[]> {
-    const registry = await this.load()
-    return registry.entries.filter((e) => !existsSync(e.filePath))
-  }
-
-  /**
-   * Remove all orphaned entries from the registry
-   * Returns the number of entries removed
-   */
-  async removeOrphans(): Promise<number> {
-    const registry = await this.load()
-    const originalCount = registry.entries.length
-
-    registry.entries = registry.entries.filter((e) => existsSync(e.filePath))
-
-    const removedCount = originalCount - registry.entries.length
-    if (removedCount > 0) {
-      await this.save(registry)
-    }
-
-    return removedCount
-  }
-
-  // Update the lastVerified timestamp for an entry
-  async updateVerified(name: string): Promise<void> {
-    await this.update(name, { lastVerified: new Date().toISOString() })
-  }
-
-  // Check if a file path is already registered (by any container)
-  async isPathRegistered(filePath: string): Promise<boolean> {
-    const registry = await this.load()
-    return registry.entries.some((e) => e.filePath === filePath)
-  }
-
-  /**
-   * Get the container name for a given file path
-   * Returns null if not found
-   */
-  async getByPath(filePath: string): Promise<SQLiteRegistryEntry | null> {
-    const registry = await this.load()
-    return registry.entries.find((e) => e.filePath === filePath) || null
-  }
-
-  // ============================================================
-  // Folder Ignore Methods
-  // ============================================================
-
-  // Check if a folder is in the ignore list
-  async isFolderIgnored(folderPath: string): Promise<boolean> {
-    const registry = await this.load()
-    return folderPath in registry.ignoreFolders
-  }
-
-  // Add a folder to the ignore list
-  async addIgnoreFolder(folderPath: string): Promise<void> {
-    const registry = await this.load()
-    registry.ignoreFolders[folderPath] = true
-    await this.save(registry)
-  }
-
-  /**
-   * Remove a folder from the ignore list
-   * Returns true if the folder was in the list and removed, false otherwise
-   */
-  async removeIgnoreFolder(folderPath: string): Promise<boolean> {
-    const registry = await this.load()
-    if (folderPath in registry.ignoreFolders) {
-      delete registry.ignoreFolders[folderPath]
-      await this.save(registry)
-      return true
-    }
-    return false
-  }
-
-  // List all ignored folders
-  async listIgnoredFolders(): Promise<string[]> {
-    const registry = await this.load()
-    return Object.keys(registry.ignoreFolders)
-  }
-}
-
-// Export singleton instance
-export const sqliteRegistry = new SQLiteRegistryManager()

package/engines/sqlite/scanner.ts

@@ -1,22 +0,0 @@
-/**
- * SQLite Scanner — thin wrapper around shared file-based-utils
- */
-
-import { Engine } from '../../types'
-import {
-  scanForUnregisteredFiles,
-  deriveContainerName as sharedDeriveContainerName,
-  type UnregisteredFile,
-} from '../file-based-utils'
-
-export type { UnregisteredFile }
-
-export async function scanForUnregisteredSqliteFiles(
-  directory?: string,
-): Promise<UnregisteredFile[]> {
-  return scanForUnregisteredFiles(Engine.SQLite, directory)
-}
-
-export function deriveContainerName(fileName: string): string {
-  return sharedDeriveContainerName(fileName, Engine.SQLite)
-}

package/engines/sqlite/version-maps.ts

@@ -1,64 +0,0 @@
-/**
- * SQLite 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 SQLITE_VERSION_MAP to match
- */
-
-import { logDebug } from '../../core/error-handler'
-
-/**
- * Map of major SQLite versions to their latest stable patch versions.
- * Must match versions available in hostdb releases.json.
- */
-export const SQLITE_VERSION_MAP: Record<string, string> = {
-  // 1-part: major version → latest
-  '3': '3.51.2',
-  // 2-part: major.minor → latest patch
-  '3.51': '3.51.2',
-  // 3-part: exact version (identity mapping)
-  '3.51.2': '3.51.2',
-}
-
-/**
- * Supported major SQLite 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.51.2') or null if not supported
- */
-export function getFullVersion(majorVersion: string): string | null {
-  return SQLITE_VERSION_MAP[majorVersion] || null
-}
-
-/**
- * Normalize a version string to X.Y.Z format.
- *
- * @param version - Version string (e.g., '3', '3.51', '3.51.2')
- * @returns Normalized version (e.g., '3.51.2')
- */
-export function normalizeVersion(version: string): string {
-  // If it's a version key in the map (major, major.minor, or full), return the mapped version
-  // Identity mappings for 3-part versions (e.g., '3.51.2' -> '3.51.2') are already in the map
-  const fullVersion = SQLITE_VERSION_MAP[version]
-  if (fullVersion) {
-    return fullVersion
-  }
-
-  // Unknown version - log at debug level and return as-is
-  // This may cause download failures if the version doesn't exist in hostdb
-  logDebug(
-    `SQLite version '${version}' not in version map, may not be available in hostdb`,
-  )
-  return version
-}

package/engines/surrealdb/README.md

@@ -1,218 +0,0 @@
-# SurrealDB Engine Implementation
-
-## Overview
-
-SurrealDB is a multi-model database supporting document, graph, and relational paradigms. It uses SurrealQL (SQL-like with graph traversal) for queries.
-
-## 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
-```
-surrealdb/
-└── bin/
-    └── surreal          # Unified binary
-```
-
-### Version Map Sync
-
-```typescript
-export const SURREALDB_VERSION_MAP: Record<string, string> = {
-  '2': '2.3.2',
-}
-```
-
-## Implementation Details
-
-### Binary Manager
-
-SurrealDB uses `BaseBinaryManager` with standard configuration.
-
-### Version Parsing
-
-- **Version output format**: `surreal 2.3.2 for linux on x86_64` or just `2.3.2`
-- **Parse pattern**: `/(\d+\.\d+\.\d+)/`
-
-### Default Configuration
-
-- **Default Port**: 8000 (auto-increments on conflict)
-- **Default Credentials**: `root` / `root`
-- **Storage Backend**: SurrealKV (`surrealkv://path`)
-- **Hierarchy**: Root > Namespace > Database
-- **PID File**: `surrealdb.pid` in container directory
-
-### Namespace Derivation
-
-Namespace is derived from container name:
-- `my-app` -> namespace `my_app` (dashes replaced with underscores)
-- Default database: `test`
-
-### Connection Schemes
-
-- **WebSocket**: `ws://127.0.0.1:{port}` (for real-time queries)
-- **HTTP**: `http://127.0.0.1:{port}` (REST API)
-
-### Critical: Background Process Stdio
-
-Like CockroachDB, **MUST use `stdio: ['ignore', 'ignore', 'ignore']`**:
-
-```typescript
-const proc = spawn(surrealBinary, args, {
-  stdio: ['ignore', 'ignore', 'ignore'],  // NOT 'pipe'
-  detached: true,
-  cwd: containerDir,  // For history file
-  windowsHide: true,
-})
-proc.unref()
-```
-
-Using `'pipe'` causes hangs in Docker/CI environments.
-
-### History File Handling
-
-SurrealDB writes `history.txt` to CWD. The engine sets `cwd` to container directory so history is stored in `~/.spindb/containers/surrealdb/<name>/history.txt` rather than polluting user's working directory.
-
-### Startup Command
-
-```bash
-surreal start \
-  --bind 127.0.0.1:{port} \
-  --user root \
-  --pass root \
-  surrealkv://{dataDir}
-```
-
-### Health Check
-
-```bash
-surreal isready --endpoint http://127.0.0.1:{port}
-```
-
-### CLI Shell
-
-```bash
-surreal sql --endpoint ws://127.0.0.1:{port}
-```
-
-### Scripting Flag
-
-Use `--hide-welcome` with `surreal sql` to suppress the welcome banner for scriptable/parseable output. The engine uses this automatically for non-interactive commands.
-
-## Backup & Restore
-
-### Backup Method
-
-Uses SurrealDB's native export/import:
-- `surreal export` - Creates SurrealQL script
-- `surreal import` - Restores from SurrealQL script
-
-## Integration Test Notes
-
-### Test Fixtures
-
-Located in `tests/fixtures/surrealdb/seeds/`:
-- SurrealQL scripts for testing
-
-## Docker E2E Test Notes
-
-SurrealDB Docker E2E tests verify:
-- Server lifecycle
-- SurrealQL operations
-- Multi-model features (if tested)
-- Export/import
-
-## Known Issues & Gotchas
-
-### 1. stdio Must Be 'ignore'
-
-**Critical**: Same as CockroachDB - using `stdio: 'pipe'` causes hangs. Always use `['ignore', 'ignore', 'ignore']`.
-
-### 2. History File Pollution
-
-Without setting `cwd`, SurrealDB writes `history.txt` to user's working directory. The engine sets `cwd` to container directory.
-
-### 3. Namespace/Database Hierarchy
-
-SurrealDB has a three-level hierarchy:
-- Root (authentication level)
-- Namespace (derived from container name)
-- Database (default: `test`)
-
-This differs from most other databases.
-
-### 4. WebSocket vs HTTP
-
-SurrealDB supports both WebSocket (`ws://`) and HTTP (`http://`) connections:
-- WebSocket: For real-time subscriptions
-- HTTP: For REST-style requests
-
-### 5. Multi-Model Complexity
-
-SurrealDB supports document, graph, and relational models. Queries can combine paradigms, which can be confusing for new users.
-
-### 6. --hide-welcome Flag
-
-For scripting, always use `--hide-welcome` to suppress the interactive welcome banner.
-
-## CI/CD Notes
-
-### GitHub Actions Cache Step
-
-```yaml
-- name: Cache SurrealDB binaries
-  uses: actions/cache@v4
-  with:
-    path: ~/.spindb/bin/surrealdb-*
-    key: surrealdb-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('engines/surrealdb/version-maps.ts') }}
-```
-
-## SurrealQL Quick Reference
-
-### Namespace & Database
-```sql
-USE NS my_namespace DB my_database;
-```
-
-### Records
-```sql
--- Create
-CREATE user:john SET name = 'John', age = 30;
-
--- Select
-SELECT * FROM user;
-
--- Update
-UPDATE user:john SET age = 31;
-
--- Delete
-DELETE user:john;
-```
-
-### Graph Traversal
-```sql
--- Create relation
-RELATE user:john->knows->user:jane;
-
--- Traverse
-SELECT ->knows->user FROM user:john;
-```
-
-### Schema
-```sql
-DEFINE TABLE user SCHEMAFULL;
-DEFINE FIELD name ON user TYPE string;
-DEFINE FIELD age ON user TYPE int;
-```

package/engines/surrealdb/backup.ts

@@ -1,131 +0,0 @@
-/**
- * SurrealDB backup module
- * Supports SurrealQL-based backups using surreal export
- *
- * SurrealDB backup formats:
- * - SurrealQL: Schema + data as SurrealQL statements (portable, human-readable)
- */
-
-import { spawn } from 'child_process'
-import { stat, mkdir } from 'fs/promises'
-import { existsSync } from 'fs'
-import { dirname } from 'path'
-import { logDebug } from '../../core/error-handler'
-import { requireSurrealPath } from './cli-utils'
-import type { ContainerConfig, BackupOptions, BackupResult } from '../../types'
-
-/**
- * Create a SurrealQL backup using surreal export
- */
-async function createSurqlBackup(
-  container: ContainerConfig,
-  outputPath: string,
-  database: string,
-): Promise<BackupResult> {
-  const { port, version } = container
-  // SurrealDB uses namespace/database hierarchy - use container name as namespace
-  const namespace = container.name.replace(/-/g, '_')
-
-  const surrealPath = await requireSurrealPath(version)
-
-  // Ensure output directory exists
-  const outputDir = dirname(outputPath)
-  if (!existsSync(outputDir)) {
-    await mkdir(outputDir, { recursive: true })
-  }
-
-  return new Promise<BackupResult>((resolve, reject) => {
-    // surreal export command
-    const args = [
-      'export',
-      '--endpoint',
-      `http://127.0.0.1:${port}`,
-      '--user',
-      'root',
-      '--pass',
-      'root',
-      '--ns',
-      namespace,
-      '--db',
-      database,
-      outputPath,
-    ]
-
-    logDebug(`Running: surreal ${args.join(' ')}`)
-
-    const proc = spawn(surrealPath, args, {
-      stdio: ['ignore', 'pipe', 'pipe'],
-    })
-
-    let _stdout = ''
-    let stderr = ''
-
-    proc.stdout.on('data', (data: Buffer) => {
-      _stdout += data.toString()
-    })
-    proc.stderr.on('data', (data: Buffer) => {
-      stderr += data.toString()
-    })
-
-    proc.on('error', reject)
-
-    proc.on('close', async (code) => {
-      if (code === 0) {
-        try {
-          const stats = await stat(outputPath)
-          resolve({
-            path: outputPath,
-            format: 'surql',
-            size: stats.size,
-          })
-        } catch (error) {
-          reject(new Error(`Backup file not created: ${error}`))
-        }
-      } else if (code === null) {
-        reject(
-          new Error(
-            `surreal export was terminated by signal${stderr ? `: ${stderr}` : ''}`,
-          ),
-        )
-      } else {
-        reject(
-          new Error(
-            `surreal export exited with code ${code}${stderr ? `: ${stderr}` : ''}`,
-          ),
-        )
-      }
-    })
-  })
-}
-
-/**
- * Create a backup
- *
- * @param container - Container configuration
- * @param outputPath - Path to write backup file
- * @param options - Backup options
- */
-export async function createBackup(
-  container: ContainerConfig,
-  outputPath: string,
-  options: BackupOptions,
-): Promise<BackupResult> {
-  const database = options.database || container.database || 'default'
-
-  return createSurqlBackup(container, outputPath, database)
-}
-
-/**
- * Create a backup for cloning purposes
- * Uses SurrealQL format for reliability
- */
-export async function createCloneBackup(
-  container: ContainerConfig,
-  outputPath: string,
-): Promise<BackupResult> {
-  return createSurqlBackup(
-    container,
-    outputPath,
-    container.database || 'default',
-  )
-}

package/engines/surrealdb/binary-manager.ts

@@ -1,45 +0,0 @@
-/**
- * SurrealDB Binary Manager
- *
- * Handles downloading, extracting, and managing SurrealDB binaries from hostdb.
- * Extends BaseBinaryManager for shared download/extraction logic.
- */
-
-import {
-  BaseBinaryManager,
-  type BinaryManagerConfig,
-} from '../../core/base-binary-manager'
-import { getBinaryUrl } from './binary-urls'
-import { normalizeVersion } from './version-maps'
-import { Engine, type Platform, type Arch } from '../../types'
-
-class SurrealDBBinaryManager extends BaseBinaryManager {
-  protected readonly config: BinaryManagerConfig = {
-    engine: Engine.SurrealDB,
-    engineName: 'surrealdb',
-    displayName: 'SurrealDB',
-    serverBinary: 'surreal',
-  }
-
-  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:
-    // "surreal 2.3.2 for linux on x86_64"
-    // or just "2.3.2"
-    const match = stdout.match(/(\d+\.\d+\.\d+)/)
-    return match?.[1] ?? null
-  }
-}
-
-export const surrealdbBinaryManager = new SurrealDBBinaryManager()