postgresai 0.14.0-beta.14 → 0.14.0-beta.16

package/bin/postgres-ai.ts

@@ -20,7 +20,9 @@ import { maskSecret } from "../lib/util";
 import { createInterface } from "readline";
 import * as childProcess from "child_process";
 import { REPORT_GENERATORS, CHECK_INFO, generateAllReports } from "../lib/checkup";
-import { createCheckupReport, uploadCheckupReportJson, RpcError, formatRpcErrorForDisplay, withRetry } from "../lib/checkup-api";
+import { getCheckupEntry } from "../lib/checkup-dictionary";
+import { createCheckupReport, uploadCheckupReportJson, convertCheckupReportJsonToMarkdown, RpcError, formatRpcErrorForDisplay, withRetry } from "../lib/checkup-api";
+import { generateCheckSummary } from "../lib/checkup-summary";
 
 // Singleton readline interface for stdin prompts
 let rl: ReturnType<typeof createInterface> | null = null;
@@ -183,6 +185,7 @@ interface CheckupOptions {
   upload?: boolean;
   project?: string;
   json?: boolean;
+  markdown?: boolean;
 }
 
 interface UploadConfig {
@@ -294,7 +297,6 @@ async function uploadCheckupReports(
   );
 
   const reportId = created.reportId;
-  logUpload(`Created remote checkup report: ${reportId}`);
 
   const uploaded: Array<{ checkId: string; filename: string; chunkId: number }> = [];
   for (const [checkId, report] of Object.entries(reports)) {
@@ -317,7 +319,6 @@ async function uploadCheckupReports(
     );
     uploaded.push({ checkId, filename: `${checkId}.json`, chunkId: r.reportChunkId });
   }
-  logUpload("Upload completed");
 
   return { project: uploadCfg.project, reportId, uploaded };
 }
@@ -339,7 +340,8 @@ function writeReportFiles(reports: Record<string, any>, outputPath: string): voi
 function printUploadSummary(
   summary: UploadSummary,
   projectWasGenerated: boolean,
-  useStderr: boolean
+  useStderr: boolean,
+  reports: Record<string, any>
 ): void {
   const out = useStderr ? console.error : console.log;
   out("\nCheckup report uploaded");
@@ -350,11 +352,38 @@ function printUploadSummary(
     out(`Project: ${summary.project}`);
   }
   out(`Report ID: ${summary.reportId}`);
-  out("View in Console: console.postgres.ai → Support → checkup reports");
+  out("View in Console: console.postgres.ai → Checkup → checkup reports");
   out("");
-  out("Files:");
+
+  // Show check summaries (filter out generic info messages)
+  const summaries = [];
+  let skippedCount = 0;
+
   for (const item of summary.uploaded) {
-    out(`- ${item.checkId}: ${item.filename}`);
+    const report = reports[item.checkId];
+    if (report) {
+      const { status, message } = generateCheckSummary(item.checkId, report);
+      const title = report.checkTitle || item.checkId;
+
+      // Show if: warning/ok status, or info with concrete data (contains numbers or version info)
+      const isSignificant = status !== 'info' || /\d/.test(message) || message.includes('PostgreSQL') || message.includes('Version');
+
+      if (isSignificant) {
+        summaries.push({ checkId: item.checkId, title, status, message });
+      } else {
+        skippedCount++;
+      }
+    }
+  }
+
+  // Print significant checks
+  for (const { checkId, title, message } of summaries) {
+    out(`  ${checkId} (${title}): ${message}`);
+  }
+
+  // Show count of other checks
+  if (skippedCount > 0) {
+    out(`  ${skippedCount} other check${skippedCount > 1 ? 's' : ''} completed`);
   }
 }
 
@@ -757,7 +786,7 @@ program
 
       const supabaseClient = new SupabaseClient(supabaseConfig);
 
