@exposify/supabase 0.1.0

package/README.md

@@ -0,0 +1,228 @@
+# @exposify/supabase — setup guide
+
+Make a Supabase-backed app's database and edge functions usable by AI agents:
+one edge function serves MCP, with tools generated from your database
+(PostgREST + Row Level Security) plus any edge functions you explicitly
+register. The caller's JWT passes straight through to PostgREST — **RLS is
+the authorization layer**. The agent can do exactly what that logged-in user
+can do, nothing more.
+
+This guide walks through setup end to end. For the design rationale, see
+`docs/superpowers/specs/2026-08-15-agentify-supabase-design.md` in the repo
+root.
+
+## Prerequisites
+
+- 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
+  package; the edge function itself runs on Deno and needs no local install).
+
+## 1. Scaffold
+
+From your Supabase project's root (the directory containing `supabase/`):
+
+```bash
+npx agentify-supabase init
+```
+
+This writes two things and never overwrites an existing function file:
+
+- `supabase/migrations/<timestamp>_agentify_meta.sql` — a SQL migration that
+  adds `agentify_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
+  to `anon`/`authenticated` and call with a low-privilege key.
+- `supabase/functions/mcp/index.ts` — the edge function itself, a few lines
+  around `aiReady()`.
+- `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:
+
+```
+Apply the migration and deploy the function to whatever Supabase project is
+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:
+
+```
+Run these to finish setup:
+  1. supabase db push
+  2. supabase functions deploy mcp
+  3. Paste the function URL + a user JWT into an MCP client.
+```
+
+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.
+
+## 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
+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`
+column list, `order`, and a `limit` capped server-side (100 rows by default,
+regardless of what the caller asks for).
+
+Writes and Postgres functions are **opt-in**, edited in
+`supabase/functions/mcp/index.ts`:
+
+```ts
+import { aiReady } from "npm:@exposify/supabase";
+
+Deno.serve(aiReady({
+  // "<table>.insert" | "<table>.update" | "<table>.delete" | "<table>.*"
+  writes: ["orders.insert", "orders.update"],
+
+  // Postgres functions exposed as rpc_<fn> tools
+  rpc: ["place_order"],
+
+  // Sibling edge functions, invoked via fetch with the caller's forwarded JWT
+  functions: {
+    refund: {
+      description: "Refund an order",
+      input: {
+        type: "object",
+        properties: { orderId: { type: "string", description: "Order to refund" } },
+        required: ["orderId"],
+      },
+    },
+  },
+}));
+```
+
+Notes:
+- `update_<table>` and `delete_<table>` always require at least one filter —
+  there is no way to opt into a table-wide mutation, even where RLS would
+  technically allow it.
+- Column/table descriptions shown to the agent come from SQL comments
+  (`COMMENT ON TABLE orders IS '...'`, `COMMENT ON COLUMN orders.status IS
+  '...'`) — write these once and every generated tool reads them.
+- A registered `functions` entry's `input` is a small JSON Schema subset
+  (`object`/`string`/`number`/`integer`/`boolean`/`array`, `enum`,
+  `required`) — enough for a flat tool-input shape, not a full JSON Schema
+  implementation.
+
+Other options you can pass to `aiReady()`:
+
+| Option | Default | What it does |
+|---|---|---|
+| `docs` | `["docs/**/*.md"]` | Glob(s), relative to the function directory, bundled into the knowledge base |
+| `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 |
+
+## 3. Apply the migration and deploy
+
+If you didn't let `init` do this for you (or you've since edited `writes`/
+`rpc`/`functions`/`docs` and need to redeploy):
+
+```bash
+supabase db push
+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).
+
+(Local dev: `supabase start` then `supabase functions serve mcp` instead of
+`deploy`.)
+
+## 4. Connect an MCP client
+
+Point any MCP client at the function's URL with a real user's JWT as the
+bearer token — for example, with the Claude Code CLI:
+
+```bash
+claude mcp add --transport http my-app https://<project-ref>.supabase.co/functions/v1/mcp \
+  --header "Authorization: Bearer <user-jwt>"
+```
+
+Ask the agent to query or mutate data. **It should succeed for that user's
+own rows and be refused everyone else's** — that's the definition of done:
+RLS enforcement, not anything in this SDK, is what makes that true.
+
+## Knowledge base
+
+Any markdown files matching the `docs` glob (default `docs/**/*.md`,
+relative to `supabase/functions/mcp/`) are bundled with the function,
+chunked, and indexed with BM25 the first time the function handles a
+request in a given instance. There's no cache file and no invalidation
+logic — redeploying the function *is* the invalidation. Agents can search
+them via the `search_docs` tool.
+
+## When PostgREST is unreachable: the fallback ladder
+
+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
+   memory for the life of the edge instance, not refetched per call.
+2. **Bundled manifest** — if step 1 fails, and a `agentify.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
+   still serves any registered `functions` tools and `search_docs`, never
+   crashes, and says so.
+
+Whichever rung actually served the request is disclosed to the MCP client
+in the `initialize` handshake's `instructions` field, so a degraded server
+never looks silently healthy.
+
+To generate the fallback manifest ahead of time, run against a reachable
+project (local `supabase start` or linked):
+
+```bash
+SUPABASE_URL=http://localhost:54321 \
+SUPABASE_SERVICE_ROLE_KEY=<service-role-key> \
+npx agentify-supabase generate
+```
+
+This writes `supabase/functions/mcp/agentify.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" };
+
+Deno.serve(aiReady({ manifest, /* ...writes/rpc/functions... */ }));
+```
+
+## Troubleshooting
+
+**"agentify_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
+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.
+
+**An `rpc_<fn>` tool takes a single opaque `args` object instead of named
+parameters.** PostgREST's OpenAPI document didn't have a recognizable
+argument schema for that function (older PostgREST, or a function with no
+declared parameters in a shape this SDK's parser recognizes) — pass a JSON
+object of the function's actual parameter names as `args` and it's forwarded
+as-is.
+
+**Writes/RPCs I configured aren't callable.** Double-check the `writes`
+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.

package/dist/cli.js

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+
+// bin/cli.ts
+import { mkdir, readFile, writeFile, access } from "fs/promises";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { execFileSync } from "child_process";
+import { createInterface } from "readline/promises";
+
+// src/fetch-openapi.ts
+async function fetchOpenApi(postgrestUrl, headers, fetchImpl) {
+  const res = await fetchImpl(postgrestUrl, {
+    headers: { ...Object.fromEntries(headers), accept: "application/openapi+json" }
+  });
+  if (!res.ok) {
+    throw new Error(`PostgREST OpenAPI fetch failed: HTTP ${res.status}`);
+  }
+  return await res.json();
+}
+
+// src/meta.ts
+var MissingAgentifyMetaError = class extends Error {
+  constructor(cause) {
+    super(cause);
+    this.name = "MissingAgentifyMetaError";
+  }
+};
+async function fetchAgentifyMeta(postgrestUrl, headers, fetchImpl) {
+  const res = await fetchImpl(`${postgrestUrl}/rpc/agentify_meta`, {
+    method: "POST",
+    headers: { ...Object.fromEntries(headers), "content-type": "application/json" },
+    body: "{}"
+  });
+  if (res.status === 404) {
+    throw new MissingAgentifyMetaError(
+      "agentify_meta() is not reachable at /rpc/agentify_meta (404). Run `npx agentify-supabase init` (or apply sql/agentify_meta.sql directly) and `supabase db push`, then redeploy the function."
+    );
+  }
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    if (/PGRST202|function .* does not exist/i.test(body)) {
+      throw new MissingAgentifyMetaError(
+        "agentify_meta() is missing from the database (PostgREST error PGRST202). Apply the migration in sql/agentify_meta.sql via `supabase db push`, then redeploy the function."
+      );
+    }
+    throw new Error(`agentify_meta() call failed: HTTP ${res.status} ${body}`.trim());
+  }
+  return await res.json();
+}
+
+// src/openapi.ts
+var TYPE_MAP = {
+  integer: "integer",
+  number: "number",
+  boolean: "boolean",
+  object: "object",
+  array: "array",
+  string: "string"
+};
+function isPrimaryKey(prop) {
+  return /<pk\/>/i.test(prop.description ?? "");
+}
+function columnsFromOpenApi(doc, table) {
+  const def = doc.definitions?.[table];
+  if (!def?.properties) return [];
+  const required = new Set(def.required ?? []);
+  return Object.entries(def.properties).map(([name, prop]) => ({
+    name,
+    type: TYPE_MAP[prop.type ?? "string"] ?? "string",
+    format: prop.format,
+    required: required.has(name),
+    isPrimaryKey: isPrimaryKey(prop),
+    // Falls back to the OpenAPI-embedded comment (PostgREST mirrors `COMMENT
+    // ON COLUMN` into `description`, then appends its own "Note:\nThis is a
+    // Primary/Foreign Key...<pk/|fk/>" boilerplate) -- strip that boilerplate
+    // so a column with no real comment ends up `undefined`, not the
+    // boilerplate text. agentify_meta()'s copy wins when both exist anyway
+    // -- see introspect.ts's merge.
+    description: prop.description?.replace(/\n*Note:[\s\S]*$/, "").trim() || void 0
+  }));
+}
+function tablesInOpenApi(doc) {
+  return new Set(Object.keys(doc.definitions ?? {}));
+}
+
+// src/introspect.ts
+function introspectTables(openapi, metaRows) {
+  const exposedInOpenApi = tablesInOpenApi(openapi);
+  const byTable = groupByTable(metaRows);
+  const tables = [];
+  for (const [name, rows] of byTable) {
+    const rlsEnabled = rows[0].rls_enabled;
+    if (!rlsEnabled) continue;
+    if (!exposedInOpenApi.has(name)) continue;
+    const openApiColumns = new Map(columnsFromOpenApi(openapi, name).map((c) => [c.name, c]));
+    const columns = [];
+    for (const row of rows) {
+      const fromOpenApi = openApiColumns.get(row.column_name);
+      if (!fromOpenApi) continue;
+      columns.push({
+        ...fromOpenApi,
+        // agentify_meta()'s comment wins over OpenAPI's mirrored copy (spec:
+        // "Column comments → param descriptions" sourced from the migration).
+        description: row.column_comment ?? fromOpenApi.description
+      });
+    }
+    if (columns.length === 0) continue;
+    tables.push({
+      name,
+      rlsEnabled: true,
+      description: rows[0].table_comment ?? void 0,
+      columns
+    });
+  }
+  return tables.sort((a, b) => a.name.localeCompare(b.name));
+}
+function groupByTable(rows) {
+  const map = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const list = map.get(row.table_name) ?? [];
+    list.push(row);
+    map.set(row.table_name, list);
+  }
+  return map;
+}
+
+// src/manifest.ts
+var MANIFEST_VERSION = 1;
+function buildManifest(openapi, metaRows, generatedAt) {
+  return { version: MANIFEST_VERSION, generatedAt, tables: introspectTables(openapi, metaRows) };
+}
+
+// bin/cli.ts
+var PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+var FUNCTION_DIR = "supabase/functions/mcp";
+var FUNCTION_TEMPLATE = `import { aiReady } from "npm:@exposify/supabase";
+
+Deno.serve(aiReady({
+  // writes: ["orders.insert", "orders.update"],
+  // rpc: ["place_order"],
+  // functions: {
+  //   refund: { description: "Refund an order", input: { type: "object", properties: {} } },
+  // },
+}));
+`;
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function hasSupabaseCli() {
+  try {
+    execFileSync("supabase", ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function promptYesNo(question) {
+  if (!process.stdin.isTTY) return false;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (await rl.question(`${question} [y/N] `)).trim().toLowerCase();
+    return answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+function printManualCommands(opts = {}) {
+  console.log("\nRun these to finish setup:");
+  const steps = [];
+  if (!opts.alreadyPushed) steps.push("supabase db push");
+  if (!opts.alreadyDeployed) steps.push("supabase functions deploy mcp");
+  steps.forEach((cmd, i) => console.log(`  ${i + 1}. ${cmd}`));
+  console.log(`  ${steps.length + 1}. Paste the function URL + a user JWT into an MCP client.`);
+}
+async function cmdInit() {
+  const migrationSql = await readFile(join(PACKAGE_ROOT, "sql/agentify_meta.sql"), "utf8");
+  const migrationsDir = "supabase/migrations";
+  await mkdir(migrationsDir, { recursive: true });
+  const migrationPath = join(migrationsDir, `${timestamp()}_agentify_meta.sql`);
+  await writeFile(migrationPath, migrationSql);
+  console.log(`Wrote ${migrationPath}`);
+  await mkdir(FUNCTION_DIR, { recursive: true });
+  const functionPath = join(FUNCTION_DIR, "index.ts");
+  if (await exists(functionPath)) {
+    console.log(`Skipped ${functionPath} (already exists)`);
+  } else {
+    await writeFile(functionPath, FUNCTION_TEMPLATE);
+    console.log(`Wrote ${functionPath}`);
+  }
+  await mkdir(join(FUNCTION_DIR, "docs"), { recursive: true });
+  if (!hasSupabaseCli()) {
+    console.log("\nSupabase CLI not found on PATH -- install it to run the next steps automatically next time.");
+    printManualCommands();
+    return;
+  }
+  const connect = await promptYesNo(
+    "\nApply the migration and deploy the function to whatever Supabase project is currently linked, now?"
+  );
+  if (!connect) {
+    printManualCommands();
+    return;
+  }
+  let pushed = false;
+  try {
+    console.log("\n$ supabase db push");
+    execFileSync("supabase", ["db", "push"], { stdio: "inherit" });
+    pushed = true;
+    console.log("\n$ supabase functions deploy mcp");
+    execFileSync("supabase", ["functions", "deploy", "mcp"], { stdio: "inherit" });
+    console.log("\nDone. Paste the function URL + a user JWT into an MCP client to try it.");
+  } catch (err) {
+    console.error(`
+Supabase CLI command failed: ${err instanceof Error ? err.message : err}`);
+    printManualCommands({ alreadyPushed: pushed });
+  }
+}
+async function cmdGenerate() {
+  const supabaseUrl = process.env.SUPABASE_URL ?? argValue("--url");
+  const serviceKey = process.env.SUPABASE_SERVICE_ROLE_KEY ?? argValue("--key");
+  if (!supabaseUrl || !serviceKey) {
+    console.error(
+      "generate needs SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY (env vars, or --url/--key flags) pointing at a running local or linked project (e.g. `supabase start`)."
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const postgrestUrl = `${supabaseUrl.replace(/\/+$/, "")}/rest/v1`;
+  const headers = new Headers({ authorization: `Bearer ${serviceKey}`, apikey: serviceKey });
+  const [openapi, metaRows] = await Promise.all([
+    fetchOpenApi(postgrestUrl, headers, fetch),
+    fetchAgentifyMeta(postgrestUrl, headers, fetch)
+  ]);
+  const manifest = buildManifest(openapi, metaRows, (/* @__PURE__ */ new Date()).toISOString());
+  const outPath = join(FUNCTION_DIR, "agentify.manifest.json");
+  await mkdir(dirname(outPath), { recursive: true });
+  await writeFile(outPath, JSON.stringify(manifest, null, 2));
+  console.log(`Wrote ${outPath} (${manifest.tables.length} table(s))`);
+}
+function argValue(flag) {
+  const i = process.argv.indexOf(flag);
+  return i >= 0 ? process.argv[i + 1] : void 0;
+}
+function timestamp() {
+  const d = /* @__PURE__ */ new Date();
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+}
+async function main() {
+  const [, , cmd] = process.argv;
+  if (cmd === "init") return cmdInit();
+  if (cmd === "generate") return cmdGenerate();
+  console.log("Usage: agentify-supabase <init|generate>");
+  console.log("  init      Scaffold the agentify_meta() migration + supabase/functions/mcp/index.ts,");
+  console.log("            then interactively offer to run `supabase db push` + `functions deploy`");
+  console.log("  generate  Build agentify.manifest.json from a running local/linked project");
+  process.exitCode = cmd ? 1 : 0;
+}
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exitCode = 1;
+});