@libredb/studio 0.9.7 → 0.9.12

package/CLAUDE.md

@@ -1,265 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-LibreDB Studio is a web-based SQL IDE for cloud-native teams. It supports PostgreSQL, MySQL, SQLite, Oracle, SQL Server, MongoDB, Redis with AI-powered query assistance.
-
-## Github
-* Repository: https://github.com/libredb/libredb-studio
-* Container Registry: https://github.com/libredb/libredb-studio/pkgs/container/libredb-studio
-* Docker Image: ghcr.io/libredb/libredb-studio:latest
-* Helm Chart: https://artifacthub.io/packages/helm/libredb-studio/libredb-studio
-* Helm Repo: https://libredb.org/libredb-studio/
-* Helm OCI: oci://ghcr.io/libredb/charts/libredb-studio
-
-## Development Commands
-
-```bash
-# Install dependencies (Bun preferred)
-bun install
-
-# Development server with Turbopack
-bun dev
-
-# Production build
-bun run build
-
-# Start production server
-bun start
-
-# Lint code
-bun run lint
-
-# Run all tests (unit + API + integration + hooks + components)
-bun run test
-
-# Run individual test layers
-bun run test:unit
-bun run test:api
-bun run test:integration
-bun run test:hooks
-bun run test:components
-
-# E2E tests (Playwright, requires build)
-bun run test:e2e
-
-# Coverage report
-bun run test:coverage
-
-# Docker development
-docker-compose up -d
-
-# Helm chart
-helm lint charts/libredb-studio --strict
-helm template test charts/libredb-studio --set secrets.jwtSecret=test-secret-32-chars-minimum-here --set secrets.adminPassword=test123 --set secrets.userPassword=test123
-helm dependency build charts/libredb-studio
-```
-
-The project uses ESLint 9 for linting and `bun:test` for testing with `@testing-library/react` + `happy-dom` for component tests and Playwright for E2E tests.
-
-> **Important**: Always use `bun run test` instead of bare `bun test`. Component tests require isolated execution groups (handled by `tests/run-components.sh`) to prevent `mock.module()` cross-contamination between test files.
-
-## Architecture
-
-### Tech Stack
-- **Framework:** Next.js 16 (App Router) with React 19 and TypeScript
-- **Styling:** Tailwind CSS 4 with Shadcn/UI components
-- **SQL Editor:** Monaco Editor
-- **Data Grid:** TanStack React Table with react-virtual for virtualization
-- **AI:** Multi-model support (Gemini, OpenAI, Ollama, Custom)
-- **Databases:** PostgreSQL (`pg`), MySQL (`mysql2`), SQLite (`better-sqlite3`), Oracle (`oracledb`), SQL Server (`mssql`), MongoDB (`mongodb`), Redis (`ioredis`)
-- **Auth:** JWT-based with `jose` library + OIDC SSO with `openid-client` (Auth0, Keycloak, Okta, Azure AD)
-- **Storage:** Pluggable storage layer — localStorage (default), SQLite (`better-sqlite3`), or PostgreSQL (`pg`)
-
-### Directory Structure
-
-```
-src/
-├── app/                    # Next.js App Router
-│   ├── api/
-│   │   ├── auth/           # Login/logout/me endpoints
-│   │   │   └── oidc/       # OIDC login + callback routes (PKCE, code exchange)
-│   │   ├── ai/             # AI endpoints (chat, nl2sql, explain, safety)
-│   │   ├── db/             # Query, schema, health, maintenance, transactions
-│   │   ├── storage/        # Storage sync API (config, CRUD, migrate)
-│   │   └── admin/          # Fleet health, audit endpoints
-│   ├── admin/              # Admin dashboard (RBAC protected)
-│   └── login/              # Login page
-├── components/             # React components
-│   ├── Studio.tsx          # Main application shell
-│   ├── QueryEditor.tsx     # Monaco SQL editor wrapper
-│   ├── ResultsGrid.tsx     # Virtualized data grid
-│   ├── sidebar/            # Sidebar, ConnectionsList, ConnectionItem
-│   ├── studio/             # StudioTabBar, QueryToolbar, BottomPanel
-│   ├── admin/              # AdminDashboard, tabs (Overview, Operations, etc.)
-│   ├── schema-explorer/    # SchemaExplorer component
-│   └── ui/                 # Shadcn/UI primitives
-├── hooks/                  # Custom React hooks
-└── lib/
-    ├── storage/            # Storage abstraction layer
-    │   ├── index.ts        # Barrel export
-    │   ├── types.ts        # StorageData, ServerStorageProvider interfaces
-    │   ├── storage-facade.ts # Public sync API + CustomEvent dispatch
-    │   ├── local-storage.ts  # Pure localStorage CRUD
-    │   ├── factory.ts      # Env-based provider factory (singleton)
-    │   └── providers/
-    │       ├── sqlite.ts   # better-sqlite3 backend
-    │       └── postgres.ts # pg backend
-    ├── db/                 # Database provider module (Strategy Pattern)
-    │   ├── providers/
-    │   │   ├── sql/        # SQL providers (postgres, mysql, sqlite, oracle, mssql)
-    │   │   ├── document/   # Document providers (mongodb)
-    │   │   ├── keyvalue/   # Key-value providers (redis)
-    │   ├── factory.ts      # Provider factory
-    │   ├── types.ts        # Database types
-    │   └── errors.ts       # Custom error classes
-    ├── llm/                # LLM provider module (Strategy Pattern)
-    ├── schema-diff/        # Schema diff engine + migration SQL generator
-    ├── sql/                # SQL statement splitter, alias extractor
-    ├── types.ts            # TypeScript type definitions
-    ├── auth.ts             # JWT auth utilities (login, logout, signJWT, verifyJWT)
-    ├── oidc.ts             # OIDC utilities (discovery, PKCE, token exchange, role mapping, logout)
-    └── storage.ts          # LocalStorage management
-
-tests/
-├── setup.ts               # Global test setup (env vars, localStorage mock)
-├── setup-dom.ts            # DOM environment setup (happy-dom)
-├── run-components.sh       # Component test isolation runner
-├── fixtures/               # Mock data (connections, schemas, query results)
-├── helpers/                # Test utilities (mock providers, mock Monaco, etc.)
-├── unit/                   # Pure function tests
-├── api/                    # API route handler tests
-├── integration/            # Database provider tests (mocked drivers)
-├── hooks/                  # React hook tests
-└── components/             # Component tests (happy-dom)
-
-e2e/                        # Playwright E2E tests (browser)
-
-charts/
-└── libredb-studio/         # Helm chart for Kubernetes deployment
-    ├── Chart.yaml           # Chart metadata + ArtifactHub annotations
-    ├── values.yaml          # Default configuration
-    ├── values.schema.json   # JSON Schema validation
-    └── templates/           # K8s manifests (deployment, service, ingress, etc.)
-```
-
-### Key Patterns
-
-1. **Database Abstraction:** `src/lib/db/` module provides Strategy Pattern implementation for multiple database types:
-   - **SQL:** PostgreSQL, MySQL, SQLite, Oracle, SQL Server (extend `SQLBaseProvider`)
-   - **Document:** MongoDB (extends `BaseDatabaseProvider`)
-   - **Key-Value:** Redis (extends `BaseDatabaseProvider`)
-
-2. **LLM Abstraction:** `src/lib/llm/` module provides Strategy Pattern for AI providers (Gemini, OpenAI, Ollama, Custom)
-
-3. **Authentication Flow:** Supports two modes controlled by `NEXT_PUBLIC_AUTH_PROVIDER`:
-   - **Local** (default): Email/password login → JWT session cookie
-   - **OIDC**: SSO redirect → PKCE code exchange → local JWT session cookie (same as local)
-
-   JWT tokens stored in HTTP-only cookies. Proxy (`src/proxy.ts`) protects routes and enforces RBAC (admin vs user roles). OIDC module (`src/lib/oidc.ts`) handles discovery, PKCE, token exchange, role mapping, and provider logout.
-
-4. **API Routes:** All backend logic in `src/app/api/`. Protected routes require valid JWT. Public routes: `/login`, `/api/auth`, `/api/db/health`
-
-5. **Storage Abstraction:** `src/lib/storage/` module provides pluggable persistence:
-   - **Local** (default): Browser localStorage, zero config
-   - **SQLite**: `better-sqlite3` file DB for single-node persistent storage
-   - **PostgreSQL**: `pg` for multi-node enterprise storage
-   - Write-through cache: localStorage always serves reads; `useStorageSync` hook pushes mutations to server (debounced)
-   - Controlled by `STORAGE_PROVIDER` env var (server-side only, discovered at runtime via `/api/storage/config`)
-
-6. **Multi-Tab Workspace:** Each query tab has independent state (query, results, execution status)
-
-### Environment Variables
-
-Required in `.env.local`:
-```
-# Authentication (local mode)
-ADMIN_EMAIL=admin@libredb.org   # Admin email
-ADMIN_PASSWORD=<password>       # Admin password
-USER_EMAIL=user@libredb.org     # User email
-USER_PASSWORD=<password>        # User password
-JWT_SECRET=<32+ chars>          # JWT signing secret
-
-# Auth provider: "local" (default) or "oidc"
-NEXT_PUBLIC_AUTH_PROVIDER=local
-
-# OIDC config (required when provider=oidc)
-OIDC_ISSUER=<issuer-url>        # e.g. https://dev-xxx.auth0.com
-OIDC_CLIENT_ID=<client-id>
-OIDC_CLIENT_SECRET=<secret>
-OIDC_SCOPE=openid profile email # Optional, defaults shown
-OIDC_ROLE_CLAIM=                # Claim path for role (e.g. realm_access.roles)
-OIDC_ADMIN_ROLES=admin          # Comma-separated admin role values
-
-# Optional AI config
-LLM_PROVIDER=gemini             # gemini, openai, ollama, custom
-LLM_API_KEY=<key>
-LLM_MODEL=gemini-2.5-flash
-LLM_API_URL=<url>               # For ollama/custom providers
-
-# Optional storage config (server-side only, not NEXT_PUBLIC_)
-STORAGE_PROVIDER=local                  # local (default) | sqlite | postgres
-STORAGE_SQLITE_PATH=./data/libredb-storage.db  # SQLite file path
-STORAGE_POSTGRES_URL=postgresql://...           # PostgreSQL connection URL
-```
-
-### Path Aliases
-
-TypeScript path alias `@/*` maps to `./src/*`. Use `@/components/...`, `@/lib/...`, etc.
-
-## Pre-Commit Verification (MANDATORY)
-
-**After every code change, you MUST run the CI pipeline checks locally before considering the task complete.** These match `.github/workflows/ci.yml` and `docker-build-push.yml`:
-
-```bash
-# 1. Lint (ESLint 9)
-bun run lint
-
-# 2. Type check (TypeScript strict)
-bun run typecheck
-
-# 3. Tests (unit + API + integration + hooks + components)
-bun run test
-
-# 4. Build (Next.js production build)
-bun run build
-```
-
-**Do NOT skip any step.** If any step fails, fix the issue before proceeding. The GitHub Actions CI will run all four checks — a local pass on all four guarantees the CI will also pass.
-
-## Docker Build
-
-The Dockerfile uses multi-stage Bun build with standalone Next.js output. Build args: `JWT_SECRET_BUILD`, `ADMIN_PASSWORD_BUILD`, `USER_PASSWORD_BUILD`. Health check: `GET /api/db/health`.
-
-## Database Connections
-
-### SQL Databases (PostgreSQL, MySQL, SQLite)
-```typescript
-const connection = {
-  type: 'postgres', // or 'mysql', 'sqlite'
-  host: 'localhost',
-  port: 5432,
-  database: 'mydb',
-  user: 'admin',
-  password: 'secret',
-};
-```
-
-### MongoDB
-```typescript
-const connection = {
-  type: 'mongodb',
-  connectionString: 'mongodb://localhost:27017/mydb',
-  // or host/port/database format
-};
-
-// Query format (JSON)
-const query = JSON.stringify({
-  collection: 'users',
-  operation: 'find',
-  filter: { status: 'active' },
-  options: { limit: 50 }
-});
-```

