spindb 0.33.1 → 0.34.0

package/cli/commands/ports.ts

@@ -0,0 +1,211 @@
+import { Command } from 'commander'
+import chalk from 'chalk'
+import { existsSync } from 'fs'
+import { containerManager } from '../../core/container-manager'
+import { processManager } from '../../core/process-manager'
+import { getPgwebStatus } from '../../core/pgweb-utils'
+import { uiError, uiInfo } from '../ui/theme'
+import { getEngineIcon } from '../constants'
+import { Engine, type ContainerConfig } from '../../types'
+import { loadEnginesJson } from '../../config/engines-registry'
+
+function getSecondaryPorts(
+  config: ContainerConfig,
+): Array<{ port: number; label: string }> {
+  const ports: Array<{ port: number; label: string }> = []
+  switch (config.engine) {
+    case 'cockroachdb':
+      ports.push({ port: config.port + 1, label: 'HTTP UI' })
+      break
+    case 'clickhouse':
+      ports.push({ port: config.port + 1, label: 'HTTP' })
+      break
+    case 'qdrant':
+      ports.push({ port: config.port + 1, label: 'gRPC' })
+      break
+    case 'typedb':
+      ports.push({ port: config.port + 6271, label: 'HTTP' })
+      break
+    case 'questdb':
+      ports.push({ port: config.port + 188, label: 'HTTP Console' })
+      ports.push({ port: config.port + 197, label: 'ILP' })
+      break
+    case 'ferretdb':
+      if (config.backendPort) {
+        ports.push({ port: config.backendPort, label: 'PostgreSQL backend' })
+      }
+      break
+  }
+  return ports
+}
+
+export type PortEntry = { port: number; label: string }
+
+export async function getContainerPorts(config: ContainerConfig): Promise<{
+  status: 'running' | 'stopped' | 'available' | 'missing'
+  ports: PortEntry[]
+}> {
+  const isFileBasedDB =
+    config.engine === Engine.SQLite || config.engine === Engine.DuckDB
+
+  if (isFileBasedDB) {
+    const fileExists = existsSync(config.database)
+    return {
+      status: fileExists ? 'available' : 'missing',
+      ports: [],
+    }
+  }
+
+  const isRunning = await processManager.isRunning(config.name, {
+    engine: config.engine,
+  })
+
+  const enginesJson = await loadEnginesJson()
+  const engineConfig = enginesJson.engines[config.engine]
+  const displayName = engineConfig?.displayName || config.engine
+
+  const ports: PortEntry[] = [{ port: config.port, label: displayName }]
+
+  // Add secondary ports
+  ports.push(...getSecondaryPorts(config))
+
+  // Check for pgweb (PG-wire-protocol engines only)
+  if (
+    config.engine === 'postgresql' ||
+    config.engine === 'cockroachdb' ||
+    config.engine === 'ferretdb'
+  ) {
+    const pgweb = await getPgwebStatus(config.name, config.engine)
+    if (pgweb.running && pgweb.port) {
+      ports.push({ port: pgweb.port, label: 'pgweb' })
+    }
+  }
+
+  return {
+    status: isRunning ? 'running' : 'stopped',
+    ports,
+  }
+}
+
+export const portsCommand = new Command('ports')
+  .description('Show ports used by containers')
+  .argument('[name]', 'Container name (shows all if omitted)')
+  .option('--json', 'Output as JSON')
+  .option('--running', 'Only show running containers')
+  .action(
+    async (
+      name: string | undefined,
+      options: { json?: boolean; running?: boolean },
+    ) => {
+      try {
+        let containers: ContainerConfig[]
+
+        if (name) {
+          const config = await containerManager.getConfig(name)
+          if (!config) {
+            if (options.json) {
+              console.log(
+                JSON.stringify({ error: `Container "${name}" not found` }),
+              )
+            } else {
+              console.error(uiError(`Container "${name}" not found`))
+            }
+            process.exit(1)
+          }
+          containers = [config]
+        } else {
+          containers = await containerManager.list()
+        }
+
+        // Gather port info for all containers
+        const results = await Promise.all(
+          containers.map(async (config) => {
+            const { status, ports } = await getContainerPorts(config)
+            return { config, status, ports }
+          }),
+        )
+
+        // Filter to running only if requested
+        const filtered = options.running
+          ? results.filter((r) => r.status === 'running')
+          : results
+
+        if (options.json) {
+          const jsonOutput = filtered.map((r) => ({
+            name: r.config.name,
+            engine: r.config.engine,
+            status: r.status,
+            ports: r.ports,
+          }))
+          console.log(JSON.stringify(jsonOutput, null, 2))
+          return
+        }
+
+        if (filtered.length === 0) {
+          console.log(
+            uiInfo(
+              options.running
+                ? 'No running containers found.'
+                : 'No containers found. Create one with: spindb create',
+            ),
+          )
+          return
+        }
+
+        console.log()
+        console.log(
+          chalk.gray('  ') +
+            chalk.bold.white('NAME'.padEnd(22)) +
+            chalk.bold.white('ENGINE'.padEnd(18)) +
+            chalk.bold.white('STATUS'.padEnd(12)) +
+            chalk.bold.white('PORT(S)'),
+        )
+        console.log(chalk.gray('  ' + '─'.repeat(78)))
+
+        for (const { config, status, ports } of filtered) {
+          const engineIcon = getEngineIcon(config.engine)
+          const engineName = config.engine.padEnd(13)
+
+          const statusDisplay =
+            status === 'running'
+              ? chalk.green('● running'.padEnd(12))
+              : status === 'available'
+                ? chalk.blue('● available'.padEnd(12))
+                : status === 'missing'
+                  ? chalk.gray('○ missing'.padEnd(12))
+                  : chalk.gray('○ stopped'.padEnd(12))
+
+          let portDisplay: string
+          if (ports.length === 0) {
+            portDisplay = chalk.gray('—')
+          } else {
+            const parts = ports.map((p, i) =>
+              i === 0
+                ? String(p.port)
+                : `${p.port} ${chalk.gray(`(${p.label})`)}`,
+            )
+            portDisplay = parts.join(chalk.gray(', '))
+          }
+
+          console.log(
+            chalk.gray('  ') +
+              chalk.cyan(config.name.padEnd(22)) +
+              engineIcon +
+              chalk.white(engineName) +
+              statusDisplay +
+              portDisplay,
+          )
+        }
+
+        console.log()
+      } catch (error) {
+        const e = error as Error
+        if (options.json) {
+          console.log(JSON.stringify({ error: e.message }))
+        } else {
+          console.error(uiError(e.message))
+        }
+        process.exit(1)
+      }
+    },
+  )

