spindb 0.11.2 → 0.12.3

package/README.md

@@ -7,7 +7,7 @@
 
 **The first npm CLI for running local databases without Docker.**
 
-Spin up PostgreSQL, MySQL, and SQLite instances for local development. No Docker daemon, no container networking, no volume mounts. Just databases running on localhost, ready in seconds.
+Spin up PostgreSQL, MySQL, SQLite, and MongoDB instances for local development. No Docker daemon, no container networking, no volume mounts. Just databases running on localhost, ready in seconds.
 
 ---
 
@@ -210,12 +210,50 @@ spindb connect mydb --litecli
 
 **Note:** Unlike server databases, SQLite databases don't need to be "started" or "stopped"—they're always available as long as the file exists.
 
+#### MongoDB
+
+| | |
+|---|---|
+| Versions | 6.0, 7.0, 8.0 |
+| Default port | 27017 |
+| Default user | None (no auth by default) |
+| Binary source | System installation |
+
+Like MySQL, SpinDB uses your system's MongoDB installation. MongoDB binaries aren't available as a single cross-platform download, so you'll need to install MongoDB via your package manager.
+
+```bash
+# macOS
+brew tap mongodb/brew
+brew install mongodb-community mongosh mongodb-database-tools
+
+# Ubuntu/Debian (follow MongoDB's official guide)
+# https://www.mongodb.com/docs/manual/tutorial/install-mongodb-on-ubuntu/
+
+# Windows (Chocolatey)
+choco install mongodb mongodb-shell mongodb-database-tools
+
+# Check if SpinDB can find MongoDB
+spindb deps check --engine mongodb
+```
+
+MongoDB uses JavaScript for queries instead of SQL. When using `spindb run`, pass JavaScript code:
+
+```bash
+# Insert a document
+spindb run mydb --sql "db.users.insertOne({name: 'Alice', email: 'alice@example.com'})"
+
+# Query documents
+spindb run mydb --sql "db.users.find().pretty()"
+
+# Run a JavaScript file
+spindb run mydb --file ./scripts/seed.js
+```
+
 ### Planned Engines
 
 | Engine | Type | Status |
 |--------|------|--------|
 | Redis | In-memory key-value | Planned for v1.2 |
-| MongoDB | Document database | Planned for v1.2 |
 
 ---
 
@@ -317,12 +355,16 @@ spindb connect mydb --install-mycli
 spindb connect mydb --install-tui
 ```
 
-#### `run` - Execute SQL
+#### `run` - Execute SQL/scripts
 
 ```bash
 spindb run mydb script.sql                    # Run a SQL file
 spindb run mydb --sql "SELECT * FROM users"   # Run inline SQL
 spindb run mydb seed.sql --database my_app    # Target specific database
