# project-supabase-api

Controlled AI-to-Supabase integration layer for the AI Projects portfolio.

**Not a generic Supabase client library.** The official SDKs (`@supabase/supabase-js`, `supabase-py`) already solve that. This repo adds the **AI adapter layer**: safety-bounded operations, agent-purpose-built MCP server, migration tooling, and reusable schema contracts.

**Canonical Architecture:** API-149 (Supabase API Integration Layer)

## What It Does

- **Bounded client** — Wraps `@supabase/supabase-js` with table allowlists, row limits, query validation, and write confirmation gates
- **MCP server** — Thin transport over application layer; exposes read-only (default) and gated-write tools for AI agent consumption
- **Python CLI** — Zero-dependency CLI for agent scripts where Node isn't available
- **Migration tooling** — Standardized DDL with prefix validation, collision detection, dry-run, and planning
- **Schema contracts** — Typed table interfaces for the shared project's 50+ tables
- **Capability reporting** — Doctor command qualifies supported/unavailable/plan-gated/experimental capabilities
- **Security audit** — RLS status, grants inspection, protected schema validation
- **Project/environment targeting** — Every operation requires explicit project reference; production never inferred

## Scope

This repo targets the **shared Supabase project** (`buobojrsaanekrbobgwc`) used by:

- project-dashboard
- project-setness-consulting
- project-cpe
- project-munoz
- project-politics
- (future) Albert ledger, LevelBest, Nathan

## Quick Start

### TypeScript

```bash
npm install
npm run verify
```

### Python

```bash
pip install -e ".[dev]"
python -m pytest
```

## Safety Model

| Operation | Default | Write Gate |
|-----------|---------|------------|
| SELECT queries | Allowed | Bounded (max rows, timeout) |
| Schema inspection | Allowed | Read-only |
| Storage read | Allowed | Bounded |
| INSERT/UPDATE/DELETE | Allowed with token | `APPLY_SUPABASE_CHANGES` or per-operation token |
| DDL (migrations) | Owner-gated | Separate confirmation, dry-run default |
| Edge Function invoke | Allowed with scope | Function allowlist |
| Realtime subscribe | Allowed | Channel allowlist |

## Repository Structure

```
src/
├── ts/              # TypeScript source (primary)
│   ├── client/      # Bounded client wrapper
│   ├── auth/        # Session/token management, RLS
│   ├── database/    # Query builder, schema inspector, contracts
│   ├── storage/     # Storage adapter
│   ├── edge-functions/  # Functions adapter
│   ├── realtime/    # Realtime adapter
│   ├── migrations/  # DDL runner, naming validation
│   ├── safety/      # Allowlists, write gates, audit
│   └── mcp/         # MCP server and tools
└── python/          # Python CLI (zero-dep)
    └── supabase_api/
```

## Documentation

- [ARCHITECTURE.md](./ARCHITECTURE.md) — Module layout, dependency direction, trust boundaries
- [SECURITY.md](./SECURITY.md) — Token handling, write gates, incident response
- [STATUS.md](./STATUS.md) — Current lifecycle state and verification results
- [AGENTS.md](./AGENTS.md) — Agent instructions and hard rules
- [CHANGELOG.md](./CHANGELOG.md) — Versioned changes
- [docs/PLATFORM-COMPATIBILITY.md](./docs/PLATFORM-COMPATIBILITY.md) — Current Supabase platform requirements
- [docs/CONSUMER-ADOPTION.md](./docs/CONSUMER-ADOPTION.md) — Adoption guide for consumer repositories
- [docs/ARCHITECTURAL-DECISION-API149-CANONICAL.md](./docs/ARCHITECTURAL-DECISION-API149-CANONICAL.md) — API-149 canonical, API-128 superseded

## Architecture Principles

1. **MCP is a thin transport** — Business logic lives in the application layer, not in MCP tools
2. **Project/environment targeting** — Every operation requires explicit project reference
3. **Read-first authority** — Read operations default; mutations require explicit enablement
4. **Dry-run before mutations** — Migrations default to dry-run
5. **Post-change read-back** — Mutations return evidence of applied changes
6. **No arbitrary REST, shell, SQL, or filesystem passthrough** — All operations validated against allowlists

## License

Private — AI Projects portfolio internal use.