spindb 0.31.4 → 0.33.1

package/engines/typedb/binary-manager.ts

@@ -0,0 +1,200 @@
+/**
+ * TypeDB Binary Manager
+ *
+ * Handles downloading, extracting, and managing TypeDB binaries from hostdb.
+ * Extends BaseBinaryManager for shared download/extraction logic.
+ *
+ * TypeDB archives extract to a `typedb/` directory with nested structure:
+ *   typedb/
+ *   ├── typedb                  (launcher script)
+ *   ├── server/
+ *   │   ├── typedb_server_bin   (server binary)
+ *   │   └── config.yml          (default config)
+ *   ├── console/
+ *   │   └── typedb_console_bin  (console binary)
+ *   └── LICENSE
+ *
+ * We reorganize this preserving the relative structure the launcher expects:
+ *   bin/
+ *   ├── typedb                  (launcher)
+ *   ├── server/
+ *   │   └── typedb_server_bin   (server binary)
+ *   ├── console/
+ *   │   └── typedb_console_bin  (console binary)
+ *   └── config.yml              (moved for reference)
+ *   server/
+ *   └── config.yml              (default config for reference)
+ */
+
+import { existsSync } from 'fs'
+import { mkdir, readdir } from 'fs/promises'
+import { join } from 'path'
+import {
+  BaseBinaryManager,
+  type BinaryManagerConfig,
+} from '../../core/base-binary-manager'
+import { moveEntry } from '../../core/fs-error-utils'
+import { logDebug } from '../../core/error-handler'
+import { paths } from '../../config/paths'
+import { getBinaryUrl } from './binary-urls'
+import { normalizeVersion } from './version-maps'
+import { Engine, Platform, type Arch } from '../../types'
+
+class TypeDBBinaryManager extends BaseBinaryManager {
+  protected readonly config: BinaryManagerConfig = {
+    engine: Engine.TypeDB,
+    engineName: 'typedb',
+    displayName: 'TypeDB',
+    serverBinary: 'typedb',
+  }
+
+  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 {
+    // Try standard three-part semver (e.g., "3.8.0")
+    const threePartMatch = stdout.match(/(\d+\.\d+\.\d+)/)
+    if (threePartMatch) {
+      return threePartMatch[1]
+    }
+
+    // Fallback: two-part version (e.g., "3.8")
+    const twoPartMatch = stdout.match(/(\d+\.\d+)/)
+    if (twoPartMatch) {
+      logDebug(
+        `TypeDB version parsed as two-part: ${twoPartMatch[1]} (from: ${stdout.trim().slice(0, 100)})`,
+      )
+      return twoPartMatch[1]
+    }
+
+    logDebug(
+      `Could not parse TypeDB version from output: ${stdout.trim().slice(0, 100)}`,
+    )
+    return null
+  }
+
+  /**
+   * Override moveExtractedEntries to handle TypeDB's nested directory structure.
+   *
+   * TypeDB archives extract to: typedb/server/typedb_server_bin, typedb/console/typedb_console_bin
+   * We reorganize to: bin/typedb, bin/server/typedb_server_bin, bin/console/typedb_console_bin
+   * And preserve server/config.yml for reference.
+   */
+  protected async moveExtractedEntries(
+    extractDir: string,
+    binPath: string,
+  ): Promise<void> {
+    const entries = await readdir(extractDir, { withFileTypes: true })
+    const ext = process.platform === 'win32' ? '.exe' : ''
+    const batExt = process.platform === 'win32' ? '.bat' : ''
+
+    // Find the typedb directory (e.g., "typedb" or "typedb-3.8.0")
+    const typedbDir = entries.find(
+      (e) =>
+        e.isDirectory() &&
+        (e.name === 'typedb' || e.name.startsWith('typedb-')),
+    )
+
+    const sourceDir = typedbDir ? join(extractDir, typedbDir.name) : extractDir
+
+    // Create bin/ directory
+    const destBinDir = join(binPath, 'bin')
+    await mkdir(destBinDir, { recursive: true })
+
+    // Move launcher script to bin/
+    const launcherName = `typedb${batExt}`
+    const launcherPath = join(sourceDir, launcherName)
+    if (existsSync(launcherPath)) {
+      await moveEntry(launcherPath, join(destBinDir, launcherName))
+    }
+
+    // Move server/ directory into bin/ (preserves bin/server/typedb_server_bin path the launcher expects)
+    const destServerDir = join(destBinDir, 'server')
+    await mkdir(destServerDir, { recursive: true })
+    const serverBinName = `typedb_server_bin${ext}`
+    const serverBinPath = join(sourceDir, 'server', serverBinName)
+    if (existsSync(serverBinPath)) {
+      await moveEntry(serverBinPath, join(destServerDir, serverBinName))
+    }
+
+    // Move console/ directory into bin/ (preserves bin/console/typedb_console_bin path the launcher expects)
+    const destConsoleDir = join(destBinDir, 'console')
+    await mkdir(destConsoleDir, { recursive: true })
+    const consoleBinName = `typedb_console_bin${ext}`
+    const consoleBinPath = join(sourceDir, 'console', consoleBinName)
+    if (existsSync(consoleBinPath)) {
+      await moveEntry(consoleBinPath, join(destConsoleDir, consoleBinName))
+    }
+
+    // Preserve server/config.yml as reference config
+    const configPath = join(sourceDir, 'server', 'config.yml')
+    if (existsSync(configPath)) {
+      const destRefServerDir = join(binPath, 'server')
+      await mkdir(destRefServerDir, { recursive: true })
+      await moveEntry(configPath, join(destRefServerDir, 'config.yml'))
+    }
+
+    // Move LICENSE if present
+    const licensePath = join(sourceDir, 'LICENSE')
+    if (existsSync(licensePath)) {
+      await moveEntry(licensePath, join(binPath, 'LICENSE'))
+    }
+
+    logDebug('TypeDB binaries reorganized to standard bin/ layout')
+  }
+
+  /**
+   * Override verify to handle TypeDB's launcher script.
+   * TypeDB's main binary is a launcher script, not a direct executable.
+   * We verify the actual server binary exists instead of running --version.
+   */
+  async verify(
+    version: string,
+    platform: Platform,
+    arch: Arch,
+  ): Promise<boolean> {
+    const fullVersion = this.getFullVersion(version)
+    const binPath = paths.getBinaryPath({
+      engine: this.config.engineName,
+      version: fullVersion,
+      platform,
+      arch,
+    })
+
+    const ext = platform === Platform.Win32 ? '.exe' : ''
+    const batExt = platform === Platform.Win32 ? '.bat' : ''
+    const launcherPath = join(binPath, 'bin', `typedb${batExt}`)
+    const serverPath = join(binPath, 'bin', 'server', `typedb_server_bin${ext}`)
+    const consolePath = join(
+      binPath,
+      'bin',
+      'console',
+      `typedb_console_bin${ext}`,
+    )
+
+    if (!existsSync(launcherPath)) {
+      throw new Error(`TypeDB launcher not found at ${launcherPath}`)
+    }
+
+    if (!existsSync(serverPath)) {
+      throw new Error(`TypeDB server binary not found at ${serverPath}`)
+    }
+
+    if (!existsSync(consolePath)) {
+      throw new Error(`TypeDB console binary not found at ${consolePath}`)
+    }
+
+    return true
+  }
+}
+
+export const typedbBinaryManager = new TypeDBBinaryManager()

