spindb 0.9.2 → 0.9.3

package/README.md

@@ -653,16 +653,13 @@ rm -rf ~/.spindb
 
 ## Contributing
 
-See [CLAUDE.md](CLAUDE.md) for development setup and architecture documentation.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and distribution info.
 
-### Running Tests
+See [ARCHITECTURE.md](ARCHITECTURE.md) for project architecture and comprehensive CLI command examples.
 
-```bash
-pnpm test           # All tests
-pnpm test:unit      # Unit tests only
-pnpm test:pg        # PostgreSQL integration
-pnpm test:mysql     # MySQL integration
-```
+See [CLAUDE.md](CLAUDE.md) for AI-assisted development context.
+
+See [ENGINES.md](ENGINES.md) for detailed engine documentation (backup formats, planned engines, etc.).
 
 ---
 

package/cli/commands/attach.ts

@@ -0,0 +1,108 @@
+import { Command } from 'commander'
+import { existsSync } from 'fs'
+import { resolve, basename } from 'path'
+import chalk from 'chalk'
+import { sqliteRegistry } from '../../engines/sqlite/registry'
+import { containerManager } from '../../core/container-manager'
+import { deriveContainerName } from '../../engines/sqlite/scanner'
+import { uiSuccess, uiError } from '../ui/theme'
+
+export const attachCommand = new Command('attach')
+  .description('Register an existing SQLite database with SpinDB')
+  .argument('<path>', 'Path to SQLite database file')
+  .option('-n, --name <name>', 'Container name (defaults to filename)')
+  .option('--json', 'Output as JSON')
+  .action(
+    async (
+      path: string,
+      options: { name?: string; json?: boolean },
+    ): Promise<void> => {
+      try {
+        const absolutePath = resolve(path)
+
+        // Verify file exists
+        if (!existsSync(absolutePath)) {
+          if (options.json) {
+            console.log(
+              JSON.stringify({ success: false, error: 'File not found' }),
+            )
+          } else {
+            console.error(uiError(`File not found: ${absolutePath}`))
+          }
+          process.exit(1)
+        }
+
+        // Check if already registered
+        if (await sqliteRegistry.isPathRegistered(absolutePath)) {
+          const entry = await sqliteRegistry.getByPath(absolutePath)
+          if (options.json) {
+            console.log(
+              JSON.stringify({
+                success: false,
+                error: 'Already registered',
+                existingName: entry?.name,
+              }),
+            )
+          } else {
+            console.error(
+              uiError(`File is already registered as "${entry?.name}"`),
+            )
+          }
+          process.exit(1)
+        }
+
+        // Determine container name
+        const containerName =
+          options.name || deriveContainerName(basename(absolutePath))
+
+        // Check if container name exists
+        if (await containerManager.exists(containerName)) {
+          if (options.json) {
+            console.log(
+              JSON.stringify({
+                success: false,
+                error: 'Container name already exists',
+              }),
+            )
+          } else {
+            console.error(uiError(`Container "${containerName}" already exists`))
+          }
+          process.exit(1)
+        }
+
+        // Register the file
+        await sqliteRegistry.add({
+          name: containerName,
+          filePath: absolutePath,
+          created: new Date().toISOString(),
+        })
+
+        if (options.json) {
+          console.log(
+            JSON.stringify({
+              success: true,
+              name: containerName,
+              filePath: absolutePath,
+            }),
+          )
+        } else {
+          console.log(
+            uiSuccess(
+              `Registered "${basename(absolutePath)}" as "${containerName}"`,
+            ),
+          )
+          console.log()
+          console.log(chalk.gray('  Connect with:'))
+          console.log(chalk.cyan(`    spindb connect ${containerName}`))
+        }
+      } catch (error) {
+        const e = error as Error
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: e.message }))
+        } else {
+          console.error(uiError(e.message))
+        }
+        process.exit(1)
+      }
+    },
+  )

package/cli/commands/create.ts

@@ -100,6 +100,12 @@ async function createSqliteContainer(
         restoreSpinner.succeed('Backup restored successfully')
       } catch (error) {
         restoreSpinner.fail('Failed to restore backup')
+        // Clean up the created container on restore failure
+        try {
+          await containerManager.delete(containerName, { force: true })
+        } catch {
+          // Ignore cleanup errors - still throw the original restore error
+        }
         throw error
       }
     }

package/cli/commands/detach.ts

