supaschema 0.1.0-rc.1

package/docs/config.md

@@ -0,0 +1,72 @@
+# Configuration Reference
+
+`supaschema` looks for config in this order:
+
+1. `--config <path>` (`.json`, `.mjs`, or `.js` with a default export)
+2. `supaschema.config.json` in the working directory
+3. `supaschema.config.mjs`, then `supaschema.config.js`
+4. Built-in defaults
+
+Unknown keys are rejected (the schema is strict), so typos fail loudly. The scaffolded config carries a `$schema` pointer at the shipped `config-schema.json` (generated from the Zod schema at build time), so editors autocomplete and validate every key.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `$schema` | scaffolded | JSON Schema pointer for editor tooling; ignored by the loader. |
+| `adapter` | `"supabase-auto"` | `supabase-auto` blocks managed Supabase schemas as declarative owners and blocks `CREATE INDEX CONCURRENTLY` plans; `postgres` disables those policies. |
+| `cascade` | `"never"` | `CASCADE` is never emitted. This is not configurable away. |
+| `destructiveChanges` | `"hint-required"` | `hint-required` blocks destructive operations until the object key is listed in `hints.destructive`; `block` always blocks; `allow` permits everything (not recommended). |
+| `environments` | `{}` | Named database targets for the global `--env` flag: `{ "staging": { "databaseUrl": "$STAGING_DB" } }` lets `supaschema --env staging diff ...` resolve the URL (with `$ENV_NAME` indirection) without repeating it per command. |
+| `excludedGrantRoles` | `[]` | Grants and default privileges whose grantee or `FOR ROLE` matches are removed from extracted models (useful for platform roles such as `supabase_admin`). |
+| `hints.destructive` | `[]` | Exact object keys (or `"*"`) approved for destructive drop/replace. |
+| `hints.renames` | `[]` | `{ "from": "<object key>", "to": "<object key>" }` pairs rendered as guarded `ALTER ... RENAME`. |
+| `idempotency` | `"required"` | Rendered SQL is replay-safe by construction. Not configurable away. |
+| `lockTimeout` | `"5s"` | Value for the `SET lock_timeout` migration preamble. |
+| `managedSchemas` | Supabase set | Schemas treated as platform-owned under `supabase-auto`. |
+| `migrationsDir` | `"supabase/migrations"` | Where zero-flag `diff` writes migrations, zero-arg `check` reads them, and `verify` finds the newest pending file. The `--migrations-dir` flag overrides per command. |
+| `typesFile` | `"database.types.ts"` | Where `supaschema types` writes generated TypeScript types. When the file exists, every `diff` that writes a migration regenerates it from the target tree. |
+| `zodFile` | `"database.zod.ts"` | Where `supaschema types` writes generated runtime Zod validators (requires `zod` in the consuming project). Refreshed by `diff` on the same exists-means-opted-in rule as `typesFile`. |
+| `normalize` | `"deparse"` | Every object's SQL is rewritten into canonical form via `pgsql-deparser` (the pure-TypeScript companion of the `libpg-query` parser). Fidelity-gated per object: the canonical text is used only when it reparses to the identical location-stripped parse tree, otherwise the source text is kept with a `SUPA_NORMALIZE_*` warning. Hashes never change (identity is AST-based); rendered output is formatting-independent. Set `"off"` to keep source spelling verbatim. `check` always runs the round-trip proof and reports `SUPA_CHECK_DEPARSE_*` findings regardless of this setting. |
+| `postgresVersion` | `"15+"` | Documentation of the supported floor; guards target PostgreSQL 15+ syntax. |
+| `renameDetection` | `"hints-only"` | `hints-only` uses `hints.renames`; `off` disables rename handling entirely. |
+| `schemaPaths` | `["supabase/schemas"]` | Paths read by `git:` sources and the default `--to dir:` target (the first entry). `supabase/config.toml` is read only to discover the local database URL (`[db] port`), never for schema paths; configure paths here. |
+| `schemas.include` / `schemas.exclude` | `[]` | Persistent schema filters applied to every extracted model (the CLI `--schema` flag composes on top). |
+| `statementTimeout` | `"60s"` | Value for the `SET statement_timeout` migration preamble. |
+| `transactionMode` | `"per-migration"` | How `verify` applies the migration and how transaction hazards are graded. `per-migration` mirrors runners like `supabase db push` (one transaction per file); `per-statement` matches autocommit runners. |
+| `verify --ensure-roles` (CLI) | off | Pre-creates missing `NOLOGIN` roles referenced by grants, default privileges, and policies on the verification server. Roles are cluster-level and are never dropped. |
+| `validators` | `["internal-parser"]` | Additional external validators to run during `check` (see below). |
+
+## Validators
+
+`internal-parser` is always the correctness owner. Optional external validators run as subprocesses during `check` and `verify`:
+
+- `squawk` / `squawk-cli` — runs the `squawk` binary
+- `pgls` / `postgres-language-server` / `@postgres-language-server/cli` — runs `postgres-language-server check`
+- `sqlfluff` — runs the external Python `sqlfluff lint --dialect postgres`
+- `pg-formatter` / `pgformatter` — runs `pg-formatter --check`
+
+A configured validator that is not installed produces `SUPA_VALIDATOR_UNAVAILABLE` as an error: configured checks may not silently skip.
+
+## Example
+
+```json
+{
+  "destructiveChanges": "hint-required",
+  "excludedGrantRoles": [
+    "supabase_admin",
+    "supabase_auth_admin",
+    "supabase_storage_admin",
+    "dashboard_user",
+    "pgbouncer",
+    "authenticator"
+  ],
+  "hints": {
+    "destructive": ["table:app.legacy_imports"],
+    "renames": [{ "from": "table:app.accounts", "to": "table:app.customers" }]
+  },
+  "lockTimeout": "5s",
+  "schemas": { "exclude": [], "include": ["app", "public"] },
+  "statementTimeout": "60s",
+  "transactionMode": "per-migration",
+  "validators": ["internal-parser", "squawk"]
+}
+```

