postgresai 0.16.0-rc.3 → 0.16.0-rc.4

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## Unreleased
+
+### Fixed
+
+- `checkup --markdown` previously performed server-side conversion and sent the
+  full report JSON to the PostgresAI API even when `--no-upload` was set. The
+  flags are now mutually exclusive, and `--no-upload` prevents report data from
+  being sent to the PostgresAI API. Use `--json` or `--output` for local-only
+  output.

package/bin/postgres-ai.ts

@@ -335,12 +335,18 @@ function prepareUploadConfig(
       console.error("Tip: run 'postgresai auth' or pass --api-key / set PGAI_API_KEY");
       return null; // Signal to exit
     }
-    // No credentials and upload not explicitly requested: fall back to
-    // local-only mode, but say so prominently — skipping the upload silently
-    // hides the fact that results never reach the Console.
-    console.error("Notice: no API key configured — results will NOT be uploaded to PostgresAI.");
-    console.error("        To upload: run 'postgresai auth login' or pass --api-key / set PGAI_API_KEY.");
-    console.error("        To run locally without this notice, pass --no-upload.");
+    if (opts.markdown) {
+      console.error("Notice: no API key configured — regular report upload is disabled.");
+      console.error("        The full report JSON will still be sent to the PostgresAI API for markdown conversion.");
+      console.error("        To avoid sending report data, replace --markdown with --no-upload and --json or --output.");
+    } else {
+      // No credentials and upload not explicitly requested: fall back to
+      // local-only mode, but say so prominently — skipping the upload silently
+      // hides the fact that results never reach the Console.
+      console.error("Notice: no API key configured — results will NOT be uploaded to PostgresAI.");
+      console.error("        To upload: run 'postgresai auth login' or pass --api-key / set PGAI_API_KEY.");
+      console.error("        To run locally without this notice, pass --no-upload.");
+    }
     return undefined; // Skip upload, run checks locally
   }
 
@@ -1996,7 +2002,7 @@ program
     "project name or ID for remote upload (used with --upload; defaults to config defaultProject; auto-generated on first run)"
   )
   .option("--json", "output JSON to stdout")
