postgresai 0.15.0-rc.8 → 0.16.0-dev.0

package/test/checkup.test.ts

@@ -42,6 +42,24 @@ function runCli(args: string[], env: Record<string, string> = {}) {
   };
 }
 
+// Async variant for tests that need an in-process fake API (Bun.serve):
+// spawnSync would block the event loop and the fake server could never respond.
+async function runCliAsync(args: string[], env: Record<string, string> = {}) {
+  const cliPath = resolve(import.meta.dir, "..", "bin", "postgres-ai.ts");
+  const bunBin = typeof process.execPath === "string" && process.execPath.length > 0 ? process.execPath : "bun";
+  const proc = Bun.spawn([bunBin, cliPath, ...args], {
+    env: { ...process.env, ...env },
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [status, stdout, stderr] = await Promise.all([
+    proc.exited,
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  return { status, stdout, stderr };
+}
+
 // Unit tests for parseVersionNum
 describe("parseVersionNum", () => {
   test("parses PG 16.3 version number", () => {
@@ -403,7 +421,11 @@ describe("Report generators with mock client", () => {
     expect(pg16MetricSql).toContain("sum(coalesce(extends, 0) * op_bytes)");
     expect(pg18MetricSql).toContain("sum(coalesce(read_bytes, 0))");
     expect(pg18MetricSql).toContain("sum(coalesce(extend_bytes, 0))");
-    expect(pg18MetricSql).toContain("sum(coalesce(writebacks, 0) * coalesce(op_bytes, 0))");
+    // PG18 removed op_bytes entirely; writeback bytes cannot be derived, so the SQL emits a constant 0.
+    expect(pg18MetricSql).toContain("0::int8 as writeback_bytes_mb");
+    // Regression guard: any op_bytes reference in the PG18 branch makes the whole query
+    // fail with `column "op_bytes" does not exist`, degrading all of I001.
+    expect(pg18MetricSql).not.toContain("op_bytes");
   });
 
   test("generateI001 returns unavailable on PostgreSQL 16 when ioStats are empty", async () => {
@@ -1237,6 +1259,186 @@ describe("H004 - Redundant indexes", () => {
   // Top-level structure tests removed - covered by schema-validation.test.ts
 });
 
+// Tests for F003 (Autovacuum: dead tuples)
+describe("F003 - Dead tuples", () => {
+  // The seeded UX-test case that F004 missed: 8.27M dead tuples,
+  // dead:live ratio 1.3:1 (dead_pct ~56.5%), autovacuum disabled via reloptions.
+  const seededProblemRow = {
+    tag_schemaname: "public",
+    tag_relname: "events",
+    n_live_tup: "6361538",
+    n_dead_tup: "8270000",
+    dead_pct: 56.52,
+    last_autovacuum: "0",
+    last_vacuum: "0",
+    autovacuum_count: "0",
+    vacuum_count: "0",
+    autovacuum_disabled: 1,
+    table_size_b: "2147483648",
+  };
+
+  test("getDeadTuples maps rows and computes flags", async () => {
+    const mockClient = createMockClient({ deadTuplesRows: [seededProblemRow] });
+
+    const tables = await checkup.getDeadTuples(mockClient as any);
+    expect(tables.length).toBe(1);
+    const t = tables[0];
+    expect(t.schema_name).toBe("public");
+    expect(t.table_name).toBe("events");
+    expect(t.n_live_tup).toBe(6361538);
+    expect(t.n_dead_tup).toBe(8270000);
+    expect(t.dead_pct).toBe(56.52);
+    expect(t.autovacuum_disabled).toBe(true);
+    expect(t.last_autovacuum).toBeNull();
+    expect(t.last_autovacuum_epoch).toBe(0);
+    expect(t.last_vacuum).toBeNull();
+    expect(t.table_size_bytes).toBe(2147483648);
+    expect(t.table_size_pretty).toBe("2.00 GiB");
+    expect(t.exceeds_dead_tuple_thresholds).toBe(true);
+    expect(t.autovacuum_disabled_flagged).toBe(true);
+  });
+
+  test("getDeadTuples converts non-zero vacuum epochs to ISO timestamps", async () => {
+    const mockClient = createMockClient({
+      deadTuplesRows: [{
+        ...seededProblemRow,
+        last_autovacuum: "1704067200", // 2024-01-01T00:00:00Z
+        last_vacuum: "1706745600", // 2024-02-01T00:00:00Z
+        autovacuum_count: "3",
+        vacuum_count: "1",
+        autovacuum_disabled: 0,
+      }],
+    });
+
+    const [t] = await checkup.getDeadTuples(mockClient as any);
+    expect(t.last_autovacuum).toBe("2024-01-01T00:00:00.000Z");
+    expect(t.last_autovacuum_epoch).toBe(1704067200);
+    expect(t.last_vacuum).toBe("2024-02-01T00:00:00.000Z");
+    expect(t.autovacuum_count).toBe(3);
+    expect(t.vacuum_count).toBe(1);
+    expect(t.autovacuum_disabled).toBe(false);
+  });
+
+  test("dead-tuple thresholds require BOTH absolute and relative excess", async () => {
+    const mockClient = createMockClient({
+      deadTuplesRows: [
+        // High count, low ratio (large healthy table churning under active autovacuum)
+        { ...seededProblemRow, tag_relname: "big_churn", n_live_tup: "100000000", n_dead_tup: "150000", dead_pct: 0.15, autovacuum_disabled: 0 },
+        // High ratio, low count (small table - not worth flagging)
+        { ...seededProblemRow, tag_relname: "tiny", n_live_tup: "100", n_dead_tup: "900", dead_pct: 90, autovacuum_disabled: 0 },
+        // Both high - must be flagged
+        { ...seededProblemRow, tag_relname: "problem", n_live_tup: "100000", n_dead_tup: "100000", dead_pct: 50, autovacuum_disabled: 0 },
+      ],
+    });
+
+    const tables = await checkup.getDeadTuples(mockClient as any);
+    const byName = new Map(tables.map((t) => [t.table_name, t]));
+    expect(byName.get("big_churn")!.exceeds_dead_tuple_thresholds).toBe(false);
+    expect(byName.get("tiny")!.exceeds_dead_tuple_thresholds).toBe(false);
+    expect(byName.get("problem")!.exceeds_dead_tuple_thresholds).toBe(true);
+  });
+
+  test("autovacuum disabled is flagged only on non-tiny tables", async () => {
+    const mockClient = createMockClient({
+      deadTuplesRows: [
+        { ...seededProblemRow, tag_relname: "tiny_disabled", n_live_tup: "50", n_dead_tup: "0", dead_pct: 0 },
+        { ...seededProblemRow, tag_relname: "big_disabled", n_live_tup: "20000", n_dead_tup: "0", dead_pct: 0 },
+      ],
+    });
+
+    const tables = await checkup.getDeadTuples(mockClient as any);
+    const byName = new Map(tables.map((t) => [t.table_name, t]));
+    expect(byName.get("tiny_disabled")!.autovacuum_disabled).toBe(true);
+    expect(byName.get("tiny_disabled")!.autovacuum_disabled_flagged).toBe(false);
+    expect(byName.get("big_disabled")!.autovacuum_disabled_flagged).toBe(true);
+  });
+
+  test("buildDeadTuplesConclusions produces concrete conclusions and recommendations", async () => {
+    const mockClient = createMockClient({ deadTuplesRows: [seededProblemRow] });
+    const tables = await checkup.getDeadTuples(mockClient as any);
+
+    const { conclusions, recommendations } = checkup.buildDeadTuplesConclusions(tables);
+    expect(conclusions.length).toBe(1);
+    expect(conclusions[0]).toContain('"public"."events"');
+    expect(conclusions[0]).toContain("8,270,000 dead tuples");
+    expect(conclusions[0]).toContain("56.52% of all tuples");
+    expect(conclusions[0]).toContain("autovacuum is disabled");
+    expect(conclusions[0]).toContain("never vacuumed");
+
+    expect(recommendations.length).toBe(1);
+    expect(recommendations[0]).toContain('alter table "public"."events" reset (autovacuum_enabled);');
+    expect(recommendations[0]).toContain('vacuum (analyze) "public"."events";');
+  });
+
+  test("buildDeadTuplesConclusions distinguishes vacuum-lag from disabled-autovacuum cases", async () => {
+    const mockClient = createMockClient({
+      deadTuplesRows: [
+        // Dead tuples high but autovacuum enabled -> vacuum + tuning advice
+        { ...seededProblemRow, tag_relname: "lagging", autovacuum_disabled: 0, last_autovacuum: "1704067200" },
+        // Autovacuum disabled, no dead tuples yet -> re-enable advice
+        { ...seededProblemRow, tag_relname: "disabled_only", n_live_tup: "50000", n_dead_tup: "0", dead_pct: 0 },
+      ],
+    });
+    const tables = await checkup.getDeadTuples(mockClient as any);
+
+    const { conclusions, recommendations } = checkup.buildDeadTuplesConclusions(tables);
+    expect(conclusions.length).toBe(2);
+    const laggingRec = recommendations.find((r) => r.includes('"public"."lagging"'))!;
+    expect(laggingRec).toContain("vacuum (analyze)");
+    expect(laggingRec).toContain("autovacuum_vacuum_scale_factor");
+    expect(laggingRec).not.toContain("reset (autovacuum_enabled)");
+
+    const disabledRec = recommendations.find((r) => r.includes('"public"."disabled_only"'))!;
+    expect(disabledRec).toContain('alter table "public"."disabled_only" reset (autovacuum_enabled);');
+  });
+
+  test("generateF003 creates report with counts, thresholds, and conclusions", async () => {
+    const mockClient = createMockClient({
+      deadTuplesRows: [
+        seededProblemRow,
+        { ...seededProblemRow, tag_relname: "disabled_only", n_live_tup: "50000", n_dead_tup: "0", dead_pct: 0 },
+      ],
+    });
+
+    const report = await checkup.REPORT_GENERATORS.F003(mockClient as any, "test-node");
+    expect(report.checkId).toBe("F003");
+    expect(report.checkTitle).toBe("Autovacuum: dead tuples");
+
+    const data = report.results["test-node"].data;
+    expect("testdb" in data).toBe(true);
+    const dbData = data["testdb"] as any;
+    expect(dbData.dead_tuples_tables.length).toBe(2);
+    expect(dbData.total_count).toBe(2);
+    expect(dbData.flagged_count).toBe(1);
+    expect(dbData.autovacuum_disabled_count).toBe(2);
+    expect(dbData.autovacuum_disabled_flagged_count).toBe(2);
+    expect(dbData.total_dead_tuples).toBe(8270000);
+    expect(dbData.thresholds).toEqual({
+      dead_tuples_min: checkup.F003_DEAD_TUPLES_MIN,
+      dead_pct_min: checkup.F003_DEAD_PCT_MIN,
+      autovacuum_disabled_min_rows: checkup.F003_AUTOVACUUM_DISABLED_MIN_ROWS,
+    });
+    expect(dbData.conclusions.length).toBe(2);
+    expect(dbData.recommendations.length).toBe(2);
+    expect(dbData.database_size_bytes).toBeTruthy();
+    expect(report.results["test-node"].postgres_version).toBeTruthy();
+  });
+
+  test("generateF003 handles a healthy database (no rows)", async () => {
+    const mockClient = createMockClient({ deadTuplesRows: [] });
+
+    const report = await checkup.REPORT_GENERATORS.F003(mockClient as any, "test-node");
+    const dbData = report.results["test-node"].data["testdb"] as any;
+    expect(dbData.dead_tuples_tables).toEqual([]);
+    expect(dbData.total_count).toBe(0);
+    expect(dbData.flagged_count).toBe(0);
+    expect(dbData.autovacuum_disabled_count).toBe(0);
+    expect(dbData.autovacuum_disabled_flagged_count).toBe(0);
+    expect(dbData.conclusions).toEqual([]);
+    expect(dbData.recommendations).toEqual([]);
+  });
+});
+
 // CLI tests
 describe("CLI tests", () => {
   test("checkup command exists and shows help", () => {
@@ -1452,6 +1654,113 @@ describe("CLI tests", () => {
   });
 });
 
+// CLI-level tests for the checkup auth pre-flight: missing/invalid credentials
+// must surface BEFORE checks run (previously the upload at the end of the run
+// was the first authenticated call, wasting minutes of work on a 401).
+describe("checkup auth pre-flight (CLI)", () => {
+  // Dead Postgres port: if the pre-flight correctly stops the run, the CLI
+  // never attempts this connection; if the run continues, the connection
+  // failure mentions this address.
+  const DEAD_DB = "postgresql://test:test@127.0.0.1:2/test";
+
+  test("no API key: prominent notice, run continues locally", () => {
+    const env = {
+      XDG_CONFIG_HOME: `/tmp/postgresai-test-preflight-nokey-${process.pid}`,
+      PGAI_API_KEY: "",
+    };
+    const r = runCli(["checkup", DEAD_DB], env);
+    expect(r.stderr).toMatch(/results will NOT be uploaded/i);
+    expect(r.stderr).toMatch(/auth login/);
+    expect(r.stderr).toMatch(/--no-upload/);
+    // Falls back to local-only mode instead of failing fast
+    expect(r.stderr).not.toMatch(/API key is required/i);
+    // Run continued to the database connection stage
+    expect(r.status).not.toBe(0);
+    expect(r.stderr).toMatch(/127\.0\.0\.1:2|ECONNREFUSED|connect/i);
+  });
+
+  test("--no-upload: no notice, pre-flight skipped entirely", () => {
+    const env = {
+      XDG_CONFIG_HOME: `/tmp/postgresai-test-preflight-noupload-${process.pid}`,
+      PGAI_API_KEY: "",
+    };
+    const r = runCli(["checkup", DEAD_DB, "--no-upload"], env);
+    expect(r.stderr).not.toMatch(/results will NOT be uploaded/i);
+    expect(r.stderr).not.toMatch(/could not verify API key/i);
+    expect(r.stderr).not.toMatch(/API key is required/i);
+  });
+
+  test("invalid API key (HTTP 401): fails fast before running checks", async () => {
+    const server = Bun.serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      fetch() {
+        return new Response(JSON.stringify({ message: "Invalid token" }), {
+          status: 401,
+          headers: { "Content-Type": "application/json" },
+        });
+      },
+    });
+    try {
+      const env = {
+        XDG_CONFIG_HOME: `/tmp/postgresai-test-preflight-badkey-${process.pid}`,
+        PGAI_API_KEY: "bad-token",
+        PGAI_API_BASE_URL: `http://127.0.0.1:${server.port}`,
+      };
+      const r = await runCliAsync(["checkup", DEAD_DB, "--project", "preflight-test"], env);
+      expect(r.status).not.toBe(0);
+      expect(r.stderr).toMatch(/rejected by the PostgresAI API \(HTTP 401\)/);
+      expect(r.stderr).toMatch(/auth login/);
+      expect(r.stderr).toMatch(/--no-upload/);
+      // Stopped BEFORE connecting to the database / running checks
+      expect(r.stderr).not.toMatch(/127\.0\.0\.1:2|ECONNREFUSED/);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("--no-upload skips pre-flight even when an invalid key is configured", async () => {
+    const server = Bun.serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      fetch() {
+        return new Response(JSON.stringify({ message: "Invalid token" }), {
+          status: 401,
+          headers: { "Content-Type": "application/json" },
+        });
+      },
+    });
+    try {
+      const env = {
+        XDG_CONFIG_HOME: `/tmp/postgresai-test-preflight-badkey-noupload-${process.pid}`,
+        PGAI_API_KEY: "bad-token",
+        PGAI_API_BASE_URL: `http://127.0.0.1:${server.port}`,
+      };
+      const r = await runCliAsync(["checkup", DEAD_DB, "--no-upload"], env);
+      expect(r.stderr).not.toMatch(/rejected by the PostgresAI API/);
+      expect(r.stderr).not.toMatch(/could not verify API key/i);
+      // Fails later at the database connection stage instead
+      expect(r.status).not.toBe(0);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("transient pre-flight failure (network error): warns and continues", () => {
+    const env = {
+      XDG_CONFIG_HOME: `/tmp/postgresai-test-preflight-netfail-${process.pid}`,
+      PGAI_API_KEY: "some-token",
+      PGAI_API_BASE_URL: "http://127.0.0.1:1", // connect refused — transient, not a 401/403
+    };
+    const r = runCli(["checkup", DEAD_DB, "--project", "preflight-test"], env);
+    expect(r.stderr).toMatch(/Warning: could not verify API key/i);
+    expect(r.stderr).not.toMatch(/rejected by the PostgresAI API/);
+    // Run continued to the database connection stage
+    expect(r.status).not.toBe(0);
+    expect(r.stderr).toMatch(/127\.0\.0\.1:2|ECONNREFUSED|connect/i);
+  });
+});
+
 // Tests for checkup-api module
 describe("checkup-api", () => {
   test("formatRpcErrorForDisplay formats details/hint nicely", () => {
@@ -1698,12 +2007,172 @@ describe("checkup-api", () => {
       }
     });
   });
+
+  // Auth pre-flight: verifyApiKey checks the key with a cheap authenticated
+  // GET before checkup runs expensive checks. Only definitive 401/403 is
+  // "invalid"; anything transient must come back "unknown" (warn + continue).
+  describe("verifyApiKey (auth pre-flight)", () => {
+    function serveStatus(status: number, body = "[]") {
+      return Bun.serve({
+        hostname: "127.0.0.1",
+        port: 0,
+        fetch() {
+          return new Response(body, { status, headers: { "Content-Type": "application/json" } });
+        },
+      });
+    }
+
+    test("returns valid on HTTP 200", async () => {
+      const server = serveStatus(200);
+      try {
+        const r = await api.verifyApiKey({ apiKey: "k", apiBaseUrl: `http://127.0.0.1:${server.port}` });
+        expect(r.status).toBe("valid");
+      } finally {
+        server.stop(true);
+      }
+    });
+
+    test("returns invalid on HTTP 401", async () => {
+      const server = serveStatus(401, JSON.stringify({ message: "Invalid token" }));
+      try {
+        const r = await api.verifyApiKey({ apiKey: "bad", apiBaseUrl: `http://127.0.0.1:${server.port}` });
+        expect(r.status).toBe("invalid");
+        expect((r as { statusCode: number }).statusCode).toBe(401);
+      } finally {
+        server.stop(true);
+      }
+    });
+
+    test("returns invalid on HTTP 403", async () => {
+      const server = serveStatus(403);
+      try {
+        const r = await api.verifyApiKey({ apiKey: "bad", apiBaseUrl: `http://127.0.0.1:${server.port}` });
+        expect(r.status).toBe("invalid");
+        expect((r as { statusCode: number }).statusCode).toBe(403);
+      } finally {
+        server.stop(true);
+      }
+    });
+
+    test("returns unknown on HTTP 500 (not a definitive rejection)", async () => {
+      const server = serveStatus(500);
+      try {
+        const r = await api.verifyApiKey({ apiKey: "k", apiBaseUrl: `http://127.0.0.1:${server.port}` });
+        expect(r.status).toBe("unknown");
+        expect((r as { detail: string }).detail).toMatch(/HTTP 500/);
+      } finally {
+        server.stop(true);
+      }
+    });
+
+    test("returns unknown on connection refused", async () => {
+      const r = await api.verifyApiKey({ apiKey: "k", apiBaseUrl: "http://127.0.0.1:1" }); // port 1 — connect refused
+      expect(r.status).toBe("unknown");
+    });
+
+    test("returns unknown on timeout", async () => {
+      const server = Bun.serve({
+        hostname: "127.0.0.1",
+        port: 0,
+        async fetch() {
+          await new Promise((resolve) => setTimeout(resolve, 5000));
+          return new Response("[]");
+        },
+      });
+      try {
+        const r = await api.verifyApiKey({
+          apiKey: "k",
+          apiBaseUrl: `http://127.0.0.1:${server.port}`,
+          timeoutMs: 100,
+        });
+        expect(r.status).toBe("unknown");
+      } finally {
+        server.stop(true);
+      }
+    });
+
+    test("does not send the key over plaintext HTTP to non-loopback hosts", async () => {
+      const saved = process.env.CHECKUP_ALLOW_HTTP;
+      delete process.env.CHECKUP_ALLOW_HTTP;
+      try {
+        const r = await api.verifyApiKey({ apiKey: "k", apiBaseUrl: "http://example.com/api" });
+        expect(r.status).toBe("unknown");
+        expect((r as { detail: string }).detail).toMatch(/plaintext HTTP/);
+      } finally {
+        if (saved !== undefined) process.env.CHECKUP_ALLOW_HTTP = saved;
+      }
+    });
+  });
 });
 
 // Tests for checkup-summary module
 describe("checkup-summary", () => {
   const summary = require("../lib/checkup-summary");
 
+  test("generateCheckSummary for F003 with no issues", () => {
+    const report = {
+      results: {
+        node1: {
+          data: {
+            db1: {
+              dead_tuples_tables: [],
+              total_count: 0,
+              flagged_count: 0,
+              autovacuum_disabled_count: 0,
+              autovacuum_disabled_flagged_count: 0,
+            },
+          },
+        },
+      },
+    };
+    const result = summary.generateCheckSummary("F003", report);
+    expect(result.status).toBe("ok");
+    expect(result.message).toMatch(/no significant dead tuple/i);
+  });
+
+  test("generateCheckSummary for F003 ignores tiny disabled-autovacuum tables", () => {
+    const report = {
+      results: {
+        node1: {
+          data: {
+            db1: {
+              dead_tuples_tables: [],
+              total_count: 2,
+              flagged_count: 0,
+              autovacuum_disabled_count: 2,
+              autovacuum_disabled_flagged_count: 0,
+            },
+          },
+        },
+      },
+    };
+    const result = summary.generateCheckSummary("F003", report);
+    expect(result.status).toBe("ok");
+  });
+
+  test("generateCheckSummary for F003 with problems", () => {
+    const report = {
+      results: {
+        node1: {
+          data: {
+            db1: {
+              dead_tuples_tables: [],
+              total_count: 3,
+              flagged_count: 1,
+              autovacuum_disabled_count: 2,
+              autovacuum_disabled_flagged_count: 2,
+            },
+          },
+        },
+      },
+    };
+    const result = summary.generateCheckSummary("F003", report);
+    expect(result.status).toBe("warning");
+    expect(result.message).toBe(
+      "1 table with excessive dead tuples, 2 tables with autovacuum disabled"
+    );
+  });
+
   test("generateCheckSummary for H001 with no issues", () => {
     const report = {
       results: {
@@ -3099,6 +3568,7 @@ describe("Version-aware SQL query selection (PG13-PG18)", () => {
       H001: "pg_invalid_indexes",
       H002: "unused_indexes",
       H004: "redundant_indexes",
+      F003: "pg_dead_tuples",
       F004: "pg_table_bloat",
       F005: "pg_btree_bloat",
       settings: "settings",

package/test/mcp-server.test.ts

@@ -238,6 +238,8 @@ describe("MCP Server", () => {
 
       expect(response.isError).toBe(true);
       expect(getResponseText(response)).toContain("401");
+      // Agent-facing remediation: invalid key must point at re-auth, not dead-end
+      expect(getResponseText(response)).toContain("Run 'postgresai auth'");
 
       readConfigSpy.mockRestore();
     });
@@ -1678,6 +1680,8 @@ describe("MCP Server", () => {
 
       expect(response.isError).toBe(true);
       expect(getResponseText(response)).toContain("401");
+      // Agent-facing remediation: invalid key must point at re-auth, not dead-end
+      expect(getResponseText(response)).toContain("Run 'postgresai auth'");
 
       readConfigSpy.mockRestore();
     });