package/docs/corpus.md

@@ -0,0 +1,33 @@
+# The corpus oracle
+
+`supaschema corpus` exists because of the oracle problem: every other gate in this package compares supaschema to itself. `verify` builds both temporary databases from the engine's own models, so a modeling error that is symmetric in the models produces two identically-wrong databases — fingerprints match and the bug ships. Fixtures only contain constructs their author thought of, while real catalogs carry state no tree ever declares: materialized default ACL entries, `pg_init_privs` baselines, executor-role-attributed default privileges, statement-order grant churn.
+
+The corpus is an independently-evolved, deliberately dirty database. The lane:
+
+1. Create a disposable database and apply `roles.sql` (the minimal platform role contract — applied by the runner over the wire, never by Docker volume mounts, so it works identically in CI service containers and local runs).
+2. Replay `migrations/*.sql` in version order, one transaction per file (mirroring `supabase db push`). These migrations deliberately deposit catalog noise: explicit grants that materialize `proacl` default entries, no-op revokes that leave no trace, default-ACL rows, RLS facet pairs, serial decomposition with hostile quoting, grant-then-revoke churn.
+3. Cross-lane diff the dirty database against `tree/` (the same end state in clean declarative spelling, plus intended pending work) and render the reconciliation under `corpus.json`.
+4. Static-check the rendered migration, then apply it twice — the second apply must leave the catalog fingerprint unchanged.
+5. Re-diff the database against the tree: the residual must be zero operations (`SUPA_CORPUS_RECONVERGENCE` otherwise). A correct diff engine must converge; false drift cannot.
+
+## Running it
+
+```sh
+npm run corpus:check
+# or
+supaschema corpus --corpus-dir corpus/supabase-style [--database-url <url>] [--json]
+```
+
+The database URL resolves like every other command (flag, then `SUPASCHEMA_DATABASE_URL`, then the nearest `supabase/config.toml`). Without a resolvable URL the command prints a skip notice and exits 0, so OS-matrix CI jobs without a database pass through. Non-local hosts are refused unless `SUPASCHEMA_CORPUS_ALLOW_REMOTE=1`.
+
+## Regression-corpus discipline
+
+Every future false-drift or parity bug adds its statement class to the corpus in the same change that fixes it: the triggering DDL goes into `corpus/supabase-style/migrations/`, the clean declarative spelling goes into `tree/`, and `npm run corpus:check` must converge. The corpus is the living inventory of every noise class the engine has ever mishandled.
+
+## Bring your own corpus
+
+`--corpus-dir` accepts any directory with the same four pieces (`roles.sql`, `migrations/`, `tree/`, `corpus.json`), so a consuming repository can maintain its **own** corpus pinning the noise classes from its own incidents: when a diff misbehaves on your schema, copy the triggering DDL into your corpus migrations, express the same end state in your corpus tree, and wire `supaschema corpus --corpus-dir <your-corpus>` into your CI. The shipped `corpus/supabase-style` keeps protecting the engine; yours keeps protecting your schema's specific shapes.
+
+## Scope
+
+The corpus lane proves engine correctness against dirty-real state. It does not replace the repo-side drift gate: continuous assurance for an actual repository is `supaschema diff --fail-on-diff` plus `supaschema migrations` against the live database, which detect when that repo's tree and databases diverge. Corpus = is the engine right; drift gate = is the repo in sync.

package/docs/diagnostics.md