-  .option("--markdown", "output markdown to stdout")
+  .option("--markdown", "output markdown via PostgresAI API (transmits the full report JSON)")
   .addHelpText(
     "after",
     [
@@ -2010,7 +2016,7 @@ program
       "  postgresai checkup postgresql://user:pass@host:5432/db --check-id H002",
       "  postgresai checkup postgresql://user:pass@host:5432/db --output ./reports",
       "  postgresai checkup postgresql://user:pass@host:5432/db --no-upload --json",
-      "  postgresai checkup postgresql://user:pass@host:5432/db --no-upload --markdown",
+      "  postgresai checkup postgresql://user:pass@host:5432/db --markdown",
     ].join("\n")
   )
   .action(async (checkIdOrConn: string | undefined, connArg: string | undefined, opts: CheckupOptions, cmd: Command) => {
@@ -2060,9 +2066,14 @@ program
       process.exitCode = 1;
       return;
     }
-    // Note: --json, --markdown and --upload/--no-upload are independent flags.
-    // Use --no-upload to explicitly disable upload when using --json or --markdown.
     const uploadExplicitlyDisabled = opts.upload === false;
+    if (uploadExplicitlyDisabled && shouldConvertMarkdown) {
+      console.error("Error: --no-upload and --markdown are mutually exclusive");
+      console.error("Markdown conversion is performed by the PostgresAI API and transmits the full report JSON.");
+      console.error("Drop --no-upload to allow transmission, or use --json or --output for local-only output.");
+      process.exitCode = 1;
+      return;
+    }
     let shouldUpload = !uploadExplicitlyDisabled;
 
     // Preflight: validate/create output directory BEFORE connecting / running checks.
@@ -2308,7 +2319,9 @@ program
 
         console.log('\nFor details:');
         console.log('  --json          Output JSON');
-        console.log('  --markdown      Output markdown');
+        if (!uploadExplicitlyDisabled) {
+          console.log('  --markdown      Output markdown via PostgresAI API');
+        }
         console.log('  --output <dir>  Save to directory');
       }
     } catch (error) {
@@ -3931,13 +3944,9 @@ targets
 // Authentication and API key management
 const auth = program.command("auth").description("authentication and API key management");
 
-auth
-  .command("login", { isDefault: true })
-  .description("authenticate via browser (OAuth) or store API key directly")
-  .option("--set-key <key>", "store API key directly without OAuth flow")
-  .option("--port <port>", "local callback server port (default: random)", parseInt)
-  .option("--debug", "enable debug output")
-  .action(async (opts: { setKey?: string; port?: number; debug?: boolean }) => {
+type AuthLoginOptions = { setKey?: string; port?: number; debug?: boolean };
+
+async function runAuthLogin(opts: AuthLoginOptions) {
     // If --set-key is provided, store it directly without OAuth
     if (opts.setKey) {
       const trimmedKey = opts.setKey.trim();
@@ -4191,7 +4200,21 @@ auth
       console.error(`Authentication error: ${message}`);
       process.exit(1);
     }
-  });
+}
+
+function configureLoginCommand(command: Command): Command {
+  return command
+    .description("authenticate via browser (OAuth) or store API key directly")
+    .option("--set-key <key>", "store API key directly without OAuth flow")
+    .option("--port <port>", "local callback server port (default: random)", parseInt)
+    .option("--debug", "enable debug output");
+}
+
+configureLoginCommand(auth.command("login", { isDefault: true }))
+  .action(runAuthLogin);
+
+configureLoginCommand(program.command("login"))
+  .action(runAuthLogin);
 
 auth
   .command("show-key")

package/dist/bin/postgres-ai.js

@@ -13425,7 +13425,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.16.0-rc.3",
+  version: "0.16.0-rc.4",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -16256,7 +16256,7 @@ var Result = import_lib.default.Result;
 var TypeOverrides = import_lib.default.TypeOverrides;
 var defaults = import_lib.default.defaults;
 // package.json
-var version = "0.16.0-rc.3";
+var version = "0.16.0-rc.4";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -29518,10 +29518,28 @@ async function checkCurrentUserPermissions(client) {
 
       union all
 
+      select
+        'postgres_ai schema exists' as permission_name,
+        'optional' as status,
+        to_regnamespace('postgres_ai') is not null as granted
+
+      union all
+
+      select
+        'usage on postgres_ai schema' as permission_name,
+        'optional' as status,
+        case
+          when to_regnamespace('postgres_ai') is null then null
+          else has_schema_privilege(current_user, 'postgres_ai', 'USAGE')
+        end as granted
+
+      union all
+
       select
         'postgres_ai.pg_statistic view exists' as permission_name,
         'optional' as status,
         case
+          when to_regnamespace('postgres_ai') is null then null
           when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then null
           else to_regclass('postgres_ai.pg_statistic') is not null
         end as granted
@@ -29532,6 +29550,7 @@ async function checkCurrentUserPermissions(client) {
         'select on postgres_ai.pg_statistic' as permission_name,
         'optional' as status,
         case
+          when to_regnamespace('postgres_ai') is null then null
           when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then null
           when to_regclass('postgres_ai.pg_statistic') is null then null
           else has_table_privilege(current_user, 'postgres_ai.pg_statistic', 'select')
@@ -29551,6 +29570,10 @@ async function checkCurrentUserPermissions(client) {
             when permission_name like 'select on pg_catalog.pg_index' then
               format('grant select on pg_catalog.pg_index to %I;', current_user)
           end
+        when permission_name = 'postgres_ai schema exists' and granted = false then
+          '-- run postgresai prepare-db or create the postgres_ai schema and pg_statistic view manually'
+        when permission_name = 'usage on postgres_ai schema' and granted = false then
+          format('grant usage on schema postgres_ai to %I;', current_user)
         when permission_name = 'postgres_ai.pg_statistic view exists' and granted = false then
           '-- create postgres_ai.pg_statistic view (see setup script)'
         when permission_name = 'select on postgres_ai.pg_statistic' and granted = false then
@@ -29577,6 +29600,10 @@ function formatPermissionCheckMessages(result) {
   const warnings = [];
   const errors3 = [];
   for (const row of result.missingOptional) {
+    if (row.permission_name === "postgres_ai schema exists") {
+      warnings.push("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.");
+      continue;
+    }
     const fix = row.fix_command ? ` Fix: ${row.fix_command}` : "";
     warnings.push(`Warning: optional permission missing — ${row.permission_name}.${fix}`);
   }
@@ -32765,12 +32792,70 @@ async function generateF003(client, nodeName) {
   };
   return report;
 }
+function bloatErrorStatus(err) {
+  const error2 = err instanceof Error ? err.message : String(err);
+  const code = typeof err === "object" && err !== null && "code" in err ? String(err.code || "") : "";
+  const normalized = error2.toLowerCase();
+  let reason = "query_error";
+  if (code === "3F000" || normalized.includes('schema "postgres_ai" does not exist')) {
+    reason = "missing_schema";
+  } else if (code === "42P01" || normalized.includes('relation "postgres_ai.pg_statistic" does not exist')) {
+    reason = "missing_view";
+  } else if (code === "42501" || normalized.includes("permission denied")) {
+    reason = "missing_grant";
+  }
+  return { ok: false, reason, error: error2 };
+}
+async function getBloatCheckStatus(client) {
+  try {
+    const result = await client.query(`
+      select
+        to_regnamespace('postgres_ai') is not null as schema_exists,
+        case
+          when to_regnamespace('postgres_ai') is null then false
+          else has_schema_privilege(current_user, 'postgres_ai', 'USAGE')
+        end as schema_usage,
+        case
+          when to_regnamespace('postgres_ai') is null then false
+          when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then false
+          else to_regclass('postgres_ai.pg_statistic') is not null
+        end as view_exists,
+        case
+          when to_regnamespace('postgres_ai') is null then false
+          when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then false
+          when to_regclass('postgres_ai.pg_statistic') is null then false
+          else has_table_privilege(current_user, 'postgres_ai.pg_statistic', 'SELECT')
+        end as view_select
+    `);
+    const capability = result.rows[0] || {};
+    if (!capability.schema_exists) {
+      return { ok: false, reason: "missing_schema", error: 'schema "postgres_ai" does not exist' };
+    }
+    if (!capability.schema_usage) {
+      return { ok: false, reason: "missing_grant", error: "permission denied for schema postgres_ai" };
+    }
+    if (!capability.view_exists) {
+      return { ok: false, reason: "missing_view", error: 'relation "postgres_ai.pg_statistic" does not exist' };
+    }
+    if (!capability.view_select) {
+      return { ok: false, reason: "missing_grant", error: "permission denied for relation postgres_ai.pg_statistic" };
+    }
+    return { ok: true, reason: null, error: null };
+  } catch (err) {
+    return bloatErrorStatus(err);
+  }
+}
 async function generateF004(client, nodeName) {
   const report = createBaseReport("F004", "Autovacuum: heap bloat (estimated)", nodeName);
   const postgresVersion = await getPostgresVersion(client);
   const pgMajorVersion = parseInt(postgresVersion.server_major_ver, 10);
   let bloatedTables = [];
+  let status = await getBloatCheckStatus(client);
   try {
+    if (!status.ok)
+      throw Object.assign(new Error(status.error || "Bloat prerequisites unavailable"), {
+        code: status.reason === "missing_schema" ? "3F000" : status.reason === "missing_view" ? "42P01" : status.reason === "missing_grant" ? "42501" : undefined
+      });
     const sql = getMetricSql(METRIC_NAMES.F004, pgMajorVersion);
     const bloatResult = await client.query(sql);
     const vacuumStatsResult = await client.query(`
@@ -32814,7 +32899,8 @@ async function generateF004(client, nodeName) {
       };
     });
   } catch (err) {
-    const errorMsg = err instanceof Error ? err.message : String(err);
+    status = bloatErrorStatus(err);
+    const errorMsg = status.error || "Unknown error";
     console.error(`[F004] Error estimating table bloat: ${errorMsg}`);
     if (errorMsg.includes("postgres_ai.")) {
       console.error(`  Hint: Run "postgresai prepare-db <connection>" to create required objects.`);
@@ -32824,6 +32910,7 @@ async function generateF004(client, nodeName) {
   const totalCount = bloatedTables.length;
   const totalBloatSizeBytes = bloatedTables.reduce((sum, t) => sum + t.bloat_size, 0);
   const dbEntry = {
+    status,
     bloated_tables: bloatedTables,
     total_count: totalCount,
     total_bloat_size_bytes: totalBloatSizeBytes,
@@ -32842,7 +32929,12 @@ async function generateF005(client, nodeName) {
   const postgresVersion = await getPostgresVersion(client);
   const pgMajorVersion = parseInt(postgresVersion.server_major_ver, 10);
   let bloatedIndexes = [];
+  let status = await getBloatCheckStatus(client);
   try {
+    if (!status.ok)
+      throw Object.assign(new Error(status.error || "Bloat prerequisites unavailable"), {
+        code: status.reason === "missing_schema" ? "3F000" : status.reason === "missing_view" ? "42P01" : status.reason === "missing_grant" ? "42501" : undefined
+      });
     const sql = getMetricSql(METRIC_NAMES.F005, pgMajorVersion);
     const bloatResult = await client.query(sql);
     const vacuumStatsResult = await client.query(`
@@ -32891,7 +32983,8 @@ async function generateF005(client, nodeName) {
       };
     });
   } catch (err) {
-    const errorMsg = err instanceof Error ? err.message : String(err);
+    status = bloatErrorStatus(err);
+    const errorMsg = status.error || "Unknown error";
     console.error(`[F005] Error estimating index bloat: ${errorMsg}`);
     if (errorMsg.includes("postgres_ai.")) {
       console.error(`  Hint: Run "postgresai prepare-db <connection>" to create required objects.`);
@@ -32901,6 +32994,7 @@ async function generateF005(client, nodeName) {
   const totalCount = bloatedIndexes.length;
   const totalBloatSizeBytes = bloatedIndexes.reduce((sum, idx) => sum + idx.bloat_size, 0);
   const dbEntry = {
+    status,
     bloated_indexes: bloatedIndexes,
     total_count: totalCount,
     total_bloat_size_bytes: totalBloatSizeBytes,
@@ -33573,6 +33667,10 @@ function generateCheckSummary(checkId, report) {
       return summarizeF001(nodeData);
     case "F003":
       return summarizeF003(nodeData);
+    case "F004":
+      return summarizeBloat(nodeData, "table");
+    case "F005":
+      return summarizeBloat(nodeData, "index");
     case "G001":
       return summarizeG001(nodeData);
     case "G003":
@@ -33758,6 +33856,25 @@ function summarizeF003(nodeData) {
   }
   return { status: "warning", message: parts.join(", ") };
 }
+function summarizeBloat(nodeData, kind) {
+  const data = nodeData?.data || {};
+  let totalCount = 0;
+  for (const dbData of Object.values(data)) {
+    const dbEntry = dbData;
+    if (dbEntry?.status?.ok === false) {
+      const reason = String(dbEntry.status.reason || "query_error").replaceAll("_", " ");
+      return { status: "warning", message: `Bloat estimate degraded: ${reason}` };
+    }
+    totalCount += dbEntry?.total_count || 0;
+  }
+  if (totalCount === 0) {
+    return { status: "ok", message: `No bloated ${kind}${kind === "index" ? "es" : "s"} found` };
+  }
+  return {
+    status: "warning",
+    message: `Found ${totalCount} bloated ${kind}${totalCount === 1 ? "" : kind === "index" ? "es" : "s"}`
+  };
+}
 function summarizeG001(nodeData) {
   const data = nodeData?.data || {};
   const settingsCount = Object.keys(data).length;
@@ -34114,9 +34231,15 @@ function prepareUploadConfig(opts, rootOpts, shouldUpload, uploadExplicitlyReque
       console.error("Tip: run 'postgresai auth' or pass --api-key / set PGAI_API_KEY");
       return null;
     }
-    console.error("Notice: no API key configured \u2014 results will NOT be uploaded to PostgresAI.");
-    console.error("        To upload: run 'postgresai auth login' or pass --api-key / set PGAI_API_KEY.");
-    console.error("        To run locally without this notice, pass --no-upload.");
+    if (opts.markdown) {
+      console.error("Notice: no API key configured \u2014 regular report upload is disabled.");
+      console.error("        The full report JSON will still be sent to the PostgresAI API for markdown conversion.");
+      console.error("        To avoid sending report data, replace --markdown with --no-upload and --json or --output.");
+    } else {
+      console.error("Notice: no API key configured \u2014 results will NOT be uploaded to PostgresAI.");
+      console.error("        To upload: run 'postgresai auth login' or pass --api-key / set PGAI_API_KEY.");
+      console.error("        To run locally without this notice, pass --no-upload.");
+    }
     return;
   }
   const cfg = readConfig();
@@ -35341,7 +35464,7 @@ program2.command("unprepare-db [conn]").description("remove monitoring setup: dr
     closeReadline();
   }
 });
-program2.command("checkup [checkIdOrConn] [conn]").description("generate health check reports directly from PostgreSQL (express mode)").option("--check-id <id>", `specific check to run (see list below), or ALL`).option("--node-name <name>", "node name for reports", "node-01").option("--output <path>", "output directory for JSON files").option("--upload", "upload JSON results to PostgresAI (requires API key)").option("--no-upload", "disable upload to PostgresAI").option("--project <project>", "project name or ID for remote upload (used with --upload; defaults to config defaultProject; auto-generated on first run)").option("--json", "output JSON to stdout").option("--markdown", "output markdown to stdout").addHelpText("after", [
+program2.command("checkup [checkIdOrConn] [conn]").description("generate health check reports directly from PostgreSQL (express mode)").option("--check-id <id>", `specific check to run (see list below), or ALL`).option("--node-name <name>", "node name for reports", "node-01").option("--output <path>", "output directory for JSON files").option("--upload", "upload JSON results to PostgresAI (requires API key)").option("--no-upload", "disable upload to PostgresAI").option("--project <project>", "project name or ID for remote upload (used with --upload; defaults to config defaultProject; auto-generated on first run)").option("--json", "output JSON to stdout").option("--markdown", "output markdown via PostgresAI API (transmits the full report JSON)").addHelpText("after", [
   "",
   "Available checks:",
   ...Object.entries(CHECK_INFO).map(([id, title]) => `  ${id}: ${title}`),
@@ -35352,7 +35475,7 @@ program2.command("checkup [checkIdOrConn] [conn]").description("generate health
   "  postgresai checkup postgresql://user:pass@host:5432/db --check-id H002",
   "  postgresai checkup postgresql://user:pass@host:5432/db --output ./reports",
   "  postgresai checkup postgresql://user:pass@host:5432/db --no-upload --json",
-  "  postgresai checkup postgresql://user:pass@host:5432/db --no-upload --markdown"
+  "  postgresai checkup postgresql://user:pass@host:5432/db --markdown"
 ].join(`
 `)).action(async (checkIdOrConn, connArg, opts, cmd) => {
   const checkIdPattern = /^[A-Z]\d{3}$/i;
@@ -35392,6 +35515,13 @@ Usage: postgresai checkup ${checkId} postgresql://user@host:5432/dbname
     return;
   }
   const uploadExplicitlyDisabled = opts.upload === false;
+  if (uploadExplicitlyDisabled && shouldConvertMarkdown) {
+    console.error("Error: --no-upload and --markdown are mutually exclusive");
+    console.error("Markdown conversion is performed by the PostgresAI API and transmits the full report JSON.");
+    console.error("Drop --no-upload to allow transmission, or use --json or --output for local-only output.");
+    process.exitCode = 1;
+    return;
+  }
   let shouldUpload = !uploadExplicitlyDisabled;
   const outputPath = prepareOutputDirectory(opts.output);
   if (outputPath === null) {
@@ -35574,7 +35704,9 @@ Usage: postgresai checkup ${checkId} postgresql://user@host:5432/dbname
       console.log(`
 For details:`);
       console.log("  --json          Output JSON");
-      console.log("  --markdown      Output markdown");
+      if (!uploadExplicitlyDisabled) {
+        console.log("  --markdown      Output markdown via PostgresAI API");
+      }
       console.log("  --output <dir>  Save to directory");
     }
   } catch (error2) {
@@ -36789,7 +36921,7 @@ targets.command("test <name>").description("test monitoring target database conn
   }
 });
 var auth = program2.command("auth").description("authentication and API key management");
-auth.command("login", { isDefault: true }).description("authenticate via browser (OAuth) or store API key directly").option("--set-key <key>", "store API key directly without OAuth flow").option("--port <port>", "local callback server port (default: random)", parseInt).option("--debug", "enable debug output").action(async (opts) => {
+async function runAuthLogin(opts) {
   if (opts.setKey) {
     const trimmedKey = opts.setKey.trim();
     if (!trimmedKey) {
@@ -36990,7 +37122,12 @@ Authentication failed: ${message}`);
     console.error(`Authentication error: ${message}`);
     process.exit(1);
   }
-});
+}
+function configureLoginCommand(command) {
+  return command.description("authenticate via browser (OAuth) or store API key directly").option("--set-key <key>", "store API key directly without OAuth flow").option("--port <port>", "local callback server port (default: random)", parseInt).option("--debug", "enable debug output");
+}
+configureLoginCommand(auth.command("login", { isDefault: true })).action(runAuthLogin);
+configureLoginCommand(program2.command("login")).action(runAuthLogin);
 auth.command("show-key").description("show API key (masked)").action(async () => {
   const cfg = readConfig();
   if (!cfg.apiKey) {

package/lib/checkup-summary.ts

@@ -41,6 +41,8 @@ export function generateCheckSummary(checkId: string, report: any): CheckSummary
     case 'D004': return summarizeD004(nodeData);
     case 'F001': return summarizeF001(nodeData);
     case 'F003': return summarizeF003(nodeData);
+    case 'F004': return summarizeBloat(nodeData, 'table');
+    case 'F005': return summarizeBloat(nodeData, 'index');
     case 'G001': return summarizeG001(nodeData);
     case 'G003': return summarizeG003(nodeData);
     default:
@@ -273,6 +275,29 @@ function summarizeF003(nodeData: any): CheckSummary {
   return { status: 'warning', message: parts.join(', ') };
 }
 
+function summarizeBloat(nodeData: any, kind: 'table' | 'index'): CheckSummary {
+  const data = nodeData?.data || {};
+  let totalCount = 0;
+
+  for (const dbData of Object.values(data)) {
+    const dbEntry = dbData as any;
+    if (dbEntry?.status?.ok === false) {
+      const reason = String(dbEntry.status.reason || 'query_error').replaceAll('_', ' ');
+      return { status: 'warning', message: `Bloat estimate degraded: ${reason}` };
+    }
+    totalCount += dbEntry?.total_count || 0;
+  }
+
+  if (totalCount === 0) {
+    return { status: 'ok', message: `No bloated ${kind}${kind === 'index' ? 'es' : 's'} found` };
+  }
+
+  return {
+    status: 'warning',
+    message: `Found ${totalCount} bloated ${kind}${totalCount === 1 ? '' : kind === 'index' ? 'es' : 's'}`,
+  };
+}
+
 function summarizeG001(nodeData: any): CheckSummary {
   const data = nodeData?.data || {};
   const settingsCount = Object.keys(data).length;

package/lib/checkup.ts

@@ -1498,6 +1498,74 @@ async function generateF003(client: Client, nodeName: string): Promise<Report> {
  * Uses pg_stats for column statistics to estimate row sizes.
  * SQL loaded from config/pgwatch-prometheus/metrics.yml (pg_table_bloat metric).
  */
+type BloatCheckReason = "missing_schema" | "missing_view" | "missing_grant" | "query_error";
+
+interface BloatCheckStatus {
+  ok: boolean;
+  reason: BloatCheckReason | null;
+  error: string | null;
+}
+
+function bloatErrorStatus(err: unknown): BloatCheckStatus {
+  const error = err instanceof Error ? err.message : String(err);
+  const code = typeof err === "object" && err !== null && "code" in err
+    ? String((err as { code?: unknown }).code || "")
+    : "";
+  const normalized = error.toLowerCase();
+
+  let reason: BloatCheckReason = "query_error";
+  if (code === "3F000" || normalized.includes('schema "postgres_ai" does not exist')) {
+    reason = "missing_schema";
+  } else if (code === "42P01" || normalized.includes('relation "postgres_ai.pg_statistic" does not exist')) {
+    reason = "missing_view";
+  } else if (code === "42501" || normalized.includes("permission denied")) {
+    reason = "missing_grant";
+  }
+
+  return { ok: false, reason, error };
+}
+
+async function getBloatCheckStatus(client: Client): Promise<BloatCheckStatus> {
+  try {
+    const result = await client.query(`
+      select
+        to_regnamespace('postgres_ai') is not null as schema_exists,
+        case
+          when to_regnamespace('postgres_ai') is null then false
+          else has_schema_privilege(current_user, 'postgres_ai', 'USAGE')
+        end as schema_usage,
+        case
+          when to_regnamespace('postgres_ai') is null then false
+          when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then false
+          else to_regclass('postgres_ai.pg_statistic') is not null
+        end as view_exists,
+        case
+          when to_regnamespace('postgres_ai') is null then false
+          when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then false
+          when to_regclass('postgres_ai.pg_statistic') is null then false
+          else has_table_privilege(current_user, 'postgres_ai.pg_statistic', 'SELECT')
+        end as view_select
+    `);
+    const capability = result.rows[0] || {};
+
+    if (!capability.schema_exists) {
+      return { ok: false, reason: "missing_schema", error: 'schema "postgres_ai" does not exist' };
+    }
+    if (!capability.schema_usage) {
+      return { ok: false, reason: "missing_grant", error: "permission denied for schema postgres_ai" };
+    }
+    if (!capability.view_exists) {
+      return { ok: false, reason: "missing_view", error: 'relation "postgres_ai.pg_statistic" does not exist' };
+    }
+    if (!capability.view_select) {
+      return { ok: false, reason: "missing_grant", error: "permission denied for relation postgres_ai.pg_statistic" };
+    }
+    return { ok: true, reason: null, error: null };
+  } catch (err) {
+    return bloatErrorStatus(err);
+  }
+}
+
 async function generateF004(client: Client, nodeName: string): Promise<Report> {
   const report = createBaseReport("F004", "Autovacuum: heap bloat (estimated)", nodeName);
   const postgresVersion = await getPostgresVersion(client);
@@ -1520,8 +1588,15 @@ async function generateF004(client: Client, nodeName: string): Promise<Report> {
   }
 
   let bloatedTables: BloatedTable[] = [];
+  let status = await getBloatCheckStatus(client);
 
   try {
+    if (!status.ok) throw Object.assign(new Error(status.error || "Bloat prerequisites unavailable"), {
+      code: status.reason === "missing_schema" ? "3F000"
+        : status.reason === "missing_view" ? "42P01"
+        : status.reason === "missing_grant" ? "42501"
+        : undefined,
+    });
     // Get bloat data
     const sql = getMetricSql(METRIC_NAMES.F004, pgMajorVersion);
     const bloatResult = await client.query(sql);
@@ -1572,7 +1647,8 @@ async function generateF004(client: Client, nodeName: string): Promise<Report> {
       };
     });
   } catch (err) {
-    const errorMsg = err instanceof Error ? err.message : String(err);
+    status = bloatErrorStatus(err);
+    const errorMsg = status.error || "Unknown error";
     console.error(`[F004] Error estimating table bloat: ${errorMsg}`);
     if (errorMsg.includes("postgres_ai.")) {
       console.error(`  Hint: Run "postgresai prepare-db <connection>" to create required objects.`);
@@ -1587,6 +1663,7 @@ async function generateF004(client: Client, nodeName: string): Promise<Report> {
   const totalBloatSizeBytes = bloatedTables.reduce((sum, t) => sum + t.bloat_size, 0);
 
   const dbEntry = {
+    status,
     bloated_tables: bloatedTables,
     total_count: totalCount,
     total_bloat_size_bytes: totalBloatSizeBytes,
@@ -1634,8 +1711,15 @@ async function generateF005(client: Client, nodeName: string): Promise<Report> {
   }
 
   let bloatedIndexes: BloatedIndex[] = [];
+  let status = await getBloatCheckStatus(client);
 
   try {
+    if (!status.ok) throw Object.assign(new Error(status.error || "Bloat prerequisites unavailable"), {
+      code: status.reason === "missing_schema" ? "3F000"
+        : status.reason === "missing_view" ? "42P01"
+        : status.reason === "missing_grant" ? "42501"
+        : undefined,
+    });
     // Get bloat data
     const sql = getMetricSql(METRIC_NAMES.F005, pgMajorVersion);
     const bloatResult = await client.query(sql);
@@ -1690,7 +1774,8 @@ async function generateF005(client: Client, nodeName: string): Promise<Report> {
       };
     });
   } catch (err) {
-    const errorMsg = err instanceof Error ? err.message : String(err);
+    status = bloatErrorStatus(err);
+    const errorMsg = status.error || "Unknown error";
     console.error(`[F005] Error estimating index bloat: ${errorMsg}`);
     if (errorMsg.includes("postgres_ai.")) {
       console.error(`  Hint: Run "postgresai prepare-db <connection>" to create required objects.`);
@@ -1705,6 +1790,7 @@ async function generateF005(client: Client, nodeName: string): Promise<Report> {
   const totalBloatSizeBytes = bloatedIndexes.reduce((sum, idx) => sum + idx.bloat_size, 0);
 
   const dbEntry = {
+    status,
     bloated_indexes: bloatedIndexes,
     total_count: totalCount,
     total_bloat_size_bytes: totalBloatSizeBytes,

package/lib/init.ts

@@ -1019,10 +1019,28 @@ export async function checkCurrentUserPermissions(
 
       union all
 
+      select
+        'postgres_ai schema exists' as permission_name,
+        'optional' as status,
+        to_regnamespace('postgres_ai') is not null as granted
+
+      union all
+
+      select
+        'usage on postgres_ai schema' as permission_name,
+        'optional' as status,
+        case
+          when to_regnamespace('postgres_ai') is null then null
+          else has_schema_privilege(current_user, 'postgres_ai', 'USAGE')
+        end as granted
+
+      union all
+
       select
         'postgres_ai.pg_statistic view exists' as permission_name,
         'optional' as status,
         case
+          when to_regnamespace('postgres_ai') is null then null
           when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then null
           else to_regclass('postgres_ai.pg_statistic') is not null
         end as granted
@@ -1033,6 +1051,7 @@ export async function checkCurrentUserPermissions(
         'select on postgres_ai.pg_statistic' as permission_name,
         'optional' as status,
         case
+          when to_regnamespace('postgres_ai') is null then null
           when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then null
           when to_regclass('postgres_ai.pg_statistic') is null then null
           else has_table_privilege(current_user, 'postgres_ai.pg_statistic', 'select')
@@ -1052,6 +1071,10 @@ export async function checkCurrentUserPermissions(
             when permission_name like 'select on pg_catalog.pg_index' then
               format('grant select on pg_catalog.pg_index to %I;', current_user)
           end
+        when permission_name = 'postgres_ai schema exists' and granted = false then
+          '-- run postgresai prepare-db or create the postgres_ai schema and pg_statistic view manually'
+        when permission_name = 'usage on postgres_ai schema' and granted = false then
+          format('grant usage on schema postgres_ai to %I;', current_user)
         when permission_name = 'postgres_ai.pg_statistic view exists' and granted = false then
           '-- create postgres_ai.pg_statistic view (see setup script)'
         when permission_name = 'select on postgres_ai.pg_statistic' and granted = false then
@@ -1097,6 +1120,12 @@ export function formatPermissionCheckMessages(result: PreflightPermissionResult)
   const errors: string[] = [];
 
   for (const row of result.missingOptional) {
+    if (row.permission_name === "postgres_ai schema exists") {
+      warnings.push(
+        "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."
+      );
+      continue;
+    }
     const fix = row.fix_command ? ` Fix: ${row.fix_command}` : "";
     warnings.push(`Warning: optional permission missing — ${row.permission_name}.${fix}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresai",
-  "version": "0.16.0-rc.3",
+  "version": "0.16.0-rc.4",
   "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,

package/test/schema-validation.test.ts

@@ -99,6 +99,46 @@ describe("Schema validation", () => {
     validateAgainstSchema(report, "F003");
   });
 
+  for (const checkId of ["F004", "F005"]) {
+    test(`${checkId} distinguishes a healthy empty result from missing schema`, async () => {
+      const healthyClient = createMockClient();
+      const healthy = await checkup.REPORT_GENERATORS[checkId](healthyClient as any, "node-01");
+      const healthyDb = healthy.results["node-01"].data.testdb;
+      expect(healthyDb.status).toEqual({ ok: true, reason: null, error: null });
+      validateAgainstSchema(healthy, checkId);
+
+      const missingSchemaClient = createMockClient({
+        bloatCapabilityRows: [
+          { schema_exists: false, schema_usage: false, view_exists: false, view_select: false },
+        ],
+      });
+      const degraded = await checkup.REPORT_GENERATORS[checkId](missingSchemaClient as any, "node-01");
+      const degradedDb = degraded.results["node-01"].data.testdb;
+      expect(degradedDb.status).toEqual({
+        ok: false,
+        reason: "missing_schema",
+        error: 'schema "postgres_ai" does not exist',
+      });
+      validateAgainstSchema(degraded, checkId);
+    });
+
+    test(`${checkId} exposes missing-grant degradation`, async () => {
+      const client = createMockClient({
+        bloatCapabilityRows: [
+          { schema_exists: true, schema_usage: true, view_exists: true, view_select: false },
+        ],
+      });
+      const report = await checkup.REPORT_GENERATORS[checkId](client as any, "node-01");
+      const dbEntry = report.results["node-01"].data.testdb;
+      expect(dbEntry.status).toEqual({
+        ok: false,
+        reason: "missing_grant",
+        error: "permission denied for relation postgres_ai.pg_statistic",
+      });
+      validateAgainstSchema(report, checkId);
+    });
+  }
+
   // Settings reports (D004, F001, G001) - single test each
   for (const checkId of ["D004", "F001", "G001"]) {
     test(`${checkId} validates against schema`, async () => {

package/test/test-utils.ts

@@ -19,6 +19,7 @@ export interface MockClientOptions {
   indexBloatRows?: any[];
   deadTuplesRows?: any[];
   vacuumStatsRows?: any[];
+  bloatCapabilityRows?: any[];
   deadlockStatsRows?: any[];
   pgStatStatementsExtensionRows?: any[];
   pgStatStatementsStatsRows?: any[];
@@ -61,6 +62,7 @@ export function createMockClient(options: MockClientOptions = {}) {
     indexBloatRows = [],
     deadTuplesRows = [],
     vacuumStatsRows = [],
+    bloatCapabilityRows = [{ schema_exists: true, schema_usage: true, view_exists: true, view_select: true }],
     deadlockStatsRows = [{ deadlocks: "0", conflicts: "0", stats_reset: null }],
     pgStatStatementsExtensionRows = [],
     pgStatStatementsStatsRows = [],
@@ -128,6 +130,9 @@ export function createMockClient(options: MockClientOptions = {}) {
         return { rows: deadTuplesRows };
       }
       // F004/F005: bloat metrics from metrics.yml
+      if (sql.includes("to_regnamespace('postgres_ai')") && sql.includes("view_select")) {
+        return { rows: bloatCapabilityRows };
+      }
       if (sql.includes("tag_idxname") && sql.includes("bloat_size")) {
         return { rows: indexBloatRows };
       }