@exposify/supabase 0.1.0 → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -15,7 +15,7 @@ root.
 
 - A Supabase project (local via the [Supabase CLI](https://supabase.com/docs/guides/cli), or hosted).
 - The Supabase CLI (`supabase` on your `PATH`) for `db push` / `functions deploy`.
-- Node or Yarn to run `npx agentify-supabase` (the CLI is a regular npm
+- Node or Yarn to run `npx exposify-supabase` (the CLI is a regular npm
   package; the edge function itself runs on Deno and needs no local install).
 
 ## 1. Scaffold
@@ -23,13 +23,16 @@ root.
 From your Supabase project's root (the directory containing `supabase/`):
 
 ```bash
-npx agentify-supabase init
+npx exposify-supabase init
 ```
 
-This writes two things and never overwrites an existing function file:
+This is safe to re-run — it never overwrites an existing function file, and
+never scaffolds a second copy of the migration if one's already there
+(checked by filename, not content: migrations are meant to be immutable
+once written, so a re-run skips rather than rewrites). It writes:
 
-- `supabase/migrations/<timestamp>_agentify_meta.sql` — a SQL migration that
-  adds `agentify_meta()`, a `SECURITY DEFINER` function returning, per table,
+- `supabase/migrations/<timestamp>_exposify_meta.sql` — a SQL migration that
+  adds `exposify_meta()`, a `SECURITY DEFINER` function returning, per table,
   whether RLS is enabled and any `COMMENT ON TABLE`/`COMMENT ON COLUMN` text
   you've written. It only ever returns catalog metadata (table/column names,
   flags, comments) — never row data — which is what makes it safe to grant
@@ -39,8 +42,13 @@ This writes two things and never overwrites an existing function file:
 - `supabase/functions/mcp/docs/` — an empty directory for optional bundled
   docs (see "Knowledge base" below).
 
-`init` is interactive from there. If the Supabase CLI is on your `PATH` and
-you're running it in a real terminal, it asks:
+If you run it somewhere that doesn't look like a Supabase project root (no
+`supabase/config.toml`), it warns but still proceeds — worth double-checking
+you're in the directory you think you are before continuing.
+
+`init` is interactive from there (skips straight to the old fixed behavior
+below if stdin isn't a real terminal — CI, a script, piped input). If the
+Supabase CLI is on your `PATH`, it asks:
 
 ```
 Apply the migration and deploy the function to whatever Supabase project is
@@ -49,8 +57,8 @@ currently linked, now? [y/N]
 
 Answering **y** runs `supabase db push` then `supabase functions deploy mcp`
 for you, streaming their output. The default is **no** — pressing Enter, the
-Supabase CLI not being installed, or running `init` non-interactively (CI, a
-script, piped input) all skip straight to printing the commands instead:
+Supabase CLI not being installed, or running `init` non-interactively all
+skip straight to printing the commands instead:
 
 ```
 Run these to finish setup:
@@ -61,14 +69,51 @@ Run these to finish setup:
 
 That's deliberate: `db push`/`functions deploy` act on whatever project is
 *currently linked*, which may not be a throwaway one, so nothing gets pushed
-without an explicit yes. If you want to edit `writes`/`rpc`/`functions` (next
-section) before the first deploy, just say no here and run the printed
-commands yourself once you're done editing.
+without an explicit yes.
+
+### The setup wizard
+
+If `init` can reach the project you're setting up — either because it was
+already deployed (a re-run), or because you say yes above and the deploy
+succeeds — it walks through a short interactive wizard instead of leaving
+you to hand-edit `writes`/`rpc`/comments yourself:
+
+1. **Anonymous sign-in.** `init` tries to auto-detect this via the project's
+   public `/auth/v1/settings` endpoint and asks you to confirm; if it can't
+   detect it, it just asks. If enabled, it adds a warning comment to the
+   generated `index.ts`: an anonymous Supabase Auth session gets
+   `role: authenticated` (not `role: anon`), so it passes any RLS policy
+   scoped to `authenticated` unless that policy explicitly excludes
+   `auth.jwt()->>'is_anonymous' = 'true'`. Worth knowing before granting
+   `writes` on anything an anonymous session could reach.
+2. **Per-table writes.** For every RLS-enabled table, asks which of
+   insert/update/delete to grant (`i`, `u`, `d`, comma-separated, or Enter
+   for none) — the resulting `writes` array is written for you instead of
+   left as a commented-out example.
+3. **RPC functions.** Lists Postgres functions PostgREST exposes and lets
+   you pick which to expose as tools.
+4. **Documentation.** For every table or column `exposify_meta()` reports
+   has no comment, offers to write one right there — the answers become a
+   `COMMENT ON TABLE`/`COMMENT ON COLUMN` migration
+   (`<timestamp>_exposify_comments.sql`) that gets applied alongside the
+   rest. This is what gives `query_<table>`/`insert_<table>`/etc. their tool
+   and parameter descriptions (see "Column/table descriptions" below) —
+   worth doing even for tables you're not granting writes on, since it's
+   the only thing that makes read tools self-explanatory to an agent.
+
+If `supabase/functions/mcp/index.ts` already exists, none of this touches
+it — your selections are printed as a config snippet to merge in by hand
+instead, and the documentation migration still gets written either way.
+Connects using `SUPABASE_URL`/`SUPABASE_SERVICE_ROLE_KEY` (env vars or
+`--url`/`--key` flags — **the service role key, not the anon key**; see the
+note on introspection below) — without those, `init` can't reach anything to
+introspect and falls back to the fixed scaffold-and-ask-to-deploy flow above,
+same as before this wizard existed.
 
 ## 2. Decide what's exposed
 
 **Every RLS-enabled table is automatically readable.** A table only shows up
-at all if `agentify_meta()` reports RLS is turned on for it *and* PostgREST
+at all if `exposify_meta()` reports RLS is turned on for it *and* PostgREST
 actually exposes it (the calling role has grants) — an RLS-less table is
 invisible, full stop, with no override. For each exposed table you get a
 `query_<table>` tool: typed filters (`eq`/`neq`/`gt`/`lt`/`like`), a `select`
@@ -122,7 +167,34 @@ Other options you can pass to `aiReady()`:
 | `docsAuth` | `"public"` | `"required"` hides `search_docs` until the caller sends *any* `Authorization` header (presence-only, not validated) |
 | `maxRows` | `100` | Hard cap applied to every `query_<table>` call |
 | `rateLimit` / `rateWindowMs` | `60` / `60000` | In-memory, per-instance, best-effort rate limit — **not** distributed across edge instances; real limits belong to Supabase's own gateway |
-| `supabaseUrl` / `anonKey` | read from `SUPABASE_URL` / `SUPABASE_ANON_KEY` env vars | Override for local dev/testing; in a deployed function the env vars are automatic |
+| `supabaseUrl` / `anonKey` / `serviceRoleKey` | read from `SUPABASE_URL` / `SUPABASE_ANON_KEY` / `SUPABASE_SERVICE_ROLE_KEY` env vars | Override for local dev/testing; in a deployed function all three env vars are automatic. `serviceRoleKey` is used only for schema introspection — see below. |
+
+### Why introspection needs the service role key
+
+Every actual data call (`query_<table>`, `insert_<table>`, `rpc_<fn>`, ...)
+uses the caller's own forwarded JWT, or the anon key as its fallback for an
+unauthenticated caller — **that part is unaffected by any of this** and is
+still what makes RLS the real authorization layer.
+
+Schema introspection is different: fetching PostgREST's OpenAPI document (the
+one-time-per-instance call that discovers which tables/columns exist) has to
+use `SUPABASE_SERVICE_ROLE_KEY`. Supabase's gateway rejects that specific
+request outright for an anon or publishable-tier key —
+`{"message":"Invalid API key","hint":"Only the service_role API key can be
+used for this endpoint."}` — regardless of RLS policies or table grants, and
+regardless of whether you're using a legacy JWT-format anon key or a newer
+`sb_publishable_...` key. This isn't documented anywhere in Supabase's own
+docs as far as we've found; it was discovered by deploying this SDK against
+a real project. The service role key never leaves the function and is never
+used for anything except this schema-shape discovery — it doesn't touch row
+data, and RLS still fully governs every actual tool call.
+
+If you deploy with `supabase functions deploy` this just works — Supabase
+auto-injects `SUPABASE_SERVICE_ROLE_KEY` into every edge function already.
+The only place you'd ever need to supply it yourself is local dev/testing
+(the `serviceRoleKey` option above) or the CLI's `init`/`generate` (see
+their own sections), which run outside the deployed function and need it
+passed explicitly.
 
 ## 3. Apply the migration and deploy
 