-      // Fetch database URL for JSON output (non-blocking, best-effort)
+      // Fetch database URL for JSON output (best-effort, errors return null)
       let databaseUrl: string | null = null;
       if (jsonOutput) {
         databaseUrl = await fetchPoolerDatabaseUrl(supabaseConfig, opts.monitoringUser);
@@ -1642,17 +1671,19 @@ program
   });
 
 program
-  .command("checkup [conn]")
+  .command("checkup [checkIdOrConn] [conn]")
   .description("generate health check reports directly from PostgreSQL (express mode)")
-  .option("--check-id <id>", `specific check to run: ${Object.keys(CHECK_INFO).join(", ")}, or ALL`, "ALL")
+  .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("--[no-]upload", "upload JSON results to PostgresAI (default: enabled; requires API key)", undefined)
+  .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 (implies --no-upload)")
+  .option("--json", "output JSON to stdout")
+  .option("--markdown", "output markdown to stdout")
   .addHelpText(
     "after",
     [
@@ -1662,15 +1693,44 @@ program
       "",
       "Examples:",
       "  postgresai checkup postgresql://user:pass@host:5432/db",
-      "  postgresai checkup postgresql://user:pass@host:5432/db --check-id A003",
+      "  postgresai checkup H002 postgresql://user:pass@host:5432/db",
+      "  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 --project my_project",
-      "  postgresai set-default-project my_project",
-      "  postgresai checkup postgresql://user:pass@host:5432/db",
       "  postgresai checkup postgresql://user:pass@host:5432/db --no-upload --json",
+      "  postgresai checkup postgresql://user:pass@host:5432/db --no-upload --markdown",
     ].join("\n")
   )
