postgresai 0.16.0-dev.10 → 0.16.0-dev.11

package/lib/util.ts

@@ -58,9 +58,14 @@ const STANDARD_REASON_PHRASES: Record<number, string> = {
  * 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.
+ * label. Behind an h2/h3 proxy the reason phrase is dropped entirely
+ * (`statusText` is empty), so the JSON body's `code`, `details`, and `hint`
+ * are all we get — they must be surfaced too (CLI half of
+ * https://gitlab.com/postgres-ai/platform-all/-/issues/537).
+ * Headline precedence: JSON body `message` → custom reason phrase → generic
+ * label, suffixed with the JSON `code` (e.g. `PT403`) when present; the JSON
+ * `details` (plural, PostgREST's spelling) is shown as a supplementary line,
+ * and the JSON `hint` (the remediation) as a trailing `Hint:` line.
  */
 export function formatHttpError(
   operation: string,
@@ -73,6 +78,8 @@ export function formatHttpError(
 
   let bodyMessage: string | undefined;
   let bodyDetails: string | undefined;
+  let bodyCode: string | undefined;
+  let bodyHint: string | undefined;
 
   if (responseBody && !isHtmlContent(responseBody)) {
     // If it's HTML (like Cloudflare error pages), we fall through with no
@@ -81,18 +88,37 @@ export function formatHttpError(
       const errObj = JSON.parse(responseBody);
       const message = errObj.message ?? errObj.error;
       if (typeof message === "string" && message.trim().length > 0) {
-        bodyMessage = message.trim();
+        bodyMessage = redactTextSecrets(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();
+        bodyDetails = redactTextSecrets(details.trim());
+      }
+      if (typeof errObj.code === "string" && errObj.code.trim().length > 0) {
+        bodyCode = errObj.code.trim();
+      }
+      if (typeof errObj.hint === "string" && errObj.hint.trim().length > 0) {
+        bodyHint = redactTextSecrets(errObj.hint.trim());
+      }
+      if (
+        bodyMessage === undefined &&
+        bodyDetails === undefined &&
+        bodyCode === undefined &&
+        bodyHint === undefined
+      ) {
+        // A JSON body with none of the known fields (message/error/details/
+        // detail/code/hint) still carries the only diagnostic there is —
+        // surface it (redacted, compact) instead of silently dropping it.
+        bodyDetails = redactSecretsForLog(JSON.stringify(errObj));
       }
     } catch {
       // Plain text error - treat it as the details line if short and useful.
+      // Scrubbed: raw error bodies can echo credentials (e.g. a connStr) and
+      // this string ends up in thrown Errors / MCP isError responses.
       const trimmed = responseBody.trim();
       if (trimmed.length > 0 && trimmed.length < 500) {
-        bodyDetails = trimmed;
+        bodyDetails = redactTextSecrets(trimmed);
       }
     }
   }
@@ -106,12 +132,17 @@ export function formatHttpError(
     trimmedReason !== generic
       ? trimmedReason
       : undefined;
+  const safeReasonPhrase = reasonPhrase ? redactTextSecrets(reasonPhrase) : undefined;
 
-  const headline = bodyMessage ?? reasonPhrase ?? generic;
-  let errMsg = `${operation}: HTTP ${status} - ${headline}`;
+  const headline = bodyMessage ?? safeReasonPhrase ?? generic;
+  const codeSuffix = bodyCode && !headline.includes(bodyCode) ? ` (${bodyCode})` : "";
+  let errMsg = `${operation}: HTTP ${status} - ${headline}${codeSuffix}`;
   if (bodyDetails && bodyDetails !== headline) {
     errMsg += `\n${bodyDetails}`;
   }
+  if (bodyHint) {
+    errMsg += `\nHint: ${bodyHint}`;
+  }
 
   return errMsg + remediation;
 }
@@ -133,6 +164,49 @@ export function describeFetchError(operation: string, url: string, err: unknown)
   return `${operation}: could not reach ${url} (${detail})`;
 }
 
+/**
+ * An HTTP error response with the status attached, so callers can classify
+ * retryability without string-matching the formatted message.
+ */
+export class HttpStatusError extends Error {
+  readonly status: number;
+  constructor(message: string, status: number) {
+    super(message);
+    this.name = "HttpStatusError";
+    this.status = status;
+  }
+}
+
+/** Transient statuses worth retrying/resuming on: server errors and rate limits. */
+export function isRetryableHttpStatus(status: number): boolean {
+  return status >= 500 || status === 429;
+}
+
+/** Hard upper bound for a single platform request, even outside Joe polling. */
+export const DEFAULT_HTTP_REQUEST_TIMEOUT_MS = 25_000;
+
+export class HttpRequestTimeoutError extends Error {
+  constructor(operation: string, timeoutMs: number) {
+    super(`${operation}: request timed out after ${timeoutMs}ms`);
+    this.name = "HttpRequestTimeoutError";
+  }
+}
+
+/** Return a finite AbortSignal timeout acceptable to both Node and Bun fetch. */
+export function requestTimeoutSignal(timeoutMs?: number): { signal: AbortSignal; timeoutMs: number } {
+  const requested =
+    typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0
+      ? timeoutMs
+      : DEFAULT_HTTP_REQUEST_TIMEOUT_MS;
+  const bounded = Math.max(1, Math.min(DEFAULT_HTTP_REQUEST_TIMEOUT_MS, Math.floor(requested)));
+  return { signal: AbortSignal.timeout(bounded), timeoutMs: bounded };
+}
+
+export function isFetchTimeout(err: unknown): boolean {
+  const name = (err as { name?: unknown } | null)?.name;
+  return name === "AbortError" || name === "TimeoutError";
+}
+
 export function maskSecret(secret: string): string {
   if (!secret) return "";
   if (secret.length <= 8) return "****";
@@ -140,45 +214,87 @@ 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;
+/**
+ * Credential-bearing field names. Match complete normalized names rather than
+ * substrings: MCP results can contain ordinary SQL columns such as `author_id`,
+ * `token_type`, `tokens`, and `credited_at`, and corrupting those values is worse
+ * than leaving an unfamiliar key untouched. CamelCase is normalized so DBLab's
+ * `connStr` and `dbPassword` remain covered.
+ */
+function isSensitiveLogKey(key: string): boolean {
+  const normalized = key
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/[-\s]+/g, "_")
+    .toLowerCase();
+  return /^(?:password|passwd|db_(?:pass|password)|conn_?str|secret|token|api_key|private_key|access_key|access_token|refresh_token|auth|auth_key|auth_token|authorization|credentials?|dsn)$/.test(normalized);
+}
+
+/**
+ * Return a deep copy with DBLab credential fields removed.
+ *
+ * Best-effort hygiene only, NOT a security barrier: redaction is key-name
+ * based, so secret VALUES under non-matching keys (e.g.
+ * `select rolpassword as x from pg_authid`) pass through untouched. The
+ * joe:exec scope and the org execution policy are the actual controls.
+ */
+export function redactSecrets(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(redactSecrets);
+  }
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+      out[key] = isSensitiveLogKey(key) && child != null
+        ? "[REDACTED]"
+        : redactSecrets(child);
+    }
+    return out;
+  }
+  return value;
+}
 
 /**
  * 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
+ * DBLab bodies carry live credentials: the clone 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.
+ * cannot be redacted by key name, so it falls back to the pattern-based
+ * `redactTextSecrets` scrub — error paths (parse failures, plain-text error
+ * bodies) embed raw response text in thrown Errors that reach MCP `isError`
+ * responses and CLI stderr, and must not bypass redaction.
  */
 export function redactSecretsForLog(text: string): string {
   let parsed: unknown;
   try {
     parsed = JSON.parse(text);
   } catch {
-    return text;
+    return redactTextSecrets(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));
+  return JSON.stringify(redactSecrets(parsed));
+}
+
+/** URL userinfo credentials: `scheme://user:password@host` → password redacted. */
+const TEXT_URL_USERINFO = /(\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+):[^\s/@]+@/gi;
+
+/** `key=value` / `key: value` / `"key": "value"` pairs for credential-named keys. */
+const TEXT_SENSITIVE_PAIR =
+  /((?:password|passwd|db[-_]?pass|connstr|secret|token|api[-_]?key|private[-_]?key|access[-_]?key|cred(?:ential)?s?|dsn)["']?\s*[:=]\s*)("[^"]*"|'[^']*'|[^\s,;&]+)/gi;
+
+/**
+ * Best-effort scrub of credential-looking patterns in plain (non-JSON) text.
+ * Used for raw response text that ends up in thrown error messages, where the
+ * key-based `redactSecrets` cannot apply. Hygiene only — not an egress control.
+ */
+export function redactTextSecrets(text: string): string {
+  return text
+    .replace(TEXT_URL_USERINFO, "$1:[REDACTED]@")
+    .replace(TEXT_SENSITIVE_PAIR, "$1[REDACTED]");
 }
 
 

package/package.json

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

package/test/auth.test.ts

@@ -1,5 +1,7 @@
 import { describe, test, expect } from "bun:test";
-import { resolve } from "path";
+import { mkdtempSync, readFileSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join, resolve } from "path";
 
 import * as util from "../lib/util";
 import * as pkce from "../lib/pkce";
@@ -212,6 +214,33 @@ describe("Auth callback server", () => {
 });
 
 describe("CLI auth commands", () => {
+  test("cli: login --help shows all options", () => {
+    const r = runCli(["login", "--help"]);
+    expect(r.status).toBe(0);
+    expect(r.stdout).toMatch(/--set-key/);
+    expect(r.stdout).toMatch(/--debug/);
+  });
+
+  test("cli: login --set-key aliases auth login", () => {
+    const home = mkdtempSync(join(tmpdir(), "postgresai-login-"));
+
+    try {
+      const r = runCli(["login", "--set-key", "test-token"], {
+        HOME: home,
+        XDG_CONFIG_HOME: join(home, ".config"),
+      });
+      expect(r.status).toBe(0);
+      expect(r.stdout).toMatch(/API key saved/);
+
+      const saved = JSON.parse(
+        readFileSync(join(home, ".config", "postgresai", "config.json"), "utf8")
+      );
+      expect(saved.apiKey).toBe("test-token");
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+
   test("cli: auth login --help shows all options", () => {
     const r = runCli(["auth", "login", "--help"]);
     expect(r.status).toBe(0);

package/test/checkup.integration.test.ts

@@ -14,6 +14,7 @@ import { readFileSync } from "fs";
 import Ajv2020 from "ajv/dist/2020";
 
 import * as checkup from "../lib/checkup";
+import { checkCurrentUserPermissions } from "../lib/init";
 
 const ajv = new Ajv2020({ allErrors: true, strict: false });
 const schemasDir = resolve(import.meta.dir, "../../reporter/schemas");
@@ -191,6 +192,36 @@ describe.skipIf(!!skipReason)("checkup integration: express mode schema compatib
   // Test all checks supported by express mode
   const expressChecks = Object.keys(checkup.CHECK_INFO);
 
+  test("vanilla database preflight is non-fatal and full CLI output marks F004/F005 degraded", async () => {
+    const permissions = await checkCurrentUserPermissions(client);
+    expect(permissions.ok).toBe(true);
+    expect(permissions.missingOptional.some(
+      (row) => row.permission_name === "postgres_ai schema exists"
+    )).toBe(true);
+
+    const connString = `postgresql://postgres@localhost:${pg.port}/postgres?host=${encodeURIComponent(pg.socketDir)}`;
+    const cliPath = path.resolve(import.meta.dir, "..", "bin", "postgres-ai.ts");
+    const bunBin = typeof process.execPath === "string" && process.execPath.length > 0 ? process.execPath : "bun";
+    const result = Bun.spawnSync(
+      [bunBin, cliPath, "checkup", connString, "--no-upload", "--json"],
+      { env: { ...process.env, XDG_CONFIG_HOME: "/tmp/postgresai-test-empty-config" } }
+    );
+
+    const stderr = new TextDecoder().decode(result.stderr);
+    if (result.exitCode !== 0) {
+      throw new Error(`CLI exited ${result.exitCode}: ${stderr}`);
+    }
+    const reports = JSON.parse(new TextDecoder().decode(result.stdout));
+    expect(Object.keys(reports)).toHaveLength(17);
+    expect(stderr).toContain("optional: postgres_ai schema not found");
+    for (const checkId of ["F004", "F005"]) {
+      const dbEntry = reports[checkId].results["node-01"].data.postgres;
+      expect(dbEntry.status.ok).toBe(false);
+      expect(dbEntry.status.reason).toBe("missing_schema");
+      expect(dbEntry.status.error).toMatch(/schema "postgres_ai" does not exist/i);
+    }
+  }, { timeout: 60000 });
+
   for (const checkId of expressChecks) {
     test(`${checkId} report validates against shared schema`, async () => {
       const generator = checkup.REPORT_GENERATORS[checkId];
@@ -379,25 +410,4 @@ describe.skipIf(!!skipReason)("checkup integration: express mode schema compatib
     }
   });
 
-  test("CLI --markdown flag works without API key", async () => {
-    // Test that --markdown works even without an API key
-    const connString = `postgresql://postgres@${pg.socketDir}:${pg.port}/postgres`;
-    const cliPath = path.resolve(import.meta.dir, "..", "bin", "postgres-ai.ts");
-    const bunBin = typeof process.execPath === "string" && process.execPath.length > 0 ? process.execPath : "bun";
-
-    const result = Bun.spawnSync(
-      [bunBin, cliPath, "checkup", connString, "--check-id", "H002", "--markdown", "--no-upload"],
-      {
-        env: {
-          ...process.env,
-          XDG_CONFIG_HOME: "/tmp/postgresai-test-empty-config",
-        },
-      }
-    );
-
-    const stderr = new TextDecoder().decode(result.stderr);
-
-    // Should not complain about missing API key
-    expect(stderr).not.toMatch(/API key is required/i);
-  });
 });

package/test/checkup.test.ts

@@ -1539,12 +1539,13 @@ describe("CLI tests", () => {
     const r = runCli(["checkup", "--help"]);
     expect(r.status).toBe(0);
     expect(r.stdout).toMatch(/--markdown/);
-    expect(r.stdout).toMatch(/output markdown to stdout/i);
+    expect(r.stdout).toMatch(/PostgresAI API/i);
+    expect(r.stdout).toMatch(/transmits the full\s+report JSON/i);
   });
 
   test("checkup --markdown is recognized as valid option", () => {
     // Should not produce "unknown option" error for --markdown
-    const r = runCli(["checkup", "postgresql://test:test@localhost:5432/test", "--markdown", "--no-upload"]);
+    const r = runCli(["checkup", "postgresql://test:test@localhost:5432/test", "--markdown"]);
     // Connection will fail, but option parsing should succeed
     expect(r.stderr).not.toMatch(/unknown option/i);
     expect(r.stderr).not.toMatch(/did you mean/i);
@@ -1554,11 +1555,13 @@ describe("CLI tests", () => {
     // Use empty config dir to ensure no API key is configured
     const env = { XDG_CONFIG_HOME: "/tmp/postgresai-test-empty-config" };
     // --markdown should work even without API key
-    const r = runCli(["checkup", "postgresql://test:test@localhost:5432/test", "--markdown", "--no-upload"], env);
+    const r = runCli(["checkup", "postgresql://test:test@localhost:5432/test", "--markdown"], env);
     // Connection will fail, but --markdown flag should be recognized
     expect(r.status).not.toBe(0);
     expect(r.stderr).not.toMatch(/unknown option/i);
     expect(r.stderr).not.toMatch(/API key is required/i);
+    expect(r.stderr).toMatch(/full report JSON will still be sent/i);
+    expect(r.stderr).toMatch(/markdown conversion/i);
   });
 
   test("checkup with --no-upload and no output flags shows summary", () => {
@@ -1663,6 +1666,21 @@ describe("checkup auth pre-flight (CLI)", () => {
   // failure mentions this address.
   const DEAD_DB = "postgresql://test:test@127.0.0.1:2/test";
 
+  test("--no-upload rejects --markdown before database or API work", () => {
+    const env = {
+      XDG_CONFIG_HOME: `/tmp/postgresai-test-no-upload-markdown-${process.pid}`,
+      PGAI_API_KEY: "configured-token",
+      PGAI_API_BASE_URL: "http://127.0.0.1:1",
+    };
+    const r = runCli(["checkup", DEAD_DB, "--no-upload", "--markdown"], env);
+
+    expect(r.status).not.toBe(0);
+    expect(r.stderr).toMatch(/--no-upload and --markdown are mutually exclusive/i);
+    expect(r.stderr).toMatch(/markdown conversion is performed by the PostgresAI API/i);
+    expect(r.stderr).toMatch(/use --json or --output/i);
+    expect(r.stderr).not.toMatch(/127\.0\.0\.1:2|ECONNREFUSED/);
+  });
+
   test("no API key: prominent notice, run continues locally", () => {
     const env = {
       XDG_CONFIG_HOME: `/tmp/postgresai-test-preflight-nokey-${process.pid}`,
@@ -2173,6 +2191,31 @@ describe("checkup-summary", () => {
     );
   });
 
+  for (const checkId of ["F004", "F005"]) {
+    test(`generateCheckSummary for degraded ${checkId} is never ok`, () => {
+      const report = {
+        results: {
+          node1: {
+            data: {
+              db1: {
+                status: {
+                  ok: false,
+                  reason: "missing_schema",
+                  error: 'schema "postgres_ai" does not exist',
+                },
+                total_count: 0,
+              },
+            },
+          },
+        },
+      };
+
+      const result = summary.generateCheckSummary(checkId, report);
+      expect(result.status).toBe("warning");
+      expect(result.message).toMatch(/degraded.*missing schema/i);
+    });
+  }
+
   test("generateCheckSummary for H001 with no issues", () => {
     const report = {
       results: {
@@ -3371,6 +3414,7 @@ describe("Postgres version compatibility (PG13-PG18)", () => {
           autovacuum_vacuum_scale_factor: expectedAutovacuumSetting,
         });
         expect(reports.F004.results["test-node"].data.testdb).toEqual({
+          status: { ok: true, reason: null, error: null },
           bloated_tables: [],
           total_count: 0,
           total_bloat_size_bytes: 0,
@@ -3379,6 +3423,7 @@ describe("Postgres version compatibility (PG13-PG18)", () => {
           database_size_pretty: "1.00 GiB",
         });
         expect(reports.F005.results["test-node"].data.testdb).toEqual({
+          status: { ok: true, reason: null, error: null },
           bloated_indexes: [],
           total_count: 0,
           total_bloat_size_bytes: 0,

package/test/init.test.ts

@@ -1489,6 +1489,24 @@ describe("checkCurrentUserPermissions", () => {
     ).rejects.toThrow("permission denied for relation pg_roles");
   });
 
+  test("guards optional postgres_ai privilege probes when the schema is absent", async () => {
+    let capturedSql = "";
+    const client = {
+      query: async (sql: string) => {
+        capturedSql = sql;
+        return { rows: [] };
+      },
+    };
+
+    await init.checkCurrentUserPermissions(client as any);
+
+    expect(capturedSql).toContain("to_regnamespace('postgres_ai') is null");
+    expect(capturedSql).toContain("'postgres_ai schema exists' as permission_name");
+    expect(capturedSql).toMatch(
+      /when to_regnamespace\('postgres_ai'\) is null then null\s+when not has_schema_privilege/
+    );
+  });
+
   test("returns all rows for inspection", async () => {
     const rows: init.PermissionCheckRow[] = [
       { permission_name: "connect on database postgres", status: "required", granted: true, fix_command: null },
@@ -1545,6 +1563,23 @@ describe("formatPermissionCheckMessages", () => {
     expect(messages.errors).toHaveLength(0);
   });
 
+  test("explains that a missing postgres_ai schema only degrades F004/F005", () => {
+    const result: init.PreflightPermissionResult = {
+      ok: true,
+      rows: [],
+      missingRequired: [],
+      missingOptional: [
+        { permission_name: "postgres_ai schema exists", status: "optional", granted: false, fix_command: null },
+      ],
+    };
+
+    const messages = init.formatPermissionCheckMessages(result);
+    expect(messages.failed).toBe(false);
+    expect(messages.warnings).toEqual([
+      "Warning: optional: postgres_ai schema not found — F004/F005 (bloat estimates) will be skipped; run prepare-db or create the view manually to enable them.",
+    ]);
+  });
+
   test("returns errors with fix commands for missing required permissions", () => {
     const result: init.PreflightPermissionResult = {
       ok: false,