supaschema 0.1.0-rc.1

package/.agents/skills/supaschema/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: supaschema
+description: Generate, check, and verify replay-safe PostgreSQL/Supabase migrations from declarative SQL tree diffs with supaschema. Use when schema changes are requested, migrations must be created or validated, schema drift needs detection, or a supaschema diagnostic (SUPA_*) blocks a plan.
+---
+
+# supaschema Migration Workflow
+
+## Contract
+
+This skill is a direct execution contract for producing schema migrations with supaschema. Follow the workflow in order; do not hand-author migration SQL for changes the declarative tree can express, and never edit a generated migration (the `-- supaschema: lineage` marker) by hand.
+
+## Workflow
+
+1. **Edit the declarative tree** (`supabase/schemas/**` or the project's configured tree) to express the desired end state. Use schema-qualified object names.
+2. **Generate the migration:**
+
+   ```bash
+   supaschema diff
+   ```
+
+   Zero-flag defaults (printed to stderr; flags override): `--from` resolves to the database (then `git:HEAD`), `--to` to the config schema tree, and the file lands in `config.migrationsDir` as `<UTC timestamp>_<derived name>.sql`. Pass `--name <snake_case>` to control the name. The write is no-clobber and chain-gated. If it exits 2, read the diagnostic:
+   - `SUPA_PLAN_DESTRUCTIVE_HINT_REQUIRED` / `SUPA_PLAN_COLUMN_ALTER_HINT_REQUIRED` / `SUPA_PLAN_VIEW_REPLACE_INCOMPATIBLE` / `SUPA_PLAN_ROUTINE_RETURN_TYPE_CHANGED` — review the rendered `-- BLOCKED` section, then add the exact object key to `hints.destructive` in `supaschema.config.json` and regenerate. Never use `"*"` in committed config.
+   - `SUPA_DIFF_LINEAGE_BROKEN` — a pending generated migration exists; diff from the post-migration state instead: `--from database:<db with pending applied>`.
+   - `SUPA_DIFF_LINEAGE_DUPLICATE` — the transition is already pending; apply or remove the pending migration instead of regenerating.
+   - Renames: declare `{ "from": "<key>", "to": "<key>" }` in `hints.renames`; renames are never inferred.
+
+3. **Check replay safety:** `supaschema check` gates every `.sql` in the migrations directory (or name specific files) — must exit 0 for generated and hand-authored migrations alike.
+4. **Verify execution** (when any database is resolvable — the URL auto-resolves from `SUPASCHEMA_DATABASE_URL` or the nearest `supabase/config.toml`):
+
+   ```bash
+   supaschema verify
+   ```
+
+   Defaults to the newest pending migration in the migrations directory with the same from/to defaults as `diff`; pass `--migration <file>` to verify a specific one.
+
+   Add `--ensure-roles` when the migration grants to roles a bare PostgreSQL server lacks (e.g. `authenticated`). A fingerprint mismatch itemizes the differing objects in the diagnostic hint.
+
+5. **Commit** the tree change, the generated migration, and the refreshed types file together. supaschema never stages or applies; the migration runner (e.g. `supabase db push`) owns the database. TypeScript types come from the tree (`supaschema types` creates `database.types.ts`; every later `diff` refreshes it) — never wait for a deploy or run introspection-based typegen to get correct types.
+
+## Drift Detection
+
+```bash
+supaschema diff --fail-on-diff --quiet
+```
+
+Exit 3 means the live database and the tree have diverged; exit 0 means parity. Use this as a CI gate (`docs/ci.md` has the full pipeline recipe).
+
+When drift is large or blocked, triage before editing:
+
+- `supaschema diff --summary` — operation/diagnostic counts grouped by kind and schema, printed even when the plan is blocked.
+- `supaschema diff --write-hints <file>` — writes the gated destructive object keys as a reviewable `hints.destructive` skeleton (no-clobber).
+- `supaschema audit --from <source> [--json]` — modeled coverage by kind/schema plus every statement outside the contract grouped by diagnostic code.
+- `supaschema selfcheck` — re-extracts a live catalog's rendered SQL and reports any object whose identity diverges (`SUPA_SELFCHECK_*`); zero mismatches proves cross-lane identity parity.
+- `supaschema migrations` — classifies on-disk migrations against a target's applied history: applied, pending, ghost, or out-of-order.
+
+## Boundaries
+
+- Sources for either side of a diff: `dir:<tree>`, `git:<ref>`, `database:<url|$ENV>`, `dump:<file.sql>`, `catalog:<snapshot.json>`.
+- Data statements (`INSERT`/`UPDATE`/`DELETE`/`DO`) and enum reordering/removal are hand-authored migrations — validate them with `check` and `verify`; the enum recipe is in `docs/hints.md`.
+- Keep `transactionMode: "per-migration"` for transactional runners; `CREATE INDEX CONCURRENTLY` is blocked under `supabase-auto` and splits to a `.concurrent.sql` companion under `adapter: "postgres"`.
+- `supaschema explain <SUPA_CODE>` decodes any diagnostic offline.

package/.claude/hooks/block-generated-migration-edits.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+
+const lineageMarker = "-- supaschema: lineage ";
+const editTools = new Set(["Edit", "MultiEdit", "Write"]);
+
+try {
+  const payload = JSON.parse(readFileSync(0, "utf8"));
+  const toolName = typeof payload?.tool_name === "string" ? payload.tool_name : "";
+  const filePath =
+    typeof payload?.tool_input?.file_path === "string" ? payload.tool_input.file_path : "";
+  if (!editTools.has(toolName) || !filePath.endsWith(".sql")) {
+    process.exit(0);
+  }
+  let existing = "";
+  try {
+    existing = readFileSync(filePath, "utf8");
+  } catch {
+    process.exit(0);
+  }
+  if (!existing.includes(lineageMarker)) {
+    process.exit(0);
+  }
+  process.stderr.write(
+    `${filePath} is a supaschema-generated migration (lineage marker present). ` +
+      "Do not hand-edit it: change the declarative schema tree, delete this file if it is stale, " +
+      "and regenerate with `supaschema diff`. See .claude/rules/supaschema.md.\n",
+  );
+  process.exit(2);
+} catch {
+  process.exit(0);
+}

package/.claude/rules/supaschema.md

@@ -0,0 +1,22 @@
+---
+description: Generated-migration ownership and supaschema workflow policy for schema changes.
+---
+
+# supaschema Migration Policy
+
+## Contract
+
+This rule owns how schema migrations are produced and protected in a repo that uses supaschema: migrations are generated from the declarative tree, generated artifacts are never hand-edited, destructive intent is hint-gated, and verification mirrors the migration runner. The repeatable command workflow lives in the `supaschema` skill; write-time enforcement is hook-owned.
+
+## Rules
+
+- Schema intent changes only in the declarative SQL tree (e.g. `supabase/schemas/**`). Render the migration with `supaschema diff`; do not hand-author migration SQL for changes the tree can express.
+- Any `.sql` file containing the `-- supaschema: lineage` marker is a generated artifact. Never edit it; edit the tree and regenerate. The PreToolUse hook blocks such edits in both Claude and Codex runtimes.
+- Never overwrite a migration file. supaschema writes no-clobber (`SUPA_DIFF_OUTPUT_EXISTS`); a stale file is deleted deliberately, not clobbered.
+- Honor the lineage chain gate: `SUPA_DIFF_LINEAGE_BROKEN` means diff from the post-migration state (`--from database:<applied db>`), `SUPA_DIFF_LINEAGE_DUPLICATE` means the change is already pending. `--no-check-chain` requires explicit human approval.
+- Destructive operations (drops, table/type replacements, column drops, column type changes, incompatible view/routine replacements) stay blocked until the exact object key is added to `hints.destructive` after reviewing the rendered SQL. `"*"` never lands in committed config. A hinted table replace is not data-preserving; prefer the column ALTER lane the planner renders.
+- Renames are declared in `hints.renames`, never inferred. Kind changes and cross-schema moves are unsupported by design.
+- Run `supaschema check` on every generated or hand-authored migration. Run `supaschema verify` before merge when a database is reachable; keep `transactionMode: "per-migration"` for transactional runners such as `supabase db push`.
+- `CREATE INDEX CONCURRENTLY` is blocked under `adapter: "supabase-auto"`; under `adapter: "postgres"` it lands in the `.concurrent.sql` companion, which runs outside a transaction through an operational lane.
+- Database URLs resolve flag (`$ENV` indirection supported) > named `config.environments` entry via `--env` > `SUPASCHEMA_DATABASE_URL` > nearest `supabase/config.toml`. Do not hard-code connection strings in scripts, config, or CI.
+- Decode any `SUPA_*` diagnostic with `supaschema explain <CODE>`; recovery procedures live in `docs/hints.md`.

package/.claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-generated-migration-edits.mjs",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/.claude/skills/supaschema/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: supaschema
+description: Generate, check, and verify replay-safe PostgreSQL/Supabase migrations from declarative SQL tree diffs with supaschema. Use when schema changes are requested, migrations must be created or validated, schema drift needs detection, or a supaschema diagnostic (SUPA_*) blocks a plan.
+---
+
+# supaschema Migration Workflow
+
+## Contract
+
+This skill is a direct execution contract for producing schema migrations with supaschema. Follow the workflow in order; do not hand-author migration SQL for changes the declarative tree can express, and never edit a generated migration (the `-- supaschema: lineage` marker) by hand.
+
+## Workflow
+
+1. **Edit the declarative tree** (`supabase/schemas/**` or the project's configured tree) to express the desired end state. Use schema-qualified object names.
+2. **Generate the migration:**
+
+   ```bash
+   supaschema diff
+   ```
+
+   Zero-flag defaults (printed to stderr; flags override): `--from` resolves to the database (then `git:HEAD`), `--to` to the config schema tree, and the file lands in `config.migrationsDir` as `<UTC timestamp>_<derived name>.sql`. Pass `--name <snake_case>` to control the name. The write is no-clobber and chain-gated. If it exits 2, read the diagnostic:
+   - `SUPA_PLAN_DESTRUCTIVE_HINT_REQUIRED` / `SUPA_PLAN_COLUMN_ALTER_HINT_REQUIRED` / `SUPA_PLAN_VIEW_REPLACE_INCOMPATIBLE` / `SUPA_PLAN_ROUTINE_RETURN_TYPE_CHANGED` — review the rendered `-- BLOCKED` section, then add the exact object key to `hints.destructive` in `supaschema.config.json` and regenerate. Never use `"*"` in committed config.
+   - `SUPA_DIFF_LINEAGE_BROKEN` — a pending generated migration exists; diff from the post-migration state instead: `--from database:<db with pending applied>`.
+   - `SUPA_DIFF_LINEAGE_DUPLICATE` — the transition is already pending; apply or remove the pending migration instead of regenerating.
+   - Renames: declare `{ "from": "<key>", "to": "<key>" }` in `hints.renames`; renames are never inferred.
+
+3. **Check replay safety:** `supaschema check` gates every `.sql` in the migrations directory (or name specific files) — must exit 0 for generated and hand-authored migrations alike.
+4. **Verify execution** (when any database is resolvable — the URL auto-resolves from `SUPASCHEMA_DATABASE_URL` or the nearest `supabase/config.toml`):
+
+   ```bash
+   supaschema verify
+   ```
+
+   Defaults to the newest pending migration in the migrations directory with the same from/to defaults as `diff`; pass `--migration <file>` to verify a specific one.
+
+   Add `--ensure-roles` when the migration grants to roles a bare PostgreSQL server lacks (e.g. `authenticated`). A fingerprint mismatch itemizes the differing objects in the diagnostic hint.
+
+5. **Commit** the tree change, the generated migration, and the refreshed types file together. supaschema never stages or applies; the migration runner (e.g. `supabase db push`) owns the database. TypeScript types come from the tree (`supaschema types` creates `database.types.ts`; every later `diff` refreshes it) — never wait for a deploy or run introspection-based typegen to get correct types.
+
+## Drift Detection
+
+```bash
+supaschema diff --fail-on-diff --quiet
+```
+
+Exit 3 means the live database and the tree have diverged; exit 0 means parity. Use this as a CI gate (`docs/ci.md` has the full pipeline recipe).
+
+When drift is large or blocked, triage before editing:
+
+- `supaschema diff --summary` — operation/diagnostic counts grouped by kind and schema, printed even when the plan is blocked.
+- `supaschema diff --write-hints <file>` — writes the gated destructive object keys as a reviewable `hints.destructive` skeleton (no-clobber).
+- `supaschema audit --from <source> [--json]` — modeled coverage by kind/schema plus every statement outside the contract grouped by diagnostic code.
+- `supaschema selfcheck` — re-extracts a live catalog's rendered SQL and reports any object whose identity diverges (`SUPA_SELFCHECK_*`); zero mismatches proves cross-lane identity parity.
+- `supaschema migrations` — classifies on-disk migrations against a target's applied history: applied, pending, ghost, or out-of-order.
+
+## Boundaries
+
+- Sources for either side of a diff: `dir:<tree>`, `git:<ref>`, `database:<url|$ENV>`, `dump:<file.sql>`, `catalog:<snapshot.json>`.
+- Data statements (`INSERT`/`UPDATE`/`DELETE`/`DO`) and enum reordering/removal are hand-authored migrations — validate them with `check` and `verify`; the enum recipe is in `docs/hints.md`.
+- Keep `transactionMode: "per-migration"` for transactional runners; `CREATE INDEX CONCURRENTLY` is blocked under `supabase-auto` and splits to a `.concurrent.sql` companion under `adapter: "postgres"`.
+- `supaschema explain <SUPA_CODE>` decodes any diagnostic offline.

package/.codex/hooks/supaschema-tool-gate.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const lineageMarker = "-- supaschema: lineage ";
+const updateHeader = "*** Update File: ";
+const deleteHeader = "*** Delete File: ";
+const addHeader = "*** Add File: ";
+
+function patchTargets(patchText) {
+  const updates = [];
+  const deletes = [];
+  const adds = new Set();
+  for (const line of patchText.split("\n")) {
+    if (line.startsWith(updateHeader)) {
+      updates.push(resolve(line.slice(updateHeader.length).trim()));
+    } else if (line.startsWith(deleteHeader)) {
+      deletes.push(resolve(line.slice(deleteHeader.length).trim()));
+    } else if (line.startsWith(addHeader)) {
+      adds.add(resolve(line.slice(addHeader.length).trim()));
+    }
+  }
+  const rewrites = deletes.filter((path) => adds.has(path));
+  return [...updates, ...rewrites];
+}
+
+function editTargets(payload) {
+  const toolName = typeof payload?.tool_name === "string" ? payload.tool_name : "";
+  const input = payload?.tool_input ?? {};
+  if (toolName === "apply_patch") {
+    const patch = typeof input.patch === "string" ? input.patch : (input.input ?? "");
+    return typeof patch === "string" ? patchTargets(patch) : [];
+  }
+  if (typeof input.file_path === "string" && input.file_path.length > 0) {
+    return [input.file_path];
+  }
+  return [];
+}
+
+function isGeneratedMigration(path) {
+  if (!path.endsWith(".sql")) {
+    return false;
+  }
+  try {
+    return readFileSync(path, "utf8").includes(lineageMarker);
+  } catch {
+    return false;
+  }
+}
+
+function emit(result) {
+  process.stdout.write(JSON.stringify(result));
+  process.exit(0);
+}
+
+try {
+  const payload = JSON.parse(readFileSync(0, "utf8"));
+  const blocked = editTargets(payload).find((path) => isGeneratedMigration(path));
+  if (!blocked) {
+    emit({});
+  }
+  emit({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: `${blocked} is a supaschema-generated migration (lineage marker present). Do not hand-edit it: change the declarative schema tree, delete this file if it is stale, and regenerate with \`supaschema diff\`. See .claude/rules/supaschema.md.`,
+    },
+  });
+} catch (error) {
+  emit({
+    systemMessage: `supaschema-tool-gate hook error (fail-open): ${error instanceof Error ? error.message : String(error)}`,
+  });
+}

package/.codex/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/supaschema-tool-gate.mjs\"",
+            "timeout": 10,
+            "statusMessage": "Checking supaschema generated-migration policy"
+          }
+        ]
+      }
+    ]
+  }
+}