@@ -0,0 +1,77 @@
+# Diagnostics
+
+Diagnostics have `code`, `severity`, `message`, and optional `ref`, `file`, `statement`, and `hint` fields.
+
+| Code | Severity | Meaning |
+| --- | --- | --- |
+| `SUPA_PARSE_ERROR` | error | `libpg-query` could not parse the SQL. |
+| `SUPA_PARSE_UNAVAILABLE` | warning | The parser dependency did not expose an expected parser function. |
+| `SUPA_EXTRACT_PARSER_REQUIRED` | error | AST extraction requires the `libpg-query` parser; there is no regex fallback. |
+| `SUPA_EXTRACT_UNSUPPORTED` | error | The source contains DDL that `supaschema` cannot model safely. |
+| `SUPA_EXTRACT_DUPLICATE_OBJECT` | error | Two source statements claim the same object identity. |
+| `SUPA_EXTRACT_SIDE_EFFECT_UNSUPPORTED` | error | The source contains a data/control-plane side-effect statement that is not a replay-safe schema object. |
+| `SUPA_OBJECT_PARSE_FAILED` | error | Object SQL did not parse, so its identity hash fell back to normalized text. |
+| `SUPA_SUPABASE_MANAGED_SCHEMA` | error | A Supabase-managed schema was edited as declarative source. |
+| `SUPA_SUPABASE_VIEW_SECURITY_INVOKER` | warning | A view in an exposed schema does not set `security_invoker`, so RLS applies as the view owner. |
+| `SUPA_CATALOG_EXTRACT_FAILED` | error | Catalog extraction failed against the supplied database. |
+| `SUPA_CATALOG_SNAPSHOT_VERSION` | warning | A `catalog:` snapshot was produced by a different supaschema model version; regenerate it to keep hashes comparable. |
+| `SUPA_OBJECT_PARSE_FAILED` | error | Object SQL did not parse, so its identity hash fell back to normalized text. |
+| `SUPA_DIFF_LINEAGE_BROKEN` | error | The plan's from-state does not continue the newest pending supaschema migration in the output directory. |
+| `SUPA_DIFF_LINEAGE_DUPLICATE` | error | A pending supaschema migration already covers this exact from/to transition. |
+| `SUPA_DIFF_OUTPUT_EXISTS` | error | The output migration file already exists; supaschema never overwrites migrations. |
+| `SUPA_PLAN_DESTRUCTIVE_HINT_REQUIRED` | error | A destructive change lacks an explicit hint. |
+| `SUPA_PLAN_ADD_COLUMN_UNSAFE` | error | An additive column change needs explicit migration review. |
+| `SUPA_PLAN_COLUMN_ALTER_HINT_REQUIRED` | error | Column drops and type changes render data-preserving ALTERs only after a destructive-change hint. |
+| `SUPA_PLAN_DEPENDENCY_CYCLE` | error | Dependency ordering produced a cycle. |
+| `SUPA_PLAN_EMPTY_WITH_DRIFT` | error | The plan has no operations but the model fingerprints differ; an empty migration would silently mask real drift. |
+| `SUPA_PLAN_RENAME_HINT_UNMATCHED` | error | A rename hint did not match both source and target objects. |
+| `SUPA_PLAN_RENAME_KIND_MISMATCH` | error | A rename hint maps between different object kinds. |
+| `SUPA_PLAN_RENAME_SET_SCHEMA_UNSUPPORTED` | error | A rename hint attempts to move an object between schemas. |
+| `SUPA_PLAN_RENAME_UNSUPPORTED` | error | The object kind cannot yet be renamed safely by the renderer. |
+| `SUPA_PLAN_RENAME_VERIFY_REQUIRED` | warning | Rename output must be verified against PostgreSQL before release. |
+| `SUPA_PLAN_ROUTINE_RETURN_TYPE_CHANGED` | error | The routine's return type or OUT parameters changed; `CREATE OR REPLACE` cannot apply it without a hinted drop. |
+| `SUPA_PLAN_VIEW_REPLACE_INCOMPATIBLE` | error | The view drops, renames, or reorders output columns; `CREATE OR REPLACE VIEW` cannot apply it without a hinted drop. |
+| `SUPA_PLAN_VIEW_REPLACE_VERIFY_REQUIRED` | warning | View output columns are statically unknowable; verify the replacement against PostgreSQL rules. |
+| `SUPA_PLAN_CONCURRENT_INDEX_UNSUPPORTED` | error | `CREATE INDEX CONCURRENTLY` cannot run inside the transaction the migration runner uses. |
+| `SUPA_CHECK_CASCADE` | error | `CASCADE` appears in migration SQL. |
+| `SUPA_CHECK_DROP_IF_EXISTS` | error | A `DROP` statement lacks `IF EXISTS`. |
+| `SUPA_CHECK_CREATE_SCHEMA_GUARD` | error | `CREATE SCHEMA` lacks `IF NOT EXISTS` or a catalog guard. |
+| `SUPA_CHECK_CREATE_EXTENSION_GUARD` | error | `CREATE EXTENSION` lacks `IF NOT EXISTS` or a catalog guard. |
+| `SUPA_CHECK_CREATE_TABLE_GUARD` | error | `CREATE TABLE` lacks `IF NOT EXISTS` or a catalog guard. |
+| `SUPA_CHECK_CREATE_SEQUENCE_GUARD` | error | `CREATE SEQUENCE` lacks `IF NOT EXISTS` or a catalog guard. |
+| `SUPA_CHECK_CREATE_INDEX_GUARD` | error | `CREATE INDEX` lacks `IF NOT EXISTS` or a catalog guard. |
+| `SUPA_CHECK_CREATE_MATERIALIZED_VIEW_GUARD` | error | `CREATE MATERIALIZED VIEW` lacks `IF NOT EXISTS` or a catalog guard. |
+| `SUPA_CHECK_CREATE_VIEW_REPLACE` | error | `CREATE VIEW` lacks `OR REPLACE`. |
+| `SUPA_CHECK_CREATE_ROUTINE_REPLACE` | error | `CREATE FUNCTION` or `CREATE PROCEDURE` lacks `OR REPLACE`. |
+| `SUPA_CHECK_CREATE_TYPE_GUARD` | error | `CREATE TYPE` or `CREATE DOMAIN` is not wrapped in a catalog guard. |
+| `SUPA_CHECK_ADD_CONSTRAINT_GUARD` | error | `ALTER TABLE ... ADD CONSTRAINT` is not wrapped in a catalog guard. |
+| `SUPA_CHECK_CREATE_TRIGGER_REPLACEMENT` | error | `CREATE TRIGGER` is not preceded by `DROP TRIGGER IF EXISTS`. |
+| `SUPA_CHECK_SEARCH_PATH` | error | Migration SQL depends on session `search_path`. |
+| `SUPA_CHECK_SECURITY_DEFINER_SEARCH_PATH` | warning | A `SECURITY DEFINER` function lacks function-local `SET search_path`. |
+| `SUPA_CHECK_ENUM_VALUE_USE_SAME_TRANSACTION` | error/warning | An enum value added in this migration is used later in the same file; transactional runners fail. Error under `transactionMode: "per-migration"`, warning under `per-statement`. |
+| `SUPA_CHECK_NONTRANSACTIONAL_INDEX` | error/warning | `CREATE INDEX CONCURRENTLY` needs transaction wrapping disabled. Error under `supabase-auto` or `per-migration` mode. |
+| `SUPA_CHECK_NONTRANSACTIONAL_REFRESH` | error/warning | `REFRESH MATERIALIZED VIEW CONCURRENTLY` needs transaction wrapping disabled. Error under `supabase-auto` or `per-migration` mode. |
+| `SUPA_CHECK_ALTER_COLUMN_TYPE_REWRITE` | warning | `ALTER COLUMN TYPE` can rewrite the table under an `ACCESS EXCLUSIVE` lock. |
+| `SUPA_CHECK_SET_NOT_NULL_SCAN` | warning | `SET NOT NULL` scans the table unless a validated `CHECK` constraint already proves it. |
+| `SUPA_CHECK_DEPARSE_MISMATCH` | warning | A statement does not round-trip through the deparser to an identical parse tree; `normalize: "deparse"` would keep its source text. |
+| `SUPA_CHECK_DEPARSE_UNSUPPORTED` | warning | A statement cannot be deparsed for the round-trip proof. |
+| `SUPA_NORMALIZE_FIDELITY` | warning | Deparsed SQL did not reparse to the identical parse tree; the object kept its source text under `normalize: "deparse"`. |
+| `SUPA_NORMALIZE_UNSUPPORTED` | warning | The deparser cannot render this object; it kept its source text under `normalize: "deparse"`. |
+| `SUPA_CORPUS_RECONVERGENCE` | error | The corpus oracle did not converge: residual operations remain after applying the rendered reconciliation to the dirty corpus database, the second apply changed the catalog, or a pipeline stage failed (see `docs/corpus.md`). |
+| `SUPA_CHECK_VOLATILE_DEFAULT_REWRITE` | warning | `ADD COLUMN` with a volatile default rewrites the whole table. |
+| `SUPA_CHECK_INSERT_ON_CONFLICT` | error | `INSERT` statements in migrations must use `ON CONFLICT` for replay safety. |
+| `SUPA_CHECK_DML_REVIEW` | warning | `UPDATE`/`DELETE` statements need explicit idempotency review. |
+| `SUPA_CHECK_POLICY_REPLACEMENT` | error | `CREATE POLICY` should be paired with an explicit prior drop for replacement. |
+| `SUPA_SELFCHECK_HASH_MISMATCH` | error | A catalog object hashes differently after its rendered SQL is re-extracted; cross-lane diffs would report a false change. |
+| `SUPA_SELFCHECK_MISSING` | error | A catalog object disappeared when its rendered SQL was re-extracted. |
+| `SUPA_SELFCHECK_UNEXPECTED` | error | Re-extraction produced an object the catalog model does not contain. |
+| `SUPA_VALIDATOR_FAILED` | error | A configured external validator reported diagnostics. |
+| `SUPA_VALIDATOR_UNAVAILABLE` | error | A configured external validator binary was not found. |
+| `SUPA_VALIDATOR_UNKNOWN` | error | The config references an unknown validator. |
+| `SUPA_VERIFY_CLEANUP_FAILED` | warning | A temporary verification database could not be dropped and may need manual removal. |
+| `SUPA_VERIFY_FINGERPRINT_MISMATCH` hints | — | The mismatch hint names the differing objects: missing from the migration result, not present in the target, and definition differs. |
+| `SUPA_VERIFY_FAILED` | error | Temporary database verification failed. |
+| `SUPA_VERIFY_FINGERPRINT_MISMATCH` | error | Applying the migration twice did not produce the target catalog fingerprint. |
+| `SUPA_VERIFY_ROLE_CAPABILITY` | error | The verification role cannot `CREATE DATABASE`; use a role with `CREATEDB` (on local Supabase stacks prefer `supabase_admin`). |
+| `SUPA_VERIFY_STUB_REFERENCE` | warning | A `verify` failure under `--ensure-environment` references a Supabase-managed schema that the environment stub only provisions minimally; the failure may be a stub limitation rather than a real migration defect. Re-run against a real Supabase database to confirm. |
+| `SUPA_VERIFY_RECONVERGENCE` | error | The migrated catalog cross-lane diffed against the target model is not empty; the model declares state the catalog cannot reproduce (false drift), or lane parity is broken. |

