postgresai 0.16.0-dev.1 → 0.16.0-dev.3

package/sql/06.helpers.sql

@@ -2,126 +2,6 @@
 -- These functions use SECURITY DEFINER to allow the monitoring user to perform
 -- operations they don't have direct permissions for.
 
-/*
- * explain_generic
- *
- * Function to get generic explain plans with optional HypoPG index testing.
- * Requires: PostgreSQL 16+ (for generic_plan option), HypoPG extension (optional).
- *
- * Security notes:
- * - EXPLAIN without ANALYZE is read-only (plans but doesn't execute the query)
- * - PostgreSQL's EXPLAIN only accepts a single statement (primary protection)
- * - Input validation uses a simple heuristic to detect multiple statements
- *   (Note: may reject valid queries containing semicolons in string literals)
- *
- * Usage examples:
- *   -- Basic generic plan
- *   select postgres_ai.explain_generic('select * from users where id = $1');
- *
- *   -- JSON format
- *   select postgres_ai.explain_generic('select * from users where id = $1', 'json');
- *
- *   -- Test a hypothetical index
- *   select postgres_ai.explain_generic(
- *     'select * from users where email = $1',
- *     'text',
- *     'create index on users (email)'
- *   );
- */
-create or replace function postgres_ai.explain_generic(
-  in query text,
-  in format text default 'text',
-  in hypopg_index text default null,
-  out result text
-)
-language plpgsql
-security definer
-set search_path = pg_catalog, public
-as $$
-declare
-  v_line record;
-  v_lines text[] := '{}';
-  v_explain_query text;
-  v_hypo_result record;
-  v_version int;
-  v_hypopg_available boolean;
-  v_clean_query text;
-begin
-  -- Check PostgreSQL version (generic_plan requires 16+)
-  select current_setting('server_version_num')::int into v_version;
-
-  if v_version < 160000 then
-    raise exception 'generic_plan requires PostgreSQL 16+, current version: %',
-      current_setting('server_version');
-  end if;
-
-  -- Input validation: reject empty queries
-  if query is null or trim(query) = '' then
-    raise exception 'query cannot be empty';
-  end if;
-
-  -- Input validation: detect multiple statements (defense-in-depth)
-  -- Note: This is a simple heuristic - EXPLAIN itself only accepts single statements
-  -- Limitation: Queries with semicolons inside string literals will be rejected
-  v_clean_query := trim(query);
-  if v_clean_query like '%;%' then
-    -- Strip trailing semicolon if present (common user convenience)
-    v_clean_query := regexp_replace(v_clean_query, ';\s*$', '');
-    -- If there's still a semicolon, reject (likely multiple statements or semicolon in string)
-    if v_clean_query like '%;%' then
-      raise exception 'query contains semicolon (multiple statements not allowed; note: semicolons in string literals are also not supported)';
-    end if;
-  end if;
-
-  -- Check if HypoPG extension is available
-  if hypopg_index is not null then
-    select exists(
-      select 1 from pg_extension where extname = 'hypopg'
-    ) into v_hypopg_available;
-
-    if not v_hypopg_available then
-      raise exception 'HypoPG extension is required for hypothetical index testing but is not installed';
-    end if;
-
-    -- Create hypothetical index
-    select * into v_hypo_result from hypopg_create_index(hypopg_index);
-    raise notice 'Created hypothetical index: % (oid: %)',
-      v_hypo_result.indexname, v_hypo_result.indexrelid;
-  end if;
-
-  -- Build and execute EXPLAIN query
-  -- Note: EXPLAIN is read-only (plans but doesn't execute), making this safe
-  begin
-    if lower(format) = 'json' then
-      execute 'explain (verbose, settings, generic_plan, format json) ' || v_clean_query
-        into result;
-    else
-      for v_line in execute 'explain (verbose, settings, generic_plan) ' || v_clean_query loop
-        v_lines := array_append(v_lines, v_line."QUERY PLAN");
-      end loop;
-      result := array_to_string(v_lines, e'\n');
-    end if;
-  exception when others then
-    -- Clean up hypothetical index before re-raising
-    if hypopg_index is not null then
-      perform hypopg_reset();
-    end if;
-    raise;
-  end;
-
-  -- Clean up hypothetical index
-  if hypopg_index is not null then
-    perform hypopg_reset();
-  end if;
-end;
-$$;
-
-comment on function postgres_ai.explain_generic(text, text, text) is
-  'Returns generic EXPLAIN plan with optional HypoPG index testing (requires PG16+)';
-
--- Grant execute to the monitoring user
-grant execute on function postgres_ai.explain_generic(text, text, text) to {{ROLE_IDENT}};
-
 /*
  * table_describe
  *
@@ -435,5 +315,3 @@ comment on function postgres_ai.table_describe(text) is
   'Returns comprehensive table information in compact text format for LLM analysis';
 
 grant execute on function postgres_ai.table_describe(text) to {{ROLE_IDENT}};
-
-

package/test/dblab.cli.test.ts

@@ -0,0 +1,339 @@
+import { describe, test, expect } from "bun:test";
+import { resolve } from "path";
+import { mkdtempSync } from "fs";
+import { tmpdir } from "os";
+
+function runCli(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 result = Bun.spawnSync([bunBin, cliPath, ...args], {
+    env: { ...process.env, ...env },
+  });
+  return {
+    status: result.exitCode,
+    stdout: new TextDecoder().decode(result.stdout),
+    stderr: new TextDecoder().decode(result.stderr),
+  };
+}
+
+// Async spawn — MUST be used for any test that hits the in-process fake server:
+// Bun.spawnSync would block this process's event loop, so the fake `Bun.serve`
+// could never answer the subprocess's request (deadlock).
+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 };
+}
+
+function isolatedEnv(extra: Record<string, string> = {}) {
+  const cfgHome = mkdtempSync(resolve(tmpdir(), "postgresai-dblab-test-"));
+  return { XDG_CONFIG_HOME: cfgHome, HOME: cfgHome, ...extra };
+}
+
+interface Recorded {
+  method: string;
+  pathname: string;
+  search: string;
+  bodyJson: any | null;
+}
+
+/**
+ * Fake Platform API: serves the `/dblab_instances` resolver listing and echoes
+ * every `/rpc/dblab_api_call` proxy call so tests can assert the action/method/
+ * payload the CLI produced.
+ */
+async function startFakeApi(instances?: unknown[]) {
+  const requests: Recorded[] = [];
+  const rows = instances ?? [
+    { id: 7, project_id: 12, project_name: "Main DB", project_alias: "main-db", project_label_or_name: "Main DB" },
+  ];
+
+  const server = Bun.serve({
+    hostname: "127.0.0.1",
+    port: 0,
+    async fetch(req) {
+      const url = new URL(req.url);
+      const bodyText = req.method === "POST" ? await req.text() : "";
+      let bodyJson: any | null = null;
+      try { bodyJson = bodyText ? JSON.parse(bodyText) : null; } catch { bodyJson = null; }
+      requests.push({ method: req.method, pathname: url.pathname, search: url.search, bodyJson });
+
+      if (req.method === "GET" && url.pathname.endsWith("/dblab_instances")) {
+        return new Response(JSON.stringify(rows), { status: 200, headers: { "Content-Type": "application/json" } });
+      }
+      if (req.method === "POST" && url.pathname.endsWith("/rpc/dblab_api_call")) {
+        // Echo a plausible reply keyed off the action.
+        const action = String(bodyJson?.action ?? "");
+        const reply = action === "/clones" || action.startsWith("/branches") || action.startsWith("/snapshots") || action.endsWith("/log")
+          ? []
+          : { instance_id: bodyJson?.instance_id, action, method: bodyJson?.method, ok: true };
+        return new Response(JSON.stringify(reply), { status: 200, headers: { "Content-Type": "application/json" } });
+      }
+      return new Response("not found", { status: 404 });
+    },
+  });
+
+  const baseUrl = `http://${server.hostname}:${server.port}/api/general`;
+  return {
+    baseUrl,
+    requests,
+    proxyCalls: () => requests.filter((r) => r.pathname.endsWith("/rpc/dblab_api_call")),
+    resolverCalls: () => requests.filter((r) => r.pathname.endsWith("/dblab_instances")),
+    stop: () => server.stop(true),
+  };
+}
+
+describe("CLI DBLab companion command groups", () => {
+  test("top-level help lists clone, branch, and snapshot groups", () => {
+    const r = runCli(["--help"], isolatedEnv());
+    const out = `${r.stdout}\n${r.stderr}`;
+    expect(out).toContain("clone");
+    expect(out).toContain("branch");
+    expect(out).toContain("snapshot");
+  });
+
+  test("clone help exposes create/list/status/reset/destroy", () => {
+    const r = runCli(["clone", "--help"], isolatedEnv());
+    expect(r.status).toBe(0);
+    const out = `${r.stdout}\n${r.stderr}`;
+    expect(out).toContain("create");
+    expect(out).toContain("list");
+    expect(out).toContain("status");
+    expect(out).toContain("reset");
+    expect(out).toContain("destroy");
+  });
+
+  test("branch help exposes list/create/delete/log", () => {
+    const r = runCli(["branch", "--help"], isolatedEnv());
+    expect(r.status).toBe(0);
+    const out = `${r.stdout}\n${r.stderr}`;
+    expect(out).toContain("list");
+    expect(out).toContain("create");
+    expect(out).toContain("delete");
+    expect(out).toContain("log");
+  });
+
+  test("snapshot help exposes list/create/destroy", () => {
+    const r = runCli(["snapshot", "--help"], isolatedEnv());
+    expect(r.status).toBe(0);
+    const out = `${r.stdout}\n${r.stderr}`;
+    expect(out).toContain("list");
+    expect(out).toContain("create");
+    expect(out).toContain("destroy");
+  });
+
+  test("clone create fails fast without an API key", () => {
+    const r = runCli(["clone", "create", "--project", "main-db"], isolatedEnv());
+    expect(r.status).toBe(1);
+    expect(`${r.stdout}\n${r.stderr}`).toContain("API key is required");
+  });
+
+  test("clone list without --project errors", () => {
+    const r = runCli(["clone", "list"], isolatedEnv({ PGAI_API_KEY: "test-key" }));
+    expect(r.status).not.toBe(0);
+    expect(`${r.stdout}\n${r.stderr}`.toLowerCase()).toContain("project");
+  });
+
+  test("clone create resolves the alias then proxies /clone POST", async () => {
+    const api = await startFakeApi();
+    try {
+      const r = await runCliAsync(
+        ["clone", "create", "--project", "main-db", "--json"],
+        isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
+      );
+      expect(r.status).toBe(0);
+      // The resolver GET happened.
+      expect(api.resolverCalls().length).toBe(1);
+      // Exactly one proxy call, with the right action/method/instance.
+      const proxied = api.proxyCalls();
+      expect(proxied.length).toBe(1);
+      expect(proxied[0].bodyJson.instance_id).toBe("7");
+      expect(proxied[0].bodyJson.action).toBe("/clone");
+      expect(proxied[0].bodyJson.method).toBe("post");
+      expect(proxied[0].bodyJson.data).toEqual({ protected: false });
+    } finally {
+      api.stop();
+    }
+  });
+
+  test("clone create maps branch/snapshot/protected into the payload", async () => {
+    const api = await startFakeApi();
+    try {
+      const r = await runCliAsync(
+        ["clone", "create", "--project", "main-db", "--branch", "feature-idx", "--snapshot", "s-9", "--protected", "--json"],
+        isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
+      );
+      expect(r.status).toBe(0);
+      const body = api.proxyCalls()[0].bodyJson;
+      expect(body.data).toEqual({ protected: true, branch: "feature-idx", snapshot: { id: "s-9" } });
+    } finally {
+      api.stop();
+    }
+  });
+
+  test("clone reset proxies /clone/<id>/reset POST", async () => {
+    const api = await startFakeApi();
+    try {
+      const r = await runCliAsync(
+        ["clone", "reset", "c-8f21", "--project", "main-db", "--json"],
+        isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
+      );
+      expect(r.status).toBe(0);
+      const body = api.proxyCalls()[0].bodyJson;
+      expect(body.action).toBe("/clone/c-8f21/reset");
+      expect(body.method).toBe("post");
+      expect(body.data).toEqual({ latest: true });
+    } finally {
+      api.stop();
+    }
+  });
+
+  test("clone destroy proxies /clone/<id> DELETE and resolves a numeric project id", async () => {
+    const api = await startFakeApi();
+    try {
+      const r = await runCliAsync(
+        ["clone", "destroy", "c-8f21", "--project", "12", "--json"],
+        isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
+      );
+      expect(r.status).toBe(0);
+      const body = api.proxyCalls()[0].bodyJson;
+      expect(body.instance_id).toBe("7"); // resolved from project_id 12
+      expect(body.action).toBe("/clone/c-8f21");
+      expect(body.method).toBe("delete");
+    } finally {
+      api.stop();
+    }
+  });
+
+  test("branch create proxies /branch POST with branchName + snapshotID", async () => {
+    const api = await startFakeApi();
+    try {
+      const r = await runCliAsync(
+        ["branch", "create", "feature-idx", "--project", "main-db", "--snapshot", "latest", "--json"],
+        isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
+      );
+      expect(r.status).toBe(0);
+      const body = api.proxyCalls()[0].bodyJson;
+      expect(body.action).toBe("/branch");
+      expect(body.method).toBe("post");
+      expect(body.data).toEqual({ branchName: "feature-idx", snapshotID: "latest" });
+    } finally {
+      api.stop();
+    }
+  });
+
+  test("branch log proxies /branch/<name>/log GET", async () => {
+    const api = await startFakeApi();
+    try {
+      const r = await runCliAsync(
+        ["branch", "log", "feature-idx", "--project", "main-db", "--json"],
+        isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
+      );
+      expect(r.status).toBe(0);
+      const body = api.proxyCalls()[0].bodyJson;
+      expect(body.action).toBe("/branch/feature-idx/log");
+      expect(body.method).toBe("get");
+    } finally {
+      api.stop();
+    }
+  });
+
+  test("snapshot list proxies /snapshots GET", async () => {
+    const api = await startFakeApi();
+    try {
+      const r = await runCliAsync(
+        ["snapshot", "list", "--project", "main-db", "--json"],
+        isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
+      );
+      expect(r.status).toBe(0);
+      const body = api.proxyCalls()[0].bodyJson;
+      expect(body.action).toBe("/snapshots");
+      expect(body.method).toBe("get");
+    } finally {
+      api.stop();
+    }
+  });
+
+  test("snapshot create proxies /branch/snapshot POST with cloneID", async () => {
+    const api = await startFakeApi();
+    try {
+      const r = await runCliAsync(
+        ["snapshot", "create", "--project", "main-db", "--clone", "c-8f21", "--message", "before idx", "--json"],
+        isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
+      );
+      expect(r.status).toBe(0);
+      const body = api.proxyCalls()[0].bodyJson;
+      expect(body.action).toBe("/branch/snapshot");
+      expect(body.data).toEqual({ cloneID: "c-8f21", message: "before idx" });
+    } finally {
+      api.stop();
+    }
+  });
+
+  test("snapshot destroy proxies /snapshot/<id>?force=<bool> DELETE", async () => {
+    const api = await startFakeApi();
+    try {
+      const r = await runCliAsync(
+        ["snapshot", "destroy", "s-1", "--project", "main-db", "--force", "--json"],
+        isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
+      );
+      expect(r.status).toBe(0);
+      const body = api.proxyCalls()[0].bodyJson;
+      expect(body.action).toBe("/snapshot/s-1?force=true");
+      expect(body.method).toBe("delete");
+    } finally {
+      api.stop();
+    }
+  });
+
+  test("an unknown project alias exits 1 with a helpful message (no proxy call)", async () => {
+    const api = await startFakeApi();
+    try {
+      const r = await runCliAsync(
+        ["clone", "list", "--project", "does-not-exist"],
+        isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: api.baseUrl })
+      );
+      expect(r.status).toBe(1);
+      expect(`${r.stdout}\n${r.stderr}`).toContain("No DBLab instance found");
+      expect(api.proxyCalls().length).toBe(0);
+    } finally {
+      api.stop();
+    }
+  });
+
+  test("a backend scope error (403) surfaces and exits 1", async () => {
+    // Fake server that 403s the proxy call to emulate a missing joe:admin scope.
+    const server = Bun.serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      async fetch(req) {
+        const url = new URL(req.url);
+        if (req.method === "GET" && url.pathname.endsWith("/dblab_instances")) {
+          return new Response(JSON.stringify([{ id: 7, project_id: 12, project_alias: "main-db" }]), { status: 200 });
+        }
+        return new Response('{"message":"insufficient scope: joe:admin required"}', { status: 403 });
+      },
+    });
+    try {
+      const baseUrl = `http://${server.hostname}:${server.port}/api/general`;
+      const r = await runCliAsync(
+        ["clone", "destroy", "c-1", "--project", "main-db"],
+        isolatedEnv({ PGAI_API_KEY: "test-key", PGAI_API_BASE_URL: baseUrl })
+      );
+      expect(r.status).toBe(1);
+      expect(`${r.stdout}\n${r.stderr}`).toContain("Failed to destroy clone");
+    } finally {
+      server.stop(true);
+    }
+  });
+});