package/engines/typedb/binary-urls.ts

@@ -0,0 +1,38 @@
+/**
+ * TypeDB binary URL generation
+ *
+ * Generates download URLs for TypeDB binaries from hostdb.
+ */
+
+import type { Platform, Arch } from '../../types'
+import { normalizeVersion } from './version-maps'
+
+const HOSTDB_BASE_URL =
+  'https://github.com/robertjbass/hostdb/releases/download'
+
+/**
+ * Get the binary download URL for a specific version and platform
+ *
+ * URL format: https://github.com/robertjbass/hostdb/releases/download/typedb-{version}/typedb-{version}-{platform}-{arch}.{ext}
+ *
+ * @param version - TypeDB version (e.g., '3.8.0' or '3')
+ * @param platform - Target platform (darwin, linux, win32)
+ * @param arch - Target architecture (x64, arm64)
+ */
+export function getBinaryUrl(
+  version: string,
+  platform: Platform,
+  arch: Arch,
+): string {
+  const fullVersion = normalizeVersion(version)
+  const ext = getArchiveExtension(platform)
+
+  return `${HOSTDB_BASE_URL}/typedb-${fullVersion}/typedb-${fullVersion}-${platform}-${arch}.${ext}`
+}
+
+/**
+ * Get the archive extension for a platform
+ */
+export function getArchiveExtension(platform: Platform): string {
+  return platform === 'win32' ? 'zip' : 'tar.gz'
+}

package/engines/typedb/cli-utils.ts