package/docs/hints.md

@@ -0,0 +1,92 @@
+# Hints Guide
+
+`supaschema` fails closed when intent cannot be proven from the SQL parse tree. Hints are the explicit, reviewable way to state intent.
+
+## Destructive changes
+
+A blocked plan looks like this:
+
+```
+ERROR SUPA_PLAN_DESTRUCTIVE_HINT_REQUIRED [table:app.legacy_imports]: drop of table requires an explicit destructive-change hint
+  hint: Add "table:app.legacy_imports" to hints.destructive only after reviewing the migration.
+```
+
+Recovery: review the rendered `-- BLOCKED` section, confirm the drop is intended, then add the exact object key:
+
+```json
+{
+  "hints": {
+    "destructive": ["table:app.legacy_imports"]
+  }
+}
+```
+
+`"*"` approves all destructive changes for one run; prefer exact keys in committed config.
+
+Dropped grants render as `REVOKE`, and dropped default privileges render as the reverse `ALTER DEFAULT PRIVILEGES ... REVOKE`, but both still require the destructive hint first.
+
+## Column drops and type changes
+
+When only columns change, the hinted plan renders data-preserving column ALTERs instead of replacing the table (`SUPA_PLAN_COLUMN_ALTER_HINT_REQUIRED`):
+
+- removed columns render `ALTER TABLE ... DROP COLUMN IF EXISTS`,
+- type changes render `ALTER COLUMN ... TYPE <type> USING <column>::<type>`,
+- `NOT NULL` and `DEFAULT` changes render without a hint.
+
+Identity/generated changes and table-constraint changes fall back to the replace lane. A hinted table **replace** drops and recreates the table — it is not data-preserving; prefer the column lane or hand-author the migration.
+
+## Incompatible view and routine replacements
+
+PostgreSQL rejects `CREATE OR REPLACE` when a view drops/renames/reorders output columns (`SUPA_PLAN_VIEW_REPLACE_INCOMPATIBLE`) or a routine changes its return type or OUT parameters (`SUPA_PLAN_ROUTINE_RETURN_TYPE_CHANGED`). Hinting the object key renders a guarded `DROP ... IF EXISTS` followed by the new definition. Dependent objects (views over views) must be hinted and recreated in the same plan.
+
+## Renames
+
+Without a hint, a rename diffs as drop+create (destructive, blocked). Declare the rename instead:
+
+```json
+{
+  "hints": {
+    "renames": [{ "from": "table:app.accounts", "to": "table:app.customers" }]
+  }
+}
+```
+
+The rendered SQL is a guarded `DO` block: it raises if both names exist, renames if only the old name exists, and is a no-op if the rename already happened. Rename hints:
+
+- must keep the same object kind (`SUPA_PLAN_RENAME_KIND_MISMATCH`),
+- must stay in the same schema (`SUPA_PLAN_RENAME_SET_SCHEMA_UNSUPPORTED`),
+- support schemas, tables, sequences, indexes, functions, procedures, views, and materialized views (`SUPA_PLAN_RENAME_UNSUPPORTED` otherwise),
+- always carry a `SUPA_PLAN_RENAME_VERIFY_REQUIRED` warning — run `supaschema verify`.
+
+## Object keys
+
+Keys follow `kind:schema.name`, with `(signature)` for functions/procedures and `:table` for table-scoped objects:
+
+```
+table:app.accounts
+function:app.greeting()
+policy:app.accounts_select:accounts
+index:app.accounts_email_idx:accounts
+grant:grant:table:app.accounts:authenticated
+```
+
+`supaschema plan` prints every operation key; copy keys from there rather than constructing them by hand.
+
+## Enum reordering and removal
+
+Enum value removal/reordering has no in-place ALTER in PostgreSQL. The hinted plan replaces the type (drop+create), which fails while columns depend on it. The safe hand-authored recipe is:
+
+```sql
+CREATE TYPE app.mood_next AS ENUM ('happy', 'curious');
+ALTER TABLE app.entries
+  ALTER COLUMN current TYPE app.mood_next
+  USING current::text::app.mood_next;
+DROP TYPE IF EXISTS app.mood;
+ALTER TYPE app.mood_next RENAME TO mood;
+```
+
+Validate it with `supaschema check` and `supaschema verify` like any hand-authored migration.
+
+## Changes that have no hint
+
+Data backfills and `CASCADE` drops have no hint lane by design. Hand-author those migrations and validate them with `supaschema check` and `supaschema verify`.