package/cli/constants.ts

@@ -3,12 +3,12 @@ import { Engine, type IconMode } from '../types'
 
 /**
  * Get the page size for list prompts based on terminal height.
- * Returns 20 for tall terminals (>= 30 rows), 15 for shorter ones.
- * This provides a consistent experience while avoiding rendering issues on small terminals.
+ * Scales dynamically with the terminal — reserves ~8 lines for header, prompt, and margin,
+ * then uses the remaining height for list items (clamped to 10–30).
  */
 export function getPageSize(): number {
   const terminalHeight = process.stdout.rows || 24
-  return terminalHeight >= 30 ? 20 : 15
+  return Math.max(10, Math.min(30, terminalHeight - 8))
 }
 
 // Engine icons with three display modes:

package/cli/index.ts

@@ -3,6 +3,7 @@ import { createRequire } from 'module'
 import chalk from 'chalk'
 import { createCommand } from './commands/create'
 import { listCommand } from './commands/list'
+import { portsCommand } from './commands/ports'
 import { startCommand } from './commands/start'
 import { stopCommand } from './commands/stop'
 import { deleteCommand } from './commands/delete'
@@ -117,6 +118,7 @@ export async function run(): Promise<void> {
 
   program.addCommand(createCommand)
   program.addCommand(listCommand)
+  program.addCommand(portsCommand)
   program.addCommand(startCommand)
   program.addCommand(stopCommand)
   program.addCommand(deleteCommand)

package/cli/ui/prompts.ts

@@ -301,6 +301,7 @@ export async function filterableListPrompt(
     emptyText?: string
     enableToggle?: boolean
     defaultValue?: string // Pre-select this value (cursor starts here)
+    headerItems?: (FilterableChoice | inquirer.Separator)[] // Shown above filterable items
   },
 ): Promise<string> {
   // Split choices into filterable items and static footer (separators, back buttons, etc.)
@@ -318,6 +319,7 @@ export async function filterableListPrompt(
   }
 
   // Source function for autocomplete - filters items based on input
+  const header = options.headerItems || []
   async function source(
     _answers: Record<string, unknown>,
     input: string | undefined,
@@ -328,7 +330,7 @@ export async function filterableListPrompt(
 
     if (!searchTerm) {
       // No filter - show all items
-      result = [...filterableItems, ...footerItems]
+      result = [...header, ...filterableItems, ...footerItems]
     } else {
       // Filter items by matching search term against the display name
       // Strip ANSI codes for matching but keep them for display
@@ -349,7 +351,7 @@ export async function filterableListPrompt(
           ...footerItems,
         ]
       } else {
-        result = [...filtered, ...footerItems]
+        result = [...header, ...filtered, ...footerItems]
       }
     }
 

package/core/config-manager.ts

@@ -82,6 +82,10 @@ const TYPEDB_TOOLS: BinaryTool[] = ['typedb', 'typedb_console_bin']
 
 const INFLUXDB_TOOLS: BinaryTool[] = ['influxdb3']
 
+const PGWEB_TOOLS: BinaryTool[] = ['pgweb']
+
+const DBLAB_TOOLS: BinaryTool[] = ['dblab']
+
 const ENHANCED_SHELLS: BinaryTool[] = [
   'pgcli',
   'mycli',
@@ -106,6 +110,8 @@ const ALL_TOOLS: BinaryTool[] = [
   ...QUESTDB_TOOLS,
   ...TYPEDB_TOOLS,
   ...INFLUXDB_TOOLS,
+  ...PGWEB_TOOLS,
+  ...DBLAB_TOOLS,
   ...SQLITE_TOOLS,
   ...DUCKDB_TOOLS,
   ...ENHANCED_SHELLS,
@@ -621,6 +627,8 @@ export {
   QUESTDB_TOOLS,
   TYPEDB_TOOLS,
   INFLUXDB_TOOLS,
+  PGWEB_TOOLS,
+  DBLAB_TOOLS,
   SQLITE_TOOLS,
   DUCKDB_TOOLS,
   ENHANCED_SHELLS,

package/core/dblab-utils.ts

@@ -0,0 +1,113 @@
+import { Engine, type ContainerConfig } from '../types'
+
+/** Pinned dblab version — single source of truth for download URL */
+export const DBLAB_VERSION = '0.34.2'
+
+/** Engines that support dblab (PostgreSQL, MySQL, or SQLite wire protocol) */
+export const DBLAB_ENGINES = new Set([
+  Engine.PostgreSQL,
+  Engine.MySQL,
+  Engine.MariaDB,
+  Engine.CockroachDB,
+  Engine.SQLite,
+  Engine.QuestDB,
+])
+
+/**
+ * Get the platform suffix for the dblab download URL.
+ * Returns e.g. 'darwin_arm64', 'linux_amd64', 'windows_amd64'
+ */
+export function getDblabPlatformSuffix(): string {
+  const platform = process.platform
+  const arch = process.arch
+
+  if (platform === 'darwin' && arch === 'arm64') return 'darwin_arm64'
+  if (platform === 'darwin' && arch === 'x64') return 'darwin_amd64'
+  if (platform === 'linux' && arch === 'arm64') return 'linux_arm64'
+  if (platform === 'linux' && arch === 'x64') return 'linux_amd64'
+  if (platform === 'win32' && arch === 'x64') return 'windows_amd64'
+
+  throw new Error(`Unsupported platform: ${platform} ${arch}`)
+}
+
+/**
+ * Build the CLI args array for launching dblab against a container.
+ * Uses flag-based approach to avoid MySQL tcp() URL wrapper issues.
+ */
+export function getDblabArgs(
+  config: ContainerConfig,
+  database: string,
+): string[] {
+  switch (config.engine) {
+    case Engine.PostgreSQL:
+      return [
+        '--host',
+        '127.0.0.1',
+        '--port',
+        String(config.port),
+        '--user',
+        'postgres',
+        '--db',
+        database,
+        '--driver',
+        'postgres',
+        '--ssl',
+        'disable',
+      ]
+
+    case Engine.MySQL:
+    case Engine.MariaDB:
+      return [
+        '--host',
+        '127.0.0.1',
+        '--port',
+        String(config.port),
+        '--user',
+        'root',
+        '--db',
+        database,
+        '--driver',
+        'mysql',
+      ]
+
+    case Engine.CockroachDB:
+      return [
+        '--host',
+        '127.0.0.1',
+        '--port',
+        String(config.port),
+        '--user',
+        'root',
+        '--db',
+        database,
+        '--driver',
+        'postgres',
+        '--ssl',
+        'disable',
+      ]
+
+    case Engine.QuestDB:
+      return [
+        '--host',
+        '127.0.0.1',
+        '--port',
+        String(config.port),
+        '--user',
+        'admin',
+        '--pass',
+        'quest',
+        '--db',
+        database || 'qdb',
+        '--driver',
+        'postgres',
+        '--ssl',
+        'disable',
+      ]
+
+    case Engine.SQLite:
+      return ['--db', config.database, '--driver', 'sqlite3']
+
+    default:
+      throw new Error(`dblab is not supported for engine: ${config.engine}`)
+  }
+}

package/core/dependency-manager.ts

@@ -86,6 +86,10 @@ const KNOWN_BINARY_TOOLS: readonly BinaryTool[] = [
   'typedb_console_bin',
   // InfluxDB
   'influxdb3',
+  // Web panels
+  'pgweb',
+  // TUI tools
+  'dblab',
   // Enhanced shells (optional)
   'pgcli',
   'mycli',

package/core/pgweb-utils.ts

@@ -0,0 +1,62 @@
+import { existsSync } from 'fs'
+import { readFile, unlink } from 'fs/promises'
+import { join } from 'path'
+import { platformService } from './platform-service'
+import { paths } from '../config/paths'
+
+/** Pinned pgweb version — single source of truth for download URL */
+export const PGWEB_VERSION = '0.17.0'
+
+/**
+ * Check if pgweb is running for a container.
+ * Reads pgweb.pid/pgweb.port files and verifies the process is alive.
+ * Cleans up stale PID/port files if the process is dead.
+ */
+export async function getPgwebStatus(
+  containerName: string,
+  engine: string,
+): Promise<{ running: boolean; port?: number; pid?: number }> {
+  const containerDir = paths.getContainerPath(containerName, { engine })
+  const pidFile = join(containerDir, 'pgweb.pid')
+  const portFile = join(containerDir, 'pgweb.port')
+
+  if (!existsSync(pidFile)) return { running: false }
+
+  try {
+    const pid = parseInt(await readFile(pidFile, 'utf8'), 10)
+    if (platformService.isProcessRunning(pid)) {
+      const port = parseInt(await readFile(portFile, 'utf8'), 10)
+      return { running: true, port, pid }
+    }
+  } catch {
+    // PID file invalid or process dead
+  }
+
+  // Clean up stale files
+  await unlink(pidFile).catch(() => {})
+  await unlink(portFile).catch(() => {})
+  return { running: false }
+}
+
+/**
+ * Stop a running pgweb process for a container (no UI output).
+ * Returns true if a process was stopped, false if nothing was running.
+ */
+export async function stopPgweb(
+  containerName: string,
+  engine: string,
+): Promise<boolean> {
+  const status = await getPgwebStatus(containerName, engine)
+  if (!status.running || !status.pid) return false
+
+  try {
+    await platformService.terminateProcess(status.pid, false)
+  } catch {
+    // Already gone
+  }
+
+  const containerDir = paths.getContainerPath(containerName, { engine })
+  await unlink(join(containerDir, 'pgweb.pid')).catch(() => {})
+  await unlink(join(containerDir, 'pgweb.port')).catch(() => {})
+  return true
+}

package/engines/base-engine.ts

@@ -13,6 +13,7 @@ import type {
   UserCredentials,
 } from '../types'
 import { UnsupportedOperationError } from '../core/error-handler'
+import { stopPgweb } from '../core/pgweb-utils'
 
 /**
  * Base class for database engines
@@ -267,6 +268,14 @@ export abstract class BaseEngine {
     // Default: no-op. Override in engines that support connection termination.
   }
 
+  /**
+   * Stop pgweb if running for this container.
+   * Called from stop() in engines that support pgweb (PostgreSQL, CockroachDB, FerretDB).
+   */
+  protected async stopPgweb(containerName: string): Promise<void> {
+    await stopPgweb(containerName, this.name)
+  }
+
   /**
    * Execute a query and return results in a structured format.
    * @param container - The container configuration

package/engines/cockroachdb/index.ts

@@ -506,6 +506,9 @@ export class CockroachDBEngine extends BaseEngine {
       }
     }
 
+    // Kill pgweb if running for this container
+    await this.stopPgweb(name)
+
     logDebug('CockroachDB stopped')
   }
 

package/engines/ferretdb/index.ts

@@ -622,41 +622,57 @@ export class FerretDBEngine extends BaseEngine {
     let ferretStarted = false
 
     try {
-      // 1. Start PostgreSQL
+      // 1. Start PostgreSQL (skip if already running)
       onProgress?.({
         stage: 'starting',
         message: 'Starting PostgreSQL backend...',
       })
 
-      // Use pg_ctl to start PostgreSQL
-      // Add 60s timeout to prevent hanging if PostgreSQL fails to start (especially on Windows)
+      // Check if PostgreSQL backend is already running in this data dir
+      let pgAlreadyRunning = false
       try {
-        await spawnAsync(
-          pgCtl,
-          [
-            'start',
-            '-D',
-            pgDataDir,
-            '-l',
-            pgLogFile,
-            '-o',
-            `-p ${backendPort} -h 127.0.0.1`,
-            '-w', // Wait for startup
-          ],
-          { env: pgSpawnEnv, timeout: 60000 },
-        )
-      } catch (pgError) {
-        // Read PostgreSQL log for debugging
-        let pgLog = ''
+        await spawnAsync(pgCtl, ['status', '-D', pgDataDir], {
+          env: pgSpawnEnv,
+          timeout: 5000,
+        })
+        // pg_ctl status exits 0 if server is running
+        pgAlreadyRunning = true
+        logDebug('PostgreSQL backend already running, skipping start')
+      } catch {
+        // Exit code != 0 means not running — proceed to start
+      }
+
+      if (!pgAlreadyRunning) {
+        // Use pg_ctl to start PostgreSQL
+        // Add 60s timeout to prevent hanging if PostgreSQL fails to start (especially on Windows)
         try {
-          pgLog = await readFile(pgLogFile, 'utf8')
-        } catch {
-          pgLog = '(no log available)'
+          await spawnAsync(
+            pgCtl,
+            [
+              'start',
+              '-D',
+              pgDataDir,
+              '-l',
+              pgLogFile,
+              '-o',
+              `-p ${backendPort} -h 127.0.0.1`,
+              '-w', // Wait for startup
+            ],
+            { env: pgSpawnEnv, timeout: 60000 },
+          )
+        } catch (pgError) {
+          // Read PostgreSQL log for debugging
+          let pgLog = ''
+          try {
+            pgLog = await readFile(pgLogFile, 'utf8')
+          } catch {
+            pgLog = '(no log available)'
+          }
+          throw new Error(
+            `PostgreSQL backend failed to start: ${pgError instanceof Error ? pgError.message : pgError}\n` +
+              `PostgreSQL log:\n${pgLog.slice(-2000)}`, // Last 2KB of log
+          )
         }
-        throw new Error(
-          `PostgreSQL backend failed to start: ${pgError instanceof Error ? pgError.message : pgError}\n` +
-            `PostgreSQL log:\n${pgLog.slice(-2000)}`, // Last 2KB of log
-        )
       }
 
       pgStarted = true
@@ -880,6 +896,9 @@ export class FerretDBEngine extends BaseEngine {
       await this.stopPostgreSQLProcess(pgCtl, pgDataDir, pgSpawnEnv)
     }
 
+    // Kill pgweb if running for this container
+    await this.stopPgweb(name)
+
     logDebug('FerretDB stopped')
   }
 

package/engines/postgresql/index.ts

@@ -461,6 +461,9 @@ export class PostgreSQLEngine extends BaseEngine {
     const dataDir = paths.getContainerDataPath(name, { engine: this.name })
 
     await processManager.stop(pgCtlPath, dataDir)
+
+    // Kill pgweb if running for this container
+    await this.stopPgweb(name)
   }
 
   async status(container: ContainerConfig): Promise<StatusResult> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spindb",
-  "version": "0.33.1",
+  "version": "0.34.0",
   "author": "Bob Bass <bob@bbass.co>",
   "license": "PolyForm-Noncommercial-1.0.0",
   "description": "Zero-config Docker-free local database containers. Create, backup, and clone a variety of popular databases.",

package/types/index.ts

@@ -427,6 +427,10 @@ export type BinaryTool =
   | 'typedb_console_bin'
   // InfluxDB tools
   | 'influxdb3'
+  // Web panels
+  | 'pgweb'
+  // TUI tools
+  | 'dblab'
   // Enhanced shells (optional)
   | 'pgcli'
   | 'mycli'
@@ -519,6 +523,10 @@ export type SpinDBConfig = {
     typedb_console_bin?: BinaryConfig
     // InfluxDB tools
     influxdb3?: BinaryConfig
+    // Web panels
+    pgweb?: BinaryConfig
+    // TUI tools
+    dblab?: BinaryConfig
     // Enhanced shells (optional)
     pgcli?: BinaryConfig
     mycli?: BinaryConfig