@@ -136,7 +208,7 @@ supabase functions deploy mcp
 
 Only `functions deploy` is needed for a config-only change to `index.ts`;
 `db push` is only needed again if the migration itself changed (it hasn't,
-unless you're editing `sql/agentify_meta.sql` directly).
+unless you're editing `sql/exposify_meta.sql` directly).
 
 (Local dev: `supabase start` then `supabase functions serve mcp` instead of
 `deploy`.)
@@ -169,9 +241,9 @@ them via the `search_docs` tool.
 Every request tries, in order:
 
 1. **Runtime introspection** — fetch PostgREST's OpenAPI document and call
-   `agentify_meta()`. This is the normal path; the result is cached in
+   `exposify_meta()`. This is the normal path; the result is cached in
    memory for the life of the edge instance, not refetched per call.
-2. **Bundled manifest** — if step 1 fails, and a `agentify.manifest.json`
+2. **Bundled manifest** — if step 1 fails, and a `exposify.manifest.json`
    was generated ahead of time (see below), tools are built from that
    instead.
 3. **Functions + knowledge base only** — if neither works, the function
@@ -188,31 +260,38 @@ project (local `supabase start` or linked):
 ```bash
 SUPABASE_URL=http://localhost:54321 \
 SUPABASE_SERVICE_ROLE_KEY=<service-role-key> \
-npx agentify-supabase generate
+npx exposify-supabase generate
 ```
 
-This writes `supabase/functions/mcp/agentify.manifest.json`. Load it in
+Uses the **service role key**, deliberately the same key runtime
+introspection itself uses (see "Why introspection needs the service role
+key" above, and "Fallback ladder" below) — the anon key can't fetch
+PostgREST's OpenAPI document at all, so `generate` needs the same
+privileged key runtime introspection does. Nothing from the service role
+key ends up in the generated manifest — it's just table/column metadata.
+
+This writes `supabase/functions/mcp/exposify.manifest.json`. Load it in
 `aiReady({ manifest: ... })` — since the function runs on Deno, import it
 with a JSON import:
 
 ```ts
-import manifest from "./agentify.manifest.json" with { type: "json" };
+import manifest from "./exposify.manifest.json" with { type: "json" };
 
 Deno.serve(aiReady({ manifest, /* ...writes/rpc/functions... */ }));
 ```
 
 ## Troubleshooting
 
-**"agentify_meta() is not reachable" / "PGRST202" errors in function logs.**
+**"exposify_meta() is not reachable" / "PGRST202" errors in function logs.**
 The migration hasn't been applied to this database. Run `supabase db push`
-(or apply `sql/agentify_meta.sql` from this package directly), then
+(or apply `sql/exposify_meta.sql` from this package directly), then
 redeploy the function — the error message names this exact fix.
 
 **A table I expected doesn't show up as a tool.** Check, in order: is RLS
 actually enabled on it (`alter table ... enable row level security;`)? Does
 the calling role (`anon`/`authenticated`) have grants PostgREST can see? If
 both are true and it's still missing, confirm the migration is applied —
-`agentify_meta()` is what reports the RLS flag in the first place.
+`exposify_meta()` is what reports the RLS flag in the first place.
 
 **An `rpc_<fn>` tool takes a single opaque `args` object instead of named
 parameters.** PostgREST's OpenAPI document didn't have a recognizable
@@ -226,3 +305,23 @@ entries are `"<table>.insert"` / `"<table>.update"` / `"<table>.delete"` /
 `"<table>.*"` — a malformed entry is dropped (with a console warning), not
 an error, so a typo silently disables just that grant rather than crashing
 the function.
+
+**`init` just scaffolds and asks to deploy — it never asks about writes/RPCs/
+documentation.** The wizard only runs when `init` can actually reach the
+project (`SUPABASE_URL`/`SUPABASE_SERVICE_ROLE_KEY` env vars, or `--url`/`--key`
+flags — the service role key, not the anon key, for the same reason described
+above — pointing at a project where the migration is already applied). On a
+brand-new project's first `init`, that's not true yet — say yes to the
+deploy prompt (or run `supabase db push` yourself) and the wizard picks up
+automatically once the migration is live, in the same run if you said yes,
+or on your next `exposify-supabase init` otherwise.
+
+**`PostgREST OpenAPI fetch failed: HTTP 401`, and the error body (if you
+curl it directly) says `"Only the service_role API key can be used for this
+endpoint"`.** This is expected if `SUPABASE_SERVICE_ROLE_KEY` isn't
+reaching the function — see "Why introspection needs the service role key"
+above. On a deployed function this should be automatic; if you're still
+seeing this after a `supabase functions deploy`, check `supabase secrets
+list` for a stale explicit `SUPABASE_SERVICE_ROLE_KEY` override, and confirm
+you're not accidentally passing an anon/publishable key as `serviceRoleKey`
+in local dev.