postgresai 0.16.0-dev.1 → 0.16.0-dev.10

package/lib/util.ts

@@ -28,45 +28,111 @@ function isHtmlContent(text: string): boolean {
  */
 const AUTH_REMEDIATION_HINT = "Run 'postgresai auth' to (re)authenticate, or set/update PGAI_API_KEY.";
 
+/**
+ * Standard HTTP reason phrases we should NOT treat as a server-authored
+ * message: when the reason phrase equals the stock text for the status, it
+ * carries no extra information, so we prefer the friendlier generic label.
+ */
+const STANDARD_REASON_PHRASES: Record<number, string> = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  403: "Forbidden",
+  404: "Not Found",
+  408: "Request Timeout",
+  409: "Conflict",
+  413: "Payload Too Large",
+  429: "Too Many Requests",
+  500: "Internal Server Error",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+  504: "Gateway Timeout",
+};
+
 /**
  * Format an HTTP error response into a clean, developer-friendly message.
  * Handles HTML error pages (e.g., from Cloudflare) by showing just the status code and message.
  * For 401 responses, appends a remediation hint pointing at `postgresai auth`.
+ *
+ * The platform's PostgREST layer uses the `PTxyz` custom-status convention:
+ * a raised `PT403`/`PT404`/… maps to the HTTP status and delivers the RPC's
+ * user-facing message in the HTTP **reason phrase** (`response.statusText`),
+ * NOT the JSON body — the body carries only `hint`/`details` (no `message`).
+ * So callers pass `statusText` and it is preferred over the built-in generic
+ * label. Headline precedence: JSON body `message` → custom reason phrase →
+ * generic label; the JSON `details` (plural, PostgREST's spelling) is shown as
+ * a supplementary line.
  */