package/.codex/rules/supaschema.rules

@@ -0,0 +1,22 @@
+# supaschema migration policy (Codex rules surface).
+# Enforcement: write-time denial of hand-edits to generated migrations is
+# owned by .codex/hooks/supaschema-tool-gate.mjs (PreToolUse). This file
+# carries the policy text for review and prompting.
+#
+# - Schema intent changes only in the declarative SQL tree; render migrations
+#   with `supaschema diff`, never hand-author SQL the tree can express.
+# - A .sql file containing the `-- supaschema: lineage` marker is a generated
+#   artifact: change the tree and regenerate; never hand-edit it.
+# - Migration writes are no-clobber, and the lineage chain gate must not be
+#   bypassed with --no-check-chain without explicit human approval.
+# - Destructive changes (drops, column type changes, incompatible view or
+#   routine replacements) require the exact object key in hints.destructive
+#   after reviewing the rendered SQL; never commit "*".
+# - Run `supaschema check` on every migration; run `supaschema verify` before
+#   merge when a database is reachable. Keep transactionMode per-migration
+#   for transactional runners such as `supabase db push`.
+# - Database URLs resolve flag > named config.environments entry via --env >
+#   SUPASCHEMA_DATABASE_URL > the nearest supabase/config.toml; do not
+#   hard-code connection strings.
+# - Decode any SUPA_* diagnostic with `supaschema explain <CODE>`; recovery
+#   steps live in docs/hints.md.

