Merge branch 'fix/checkup-no-upload-markdown' into 'main'

fix(cli): reject markdown with no-upload

Closes #284

See merge request postgres-ai/postgresai!359

Author: NikolayS

README.md

@@ -64,7 +64,7 @@ Open [console.postgres.ai](https://console.postgres.ai) to see:
 - Issues workflow to track remediation
 - Historical data across all your projects
 
-> **Offline mode:** Add `--no-upload` to run locally without an account.
+> **Offline mode:** Add `--no-upload` to run locally without an account or sending report data to the PostgresAI API.
 
 <details open>
 <summary>See demo</summary>
@@ -85,6 +85,10 @@ npx postgresai checkup --check-id H002 postgresql://...
 npx postgresai checkup --no-upload --check-id H002 postgresql://...
 ```
 
+Markdown conversion is performed by the PostgresAI API and transmits the full
+report JSON. Therefore, `--markdown` cannot be combined with `--no-upload`. For
+local-only output, use `--json` or `--output` instead.
+
 > **Tips:** `npx pgai checkup` also works. `bunx postgresai` if you prefer Bun.
 
 ## Full monitoring stack

cli/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.

cli/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) {

cli/test/checkup.integration.test.ts

@@ -410,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);
-  });
 });

cli/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}`,