kamehadb: Instructions file for Codex

AGENTS.md

This file provides guidance for coding agents working in this repository.

Project Overview

KamehaDB is a local-first database GUI built as a single Wails v2 desktop app: a Go backend embedded in the executable plus a React 19 + Vite frontend. The current app supports PostgreSQL, MySQL, SQLite, MongoDB, Redis, SQL Server, Oracle, ClickHouse, DuckDB, and MariaDB. It includes schema browsing, a CodeMirror SQL editor, query history, PostgreSQL stats views, schema timeline/diff workflows, Redis/Mongo explorers, embedded PostgreSQL and Mongo shells, PostgreSQL backup/restore flows, an in-app logs viewer, a read-only MCP server, and an AI chat panel with schema-aware context.

There is also a separate marketing/docs site in landing/, but it is not part of the pnpm workspace used by the desktop app.

Repository Layout

├── apps/
│   └── desktop/          # React 19 + Vite 7 frontend (Wails webview)
├── dbcore/               # Reusable provider core: contracts, providers, lifecycle manager
├── internal/             # Go backend: services, store, MCP, terminal
├── packages/
│   └── shared/           # Shared Zod schemas and frontend-facing types
├── landing/              # Separate Next.js marketing site (not in pnpm workspace)
├── main.go / app.go      # Wails entrypoint and bound app methods
├── wails.json            # Wails project config (frontend dir, build hooks)
├── docker-compose.yml    # Local dev databases
└── docker-init/          # Seed SQL for Postgres/MySQL/MariaDB

Workspace And Package Boundaries

• The pnpm workspace includes only apps/* and packages/*.
• landing/ has its own package-lock.json and is managed separately with npm.
• Most root scripts target the pnpm workspace only. Do not assume they affect landing/ unless they explicitly use npm --prefix landing.
• The Go module lives at the repo root (go.mod); internal/ is not part of the pnpm workspace.

Commands

Workspace root

# Install workspace dependencies
pnpm install

# Start dev databases
docker compose up -d

# Run the full app in Wails dev mode (frontend watcher + Go backend)
pnpm dev

# Run only the frontend dev server (no backend bindings)
pnpm dev:desktop

# Build the production desktop binary into build/bin/
pnpm build

# Typecheck all workspace packages (desktop: pnpm --dir apps/desktop exec tsc --noEmit)
pnpm typecheck

# Lint all workspace packages that expose a lint script
pnpm lint

# Run all workspace package tests that expose a test script
pnpm test

# Run the Go backend tests
pnpm test:go

# Lint the Go backend with golangci-lint (resolved via `go tool` from go.mod — no separate install)
pnpm lint:go

# Format Go source with gofumpt + goimports
pnpm format:go