@@ -0,0 +1,100 @@
+import { Command } from 'commander'
+import chalk from 'chalk'
+import { sqliteRegistry } from '../../engines/sqlite/registry'
+import { containerManager } from '../../core/container-manager'
+import { promptConfirm } from '../ui/prompts'
+import { uiSuccess, uiError, uiWarning } from '../ui/theme'
+import { Engine } from '../../types'
+
+export const detachCommand = new Command('detach')
+  .description('Unregister a SQLite database from SpinDB (keeps file on disk)')
+  .argument('<name>', 'Container name')
+  .option('-f, --force', 'Skip confirmation prompt')
+  .option('--json', 'Output as JSON')
+  .action(
+    async (
+      name: string,
+      options: { force?: boolean; json?: boolean },
+    ): Promise<void> => {
+      try {
+        // Get container config
+        const config = await containerManager.getConfig(name)
+
+        if (!config) {
+          if (options.json) {
+            console.log(
+              JSON.stringify({ success: false, error: 'Container not found' }),
+            )
+          } else {
+            console.error(uiError(`Container "${name}" not found`))
+          }
+          process.exit(1)
+        }
+
+        // Verify it's a SQLite container
+        if (config.engine !== Engine.SQLite) {
+          if (options.json) {
+            console.log(
+              JSON.stringify({
+                success: false,
+                error:
+                  'Not a SQLite container. Use "spindb delete" for server databases.',
+              }),
+            )
+          } else {
+            console.error(uiError(`"${name}" is not a SQLite container`))
+            console.log(
+              chalk.gray(
+                '  Use "spindb delete" for server databases (PostgreSQL, MySQL)',
+              ),
+            )
+          }
+          process.exit(1)
+        }
+
+        // Confirm unless --force
+        if (!options.force && !options.json) {
+          const confirmed = await promptConfirm(
+            `Detach "${name}" from SpinDB? (file will be kept on disk)`,
+            true,
+          )
+          if (!confirmed) {
+            console.log(uiWarning('Cancelled'))
+            return
+          }
+        }
+
+        const entry = await sqliteRegistry.get(name)
+        const filePath = entry?.filePath
+
+        // Remove from registry only (not the file)
+        await sqliteRegistry.remove(name)
+
+        if (options.json) {
+          console.log(
+            JSON.stringify({
+              success: true,
+              name,
+              filePath,
+            }),
+          )
+        } else {
+          console.log(uiSuccess(`Detached "${name}" from SpinDB`))
+          if (filePath) {
+            console.log(chalk.gray(`  File remains at: ${filePath}`))
+          }
+          console.log()
+          console.log(chalk.gray('  Re-attach with:'))
+          console.log(chalk.cyan(`    spindb attach ${filePath || '<path>'}`))
+        }
+      } catch (error) {
+        const e = error as Error
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: e.message }))
+        } else {
+          console.error(uiError(e.message))
+        }
+        process.exit(1)
+      }
+    },
+  )

package/cli/commands/doctor.ts