package/docs/release.md

@@ -0,0 +1,19 @@
+# Release
+
+The package is designed for npm trusted publishing from GitHub Actions.
+
+1. Create the public GitHub repository.
+2. Add the npm trusted publisher for the repository and release workflow.
+3. Push a tag or publish a GitHub release.
+4. Confirm CI passes lint, typecheck, tests, fixture diff, fixture verification, the corpus oracle (`npm run corpus:check`, dirty-real reconvergence), source-tree, dump, catalog-snapshot, large, live-catalog, shadow-round-trip, and replay-verification benchmarks, `npm pack`, global tarball install, and `npx` tarball smoke.
+5. Stamp the release date on the `0.1.0 (unreleased)` CHANGELOG heading in the release commit.
+
+The release workflow uses:
+
+- `permissions.id-token: write`
+- `actions/setup-node` with `registry-url: https://registry.npmjs.org`
+- `npm publish --access public`
+
+With npm trusted publishing, provenance is generated through the GitHub Actions OIDC trust relationship, so no long-lived npm token is required.
+
+Do not publish from a laptop for production releases.

package/docs/support-matrix.md

@@ -0,0 +1,57 @@
+# Support Matrix
+
+`supaschema` is fail-closed: unsupported DDL blocks migration generation instead of guessing. Extraction and checking are AST-only — every statement is classified through the PostgreSQL parser, never regex.
+
+| Object | Extract | Render | Notes |
+| --- | --- | --- | --- |
+| Schemas | Yes | `CREATE SCHEMA IF NOT EXISTS` / `DROP SCHEMA IF EXISTS` | Supabase-managed schemas are blocked in `supabase-auto`. |
+| Extensions | Yes | `CREATE EXTENSION IF NOT EXISTS` | Extension schema is fingerprint metadata. |
+| Types/enums | Yes | `DO` catalog guard / `DROP TYPE IF EXISTS`; appended enum values render as `ALTER TYPE ... ADD VALUE IF NOT EXISTS` | Enum narrowing, removal, or reordering is destructive. |
+| Domains | Yes | `DO` catalog guard / `DROP DOMAIN IF EXISTS` | Domain replacement is destructive. |
+| Tables | Yes | `CREATE TABLE IF NOT EXISTS`; additive columns use `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` | Unsafe column changes, table replacement, and table drop block. Standalone `ALTER COLUMN ... SET/DROP DEFAULT` folds into the table's canonical shape. |
+| Foreign data wrappers | Yes (whole-object) | `DO` catalog guard (no `IF NOT EXISTS` form upstream) / `DROP FOREIGN DATA WRAPPER IF EXISTS` | Drops and replaces are destructive-gated. Extension-owned wrappers are excluded from catalogs. |
+| Foreign servers | Yes (whole-object) | `CREATE SERVER IF NOT EXISTS` / `DROP SERVER IF EXISTS` | Drops and replaces are destructive-gated. |
+| Foreign tables | Yes (whole-object) | `CREATE FOREIGN TABLE IF NOT EXISTS` / `DROP FOREIGN TABLE IF EXISTS` | No column-level diffing; user mappings are excluded (credentials). |
+| Constraints | Yes | `DO` catalog guard / `DROP CONSTRAINT IF EXISTS` | External `ALTER TABLE ADD CONSTRAINT` is modeled separately. |
+| Indexes | Yes | `CREATE INDEX IF NOT EXISTS` | `CONCURRENTLY` emits transaction metadata. |
+| Sequences | Yes | `CREATE SEQUENCE IF NOT EXISTS` | Drop requires destructive hint. |
+| Functions/procedures | Yes | `CREATE OR REPLACE` / `DROP ... IF EXISTS` | Return-type incompatible replacements fail verification. |
+| Views | Yes | `CREATE OR REPLACE VIEW` | PostgreSQL-compatible replacement shape must be verified. |
+| Materialized views | Yes | `CREATE MATERIALIZED VIEW IF NOT EXISTS` | Replacement/drop requires destructive hint. |
+| Triggers | Yes | `DROP TRIGGER IF EXISTS` then create | Replacement is explicit. |
+| RLS | Yes | `ALTER TABLE ... ROW LEVEL SECURITY` | Removal/replacement is destructive. |
+| Policies | Yes | `DROP POLICY IF EXISTS` then create | PostgreSQL has no `CREATE OR REPLACE POLICY`. |
+| Grants/default privileges | Yes (structured per target × grantee) | Canonical `GRANT`; hinted removal renders `REVOKE` / reverse `ALTER DEFAULT PRIVILEGES ... REVOKE` | Split statements for one target × grantee aggregate into one privilege-set identity (full-set unions collapse to `ALL`); mixed `WITH GRANT OPTION` splits stay duplicate errors. |
+| Comments | Yes (keyed by structured descriptor) | `COMMENT ON ...`; removal renders `COMMENT ON ... IS NULL` | Live catalogs extract relation, column, function, and schema comments. |
+| Side-effect statements | Blocks | No | `INSERT`, `UPDATE`, `DELETE`, `DO`, and control-plane `SELECT` statements belong in explicit reviewed migrations. |
+
+## Supabase Adapter
+
+With `adapter: "supabase-auto"`, objects in these platform-owned schemas are blocked: `auth`, `storage`, `realtime`, `vault`, `extensions`, `cron`, `net`, `supabase_functions`, `graphql`, and `graphql_public`.
+
+## Verify Environment Stub
+
+`verify --ensure-environment` (the default under `adapter: "supabase-auto"`) provisions a minimal stand-in for the Supabase-provisioned surface so a declarative tree that _references_ managed schemas can apply against bare PostgreSQL:
+
+- `auth.users` with the stable GoTrue column set (`id`, `aud`, `role`, `email`, `phone`, `raw_app_meta_data`, `raw_user_meta_data`, `last_sign_in_at`, `is_anonymous`, …).
+- The `auth.uid()`, `auth.role()`, `auth.jwt()`, and `auth.email()` helper functions.
+- The `cron.job` and `cron.job_run_details` tables.
+
+The stub is symmetric across both temporary databases and subtracted from the reconvergence check, so it never affects catalog parity. It is an **approximation**: other managed objects (`storage.*`, `realtime.*`, `vault.*`, `auth.identities`, `auth.sessions`, …) are not stubbed. A migration that references an un-stubbed managed object fails verify with `SUPA_VERIFY_FAILED` plus a `SUPA_VERIFY_STUB_REFERENCE` warning naming the schema — that failure may be a stub limitation rather than a real defect; re-run verify against a real Supabase database (without `--ensure-environment`) to confirm.
+
+## Examples
+
+- `examples/supabase/schemas` demonstrates Supabase-style declarative schema input with RLS and policies; `examples/supabase/schemas-next` is the evolved tree, so a full diff runs out of the box:
+
+  ```bash
+  cd examples/supabase
+  npx supaschema diff --from dir:schemas --to dir:schemas-next --out stdout
+  ```
+
+- `examples/postgres/schemas` demonstrates a generic PostgreSQL schema tree without Supabase-managed schema rules.
+
+## Rename Policy
+
+Rename detection is hints-only. The planner does not infer renames from similar definitions because a false positive can destroy data.
+
+Explicit hints render guarded idempotent renames for schemas, tables, sequences, indexes, functions, procedures, views, and materialized views. Unsupported rename kinds, schema moves, and kind mismatches block.

