spindb 0.8.2 → 0.9.0

package/cli/commands/menu/index.ts

@@ -13,7 +13,7 @@ import {
 } from './container-handlers'
 import { handleBackup, handleRestore, handleClone } from './backup-handlers'
 import { handleEngines } from './engine-handlers'
-import { handleCheckUpdate } from './update-handlers'
+import { handleCheckUpdate, handleDoctor } from './update-handlers'
 import { type MenuChoice } from './shared'
 
 async function showMainMenu(): Promise<void> {
@@ -97,6 +97,7 @@ async function showMainMenu(): Promise<void> {
       disabled: hasEngines ? false : 'No engines installed',
     },
     new inquirer.Separator(),
+    { name: `${chalk.bgRed.white('+')} System health check`, value: 'doctor' },
     { name: `${chalk.cyan('↑')} Check for updates`, value: 'check-update' },
     { name: `${chalk.gray('⏻')} Exit`, value: 'exit' },
   ]
@@ -136,6 +137,9 @@ async function showMainMenu(): Promise<void> {
     case 'engines':
       await handleEngines()
       break
+    case 'doctor':
+      await handleDoctor()
+      break
     case 'check-update':
       await handleCheckUpdate()
       break

package/cli/commands/menu/shell-handlers.ts

@@ -6,13 +6,16 @@ import {
   isUsqlInstalled,
   isPgcliInstalled,
   isMycliInstalled,
+  isLitecliInstalled,
   detectPackageManager,
   installUsql,
   installPgcli,
   installMycli,
+  installLitecli,
   getUsqlManualInstructions,
   getPgcliManualInstructions,
   getMycliManualInstructions,
+  getLitecliManualInstructions,
 } from '../../../core/dependency-manager'
 import { platformService } from '../../../core/platform-service'
 import { getEngine } from '../../../engines'
@@ -66,10 +69,11 @@ export async function handleOpenShell(containerName: string): Promise<void> {
   const shellCheckSpinner = createSpinner('Checking available shells...')
   shellCheckSpinner.start()
 
-  const [usqlInstalled, pgcliInstalled, mycliInstalled] = await Promise.all([
+  const [usqlInstalled, pgcliInstalled, mycliInstalled, litecliInstalled] = await Promise.all([
     isUsqlInstalled(),
     isPgcliInstalled(),
     isMycliInstalled(),
+    isLitecliInstalled(),
   ])
 
   shellCheckSpinner.stop()
@@ -84,12 +88,36 @@ export async function handleOpenShell(containerName: string): Promise<void> {
     | 'install-pgcli'
     | 'mycli'
     | 'install-mycli'
+    | 'litecli'
+    | 'install-litecli'
     | 'back'
 
-  const defaultShellName = config.engine === 'mysql' ? 'mysql' : 'psql'
-  const engineSpecificCli = config.engine === 'mysql' ? 'mycli' : 'pgcli'
-  const engineSpecificInstalled =
-    config.engine === 'mysql' ? mycliInstalled : pgcliInstalled
+  // Engine-specific shell names
+  let defaultShellName: string
+  let engineSpecificCli: string
+  let engineSpecificInstalled: boolean
+  let engineSpecificValue: ShellChoice
+  let engineSpecificInstallValue: ShellChoice
+
+  if (config.engine === 'sqlite') {
+    defaultShellName = 'sqlite3'
+    engineSpecificCli = 'litecli'
+    engineSpecificInstalled = litecliInstalled
+    engineSpecificValue = 'litecli'
+    engineSpecificInstallValue = 'install-litecli'
+  } else if (config.engine === 'mysql') {
+    defaultShellName = 'mysql'
+    engineSpecificCli = 'mycli'
+    engineSpecificInstalled = mycliInstalled
+    engineSpecificValue = 'mycli'
+    engineSpecificInstallValue = 'install-mycli'
+  } else {
+    defaultShellName = 'psql'
+    engineSpecificCli = 'pgcli'
+    engineSpecificInstalled = pgcliInstalled
+    engineSpecificValue = 'pgcli'
+    engineSpecificInstallValue = 'install-pgcli'
+  }
 
   const choices: Array<{ name: string; value: ShellChoice } | inquirer.Separator> = [
     {
@@ -101,15 +129,16 @@ export async function handleOpenShell(containerName: string): Promise<void> {
   if (engineSpecificInstalled) {
     choices.push({
       name: `⚡ Use ${engineSpecificCli} (enhanced features, recommended)`,
-      value: config.engine === 'mysql' ? 'mycli' : 'pgcli',
+      value: engineSpecificValue,
     })
   } else {
     choices.push({
       name: `↓ Install ${engineSpecificCli} (enhanced features, recommended)`,
-      value: config.engine === 'mysql' ? 'install-mycli' : 'install-pgcli',
+      value: engineSpecificInstallValue,
     })
   }
 
+  // usql supports SQLite too
   if (usqlInstalled) {
     choices.push({
       name: '⚡ Use usql (universal SQL client)',
@@ -241,6 +270,39 @@ export async function handleOpenShell(containerName: string): Promise<void> {
     return
   }
 
+  if (shellChoice === 'install-litecli') {
+    console.log()
+    console.log(info('Installing litecli for enhanced SQLite shell...'))
+    const pm = await detectPackageManager()
+    if (pm) {
+      const result = await installLitecli(pm)
+      if (result.success) {
+        console.log(success('litecli installed successfully!'))
+        console.log()
+        await launchShell(containerName, config, connectionString, 'litecli')
+      } else {
+        console.error(error(`Failed to install litecli: ${result.error}`))
+        console.log()
+        console.log(chalk.gray('Manual installation:'))
+        for (const instruction of getLitecliManualInstructions()) {
+          console.log(chalk.cyan(`  ${instruction}`))
+        }
+        console.log()
+        await pressEnterToContinue()
+      }
+    } else {
+      console.error(error('No supported package manager found'))
+      console.log()
+      console.log(chalk.gray('Manual installation:'))
+      for (const instruction of getLitecliManualInstructions()) {
+        console.log(chalk.cyan(`  ${instruction}`))
+      }
+      console.log()
+      await pressEnterToContinue()
+    }
+    return
+  }
+
   await launchShell(containerName, config, connectionString, shellChoice)
 }
 
@@ -248,7 +310,7 @@ async function launchShell(
   containerName: string,
   config: NonNullable<Awaited<ReturnType<typeof containerManager.getConfig>>>,
   connectionString: string,
-  shellType: 'default' | 'usql' | 'pgcli' | 'mycli',
+  shellType: 'default' | 'usql' | 'pgcli' | 'mycli' | 'litecli',
 ): Promise<void> {
   console.log(info(`Connecting to ${containerName}...`))
   console.log()
@@ -275,11 +337,21 @@ async function launchShell(
       config.database,
     ]
     installHint = 'brew install mycli'
+  } else if (shellType === 'litecli') {
+    // litecli takes the database file path directly
+    shellCmd = 'litecli'
+    shellArgs = [config.database]
+    installHint = 'brew install litecli'
   } else if (shellType === 'usql') {
-    // usql accepts connection strings directly for both PostgreSQL and MySQL
+    // usql accepts connection strings directly for PostgreSQL, MySQL, and SQLite
     shellCmd = 'usql'
     shellArgs = [connectionString]
     installHint = 'brew tap xo/xo && brew install xo/xo/usql'
+  } else if (config.engine === 'sqlite') {
+    // Default SQLite shell
+    shellCmd = 'sqlite3'
+    shellArgs = [config.database]
+    installHint = 'brew install sqlite3'
   } else if (config.engine === 'mysql') {
     shellCmd = 'mysql'
     shellArgs = [
@@ -302,19 +374,31 @@ async function launchShell(
     stdio: 'inherit',
   })
 
-  shellProcess.on('error', (err: NodeJS.ErrnoException) => {
-    if (err.code === 'ENOENT') {
-      console.log(warning(`${shellCmd} not found on your system.`))
-      console.log()
-      console.log(chalk.gray('  Connect manually with:'))
-      console.log(chalk.cyan(`  ${connectionString}`))
-      console.log()
-      console.log(chalk.gray(`  Install ${shellCmd}:`))
-      console.log(chalk.cyan(`  ${installHint}`))
+  await new Promise<void>((resolve) => {
+    let settled = false
+
+    const settle = () => {
+      if (!settled) {
+        settled = true
+        resolve()
+      }
     }
-  })
 
-  await new Promise<void>((resolve) => {
-    shellProcess.on('close', () => resolve())
+    shellProcess.on('error', (err: NodeJS.ErrnoException) => {
+      if (err.code === 'ENOENT') {
+        console.log(warning(`${shellCmd} not found on your system.`))
+        console.log()
+        console.log(chalk.gray('  Connect manually with:'))
+        console.log(chalk.cyan(`  ${connectionString}`))
+        console.log()
+        console.log(chalk.gray(`  Install ${shellCmd}:`))
+        console.log(chalk.cyan(`  ${installHint}`))
+      } else {
+        console.log(error(`Failed to start ${shellCmd}: ${err.message}`))
+      }
+      settle()
+    })
+
+    shellProcess.on('close', settle)
   })
 }

package/cli/commands/menu/sql-handlers.ts

@@ -169,11 +169,23 @@ export async function handleViewLogs(containerName: string): Promise<void> {
       stdio: 'inherit',
     })
     await new Promise<void>((resolve) => {
-      process.on('SIGINT', () => {
+      let settled = false
+
+      const cleanup = () => {
+        if (!settled) {
+          settled = true
+          process.off('SIGINT', handleSigint)
+          resolve()
+        }
+      }
+
+      const handleSigint = () => {
         child.kill('SIGTERM')
-        resolve()
-      })
-      child.on('close', () => resolve())
+        cleanup()
+      }
+
+      process.on('SIGINT', handleSigint)
+      child.on('close', cleanup)
     })
     return
   }

package/cli/commands/menu/update-handlers.ts

@@ -1,9 +1,17 @@
+import { existsSync } from 'fs'
 import chalk from 'chalk'
 import inquirer from 'inquirer'
 import { updateManager } from '../../../core/update-manager'
+import { containerManager } from '../../../core/container-manager'
+import { configManager } from '../../../core/config-manager'
+import { sqliteRegistry } from '../../../engines/sqlite/registry'
+import { paths } from '../../../config/paths'
+import { getSupportedEngines } from '../../../config/engine-defaults'
+import { checkEngineDependencies } from '../../../core/dependency-manager'
 import { createSpinner } from '../../ui/spinner'
 import { header, success, error, warning, info } from '../../ui/theme'
 import { pressEnterToContinue } from './shared'
+import { Engine } from '../../../types'
 
 export async function handleCheckUpdate(): Promise<void> {
   console.clear()
@@ -92,3 +100,273 @@ export async function handleCheckUpdate(): Promise<void> {
     await pressEnterToContinue()
   }
 }
+
+type HealthCheckResult = {
+  name: string
+  status: 'ok' | 'warning' | 'error'
+  message: string
+  details?: string[]
+  action?: {
+    label: string
+    handler: () => Promise<void>
+  }
+}
+
+async function checkConfiguration(): Promise<HealthCheckResult> {
+  const configPath = paths.config
+
+  if (!existsSync(configPath)) {
+    return {
+      name: 'Configuration',
+      status: 'ok',
+      message: 'No config file yet (will be created on first use)',
+    }
+  }
+
+  try {
+    const config = await configManager.load()
+    const binaryCount = Object.keys(config.binaries || {}).length
+    const isStale = await configManager.isStale()
+
+    if (isStale) {
+      return {
+        name: 'Configuration',
+        status: 'warning',
+        message: 'Binary cache is stale (>7 days old)',
+        details: [`Binary tools cached: ${binaryCount}`],
+        action: {
+          label: 'Refresh binary cache',
+          handler: async () => {
+            await configManager.refreshAllBinaries()
+            console.log(success('Binary cache refreshed'))
+          },
+        },
+      }
+    }
+
+    return {
+      name: 'Configuration',
+      status: 'ok',
+      message: 'Configuration valid',
+      details: [`Binary tools cached: ${binaryCount}`],
+    }
+  } catch (err) {
+    return {
+      name: 'Configuration',
+      status: 'error',
+      message: 'Configuration file is corrupted',
+      details: [(err as Error).message],
+    }
+  }
+}
+
+async function checkContainers(): Promise<HealthCheckResult> {
+  try {
+    const containers = await containerManager.list()
+
+    if (containers.length === 0) {
+      return {
+        name: 'Containers',
+        status: 'ok',
+        message: 'No containers (create one with: spindb create)',
+      }
+    }
+
+    const byEngine: Record<string, { running: number; stopped: number }> = {}
+
+    for (const c of containers) {
+      const engineName = c.engine
+      if (!byEngine[engineName]) {
+        byEngine[engineName] = { running: 0, stopped: 0 }
+      }
+      if (c.status === 'running') {
+        byEngine[engineName].running++
+      } else {
+        byEngine[engineName].stopped++
+      }
+    }
+
+    const details = Object.entries(byEngine).map(([engine, counts]) => {
+      if (engine === Engine.SQLite) {
+        return `${engine}: ${counts.running} exist, ${counts.stopped} missing`
+      }
+      return `${engine}: ${counts.running} running, ${counts.stopped} stopped`
+    })
+
+    return {
+      name: 'Containers',
+      status: 'ok',
+      message: `${containers.length} container(s)`,
+      details,
+    }
+  } catch (err) {
+    return {
+      name: 'Containers',
+      status: 'error',
+      message: 'Failed to list containers',
+      details: [(err as Error).message],
+    }
+  }
+}
+
+async function checkSqliteRegistry(): Promise<HealthCheckResult> {
+  try {
+    const entries = await sqliteRegistry.list()
+
+    if (entries.length === 0) {
+      return {
+        name: 'SQLite Registry',
+        status: 'ok',
+        message: 'No SQLite databases registered',
+      }
+    }
+
+    const orphans = await sqliteRegistry.findOrphans()
+
+    if (orphans.length > 0) {
+      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}`),
+        action: {
+          label: 'Remove orphaned entries from registry',
+          handler: async () => {
+            const count = await sqliteRegistry.removeOrphans()
+            console.log(success(`Removed ${count} orphaned entries`))
+          },
+        },
+      }
+    }
+
+    return {
+      name: 'SQLite Registry',
+      status: 'ok',
+      message: `${entries.length} database(s) registered, all files exist`,
+    }
+  } catch (err) {
+    return {
+      name: 'SQLite Registry',
+      status: 'warning',
+      message: 'Could not check registry',
+      details: [(err as Error).message],
+    }
+  }
+}
+
+async function checkBinaries(): Promise<HealthCheckResult> {
+  try {
+    const engines = getSupportedEngines()
+    const results: string[] = []
+    let hasWarning = false
+
+    for (const engine of engines) {
+      const statuses = await checkEngineDependencies(engine)
+      const installed = statuses.filter((s) => s.installed).length
+      const total = statuses.length
+
+      if (installed < total) {
+        hasWarning = true
+        results.push(`${engine}: ${installed}/${total} tools installed`)
+      } else {
+        results.push(`${engine}: all ${total} tools available`)
+      }
+    }
+
+    return {
+      name: 'Database Tools',
+      status: hasWarning ? 'warning' : 'ok',
+      message: hasWarning ? 'Some tools missing' : 'All tools available',
+      details: results,
+    }
+  } catch (err) {
+    return {
+      name: 'Database Tools',
+      status: 'error',
+      message: 'Failed to check tools',
+      details: [(err as Error).message],
+    }
+  }
+}
+
+function displayResult(result: HealthCheckResult): void {
+  const icon =
+    result.status === 'ok'
+      ? chalk.green('✓')
+      : result.status === 'warning'
+        ? chalk.yellow('⚠')
+        : chalk.red('✕')
+
+  console.log(`${icon} ${chalk.bold(result.name)}`)
+  console.log(`  └─ ${result.message}`)
+
+  if (result.details) {
+    for (const detail of result.details) {
+      console.log(chalk.gray(`     ${detail}`))
+    }
+  }
+  console.log()
+}
+
+export async function handleDoctor(): Promise<void> {
+  console.clear()
+  console.log(header('SpinDB Health Check'))
+  console.log()
+
+  const checks = [
+    await checkConfiguration(),
+    await checkContainers(),
+    await checkSqliteRegistry(),
+    await checkBinaries(),
+  ]
+
+  // Display results
+  for (const check of checks) {
+    displayResult(check)
+  }
+
+  // Collect actions for warnings
+  const actionsAvailable = checks.filter((c) => c.action)
+
+  if (actionsAvailable.length > 0) {
+    type ActionChoice = {
+      name: string
+      value: string
+    }
+
+    const choices: ActionChoice[] = [
+      ...actionsAvailable.map((c) => ({
+        name: c.action!.label,
+        value: c.name,
+      })),
+      { name: chalk.gray('Skip (do nothing)'), value: 'skip' },
+    ]
+
+    const { selectedAction } = await inquirer.prompt<{
+      selectedAction: string
+    }>([
+      {
+        type: 'list',
+        name: 'selectedAction',
+        message: 'What would you like to do?',
+        choices,
+      },
+    ])
+
+    if (selectedAction !== 'skip') {
+      const check = checks.find((c) => c.name === selectedAction)
+      if (check?.action) {
+        console.log()
+        await check.action.handler()
+      }
+    }
+  } else {
+    const hasIssues = checks.some((c) => c.status !== 'ok')
+    if (!hasIssues) {
+      console.log(chalk.green('All systems healthy! ✓'))
+    }
+  }
+
+  console.log()
+  await pressEnterToContinue()
+}

package/cli/commands/run.ts

@@ -7,6 +7,7 @@ import { getEngine } from '../../engines'
 import { promptInstallDependencies } from '../ui/prompts'
 import { error, warning } from '../ui/theme'
 import { getMissingDependencies } from '../../core/dependency-manager'
+import { Engine } from '../../types'
 
 export const runCommand = new Command('run')
   .description('Run SQL file or statement against a container')
@@ -31,16 +32,29 @@ export const runCommand = new Command('run')
 
         const { engine: engineName } = config
 
-        const running = await processManager.isRunning(containerName, {
-          engine: engineName,
-        })
-        if (!running) {
-          console.error(
-            error(
-              `Container "${containerName}" is not running. Start it first with: spindb start ${containerName}`,
-            ),
-          )
-          process.exit(1)
+        // SQLite: check file exists instead of running status
+        if (engineName === Engine.SQLite) {
+          if (!existsSync(config.database)) {
+            console.error(
+              error(
+                `SQLite database file not found: ${config.database}`,
+              ),
+            )
+            process.exit(1)
+          }
+        } else {
+          // Server databases need to be running
+          const running = await processManager.isRunning(containerName, {
+            engine: engineName,
+          })
+          if (!running) {
+            console.error(
+              error(
+                `Container "${containerName}" is not running. Start it first with: spindb start ${containerName}`,
+              ),
+            )
+            process.exit(1)
+          }
         }
 
         if (file && options.sql) {
@@ -123,7 +137,9 @@ export const runCommand = new Command('run')
           const missingTool = matchingPattern
             .replace(' not found', '')
             .replace(' client', '')
-          const installed = await promptInstallDependencies(missingTool)
+          // Determine engine from the missing tool name
+          const toolEngine = missingTool === 'mysql' ? Engine.MySQL : Engine.PostgreSQL
+          const installed = await promptInstallDependencies(missingTool, toolEngine)
           if (installed) {
             console.log(
               chalk.yellow('  Please re-run your command to continue.'),

package/cli/commands/url.ts

@@ -47,15 +47,23 @@ export const urlCommand = new Command('url')
         const connectionString = engine.getConnectionString(config, databaseName)
 
         if (options.json) {
-          const jsonOutput = {
-            connectionString,
-            host: '127.0.0.1',
-            port: config.port,
-            database: databaseName,
-            user: config.engine === 'postgresql' ? 'postgres' : 'root',
-            engine: config.engine,
-            container: config.name,
-          }
+          const jsonOutput =
+            config.engine === 'sqlite'
+              ? {
+                  connectionString,
+                  path: databaseName,
+                  engine: config.engine,
+                  container: config.name,
+                }
+              : {
+                  connectionString,
+                  host: '127.0.0.1',
+                  port: config.port,
+                  database: databaseName,
+                  user: config.engine === 'postgresql' ? 'postgres' : 'root',
+                  engine: config.engine,
+                  container: config.name,
+                }
           console.log(JSON.stringify(jsonOutput, null, 2))
           return
         }

package/cli/constants.ts

@@ -1,6 +1,7 @@
 export const ENGINE_ICONS: Record<string, string> = {
   postgresql: '🐘',
   mysql: '🐬',
+  sqlite: '🪶',
 }
 
 export const DEFAULT_ENGINE_ICON = '▣'

package/cli/index.ts

@@ -24,6 +24,7 @@ import { selfUpdateCommand } from './commands/self-update'
 import { versionCommand } from './commands/version'
 import { runCommand } from './commands/run'
 import { logsCommand } from './commands/logs'
+import { doctorCommand } from './commands/doctor'
 import { updateManager } from '../core/update-manager'
 
 /**
@@ -123,6 +124,7 @@ export async function run(): Promise<void> {
   program.addCommand(versionCommand)
   program.addCommand(runCommand)
   program.addCommand(logsCommand)
+  program.addCommand(doctorCommand)
 
   // If no arguments provided, show interactive menu
   if (process.argv.length <= 2) {