@@ -0,0 +1,210 @@
+/**
+ * TypeDB CLI utilities
+ *
+ * Helper functions for working with TypeDB command-line tools.
+ */
+
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { paths } from '../../config/paths'
+import { configManager } from '../../core/config-manager'
+import { platformService } from '../../core/platform-service'
+import { normalizeVersion } from './version-maps'
+
+export const TYPEDB_NOT_FOUND_ERROR =
+  'TypeDB binary not found. Run: spindb engines download typedb <version>'
+
+/** Default TypeDB credentials (TypeDB 3.x requires authentication) */
+export const TYPEDB_DEFAULT_USERNAME = 'admin'
+export const TYPEDB_DEFAULT_PASSWORD = 'password'
+
+/**
+ * Get standard TypeDB console connection arguments including authentication.
+ * TypeDB 3.x requires --username and --password for all console operations.
+ *
+ * @param tlsDisabled - When true (the default for local dev), appends --tls-disabled.
+ *   Pass false when connecting to a TLS-enabled TypeDB server.
+ */
+export function getConsoleBaseArgs(
+  port: number,
+  host = '127.0.0.1',
+  tlsDisabled = true,
+): string[] {
+  const args = [
+    '--address',
+    `${host}:${port}`,
+    ...(tlsDisabled ? ['--tls-disabled'] : []),
+    '--username',
+    TYPEDB_DEFAULT_USERNAME,
+    '--password',
+    TYPEDB_DEFAULT_PASSWORD,
+  ]
+  return args
+}
+
+/**
+ * Get the path to the typedb launcher binary
+ *
+ * First checks the config cache, then scans the downloaded binaries directory.
+ * Returns null if not found.
+ */
+export async function getTypeDBPath(): Promise<string | null> {
+  // Check config cache first
+  const cached = await configManager.getBinaryPath('typedb')
+  if (cached && existsSync(cached)) {
+    return cached
+  }
+
+  // Fall back to filesystem scan using the same logic as getTypeDBPathForVersion
+  const { TYPEDB_VERSION_MAP } = await import('./version-maps')
+  for (const version of Object.values(TYPEDB_VERSION_MAP)) {
+    const found = await getTypeDBPathForVersion(version)
+    if (found) {
+      await configManager.setBinaryPath('typedb', found, 'bundled')
+      return found
+    }
+  }
+
+  return null
+}
+
+/**
+ * Get the typedb binary path for a specific version
+ */
+export async function getTypeDBPathForVersion(
+  version: string,
+): Promise<string | null> {
+  const { platform, arch } = platformService.getPlatformInfo()
+  const fullVersion = normalizeVersion(version)
+  // TypeDB launcher is a .bat script on Windows, no extension on other platforms
+  const batExt = platform === 'win32' ? '.bat' : ''
+
+  const binPath = paths.getBinaryPath({
+    engine: 'typedb',
+    version: fullVersion,
+    platform,
+    arch,
+  })
+
+  const typedbPath = join(binPath, 'bin', `typedb${batExt}`)
+  if (existsSync(typedbPath)) {
+    return typedbPath
+  }
+
+  return null
+}
+
+/**
+ * Get the typedb_console_bin path for a specific version
+ */
+export async function getTypeDBConsolePath(
+  version: string,
+): Promise<string | null> {
+  const { platform, arch } = platformService.getPlatformInfo()
+  const fullVersion = normalizeVersion(version)
+  const ext = platformService.getExecutableExtension()
+
+  const binPath = paths.getBinaryPath({
+    engine: 'typedb',
+    version: fullVersion,
+    platform,
+    arch,
+  })
+
+  const consolePath = join(
+    binPath,
+    'bin',
+    'console',
+    `typedb_console_bin${ext}`,
+  )
+  if (existsSync(consolePath)) {
+    return consolePath
+  }
+
+  return null
+}
+
+/**
+ * Require the typedb binary path, throwing if not found
+ */
+export async function requireTypeDBPath(version?: string): Promise<string> {
+  // If version provided, look for that specific version
+  if (version) {
+    const path = await getTypeDBPathForVersion(version)
+    if (path) {
+      return path
+    }
+  }
+
+  // Try config cache
+  const cached = await getTypeDBPath()
+  if (cached) {
+    return cached
+  }
+
+  throw new Error(TYPEDB_NOT_FOUND_ERROR)
+}
+
+/**
+ * Require the typedb_console_bin path, throwing if not found
+ */
+export async function requireTypeDBConsolePath(
+  version?: string,
+): Promise<string> {
+  if (version) {
+    const path = await getTypeDBConsolePath(version)
+    if (path) {
+      return path
+    }
+  }
+
+  // Try config cache
+  const cached = await configManager.getBinaryPath('typedb_console_bin')
+  if (cached && existsSync(cached)) {
+    return cached
+  }
+
+  // Fall back to scanning all installed versions (same pattern as requireTypeDBPath)
+  const { TYPEDB_VERSION_MAP } = await import('./version-maps')
+  for (const ver of Object.values(TYPEDB_VERSION_MAP)) {
+    const found = await getTypeDBConsolePath(ver)
+    if (found) {
+      return found
+    }
+  }
+
+  throw new Error(
+    'TypeDB console binary not found. Run: spindb engines download typedb <version>',
+  )
+}
+
+/**
+ * Validate a TypeDB identifier (database name)
+ * TypeDB identifiers follow specific rules:
+ * - Start with letter or underscore
+ * - Contain letters, digits, underscores, dashes
+ * - Max 63 characters
+ *
+ * @throws Error if identifier is invalid
+ */
+export function validateTypeDBIdentifier(
+  identifier: string,
+  type: 'database' = 'database',
+): void {
+  if (!identifier) {
+    throw new Error(`${type} name cannot be empty`)
+  }
+
+  if (identifier.length > 63) {
+    throw new Error(`${type} name cannot exceed 63 characters`)
+  }
+
+  // TypeDB allows alphanumeric, underscores, and dashes
+  const validPattern = /^[a-zA-Z_][a-zA-Z0-9_-]*$/
+  if (!validPattern.test(identifier)) {
+    throw new Error(
+      `Invalid ${type} name "${identifier}". ` +
+        `Must start with a letter or underscore and contain only letters, digits, underscores, and dashes.`,
+    )
+  }
+}