package/examples/postgres/schemas/001_app.sql

@@ -0,0 +1,17 @@
+CREATE SCHEMA app;
+
+CREATE TABLE app.accounts (
+  id bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+  email text NOT NULL,
+  created_at timestamptz DEFAULT now() NOT NULL
+);
+
+CREATE INDEX accounts_email_idx ON app.accounts (email);
+
+CREATE OR REPLACE FUNCTION app.account_count()
+RETURNS bigint
+LANGUAGE sql
+STABLE
+AS $$
+  SELECT count(*) FROM app.accounts
+$$;

package/examples/supabase/schemas/001_app.sql

@@ -0,0 +1,13 @@
+CREATE SCHEMA app;
+
+CREATE TABLE app.accounts (
+  id bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+  name text NOT NULL
+);
+
+ALTER TABLE app.accounts ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY accounts_select ON app.accounts
+  FOR SELECT
+  TO public
+  USING (true);

package/examples/supabase/schemas-next/001_app.sql

@@ -0,0 +1,21 @@
+CREATE SCHEMA app;
+
+CREATE TYPE app.account_status AS ENUM ('active', 'suspended');
+
+CREATE TABLE app.accounts (
+  id bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+  name text NOT NULL,
+  status app.account_status DEFAULT 'active'::app.account_status NOT NULL
+);
+
+ALTER TABLE app.accounts ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY accounts_select ON app.accounts
+  FOR SELECT
+  TO public
+  USING (true);
+
+CREATE OR REPLACE VIEW app.account_names AS
+  SELECT id, name FROM app.accounts;
+
+COMMENT ON TABLE app.accounts IS 'Customer accounts';