package/CODE_OF_CONDUCT.md

@@ -1,124 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in our
-community a harassment-free experience for everyone, regardless of age, body
-size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, caste, color, religion, or sexual
-identity and orientation.
-
-We pledge to act and interact in ways that contribute to an open, welcoming,
-diverse, inclusive, and healthy community.
-
-## Our Standards
-
-Examples of behavior that contributes to a positive environment for our
-community include:
-
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
-  and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the overall
-  community
-
-Examples of unacceptable behavior include:
-
-* The use of sexualized language or imagery, and sexual attention or advances of
-  any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email address,
-  without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
-
-## Enforcement Responsibilities
-
-Community leaders are responsible for clarifying and enforcing our standards of
-acceptable behavior and will take appropriate and fair corrective action in
-response to any behavior that they deem inappropriate, threatening, offensive,
-or harmful.
-
-Community leaders have the right and responsibility to remove, edit, or reject
-comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned to this Code of Conduct, and will communicate reasons for moderation
-decisions when appropriate.
-
-## Scope
-
-This Code of Conduct applies within all community spaces, and also applies when
-an individual is officially representing the community in public spaces.
-Examples of representing our community include using an official project e-mail
-address, posting via an official social media account, or acting as an appointed
-representative at an online or offline event.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leaders responsible for enforcement at
-cevheribozoglan@gmail.com.
-All complaints will be reviewed and investigated promptly and fairly.
-
-All community leaders are obligated to respect the privacy and security of the
-reporter of any incident.
-
-## Enforcement Guidelines
-
-Community leaders will follow these Community Impact Guidelines in determining
-the consequences for any action they deem in violation of this Code of Conduct:
-
-### 1. Correction
-**Community Impact**: Use of inappropriate language or other behavior deemed
-unprofessional or unwelcome in the community.
-
-**Consequence**: A private, written warning from community leaders, providing
-clarity around the nature of the violation and an explanation of why the
-behavior was inappropriate. A public apology may be requested.
-
-### 2. Warning
-**Community Impact**: A violation through a single incident or series of
-actions.
-
-**Consequence**: A warning with consequences for continued behavior. No
-interaction with the people involved, including unsolicited interaction with
-those enforcing the Code of Conduct, for a specified period of time. This
-includes avoiding interactions in community spaces as well as external channels
-like social media. Violating these terms may lead to a temporary or permanent
-ban.
-
-### 3. Temporary Ban
-**Community Impact**: A serious violation of community standards, including
-sustained inappropriate behavior.
-
-**Consequence**: A temporary ban from any sort of interaction or public
-communication with the community for a specified period of time. No public or
-private interaction with the people involved, including unsolicited interaction
-with those enforcing the Code of Conduct, is allowed during this period.
-Violating these terms may lead to a permanent ban.
-
-### 4. Permanent Ban
-**Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior, harassment of an
-individual, or aggression toward or disparagement of classes of individuals.
-
-**Consequence**: A permanent ban from any sort of public interaction within the
-community.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage],
-version 2.1, available at
-[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]
-
-[homepage]: https://www.contributor-covenant.org
-[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
-
-For answers to common questions about this code of conduct, see
-[https://www.contributor-covenant.org/faq][faq]
-
-[faq]: https://www.contributor-covenant.org/faq
-

package/CONTRIBUTING.md

@@ -1,154 +0,0 @@
-# Contributing to LibreDB Studio
-
-First off, thank you for considering contributing to LibreDB Studio! It's people like you that make LibreDB Studio such a great tool.
-
-## Code of Conduct
-
-This project and everyone participating in it is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
-
-## How Can I Contribute?
-
-### Reporting Bugs
-
-Before creating bug reports, please check the existing issues to avoid duplicates. When you create a bug report, include as many details as possible:
-
-- **Use a clear and descriptive title**
-- **Describe the exact steps to reproduce the problem**
-- **Describe the behavior you observed and what you expected**
-- **Include screenshots if possible**
-- **Include your environment details** (OS, browser, Node.js version)
-
-### Suggesting Features
-
-Feature suggestions are welcome! Please provide:
-
-- **A clear and descriptive title**
-- **A detailed description of the proposed feature**
-- **Explain why this feature would be useful**
-- **Include mockups or examples if applicable**
-
-### Pull Requests
-
-1. **Fork the repository** and create your branch from `main`
-2. **Follow the coding style** of the project
-3. **Write clear commit messages**
-4. **Update documentation** if needed
-5. **Test your changes** thoroughly
-
-## Development Setup
-
-### Prerequisites
-
-- [Bun](https://bun.sh/) (recommended) or Node.js 20+
-- Git
-
-### Getting Started
-
-```bash
-# Clone your fork
-git clone https://github.com/YOUR_USERNAME/libredb-studio.git
-cd libredb-studio
-
-# Install dependencies
-bun install
-
-# Copy environment example
-cp .env.example .env.local
-
-# Start development server
-bun dev
-```
-
-### Environment Variables
-
-Required for development:
-```env
-ADMIN_PASSWORD=admin123
-USER_PASSWORD=user123
-JWT_SECRET=your_32_character_random_string_here
-```
-
-Optional (for AI features):
-```env
-LLM_PROVIDER=gemini
-LLM_API_KEY=your_api_key
-LLM_MODEL=gemini-2.5-flash
-```
-
-### Development Database
-
-We provide a ready-to-use PostgreSQL setup with sample data for testing:
-
-```bash
-# Start PostgreSQL with sample e-commerce data
-docker compose -f docker/postgres.yml up -d
-
-# Connect with:
-# Host: localhost, Port: 5432, Database: libredb_dev
-# User: postgres, Password: postgres
-```
-
-**Includes:**
-- PostgreSQL 17 with `pg_stat_statements` enabled
-- E-commerce sample schema (customers, products, orders)
-- 100+ records across multiple tables
-- Pre-built views for reporting
-
-> This is especially useful for testing the **Monitoring Dashboard** features.
-
-### Project Structure
-
-```
-src/
-├── app/              # Next.js App Router
-│   ├── api/          # API routes
-│   ├── admin/        # Admin pages
-│   └── login/        # Login page
-├── components/       # React components
-├── hooks/            # Custom React hooks
-└── lib/
-    ├── db/           # Database providers (Strategy Pattern)
-    ├── llm/          # LLM providers (Strategy Pattern)
-    └── ...           # Utilities
-```
-
-### Available Scripts
-
-```bash
-bun dev        # Start development server
-bun build      # Build for production
-bun start      # Start production server
-bun lint       # Run ESLint
-```
-
-## Coding Guidelines
-
-### TypeScript
-
-- Use TypeScript for all new code
-- Define proper types/interfaces
-- Avoid `any` type when possible
-
-### React
-
-- Use functional components with hooks
-- Follow the existing component patterns
-- Keep components focused and small
-
-### Styling
-
-- Use Tailwind CSS for styling
-- Follow the existing design patterns
-- Use Shadcn/UI components when applicable
-
-### Commits
-
-- Use clear, descriptive commit messages
-- Reference issues in commits when applicable (e.g., `Fix #123`)
-- Keep commits focused on a single change
-
-## Questions?
-
-Feel free to open an issue with your question or reach out to the maintainers.
-
-Thank you for contributing!

package/Dockerfile

@@ -1,73 +0,0 @@
-# ==============================================================================
-# LibreDB Studio - Production Dockerfile
-# Optimized for Render, Railway, Fly.io, and Kubernetes
-# ==============================================================================
-
-# Bun for fast dependency installation, Node.js for build
-# Bun's JIT compiler segfaults under QEMU emulation (ARM64 cross-build),
-# so we use Node.js for the Next.js build step.
-FROM oven/bun:1 AS deps
-WORKDIR /usr/src/app
-RUN apt-get update && apt-get install -y python3 make g++ --no-install-recommends && rm -rf /var/lib/apt/lists/*
-COPY package.json bun.lock ./
-RUN bun install --frozen-lockfile
-
-# Build with Node.js to avoid Bun/QEMU segfaults on ARM64
-FROM node:20-slim AS builder
-WORKDIR /usr/src/app
-COPY --from=deps /usr/src/app/node_modules ./node_modules
-COPY . .
-
-ENV NEXT_TELEMETRY_DISABLED=1
-ENV DOCKER_BUILD=true
-
-ARG JWT_SECRET_BUILD="build-time-placeholder-secret-32ch"
-ARG ADMIN_PASSWORD_BUILD="build"
-ARG USER_PASSWORD_BUILD="build"
-ENV JWT_SECRET=$JWT_SECRET_BUILD
-ENV ADMIN_PASSWORD=$ADMIN_PASSWORD_BUILD
-ENV USER_PASSWORD=$USER_PASSWORD_BUILD
-
-RUN npx next build
-
-# Production image - use Node.js slim for lower memory footprint
-FROM node:20-slim AS runner
-WORKDIR /app
-
-ENV NODE_ENV=production
-ENV NEXT_TELEMETRY_DISABLED=1
-
-# Memory optimization for low-memory environments (Render free tier)
-# V8 heap limit to prevent OOM on 512MB instances
-ENV NODE_OPTIONS="--max-old-space-size=384"
-
-COPY --from=builder /usr/src/app/public ./public
-
-# Set the correct permission for prerender cache and storage
-RUN mkdir -p .next data
-
-# Automatically leverage output traces to reduce image size
-# https://nextjs.org/docs/advanced-features/output-file-tracing
-COPY --from=builder /usr/src/app/.next/standalone ./
-COPY --from=builder /usr/src/app/.next/static ./.next/static
-
-# Copy better-sqlite3 native binding for server storage support
-COPY --from=builder /usr/src/app/node_modules/better-sqlite3 ./node_modules/better-sqlite3
-COPY --from=builder /usr/src/app/node_modules/bindings ./node_modules/bindings
-COPY --from=builder /usr/src/app/node_modules/file-uri-to-path ./node_modules/file-uri-to-path
-# prebuild-install is only needed at build time, not runtime
-
-# Create non-root user for security
-RUN addgroup --system --gid 1001 nodejs && \
-    adduser --system --uid 1001 nextjs && \
-    chown -R nextjs:nodejs /app
-USER nextjs
-
-# Render uses PORT env variable, default to 3000
-EXPOSE 3000/tcp
-ENV PORT=3000
-ENV HOSTNAME="0.0.0.0"
-
-# server.js is created by next build from the standalone output
-# https://nextjs.org/docs/pages/api-reference/next-config-js/output
-CMD ["node", "server.js"]