postgresai 0.14.0-dev.69 → 0.14.0-dev.70

package/dist/bin/postgres-ai.js

@@ -13064,7 +13064,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.14.0-dev.69",
+  version: "0.14.0-dev.70",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -15887,7 +15887,7 @@ var Result = import_lib.default.Result;
 var TypeOverrides = import_lib.default.TypeOverrides;
 var defaults = import_lib.default.defaults;
 // package.json
-var version = "0.14.0-dev.69";
+var version = "0.14.0-dev.70";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -24459,6 +24459,397 @@ async function verifyInitSetup(params) {
   }
 }
 
+// lib/supabase.ts
+var SUPABASE_API_BASE = "https://api.supabase.com";
+function isValidProjectRef(ref) {
+  return /^[a-z0-9]{10,30}$/i.test(ref);
+}
+
+class SupabaseClient {
+  config;
+  constructor(config2) {
+    if (!config2.projectRef) {
+      throw new Error("Supabase project reference is required");
+    }
+    if (!config2.accessToken) {
+      throw new Error("Supabase access token is required");
+    }
+    if (!isValidProjectRef(config2.projectRef)) {
+      throw new Error(`Invalid Supabase project reference format: "${config2.projectRef}". Expected 10-30 alphanumeric characters.`);
+    }
+    this.config = config2;
+  }
+  async query(sql, readOnly = false) {
+    const url = `${SUPABASE_API_BASE}/v1/projects/${encodeURIComponent(this.config.projectRef)}/database/query`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.config.accessToken}`
+      },
+      body: JSON.stringify({
+        query: sql,
+        read_only: readOnly
+      })
+    });
+    const body = await response.text();
+    let data;
+    try {
+      data = JSON.parse(body);
+    } catch {
+      throw this.createPgError({
+        message: `Supabase API returned non-JSON response: ${body.slice(0, 200)}`,
+        httpStatus: response.status
+      });
+    }
+    if (!response.ok) {
+      throw this.parseApiError(data, response.status);
+    }
+    if (data && typeof data === "object" && "error" in data && data.error) {
+      throw this.parseApiError(data, response.status);
+    }
+    const rows = Array.isArray(data) ? data : [];
+    return {
+      rows,
+      rowCount: rows.length
+    };
+  }
+  async testConnection() {
+    const result = await this.query("SELECT current_database() as db, version() as version", true);
+    const row = result.rows[0] ?? {};
+    return {
+      database: String(row.db ?? ""),
+      version: String(row.version ?? "")
+    };
+  }
+  async getCurrentDatabase() {
+    const result = await this.query("SELECT current_database() as db", true);
+    const row = result.rows[0] ?? {};
+    return String(row.db ?? "");
+  }
+  parseApiError(data, httpStatus) {
+    if (data && typeof data === "object" && !Array.isArray(data)) {
+      const errObj = "error" in data && data.error ? data.error : data;
+      const pgCode = this.extractPgErrorCode(errObj);
+      const message = this.extractErrorMessage(errObj);
+      const detail = this.extractField(errObj, ["details", "detail"]);
+      const hint = this.extractField(errObj, ["hint"]);
+      return this.createPgError({
+        message,
+        code: pgCode,
+        detail,
+        hint,
+        httpStatus,
+        supabaseErrorCode: typeof errObj === "object" && errObj && "code" in errObj ? String(errObj.code ?? "") : undefined
+      });
+    }
+    return this.createPgError({
+      message: `Supabase API error (HTTP ${httpStatus})`,
+      httpStatus
+    });
+  }
+  extractPgErrorCode(errObj) {
+    if (!errObj || typeof errObj !== "object")
+      return;
+    const obj = errObj;
+    if (typeof obj.code === "string") {
+      const code = obj.code;
+      if (/^\d{5}$/.test(code)) {
+        return code;
+      }
+      return this.mapSupabaseCodeToPg(code);
+    }
+    return;
+  }
+  mapSupabaseCodeToPg(code) {
+    const mapping = {
+      PGRST301: "28000",
+      PGRST302: "28P01",
+      "42501": "42501",
+      PGRST000: "42501",
+      "42601": "42601",
+      "42P01": "42P01",
+      PGRST200: "42P01",
+      "42883": "42883",
+      "08000": "08000",
+      "08003": "08003",
+      "08006": "08006",
+      "42710": "42710"
+    };
+    return mapping[code];
+  }
+  extractErrorMessage(errObj) {
+    if (!errObj || typeof errObj !== "object") {
+      return "Unknown Supabase API error";
+    }
+    const obj = errObj;
+    for (const field of ["message", "error", "msg", "description"]) {
+      if (typeof obj[field] === "string" && obj[field]) {
+        return obj[field];
+      }
+    }
+    if (obj.error && typeof obj.error === "object") {
+      return this.extractErrorMessage(obj.error);
+    }
+    return "Unknown Supabase API error";
+  }
+  extractField(errObj, fieldNames) {
+    if (!errObj || typeof errObj !== "object")
+      return;
+    const obj = errObj;
+    for (const field of fieldNames) {
+      if (typeof obj[field] === "string" && obj[field]) {
+        return obj[field];
+      }
+    }
+    return;
+  }
+  createPgError(opts) {
+    const err = new Error(opts.message);
+    if (opts.code)
+      err.code = opts.code;
+    if (opts.detail)
+      err.detail = opts.detail;
+    if (opts.hint)
+      err.hint = opts.hint;
+    if (opts.httpStatus)
+      err.httpStatus = opts.httpStatus;
+    if (opts.supabaseErrorCode)
+      err.supabaseErrorCode = opts.supabaseErrorCode;
+    return err;
+  }
+}
+function resolveSupabaseConfig(opts) {
+  const accessToken = opts.accessToken?.trim() || process.env.SUPABASE_ACCESS_TOKEN?.trim() || "";
+  const projectRef = opts.projectRef?.trim() || process.env.SUPABASE_PROJECT_REF?.trim() || "";
+  if (!accessToken) {
+    throw new Error(`Supabase access token is required.
+` + `Provide it via --supabase-access-token or SUPABASE_ACCESS_TOKEN environment variable.
+` + "Generate a token at: https://supabase.com/dashboard/account/tokens");
+  }
+  if (!projectRef) {
+    throw new Error(`Supabase project reference is required.
+` + `Provide it via --supabase-project-ref or SUPABASE_PROJECT_REF environment variable.
+` + "Find your project ref in the Supabase dashboard URL: https://supabase.com/dashboard/project/<ref>");
+  }
+  return { accessToken, projectRef };
+}
+function extractProjectRefFromUrl(dbUrl) {
+  try {
+    const url = new URL(dbUrl);
+    const host = url.hostname;
+    const match = host.match(/^(?:db\.)?([^.]+)\.supabase\.co$/i);
+    if (match && match[1]) {
+      return match[1];
+    }
+    if (host.includes("pooler.supabase.com")) {
+      const username = url.username;
+      const userMatch = username.match(/^postgres\.([a-z0-9]+)$/i);
+      if (userMatch && userMatch[1]) {
+        return userMatch[1];
+      }
+    }
+    const poolerMatch = host.match(/^([a-z0-9]+)\.pooler\.supabase\.com$/i);
+    if (poolerMatch && poolerMatch[1] && !poolerMatch[1].startsWith("aws-")) {
+      return poolerMatch[1];
+    }
+    return;
+  } catch {
+    return;
+  }
+}
+async function applyInitPlanViaSupabase(params) {
+  const applied = [];
+  const skippedOptional = [];
+  const executeStep = async (step) => {
+    const wrappedSql = `BEGIN;
+${step.sql}
+COMMIT;`;
+    await params.client.query(wrappedSql, false);
+  };
+  for (const step of params.plan.steps.filter((s) => !s.optional)) {
+    try {
+      if (params.verbose) {
+        console.log(`Executing step: ${step.name}`);
+      }
+      await executeStep(step);
+      applied.push(step.name);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      const errAny = e;
+      const wrapped = new Error(`Failed at step "${step.name}": ${msg}`);
+      const pgErrorFields = [
+        "code",
+        "detail",
+        "hint",
+        "position",
+        "internalPosition",
+        "internalQuery",
+        "where",
+        "schema",
+        "table",
+        "column",
+        "dataType",
+        "constraint",
+        "file",
+        "line",
+        "routine",
+        "httpStatus",
+        "supabaseErrorCode"
+      ];
+      for (const field of pgErrorFields) {
+        if (errAny[field] !== undefined) {
+          wrapped[field] = errAny[field];
+        }
+      }
+      if (e instanceof Error && e.stack) {
+        wrapped.stack = e.stack;
+      }
+      throw wrapped;
+    }
+  }
+  for (const step of params.plan.steps.filter((s) => s.optional)) {
+    try {
+      if (params.verbose) {
+        console.log(`Executing optional step: ${step.name}`);
+      }
+      await executeStep(step);
+      applied.push(step.name);
+    } catch {
+      skippedOptional.push(step.name);
+    }
+  }
+  return { applied, skippedOptional };
+}
+async function verifyInitSetupViaSupabase(params) {
+  const missingRequired = [];
+  const missingOptional = [];
+  const role = params.monitoringUser;
+  const db = params.database;
+  if (!isValidIdentifier(role)) {
+    throw new Error(`Invalid monitoring user name: "${role}". Must be a valid PostgreSQL identifier (letters, digits, underscores, max 63 chars, starting with letter or underscore).`);
+  }
+  const roleRes = await params.client.query(`SELECT 1 FROM pg_catalog.pg_roles WHERE rolname = '${escapeLiteral2(role)}'`, true);
+  const roleExists = roleRes.rowCount > 0;
+  if (!roleExists) {
+    missingRequired.push(`role "${role}" does not exist`);
+    return { ok: false, missingRequired, missingOptional };
+  }
+  const connectRes = await params.client.query(`SELECT has_database_privilege('${escapeLiteral2(role)}', '${escapeLiteral2(db)}', 'CONNECT') as ok`, true);
+  if (!connectRes.rows?.[0]?.ok) {
+    missingRequired.push(`CONNECT on database "${db}"`);
+  }
+  const pgMonitorRes = await params.client.query(`SELECT pg_has_role('${escapeLiteral2(role)}', 'pg_monitor', 'member') as ok`, true);
+  if (!pgMonitorRes.rows?.[0]?.ok) {
+    missingRequired.push("membership in role pg_monitor");
+  }
+  const pgIndexRes = await params.client.query(`SELECT has_table_privilege('${escapeLiteral2(role)}', 'pg_catalog.pg_index', 'SELECT') as ok`, true);
+  if (!pgIndexRes.rows?.[0]?.ok) {
+    missingRequired.push("SELECT on pg_catalog.pg_index");
+  }
+  const schemaExistsRes = await params.client.query("SELECT nspname FROM pg_namespace WHERE nspname = 'postgres_ai'", true);
+  if (schemaExistsRes.rowCount === 0) {
+    missingRequired.push("schema postgres_ai exists");
+  } else {
+    const schemaPrivRes = await params.client.query(`SELECT has_schema_privilege('${escapeLiteral2(role)}', 'postgres_ai', 'USAGE') as ok`, true);
+    if (!schemaPrivRes.rows?.[0]?.ok) {
+      missingRequired.push("USAGE on schema postgres_ai");
+    }
+  }
+  const viewExistsRes = await params.client.query("SELECT to_regclass('postgres_ai.pg_statistic') IS NOT NULL as ok", true);
+  if (!viewExistsRes.rows?.[0]?.ok) {
+    missingRequired.push("view postgres_ai.pg_statistic exists");
+  } else {
+    const viewPrivRes = await params.client.query(`SELECT has_table_privilege('${escapeLiteral2(role)}', 'postgres_ai.pg_statistic', 'SELECT') as ok`, true);
+    if (!viewPrivRes.rows?.[0]?.ok) {
+      missingRequired.push("SELECT on view postgres_ai.pg_statistic");
+    }
+  }
+  const publicSchemaExistsRes = await params.client.query("SELECT nspname FROM pg_namespace WHERE nspname = 'public'", true);
+  if (publicSchemaExistsRes.rowCount === 0) {
+    missingRequired.push("schema public exists");
+  } else {
+    const schemaUsageRes = await params.client.query(`SELECT has_schema_privilege('${escapeLiteral2(role)}', 'public', 'USAGE') as ok`, true);
+    if (!schemaUsageRes.rows?.[0]?.ok) {
+      missingRequired.push("USAGE on schema public");
+    }
+  }
+  const rolcfgRes = await params.client.query(`SELECT rolconfig FROM pg_catalog.pg_roles WHERE rolname = '${escapeLiteral2(role)}'`, true);
+  const rolconfig = rolcfgRes.rows?.[0]?.rolconfig;
+  const spLine = Array.isArray(rolconfig) ? rolconfig.find((v) => String(v).startsWith("search_path=")) : undefined;
+  if (typeof spLine !== "string" || !spLine) {
+    missingRequired.push("role search_path is set");
+  } else {
+    const sp = spLine.toLowerCase();
+    if (!sp.includes("postgres_ai") || !sp.includes("public") || !sp.includes("pg_catalog")) {
+      missingRequired.push("role search_path includes postgres_ai, public and pg_catalog");
+    }
+  }
+  const explainFnExistsRes = await params.client.query("SELECT oid FROM pg_proc WHERE proname = 'explain_generic' AND pronamespace = (SELECT oid FROM pg_namespace WHERE nspname = 'postgres_ai')", true);
+  if (explainFnExistsRes.rowCount === 0) {
+    missingRequired.push("function postgres_ai.explain_generic exists");
+  } else {
+    const explainFnRes = await params.client.query(`SELECT has_function_privilege('${escapeLiteral2(role)}', 'postgres_ai.explain_generic(text, text, text)', 'EXECUTE') as ok`, true);
+    if (!explainFnRes.rows?.[0]?.ok) {
+      missingRequired.push("EXECUTE on postgres_ai.explain_generic(text, text, text)");
+    }
+  }
+  const tableDescribeFnExistsRes = await params.client.query("SELECT oid FROM pg_proc WHERE proname = 'table_describe' AND pronamespace = (SELECT oid FROM pg_namespace WHERE nspname = 'postgres_ai')", true);
+  if (tableDescribeFnExistsRes.rowCount === 0) {
+    missingRequired.push("function postgres_ai.table_describe exists");
+  } else {
+    const tableDescribeFnRes = await params.client.query(`SELECT has_function_privilege('${escapeLiteral2(role)}', 'postgres_ai.table_describe(text)', 'EXECUTE') as ok`, true);
+    if (!tableDescribeFnRes.rows?.[0]?.ok) {
+      missingRequired.push("EXECUTE on postgres_ai.table_describe(text)");
+    }
+  }
+  if (params.includeOptionalPermissions) {
+    const extRes = await params.client.query("SELECT 1 FROM pg_extension WHERE extname = 'rds_tools'", true);
+    if (extRes.rowCount === 0) {
+      missingOptional.push("extension rds_tools");
+    } else {
+      try {
+        const fnRes = await params.client.query(`SELECT has_function_privilege('${escapeLiteral2(role)}', 'rds_tools.pg_ls_multixactdir()', 'EXECUTE') as ok`, true);
+        if (!fnRes.rows?.[0]?.ok) {
+          missingOptional.push("EXECUTE on rds_tools.pg_ls_multixactdir()");
+        }
+      } catch {
+        missingOptional.push("EXECUTE on rds_tools.pg_ls_multixactdir()");
+      }
+    }
+    const optionalFns = [
+      "pg_catalog.pg_stat_file(text)",
+      "pg_catalog.pg_stat_file(text, boolean)",
+      "pg_catalog.pg_ls_dir(text)",
+      "pg_catalog.pg_ls_dir(text, boolean, boolean)"
+    ];
+    for (const fn of optionalFns) {
+      try {
+        const fnRes = await params.client.query(`SELECT has_function_privilege('${escapeLiteral2(role)}', '${fn}', 'EXECUTE') as ok`, true);
+        if (!fnRes.rows?.[0]?.ok) {
+          missingOptional.push(`EXECUTE on ${fn}`);
+        }
+      } catch {
+        missingOptional.push(`EXECUTE on ${fn}`);
+      }
+    }
+  }
+  return {
+    ok: missingRequired.length === 0,
+    missingRequired,
+    missingOptional
+  };
+}
+function isValidIdentifier(name) {
+  return /^[a-zA-Z_][a-zA-Z0-9_]{0,62}$/.test(name);
+}
+function escapeLiteral2(value) {
+  if (value.includes("\x00")) {
+    throw new Error("SQL literal cannot contain null bytes");
+  }
+  return value.replace(/'/g, "''");
+}
+
 // lib/pkce.ts
 import * as crypto from "crypto";
 function generateRandomString(length = 64) {
@@ -26743,7 +27134,7 @@ program2.command("set-default-project <project>").description("store default pro
   writeConfig({ defaultProject: value });
   console.log(`Default project saved: ${value}`);
 });
-program2.command("prepare-db [conn]").description("prepare database for monitoring: create monitoring user, required view(s), and grant permissions (idempotent)").option("--db-url <url>", "PostgreSQL connection URL (admin) to run the setup against (deprecated; pass it as positional arg)").option("-h, --host <host>", "PostgreSQL host (psql-like)").option("-p, --port <port>", "PostgreSQL port (psql-like)").option("-U, --username <username>", "PostgreSQL user (psql-like)").option("-d, --dbname <dbname>", "PostgreSQL database name (psql-like)").option("--admin-password <password>", "Admin connection password (otherwise uses PGPASSWORD if set)").option("--monitoring-user <name>", "Monitoring role name to create/update", DEFAULT_MONITORING_USER).option("--password <password>", "Monitoring role password (overrides PGAI_MON_PASSWORD)").option("--skip-optional-permissions", "Skip optional permissions (RDS/self-managed extras)", false).option("--verify", "Verify that monitoring role/permissions are in place (no changes)", false).option("--reset-password", "Reset monitoring role password only (no other changes)", false).option("--print-sql", "Print SQL plan and exit (no changes applied)", false).option("--print-password", "Print generated monitoring password (DANGEROUS in CI logs)", false).addHelpText("after", [
+program2.command("prepare-db [conn]").description("prepare database for monitoring: create monitoring user, required view(s), and grant permissions (idempotent)").option("--db-url <url>", "PostgreSQL connection URL (admin) to run the setup against (deprecated; pass it as positional arg)").option("-h, --host <host>", "PostgreSQL host (psql-like)").option("-p, --port <port>", "PostgreSQL port (psql-like)").option("-U, --username <username>", "PostgreSQL user (psql-like)").option("-d, --dbname <dbname>", "PostgreSQL database name (psql-like)").option("--admin-password <password>", "Admin connection password (otherwise uses PGPASSWORD if set)").option("--monitoring-user <name>", "Monitoring role name to create/update", DEFAULT_MONITORING_USER).option("--password <password>", "Monitoring role password (overrides PGAI_MON_PASSWORD)").option("--skip-optional-permissions", "Skip optional permissions (RDS/self-managed extras)", false).option("--verify", "Verify that monitoring role/permissions are in place (no changes)", false).option("--reset-password", "Reset monitoring role password only (no other changes)", false).option("--print-sql", "Print SQL plan and exit (no changes applied)", false).option("--print-password", "Print generated monitoring password (DANGEROUS in CI logs)", false).option("--supabase", "Use Supabase Management API instead of direct PostgreSQL connection", false).option("--supabase-access-token <token>", "Supabase Management API access token (or SUPABASE_ACCESS_TOKEN env)").option("--supabase-project-ref <ref>", "Supabase project reference (or SUPABASE_PROJECT_REF env)").option("--json", "Output result as JSON (machine-readable)", false).addHelpText("after", [
   "",
   "Examples:",
   "  postgresai prepare-db postgresql://admin@host:5432/dbname",
@@ -26779,17 +27170,48 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
   "  postgresai prepare-db <conn> --reset-password --password '...'",
   "",
   "Offline SQL plan (no DB connection):",
-  "  postgresai prepare-db --print-sql"
+  "  postgresai prepare-db --print-sql",
+  "",
+  "Supabase mode (use Management API instead of direct connection):",
+  "  postgresai prepare-db --supabase --supabase-project-ref <ref>",
+  "  SUPABASE_ACCESS_TOKEN=... postgresai prepare-db --supabase --supabase-project-ref <ref>",
+  "",
+  "  Generate a token at: https://supabase.com/dashboard/account/tokens",
+  "  Find your project ref in: https://supabase.com/dashboard/project/<ref>"
 ].join(`
 `)).action(async (conn, opts, cmd) => {
-  if (opts.verify && opts.resetPassword) {
-    console.error("\u2717 Provide only one of --verify or --reset-password");
+  const jsonOutput = opts.json;
+  const outputJson = (data) => {
+    console.log(JSON.stringify(data, null, 2));
+  };
+  const outputError = (error2) => {
+    if (jsonOutput) {
+      outputJson({
+        success: false,
+        mode: opts.supabase ? "supabase" : "direct",
+        error: error2
+      });
+    } else {
+      console.error(`Error: prepare-db${opts.supabase ? " (Supabase)" : ""}: ${error2.message}`);
+      if (error2.step)
+        console.error(`  Step: ${error2.step}`);
+      if (error2.code)
+        console.error(`  Code: ${error2.code}`);
+      if (error2.detail)
+        console.error(`  Detail: ${error2.detail}`);
+      if (error2.hint)
+        console.error(`  Hint: ${error2.hint}`);
+      if (error2.httpStatus)
+        console.error(`  HTTP Status: ${error2.httpStatus}`);
+    }
     process.exitCode = 1;
+  };
+  if (opts.verify && opts.resetPassword) {
+    outputError({ message: "Provide only one of --verify or --reset-password" });
     return;
   }
   if (opts.verify && opts.printSql) {
-    console.error("\u2717 --verify cannot be combined with --print-sql");
-    process.exitCode = 1;
+    outputError({ message: "--verify cannot be combined with --print-sql" });
     return;
   }
   const shouldPrintSql = !!opts.printSql;
@@ -26822,6 +27244,266 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
       return;
     }
   }
+  if (opts.supabase) {
+    let supabaseConfig;
+    try {
+      let projectRef = opts.supabaseProjectRef;
+      if (!projectRef && conn) {
+        projectRef = extractProjectRefFromUrl(conn);
+      }
+      supabaseConfig = resolveSupabaseConfig({
+        accessToken: opts.supabaseAccessToken,
+        projectRef
+      });
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      outputError({ message: msg });
+      return;
+    }
+    const includeOptionalPermissions2 = !opts.skipOptionalPermissions;
+    if (!jsonOutput) {
+      console.log(`Supabase mode: project ref ${supabaseConfig.projectRef}`);
+      console.log(`Monitoring user: ${opts.monitoringUser}`);
+      console.log(`Optional permissions: ${includeOptionalPermissions2 ? "enabled" : "skipped"}`);
+    }
+    const supabaseClient = new SupabaseClient(supabaseConfig);
+    try {
+      const database = await supabaseClient.getCurrentDatabase();
+      if (!database) {
+        throw new Error("Failed to resolve current database name");
+      }
+      if (!jsonOutput) {
+        console.log(`Database: ${database}`);
+      }
+      if (opts.verify) {
+        const v = await verifyInitSetupViaSupabase({
+          client: supabaseClient,
+          database,
+          monitoringUser: opts.monitoringUser,
+          includeOptionalPermissions: includeOptionalPermissions2
+        });
+        if (v.ok) {
+          if (jsonOutput) {
+            outputJson({
+              success: true,
+              mode: "supabase",
+              action: "verify",
+              database,
+              monitoringUser: opts.monitoringUser,
+              verified: true,
+              missingOptional: v.missingOptional
+            });
+          } else {
+            console.log("\u2713 prepare-db verify: OK");
+            if (v.missingOptional.length > 0) {
+              console.log("\u26A0 Optional items missing:");
+              for (const m of v.missingOptional)
+                console.log(`- ${m}`);
+            }
+          }
+          return;
+        }
+        if (jsonOutput) {
+          outputJson({
+            success: false,
+            mode: "supabase",
+            action: "verify",
+            database,
+            monitoringUser: opts.monitoringUser,
+            verified: false,
+            missingRequired: v.missingRequired,
+            missingOptional: v.missingOptional
+          });
+        } else {
+          console.error("\u2717 prepare-db verify failed: missing required items");
+          for (const m of v.missingRequired)
+            console.error(`- ${m}`);
+          if (v.missingOptional.length > 0) {
+            console.error("Optional items missing:");
+            for (const m of v.missingOptional)
+              console.error(`- ${m}`);
+          }
+        }
+        process.exitCode = 1;
+        return;
+      }
+      let monPassword;
+      let passwordGenerated = false;
+      try {
+        const resolved = await resolveMonitoringPassword({
+          passwordFlag: opts.password,
+          passwordEnv: process.env.PGAI_MON_PASSWORD,
+          monitoringUser: opts.monitoringUser
+        });
+        monPassword = resolved.password;
+        passwordGenerated = resolved.generated;
+        if (resolved.generated) {
+          const canPrint = process.stdout.isTTY || !!opts.printPassword || jsonOutput;
+          if (canPrint) {
+            if (!jsonOutput) {
+              const shellSafe = monPassword.replace(/'/g, "'\\''");
+              console.error("");
+              console.error(`Generated monitoring password for ${opts.monitoringUser} (copy/paste):`);
+              console.error(`PGAI_MON_PASSWORD='${shellSafe}'`);
+              console.error("");
+              console.log("Store it securely (or rerun with --password / PGAI_MON_PASSWORD to set your own).");
+            }
+          } else {
+            console.error([
+              `\u2717 Monitoring password was auto-generated for ${opts.monitoringUser} but not printed in non-interactive mode.`,
+              "",
+              "Provide it explicitly:",
+              "  --password <password>   or   PGAI_MON_PASSWORD=...",
+              "",
+              "Or (NOT recommended) print the generated password:",
+              "  --print-password"
+            ].join(`
+`));
+            process.exitCode = 1;
+            return;
+          }
+        }
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        outputError({ message: msg });
+        return;
+      }
+      const plan = await buildInitPlan({
+        database,
+        monitoringUser: opts.monitoringUser,
+        monitoringPassword: monPassword,
+        includeOptionalPermissions: includeOptionalPermissions2
+      });
+      const supabaseApplicableSteps = plan.steps.filter((s) => s.name !== "03.optional_rds" && s.name !== "04.optional_self_managed");
+      const effectivePlan = opts.resetPassword ? { ...plan, steps: supabaseApplicableSteps.filter((s) => s.name === "01.role") } : { ...plan, steps: supabaseApplicableSteps };
+      if (shouldPrintSql) {
+        console.log(`
+--- SQL plan ---`);
+        for (const step of effectivePlan.steps) {
+          console.log(`
+-- ${step.name}${step.optional ? " (optional)" : ""}`);
+          console.log(redactPasswords(step.sql));
+        }
+        console.log(`
+--- end SQL plan ---
+`);
+        console.log("Note: passwords are redacted in the printed SQL output.");
+        return;
+      }
+      const { applied, skippedOptional } = await applyInitPlanViaSupabase({
+        client: supabaseClient,
+        plan: effectivePlan
+      });
+      if (jsonOutput) {
+        const result = {
+          success: true,
+          mode: "supabase",
+          action: opts.resetPassword ? "reset-password" : "apply",
+          database,
+          monitoringUser: opts.monitoringUser,
+          applied,
+          skippedOptional,
+          warnings: skippedOptional.length > 0 ? ["Some optional steps were skipped (not supported or insufficient privileges)"] : []
+        };
+        if (passwordGenerated) {
+          result.generatedPassword = monPassword;
+        }
+        outputJson(result);
+      } else {
+        console.log(opts.resetPassword ? "\u2713 prepare-db password reset completed" : "\u2713 prepare-db completed");
+        if (skippedOptional.length > 0) {
+          console.log("\u26A0 Some optional steps were skipped (not supported or insufficient privileges):");
+          for (const s of skippedOptional)
+            console.log(`- ${s}`);
+        }
+        if (process.stdout.isTTY) {
+          console.log(`Applied ${applied.length} steps`);
+        }
+      }
+    } catch (error2) {
+      const errAny = error2;
+      let message = "";
+      if (error2 instanceof Error && error2.message) {
+        message = error2.message;
+      } else if (errAny && typeof errAny === "object" && typeof errAny.message === "string" && errAny.message) {
+        message = errAny.message;
+      } else {
+        message = String(error2);
+      }
+      if (!message || message === "[object Object]") {
+        message = "Unknown error";
+      }
+      const stepMatch = typeof message === "string" ? message.match(/Failed at step "([^"]+)":/i) : null;
+      const failedStep = stepMatch?.[1];
+      const errorObj = { message };
+      if (failedStep)
+        errorObj.step = failedStep;
+      if (errAny && typeof errAny === "object") {
+        if (typeof errAny.code === "string" && errAny.code)
+          errorObj.code = errAny.code;
+        if (typeof errAny.detail === "string" && errAny.detail)
+          errorObj.detail = errAny.detail;
+        if (typeof errAny.hint === "string" && errAny.hint)
+          errorObj.hint = errAny.hint;
+        if (typeof errAny.httpStatus === "number")
+          errorObj.httpStatus = errAny.httpStatus;
+      }
+      if (jsonOutput) {
+        outputJson({
+          success: false,
+          mode: "supabase",
+          error: errorObj
+        });
+        process.exitCode = 1;
+      } else {
+        console.error(`Error: prepare-db (Supabase): ${message}`);
+        if (failedStep) {
+          console.error(`  Step: ${failedStep}`);
+        }
+        if (errAny && typeof errAny === "object") {
+          if (typeof errAny.code === "string" && errAny.code) {
+            console.error(`  Code: ${errAny.code}`);
+          }
+          if (typeof errAny.detail === "string" && errAny.detail) {
+            console.error(`  Detail: ${errAny.detail}`);
+          }
+          if (typeof errAny.hint === "string" && errAny.hint) {
+            console.error(`  Hint: ${errAny.hint}`);
+          }
+          if (typeof errAny.httpStatus === "number") {
+            console.error(`  HTTP Status: ${errAny.httpStatus}`);
+          }
+        }
+        if (errAny && typeof errAny === "object" && typeof errAny.code === "string") {
+          if (errAny.code === "42501") {
+            if (failedStep === "01.role") {
+              console.error("  Context: role creation/update requires CREATEROLE or superuser");
+            } else if (failedStep === "02.permissions") {
+              console.error("  Context: grants/view/search_path require sufficient GRANT/DDL privileges");
+            }
+            console.error("  Fix: ensure your Supabase access token has sufficient permissions");
+            console.error("  Tip: run with --print-sql to review the exact SQL plan");
+          }
+        }
+        if (errAny && typeof errAny === "object" && typeof errAny.httpStatus === "number") {
+          if (errAny.httpStatus === 401) {
+            console.error("  Hint: invalid or expired access token; generate a new one at https://supabase.com/dashboard/account/tokens");
+          }
+          if (errAny.httpStatus === 403) {
+            console.error("  Hint: access denied; check your token permissions and project access");
+          }
+          if (errAny.httpStatus === 404) {
+            console.error("  Hint: project not found; verify the project reference is correct");
+          }
+          if (errAny.httpStatus === 429) {
+            console.error("  Hint: rate limited; wait a moment and try again");
+          }
+        }
+        process.exitCode = 1;
+      }
+    }
+    return;
+  }
   let adminConn;
   try {
     adminConn = resolveAdminConnection({
@@ -26836,18 +27518,24 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
     });
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
-    console.error(`Error: prepare-db: ${msg}`);
-    if (typeof msg === "string" && msg.startsWith("Connection is required.")) {
-      console.error("");
-      cmd.outputHelp({ error: true });
+    if (jsonOutput) {
+      outputError({ message: msg });
+    } else {
+      console.error(`Error: prepare-db: ${msg}`);
+      if (typeof msg === "string" && msg.startsWith("Connection is required.")) {
+        console.error("");
+        cmd.outputHelp({ error: true });
+      }
+      process.exitCode = 1;
     }
-    process.exitCode = 1;
     return;
   }
   const includeOptionalPermissions = !opts.skipOptionalPermissions;
-  console.log(`Connecting to: ${adminConn.display}`);
-  console.log(`Monitoring user: ${opts.monitoringUser}`);
-  console.log(`Optional permissions: ${includeOptionalPermissions ? "enabled" : "skipped"}`);
+  if (!jsonOutput) {
+    console.log(`Connecting to: ${adminConn.display}`);
+    console.log(`Monitoring user: ${opts.monitoringUser}`);
+    console.log(`Optional permissions: ${includeOptionalPermissions ? "enabled" : "skipped"}`);
+  }
   let client;
   try {
     const connResult = await connectWithSslFallback(Client, adminConn);
@@ -26865,26 +27553,52 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
         includeOptionalPermissions
       });
       if (v.ok) {
-        console.log("\u2713 prepare-db verify: OK");
-        if (v.missingOptional.length > 0) {
-          console.log("\u26A0 Optional items missing:");
-          for (const m of v.missingOptional)
-            console.log(`- ${m}`);
+        if (jsonOutput) {
+          outputJson({
+            success: true,
+            mode: "direct",
+            action: "verify",
+            database,
+            monitoringUser: opts.monitoringUser,
+            verified: true,
+            missingOptional: v.missingOptional
+          });
+        } else {
+          console.log("\u2713 prepare-db verify: OK");
+          if (v.missingOptional.length > 0) {
+            console.log("\u26A0 Optional items missing:");
+            for (const m of v.missingOptional)
+              console.log(`- ${m}`);
+          }
         }
         return;
       }
-      console.error("\u2717 prepare-db verify failed: missing required items");
-      for (const m of v.missingRequired)
-        console.error(`- ${m}`);
-      if (v.missingOptional.length > 0) {
-        console.error("Optional items missing:");
-        for (const m of v.missingOptional)
+      if (jsonOutput) {
+        outputJson({
+          success: false,
+          mode: "direct",
+          action: "verify",
+          database,
+          monitoringUser: opts.monitoringUser,
+          verified: false,
+          missingRequired: v.missingRequired,
+          missingOptional: v.missingOptional
+        });
+      } else {
+        console.error("\u2717 prepare-db verify failed: missing required items");
+        for (const m of v.missingRequired)
           console.error(`- ${m}`);
+        if (v.missingOptional.length > 0) {
+          console.error("Optional items missing:");
+          for (const m of v.missingOptional)
+            console.error(`- ${m}`);
+        }
       }
       process.exitCode = 1;
       return;
     }
     let monPassword;
+    let passwordGenerated = false;
     try {
       const resolved = await resolveMonitoringPassword({
         passwordFlag: opts.password,
@@ -26892,15 +27606,18 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
         monitoringUser: opts.monitoringUser
       });
       monPassword = resolved.password;
+      passwordGenerated = resolved.generated;
       if (resolved.generated) {
-        const canPrint = process.stdout.isTTY || !!opts.printPassword;
+        const canPrint = process.stdout.isTTY || !!opts.printPassword || jsonOutput;
         if (canPrint) {
-          const shellSafe = monPassword.replace(/'/g, "'\\''");
-          console.error("");
-          console.error(`Generated monitoring password for ${opts.monitoringUser} (copy/paste):`);
-          console.error(`PGAI_MON_PASSWORD='${shellSafe}'`);
-          console.error("");
-          console.log("Store it securely (or rerun with --password / PGAI_MON_PASSWORD to set your own).");
+          if (!jsonOutput) {
+            const shellSafe = monPassword.replace(/'/g, "'\\''");
+            console.error("");
+            console.error(`Generated monitoring password for ${opts.monitoringUser} (copy/paste):`);
+            console.error(`PGAI_MON_PASSWORD='${shellSafe}'`);
+            console.error("");
+            console.log("Store it securely (or rerun with --password / PGAI_MON_PASSWORD to set your own).");
+          }
         } else {
           console.error([
             `\u2717 Monitoring password was auto-generated for ${opts.monitoringUser} but not printed in non-interactive mode.`,
@@ -26918,8 +27635,7 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
       }
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
-      console.error(`\u2717 ${msg}`);
-      process.exitCode = 1;
+      outputError({ message: msg });
       return;
     }
     const plan = await buildInitPlan({
@@ -26944,14 +27660,31 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
       return;
     }
     const { applied, skippedOptional } = await applyInitPlan({ client, plan: effectivePlan });
-    console.log(opts.resetPassword ? "\u2713 prepare-db password reset completed" : "\u2713 prepare-db completed");
-    if (skippedOptional.length > 0) {
-      console.log("\u26A0 Some optional steps were skipped (not supported or insufficient privileges):");
-      for (const s of skippedOptional)
-        console.log(`- ${s}`);
-    }
-    if (process.stdout.isTTY) {
-      console.log(`Applied ${applied.length} steps`);
+    if (jsonOutput) {
+      const result = {
+        success: true,
+        mode: "direct",
+        action: opts.resetPassword ? "reset-password" : "apply",
+        database,
+        monitoringUser: opts.monitoringUser,
+        applied,
+        skippedOptional,
+        warnings: skippedOptional.length > 0 ? ["Some optional steps were skipped (not supported or insufficient privileges)"] : []
+      };
+      if (passwordGenerated) {
+        result.generatedPassword = monPassword;
+      }
+      outputJson(result);
+    } else {
+      console.log(opts.resetPassword ? "\u2713 prepare-db password reset completed" : "\u2713 prepare-db completed");
+      if (skippedOptional.length > 0) {
+        console.log("\u26A0 Some optional steps were skipped (not supported or insufficient privileges):");
+        for (const s of skippedOptional)
+          console.log(`- ${s}`);
+      }
+      if (process.stdout.isTTY) {
+        console.log(`Applied ${applied.length} steps`);
+      }
     }
   } catch (error2) {
     const errAny = error2;
@@ -26966,45 +27699,65 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
     if (!message || message === "[object Object]") {
       message = "Unknown error";
     }
-    console.error(`Error: prepare-db: ${message}`);
     const stepMatch = typeof message === "string" ? message.match(/Failed at step "([^"]+)":/i) : null;
     const failedStep = stepMatch?.[1];
-    if (failedStep) {
-      console.error(`  Step: ${failedStep}`);
-    }
+    const errorObj = { message };
+    if (failedStep)
+      errorObj.step = failedStep;
     if (errAny && typeof errAny === "object") {
-      if (typeof errAny.code === "string" && errAny.code) {
-        console.error(`  Code: ${errAny.code}`);
-      }
-      if (typeof errAny.detail === "string" && errAny.detail) {
-        console.error(`  Detail: ${errAny.detail}`);
-      }
-      if (typeof errAny.hint === "string" && errAny.hint) {
-        console.error(`  Hint: ${errAny.hint}`);
+      if (typeof errAny.code === "string" && errAny.code)
+        errorObj.code = errAny.code;
+      if (typeof errAny.detail === "string" && errAny.detail)
+        errorObj.detail = errAny.detail;
+      if (typeof errAny.hint === "string" && errAny.hint)
+        errorObj.hint = errAny.hint;
+    }
+    if (jsonOutput) {
+      outputJson({
+        success: false,
+        mode: "direct",
+        error: errorObj
+      });
+      process.exitCode = 1;
+    } else {
+      console.error(`Error: prepare-db: ${message}`);
+      if (failedStep) {
+        console.error(`  Step: ${failedStep}`);
       }
-    }
-    if (errAny && typeof errAny === "object" && typeof errAny.code === "string") {
-      if (errAny.code === "42501") {
-        if (failedStep === "01.role") {
-          console.error("  Context: role creation/update requires CREATEROLE or superuser");
-        } else if (failedStep === "02.permissions") {
-          console.error("  Context: grants/view/search_path require sufficient GRANT/DDL privileges");
+      if (errAny && typeof errAny === "object") {
+        if (typeof errAny.code === "string" && errAny.code) {
+          console.error(`  Code: ${errAny.code}`);
+        }
+        if (typeof errAny.detail === "string" && errAny.detail) {
+          console.error(`  Detail: ${errAny.detail}`);
+        }
+        if (typeof errAny.hint === "string" && errAny.hint) {
+          console.error(`  Hint: ${errAny.hint}`);
         }
-        console.error("  Fix: connect as a superuser (or a role with CREATEROLE and sufficient GRANT privileges)");
-        console.error("  Fix: on managed Postgres, use the provider's admin/master user");
-        console.error("  Tip: run with --print-sql to review the exact SQL plan");
-      }
-      if (errAny.code === "ECONNREFUSED") {
-        console.error("  Hint: check host/port and ensure Postgres is reachable from this machine");
-      }
-      if (errAny.code === "ENOTFOUND") {
-        console.error("  Hint: DNS resolution failed; double-check the host name");
       }
-      if (errAny.code === "ETIMEDOUT") {
-        console.error("  Hint: connection timed out; check network/firewall rules");
+      if (errAny && typeof errAny === "object" && typeof errAny.code === "string") {
+        if (errAny.code === "42501") {
+          if (failedStep === "01.role") {
+            console.error("  Context: role creation/update requires CREATEROLE or superuser");
+          } else if (failedStep === "02.permissions") {
+            console.error("  Context: grants/view/search_path require sufficient GRANT/DDL privileges");
+          }
+          console.error("  Fix: connect as a superuser (or a role with CREATEROLE and sufficient GRANT privileges)");
+          console.error("  Fix: on managed Postgres, use the provider's admin/master user");
+          console.error("  Tip: run with --print-sql to review the exact SQL plan");
+        }
+        if (errAny.code === "ECONNREFUSED") {
+          console.error("  Hint: check host/port and ensure Postgres is reachable from this machine");
+        }
+        if (errAny.code === "ENOTFOUND") {
+          console.error("  Hint: DNS resolution failed; double-check the host name");
+        }
+        if (errAny.code === "ETIMEDOUT") {
+          console.error("  Hint: connection timed out; check network/firewall rules");
+        }
       }
+      process.exitCode = 1;
     }
-    process.exitCode = 1;
   } finally {
     if (client) {
       try {