package/examples/supabase/supaschema.config.json

@@ -0,0 +1,15 @@
+{
+  "adapter": "supabase-auto",
+  "destructiveChanges": "hint-required",
+  "excludedGrantRoles": [
+    "supabase_admin",
+    "supabase_auth_admin",
+    "supabase_storage_admin",
+    "dashboard_user",
+    "pgbouncer",
+    "authenticator"
+  ],
+  "schemaPaths": ["schemas"],
+  "transactionMode": "per-migration",
+  "validators": ["internal-parser"]
+}

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "supaschema",
+  "version": "0.1.0-rc.1",
+  "description": "From declarative schema to fully synced database in milliseconds with one command. No ORM, no Docker, and no shadow database needed.",
+  "type": "module",
+  "license": "AGPL-3.0-only",
+  "author": "John McLaughlin",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jmclaughlin724/supaschema.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jmclaughlin724/supaschema/issues"
+  },
+  "homepage": "https://github.com/jmclaughlin724/supaschema#readme",
+  "bin": {
+    "supaschema": "bin/supaschema"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    ".agents",
+    ".claude",
+    ".codex",
+    "AGENTS.md",
+    "benchmarks/README.md",
+    "benchmarks/compare.js",
+    "benchmarks/fixtures",
+    "benchmarks/plot-lib.js",
+    "benchmarks/plot-svg.js",
+    "benchmarks/plot.js",
+    "benchmarks/tools",
+    "bin",
+    "config-schema.json",
+    "corpus",
+    "dist",
+    "docs",
+    "examples",
+    "LICENSE",
+    "LICENSE-COMMERCIAL.md",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "benchmark": "npm run build && node dist/benchmark.js",
+    "bench:compare": "npm run build && node benchmarks/compare.js",
+    "bench:plot": "node benchmarks/plot.js",
+    "build": "tsc -p tsconfig.json && node dist/config-schema-gen.js",
+    "check": "npm run lint && npm run typecheck && npm test && npm run build",
+    "check:package": "publint && attw --pack . --profile esm-only",
+    "clean": "rm -rf dist coverage",
+    "docs:api": "typedoc src/index.ts --out api-docs",
+    "corpus:check": "npm run build && node dist/cli.js corpus --corpus-dir corpus/supabase-style",
+    "fixture:diff": "node dist/cli.js diff --from dir:tests/fixtures/basic/from --to dir:tests/fixtures/basic/to --out stdout",
+    "fixture:verify": "npm run build && out=$(mktemp -d)/basic.sql && node dist/cli.js diff --from dir:tests/fixtures/basic/from --to dir:tests/fixtures/basic/to --out \"$out\" && node dist/cli.js verify --from dir:tests/fixtures/basic/from --to dir:tests/fixtures/basic/to --migration \"$out\"",
+    "format": "biome check --write .",
+    "lint": "biome check .",
+    "pack:dry": "npm pack --dry-run",
+    "postinstall": "node bin/postinstall.mjs",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "keywords": [
+    "postgres",
+    "postgresql",
+    "supabase",
+    "migration",
+    "schema",
+    "diff",
+    "sql"
+  ],
+  "dependencies": {
+    "commander": "^14.0.3",
+    "libpg-query": "^17.7.3",
+    "pg": "^8.21.0",
+    "pgsql-deparser": "^17.18.3",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.3",
+    "@biomejs/biome": "^2.4.16",
+    "@types/node": "^25.9.3",
+    "@types/pg": "^8.15.6",
+    "@vitest/coverage-v8": "^4.1.8",
+    "fast-check": "^4.8.0",
+    "publint": "^0.3.21",
+    "typedoc": "^0.28.19",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  }
+}