@@ -141,8 +141,9 @@ async function checkContainers(): Promise<HealthCheckResult> {
 async function checkSqliteRegistry(): Promise<HealthCheckResult> {
   try {
     const entries = await sqliteRegistry.list()
+    const ignoredFolders = await sqliteRegistry.listIgnoredFolders()
 
-    if (entries.length === 0) {
+    if (entries.length === 0 && ignoredFolders.length === 0) {
       return {
         name: 'SQLite Registry',
         status: 'ok',
@@ -153,11 +154,18 @@ async function checkSqliteRegistry(): Promise<HealthCheckResult> {
     const orphans = await sqliteRegistry.findOrphans()
 
     if (orphans.length > 0) {
+      const details = [
+        ...orphans.map((o) => `"${o.name}" → ${o.filePath}`),
+        ...(ignoredFolders.length > 0
+          ? [`${ignoredFolders.length} folder(s) ignored`]
+          : []),
+      ]
+
       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}`),
+        details,
         action: {
           label: 'Remove orphaned entries from registry',
           handler: async () => {
@@ -168,10 +176,16 @@ async function checkSqliteRegistry(): Promise<HealthCheckResult> {
       }
     }
 
+    const details = [`${entries.length} database(s) registered, all files exist`]
+    if (ignoredFolders.length > 0) {
+      details.push(`${ignoredFolders.length} folder(s) ignored`)
+    }
+
     return {
       name: 'SQLite Registry',
       status: 'ok',
       message: `${entries.length} database(s) registered, all files exist`,
+      details: ignoredFolders.length > 0 ? details : undefined,
     }
   } catch (error) {
     return {

package/cli/commands/edit.ts

@@ -521,6 +521,11 @@ export const editCommand = new Command('edit')
           spinner.start()
 
           try {
+            // Track if we need to delete source file after registry update
+            // (for cross-device moves where rename doesn't work)
+            let needsSourceCleanup = false
+            const originalPath = config.database
+
             // Try rename first (fast, same filesystem)
             try {
               renameSync(config.database, newPath)
@@ -531,8 +536,8 @@ export const editCommand = new Command('edit')
                 try {
                   // Copy file preserving mode/permissions
                   copyFileSync(config.database, newPath)
-                  // Only delete source after successful copy
-                  unlinkSync(config.database)
+                  // Don't delete source yet - wait for registry update to succeed
+                  needsSourceCleanup = true
                 } catch (copyErr) {
                   // Clean up partial target on failure
                   if (existsSync(newPath)) {
@@ -555,6 +560,11 @@ export const editCommand = new Command('edit')
             })
             await sqliteRegistry.update(containerName, { filePath: newPath })
 
+            // Now safe to delete source file for cross-device moves
+            if (needsSourceCleanup && existsSync(originalPath)) {
+              unlinkSync(originalPath)
+            }
+
             spinner.succeed(`Database relocated to ${newPath}`)
           } catch (error) {
             spinner.fail('Failed to relocate database')

package/cli/commands/list.ts

@@ -1,12 +1,18 @@
 import { Command } from 'commander'
 import chalk from 'chalk'
+import inquirer from 'inquirer'
+import { dirname, basename } from 'path'
 import { containerManager } from '../../core/container-manager'
 import { getEngine } from '../../engines'
 import { uiInfo, uiError, formatBytes } from '../ui/theme'
 import { getEngineIcon } from '../constants'
 import { Engine } from '../../types'
-import { basename } from 'path'
 import type { ContainerConfig } from '../../types'
+import { sqliteRegistry } from '../../engines/sqlite/registry'
+import {
+  scanForUnregisteredSqliteFiles,
+  deriveContainerName,
+} from '../../engines/sqlite/scanner'
 
 /**
  * Pad string to width, accounting for emoji taking 2 display columns
@@ -17,6 +23,88 @@ function padWithEmoji(str: string, width: number): string {
   return str.padEnd(width + emojiCount)
 }
 
+/**
+ * Prompt user about unregistered SQLite files in CWD
+ * Returns true if user registered any files (refresh needed)
+ */
+async function promptUnregisteredFiles(): Promise<boolean> {
+  const unregistered = await scanForUnregisteredSqliteFiles()
+
+  if (unregistered.length === 0) {
+    return false
+  }
+
+  let anyRegistered = false
+
+  for (let i = 0; i < unregistered.length; i++) {
+    const file = unregistered[i]
+    const prompt =
+      unregistered.length > 1 ? `[${i + 1} of ${unregistered.length}] ` : ''
+
+    const { action } = await inquirer.prompt<{ action: string }>([
+      {
+        type: 'list',
+        name: 'action',
+        message: `${prompt}Unregistered SQLite database "${file.fileName}" found in current directory. Register with SpinDB?`,
+        choices: [
+          { name: 'Yes', value: 'yes' },
+          { name: 'No', value: 'no' },
+          { name: "No - don't ask again for this folder", value: 'ignore' },
+        ],
+      },
+    ])
+
+    if (action === 'yes') {
+      const suggestedName = deriveContainerName(file.fileName)
+      const { containerName } = await inquirer.prompt<{
+        containerName: string
+      }>([
+        {
+          type: 'input',
+          name: 'containerName',
+          message: 'Container name:',
+          default: suggestedName,
+          validate: (input: string) => {
+            if (!input) return 'Name is required'
+            if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(input)) {
+              return 'Name must start with a letter and contain only letters, numbers, hyphens, and underscores'
+            }
+            return true
+          },
+        },
+      ])
+
+      // Check if name already exists
+      if (await sqliteRegistry.exists(containerName)) {
+        console.log(
+          chalk.yellow(`  Container "${containerName}" already exists. Skipping.`),
+        )
+        continue
+      }
+
+      await sqliteRegistry.add({
+        name: containerName,
+        filePath: file.absolutePath,
+        created: new Date().toISOString(),
+      })
+      console.log(
+        chalk.green(`  Registered "${file.fileName}" as "${containerName}"`),
+      )
+      anyRegistered = true
+    } else if (action === 'ignore') {
+      await sqliteRegistry.addIgnoreFolder(dirname(file.absolutePath))
+      console.log(chalk.gray('  Folder will be ignored in future scans.'))
+      break // Exit early
+    }
+  }
+
+  if (anyRegistered) {
+    console.log() // Add spacing before list
+  }
+
+  return anyRegistered
+}
+
 async function getContainerSize(
   container: ContainerConfig,
 ): Promise<number | null> {
@@ -46,8 +134,14 @@ export const listCommand = new Command('list')
   .alias('ls')
   .description('List all containers')
   .option('--json', 'Output as JSON')
-  .action(async (options: { json?: boolean }) => {
+  .option('--no-scan', 'Skip scanning for unregistered SQLite files in CWD')
+  .action(async (options: { json?: boolean; scan?: boolean }) => {
     try {
+      // Scan for unregistered SQLite files in CWD (unless JSON mode or --no-scan)
+      if (!options.json && options.scan !== false) {
+        await promptUnregisteredFiles()
+      }
+
       const containers = await containerManager.list()
 
       if (options.json) {

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

@@ -200,7 +200,9 @@ export async function handleCreate(): Promise<void> {
 
     startSpinner.succeed(`${dbEngine.displayName} started`)
 
-    if (config && database !== 'postgres') {
+    // Skip creating 'postgres' database for PostgreSQL - it's created by initdb
+    // For other engines (MySQL, SQLite), allow creating a database named 'postgres'
+    if (config && !(config.engine === 'postgresql' && database === 'postgres')) {
       const dbSpinner = createSpinner(`Creating database "${database}"...`)
       dbSpinner.start()
 
@@ -532,6 +534,14 @@ export async function showContainerSubmenu(
     })
   }
 
+  // Detach - only for SQLite (unregisters without deleting file)
+  if (isSQLite) {
+    actionChoices.push({
+      name: `${chalk.yellow('⊘')} Detach from SpinDB`,
+      value: 'detach',
+    })
+  }
+
   // Delete container - SQLite can always delete, server databases must be stopped
   const canDelete = isSQLite ? true : !isRunning
   actionChoices.push({
@@ -606,6 +616,9 @@ export async function showContainerSubmenu(
       await handleCopyConnectionString(containerName)
       await showContainerSubmenu(containerName, showMainMenu)
       return
+    case 'detach':
+      await handleDetachContainer(containerName, showMainMenu)
+      return // Return to list after detach
     case 'delete':
       await handleDelete(containerName)
       return // Don't show submenu again after delete
@@ -1135,6 +1148,36 @@ async function handleCloneFromSubmenu(
   }
 }
 
+async function handleDetachContainer(
+  containerName: string,
+  showMainMenu: () => Promise<void>,
+): Promise<void> {
+  const confirmed = await promptConfirm(
+    `Detach "${containerName}" from SpinDB? (file will be kept on disk)`,
+    true,
+  )
+
+  if (!confirmed) {
+    console.log(uiWarning('Cancelled'))
+    await pressEnterToContinue()
+    await showContainerSubmenu(containerName, showMainMenu)
+    return
+  }
+
+  const entry = await sqliteRegistry.get(containerName)
+  await sqliteRegistry.remove(containerName)
+
+  console.log(uiSuccess(`Detached "${containerName}" from SpinDB`))
+  if (entry?.filePath) {
+    console.log(chalk.gray(`  File remains at: ${entry.filePath}`))
+    console.log()
+    console.log(chalk.gray('  Re-attach with:'))
+    console.log(chalk.cyan(`    spindb attach ${entry.filePath}`))
+  }
+  await pressEnterToContinue()
+  await handleList(showMainMenu)
+}
+
 async function handleDelete(containerName: string): Promise<void> {
   const config = await containerManager.getConfig(containerName)
   if (!config) {

package/cli/commands/sqlite.ts

@@ -0,0 +1,247 @@
+import { Command } from 'commander'
+import chalk from 'chalk'
+import { existsSync } from 'fs'
+import { resolve, basename } from 'path'
+import { sqliteRegistry } from '../../engines/sqlite/registry'
+import {
+  scanForUnregisteredSqliteFiles,
+  deriveContainerName,
+} from '../../engines/sqlite/scanner'
+import { containerManager } from '../../core/container-manager'
+import { uiSuccess, uiError, uiInfo } from '../ui/theme'
+
+export const sqliteCommand = new Command('sqlite').description(
+  'SQLite-specific operations',
+)
+
+// sqlite scan
+sqliteCommand
+  .command('scan')
+  .description('Scan folder for unregistered SQLite files')
+  .option(
+    '-p, --path <dir>',
+    'Directory to scan (default: current directory)',
+  )
+  .option('--json', 'Output as JSON')
+  .action(async (options: { path?: string; json?: boolean }): Promise<void> => {
+    const dir = options.path ? resolve(options.path) : process.cwd()
+
+    if (!existsSync(dir)) {
+      if (options.json) {
+        console.log(
+          JSON.stringify({ error: 'Directory not found', directory: dir }),
+        )
+      } else {
+        console.error(uiError(`Directory not found: ${dir}`))
+      }
+      process.exit(1)
+    }
+
+    const unregistered = await scanForUnregisteredSqliteFiles(dir)
+
+    if (options.json) {
+      console.log(JSON.stringify({ directory: dir, files: unregistered }))
+      return
+    }
+
+    if (unregistered.length === 0) {
+      console.log(uiInfo(`No unregistered SQLite files found in ${dir}`))
+      return
+    }
+
+    console.log(
+      chalk.cyan(`Found ${unregistered.length} unregistered SQLite file(s):`),
+    )
+    for (const file of unregistered) {
+      console.log(chalk.gray(`  ${file.fileName}`))
+    }
+    console.log()
+    console.log(chalk.gray('  Register with: spindb attach <path>'))
+  })
+
+// sqlite ignore
+sqliteCommand
+  .command('ignore')
+  .description('Add folder to ignore list for CWD scanning')
+  .argument('[folder]', 'Folder path to ignore (default: current directory)')
+  .option('--json', 'Output as JSON')
+  .action(
+    async (folder: string | undefined, options: { json?: boolean }): Promise<void> => {
+      const absolutePath = resolve(folder || process.cwd())
+      await sqliteRegistry.addIgnoreFolder(absolutePath)
+
+      if (options.json) {
+        console.log(JSON.stringify({ success: true, folder: absolutePath }))
+      } else {
+        console.log(uiSuccess(`Added to ignore list: ${absolutePath}`))
+      }
+    },
+  )
+
+// sqlite unignore
+sqliteCommand
+  .command('unignore')
+  .description('Remove folder from ignore list')
+  .argument('[folder]', 'Folder path to unignore (default: current directory)')
+  .option('--json', 'Output as JSON')
+  .action(
+    async (folder: string | undefined, options: { json?: boolean }): Promise<void> => {
+      const absolutePath = resolve(folder || process.cwd())
+      const removed = await sqliteRegistry.removeIgnoreFolder(absolutePath)
+
+      if (options.json) {
+        console.log(JSON.stringify({ success: removed, folder: absolutePath }))
+      } else {
+        if (removed) {
+          console.log(uiSuccess(`Removed from ignore list: ${absolutePath}`))
+        } else {
+          console.log(uiInfo(`Folder was not in ignore list: ${absolutePath}`))
+        }
+      }
+    },
+  )
+
+// sqlite ignored (list ignored folders)
+sqliteCommand
+  .command('ignored')
+  .description('List ignored folders')
+  .option('--json', 'Output as JSON')
+  .action(async (options: { json?: boolean }): Promise<void> => {
+    const folders = await sqliteRegistry.listIgnoredFolders()
+
+    if (options.json) {
+      console.log(JSON.stringify({ folders }))
+      return
+    }
+
+    if (folders.length === 0) {
+      console.log(uiInfo('No folders are being ignored'))
+      return
+    }
+
+    console.log(chalk.cyan('Ignored folders:'))
+    for (const folder of folders) {
+      console.log(chalk.gray(`  ${folder}`))
+    }
+  })
+
+// sqlite attach (alias to top-level attach)
+sqliteCommand
+  .command('attach')
+  .description('Register an existing SQLite database (alias for "spindb attach")')
+  .argument('<path>', 'Path to SQLite database file')
+  .option('-n, --name <name>', 'Container name')
+  .option('--json', 'Output as JSON')
+  .action(
+    async (
+      path: string,
+      options: { name?: string; json?: boolean },
+    ): Promise<void> => {
+      try {
+        const absolutePath = resolve(path)
+
+        if (!existsSync(absolutePath)) {
+          if (options.json) {
+            console.log(
+              JSON.stringify({ success: false, error: 'File not found' }),
+            )
+          } else {
+            console.error(uiError(`File not found: ${absolutePath}`))
+          }
+          process.exit(1)
+        }
+
+        if (await sqliteRegistry.isPathRegistered(absolutePath)) {
+          const entry = await sqliteRegistry.getByPath(absolutePath)
+          if (options.json) {
+            console.log(
+              JSON.stringify({
+                success: false,
+                error: 'Already registered',
+                existingName: entry?.name,
+              }),
+            )
+          } else {
+            console.error(
+              uiError(`File is already registered as "${entry?.name}"`),
+            )
+          }
+          process.exit(1)
+        }
+
+        const containerName =
+          options.name || deriveContainerName(basename(absolutePath))
+
+        if (await containerManager.exists(containerName)) {
+          if (options.json) {
+            console.log(
+              JSON.stringify({
+                success: false,
+                error: 'Container name already exists',
+              }),
+            )
+          } else {
+            console.error(uiError(`Container "${containerName}" already exists`))
+          }
+          process.exit(1)
+        }
+
+        await sqliteRegistry.add({
+          name: containerName,
+          filePath: absolutePath,
+          created: new Date().toISOString(),
+        })
+
+        if (options.json) {
+          console.log(
+            JSON.stringify({
+              success: true,
+              name: containerName,
+              filePath: absolutePath,
+            }),
+          )
+        } else {
+          console.log(
+            uiSuccess(
+              `Registered "${basename(absolutePath)}" as "${containerName}"`,
+            ),
+          )
+          console.log()
+          console.log(chalk.gray('  Connect with:'))
+          console.log(chalk.cyan(`    spindb connect ${containerName}`))
+        }
+      } catch (error) {
+        const e = error as Error
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: e.message }))
+        } else {
+          console.error(uiError(e.message))
+        }
+        process.exit(1)
+      }
+    },
+  )
+
+// sqlite detach (alias to top-level detach)
+sqliteCommand
+  .command('detach')
+  .description('Unregister a SQLite database (alias for "spindb detach")')
+  .argument('<name>', 'Container name')
+  .option('-f, --force', 'Skip confirmation')
+  .option('--json', 'Output as JSON')
+  .action(
+    async (
+      name: string,
+      options: { force?: boolean; json?: boolean },
+    ): Promise<void> => {
+      // Import dynamically to avoid circular dependency issues
+      const { detachCommand } = await import('./detach')
+
+      // Build args array
+      const args = ['node', 'detach', name]
+      if (options.force) args.push('-f')
+      if (options.json) args.push('--json')
+
+      await detachCommand.parseAsync(args, { from: 'node' })
+    },
+  )

package/cli/index.ts

@@ -25,6 +25,9 @@ import { versionCommand } from './commands/version'
 import { runCommand } from './commands/run'
 import { logsCommand } from './commands/logs'
 import { doctorCommand } from './commands/doctor'
+import { attachCommand } from './commands/attach'
+import { detachCommand } from './commands/detach'
+import { sqliteCommand } from './commands/sqlite'
 import { updateManager } from '../core/update-manager'
 
 /**
@@ -125,6 +128,9 @@ export async function run(): Promise<void> {
   program.addCommand(runCommand)
   program.addCommand(logsCommand)
   program.addCommand(doctorCommand)
+  program.addCommand(attachCommand)
+  program.addCommand(detachCommand)
+  program.addCommand(sqliteCommand)
 
   // If no arguments provided, show interactive menu
   if (process.argv.length <= 2) {

package/config/paths.ts

@@ -114,12 +114,4 @@ export const paths = {
   getEngineContainersPath(engine: string): string {
     return join(this.containers, engine)
   },
-
-  /**
-   * Get path for SQLite registry file
-   * SQLite uses a registry (not container directories) since databases are stored externally
-   */
-  getSqliteRegistryPath(): string {
-    return join(this.root, 'sqlite-registry.json')
-  },
 }

package/core/config-manager.ts

@@ -10,6 +10,7 @@ import type {
   BinaryConfig,
   BinaryTool,
   BinarySource,
+  SQLiteEngineRegistry,
 } from '../types'
 
 const execAsync = promisify(exec)
@@ -349,6 +350,37 @@ export class ConfigManager {
     config.binaries = {}
     await this.save()
   }
+
+  // ============================================================
+  // SQLite Registry Methods
+  // ============================================================
+
+  /**
+   * Get the SQLite registry from config
+   * Returns empty registry if none exists
+   */
+  async getSqliteRegistry(): Promise<SQLiteEngineRegistry> {
+    const config = await this.load()
+    return (
+      config.registry?.sqlite ?? {
+        version: 1,
+        entries: [],
+        ignoreFolders: {},
+      }
+    )
+  }
+
+  /**
+   * Save the SQLite registry to config
+   */
+  async saveSqliteRegistry(registry: SQLiteEngineRegistry): Promise<void> {
+    const config = await this.load()
+    if (!config.registry) {
+      config.registry = {}
+    }
+    config.registry.sqlite = registry
+    await this.save()
+  }
 }
 
 export const configManager = new ConfigManager()

package/engines/mysql/backup.ts

@@ -98,12 +98,20 @@ async function createSqlBackup(
 
     proc.on('close', async (code) => {
       if (code === 0) {
-        const stats = await stat(outputPath)
-        safeResolve({
-          path: outputPath,
-          format: 'sql',
-          size: stats.size,
-        })
+        try {
+          const stats = await stat(outputPath)
+          safeResolve({
+            path: outputPath,
+            format: 'sql',
+            size: stats.size,
+          })
+        } catch (error) {
+          safeReject(
+            new Error(
+              `Backup completed but failed to read output file: ${error instanceof Error ? error.message : String(error)}`,
+            ),
+          )
+        }
       } else {
         const errorMessage = stderr || `mysqldump exited with code ${code}`
         safeReject(new Error(errorMessage))
@@ -164,13 +172,29 @@ async function createCompressedBackup(
     })
   })
 
-  // Wait for both pipeline AND process exit to succeed
-  await Promise.all([pipelinePromise, exitPromise])
+  // Wait for both pipeline AND process exit to complete
+  // Use allSettled to handle case where both reject (avoids unhandled rejection)
+  const results = await Promise.allSettled([pipelinePromise, exitPromise])
 
-  const stats = await stat(outputPath)
-  return {
-    path: outputPath,
-    format: 'compressed',
-    size: stats.size,
+  // Check for any rejections - prefer exitPromise error as it has more context
+  const [pipelineResult, exitResult] = results
+  if (exitResult.status === 'rejected') {
+    throw exitResult.reason
+  }
+  if (pipelineResult.status === 'rejected') {
+    throw pipelineResult.reason
+  }
+
+  try {
+    const stats = await stat(outputPath)
+    return {
+      path: outputPath,
+      format: 'compressed',
+      size: stats.size,
+    }
+  } catch (error) {
+    throw new Error(
+      `Backup completed but failed to read output file: ${error instanceof Error ? error.message : String(error)}`,
+    )
   }
 }

package/engines/sqlite/index.ts

@@ -446,15 +446,17 @@ export class SQLiteEngine extends BaseEngine {
       throw new Error('sqlite3 not found')
     }
 
-    // Pipe .dump output to file (avoids shell injection)
-    await this.dumpToFile(sqlite3, filePath, outputPath)
+    try {
+      // Pipe .dump output to file (avoids shell injection)
+      await this.dumpToFile(sqlite3, filePath, outputPath)
 
-    // Clean up temp file if we downloaded it
-    if (tempFile && existsSync(tempFile)) {
-      await unlink(tempFile)
+      return { filePath: outputPath }
+    } finally {
+      // Clean up temp file if we downloaded it (even on error)
+      if (tempFile && existsSync(tempFile)) {
+        await unlink(tempFile)
+      }
     }
-
-    return { filePath: outputPath }
   }
 
   /**

package/engines/sqlite/registry.ts

@@ -4,57 +4,38 @@
  * 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 { readFile, writeFile, mkdir } from 'fs/promises'
-import { dirname } from 'path'
-import { paths } from '../../config/paths'
-import type { SQLiteRegistry, SQLiteRegistryEntry } from '../../types'
+import { configManager } from '../../core/config-manager'
+import type { SQLiteEngineRegistry, SQLiteRegistryEntry } from '../../types'
 
 /**
  * SQLite Registry Manager
- * Manages the JSON registry that tracks external SQLite database files
+ * Manages the registry that tracks external SQLite database files
+ * Data is stored in config.json under registry.sqlite
  */
 class SQLiteRegistryManager {
-  private registryPath: string
-
-  constructor() {
-    this.registryPath = paths.getSqliteRegistryPath()
-  }
-
   /**
-   * Load the registry from disk
-   * Returns an empty registry if the file doesn't exist
+   * Load the registry from config.json
+   * Returns an empty registry if none exists
    */
-  async load(): Promise<SQLiteRegistry> {
-    if (!existsSync(this.registryPath)) {
-      return { version: 1, entries: [] }
-    }
-    try {
-      const content = await readFile(this.registryPath, 'utf8')
-      return JSON.parse(content) as SQLiteRegistry
-    } catch {
-      // If file is corrupted, return empty registry
-      return { version: 1, entries: [] }
-    }
+  async load(): Promise<SQLiteEngineRegistry> {
+    return configManager.getSqliteRegistry()
   }
 
   /**
-   * Save the registry to disk
-   * Creates the parent directory if it doesn't exist
+   * Save the registry to config.json
    */
-  async save(registry: SQLiteRegistry): Promise<void> {
-    const dir = dirname(this.registryPath)
-    if (!existsSync(dir)) {
-      await mkdir(dir, { recursive: true })
-    }
-    await writeFile(this.registryPath, JSON.stringify(registry, null, 2))
+  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 already exists
+   * @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()
@@ -64,6 +45,13 @@ class SQLiteRegistryManager {
       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)
   }
@@ -179,6 +167,49 @@ class SQLiteRegistryManager {
     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

package/engines/sqlite/scanner.ts

@@ -0,0 +1,99 @@
+/**
+ * SQLite Scanner
+ *
+ * Scans directories for unregistered SQLite database files.
+ * Used to detect SQLite databases in the current working directory
+ * that are not yet registered with SpinDB.
+ */
+
+import { readdir } from 'fs/promises'
+import { existsSync } from 'fs'
+import { resolve } from 'path'
+import { sqliteRegistry } from './registry'
+
+export type UnregisteredFile = {
+  fileName: string
+  absolutePath: string
+}
+
+/**
+ * Scan a directory for unregistered SQLite files
+ * Returns files with .sqlite, .sqlite3, or .db extensions
+ * that are not already in the registry
+ *
+ * @param directory Directory to scan (defaults to CWD)
+ * @returns Array of unregistered SQLite files
+ */
+export async function scanForUnregisteredSqliteFiles(
+  directory: string = process.cwd(),
+): Promise<UnregisteredFile[]> {
+  const absoluteDir = resolve(directory)
+
+  // Check if folder is ignored
+  if (await sqliteRegistry.isFolderIgnored(absoluteDir)) {
+    return []
+  }
+
+  // Check if directory exists
+  if (!existsSync(absoluteDir)) {
+    return []
+  }
+
+  try {
+    // Get all files in directory
+    const entries = await readdir(absoluteDir, { withFileTypes: true })
+
+    // Filter for SQLite files
+    const sqliteFiles = entries
+      .filter((e) => e.isFile())
+      .filter((e) => /\.(sqlite3?|db)$/i.test(e.name))
+      .map((e) => ({
+        fileName: e.name,
+        absolutePath: resolve(absoluteDir, e.name),
+      }))
+
+    // Filter out already registered files
+    const unregistered: UnregisteredFile[] = []
+    for (const file of sqliteFiles) {
+      if (!(await sqliteRegistry.isPathRegistered(file.absolutePath))) {
+        unregistered.push(file)
+      }
+    }
+
+    return unregistered
+  } catch {
+    // If we can't read the directory, return empty
+    return []
+  }
+}
+
+/**
+ * Derive a valid container name from a filename
+ * Removes extension and converts to valid container name format:
+ * - Must start with a letter
+ * - Can contain letters, numbers, hyphens, underscores
+ *
+ * @param fileName The SQLite filename (e.g., "my-database.sqlite")
+ * @returns A valid container name (e.g., "my-database")
+ */
+export function deriveContainerName(fileName: string): string {
+  // Remove extension
+  const base = fileName.replace(/\.(sqlite3?|db)$/i, '')
+
+  // Convert to valid container name (alphanumeric, hyphens, underscores)
+  // Replace invalid chars with hyphens
+  let name = base.replace(/[^a-zA-Z0-9_-]/g, '-')
+
+  // Ensure starts with letter
+  if (!/^[a-zA-Z]/.test(name)) {
+    name = 'db-' + name
+  }
+
+  // Remove consecutive hyphens
+  name = name.replace(/-+/g, '-')
+
+  // Trim leading/trailing hyphens
+  name = name.replace(/^-+|-+$/g, '')
+
+  return name || 'sqlite-db'
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spindb",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "Spin up local database containers without Docker. A DBngin-like CLI for PostgreSQL and MySQL.",
   "type": "module",
   "bin": {
@@ -9,11 +9,12 @@
   "scripts": {
     "start": "tsx cli/bin.ts",
     "dev": "tsx watch cli/bin.ts",
-    "test": "pnpm test:pg && pnpm test:mysql",
+    "test": "pnpm test:pg && pnpm test:mysql && pnpm test:sqlite",
     "test:pg": "node --import tsx --test tests/integration/postgresql.test.ts",
     "test:mysql": "node --import tsx --test tests/integration/mysql.test.ts",
+    "test:sqlite": "node --import tsx --test tests/integration/sqlite.test.ts",
     "test:unit": "node --import tsx --test tests/unit/*.test.ts",
-    "test:integration": "pnpm test:pg && pnpm test:mysql",
+    "test:integration": "pnpm test:pg && pnpm test:mysql && pnpm test:sqlite",
     "test:all": "pnpm test:unit && pnpm test:integration",
     "format": "prettier --write .",
     "lint": "tsc --noEmit && eslint .",

package/types/index.ts

@@ -149,6 +149,8 @@ export type SpinDBConfig = {
     litecli?: BinaryConfig
     usql?: BinaryConfig
   }
+  // Engine registries (for file-based databases like SQLite)
+  registry?: EngineRegistries
   // Default settings
   defaults?: {
     engine?: Engine
@@ -177,7 +179,25 @@ export type SQLiteRegistryEntry = {
 }
 
 /**
- * SQLite registry stored at ~/.spindb/sqlite-registry.json
+ * SQLite engine registry stored in config.json under registry.sqlite
+ * Includes entries and folder ignore list for CWD scanning
+ */
+export type SQLiteEngineRegistry = {
+  version: 1
+  entries: SQLiteRegistryEntry[]
+  ignoreFolders: Record<string, true> // O(1) lookup for ignored folders
+}
+
+/**
+ * Engine registries stored in config.json
+ * Currently only SQLite uses this (file-based databases)
+ */
+export type EngineRegistries = {
+  sqlite?: SQLiteEngineRegistry
+}
+
+/**
+ * @deprecated Use SQLiteEngineRegistry instead - now stored in config.json
  */
 export type SQLiteRegistry = {
   version: 1