+
+# MongoDB uses JavaScript instead of SQL
+spindb run mydb seed.js                                    # Run a JavaScript file
+spindb run mydb --sql "db.users.find().pretty()"           # Run inline JavaScript
 ```
 
 #### `url` - Get connection string
@@ -553,8 +595,8 @@ SpinDB supports enhanced database shells that provide features like auto-complet
 | PostgreSQL | `psql` | `pgcli` | `usql` |
 | MySQL | `mysql` | `mycli` | `usql` |
 | SQLite | `sqlite3` | `litecli` | `usql` |
+| MongoDB | `mongosh` | - | `usql` |
 | Redis (planned) | `redis-cli` | `iredis` | - |
-| MongoDB (planned) | `mongosh` | - | - |
 
 **pgcli / mycli** provide:
 - Intelligent auto-completion (tables, columns, keywords)
@@ -587,7 +629,7 @@ SpinDB uses the term "container" loosely—there's no Docker involved. When you
 Each "container" is just:
 - A configuration file (`container.json`)
 - A data directory (`data/`)
-- A log file (`postgres.log` or `mysql.log`)
+- A log file (`postgres.log`, `mysql.log`, or `mongodb.log`)
 
 Native processes mean instant startup and no virtualization overhead.
 

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

@@ -57,8 +57,6 @@ export async function handleCreate(): Promise<'main' | void> {
   let selectedEngine: string | null = null
   let selectedVersion: string | null = null
   let containerName: string | null = null
-  let selectedPort: number | null = null
-  let selectedDatabase: string | null = null
   let sqlitePath: string | undefined = undefined
 
   // Step 1: Engine selection (back returns to main menu)
@@ -71,7 +69,6 @@ export async function handleCreate(): Promise<'main' | void> {
 
   // Step 2: Version selection (back returns to engine)
   while (selectedVersion === null) {
-    // selectedEngine is guaranteed non-null here (loop doesn't exit until it's set)
     const result = await promptVersion(selectedEngine!, { includeBack: true })
     if (result === MAIN_MENU_VALUE) return 'main'
     if (result === BACK_VALUE) {
@@ -91,49 +88,28 @@ export async function handleCreate(): Promise<'main' | void> {
     containerName = result
   }
 
-  // Step 4: Database name (back returns to container name)
-  while (selectedDatabase === null) {
-    // containerName and selectedEngine are guaranteed non-null here
-    const result = await promptDatabaseName(containerName!, selectedEngine!, {
-      allowBack: true,
-    })
-    if (result === null) {
-      containerName = null
-      continue
-    }
-    selectedDatabase = result
-  }
+  // At this point, all wizard values are guaranteed to be set
+  const engine = selectedEngine!
+  const version = selectedVersion!
+  const name = containerName!
+
+  // Step 4: Database name (defaults to container name, sanitized)
+  const database = await promptDatabaseName(name, engine)
 
-  // Step 5: Port or SQLite path (back returns to database name)
-  const isSQLite = selectedEngine === 'sqlite'
+  // Step 5: Port or SQLite path
+  const isSQLite = engine === 'sqlite'
+  let port: number
   if (isSQLite) {
     // SQLite doesn't need a port, but needs a path
-    // containerName is guaranteed non-null here
-    sqlitePath = await promptSqlitePath(containerName!)
-    // promptSqlitePath doesn't support back yet, but file path is optional
-    selectedPort = 0
+    sqlitePath = await promptSqlitePath(name)
+    port = 0
   } else {
-    while (selectedPort === null) {
-      // selectedEngine is guaranteed non-null here
-      const engineDefaults = getEngineDefaults(selectedEngine!)
-      const result = await promptPort(engineDefaults.defaultPort, {
-        allowBack: true,
-      })
-      if (result === null) {
-        selectedDatabase = null
-        continue
-      }
-      selectedPort = result
-    }
+    const engineDefaults = getEngineDefaults(engine)
+    port = await promptPort(engineDefaults.defaultPort)
   }
 
   // Now we have all values - proceed with container creation
-  // At this point, all values are guaranteed to be set (wizard doesn't exit until they are)
-  const engine = selectedEngine!
-  const version = selectedVersion!
-  const port = selectedPort!
-  const database = selectedDatabase!
-  let containerNameFinal = containerName!
+  let containerNameFinal = name
 
   console.log()
   console.log(header('Creating Database Container'))
@@ -186,6 +162,13 @@ export async function handleCreate(): Promise<'main' | void> {
     )
 
     if (!installed) {
+      console.log()
+      console.log(
+        uiWarning(
+          'Container creation cancelled - required tools not installed.',
+        ),
+      )
+      await pressEnterToContinue()
       return
     }
 
@@ -196,6 +179,7 @@ export async function handleCreate(): Promise<'main' | void> {
           `Still missing tools: ${missingDeps.map((d) => d.name).join(', ')}`,
         ),
       )
+      await pressEnterToContinue()
       return
     }
 
@@ -615,12 +599,15 @@ export async function showContainerSubmenu(
         : 'Start container first',
   })
 
-  // Run SQL - always enabled for SQLite (if file exists), server databases need to be running
+  // Run SQL/script - always enabled for SQLite (if file exists), server databases need to be running
   const canRunSql = isSQLite ? existsSync(config.database) : isRunning
+  // MongoDB uses JavaScript scripts, not SQL
+  const runScriptLabel =
+    config.engine === 'mongodb' ? 'Run script file' : 'Run SQL file'
   actionChoices.push({
     name: canRunSql
-      ? `${chalk.yellow('▷')} Run SQL file`
-      : chalk.gray('▷ Run SQL file'),
+      ? `${chalk.yellow('▷')} ${runScriptLabel}`
+      : chalk.gray(`▷ ${runScriptLabel}`),
     value: 'run-sql',
     disabled: canRunSql
       ? false

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

@@ -95,10 +95,10 @@ export async function handleOpenShell(containerName: string): Promise<void> {
 
   // Engine-specific shell names
   let defaultShellName: string
-  let engineSpecificCli: string
+  let engineSpecificCli: string | null
   let engineSpecificInstalled: boolean
-  let engineSpecificValue: ShellChoice
-  let engineSpecificInstallValue: ShellChoice
+  let engineSpecificValue: ShellChoice | null
+  let engineSpecificInstallValue: ShellChoice | null
 
   if (config.engine === 'sqlite') {
     defaultShellName = 'sqlite3'
@@ -112,6 +112,13 @@ export async function handleOpenShell(containerName: string): Promise<void> {
     engineSpecificInstalled = mycliInstalled
     engineSpecificValue = 'mycli'
     engineSpecificInstallValue = 'install-mycli'
+  } else if (config.engine === 'mongodb') {
+    defaultShellName = 'mongosh'
+    // mongosh IS the enhanced shell for MongoDB (no separate enhanced CLI like pgcli/mycli)
+    engineSpecificCli = null
+    engineSpecificInstalled = false
+    engineSpecificValue = null
+    engineSpecificInstallValue = null
   } else {
     defaultShellName = 'psql'
     engineSpecificCli = 'pgcli'
@@ -129,16 +136,19 @@ export async function handleOpenShell(containerName: string): Promise<void> {
     },
   ]
 
-  if (engineSpecificInstalled) {
-    choices.push({
-      name: `⚡ Use ${engineSpecificCli} (enhanced features, recommended)`,
-      value: engineSpecificValue,
-    })
-  } else {
-    choices.push({
-      name: `↓ Install ${engineSpecificCli} (enhanced features, recommended)`,
-      value: engineSpecificInstallValue,
-    })
+  // Only show engine-specific CLI option if one exists (MongoDB's mongosh IS the default)
+  if (engineSpecificCli !== null) {
+    if (engineSpecificInstalled) {
+      choices.push({
+        name: `⚡ Use ${engineSpecificCli} (enhanced features, recommended)`,
+        value: engineSpecificValue!,
+      })
+    } else {
+      choices.push({
+        name: `↓ Install ${engineSpecificCli} (enhanced features, recommended)`,
+        value: engineSpecificInstallValue!,
+      })
+    }
   }
 
   // usql supports SQLite too
@@ -367,6 +377,10 @@ async function launchShell(
       config.database,
     ]
     installHint = 'brew install mysql-client'
+  } else if (config.engine === 'mongodb') {
+    shellCmd = 'mongosh'
+    shellArgs = [connectionString]
+    installHint = 'brew install mongosh'
   } else {
     shellCmd = 'psql'
     shellArgs = [connectionString]

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

@@ -56,6 +56,11 @@ export async function handleRunSql(containerName: string): Promise<void> {
   // Strip quotes that terminals add when drag-and-dropping files
   const stripQuotes = (path: string) => path.replace(/^['"]|['"]$/g, '').trim()
 
+  // MongoDB uses JavaScript scripts, not SQL
+  const isMongoDB = config.engine === 'mongodb'
+  const scriptType = isMongoDB ? 'Script' : 'SQL'
+  const scriptTypeLower = isMongoDB ? 'script' : 'SQL'
+
   // Prompt for file path (empty input = go back)
   console.log(
     chalk.gray(
@@ -68,7 +73,7 @@ export async function handleRunSql(containerName: string): Promise<void> {
     {
       type: 'input',
       name: 'filePath',
-      message: 'SQL file path:',
+      message: `${scriptType} file path:`,
       validate: (input: string) => {
         if (!input) return true // Empty = go back
         const cleanPath = stripQuotes(input)
@@ -90,14 +95,16 @@ export async function handleRunSql(containerName: string): Promise<void> {
   if (databases.length > 1) {
     databaseName = await promptDatabaseSelect(
       databases,
-      'Select database to run SQL against:',
+      `Select database to run ${scriptTypeLower} against:`,
     )
   } else {
     databaseName = databases[0]
   }
 
   console.log()
-  console.log(uiInfo(`Running SQL file against "${databaseName}"...`))
+  console.log(
+    uiInfo(`Running ${scriptTypeLower} file against "${databaseName}"...`),
+  )
   console.log()
 
   try {
@@ -106,11 +113,11 @@ export async function handleRunSql(containerName: string): Promise<void> {
       database: databaseName,
     })
     console.log()
-    console.log(uiSuccess('SQL file executed successfully'))
+    console.log(uiSuccess(`${scriptType} file executed successfully`))
   } catch (error) {
     const e = error as Error
     console.log()
-    console.log(uiError(`SQL execution failed: ${e.message}`))
+    console.log(uiError(`${scriptType} execution failed: ${e.message}`))
   }
 
   console.log()

package/cli/ui/prompts.ts

@@ -38,15 +38,11 @@ export async function promptContainerName(
   defaultName?: string,
   options?: { allowBack?: boolean },
 ): Promise<string | null> {
-  const message = options?.allowBack
-    ? 'Container name (empty to go back):'
-    : 'Container name:'
-
   const { name } = await inquirer.prompt<{ name: string }>([
     {
       type: 'input',
       name: 'name',
-      message,
+      message: 'Container name:',
       default: options?.allowBack ? undefined : defaultName,
       validate: (input: string) => {
         if (options?.allowBack && !input) return true // Allow empty for back
@@ -237,41 +233,28 @@ export async function promptVersion(
 /**
  * Prompt for port
  * @param defaultPort - Default port number
- * @param options.allowBack - Allow empty input to go back (returns null)
  */
-export function promptPort(
-  defaultPort?: number,
-  options?: { allowBack?: false },
-): Promise<number>
-export function promptPort(
-  defaultPort: number | undefined,
-  options: { allowBack: true },
-): Promise<number | null>
 export async function promptPort(
   defaultPort: number = defaults.port,
-  options?: { allowBack?: boolean },
-): Promise<number | null> {
-  const message = options?.allowBack ? 'Port (empty to go back):' : 'Port:'
-
-  const { port } = await inquirer.prompt<{ port: string }>([
+): Promise<number> {
+  const { port } = await inquirer.prompt<{ port: number }>([
     {
       type: 'input',
       name: 'port',
-      message,
-      default: options?.allowBack ? undefined : String(defaultPort),
+      message: 'Port:',
+      default: String(defaultPort),
       validate: (input: string) => {
-        if (options?.allowBack && !input) return true // Allow empty for back
         const num = parseInt(input, 10)
         if (isNaN(num) || num < 1 || num > 65535) {
           return 'Port must be a number between 1 and 65535'
         }
         return true
       },
+      filter: (input: string) => parseInt(input, 10),
     },
   ])
 
-  if (options?.allowBack && !port) return null
-  return parseInt(port, 10)
+  return port
 }
 
 /**
@@ -405,15 +388,18 @@ export async function promptDatabaseName(
   // MySQL uses "schema" terminology (database and schema are synonymous)
   const baseLabel =
     engine === 'mysql' ? 'Database (schema) name' : 'Database name'
-  const label = options?.allowBack
-    ? `${baseLabel} (empty to go back):`
-    : `${baseLabel}:`
 
   // Sanitize the default name to ensure it's valid
   const sanitizedDefault = defaultName
     ? sanitizeDatabaseName(defaultName)
     : undefined
 
+  // When allowBack is true, show the default in the message (since we can't use inquirer's default)
+  const label =
+    options?.allowBack && sanitizedDefault
+      ? `${baseLabel} [${sanitizedDefault}]:`
+      : `${baseLabel}:`
+
   const { database } = await inquirer.prompt<{ database: string }>([
     {
       type: 'input',
@@ -570,9 +556,10 @@ export async function promptBackupFilename(
   defaultName: string,
   options?: { allowBack?: boolean },
 ): Promise<string | null> {
+  // Show the default in the message when allowBack is true
   const message = options?.allowBack
-    ? 'Backup filename (without extension, empty to go back):'
-    : 'Backup filename (without extension):'
+    ? `Backup filename [${defaultName}]:`
+    : 'Backup filename:'
 
   const { filename } = await inquirer.prompt<{ filename: string }>([
     {

package/config/engine-defaults.ts

@@ -73,6 +73,20 @@ export const engineDefaults: Record<string, EngineDefaults> = {
     clientTools: ['sqlite3'],
     maxConnections: 0, // N/A - file-based
   },
+  mongodb: {
+    defaultVersion: '8.0',
+    defaultPort: 27017,
+    portRange: { start: 27017, end: 27100 },
+    supportedVersions: ['6.0', '7.0', '8.0'],
+    latestVersion: '8.0',
+    superuser: '', // No auth by default for local dev
+    connectionScheme: 'mongodb',
+    logFileName: 'mongodb.log',
+    pidFileName: 'mongod.pid',
+    dataSubdir: 'data',
+    clientTools: ['mongosh', 'mongodump', 'mongorestore'],
+    maxConnections: 0, // Not applicable for MongoDB
+  },
 }
 
 /**

package/config/os-dependencies.ts

@@ -411,6 +411,122 @@ const sqliteDependencies: EngineDependencies = {
   ],
 }
 
+// =============================================================================
+// MongoDB Dependencies
+// =============================================================================
+
+const mongodbDependencies: EngineDependencies = {
+  engine: 'mongodb',
+  displayName: 'MongoDB',
+  dependencies: [
+    {
+      name: 'mongod',
+      binary: 'mongod',
+      description: 'MongoDB server daemon',
+      packages: {
+        brew: {
+          package: 'mongodb/brew/mongodb-community',
+          preInstall: ['brew tap mongodb/brew'],
+        },
+        // MongoDB requires their own apt repository, not available in default repos
+        choco: { package: 'mongodb' },
+        winget: { package: 'MongoDB.Server' },
+        scoop: { package: 'mongodb' },
+      },
+      manualInstall: {
+        darwin: [
+          'Install Homebrew: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"',
+          'Add MongoDB tap: brew tap mongodb/brew',
+          'Then run: brew install mongodb-community',
+          'For specific versions: brew install mongodb-community@7.0',
+        ],
+        linux: [
+          'MongoDB requires adding their official repository.',
+          'Ubuntu/Debian: Follow https://www.mongodb.com/docs/manual/tutorial/install-mongodb-on-ubuntu/',
+          'RHEL/CentOS: Follow https://www.mongodb.com/docs/manual/tutorial/install-mongodb-on-red-hat/',
+        ],
+        win32: [
+          'Using Chocolatey: choco install mongodb',
+          'Using winget: winget install MongoDB.Server',
+          'Or download from: https://www.mongodb.com/try/download/community',
+        ],
+      },
+    },
+    {
+      name: 'mongosh',
+      binary: 'mongosh',
+      description: 'MongoDB Shell (modern interactive shell)',
+      packages: {
+        brew: { package: 'mongosh' },
+        choco: { package: 'mongodb-shell' },
+        winget: { package: 'MongoDB.Shell' },
+        scoop: { package: 'mongosh' },
+      },
+      manualInstall: {
+        darwin: [
+          'Install with Homebrew: brew install mongosh',
+          'Or download from: https://www.mongodb.com/try/download/shell',
+        ],
+        linux: [
+          'Download from: https://www.mongodb.com/try/download/shell',
+          'Or install via npm: npm install -g mongosh',
+        ],
+        win32: [
+          'Using Chocolatey: choco install mongodb-shell',
+          'Using winget: winget install MongoDB.Shell',
+          'Or download from: https://www.mongodb.com/try/download/shell',
+        ],
+      },
+    },
+    {
+      name: 'mongodump',
+      binary: 'mongodump',
+      description: 'MongoDB database backup utility',
+      packages: {
+        brew: { package: 'mongodb-database-tools' },
+        choco: { package: 'mongodb-database-tools' },
+      },
+      manualInstall: {
+        darwin: [
+          'Install with Homebrew: brew install mongodb-database-tools',
+          'Or download from: https://www.mongodb.com/try/download/database-tools',
+        ],
+        linux: [
+          'Download from: https://www.mongodb.com/try/download/database-tools',
+          'Extract and add to PATH',
+        ],
+        win32: [
+          'Using Chocolatey: choco install mongodb-database-tools',
+          'Or download from: https://www.mongodb.com/try/download/database-tools',
+        ],
+      },
+    },
+    {
+      name: 'mongorestore',
+      binary: 'mongorestore',
+      description: 'MongoDB database restore utility',
+      packages: {
+        brew: { package: 'mongodb-database-tools' },
+        choco: { package: 'mongodb-database-tools' },
+      },
+      manualInstall: {
+        darwin: [
+          'Install with Homebrew: brew install mongodb-database-tools',
+          'Or download from: https://www.mongodb.com/try/download/database-tools',
+        ],
+        linux: [
+          'Download from: https://www.mongodb.com/try/download/database-tools',
+          'Extract and add to PATH',
+        ],
+        win32: [
+          'Using Chocolatey: choco install mongodb-database-tools',
+          'Or download from: https://www.mongodb.com/try/download/database-tools',
+        ],
+      },
+    },
+  ],
+}
+
 // =============================================================================
 // Optional Tools (engine-agnostic)
 // =============================================================================
@@ -543,6 +659,7 @@ export const engineDependencies: EngineDependencies[] = [
   postgresqlDependencies,
   mysqlDependencies,
   sqliteDependencies,
+  mongodbDependencies,
 ]
 
 /**

package/core/homebrew-version-manager.ts

@@ -321,10 +321,13 @@ async function switchVersionLinux(
   }
 
   // No action required - Linux uses versioned paths directly, no symlink switching needed
-  logDebug('Linux: Version verified, no switching required (using direct path)', {
-    version: targetMajor,
-    binPath: target.binPath,
-  })
+  logDebug(
+    'Linux: Version verified, no switching required (using direct path)',
+    {
+      version: targetMajor,
+      binPath: target.binPath,
+    },
+  )
 
   return {
     success: true,

package/engines/base-engine.ts

@@ -105,6 +105,15 @@ export abstract class BaseEngine {
     throw new Error('mysqladmin not found')
   }
 
+  /**
+   * Get the path to the mongosh client if available
+   * Default implementation throws; engines that can provide a bundled or
+   * configured mongosh should override this method.
+   */
+  async getMongoshPath(): Promise<string> {
+    throw new Error('mongosh not found')
+  }
+
   /**
    * Open an interactive shell/CLI connection
    */

package/engines/index.ts

@@ -1,6 +1,7 @@
 import { postgresqlEngine } from './postgresql'
 import { mysqlEngine } from './mysql'
 import { sqliteEngine } from './sqlite'
+import { mongodbEngine } from './mongodb'
 import type { BaseEngine } from './base-engine'
 import type { EngineInfo } from '../types'
 
@@ -18,6 +19,9 @@ export const engines: Record<string, BaseEngine> = {
   // SQLite and aliases
   sqlite: sqliteEngine,
   lite: sqliteEngine,
+  // MongoDB and aliases
+  mongodb: mongodbEngine,
+  mongo: mongodbEngine,
 }
 
 /**