postgresai 0.16.0-dev.1 → 0.16.0-dev.11

package/lib/supabase.ts

@@ -733,24 +733,6 @@ export async function verifyInitSetupViaSupabase(params: {
   }
 
   // Check helper functions - first verify they exist to avoid has_function_privilege errors
-  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('${escapeLiteral(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

package/lib/util.ts

@@ -28,45 +28,185 @@ 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. 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, 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;
+  let bodyCode: string | undefined;
+  let bodyHint: 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 = 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 = 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 - append it if it's short and useful
+      // 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) {
-        errMsg += `\n${trimmed}`;
+        bodyDetails = redactTextSecrets(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 safeReasonPhrase = reasonPhrase ? redactTextSecrets(reasonPhrase) : undefined;
+
+  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;
 }
 
+/**
+ * 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})`;
+}
+
+/**
+ * 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 "****";
@@ -74,6 +214,89 @@ 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)}`;
 }
 
+/**
+ * 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: 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
+ * 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 redactTextSecrets(text);
+  }
+  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]");
+}
+
 
 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.11",
   "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}};
-
-

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,