spindb 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spindb",
-  "version": "0.2.0",
+  "version": "0.2.01",
   "description": "Spin up local database containers without Docker. A DBngin-like CLI for PostgreSQL.",
   "type": "module",
   "bin": {
@@ -48,5 +48,13 @@
     "prettier": "^3.6.2",
     "typescript": "^5.3.0",
     "typescript-eslint": "^8.48.0"
-  }
+  },
+  "tsx": {
+    "tsconfig": "./tsconfig.json"
+  },
+  "files": [
+    "bin/**/*",
+    "src/**/*",
+    "tsconfig.json"
+  ]
 }

package/.claude/settings.local.json

@@ -1,25 +0,0 @@
-{
-  "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:*)",
-      "Bash(node /Users/bob/dev/db-container/bin/cli.js:*)",
-      "Bash(node -e \"\nconst { fetchAvailableVersions, SUPPORTED_MAJOR_VERSIONS } = require(''./src/engines/postgresql/binary-urls.ts'');\n\")",
-      "Bash(node --import tsx bin/cli.js:*)",
-      "Bash(node --import tsx:*)",
-      "Bash(cat:*)"
-    ],
-    "deny": [],
-    "ask": []
-  }
-}

package/.env.example

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

package/.prettierignore

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

package/.prettierrc

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

package/CLAUDE.md

@@ -1,192 +0,0 @@
-# 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.
-
-**Menu Navigation Rules:**
-- Any submenu with a "Back" button that goes to a parent menu (not main menu) MUST also have a "Back to main menu" option
-- Back buttons use blue color: `${chalk.blue('←')} Back to...`
-- Main menu buttons use house emoji: `${chalk.blue('🏠')} Back to main menu`
-
-### Container Config
-Each container has a `container.json` with:
-```typescript
-type ContainerConfig = {
-  name: string
-  engine: string
-  version: string
-  port: number
-  database: string      // User's database name (separate from container name)
-  created: string
-  status: 'created' | 'running' | 'stopped'
-  clonedFrom?: string
-}
-```
-
-The `database` field allows users to specify a custom database name in the connection string (e.g., `postgresql://postgres@localhost:5432/my-app-db`).
-
-## 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 Fetching
-PostgreSQL versions are fetched dynamically from Maven Central with a 5-minute cache. Falls back to `FALLBACK_VERSION_MAP` if network fails. See `src/engines/postgresql/binary-urls.ts`:
-
-```typescript
-// Fallback versions (used when Maven is unreachable)
-export const FALLBACK_VERSION_MAP: Record<string, string> = {
-  '14': '14.20.0',
-  '15': '15.15.0',
-  '16': '16.11.0',
-  '17': '17.7.0',
-}
-
-// Dynamic fetching from Maven
-export async function fetchAvailableVersions(): Promise<Record<string, string[]>>
-```
-
-The create flow uses two-step version selection: first major version (14, 15, 16, 17), then specific minor version within that major.
-
-### 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. **Database names immutable** - Cannot rename database after creation (would require `ALTER DATABASE`)
-
-## Future Improvements
-
-See `TODO.md` for full list. Key items:
-- [ ] Add `spindb backup` command (wrapper around pg_dump)
-- [ ] Add `spindb logs` command to tail postgres.log
-- [ ] Add `spindb exec` for running SQL files
-- [ ] Database rename support
-- [ ] Support MySQL/SQLite engines (architecture supports it)
-- [ ] 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/TODO.md

@@ -1,75 +0,0 @@
-# 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`
-- [x] **Engine/binary management** - Menu to list installed PostgreSQL versions, install new versions, uninstall unused versions (free up disk space)
-
-### Medium Priority
-- [x] **Container rename** - Rename a container without cloning/deleting (via Edit menu)
-- [ ] **Database rename** - Rename a database within a container (requires stopping container, running `ALTER DATABASE ... RENAME TO ...`, updating config)
-- [x] **Export connection string** - Copy connection string to clipboard (via container submenu)
-- [ ] **Multiple databases per container** - List/create/delete databases within a container
-- [x] **Fetch available versions** - Query Maven Central API to show all available PostgreSQL versions instead of hardcoded list
-
-### Low Priority
-- [ ] **SQLite support** - Add SQLite engine
-- [ ] **Health checks** - Periodic connection tests to verify containers are responsive
-- [ ] **Offline Support** - Package binaries locally for offline installation
-- [ ] **Binary caching** - Cache downloaded binaries locally to avoid re-downloading
-- [ ] **Binary version management** - List, install, and remove different PostgreSQL versions
-- [ ] **Binary verification** - Verify downloaded binaries with checksums
-- [ ] **Binary cleanup** - Remove old cached binaries to free up disk space
-- [ ] **Binary space monitoring** - Show disk usage of cached binaries
-- [ ] **Binary auto-cleanup** - Automatically remove old versions after a retention period
-
----
-
-## 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/eslint.config.js

@@ -1,24 +0,0 @@
-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/', 'eslint.config.js'],
-  },
-  {
-    languageOptions: {
-      parserOptions: {
-        project: true,
-        tsconfigRootDir: import.meta.dirname,
-      },
-    },
-    rules: {
-      '@typescript-eslint/no-unused-vars': [
-        'error',
-        { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
-      ],
-    },
-  },
-)

package/seeds/mysql/sample-db.sql

@@ -1,22 +0,0 @@
--- 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

@@ -1,27 +0,0 @@
--- 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;