-  .action(async (conn: string | undefined, opts: CheckupOptions, cmd: Command) => {
+  .action(async (checkIdOrConn: string | undefined, connArg: string | undefined, opts: CheckupOptions, cmd: Command) => {
+    // Support both syntaxes:
+    //   pgai checkup postgresql://...              -> run ALL checks
+    //   pgai checkup H002 postgresql://...         -> run specific check (positional)
+    //   pgai checkup --check-id H002 postgresql:// -> run specific check (option)
+    const checkIdPattern = /^[A-Z]\d{3}$/i;
+    let conn: string | undefined;
+    let checkId: string;
+
+    if (!checkIdOrConn) {
+      cmd.outputHelp();
+      process.exitCode = 1;
+      return;
+    }
+
+    if (checkIdPattern.test(checkIdOrConn)) {
+      // First arg is a check ID
+      checkId = checkIdOrConn.toUpperCase();
+      conn = connArg;
+      if (!conn) {
+        console.error(`Error: Connection string required when specifying check ID "${checkId}"`);
+        console.error(`\nUsage: postgresai checkup ${checkId} postgresql://user@host:5432/dbname\n`);
+        process.exitCode = 1;
+        return;
+      }
+    } else {
+      // First arg is the connection string
+      conn = checkIdOrConn;
+      checkId = opts.checkId?.toUpperCase() || "ALL";
+    }
+
     if (!conn) {
       cmd.outputHelp();
       process.exitCode = 1;
@@ -1678,8 +1738,18 @@ program
     }
 
     const shouldPrintJson = !!opts.json;
+    const shouldConvertMarkdown = !!opts.markdown;
     const uploadExplicitlyRequested = opts.upload === true;
-    const uploadExplicitlyDisabled = opts.upload === false || shouldPrintJson;
+
+    // Validate mutually exclusive flags
+    if (shouldPrintJson && shouldConvertMarkdown) {
+      console.error("Error: --json and --markdown are mutually exclusive");
+      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;
     let shouldUpload = !uploadExplicitlyDisabled;
 
     // Preflight: validate/create output directory BEFORE connecting / running checks.
@@ -1706,7 +1776,8 @@ program
       envPassword: process.env.PGPASSWORD,
     });
     let client: Client | undefined;
-    const spinnerEnabled = !!process.stdout.isTTY && shouldUpload;
+    // Show spinner when output is to TTY (not redirected) and not in JSON mode
+    const spinnerEnabled = !!process.stdout.isTTY && !shouldPrintJson;
     const spinner = createTtySpinner(spinnerEnabled, "Connecting to Postgres");
 
     try {
@@ -1716,17 +1787,23 @@ program
 
       // Generate reports
       let reports: Record<string, any>;
-      if (opts.checkId === "ALL") {
+      if (checkId === "ALL") {
         reports = await generateAllReports(client, opts.nodeName, (p) => {
           spinner.update(`Running ${p.checkId}: ${p.checkTitle} (${p.index}/${p.total})`);
         });
       } else {
-        const checkId = opts.checkId.toUpperCase();
         const generator = REPORT_GENERATORS[checkId];
         if (!generator) {
           spinner.stop();
-          console.error(`Unknown check ID: ${opts.checkId}`);
-          console.error(`Available: ${Object.keys(CHECK_INFO).join(", ")}, ALL`);
+          // Check if it's a valid check ID from the dictionary (just not implemented in express mode)
+          const dictEntry = getCheckupEntry(checkId);
+          if (dictEntry) {
+            console.error(`Check ${checkId} (${dictEntry.title}) is not yet available in express mode.`);
+            console.error(`Express-mode checks: ${Object.keys(CHECK_INFO).join(", ")}`);
+          } else {
+            console.error(`Unknown check ID: ${checkId}`);
+            console.error(`See 'postgresai checkup --help' for available checks.`);
+          }
           process.exitCode = 1;
           return;
         }
@@ -1752,13 +1829,133 @@ program
 
       // Print upload summary
       if (uploadSummary) {
-        printUploadSummary(uploadSummary, projectWasGenerated, shouldPrintJson);
+        printUploadSummary(uploadSummary, projectWasGenerated, shouldPrintJson || shouldConvertMarkdown, reports);
+      }
+
+      // Convert to markdown if requested
+      if (shouldConvertMarkdown) {
+        let apiKey: string;
+        let apiBaseUrl: string;
+
+        try {
+          const configResult = getConfig(rootOpts);
+          apiKey = configResult.apiKey;
+          const cfg = config.readConfig();
+          apiBaseUrl = resolveBaseUrls(rootOpts, cfg).apiBaseUrl;
+        } catch (error) {
+          spinner.stop();
+          console.error("Error: Failed to read configuration for markdown conversion");
+          console.error(error instanceof Error ? error.message : String(error));
+          process.exitCode = 1;
+          return;
+        }
+
+        // NOTE: apiKey can be empty - this is intentional. The API will return:
+        // - Without API key: Partial markdown with observations only (limited functionality)
+        // - With API key: Full markdown reports with all details
+        // This allows users to get basic insights without requiring authentication.
+
+        const markdownResults: Array<{ checkId: string; markdown?: string; error?: Error }> = [];
+
+        for (const [checkId, report] of Object.entries(reports)) {
+          try {
+            spinner.update(`Converting ${checkId} to markdown`);
+
+            // For reports that share JSON files (e.g., A002/A013 share a002.json,
+            // A003/D001/G003/F001 share a003.json), pass checkId as report_type
+            // so the API can generate the correct markdown variant
+            const markdownResult = await convertCheckupReportJsonToMarkdown({
+              apiKey,
+              apiBaseUrl,
+              checkId,
+              jsonPayload: report,
+              reportType: checkId,
+            });
+
+            // Extract markdown from response structure
+            // API returns: { reports: [{ markdown: "...", ... }], ... }
+            const markdown = markdownResult?.reports?.[0]?.markdown || markdownResult?.markdown;
+
+            markdownResults.push({
+              checkId,
+              markdown,
+            });
+          } catch (error) {
+            markdownResults.push({
+              checkId,
+              error: error instanceof Error ? error : new Error(String(error)),
+            });
+          }
+        }
+
+        spinner.stop();
+
+        // Output all markdown results
+        for (const result of markdownResults) {
+          if (result.error) {
+            if (result.error instanceof RpcError) {
+              console.error(`Error converting ${result.checkId} to markdown:`);
+              for (const line of formatRpcErrorForDisplay(result.error)) {
+                console.error(line);
+              }
+            } else {
+              console.error(`Error converting ${result.checkId} to markdown: ${result.error.message}`);
+            }
+          } else if (result.markdown) {
+            console.log(result.markdown);
+            if (!result.markdown.endsWith('\n')) {
+              console.log();
+            }
+          } else {
+            console.error(`Warning: No markdown content returned for ${result.checkId}`);
+          }
+        }
       }
 
       // Output JSON to stdout
-      if (shouldPrintJson || (!shouldUpload && !opts.output)) {
+      if (shouldPrintJson) {
         console.log(JSON.stringify(reports, null, 2));
       }
+
+      // If no output was produced, show summary
+      const hadOutput = shouldPrintJson || shouldConvertMarkdown || outputPath || uploadSummary;
+      if (!hadOutput) {
+        const checkCount = Object.keys(reports).length;
+        console.log(`Checkup completed: ${checkCount} check${checkCount > 1 ? 's' : ''}\n`);
+
+        // Collect and filter summaries
+        const summaries = [];
+        let skippedCount = 0;
+
+        for (const [checkId, report] of Object.entries(reports)) {
+          const { status, message } = generateCheckSummary(checkId, report);
+          const title = report.checkTitle || checkId;
+
+          // Show if: warning/ok status, or info with concrete data (contains numbers or version info)
+          const isSignificant = status !== 'info' || /\d/.test(message) || message.includes('PostgreSQL') || message.includes('Version');
+
+          if (isSignificant) {
+            summaries.push({ checkId, title, status, message });
+          } else {
+            skippedCount++;
+          }
+        }
+
+        // Print significant checks
+        for (const { checkId, title, message } of summaries) {
+          console.log(`  ${checkId} (${title}): ${message}`);
+        }
+
+        // Show count of other checks
+        if (skippedCount > 0) {
+          console.log(`  ${skippedCount} other check${skippedCount > 1 ? 's' : ''} completed`);
+        }
+
+        console.log('\nFor details:');
+        console.log('  --json          Output JSON');
+        console.log('  --markdown      Output markdown');
+        console.log('  --output <dir>  Save to directory');
+      }
     } catch (error) {
       if (error instanceof RpcError) {
         for (const line of formatRpcErrorForDisplay(error)) {
@@ -1824,7 +2021,8 @@ async function resolveOrInitPaths(): Promise<PathResolution> {
  */
 function isDockerRunning(): boolean {
   try {
-    const result = spawnSync("docker", ["info"], { stdio: "pipe", timeout: 5000 });
+    // Note: timeout is supported by Bun but not in @types/bun
+    const result = spawnSync("docker", ["info"], { stdio: "pipe", timeout: 5000 } as Parameters<typeof spawnSync>[2]);
     return result.status === 0;
   } catch {
     return false;
@@ -1836,7 +2034,7 @@ function isDockerRunning(): boolean {
  */
 function getComposeCmd(): string[] | null {
   const tryCmd = (cmd: string, args: string[]): boolean =>
-    spawnSync(cmd, args, { stdio: "ignore", timeout: 5000 }).status === 0;
+    spawnSync(cmd, args, { stdio: "ignore", timeout: 5000 } as Parameters<typeof spawnSync>[2]).status === 0;
   if (tryCmd("docker-compose", ["version"])) return ["docker-compose"];
   if (tryCmd("docker", ["compose", "version"])) return ["docker", "compose"];
   return null;
@@ -1850,7 +2048,7 @@ function checkRunningContainers(): { running: boolean; containers: string[] } {
     const result = spawnSync(
       "docker",
       ["ps", "--filter", "name=grafana-with-datasources", "--filter", "name=pgwatch", "--format", "{{.Names}}"],
-      { stdio: "pipe", encoding: "utf8", timeout: 5000 }
+      { stdio: "pipe", encoding: "utf8", timeout: 5000 } as Parameters<typeof spawnSync>[2]
     );
 
     if (result.status === 0 && result.stdout) {

package/bun.lock

@@ -11,12 +11,12 @@
         "pg": "^8.16.3",
       },
       "devDependencies": {
-        "@types/bun": "^1.1.14",
+        "@types/bun": "^1.3.6",
         "@types/js-yaml": "^4.0.9",
         "@types/pg": "^8.15.6",
         "ajv": "^8.17.1",
         "ajv-formats": "^3.0.1",
-        "typescript": "^5.3.3",
+        "typescript": "^5.9.3",
       },
     },
   },
@@ -25,7 +25,7 @@
 
     "@modelcontextprotocol/sdk": ["@modelcontextprotocol/sdk@1.25.1", "", { "dependencies": { "@hono/node-server": "^1.19.7", "ajv": "^8.17.1", "ajv-formats": "^3.0.1", "content-type": "^1.0.5", "cors": "^2.8.5", "cross-spawn": "^7.0.5", "eventsource": "^3.0.2", "eventsource-parser": "^3.0.0", "express": "^5.0.1", "express-rate-limit": "^7.5.0", "jose": "^6.1.1", "json-schema-typed": "^8.0.2", "pkce-challenge": "^5.0.0", "raw-body": "^3.0.0", "zod": "^3.25 || ^4.0", "zod-to-json-schema": "^3.25.0" }, "peerDependencies": { "@cfworker/json-schema": "^4.1.1", "zod": "^3.25 || ^4.0" }, "optionalPeers": ["@cfworker/json-schema"] }, "sha512-yO28oVFFC7EBoiKdAn+VqRm+plcfv4v0xp6osG/VsCB0NlPZWi87ajbCZZ8f/RvOFLEu7//rSRmuZZ7lMoe3gQ=="],
 
-    "@types/bun": ["@types/bun@1.3.5", "", { "dependencies": { "bun-types": "1.3.5" } }, "sha512-RnygCqNrd3srIPEWBd5LFeUYG7plCoH2Yw9WaZGyNmdTEei+gWaHqydbaIRkIkcbXwhBT94q78QljxN0Sk838w=="],
+    "@types/bun": ["@types/bun@1.3.6", "", { "dependencies": { "bun-types": "1.3.6" } }, "sha512-uWCv6FO/8LcpREhenN1d1b6fcspAB+cefwD7uti8C8VffIv0Um08TKMn98FynpTiU38+y2dUO55T11NgDt8VAA=="],
 
     "@types/js-yaml": ["@types/js-yaml@4.0.9", "", {}, "sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg=="],
 
@@ -43,7 +43,7 @@
 
     "body-parser": ["body-parser@2.2.1", "", { "dependencies": { "bytes": "^3.1.2", "content-type": "^1.0.5", "debug": "^4.4.3", "http-errors": "^2.0.0", "iconv-lite": "^0.7.0", "on-finished": "^2.4.1", "qs": "^6.14.0", "raw-body": "^3.0.1", "type-is": "^2.0.1" } }, "sha512-nfDwkulwiZYQIGwxdy0RUmowMhKcFVcYXUU7m4QlKYim1rUtg83xm2yjZ40QjDuc291AJjjeSc9b++AWHSgSHw=="],
 
-    "bun-types": ["bun-types@1.3.5", "", { "dependencies": { "@types/node": "*" } }, "sha512-inmAYe2PFLs0SUbFOWSVD24sg1jFlMPxOjOSSCYqUgn4Hsc3rDc7dFvfVYjFPNHtov6kgUeulV4SxbuIV/stPw=="],
+    "bun-types": ["bun-types@1.3.6", "", { "dependencies": { "@types/node": "*" } }, "sha512-OlFwHcnNV99r//9v5IIOgQ9Uk37gZqrNMCcqEaExdkVq3Avwqok1bJFmvGMCkCE0FqzdY8VMOZpfpR3lwI+CsQ=="],
 
     "bytes": ["bytes@3.1.2", "", {}, "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg=="],