-export function formatHttpError(operation: string, status: number, responseBody?: string): string {
-  const statusMessage = HTTP_STATUS_MESSAGES[status] || "Request failed";
-  let errMsg = `${operation}: HTTP ${status} - ${statusMessage}`;
+export function formatHttpError(
+  operation: string,
+  status: number,
+  responseBody?: string,
+  statusText?: string
+): string {
+  const generic = HTTP_STATUS_MESSAGES[status] || "Request failed";
   const remediation = status === 401 ? `\n${AUTH_REMEDIATION_HINT}` : "";
 
-  if (responseBody) {
-    // If it's HTML (like Cloudflare error pages), don't dump the raw HTML
-    if (isHtmlContent(responseBody)) {
-      // Just use the status message, don't append HTML
-      return errMsg + remediation;
-    }
+  let bodyMessage: string | undefined;
+  let bodyDetails: string | undefined;
 
-    // Try to parse as JSON for structured error info
+  if (responseBody && !isHtmlContent(responseBody)) {
+    // If it's HTML (like Cloudflare error pages), we fall through with no
+    // parsed fields and never dump the raw HTML.
     try {
       const errObj = JSON.parse(responseBody);
-      // Extract common error message fields
-      const message = errObj.message || errObj.error || errObj.detail;
-      if (message && typeof message === "string") {
-        errMsg += `\n${message}`;
-      } else {
-        errMsg += `\n${JSON.stringify(errObj, null, 2)}`;
+      const message = errObj.message ?? errObj.error;
+      if (typeof message === "string" && message.trim().length > 0) {
+        bodyMessage = message.trim();
+      }
+      // PostgREST spells it `details` (plural); accept `detail` too.
+      const details = errObj.details ?? errObj.detail;
+      if (typeof details === "string" && details.trim().length > 0) {
+        bodyDetails = details.trim();
       }
     } catch {
-      // Plain text error - append it if it's short and useful
+      // Plain text error - treat it as the details line if short and useful.
       const trimmed = responseBody.trim();
       if (trimmed.length > 0 && trimmed.length < 500) {
-        errMsg += `\n${trimmed}`;
+        bodyDetails = trimmed;
       }
     }
   }
 
+  // A custom reason phrase (PTxyz message) is meaningful only when it differs
+  // from the stock HTTP reason phrase for this status.
+  const trimmedReason = statusText?.trim();
+  const reasonPhrase =
+    trimmedReason &&
+    trimmedReason !== STANDARD_REASON_PHRASES[status] &&
+    trimmedReason !== generic
+      ? trimmedReason
+      : undefined;
+
+  const headline = bodyMessage ?? reasonPhrase ?? generic;
+  let errMsg = `${operation}: HTTP ${status} - ${headline}`;
+  if (bodyDetails && bodyDetails !== headline) {
+    errMsg += `\n${bodyDetails}`;
+  }
+
   return errMsg + remediation;
 }
 
+/**
+ * Turn a low-level `fetch` failure into an actionable message. Node's fetch
+ * (undici) throws a `TypeError('fetch failed')` and stashes the real cause
+ * (`ECONNREFUSED`, DNS failure, `bad port`, TLS error, …) in `err.cause` — the
+ * opaque top-level message on its own tells the user nothing. This surfaces the
+ * cause and the URL that could not be reached, e.g.
+ *   "Failed to list projects: could not reach http://127.0.0.1:1 (ECONNREFUSED)"
+ */
+export function describeFetchError(operation: string, url: string, err: unknown): string {
+  const cause = (err as { cause?: { code?: string; message?: string } } | null | undefined)?.cause;
+  const detail =
+    cause?.code ||
+    cause?.message ||
+    (err instanceof Error && err.message ? err.message : String(err));
+  return `${operation}: could not reach ${url} (${detail})`;
+}
+
 export function maskSecret(secret: string): string {
   if (!secret) return "";
   if (secret.length <= 8) return "****";
@@ -74,6 +140,47 @@ export function maskSecret(secret: string): string {
   return `${secret.slice(0, Math.min(12, secret.length - 8))}${"*".repeat(Math.max(4, secret.length - 16))}${secret.slice(-4)}`;
 }
 
+/** Keys whose values are credentials: any `password`-containing key (db.password,
+ * db_password, dbPassword, …) and the DBLab connection string (`connStr`, which
+ * embeds the password). Matched case-insensitively at any depth. */
+const SENSITIVE_LOG_KEY = /password|connstr/i;
+
+/**
+ * Redact known credential fields from a serialized JSON payload before it is
+ * written to a debug log — the body-side counterpart of the `maskSecret`
+ * masking the `access-token` header already gets. Debug logging is reachable
+ * by MCP callers (`debug: true` is a caller-controlled tool argument), and
+ * DBLab bodies carry live credentials: `--db-password` rides in the clone
+ * create request (`data.db.password`), and clone create/status replies return
+ * the clone's `db.password` / `db.connStr`.
+ *
+ * A fixed placeholder is used instead of `maskSecret` because short passwords
+ * would leak most of their characters through partial masking. Non-JSON input
+ * is returned unchanged.
+ */
+export function redactSecretsForLog(text: string): string {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return text;
+  }
+  const walk = (node: unknown): unknown => {
+    if (Array.isArray(node)) {
+      return node.map(walk);
+    }
+    if (node && typeof node === "object") {
+      const out: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(node as Record<string, unknown>)) {
+        out[key] = SENSITIVE_LOG_KEY.test(key) && value != null ? "[REDACTED]" : walk(value);
+      }
+      return out;
+    }
+    return node;
+  };
+  return JSON.stringify(walk(parsed));
+}
+
 
 export interface RootOptsLike {
   apiBaseUrl?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresai",
-  "version": "0.16.0-dev.1",
+  "version": "0.16.0-dev.10",
   "description": "postgres_ai CLI",
   "license": "Apache-2.0",
   "private": false,

package/sql/06.helpers.sql

@@ -2,126 +2,6 @@
 -- These functions use SECURITY DEFINER to allow the monitoring user to perform
 -- operations they don't have direct permissions for.
 
-/*
- * explain_generic
- *
- * Function to get generic explain plans with optional HypoPG index testing.
- * Requires: PostgreSQL 16+ (for generic_plan option), HypoPG extension (optional).
- *
- * Security notes:
- * - EXPLAIN without ANALYZE is read-only (plans but doesn't execute the query)
- * - PostgreSQL's EXPLAIN only accepts a single statement (primary protection)
- * - Input validation uses a simple heuristic to detect multiple statements
- *   (Note: may reject valid queries containing semicolons in string literals)
- *
- * Usage examples:
- *   -- Basic generic plan
- *   select postgres_ai.explain_generic('select * from users where id = $1');
- *
- *   -- JSON format
- *   select postgres_ai.explain_generic('select * from users where id = $1', 'json');
- *
- *   -- Test a hypothetical index
- *   select postgres_ai.explain_generic(
- *     'select * from users where email = $1',
- *     'text',
- *     'create index on users (email)'
- *   );
- */
-create or replace function postgres_ai.explain_generic(
-  in query text,
-  in format text default 'text',
-  in hypopg_index text default null,
-  out result text
-)
-language plpgsql
-security definer
-set search_path = pg_catalog, public
-as $$
-declare
-  v_line record;
-  v_lines text[] := '{}';
-  v_explain_query text;
-  v_hypo_result record;
-  v_version int;
-  v_hypopg_available boolean;
-  v_clean_query text;
-begin
-  -- Check PostgreSQL version (generic_plan requires 16+)
-  select current_setting('server_version_num')::int into v_version;
-
-  if v_version < 160000 then
-    raise exception 'generic_plan requires PostgreSQL 16+, current version: %',
-      current_setting('server_version');
-  end if;
-
-  -- Input validation: reject empty queries
-  if query is null or trim(query) = '' then
-    raise exception 'query cannot be empty';
-  end if;
-
-  -- Input validation: detect multiple statements (defense-in-depth)
-  -- Note: This is a simple heuristic - EXPLAIN itself only accepts single statements
-  -- Limitation: Queries with semicolons inside string literals will be rejected
-  v_clean_query := trim(query);
-  if v_clean_query like '%;%' then
-    -- Strip trailing semicolon if present (common user convenience)
-    v_clean_query := regexp_replace(v_clean_query, ';\s*$', '');
-    -- If there's still a semicolon, reject (likely multiple statements or semicolon in string)
-    if v_clean_query like '%;%' then
-      raise exception 'query contains semicolon (multiple statements not allowed; note: semicolons in string literals are also not supported)';
-    end if;
-  end if;
-
-  -- Check if HypoPG extension is available
-  if hypopg_index is not null then
-    select exists(
-      select 1 from pg_extension where extname = 'hypopg'
-    ) into v_hypopg_available;
-
-    if not v_hypopg_available then
-      raise exception 'HypoPG extension is required for hypothetical index testing but is not installed';
-    end if;
-
-    -- Create hypothetical index
-    select * into v_hypo_result from hypopg_create_index(hypopg_index);
-    raise notice 'Created hypothetical index: % (oid: %)',
-      v_hypo_result.indexname, v_hypo_result.indexrelid;
-  end if;
-
-  -- Build and execute EXPLAIN query
-  -- Note: EXPLAIN is read-only (plans but doesn't execute), making this safe
-  begin
-    if lower(format) = 'json' then
-      execute 'explain (verbose, settings, generic_plan, format json) ' || v_clean_query
-        into result;
-    else
-      for v_line in execute 'explain (verbose, settings, generic_plan) ' || v_clean_query loop
-        v_lines := array_append(v_lines, v_line."QUERY PLAN");
-      end loop;
-      result := array_to_string(v_lines, e'\n');
-    end if;
-  exception when others then
-    -- Clean up hypothetical index before re-raising
-    if hypopg_index is not null then
-      perform hypopg_reset();
-    end if;
-    raise;
-  end;
-
-  -- Clean up hypothetical index
-  if hypopg_index is not null then
-    perform hypopg_reset();
-  end if;
-end;
-$$;
-
-comment on function postgres_ai.explain_generic(text, text, text) is
-  'Returns generic EXPLAIN plan with optional HypoPG index testing (requires PG16+)';
-
--- Grant execute to the monitoring user
-grant execute on function postgres_ai.explain_generic(text, text, text) to {{ROLE_IDENT}};
-
 /*
  * table_describe
  *
@@ -435,5 +315,3 @@ comment on function postgres_ai.table_describe(text) is
   'Returns comprehensive table information in compact text format for LLM analysis';
 
 grant execute on function postgres_ai.table_describe(text) to {{ROLE_IDENT}};
-
-