spindb 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,20 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(lsof:*)",
+      "Bash(npm view:*)",
+      "Bash(pnpm install:*)",
+      "Bash(pnpm run start --help:*)",
+      "Bash(pnpm run start:*)",
+      "Bash(curl:*)",
+      "Bash(psql:*)",
+      "Bash(chmod:*)",
+      "Bash(node bin/cli.js:*)",
+      "Bash(pnpm add:*)",
+      "Bash(pnpm run format:*)",
+      "Bash(pnpm run lint:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/.env.example

@@ -0,0 +1 @@
+# No environment variables needed for this project

package/.prettierignore

@@ -0,0 +1,4 @@
+*.md
+dist/
+node_modules/
+pnpm-lock.yaml

package/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "printWidth": 80,
+  "semi": false,
+  "singleQuote": true,
+  "trailingComma": "all"
+}

package/CLAUDE.md

@@ -0,0 +1,162 @@
+# CLAUDE.md - Project Context for Claude Code
+
+## Project Overview
+
+SpinDB is a CLI tool for running local PostgreSQL databases without Docker. It's a lightweight alternative to DBngin, downloading and managing PostgreSQL binaries directly.
+
+## Tech Stack
+
+- **Runtime**: Node.js 18+ with TypeScript
+- **Execution**: `tsx` for direct TypeScript execution (no build step for dev)
+- **Package Manager**: pnpm (strictly - not npm/yarn)
+- **CLI Framework**: Commander.js
+- **Interactive UI**: Inquirer.js (prompts), Chalk (colors), Ora (spinners)
+- **Module System**: ESM (`"type": "module"`)
+- **Path Aliases**: `@/*` maps to `./src/*`
+
+## Project Structure
+
+```
+src/
+├── bin/cli.ts              # Entry point (#!/usr/bin/env tsx)
+├── cli/
+│   ├── index.ts            # Commander setup, routes to commands
+│   ├── commands/           # CLI commands (create, start, stop, etc.)
+│   │   ├── menu.ts         # Interactive arrow-key menu (default when no args)
+│   │   └── config.ts       # Binary path configuration
+│   └── ui/
+│       ├── prompts.ts      # Inquirer prompts
+│       ├── spinner.ts      # Ora spinner helpers
+│       └── theme.ts        # Chalk color theme
+├── core/
+│   ├── binary-manager.ts   # Downloads PostgreSQL from zonky.io
+│   ├── config-manager.ts   # Manages ~/.spindb/config.json
+│   ├── container-manager.ts # CRUD for containers
+│   ├── port-manager.ts     # Port availability checking
+│   └── process-manager.ts  # pg_ctl start/stop wrapper
+├── config/
+│   ├── paths.ts            # ~/.spindb/ path definitions
+│   └── defaults.ts         # Default values, platform mappings
+├── engines/
+│   ├── base-engine.ts      # Abstract base class
+│   ├── index.ts            # Engine registry
+│   └── postgresql/
+│       ├── index.ts        # PostgreSQL engine implementation
+│       ├── binary-urls.ts  # Zonky.io URL builder
+│       └── restore.ts      # Backup detection and restore
+└── types/index.ts          # TypeScript interfaces
+```
+
+## Key Architecture Decisions
+
+### Binary Source
+PostgreSQL server binaries come from [zonky.io](https://github.com/zonkyio/embedded-postgres-binaries) (Maven Central). These only include server binaries (postgres, pg_ctl, initdb), NOT client tools (psql, pg_dump, pg_restore).
+
+**Download flow:**
+1. Download JAR from Maven Central
+2. Unzip JAR (it's a ZIP file)
+3. Extract `.txz` file inside
+4. Extract tar.xz to `~/.spindb/bin/postgresql-{version}-{platform}-{arch}/`
+
+### Client Tools
+Client tools (psql, pg_restore) are detected from the system. The `config-manager.ts` handles:
+- Auto-detection from PATH and common locations
+- Caching paths in `~/.spindb/config.json`
+- Manual override via `spindb config set`
+
+### Data Storage
+```
+~/.spindb/
+├── bin/                      # Downloaded PostgreSQL binaries
+├── containers/{name}/
+│   ├── container.json        # Container metadata
+│   ├── data/                 # PostgreSQL data directory
+│   └── postgres.log          # Server logs
+└── config.json               # Tool paths, settings
+```
+
+### Interactive Menu
+When `spindb` is run with no arguments, it shows an interactive menu (`src/cli/commands/menu.ts`) using Inquirer's list prompt. Users navigate with arrow keys.
+
+## Common Tasks
+
+### Running the CLI
+```bash
+pnpm run start              # Opens interactive menu
+pnpm run start create mydb  # Run specific command
+pnpm run start --help       # Show help
+```
+
+### Testing Changes
+No test suite yet. Manual testing:
+```bash
+pnpm run start create testdb -p 5433
+pnpm run start list
+pnpm run start connect testdb
+pnpm run start delete testdb --force --yes
+```
+
+### Adding a New Command
+1. Create `src/cli/commands/{name}.ts`
+2. Export a Commander `Command` instance
+3. Import and add to `src/cli/index.ts`
+4. Optionally add to interactive menu in `src/cli/commands/menu.ts`
+
+## Important Implementation Details
+
+### Platform Detection
+```typescript
+import { platform, arch } from 'os';
+// platform() returns 'darwin' | 'linux'
+// arch() returns 'arm64' | 'x64'
+// Mapped to zonky.io names in defaults.ts platformMappings
+```
+
+### Version Mapping
+Major versions (14, 15, 16, 17) map to full versions in `src/engines/postgresql/binary-urls.ts`:
+```typescript
+const VERSION_MAP = {
+  '14': '14.15.0',
+  '15': '15.10.0',
+  '16': '16.6.0',
+  '17': '17.2.0'
+};
+```
+
+### Port Management
+- Default port: 5432
+- If busy, scans 5432-5500 for available port
+- Uses `net.createServer()` to test availability
+
+### Process Management
+Uses `pg_ctl` for start/stop:
+```bash
+pg_ctl start -D {dataDir} -l {logFile} -w -o "-p {port}"
+pg_ctl stop -D {dataDir} -m fast -w
+```
+
+PID file location: `~/.spindb/containers/{name}/data/postmaster.pid`
+
+## Known Limitations
+
+1. **No client tools bundled** - psql/pg_restore must be installed separately
+2. **macOS/Linux only** - No Windows support (zonky.io doesn't provide Windows binaries)
+3. **No backup command** - pg_dump must be run manually with system tools
+4. **No automatic updates** - Binary versions are hardcoded in VERSION_MAP
+
+## Future Improvements (Not Implemented)
+
+- [ ] Add `spindb backup` command (wrapper around pg_dump)
+- [ ] Support MySQL/SQLite engines (architecture supports it)
+- [ ] Add `spindb logs` command to tail postgres.log
+- [ ] Add `spindb exec` for running SQL files
+- [ ] Automatic binary version updates
+- [ ] Windows support (would need different binary source)
+
+## Code Style Notes
+
+- No `.js` extensions in imports
+- Use `@/` path alias for all internal imports
+- Prefer `async/await` over callbacks
+- Use Ora spinners for long-running operations
+- Error messages should include actionable fix suggestions

package/README.md

@@ -0,0 +1,204 @@
+# SpinDB
+
+Spin up local PostgreSQL databases without Docker. A lightweight alternative to DBngin.
+
+## Features
+
+- **No Docker required** - Downloads and runs PostgreSQL binaries directly
+- **Multiple containers** - Run multiple isolated PostgreSQL instances on different ports
+- **Interactive menu** - Arrow-key navigation for all operations
+- **Auto port management** - Automatically finds available ports
+- **Clone containers** - Duplicate databases with all data
+- **Backup restore** - Restore pg_dump backups (requires system PostgreSQL client tools)
+
+## Installation
+
+```bash
+# Run directly with pnpx (no install needed)
+pnpx spindb
+
+# Or install globally
+pnpm add -g spindb
+```
+
+## Quick Start
+
+```bash
+# Launch interactive menu
+spindb
+
+# Or use commands directly
+spindb create mydb
+spindb list
+spindb connect mydb
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `spindb` | Open interactive menu |
+| `spindb create [name]` | Create a new database container |
+| `spindb list` | List all containers |
+| `spindb start [name]` | Start a container |
+| `spindb stop [name]` | Stop a container |
+| `spindb connect [name]` | Connect with psql |
+| `spindb restore [name] [backup]` | Restore a backup file |
+| `spindb clone [source] [target]` | Clone a container |
+| `spindb delete [name]` | Delete a container |
+| `spindb config show` | Show configuration |
+| `spindb config detect` | Auto-detect PostgreSQL tools |
+
+## How It Works
+
+SpinDB downloads pre-built PostgreSQL binaries from [zonky.io](https://github.com/zonkyio/embedded-postgres-binaries) on first use. These are the same binaries used by embedded-postgres for Java testing.
+
+Data is stored in `~/.spindb/`:
+```
+~/.spindb/
+├── bin/                    # PostgreSQL server binaries
+│   └── postgresql-16-darwin-arm64/
+├── containers/             # Container data
+│   └── mydb/
+│       ├── container.json  # Container config
+│       ├── data/           # PostgreSQL data directory
+│       └── postgres.log    # Server logs
+└── config.json             # SpinDB configuration
+```
+
+## PostgreSQL Client Tools
+
+SpinDB bundles the PostgreSQL **server** (postgres, pg_ctl, initdb) but not client tools (psql, pg_dump, pg_restore). For `connect` and `restore` commands, you need PostgreSQL client tools installed:
+
+```bash
+# macOS (Homebrew)
+brew install libpq
+brew link --force libpq
+
+# Ubuntu/Debian
+apt install postgresql-client
+
+# Or use Postgres.app (macOS)
+# Client tools are automatically detected
+```
+
+SpinDB auto-detects installed tools. Check what's configured:
+
+```bash
+spindb config show
+```
+
+Manually configure tool paths:
+
+```bash
+spindb config set psql /path/to/psql
+spindb config set pg_restore /path/to/pg_restore
+```
+
+## Supported Platforms
+
+- macOS (Apple Silicon & Intel)
+- Linux (x64 & ARM64)
+
+## Supported PostgreSQL Versions
+
+- PostgreSQL 14
+- PostgreSQL 15
+- PostgreSQL 16
+- PostgreSQL 17
+
+## Examples
+
+### Create a database with specific version
+
+```bash
+spindb create mydb --pg-version 15 --port 5433
+```
+
+### Restore a backup
+
+```bash
+# Start the container first
+spindb start mydb
+
+# Restore (supports .sql, custom format, and tar format)
+spindb restore mydb ./backup.dump -d myapp
+```
+
+### Clone for testing
+
+```bash
+# Stop the source container
+spindb stop production-copy
+
+# Clone it
+spindb clone production-copy test-branch
+
+# Start the clone
+spindb start test-branch
+```
+
+### Connect and run queries
+
+```bash
+# Interactive psql session
+spindb connect mydb
+
+# Or use the connection string directly
+psql postgresql://postgres@localhost:5432/postgres
+```
+
+## Configuration
+
+Configuration is stored in `~/.spindb/config.json`. You can edit it directly or use the `config` commands:
+
+```bash
+# Show all config
+spindb config show
+
+# Re-detect system tools
+spindb config detect
+
+# Set custom binary path
+spindb config set psql /usr/local/bin/psql
+
+# Get path for scripting
+spindb config path psql
+```
+
+## Troubleshooting
+
+### Port already in use
+
+SpinDB automatically finds an available port if the default (5432) is in use. You can also specify a port:
+
+```bash
+spindb create mydb --port 5433
+```
+
+### psql not found
+
+Install PostgreSQL client tools (see above) or configure the path manually:
+
+```bash
+spindb config set psql /path/to/psql
+```
+
+### Container won't start
+
+Check the logs:
+
+```bash
+cat ~/.spindb/containers/mydb/postgres.log
+```
+
+### Reset everything
+
+```bash
+rm -rf ~/.spindb
+```
+
+## License
+
+MIT
+# spindb

package/TODO.md

@@ -0,0 +1,66 @@
+# SpinDB TODO
+
+## Monetization Model
+
+Similar to ngrok - free tier for individual developers with core functionality, paid tiers for power users and teams.
+
+- **Free**: Full local dev experience, unlimited containers, basic backup/restore
+- **Pro** ($X/month): Security features, multi-engine support, advanced features
+- **Team** ($X/user/month): Shared configs, team collaboration, priority support
+
+## Free Features
+
+### High Priority
+- [ ] **Run SQL file** - Add menu option to run a `.sql` file against a container (wrapper around `psql -f`)
+- [ ] **Backup command** - Add `spindb backup` to create dumps using `pg_dump`
+- [ ] **Logs command** - Add `spindb logs <container>` to tail `postgres.log`
+- [ ] **Engine/binary management** - Menu to list installed PostgreSQL versions, install new versions, uninstall unused versions (free up disk space)
+
+### Medium Priority
+- [ ] **Container rename** - Rename a container without cloning/deleting
+- [ ] **Export connection string** - Copy connection string to clipboard
+- [ ] **Multiple databases per container** - List/create/delete databases within a container
+
+### Low Priority
+- [ ] **SQLite support** - Add SQLite engine
+- [ ] **Health checks** - Periodic connection tests to verify containers are responsive
+
+---
+
+## Paid Features (Pro)
+
+### Security
+- [ ] **Password support** - Set password on container creation, modify `pg_hba.conf` for password auth
+- [ ] **Encrypted backups** - Encrypt dumps with password using gpg/openssl
+
+### Multi-Engine Support
+- [ ] **MySQL support** - Add MySQL engine (needs binary source)
+- [ ] **MongoDB support** - Add MongoDB engine
+
+### Advanced Features
+- [ ] **Container templates** - Save container configs as reusable templates
+- [ ] **Import from Docker** - Import data from Docker PostgreSQL containers
+- [ ] **Automatic binary updates** - Check for and download newer PostgreSQL versions
+- [ ] **Custom superuser name** - Allow changing from default `postgres` user
+- [ ] **Scheduled backups** - Cron-like backup scheduling
+- [ ] **Cloud backup sync** - Sync backups to S3/GCS/Azure
+
+### Team Features
+- [ ] **Shared configs** - Export/import container configs for team sharing
+- [ ] **Config profiles** - Dev/staging/test profiles with different settings
+
+---
+
+## Stretch Goals
+
+- [ ] **Terminal-based IDE** - Full TUI (terminal UI) for browsing tables, running queries, viewing results, editing data inline (think `lazygit` but for databases)
+  - Potential libraries: [blessed](https://github.com/chjj/blessed), [ink](https://github.com/vadimdemedes/ink), [terminal-kit](https://github.com/cronvel/terminal-kit)
+  - Inspiration: `lazygit`, `k9s`, `pgcli`
+
+---
+
+## Known Limitations
+
+- **No Windows support** - zonky.io doesn't provide Windows binaries
+- **Client tools required** - psql/pg_dump/pg_restore must be installed separately (not bundled)
+- **Local only** - No remote connection support (binds to 127.0.0.1)

package/bin/cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+import { register } from 'tsx/esm/api'
+
+register()
+
+await import('../src/bin/cli.ts')

package/eslint.config.js

@@ -0,0 +1,18 @@
+import eslint from '@eslint/js'
+import tseslint from 'typescript-eslint'
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    ignores: ['dist/', 'node_modules/', 'bin/'],
+  },
+  {
+    rules: {
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
+      ],
+    },
+  },
+)

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "spindb",
+  "version": "0.1.0",
+  "description": "Spin up local database containers without Docker. A DBngin-like CLI for PostgreSQL.",
+  "type": "module",
+  "bin": {
+    "spindb": "./bin/cli.js"
+  },
+  "scripts": {
+    "start": "tsx src/bin/cli.ts",
+    "dev": "tsx watch src/bin/cli.ts",
+    "build": "tsc",
+    "test": "tsx --test",
+    "format": "prettier --write .",
+    "lint": "eslint ."
+  },
+  "keywords": [
+    "postgres",
+    "postgresql",
+    "database",
+    "local",
+    "development",
+    "cli"
+  ],
+  "author": "Bob Bass <bob@bbass.co>",
+  "license": "MIT",
+  "packageManager": "pnpm@9.14.2",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/robertjbass/spindb.git"
+  },
+  "homepage": "https://github.com/robertjbass/spindb#readme",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "inquirer": "^9.3.7",
+    "ora": "^8.1.1",
+    "tsx": "^4.7.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/inquirer": "^9.0.7",
+    "@types/node": "^20.10.0",
+    "eslint": "^9.39.1",
+    "prettier": "^3.6.2",
+    "typescript": "^5.3.0",
+    "typescript-eslint": "^8.48.0"
+  }
+}

package/seeds/mysql/sample-db.sql

@@ -0,0 +1,22 @@
+-- Sample database schema for testing SpinDB
+-- Creates a basic users table with common fields (MySQL syntax)
+
+CREATE TABLE IF NOT EXISTS users (
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    first_name VARCHAR(100) NOT NULL,
+    last_name VARCHAR(100) NOT NULL,
+    email VARCHAR(255) NOT NULL UNIQUE,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    deleted_at TIMESTAMP NULL,
+    INDEX idx_users_email (email),
+    INDEX idx_users_deleted_at (deleted_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- Sample data
+INSERT IGNORE INTO users (first_name, last_name, email) VALUES
+    ('Alice', 'Johnson', 'alice@example.com'),
+    ('Bob', 'Smith', 'bob@example.com'),
+    ('Charlie', 'Williams', 'charlie@example.com'),
+    ('Diana', 'Brown', 'diana@example.com'),
+    ('Eve', 'Davis', 'eve@example.com');

package/seeds/postgres/sample-db.sql

@@ -0,0 +1,27 @@
+-- Sample database schema for testing SpinDB
+-- Creates a basic users table with common fields
+
+CREATE TABLE IF NOT EXISTS users (
+    id SERIAL PRIMARY KEY,
+    first_name VARCHAR(100) NOT NULL,
+    last_name VARCHAR(100) NOT NULL,
+    email VARCHAR(255) NOT NULL UNIQUE,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+    deleted_at TIMESTAMP WITH TIME ZONE
+);
+
+-- Create an index on email for faster lookups
+CREATE INDEX IF NOT EXISTS idx_users_email ON users(email);
+
+-- Create an index on deleted_at for soft delete queries
+CREATE INDEX IF NOT EXISTS idx_users_deleted_at ON users(deleted_at);
+
+-- Sample data
+INSERT INTO users (first_name, last_name, email) VALUES
+    ('Alice', 'Johnson', 'alice@example.com'),
+    ('Bob', 'Smith', 'bob@example.com'),
+    ('Charlie', 'Williams', 'charlie@example.com'),
+    ('Diana', 'Brown', 'diana@example.com'),
+    ('Eve', 'Davis', 'eve@example.com')
+ON CONFLICT (email) DO NOTHING;

package/src/bin/cli.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env tsx
+
+import { run } from '@/cli'
+
+run().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})