package/engines/typedb/hostdb-releases.ts

@@ -0,0 +1,118 @@
+/**
+ * TypeDB hostdb releases integration
+ *
+ * Fetches available versions from hostdb releases.json and provides
+ * fallback to local version maps.
+ */
+
+import { logDebug } from '../../core/error-handler'
+import { TYPEDB_VERSION_MAP, SUPPORTED_MAJOR_VERSIONS } from './version-maps'
+
+const HOSTDB_RELEASES_URL =
+  'https://raw.githubusercontent.com/robertjbass/hostdb/main/releases.json'
+
+// Cache for fetched versions (expires after 5 minutes)
+let cachedVersions: Record<string, string[]> | null = null
+let cacheExpiry = 0
+const CACHE_TTL_MS = 5 * 60 * 1000
+
+type HostdbReleases = {
+  [engine: string]: {
+    versions: {
+      version: string
+      platforms: string[]
+    }[]
+  }
+}
+
+/**
+ * Fetch available TypeDB versions from hostdb
+ * Returns a map of major version to available patch versions
+ *
+ * Falls back to local version maps if fetch fails
+ */
+export async function fetchAvailableVersions(): Promise<
+  Record<string, string[]>
+> {
+  // Return cached versions if still valid
+  if (cachedVersions && Date.now() < cacheExpiry) {
+    return cachedVersions
+  }
+
+  try {
+    const controller = new AbortController()
+    const timeoutId = setTimeout(() => controller.abort(), 10000)
+    let response: Response
+    try {
+      response = await fetch(HOSTDB_RELEASES_URL, { signal: controller.signal })
+    } finally {
+      clearTimeout(timeoutId)
+    }
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`)
+    }
+
+    const releases = (await response.json()) as HostdbReleases
+    const typedbReleases = releases.typedb
+
+    if (!typedbReleases?.versions) {
+      throw new Error('No TypeDB versions found in releases.json')
+    }
+
+    // Group versions by major version
+    const versionMap: Record<string, string[]> = {}
+
+    for (const { version } of typedbReleases.versions) {
+      // Extract major version (e.g., "3" from "3.8.0")
+      const majorMatch = version.match(/^(\d+)/)
+      if (!majorMatch) continue
+
+      const majorVersion = majorMatch[1]
+      if (!versionMap[majorVersion]) {
+        versionMap[majorVersion] = []
+      }
+      versionMap[majorVersion].push(version)
+    }
+
+    // Sort versions within each major version (newest first)
+    for (const major of Object.keys(versionMap)) {
+      versionMap[major].sort((a, b) => {
+        const partsA = a.split('.').map(Number)
+        const partsB = b.split('.').map(Number)
+        for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
+          const diff = (partsB[i] || 0) - (partsA[i] || 0)
+          if (diff !== 0) return diff
+        }
+        return 0
+      })
+    }
+
+    // Cache the results
+    cachedVersions = versionMap
+    cacheExpiry = Date.now() + CACHE_TTL_MS
+
+    logDebug('Fetched TypeDB versions from hostdb', { versionMap })
+    return versionMap
+  } catch (error) {
+    logDebug(`Failed to fetch hostdb releases: ${error}`)
+
+    // Fall back to local version maps
+    const fallbackMap: Record<string, string[]> = {}
+    for (const major of SUPPORTED_MAJOR_VERSIONS) {
+      const fullVersion = TYPEDB_VERSION_MAP[major]
+      if (fullVersion) {
+        fallbackMap[major] = [fullVersion]
+      }
+    }
+
+    return fallbackMap
+  }
+}
+
+/**
+ * Clear the version cache (useful for testing)
+ */
+export function clearVersionCache(): void {
+  cachedVersions = null
+  cacheExpiry = 0
+}