package/AGENTS.md

@@ -0,0 +1,40 @@
+# supaschema Agent Brief
+
+## Contract
+
+This file is the operator brief for AI agents working in this repository or in a repository that uses supaschema. Durable policy lives in `.claude/rules/supaschema.md`; the repeatable workflow lives in `.claude/skills/supaschema/SKILL.md`; write-time enforcement lives in `.claude/hooks/**` and `.codex/hooks/**`.
+
+supaschema generates deterministic, replay-safe PostgreSQL/Supabase migrations from declarative SQL tree diffs. It is a generator and prover only: it never stages, commits, or applies to a tracked database.
+
+## Invariants
+
+- Migrations are generated, never hand-authored. Schema intent changes in the declarative tree (`supabase/schemas/**` or the project's tree); `supaschema diff` renders the migration.
+- A `.sql` file containing the `-- supaschema: lineage` marker is a generated artifact. Never edit it by hand — change the source tree and regenerate. Hooks in both agent runtimes block such edits.
+- Destructive intent is explicit. Drops, column type changes, and PostgreSQL-incompatible replacements stay blocked until the exact object key is added to `hints.destructive` after review. Never add `"*"` to committed config.
+- Verification must match the runner: keep `transactionMode: "per-migration"` for `supabase db push`-style runners. Run `supaschema check` always and `supaschema verify` before merge when a database is reachable.
+- Respect the lineage chain gate. When `diff` refuses with `SUPA_DIFF_LINEAGE_BROKEN` or `SUPA_DIFF_LINEAGE_DUPLICATE`, regenerate from the post-migration state (`--from database:<applied db>`); `--no-check-chain` is for explicit human-approved bypasses only.
+- Database URLs are never hard-coded: flag (`$ENV` supported) > named `config.environments` entry via `--env` > `SUPASCHEMA_DATABASE_URL` > auto-discovery from the nearest `supabase/config.toml`.
+- `supaschema explain <CODE>` decodes any `SUPA_*` diagnostic offline; `docs/hints.md` has recovery steps for blocked plans.
+
+## Common Commands
+
+Zero-flag defaults: `--from` resolves to the database (then `git:HEAD`), `--to` to the config schema tree, output to `config.migrationsDir` with a derived name, `check` to the whole migrations directory, `verify --migration` to the newest pending file. Applied defaults print to stderr; flags override.
+
+```bash
+supaschema diff                          # render the migration from applied state -> schema tree (refreshes the types file when present)
+supaschema check                         # replay-safety gate for the migrations directory
+supaschema verify                        # apply-twice proof for the newest pending migration
+supaschema types                         # Supabase-compatible TypeScript types + Zod validators from the tree; no database or introspection
+supaschema diff --fail-on-diff --quiet   # CI drift gate (exit 3 on drift)
+supaschema diff --summary                # blocked-plan triage: operation/diagnostic counts by kind and schema
+supaschema diff --write-hints <file>     # reviewable hints.destructive skeleton for gated keys
+supaschema audit --from <source>         # support-matrix coverage + out-of-contract statements by code
+supaschema selfcheck                     # cross-lane identity parity proof against a live catalog (SUPA_SELFCHECK_*)
+supaschema migrations                    # applied/pending/ghost/out-of-order vs history table
+```
+
+## Repository Development (supaschema itself)
+
+- `npm run check` — lint + typecheck + tests + build; database-gated suites auto-resolve a URL or skip.
+- `npm run fixture:verify` / `npm run benchmark` — execution proof and threshold-enforced performance lanes.
+- Source is AST-only: statement classification and SQL mutation come from `libpg-query` parse trees, never regex over SQL.