@exposify/supabase 0.3.7 → 0.3.8

package/dist/cli.js

@@ -169,6 +169,36 @@ function parseSelectionAnswer(answer, candidates) {
   );
   return candidates.filter((c) => wanted.has(c));
 }
+function writesByTable(writes) {
+  const map = /* @__PURE__ */ new Map();
+  for (const w of writes) {
+    const dot = w.lastIndexOf(".");
+    const table = dot === -1 ? w : w.slice(0, dot);
+    map.set(table, [...map.get(table) ?? [], w]);
+  }
+  return map;
+}
+function writesLabel(entries) {
+  if (entries.length === 0) return "none";
+  if (entries.some((e) => e.endsWith(".*"))) return "i,u,d";
+  return entries.map((e) => e.slice(e.lastIndexOf(".") + 1)[0]).join(",");
+}
+function resolveWritesAnswer(answer, table, current) {
+  const a = answer.trim();
+  if (a === "") return { value: current };
+  if (a === "-") return { value: [] };
+  const ops = parseWriteOpsAnswer(a);
+  if (ops.length === 0) return { value: current, note: `didn't understand "${a}" -- kept ${writesLabel(current)}` };
+  return { value: flattenWriteGrants([{ table, ops }]) };
+}
+function resolveSelectionAnswer(answer, candidates, current) {
+  const a = answer.trim();
+  if (a === "") return { value: current };
+  if (a === "-") return { value: [] };
+  const picked = parseSelectionAnswer(a, candidates);
+  if (picked.length === 0) return { value: current, note: `none of "${a}" matched -- kept ${current.join(", ") || "none"}` };
+  return { value: picked };
+}
 function tablesMissingDocs(tables) {
   return tables.map((t) => ({
     name: t.name,
@@ -198,46 +228,6 @@ function buildCommentStatements(entries) {
   return lines.length > 0 ? `${lines.join("\n")}
 ` : "";
 }
-var LICENSE_KEY_SECRET = "EXPOSIFY_LICENSE_KEY";
-var ANONYMOUS_SIGN_IN_WARNING = `// NOTE: this project has anonymous sign-in enabled. An anonymous Supabase
-// Auth session still gets role: authenticated (with an is_anonymous claim),
-// NOT role: anon -- so it passes any RLS policy scoped to "authenticated"
-// unless that policy explicitly excludes auth.jwt()->>'is_anonymous' = 'true'.
-// Double-check your RLS policies (especially on tables granted writes below)
-// account for this before trusting "authenticated" to mean "a real user".
-`;
-function buildFunctionTemplate(opts = {}) {
-  const lines = [];
-  if (opts.anonymousSignIn) lines.push(ANONYMOUS_SIGN_IN_WARNING);
-  lines.push(`import { aiReady } from "npm:@exposify/supabase";`);
-  if (opts.broker) lines.push(`import { createHostedAuthResolver } from "npm:@exposify/token-broker";`);
-  lines.push("");
-  lines.push("Deno.serve(aiReady({");
-  if (opts.broker) {
-    lines.push(
-      "  auth: createHostedAuthResolver({",
-      `    brokerUrl: ${JSON.stringify(opts.broker.brokerUrl)},`,
-      `    projectId: ${JSON.stringify(opts.broker.projectId)},`,
-      `    licenseKey: Deno.env.get(${JSON.stringify(LICENSE_KEY_SECRET)}) ?? "",`,
-      "  }),",
-      "  authRequired: true,"
-    );
-  }
-  lines.push(
-    opts.writes && opts.writes.length > 0 ? `  writes: ${JSON.stringify(opts.writes)},` : `  // writes: ["orders.insert", "orders.update"],`
-  );
-  lines.push(
-    opts.rpc && opts.rpc.length > 0 ? `  rpc: ${JSON.stringify(opts.rpc)},` : `  // rpc: ["place_order"],`
-  );
-  lines.push(
-    "  // functions: {",
-    '  //   refund: { description: "Refund an order", input: { type: "object", properties: {} } },',
-    "  // },",
-    "}));",
-    ""
-  );
-  return lines.join("\n");
-}
 function brokerUrlProblem(brokerUrl) {
   let url;
   try {
@@ -302,11 +292,782 @@ function partialConnectionWarning(url, key) {
   return null;
 }
 
-// bin/cli.ts
-var PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
-var FUNCTION_DIR = "supabase/functions/mcp";
+// bin/credentials.ts
+var PROJECT_REF_FILE = "supabase/.temp/project-ref";
+function explicitConnection(input) {
+  const url = input.flagUrl ?? input.envUrl;
+  const serviceRoleKey = input.flagKey ?? input.envKey;
+  if (!url || !serviceRoleKey) return null;
+  const fromFlags = input.flagUrl !== void 0 || input.flagKey !== void 0;
+  return {
+    url,
+    serviceRoleKey,
+    ...input.envAnonKey ? { anonKey: input.envAnonKey } : {},
+    source: fromFlags ? "flags" : "env",
+    label: fromFlags ? "--url/--key" : "SUPABASE_URL/SUPABASE_SERVICE_ROLE_KEY"
+  };
+}
+function parseStatusEnv(stdout) {
+  const vars = /* @__PURE__ */ new Map();
+  for (const line of stdout.split("\n")) {
+    const m = /^\s*([A-Z][A-Z0-9_]*)=(.*)$/.exec(line);
+    if (!m) continue;
+    vars.set(m[1], m[2].trim().replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1"));
+  }
+  const url = vars.get("API_URL");
+  const serviceRoleKey = vars.get("SERVICE_ROLE_KEY") || vars.get("SECRET_KEY");
+  if (!url || !serviceRoleKey) return null;
+  const anonKey = vars.get("ANON_KEY");
+  return { url, serviceRoleKey, ...anonKey ? { anonKey } : {} };
+}
+function isMaskedKey(key) {
+  return /[·•*]/.test(key);
+}
+function parseApiKeysJson(stdout) {
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(parsed)) return null;
+  const keys = parsed.filter(
+    (k) => !!k && typeof k === "object" && typeof k.api_key === "string" && !isMaskedKey(k.api_key)
+  );
+  const serviceRole = keys.find((k) => k.name === "service_role") ?? keys.find((k) => k.type === "secret");
+  if (!serviceRole) return null;
+  const anon = keys.find((k) => k.name === "anon");
+  return { serviceRoleKey: serviceRole.api_key, ...anon ? { anonKey: anon.api_key } : {} };
+}
+function linkedProjectUrl(ref) {
+  return `https://${ref}.supabase.co`;
+}
+function projectRefFromUrl(url) {
+  try {
+    const m = /^([a-z0-9]{20})\.supabase\.co$/.exec(new URL(url).hostname);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+async function discoverConnection(deps) {
+  const notes = [];
+  if (!deps.run) {
+    notes.push("Supabase CLI not on PATH, so it can't supply credentials.");
+    return { connection: null, notes };
+  }
+  const run = deps.run;
+  let local = null;
+  if (deps.prefer !== "linked") {
+    try {
+      local = parseStatusEnv(run(["status", "-o", "env"]));
+      if (!local) notes.push("`supabase status` didn't report an API URL and service role key.");
+    } catch {
+      notes.push("No local stack running (`supabase status` failed).");
+    }
+  }
+  const ref = deps.prefer === "local" ? null : deps.projectRef;
+  if (deps.prefer !== "local" && !ref) notes.push(`No linked project (${PROJECT_REF_FILE} not found; run \`supabase link\`).`);
+  const fromLocal = () => ({
+    ...local,
+    source: "local",
+    label: `local stack at ${local.url} (supabase status)`
+  });
+  let pick = null;
+  if (local && ref) pick = deps.choose ? await deps.choose({ localUrl: local.url, projectRef: ref }) : "linked";
+  else if (ref) pick = "linked";
+  else if (local) pick = "local";
+  if (pick === null) return { connection: null, notes };
+  if (pick === "local") return { connection: fromLocal(), notes };
+  try {
+    const keys = parseApiKeysJson(run(["projects", "api-keys", "--project-ref", ref, "--reveal", "-o", "json"]));
+    if (keys) {
+      return {
+        connection: {
+          url: linkedProjectUrl(ref),
+          ...keys,
+          source: "linked",
+          label: `linked project ${ref} (supabase projects api-keys)`
+        },
+        notes
+      };
+    }
+    notes.push(`\`supabase projects api-keys\` returned no usable service role or secret key for ${ref}.`);
+  } catch {
+    notes.push(`Couldn't fetch API keys for linked project ${ref} (run \`supabase login\`?).`);
+  }
+  return { connection: local ? fromLocal() : null, notes };
+}
+
+// bin/function-file.ts
+var LICENSE_KEY_SECRET = "EXPOSIFY_LICENSE_KEY";
+var EMPTY_CONFIG = { writes: [], rpc: [], anonymousSignIn: false, broker: null, oauth: false };
+function bypassesGatewayJwt(config) {
+  return config.broker !== null || config.oauth;
+}
+function gatewayJwtReason(config) {
+  return config.oauth ? "MCP clients' first, tokenless request must reach the function to get its login challenge" : "broker tokens aren't Supabase JWTs";
+}
+var BEGIN = "// exposify:begin";
+var END = "// exposify:end";
+var ANONYMOUS_SIGN_IN_WARNING = [
+  "// NOTE: this project has anonymous sign-in enabled. An anonymous Supabase",
+  "// Auth session still gets role: authenticated (with an is_anonymous claim),",
+  '// NOT role: anon -- so it passes any RLS policy scoped to "authenticated"',
+  "// unless that policy explicitly excludes auth.jwt()->>'is_anonymous' = 'true'.",
+  "// Double-check your RLS policies (especially on tables granted writes below)",
+  '// account for this before trusting "authenticated" to mean "a real user".'
+];
+var ANONYMOUS_MARKER = "anonymous sign-in enabled";
+function buildManagedBlock(config) {
+  if (config.broker && config.oauth) throw new Error("the hosted broker and Supabase Auth OAuth can't be combined");
+  const lines = [
+    `${BEGIN} -- generated by \`npx exposify-supabase init\`, which rewrites`,
+    `// everything down to exposify:end when you re-run it. Add your own code below.`
+  ];
+  if (config.anonymousSignIn) lines.push(...ANONYMOUS_SIGN_IN_WARNING);
+  lines.push(
+    config.oauth ? `import { aiReady, supabaseAuth } from "npm:@exposify/supabase";` : `import { aiReady } from "npm:@exposify/supabase";`
+  );
+  if (config.broker) lines.push(`import { createHostedAuthResolver } from "npm:@exposify/token-broker";`);
+  lines.push("", "const generated = {");
+  if (config.broker) {
+    lines.push(
+      "  auth: createHostedAuthResolver({",
+      `    brokerUrl: ${JSON.stringify(config.broker.brokerUrl)},`,
+      `    projectId: ${JSON.stringify(config.broker.projectId)},`,
+      `    licenseKey: Deno.env.get(${JSON.stringify(LICENSE_KEY_SECRET)}) ?? "",`,
+      "  }),",
+      "  authRequired: true,"
+    );
+  }
+  if (config.oauth) {
+    lines.push("  oauth: supabaseAuth(),");
+  }
+  lines.push(
+    `  // "<table>.insert" | "<table>.update" | "<table>.delete" | "<table>.*"`,
+    `  writes: ${JSON.stringify(config.writes)},`,
+    "  // Postgres functions exposed as rpc_<fn> tools",
+    `  rpc: ${JSON.stringify(config.rpc)},`,
+    "};",
+    END
+  );
+  return lines.join("\n");
+}
+function buildFunctionFile(config) {
+  return [
+    buildManagedBlock(config),
+    "",
+    "Deno.serve(aiReady({",
+    "  ...generated,",
+    "  // functions: {",
+    '  //   refund: { description: "Refund an order", input: { type: "object", properties: {} } },',
+    "  // },",
+    "}));",
+    ""
+  ].join("\n");
+}
+function readStringArray(text, key) {
+  const m = new RegExp(`^\\s*${key}:\\s*(\\[.*\\])\\s*,?\\s*$`, "m").exec(text);
+  if (!m) return null;
+  try {
+    const value = JSON.parse(m[1]);
+    return Array.isArray(value) && value.every((v) => typeof v === "string") ? value : null;
+  } catch {
+    return null;
+  }
+}
+function readStringField(text, key) {
+  const m = new RegExp(`^\\s*${key}:\\s*("(?:[^"\\\\]|\\\\.)*")\\s*,?\\s*$`, "m").exec(text);
+  if (!m) return null;
+  try {
+    return JSON.parse(m[1]);
+  } catch {
+    return null;
+  }
+}
+function readConfig(text) {
+  const brokerUrl = readStringField(text, "brokerUrl");
+  const projectId = readStringField(text, "projectId");
+  return {
+    writes: readStringArray(text, "writes") ?? [],
+    rpc: readStringArray(text, "rpc") ?? [],
+    anonymousSignIn: text.includes(ANONYMOUS_MARKER),
+    broker: /\bcreateHostedAuthResolver\s*\(/.test(text) && brokerUrl && projectId ? { brokerUrl, projectId } : null,
+    oauth: /^\s*oauth:\s*supabaseAuth\(\s*\)\s*,?\s*$/m.test(text)
+  };
+}
+function findBlock(lines) {
+  const start = lines.findIndex((l) => l.startsWith(BEGIN));
+  if (start === -1) return null;
+  const end = lines.findIndex((l, i) => i > start && l.trim() === END);
+  return end === -1 ? null : { start, end };
+}
+function sameIgnoringWhitespace(a, b) {
+  return a.replace(/\s+/g, "") === b.replace(/\s+/g, "");
+}
+function parseFunctionFile(text) {
+  const lines = text.split("\n");
+  const found = findBlock(lines);
+  if (!found) return { kind: "unmanaged", config: readConfig(text) };
+  const block = lines.slice(found.start, found.end + 1).join("\n");
+  const config = readConfig(block);
+  return sameIgnoringWhitespace(buildManagedBlock(config), block) ? { kind: "managed", config, block } : { kind: "modified", config };
+}
+function replaceManagedBlock(text, config) {
+  const lines = text.split("\n");
+  const found = findBlock(lines);
+  if (!found) throw new Error("replaceManagedBlock: no managed region");
+  return [...lines.slice(0, found.start), buildManagedBlock(config), ...lines.slice(found.end + 1)].join("\n");
+}
+function configsEqual(a, b) {
+  const sameSet = (x, y) => x.length === y.length && [...x].sort().join("\0") === [...y].sort().join("\0");
+  return sameSet(a.writes, b.writes) && sameSet(a.rpc, b.rpc) && a.anonymousSignIn === b.anonymousSignIn && a.broker?.brokerUrl === b.broker?.brokerUrl && a.broker?.projectId === b.broker?.projectId && a.oauth === b.oauth;
+}
+
+// bin/doctor.ts
+var FUNCTION_NAME = "mcp";
+var FUNCTION_PATH = `supabase/functions/${FUNCTION_NAME}/index.ts`;
 var MIGRATIONS_DIR = "supabase/migrations";
 var CONFIG_TOML = "supabase/config.toml";
+var DIAGNOSTICS_URI = "exposify://diagnostics";
+function detectAuthMode(functionSource) {
+  if (/\bcreateHostedAuthResolver\s*\(/.test(functionSource)) return "broker";
+  return /\boauth:\s*supabaseAuth\s*\(/.test(functionSource) ? "oauth" : "jwt";
+}
+function bypassesGatewayJwt2(mode) {
+  return mode === "broker" || mode === "oauth";
+}
+var AUTH_LABEL = { jwt: "user JWT", broker: "hosted broker", oauth: "Supabase Auth OAuth" };
+function readFunctionVerifyJwt(toml, name = FUNCTION_NAME) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const header = new RegExp(`^\\s*\\[\\s*functions\\s*\\.\\s*("?)${escaped}\\1\\s*\\]\\s*(#.*)?$`);
+  const lines = toml.split("\n");
+  const start = lines.findIndex((l) => header.test(l));
+  if (start === -1) return null;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^\s*\[/.test(lines[i])) break;
+    const m = /^\s*verify_jwt\s*=\s*(true|false)\b/.exec(lines[i]);
+    if (m) return m[1] === "true";
+  }
+  return null;
+}
+function parseSecretNames(stdout) {
+  try {
+    const parsed = JSON.parse(stdout);
+    if (!Array.isArray(parsed)) return null;
+    return parsed.flatMap((s) => s && typeof s === "object" && typeof s.name === "string" ? [s.name] : []);
+  } catch {
+    return null;
+  }
+}
+function invisibleTables(metaRows, exposed) {
+  const exposedNames = new Set(exposed.map((t) => t.name));
+  const rlsByTable = /* @__PURE__ */ new Map();
+  for (const row of metaRows) rlsByTable.set(row.table_name, row.rls_enabled);
+  const rlsOff = [];
+  const notGranted = [];
+  for (const [name, rls] of [...rlsByTable].sort(([a], [b]) => a.localeCompare(b))) {
+    if (!rls) rlsOff.push(name);
+    else if (!exposedNames.has(name)) notGranted.push(name);
+  }
+  return { rlsOff, notGranted };
+}
+function parseJsonRpcResponse(contentType, body, id) {
+  const candidates = contentType.includes("text/event-stream") ? body.split("\n").filter((l) => l.startsWith("data:")).map((l) => l.slice(5).trim()) : [body];
+  for (const raw of candidates) {
+    try {
+      const msg = JSON.parse(raw);
+      if (msg && msg.id === id) return msg;
+    } catch {
+    }
+  }
+  return null;
+}
+function isGatewayJwtRejection(status, body) {
+  return status === 401 && /UNAUTHORIZED_|Missing authorization header|Invalid JWT/i.test(body);
+}
+async function probeFunction(functionUrl, fetchImpl, auth) {
+  const attempt = async (bearer, authUsed) => {
+    let nextId = 1;
+    const call = async (method, params) => {
+      const id = nextId++;
+      const res = await fetchImpl(functionUrl, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          accept: "application/json, text/event-stream",
+          ...bearer ? { authorization: `Bearer ${bearer}` } : {},
+          ...authUsed === "anon-key" && bearer ? { apikey: bearer } : {}
+        },
+        body: JSON.stringify({ jsonrpc: "2.0", id, method, params })
+      });
+      const body = await res.text();
+      return { res, body, msg: res.ok ? parseJsonRpcResponse(res.headers.get("content-type") ?? "", body, id) : null };
+    };
+    const init = await call("initialize", {
+      protocolVersion: "2025-06-18",
+      capabilities: {},
+      clientInfo: { name: "exposify-supabase-doctor", version: "0" }
+    });
+    if (init.res.status === 404) return { kind: "not-found" };
+    if (isGatewayJwtRejection(init.res.status, init.body)) return { kind: "gateway-jwt", body: init.body.trim(), authUsed };
+    if (init.res.status === 401) return { kind: "auth-required", authUsed };
+    if (!init.res.ok) return { kind: "error", detail: `initialize: HTTP ${init.res.status} ${init.body.trim()}`.trim() };
+    if (!init.msg || init.msg.error) {
+      return { kind: "error", detail: `initialize: unexpected response ${JSON.stringify(init.msg?.error ?? init.body.slice(0, 200))}` };
+    }
+    const list = await call("tools/list", {});
+    const noTools = list.msg?.error?.code === -32601;
+    const tools = noTools ? [] : list.msg?.result?.tools;
+    if (!Array.isArray(tools)) {
+      return { kind: "error", detail: `tools/list: HTTP ${list.res.status} ${JSON.stringify(list.msg?.error ?? list.body.slice(0, 200))}` };
+    }
+    let diagnostics = null;
+    const resources = await call("resources/list", {});
+    const listed = resources.msg?.result?.resources ?? [];
+    if (listed.some((r) => r.uri === DIAGNOSTICS_URI)) {
+      const read = await call("resources/read", { uri: DIAGNOSTICS_URI });
+      const contents = read.msg?.result?.contents;
+      diagnostics = typeof contents?.[0]?.text === "string" ? contents[0].text : "(diagnostics resource present but unreadable)";
+    }
+    return { kind: "ok", tools: tools.map((t) => String(t.name)), diagnostics, authUsed };
+  };
+  try {
+    if (auth.token) return await attempt(auth.token, "token");
+    const first = await attempt(void 0, "none");
+    if (first.kind === "gateway-jwt" && auth.anonKey) return await attempt(auth.anonKey, "anon-key");
+    return first;
+  } catch (err) {
+    return { kind: "error", detail: err instanceof Error ? err.message : String(err) };
+  }
+}
+function functionUrlFor(projectUrl) {
+  return `${projectUrl.replace(/\/+$/, "")}/functions/v1/${FUNCTION_NAME}`;
+}
+async function runDoctor(deps) {
+  const sections = [];
+  const project = [];
+  const toml = await deps.readText(CONFIG_TOML);
+  project.push(
+    toml !== null ? { status: "pass", message: `${CONFIG_TOML} found` } : { status: "warn", message: `no ${CONFIG_TOML} here`, fix: "run from your Supabase project root (or `supabase init` first)" }
+  );
+  if (deps.runSupabase) {
+    let version = "";
+    try {
+      version = deps.runSupabase(["--version"]).trim().split("\n")[0] ?? "";
+    } catch {
+    }
+    project.push({ status: "pass", message: `Supabase CLI ${version}`.trim() });
+  } else {
+    project.push({ status: "warn", message: "Supabase CLI not on PATH", fix: "install it: https://supabase.com/docs/guides/cli" });
+  }
+  project.push(
+    deps.projectRef ? { status: "pass", message: `project ${deps.projectRef}` } : { status: "warn", message: "no linked hosted project", fix: "supabase link --project-ref <ref>" }
+  );
+  sections.push({ title: "Project", checks: project });
+  const files = [];
+  const migration = findExistingMigration(await deps.listDir(MIGRATIONS_DIR), "_exposify_meta.sql");
+  files.push(
+    migration ? { status: "pass", message: `migration ${MIGRATIONS_DIR}/${migration}` } : { status: "fail", message: "no *_exposify_meta.sql migration", fix: "npx exposify-supabase init" }
+  );
+  const functionSource = await deps.readText(FUNCTION_PATH);
+  const authMode = functionSource === null ? null : detectAuthMode(functionSource);
+  files.push(
+    functionSource !== null ? { status: "pass", message: `function ${FUNCTION_PATH} (auth: ${AUTH_LABEL[authMode]})` } : { status: "fail", message: `no ${FUNCTION_PATH}`, fix: "npx exposify-supabase init" }
+  );
+  if (bypassesGatewayJwt2(authMode)) {
+    const verifyJwt = toml === null ? null : readFunctionVerifyJwt(toml);
+    const oauth = authMode === "oauth";
+    files.push(
+      verifyJwt === false ? {
+        status: "pass",
+        message: `verify_jwt = false for ${FUNCTION_NAME} (${oauth ? "the OAuth login challenge needs tokenless requests through" : "broker tokens aren't JWTs"})`
+      } : {
+        status: "fail",
+        message: `verify_jwt is ${verifyJwt === null ? "unset (defaults to on)" : "on"} for ${FUNCTION_NAME}; ` + (oauth ? "MCP clients will never get the OAuth login challenge" : "the gateway will reject every extb_... token"),
+        fix: "re-run `npx exposify-supabase init` (it sets it), or add `[functions.mcp] verify_jwt = false` to config.toml and redeploy"
+      }
+    );
+  }
+  sections.push({ title: "Local files", checks: files });
+  const db = [];
+  const conn = deps.connection;
+  if (!conn) {
+    db.push({
+      status: "fail",
+      message: "no credentials to reach the project",
+      fix: "start the local stack (`supabase start`), link a project (`supabase link`), or pass --url/--key" + (deps.connectionNotes.length ? ` [${deps.connectionNotes.join(" ")}]` : "")
+    });
+  } else {
+    db.push({ status: "pass", message: `credentials from ${conn.label}` });
+    const postgrestUrl = `${conn.url.replace(/\/+$/, "")}/rest/v1`;
+    const headers = new Headers({ authorization: `Bearer ${conn.serviceRoleKey}`, apikey: conn.serviceRoleKey });
+    const [openapi, meta] = await Promise.allSettled([
+      fetchOpenApi(postgrestUrl, headers, deps.fetch),
+      fetchExposifyMeta(postgrestUrl, headers, deps.fetch)
+    ]);
+    if (meta.status === "rejected") {
+      const err = meta.reason;
+      db.push(
+        err instanceof MissingExposifyMetaError ? { status: "fail", message: "exposify_meta() isn't in the database yet", fix: "supabase db push" } : { status: "fail", message: `exposify_meta() call failed: ${err instanceof Error ? err.message : String(err)}` }
+      );
+    } else {
+      const tableCount = new Set(meta.value.map((r) => r.table_name)).size;
+      db.push({ status: "pass", message: `exposify_meta() applied (${tableCount} table(s) in the catalog)` });
+    }
+    if (openapi.status === "rejected") {
+      const reason = openapi.reason instanceof Error ? openapi.reason.message : String(openapi.reason);
+      db.push({ status: "fail", message: reason.startsWith("PostgREST") ? reason : `PostgREST schema fetch failed: ${reason}` });
+    } else {
+      db.push({ status: "pass", message: "PostgREST schema readable" });
+    }
+    if (openapi.status === "fulfilled" && meta.status === "fulfilled") {
+      const tables = introspectTables(openapi.value, meta.value);
+      db.push(
+        tables.length > 0 ? { status: "pass", message: `${tables.length} table(s) exposed as tools: ${tables.map((t) => t.name).join(", ")}` } : { status: "warn", message: "no tables exposed (none have RLS on and API grants)", fix: "enable RLS on the tables agents should read" }
+      );
+      const { rlsOff, notGranted } = invisibleTables(meta.value, tables);
+      if (rlsOff.length > 0) {
+        db.push({
+          status: "warn",
+          message: `RLS off, so invisible to agents: ${rlsOff.join(", ")}`,
+          fix: "alter table <name> enable row level security; (only for tables agents should see)"
+        });
+      }
+      if (notGranted.length > 0) {
+        db.push({
+          status: "warn",
+          message: `RLS on but not exposed by PostgREST (no API role grants): ${notGranted.join(", ")}`,
+          fix: "grant select on <name> to authenticated;"
+        });
+      }
+      const undocumented = tablesMissingDocs(tables).filter((t) => t.missingTableComment || t.columnsWithoutComments.length > 0);
+      if (undocumented.length > 0) {
+        db.push({
+          status: "warn",
+          message: `${undocumented.length} table(s) missing comments, so tools have thin descriptions: ${undocumented.map((t) => t.name).join(", ")}`,
+          fix: "re-run `npx exposify-supabase init` and write descriptions, or add COMMENT ON TABLE/COLUMN"
+        });
+      }
+    }
+  }
+  sections.push({ title: "Database", checks: db });
+  const fn = [];
+  if (!conn) {
+    fn.push({ status: "skip", message: "skipped (no project URL)" });
+  } else {
+    const url = functionUrlFor(conn.url);
+    const outcome = await probeFunction(url, deps.fetch, { token: deps.token, anonKey: conn.anonKey });
+    fn.push(...probeChecks(url, outcome, authMode, conn.source === "local"));
+  }
+  if (authMode === "broker") fn.push(licenseSecretCheck(deps));
+  sections.push({ title: "Deployed function", checks: fn });
+  return sections;
+}
+function probeChecks(url, outcome, authMode, local) {
+  switch (outcome.kind) {
+    case "ok": {
+      const via = outcome.authUsed === "token" ? " with --token" : outcome.authUsed === "anon-key" ? " as the anon role" : "";
+      const checks = [
+        { status: outcome.tools.length > 0 ? "pass" : "warn", message: `${url} answers MCP${via}: ${outcome.tools.length} tool(s)` }
+      ];
+      if (outcome.diagnostics !== null) {
+        checks.push({
+          status: "warn",
+          message: `function is running degraded: ${outcome.diagnostics.replace(/\s+/g, " ").slice(0, 300)}`,
+          fix: "see the README's degradation section; usually a missing migration or SUPABASE_SERVICE_ROLE_KEY in the function"
+        });
+      }
+      return checks;
+    }
+    case "not-found":
+      return [
+        {
+          status: "fail",
+          message: `${url} returned 404 (function not deployed)`,
+          fix: local ? "supabase functions serve" : "supabase functions deploy mcp" + (bypassesGatewayJwt2(authMode) ? " --no-verify-jwt" : "")
+        }
+      ];
+    case "gateway-jwt":
+      return [
+        bypassesGatewayJwt2(authMode) ? {
+          status: "fail",
+          message: `the gateway rejected the request before the function ran: ${outcome.body}`,
+          fix: "supabase functions deploy mcp --no-verify-jwt (and keep verify_jwt = false in config.toml)"
+        } : {
+          status: "warn",
+          message: `${url} is deployed but the gateway wants a JWT to go further`,
+          fix: "pass --token <a user's access token> to list tools"
+        }
+      ];
+    case "auth-required":
+      if (bypassesGatewayJwt2(authMode) && outcome.authUsed === "anon-key") {
+        return [
+          {
+            status: "fail",
+            message: authMode === "oauth" ? `the gateway still checks JWTs for ${url}, so MCP clients never reach the function's OAuth login challenge` : `the gateway still checks JWTs for ${url}, so every extb_... broker token is rejected before the function runs`,
+            fix: "supabase functions deploy mcp --no-verify-jwt (and keep verify_jwt = false in config.toml)"
+          }
+        ];
+      }
+      return [
+        outcome.authUsed === "token" ? { status: "fail", message: `${url} rejected --token with 401`, fix: "check the token hasn't expired and belongs to this project" } : {
+          status: "warn",
+          message: `${url} is deployed and requires auth (authRequired)`,
+          fix: `pass --token <${authMode === "broker" ? "an extb_... broker token" : authMode === "oauth" ? "an OAuth access token" : "a user's access token"}> to list tools`
+        }
+      ];
+    case "error":
+      return [{ status: "fail", message: `couldn't talk MCP to ${url}: ${outcome.detail}` }];
+  }
+}
+function licenseSecretCheck(deps) {
+  if (!deps.runSupabase || !deps.projectRef) {
+    return { status: "skip", message: `${LICENSE_KEY_SECRET} secret not checked (needs the Supabase CLI and a linked project)` };
+  }
+  let names = null;
+  try {
+    names = parseSecretNames(deps.runSupabase(["secrets", "list", "--project-ref", deps.projectRef, "-o", "json"]));
+  } catch {
+  }
+  if (names === null) return { status: "skip", message: `${LICENSE_KEY_SECRET} secret not checked (\`supabase secrets list\` failed)` };
+  return names.includes(LICENSE_KEY_SECRET) ? { status: "pass", message: `${LICENSE_KEY_SECRET} secret is set` } : {
+    status: "fail",
+    message: `${LICENSE_KEY_SECRET} secret is missing; every request will 401`,
+    fix: `supabase secrets set ${LICENSE_KEY_SECRET}=<your license key (expfy_...)>`
+  };
+}
+var SYMBOL = { pass: "\u2713", warn: "!", fail: "\u2717", skip: "-" };
+function formatReport(sections) {
+  const lines = [];
+  for (const section of sections) {
+    lines.push(section.title);
+    for (const c of section.checks) {
+      lines.push(`  ${SYMBOL[c.status]} ${c.message}`);
+      if (c.fix && (c.status === "warn" || c.status === "fail")) lines.push(`      \u2192 ${c.fix}`);
+    }
+    lines.push("");
+  }
+  const all = sections.flatMap((s) => s.checks);
+  const count = (s) => all.filter((c) => c.status === s).length;
+  lines.push(`${count("pass")} passed, ${count("warn")} warning(s), ${count("fail")} failed`);
+  return lines.join("\n");
+}
+function hasFailures(sections) {
+  return sections.some((s) => s.checks.some((c) => c.status === "fail"));
+}
+
+// src/naming.ts
+function sanitizeIdentifier(name) {
+  return name.toLowerCase().replace(/[^a-z0-9_]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
+}
+
+// bin/plan.ts
+var FUNCTION_DIR = "supabase/functions/mcp";
+var FUNCTION_PATH2 = `${FUNCTION_DIR}/index.ts`;
+var MIGRATIONS_DIR2 = "supabase/migrations";
+var CONFIG_TOML2 = "supabase/config.toml";
+var META_SUFFIX = "_exposify_meta.sql";
+var COMMENTS_SUFFIX = "_exposify_comments.sql";
+function authLabel(config) {
+  return config.broker ? "hosted broker" : config.oauth ? "Supabase Auth OAuth" : "user JWT";
+}
+function describeConfigChange(from, to) {
+  const parts = [];
+  const diff = (label, a, b) => {
+    const added = b.filter((x) => !a.includes(x)).map((x) => `+${x}`);
+    const removed = a.filter((x) => !b.includes(x)).map((x) => `-${x}`);
+    if (added.length || removed.length) parts.push(`${label}: ${[...added, ...removed].join(" ")}`);
+  };
+  diff("writes", from.writes, to.writes);
+  diff("rpc", from.rpc, to.rpc);
+  if (from.anonymousSignIn !== to.anonymousSignIn) {
+    parts.push(to.anonymousSignIn ? "+anonymous sign-in warning" : "-anonymous sign-in warning");
+  }
+  if (authLabel(from) !== authLabel(to)) {
+    parts.push(`auth: ${authLabel(from)} -> ${authLabel(to)}`);
+  } else if (from.broker?.brokerUrl !== to.broker?.brokerUrl || from.broker?.projectId !== to.broker?.projectId) {
+    parts.push("hosted broker settings");
+  }
+  return parts.join("; ");
+}
+function planInit(input) {
+  const changes = [];
+  const warnings = [];
+  let mergeSnippet = null;
+  const taken = [...input.migrations];
+  if (!findExistingMigration(input.migrations, META_SUFFIX)) {
+    const name = uniqueMigrationFilename(taken, `${input.timestamp}${META_SUFFIX}`);
+    taken.push(name);
+    changes.push({
+      path: `${MIGRATIONS_DIR2}/${name}`,
+      action: "create",
+      summary: "exposify_meta() migration",
+      content: input.metaMigrationSql,
+      effect: "push"
+    });
+  }
+  const fn = input.functionFile;
+  const canWrite = !fn || fn.state.kind === "managed";
+  const fileConfig = canWrite ? input.desired : fn.state.config;
+  if (!fn) {
+    changes.push({
+      path: FUNCTION_PATH2,
+      action: "create",
+      summary: "MCP edge function",
+      content: buildFunctionFile(input.desired),
+      effect: "deploy"
+    });
+  } else if (!configsEqual(fn.state.config, input.desired)) {
+    const summary = describeConfigChange(fn.state.config, input.desired);
+    if (fn.state.kind === "managed") {
+      changes.push({
+        path: FUNCTION_PATH2,
+        action: "update",
+        summary,
+        content: replaceManagedBlock(fn.text, input.desired),
+        effect: "deploy"
+      });
+    } else {
+      mergeSnippet = buildManagedBlock(input.desired);
+      warnings.push(
+        fn.state.kind === "modified" ? `${FUNCTION_PATH2}'s exposify:begin/end block was edited by hand, so it was left untouched (${summary}). Merge the block below in yourself.` : `${FUNCTION_PATH2} has no exposify:begin/end block (hand-written, or generated by an older init), so it was left untouched (${summary}). Merge the block below in yourself.`
+      );
+    }
+  }
+  if (bypassesGatewayJwt(input.desired) && !bypassesGatewayJwt(fileConfig)) {
+    warnings.push(
+      `${CONFIG_TOML2} was left alone too: verify_jwt stays on until the ${input.desired.oauth ? "OAuth" : "broker"} wiring is actually in ${FUNCTION_PATH2} (turning it off first would let tokenless requests run as anon). Re-run init after merging.`
+    );
+  } else if (bypassesGatewayJwt(fileConfig)) {
+    if (input.configToml === null) {
+      warnings.push(
+        `no ${CONFIG_TOML2} to record verify_jwt = false in -- always deploy with \`supabase functions deploy mcp --no-verify-jwt\` (${gatewayJwtReason(fileConfig)}).`
+      );
+    } else {
+      const { toml, changed } = setFunctionVerifyJwtFalse(input.configToml);
+      if (changed) {
+        changes.push({
+          path: CONFIG_TOML2,
+          action: "update",
+          summary: `[functions.mcp] verify_jwt = false (${gatewayJwtReason(fileConfig)})`,
+          content: toml,
+          effect: "deploy"
+        });
+      }
+    }
+  } else if (fn && bypassesGatewayJwt(fn.state.config) && canWrite && input.configToml !== null && readFunctionVerifyJwt(input.configToml) === false) {
+    warnings.push(
+      `the ${fn.state.config.oauth ? "OAuth sign-in" : "hosted broker"} was removed, but ${CONFIG_TOML2} still has verify_jwt = false for mcp, so requests without a JWT reach the function and run as anon. If you want the gateway to require a JWT again, set verify_jwt = true there and redeploy.`
+    );
+  }
+  if (input.commentsSql) {
+    const name = uniqueMigrationFilename(taken, `${input.timestamp}${COMMENTS_SUFFIX}`);
+    changes.push({
+      path: `${MIGRATIONS_DIR2}/${name}`,
+      action: "create",
+      summary: "table/column descriptions",
+      content: input.commentsSql,
+      effect: "push"
+    });
+  }
+  return { changes, fileConfig, mergeSnippet, warnings };
+}
+function needsPush(changes) {
+  return changes.some((c) => c.effect === "push");
+}
+function needsDeploy(changes) {
+  return changes.some((c) => c.effect === "deploy");
+}
+function formatPlan(changes) {
+  return changes.map((c) => `  ${c.action === "create" ? "+" : "~"} ${c.path}${c.summary ? `  (${c.summary})` : ""}`).join("\n");
+}
+var IDENT = `(?:"(?:[^"]|"")+"|[A-Za-z_][A-Za-z0-9_$]*)`;
+function unquote(ident) {
+  return ident.startsWith('"') ? ident.slice(1, -1).replace(/""/g, '"') : ident.toLowerCase();
+}
+function parseCommentMigration(sql) {
+  const keys = /* @__PURE__ */ new Set();
+  const value = `\\s+is\\s+(?:'|E'|\\$)`;
+  const table = new RegExp(`comment\\s+on\\s+table\\s+(?:public\\.)?(${IDENT})${value}`, "gi");
+  const column = new RegExp(`comment\\s+on\\s+column\\s+(?:public\\.)?(${IDENT})\\.(${IDENT})${value}`, "gi");
+  for (const m of sql.matchAll(table)) keys.add(unquote(m[1]));
+  for (const m of sql.matchAll(column)) keys.add(`${unquote(m[1])}.${unquote(m[2])}`);
+  return keys;
+}
+function withoutLocallyDocumented(status, documented) {
+  return status.map((t) => ({
+    name: t.name,
+    missingTableComment: t.missingTableComment && !documented.has(t.name),
+    columnsWithoutComments: t.columnsWithoutComments.filter((c) => !documented.has(`${t.name}.${c}`))
+  }));
+}
+function pendingComments(tables, documented) {
+  const pending = [];
+  for (const t of tables) {
+    if (documented.has(t.name) && !t.description) pending.push(t.name);
+    for (const c of t.columns) if (documented.has(`${t.name}.${c.name}`) && !c.description) pending.push(`${t.name}.${c.name}`);
+  }
+  return pending;
+}
+function staleFunctionReason(probe, config, exposedTables) {
+  if (bypassesGatewayJwt(config) && probe.kind === "ok" && probe.authUsed !== "token") {
+    return config.oauth ? "the deployed function answers without a token, but the local config requires an OAuth sign-in." : "the deployed function answers without a token, but the local config requires the hosted broker's.";
+  }
+  if (bypassesGatewayJwt(config) && (probe.kind === "gateway-jwt" || "authUsed" in probe && probe.authUsed === "anon-key")) {
+    return config.oauth ? "the gateway still checks JWTs for the function, so MCP clients never get the login challenge (deploy with --no-verify-jwt)." : "the gateway still checks JWTs for the function, so broker tokens are rejected (deploy with --no-verify-jwt).";
+  }
+  if (probe.kind !== "ok" || !exposedTables) return null;
+  const exposed = new Set(exposedTables.map((t) => t.name));
+  const expected = /* @__PURE__ */ new Set();
+  for (const w of config.writes) {
+    const dot = w.lastIndexOf(".");
+    const table = w.slice(0, dot);
+    if (!exposed.has(table)) continue;
+    const op = w.slice(dot + 1);
+    for (const o of op === "*" ? ["insert", "update", "delete"] : [op]) expected.add(`${o}_${sanitizeIdentifier(table)}`);
+  }
+  for (const fn of config.rpc) expected.add(`rpc_${sanitizeIdentifier(fn)}`);
+  const live = new Set(probe.tools.filter((t) => /^(insert|update|delete|rpc)_/.test(t)));
+  const missing = [...expected].filter((t) => !live.has(t));
+  const extra = [...live].filter((t) => !expected.has(t));
+  if (missing.length === 0 && extra.length === 0) return null;
+  const parts = [missing.length && `missing ${missing.join(", ")}`, extra.length && `still has ${extra.join(", ")}`].filter(Boolean);
+  return `the deployed function's tools don't match the local config (${parts.join("; ")}).`;
+}
+function liveVerdict(s) {
+  const notes = [];
+  let push = false;
+  let deploy = false;
+  if (s.migrationApplied === false) {
+    push = true;
+    notes.push("exposify_meta() isn't in the database yet (migration not pushed).");
+  }
+  if (s.pendingComments.length > 0) {
+    push = true;
+    notes.push(`descriptions written locally but not pushed: ${s.pendingComments.join(", ")}.`);
+  }
+  if (s.functionDeployed === false) {
+    deploy = true;
+    notes.push("the mcp function isn't deployed.");
+  } else if (s.functionStale) {
+    deploy = true;
+    notes.push(s.functionStale);
+  }
+  if (s.migrationApplied === null) notes.push("couldn't check whether the migration is applied.");
+  if (s.functionDeployed === null) notes.push("couldn't check whether the function is deployed.");
+  const upToDate = !push && !deploy && s.migrationApplied === true && s.functionDeployed === true;
+  return { upToDate, push, deploy, notes };
+}
+function manifestsEquivalent(a, b) {
+  if (!b || typeof b !== "object") return false;
+  const strip = (m) => JSON.stringify({ ...m, generatedAt: void 0 });
+  return strip(a) === strip(b);
+}
+
+// bin/cli.ts
+var PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 var FETCH_TIMEOUT_MS = 1e4;
 function fetchWithTimeout(input, init) {
   return fetch(input, { ...init, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
@@ -318,6 +1079,13 @@ async function listFilesOrEmpty(dir) {
     return [];
   }
 }
+async function readOrNull(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+}
 async function exists(path) {
   try {
     await access(path);
@@ -347,51 +1115,115 @@ async function promptYesNo(rl, question, defaultYes = false) {
 async function promptText(rl, question) {
   return (await rl.question(question)).trim();
 }
-function deployArgs(broker) {
-  return ["functions", "deploy", "mcp", ...broker ? ["--no-verify-jwt"] : []];
+var OAUTH_DASHBOARD_STEP = "In the Supabase dashboard (Authentication > OAuth Server, beta): enable the server and dynamic client registration, set the authorization path to a consent page your app hosts (built with supabase.auth.oauth.approveAuthorization), and make sure the project uses asymmetric JWT signing keys (supabaseAuth() verifies tokens via JWKS)";
+function deployArgs(auth) {
+  return ["functions", "deploy", "mcp", ...bypassesGatewayJwt(auth) ? ["--no-verify-jwt"] : []];
 }
-function clientCredential(broker) {
-  return broker ? "a broker token (extb_..., minted by the hosted broker)" : "a user JWT";
+function clientStep(auth) {
+  if (auth.oauth) return "Add the function URL to an MCP client; it opens a Supabase Auth login on connect.";
+  const credential = auth.broker ? "a broker token (extb_..., minted by the hosted broker)" : "a user JWT";
+  return `Paste the function URL + ${credential} into an MCP client.`;
 }
-function printManualCommands(opts = {}) {
-  const broker = opts.broker ?? null;
+function printManualCommands(steps, auth) {
   console.log("\nRun these to finish setup:");
-  const steps = [];
-  if (!opts.alreadyPushed) steps.push("supabase db push");
-  if (broker) steps.push(`supabase secrets set ${LICENSE_KEY_SECRET}=<your license key (expfy_...)>`);
-  if (!opts.alreadyDeployed) steps.push(`supabase ${deployArgs(broker).join(" ")}`);
-  steps.forEach((cmd, i) => console.log(`  ${i + 1}. ${cmd}`));
-  console.log(`  ${steps.length + 1}. Paste the function URL + ${clientCredential(broker)} into an MCP client.`);
-}
-function printLicenseKeyReminder(broker) {
-  if (!broker) return;
+  const lines = [];
+  if (steps.push) lines.push("supabase db push");
+  if (auth.broker) lines.push(`supabase secrets set ${LICENSE_KEY_SECRET}=<your license key (expfy_...)>`);
+  if (auth.oauth) lines.push(OAUTH_DASHBOARD_STEP);
+  if (steps.deploy) lines.push(`supabase ${deployArgs(auth).join(" ")}`);
+  lines.forEach((cmd, i) => console.log(`  ${i + 1}. ${cmd}`));
+  console.log(`  ${lines.length + 1}. ${clientStep(auth)}`);
+}
+function printLicenseKeyReminder(auth) {
+  if (!auth.broker) return;
   console.log(
     `
 If you haven't already: supabase secrets set ${LICENSE_KEY_SECRET}=<your license key (expfy_...)> -- until it's set, every request is rejected with 401.`
   );
 }
-function pushAndDeploy(broker) {
-  let pushed = false;
+function runSteps(steps, auth) {
+  const done = { push: false, deploy: false };
   try {
-    console.log("\n$ supabase db push");
-    execFileSync("supabase", ["db", "push"], { stdio: "inherit" });
-    pushed = true;
-    const args = deployArgs(broker);
-    console.log(`
+    if (steps.push) {
+      console.log("\n$ supabase db push");
+      execFileSync("supabase", ["db", "push"], { stdio: "inherit" });
+      done.push = true;
+    }
+    if (steps.deploy) {
+      const args = deployArgs(auth);
+      console.log(`
 $ supabase ${args.join(" ")}`);
-    execFileSync("supabase", args, { stdio: "inherit" });
-    return { pushed: true, deployed: true };
+      execFileSync("supabase", args, { stdio: "inherit" });
+      done.deploy = true;
+    }
+    return { done };
   } catch (err) {
-    return { pushed, deployed: false, error: err };
+    return { done, error: err };
   }
 }
-function resolveConnectionInfo() {
-  const url = process.env.SUPABASE_URL ?? argValue("--url");
-  const serviceRoleKey = process.env.SUPABASE_SERVICE_ROLE_KEY ?? argValue("--key");
-  if (!url || !serviceRoleKey) return null;
-  return { url, serviceRoleKey };
+async function offerSteps(rl, steps, auth, defaultYes = false) {
+  if (!steps.push && !steps.deploy) return true;
+  if (!rl) {
+    printManualCommands(steps, auth);
+    return false;
+  }
+  if (!hasSupabaseCli()) {
+    console.log("\nSupabase CLI not found on PATH -- install it to run the next steps automatically next time.");
+    printManualCommands(steps, auth);
+    return false;
+  }
+  const what = [steps.push && "`supabase db push`", steps.deploy && "`supabase functions deploy mcp`"].filter(Boolean).join(" and ");
+  if (!await promptYesNo(rl, `
+Run ${what} against whatever Supabase project is currently linked, now?`, defaultYes)) {
+    printManualCommands(steps, auth);
+    return false;
+  }
+  const result = runSteps(steps, auth);
+  if (result.error !== void 0) {
+    console.error(`
+Supabase CLI command failed: ${result.error instanceof Error ? result.error.message : result.error}`);
+    printManualCommands({ push: steps.push && !result.done.push, deploy: steps.deploy && !result.done.deploy }, auth);
+    return false;
+  }
+  printLicenseKeyReminder(auth);
+  return true;
+}
+function supabaseRunner() {
+  if (!hasSupabaseCli()) return null;
+  return (args) => execFileSync("supabase", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 3e4 });
+}
+async function readLinkedProjectRef() {
+  return (await readOrNull(PROJECT_REF_FILE))?.trim() || null;
+}
+async function resolveConnection(rl, opts = {}) {
+  const linkedRef = await readLinkedProjectRef();
+  const explicit = explicitConnection({
+    flagUrl: argValue("--url"),
+    flagKey: argValue("--key"),
+    envUrl: process.env.SUPABASE_URL,
+    envKey: process.env.SUPABASE_SERVICE_ROLE_KEY,
+    envAnonKey: process.env.SUPABASE_ANON_KEY
+  });
+  if (explicit) return { connection: explicit, notes: [], projectRef: projectRefFromUrl(explicit.url) };
+  const prefer = process.argv.includes("--local") ? "local" : process.argv.includes("--linked") ? "linked" : void 0;
+  const { connection, notes } = await discoverConnection({
+    run: supabaseRunner(),
+    projectRef: linkedRef,
+    prefer,
+    choose: rl ? async ({ localUrl, projectRef }) => {
+      const useLocal = await promptYesNo(
+        rl,
+        `
+Both a local stack (${localUrl}) and a linked project (${projectRef}) are available. Use the local stack?`
+      );
+      return useLocal ? "local" : "linked";
+    } : void 0
+  });
+  if (connection && !opts.quiet) console.log(`Using credentials from ${connection.label}.`);
+  return { connection, notes, projectRef: connection?.source === "local" ? null : linkedRef };
 }
 async function tryIntrospect(conn) {
+  if (!conn) return { introspection: null, migrationApplied: null };
   try {
     const postgrestUrl = `${conn.url.replace(/\/+$/, "")}/rest/v1`;
     const headers = new Headers({ authorization: `Bearer ${conn.serviceRoleKey}`, apikey: conn.serviceRoleKey });
@@ -399,13 +1231,12 @@ async function tryIntrospect(conn) {
       fetchOpenApi(postgrestUrl, headers, fetchWithTimeout),
       fetchExposifyMeta(postgrestUrl, headers, fetchWithTimeout)
     ]);
-    return { tables: introspectTables(openapi, metaRows), openapi };
+    return { introspection: { tables: introspectTables(openapi, metaRows), openapi }, migrationApplied: true };
   } catch (err) {
-    if (!(err instanceof MissingExposifyMetaError)) {
-      console.log(`
+    if (err instanceof MissingExposifyMetaError) return { introspection: null, migrationApplied: false };
+    console.log(`
 Couldn't introspect the project: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    return null;
+    return { introspection: null, migrationApplied: null };
   }
 }
 async function tryDetectAnonymousSignIn(conn) {
@@ -420,7 +1251,7 @@ async function tryDetectAnonymousSignIn(conn) {
     return null;
   }
 }
-async function askAnonymousSignIn(rl, conn) {
+async function askAnonymousSignIn(rl, conn, current) {
   const detected = conn ? await tryDetectAnonymousSignIn(conn) : null;
   if (detected !== null) {
     console.log(`
@@ -428,33 +1259,43 @@ Detected: anonymous sign-in is ${detected ? "enabled" : "disabled"} on this proj
     const confirmed = await promptYesNo(rl, "Is that correct?", true);
     if (confirmed) return detected;
   }
-  return promptYesNo(rl, "\nDoes this Supabase project have anonymous sign-in enabled (Authentication \u2192 Sign In / Providers \u2192 Anonymous)?");
+  return promptYesNo(
+    rl,
+    "\nDoes this Supabase project have anonymous sign-in enabled (Authentication \u2192 Sign In / Providers \u2192 Anonymous)?",
+    current
+  );
 }
-async function askWriteGrants(rl, tables) {
-  if (tables.length === 0) return [];
-  const configure = await promptYesNo(rl, `
-Configure write access for ${tables.length} table(s)?`);
-  if (!configure) return [];
-  const grants = [];
+async function askWriteGrants(rl, tables, current) {
+  if (tables.length === 0) return current;
+  const byTable = writesByTable(current);
+  const intro = current.length > 0 ? ` (currently: ${current.join(", ")})` : "";
+  if (!await promptYesNo(rl, `
+Configure write access for ${tables.length} table(s)${intro}?`)) return current;
+  console.log("  i=insert, u=update, d=delete, comma-separated. Enter keeps the current value, - clears it.");
+  const result = [];
   for (const table of tables) {
-    const answer = await promptText(
-      rl,
-      `  ${table.name} -- grant writes? (i=insert, u=update, d=delete, comma-separate, Enter=none): `
-    );
-    const ops = parseWriteOpsAnswer(answer);
-    if (ops.length > 0) grants.push({ table: table.name, ops });
+    const now = byTable.get(table.name) ?? [];
+    const answer = await promptText(rl, `  ${table.name} [${writesLabel(now)}]: `);
+    const { value, note } = resolveWritesAnswer(answer, table.name, now);
+    if (note) console.log(`    ${note}`);
+    result.push(...value);
+    byTable.delete(table.name);
   }
-  return grants;
+  for (const rest of byTable.values()) result.push(...rest);
+  return result;
 }
-async function askRpcSelection(rl, candidates) {
-  if (candidates.length === 0) return [];
+async function askRpcSelection(rl, candidates, current) {
+  if (candidates.length === 0) return current;
   console.log(`
 Available Postgres functions: ${candidates.join(", ")}`);
-  const answer = await promptText(rl, "Expose any as tools? (comma-separate, Enter=none): ");
-  return parseSelectionAnswer(answer, candidates);
+  const hint = current.length > 0 ? `Enter keeps [${current.join(", ")}], - clears` : "Enter=none";
+  const answer = await promptText(rl, `Expose any as tools? (comma-separate, ${hint}): `);
+  const { value, note } = resolveSelectionAnswer(answer, candidates, current);
+  if (note) console.log(`  ${note}`);
+  return value;
 }
-async function askDocumentation(rl, tables) {
-  const missing = tablesMissingDocs(tables).filter((t) => t.missingTableComment || t.columnsWithoutComments.length > 0);
+async function askDocumentation(rl, status) {
+  const missing = status.filter((t) => t.missingTableComment || t.columnsWithoutComments.length > 0);
   if (missing.length === 0) return [];
   const configure = await promptYesNo(
     rl,
@@ -485,37 +1326,16 @@ ${missing.length} table(s) are missing documentation MCP tools would otherwise s
   }
   return entries;
 }
-async function writeCommentsMigration(entries) {
-  const sql = buildCommentStatements(entries);
-  if (!sql) return null;
-  await mkdir(MIGRATIONS_DIR, { recursive: true });
-  const existing = await listFilesOrEmpty(MIGRATIONS_DIR);
-  const filename = uniqueMigrationFilename(existing, `${timestamp()}_exposify_comments.sql`);
-  const path = join(MIGRATIONS_DIR, filename);
-  await writeFile(path, sql);
-  return path;
-}
-async function ensureMetaMigration() {
-  await mkdir(MIGRATIONS_DIR, { recursive: true });
-  const existing = await listFilesOrEmpty(MIGRATIONS_DIR);
-  const found = findExistingMigration(existing, "_exposify_meta.sql");
-  if (found) return { path: join(MIGRATIONS_DIR, found), wasNew: false };
-  const migrationSql = await readFile(join(PACKAGE_ROOT, "sql/exposify_meta.sql"), "utf8");
-  const filename = uniqueMigrationFilename(existing, `${timestamp()}_exposify_meta.sql`);
-  const path = join(MIGRATIONS_DIR, filename);
-  await writeFile(path, migrationSql);
-  return { path, wasNew: true };
-}
 async function warnIfNotSupabaseProject() {
-  if (!await exists("supabase/config.toml")) {
+  if (!await exists(CONFIG_TOML2)) {
     console.warn(
       "warn: no supabase/config.toml found here -- this doesn't look like a Supabase project root (or you haven't run `supabase init` yet). Continuing, but double-check you're in the right directory."
     );
   }
 }
 function brokerFromFlags() {
-  const flagUrl = process.env.EXPOSIFY_BROKER_URL ?? argValue("--broker-url");
-  const flagProject = process.env.EXPOSIFY_PROJECT_ID ?? argValue("--broker-project");
+  const flagUrl = argValue("--broker-url") ?? process.env.EXPOSIFY_BROKER_URL;
+  const flagProject = argValue("--broker-project") ?? process.env.EXPOSIFY_PROJECT_ID;
   if (!flagUrl && !flagProject) return void 0;
   if (!flagUrl || !flagProject) {
     throw new Error("the hosted broker needs both --broker-url and --broker-project (or EXPOSIFY_BROKER_URL/EXPOSIFY_PROJECT_ID).");
@@ -524,178 +1344,201 @@ function brokerFromFlags() {
   if (problem) throw new Error(problem);
   return { brokerUrl: normalizeBrokerUrl(flagUrl), projectId: flagProject.trim() };
 }
-async function resolveBroker(rl, fromFlags) {
-  if (fromFlags) return fromFlags;
-  if (!rl) return null;
+function authFromFlags() {
+  const broker = brokerFromFlags();
+  const oauth = process.argv.includes("--oauth") || process.env.EXPOSIFY_OAUTH === "1";
+  if (broker && oauth) throw new Error("--oauth can't be combined with the hosted broker flags; pick one.");
+  if (broker) return { broker, oauth: false };
+  if (oauth) return { broker: null, oauth: true };
+  return void 0;
+}
+async function askAuth(rl, current) {
+  const broker = await askBroker(rl, current.broker);
+  if (broker) return { broker, oauth: false };
+  const oauth = await promptYesNo(
+    rl,
+    '\nLet MCP clients sign in with Supabase Auth ("click Connect and log in"; needs the OAuth 2.1 server enabled in the dashboard)?',
+    current.oauth
+  );
+  return { broker: null, oauth };
+}
+async function askBroker(rl, current) {
   const use = await promptYesNo(
     rl,
-    "\nUse the Exposify hosted broker for auth (MCP clients get a long-lived extb_... token instead of a Supabase JWT)?"
+    "\nUse the Exposify hosted broker for auth (MCP clients get a long-lived extb_... token instead of a Supabase JWT)?",
+    current !== null
   );
   if (!use) return null;
   let brokerUrl = "";
   for (; ; ) {
-    brokerUrl = normalizeBrokerUrl(await promptText(rl, "  Broker URL (from the dashboard's Hosted broker card): "));
+    const hint = current ? ` [${current.brokerUrl}]` : "";
+    const answer = await promptText(rl, `  Broker URL (from the dashboard's Hosted broker card)${hint}: `);
+    brokerUrl = normalizeBrokerUrl(answer || current?.brokerUrl || "");
     const problem = brokerUrlProblem(brokerUrl);
     if (!problem) break;
     console.log(`  ${problem}`);
   }
   let projectId = "";
-  while (!projectId) projectId = await promptText(rl, "  Project ID: ");
+  while (!projectId) {
+    const hint = current ? ` [${current.projectId}]` : "";
+    projectId = await promptText(rl, `  Project ID${hint}: `) || current?.projectId || "";
+  }
   return { brokerUrl, projectId };
 }
-async function disableJwtVerification() {
-  if (!await exists(CONFIG_TOML)) {
-    console.warn(
-      `warn: no ${CONFIG_TOML} to record verify_jwt = false in -- always deploy with \`supabase functions deploy mcp --no-verify-jwt\`, or broker tokens will be rejected with "Invalid JWT".`
-    );
-    return;
+async function readLocalState() {
+  const migrations = await listFilesOrEmpty(MIGRATIONS_DIR2);
+  const text = await readOrNull(FUNCTION_PATH2);
+  const documented = /* @__PURE__ */ new Set();
+  for (const name of migrations.filter((m) => m.endsWith(COMMENTS_SUFFIX))) {
+    for (const key of parseCommentMigration(await readOrNull(join(MIGRATIONS_DIR2, name)) ?? "")) documented.add(key);
   }
-  const { toml, changed } = setFunctionVerifyJwtFalse(await readFile(CONFIG_TOML, "utf8"));
-  if (!changed) {
-    console.log(`Skipped ${CONFIG_TOML} (verify_jwt already false for mcp)`);
-    return;
+  return {
+    migrations,
+    functionFile: text === null ? null : { text, state: parseFunctionFile(text) },
+    configToml: await readOrNull(CONFIG_TOML2),
+    documented,
+    metaMigrationSql: await readFile(join(PACKAGE_ROOT, "sql/exposify_meta.sql"), "utf8")
+  };
+}
+async function applyPlan(plan) {
+  for (const change of plan.changes) {
+    await mkdir(dirname(change.path), { recursive: true });
+    await writeFile(change.path, change.content);
+    if (change.path === FUNCTION_PATH2 && change.action === "create") await mkdir(join(FUNCTION_DIR, "docs"), { recursive: true });
   }
-  await writeFile(CONFIG_TOML, toml);
-  console.log(`Updated ${CONFIG_TOML}: [functions.mcp] verify_jwt = false (broker tokens aren't Supabase JWTs)`);
+  if (plan.changes.length > 0) console.log(`
+Changes:
+${formatPlan(plan.changes)}`);
+  for (const w of plan.warnings) console.warn(`
+warn: ${w}`);
+  if (plan.mergeSnippet) console.log(`
+${plan.mergeSnippet}`);
+}
+async function runWizard(rl, introspection, base, documented) {
+  const writes = await askWriteGrants(rl, introspection.tables, base.writes);
+  const rpc = await askRpcSelection(rl, rpcCandidatesFromOpenApi(introspection.openapi), base.rpc);
+  const docs = await askDocumentation(rl, withoutLocallyDocumented(tablesMissingDocs(introspection.tables), documented));
+  return { config: { ...base, writes, rpc }, commentsSql: buildCommentStatements(docs) };
+}
+async function checkLive(conn, known, local, config) {
+  if (!conn) return { migrationApplied: null, functionDeployed: null, pendingComments: [] };
+  const intro = known?.introspection ? known : await tryIntrospect(conn);
+  const probe = await probeFunction(functionUrlFor(conn.url), fetchWithTimeout, { anonKey: conn.anonKey });
+  return {
+    migrationApplied: intro.migrationApplied,
+    functionDeployed: probe.kind === "not-found" ? false : probe.kind === "error" ? null : true,
+    pendingComments: intro.introspection ? pendingComments(intro.introspection.tables, local.documented) : [],
+    // Only meaningful for a file init manages -- for anything else, `config` is a best-effort guess.
+    functionStale: local.functionFile?.state.kind === "managed" ? staleFunctionReason(probe, config, intro.introspection?.tables ?? null) : null
+  };
 }
 async function cmdInit() {
-  const brokerFlags = brokerFromFlags();
+  const check = process.argv.includes("--check");
+  const authFlags = authFromFlags();
   await warnIfNotSupabaseProject();
-  const { path: migrationPath, wasNew } = await ensureMetaMigration();
-  console.log(wasNew ? `Wrote ${migrationPath}` : `Skipped ${migrationPath} (already scaffolded)`);
-  await mkdir(FUNCTION_DIR, { recursive: true });
-  const functionPath = join(FUNCTION_DIR, "index.ts");
-  const functionExists = await exists(functionPath);
-  await mkdir(join(FUNCTION_DIR, "docs"), { recursive: true });
   const connWarning = partialConnectionWarning(
-    process.env.SUPABASE_URL ?? argValue("--url"),
-    process.env.SUPABASE_SERVICE_ROLE_KEY ?? argValue("--key")
+    argValue("--url") ?? process.env.SUPABASE_URL,
+    argValue("--key") ?? process.env.SUPABASE_SERVICE_ROLE_KEY
   );
   if (connWarning) console.warn(`warn: ${connWarning}`);
-  const rl = openInteractiveReadline();
-  if (!rl) {
-    const broker = await resolveBroker(null, brokerFlags);
-    if (broker) await disableJwtVerification();
-    if (!functionExists) {
-      await writeFile(functionPath, buildFunctionTemplate({ broker: broker ?? void 0 }));
-      console.log(`Wrote ${functionPath}`);
-    } else {
-      console.log(`Skipped ${functionPath} (already exists)`);
-      if (broker) printBrokerMergeHint(functionPath, broker);
-    }
-    printManualCommands({ broker });
-    return;
-  }
+  const rl = check ? null : openInteractiveReadline();
   try {
-    const conn = resolveConnectionInfo();
-    const broker = await resolveBroker(rl, brokerFlags);
-    if (broker) await disableJwtVerification();
-    const anonymousSignIn = await askAnonymousSignIn(rl, conn);
-    let introspection = conn ? await tryIntrospect(conn) : null;
-    let alreadyPushed = false;
-    let alreadyDeployed = false;
-    let brokerHintShown = false;
-    if (!introspection) {
-      if (!functionExists) {
-        await writeFile(functionPath, buildFunctionTemplate({ anonymousSignIn, broker: broker ?? void 0 }));
-        console.log(`Wrote ${functionPath}`);
-      } else {
-        console.log(`Skipped ${functionPath} (already exists)`);
-        if (broker) {
-          printBrokerMergeHint(functionPath, broker);
-          brokerHintShown = true;
-        }
+    const local = await readLocalState();
+    const current = local.functionFile?.state.config ?? EMPTY_CONFIG;
+    let conn;
+    const getConn = async () => conn !== void 0 ? conn : conn = (await resolveConnection(rl)).connection;
+    const auth = authFlags ?? (rl ? await askAuth(rl, current) : { broker: current.broker, oauth: current.oauth });
+    const anonymousSignIn = rl ? await askAnonymousSignIn(rl, await getConn(), current.anonymousSignIn) : current.anonymousSignIn;
+    let desired = { ...current, ...auth, anonymousSignIn };
+    let intro = null;
+    let commentsSql = "";
+    if (rl) {
+      intro = await tryIntrospect(await getConn());
+      if (intro.introspection) ({ config: desired, commentsSql } = await runWizard(rl, intro.introspection, desired, local.documented));
+    }
+    const plan = planInit({ ...local, desired, commentsSql, timestamp: timestamp() });
+    if (check) {
+      if (plan.changes.length === 0 && !plan.mergeSnippet) {
+        console.log("init --check: up to date, a run would change nothing.");
+        return;
       }
-      if (!hasSupabaseCli()) {
-        console.log("\nSupabase CLI not found on PATH -- install it to run the next steps automatically next time.");
-        printManualCommands({ broker });
+      console.log("init --check: a run would change:");
+      if (plan.changes.length > 0) console.log(formatPlan(plan.changes));
+      for (const w of plan.warnings) console.log(`  ! ${w}`);
+      process.exitCode = 1;
+      return;
+    }
+    await applyPlan(plan);
+    const effectiveAuth = plan.fileConfig;
+    let steps;
+    if (plan.changes.length === 0 && plan.mergeSnippet) {
+      console.log(`
+No files were changed. Merge the block above into ${FUNCTION_PATH2}, then re-run init.`);
+      return;
+    }
+    if (plan.changes.length > 0) {
+      steps = { push: needsPush(plan.changes), deploy: needsDeploy(plan.changes) };
+    } else {
+      const c = await getConn();
+      const verdict = liveVerdict(await checkLive(c, intro, local, plan.fileConfig));
+      if (verdict.upToDate) {
+        console.log("\nAlready up to date: no file changes, the migration is applied and the function is deployed. Nothing to do.");
         return;
       }
-      const connect = await promptYesNo(
-        rl,
-        "\nApply the migration and deploy the function to whatever Supabase project is currently linked, now?"
-      );
-      if (!connect) {
-        printManualCommands({ broker });
+      if (!c) {
+        console.log(
+          "\nNothing changed locally. Couldn't check the project itself (no --url/--key, env vars, or local/linked project) -- run `npx exposify-supabase doctor` once it's reachable."
+        );
         return;
       }
-      const result2 = pushAndDeploy(broker);
-      alreadyPushed = result2.pushed;
-      alreadyDeployed = result2.deployed;
-      if (!result2.deployed) {
-        console.error(`
-Supabase CLI command failed: ${result2.error instanceof Error ? result2.error.message : result2.error}`);
-        printManualCommands({ alreadyPushed, broker });
+      console.log("\nNothing changed locally, but the project is behind:");
+      for (const n of verdict.notes) console.log(`  - ${n}`);
+      if (!verdict.push && !verdict.deploy) {
+        console.log("Run `npx exposify-supabase doctor` for details.");
         return;
       }
-      printLicenseKeyReminder(broker);
-      introspection = conn ? await tryIntrospect(conn) : null;
-      if (!introspection) {
+      if (c.source === "local") {
+        const todo = [verdict.push && "`supabase migration up`", verdict.deploy && `\`supabase functions serve mcp${bypassesGatewayJwt(effectiveAuth) ? " --no-verify-jwt" : ""}\``].filter(Boolean);
+        console.log(`
+That's the local stack: run ${todo.join(" and ")}.`);
+        return;
+      }
+      steps = { push: verdict.push, deploy: verdict.deploy };
+    }
+    if (!await offerSteps(rl, steps, effectiveAuth)) return;
+    if (rl && !intro?.introspection && steps.push) {
+      const again = await tryIntrospect(await getConn());
+      if (!again.introspection) {
         console.log(
-          "\nDeployed, but couldn't reach the project to introspect tables (no SUPABASE_URL/SUPABASE_SERVICE_ROLE_KEY or --url/--key available). Re-run `exposify-supabase init` with those set to configure writes, RPCs, and documentation interactively."
+          "\nDeployed, but couldn't reach the project to introspect tables (no --url/--key, no SUPABASE_URL/SUPABASE_SERVICE_ROLE_KEY, and no local stack or linked project the Supabase CLI could supply keys for). Re-run `exposify-supabase init` with those set to configure writes, RPCs, and documentation interactively."
         );
         console.log(`
-Done. Paste the function URL + ${clientCredential(broker)} into an MCP client to try it.`);
+Done. ${clientStep(effectiveAuth)}`);
+        return;
+      }
+      const local2 = await readLocalState();
+      const base = local2.functionFile?.state.config ?? desired;
+      const wizard = await runWizard(rl, again.introspection, base, local2.documented);
+      const plan2 = planInit({ ...local2, desired: wizard.config, commentsSql: wizard.commentsSql, timestamp: timestamp() });
+      await applyPlan(plan2);
+      if (plan2.changes.length === 0) {
+        console.log("\nNothing more to change.");
+      } else if (!await offerSteps(rl, { push: needsPush(plan2.changes), deploy: needsDeploy(plan2.changes) }, plan2.fileConfig, true)) {
         return;
       }
     }
-    const grants = await askWriteGrants(rl, introspection.tables);
-    const rpcCandidates = rpcCandidatesFromOpenApi(introspection.openapi);
-    const rpc = await askRpcSelection(rl, rpcCandidates);
-    const docs = await askDocumentation(rl, introspection.tables);
-    const writes = flattenWriteGrants(grants);
-    let wroteFunctionFile = false;
-    if (!functionExists) {
-      await writeFile(functionPath, buildFunctionTemplate({ writes, rpc, anonymousSignIn, broker: broker ?? void 0 }));
-      console.log(`
-Wrote ${functionPath} with your selections.`);
-      wroteFunctionFile = true;
-    } else if (writes.length > 0 || rpc.length > 0 || broker && !brokerHintShown) {
-      console.log(`
-${functionPath} already exists -- left untouched. Merge this into your aiReady() config:`);
-      console.log(buildFunctionTemplate({ writes, rpc, anonymousSignIn, broker: broker ?? void 0 }));
-    }
-    const commentsPath = await writeCommentsMigration(docs);
-    if (commentsPath) console.log(`Wrote ${commentsPath}`);
-    const needsDeploy = wroteFunctionFile || commentsPath !== null;
-    if (!needsDeploy) {
-      console.log("\nNothing new to deploy.");
-      return;
-    }
-    if (!hasSupabaseCli()) {
-      console.log("\nSupabase CLI not found on PATH.");
-      printManualCommands({ alreadyPushed: commentsPath === null, alreadyDeployed: !wroteFunctionFile, broker });
-      return;
-    }
-    const redeploy = await promptYesNo(rl, "\nApply/deploy these changes now?", true);
-    if (!redeploy) {
-      printManualCommands({ alreadyPushed: commentsPath === null, alreadyDeployed: !wroteFunctionFile, broker });
-      return;
-    }
-    const result = pushAndDeploy(broker);
-    if (!result.deployed) {
-      console.error(`
-Supabase CLI command failed: ${result.error instanceof Error ? result.error.message : result.error}`);
-      printManualCommands({ alreadyPushed: result.pushed, broker });
-      return;
-    }
-    printLicenseKeyReminder(broker);
     console.log(`
-Done. Paste the function URL + ${clientCredential(broker)} into an MCP client to try it.`);
+Done. ${clientStep(effectiveAuth)}`);
   } finally {
-    rl.close();
+    rl?.close();
   }
 }
-function printBrokerMergeHint(functionPath, broker) {
-  console.log(`
-${functionPath} already exists -- left untouched. Merge the broker wiring into your aiReady() config:`);
-  console.log(buildFunctionTemplate({ broker }));
-}
 async function cmdGenerate() {
-  const conn = resolveConnectionInfo();
+  const check = process.argv.includes("--check");
+  const { connection: conn, notes } = await resolveConnection(null);
   if (!conn) {
     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`). The service role key is used only for this one-time introspection call, matching what runtime introspection itself uses -- never written into the generated manifest."
+      `generate needs a project to introspect: --url/--key flags, SUPABASE_URL/SUPABASE_SERVICE_ROLE_KEY env vars, or a running local stack (\`supabase start\`) / linked project (\`supabase link\`) for the Supabase CLI to supply keys for${notes.length ? ` (${notes.join(" ")})` : ""}. The service role key is used only for this one-time introspection call, matching what runtime introspection itself uses -- never written into the generated manifest.`
     );
     process.exitCode = 1;
     return;
@@ -711,9 +1554,40 @@ async function cmdGenerate() {
   ]);
   const manifest = buildManifest(openapi, metaRows, (/* @__PURE__ */ new Date()).toISOString());
   const outPath = join(FUNCTION_DIR, "exposify.manifest.json");
+  const existingRaw = await readOrNull(outPath);
+  let existing = null;
+  try {
+    existing = existingRaw === null ? null : JSON.parse(existingRaw);
+  } catch {
+  }
+  if (manifestsEquivalent(manifest, existing)) {
+    console.log(`${outPath} is up to date (${manifest.tables.length} table(s)); nothing to do.`);
+    return;
+  }
+  if (check) {
+    console.log(`generate --check: ${outPath} is ${existingRaw === null ? "missing" : "out of date"}.`);
+    process.exitCode = 1;
+    return;
+  }
   await mkdir(dirname(outPath), { recursive: true });
   await writeFile(outPath, JSON.stringify(manifest, null, 2));
-  console.log(`Wrote ${outPath} (${manifest.tables.length} table(s))`);
+  console.log(`${existingRaw === null ? "Wrote" : "Updated"} ${outPath} (${manifest.tables.length} table(s))`);
+}
+async function cmdDoctor() {
+  const rl = openInteractiveReadline();
+  const { connection, notes, projectRef } = await resolveConnection(rl, { quiet: true }).finally(() => rl?.close());
+  const sections = await runDoctor({
+    readText: readOrNull,
+    listDir: listFilesOrEmpty,
+    runSupabase: supabaseRunner(),
+    connection,
+    connectionNotes: notes,
+    projectRef,
+    fetch: fetchWithTimeout,
+    token: argValue("--token")
+  });
+  console.log(formatReport(sections));
+  if (hasFailures(sections)) process.exitCode = 1;
 }
 function argValue(flag) {
   const i = process.argv.indexOf(flag);
@@ -728,18 +1602,26 @@ async function main() {
   const [, , cmd] = process.argv;
   if (cmd === "init") return cmdInit();
   if (cmd === "generate") return cmdGenerate();
+  if (cmd === "doctor") return cmdDoctor();
   console.log(
-    "Usage: exposify-supabase <init|generate> [--url <url>] [--key <service-role-key>] [--broker-url <url> --broker-project <id>]"
+    "Usage: exposify-supabase <init|generate|doctor> [--url <url>] [--key <service-role-key>] [--local|--linked] [--broker-url <url> --broker-project <id> | --oauth] [--token <token>] [--check]"
   );
-  console.log("  init      Scaffold the exposify_meta() migration + supabase/functions/mcp/index.ts.");
-  console.log("            Interactively offers to run `supabase db push` + `functions deploy`; if a");
-  console.log("            project is reachable (SUPABASE_URL/SUPABASE_SERVICE_ROLE_KEY env vars, or --url/--key),");
-  console.log("            also walks through anonymous sign-in, per-table writes, RPC exposure, and");
-  console.log("            documentation for tables/columns missing a comment. Offers to wire in the hosted");
-  console.log("            broker (or pass --broker-url/--broker-project): adds createHostedAuthResolver to the");
-  console.log("            function, sets verify_jwt = false for it in supabase/config.toml, and deploys with");
-  console.log("            --no-verify-jwt.");
-  console.log("  generate  Build exposify.manifest.json from a running local/linked project");
+  console.log("  init      Scaffold the exposify_meta() migration + supabase/functions/mcp/index.ts, then (when the");
+  console.log("            project is reachable) walk through anonymous sign-in, per-table writes, RPC exposure, and");
+  console.log("            documentation. Safe to re-run: answers default to what's already configured, only the");
+  console.log("            exposify:begin/end block of index.ts is ever rewritten, and a run that changes nothing");
+  console.log("            says so and stops. Offers the hosted broker (or --broker-url/--broker-project), or");
+  console.log("            Supabase Auth sign-in (--oauth): adds oauth: supabaseAuth(), so MCP clients open a login");
+  console.log("            on connect. Either way it sets verify_jwt = false for mcp and deploys --no-verify-jwt.");
+  console.log("            --check: change nothing, exit 1 if a run would change a file.");
+  console.log("  generate  Build exposify.manifest.json from a running local/linked project; rewritten only when");
+  console.log("            the schema changed. --check: exit 1 if it's missing or out of date.");
+  console.log("  doctor    Read-only health check: local files, config.toml, the database migration and");
+  console.log("            exposed tables, and the deployed function answering MCP (tool count). Exits 1 on any");
+  console.log("            failure. --token <user JWT | extb_...> lets it list tools past authRequired.");
+  console.log("");
+  console.log("  Reaching the project: --url/--key, else SUPABASE_URL/SUPABASE_SERVICE_ROLE_KEY, else the Supabase");
+  console.log("  CLI supplies keys for a running local stack or the linked project (--local/--linked to pick).");
   process.exitCode = cmd ? 1 : 0;
 }
 main().catch((err) => {