# terrabase-v2

[![CI](https://github.com/Terrabase-in/terrabase/actions/workflows/ci.yml/badge.svg)](https://github.com/Terrabase-in/terrabase/actions/workflows/ci.yml)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%E2%89%A522-brightgreen.svg)](.nvmrc)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

**LLM-assisted, safety-gated Postgres migrations, exposed as an MCP server.**

A local LLM may *draft* migration SQL, but a **deterministic rule engine over Postgres's own
parser AST is the sole safety authority**. Every write goes through a two-phase, approval-gated
flow and lands in an append-only audit ledger.

> The LLM proposes, the rules decide.

## Layout (pnpm monorepo)

| Package | Purpose |
|---|---|
| `packages/core` | shared types, zod schemas, errors, config, DSN redaction |
| `packages/pg-ast` | `libpg_query` (WASM) parse + traversal + typed node guards |
| `packages/pg-safety` | the **30-rule deterministic safety analyzer** (the heart) |
| `packages/pg-introspect` | live schema → compact JSON model |
| `packages/pg-advisor` | `EXPLAIN (FORMAT JSON)` parsing + HypoPG index advice |
| `packages/pg-migrate` | append-only audit ledger + transactional, approval-gated apply |
| `packages/llm` | Ollama structured output + retry-on-zod-error |
| `apps/mcp-server` | the 5 MCP tools + two-phase orchestration |

Full design: [`docs/specs/2026-07-07-terrabase-v2-design.md`](docs/specs/2026-07-07-terrabase-v2-design.md).

## Quick start

```bash
pnpm install
pnpm build          # tsup builds every package
pnpm typecheck      # tsc --noEmit, strict
pnpm test           # vitest unit tests (run everywhere)
```

Configure via env (see [`.env.example`](.env.example)): `TERRABASE_DATABASE_URL`, `OLLAMA_HOST`,
`OLLAMA_MODEL`, `TERRABASE_PG_VERSION`.

### Run the MCP server

```bash
pnpm mcp            # speaks MCP over stdio
```

Register it with any MCP client (command: `node apps/mcp-server/dist/index.js`).

## Graceful degradation

The parser + rule engine run with **no external services**. If Ollama is down, pass `sql`
directly to `propose_migration`. If there's no database, SQL is still parsed and analyzed
offline against `TERRABASE_PG_VERSION`. Docker-backed integration tests skip automatically when
Docker is unavailable.

## MCP tools

- `inspect_schema` — compact schema model (read-only)
- `propose_migration` — `intent`→LLM-drafted SQL **or** raw `sql` → analyze → returns a
  `SafetyReport` + `proposalId` (applies nothing)
- `apply_migration` — `proposalId` + `approvalToken` → gated, transactional apply → ledger
- `explain_query` — parsed plan tree + flagged problems
- `advise_index` — HypoPG-simulated index recommendations (Tier-1 catalog fallback)

## Desktop app (Strata)

An Electron GUI over the same engine lives in `apps/desktop`. It runs the
parser + rule engine locally, auto-discovers project databases, and renders the
`SafetyReport` visually.

```bash
pnpm --filter @terrabase-v2/desktop dev
```

## Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for
setup, the PR checklist, and the one non-negotiable rule (the LLM is advisory
only). All participants are expected to follow our
[Code of Conduct](CODE_OF_CONDUCT.md).

## Security

Found a vulnerability? Please report it privately — see
[SECURITY.md](SECURITY.md). Do not open a public issue for security reports.

## License

Licensed under the [Apache License 2.0](LICENSE). © 2026 Terrabase.in.