postgresai 0.16.0-dev.1 → 0.16.0-dev.10

package/test/dblab.test.ts

@@ -0,0 +1,488 @@
+import { describe, test, expect, mock, afterEach, spyOn } from "bun:test";
+import {
+  resolveDblabInstanceId,
+  isNumericProjectRef,
+  createClone,
+  listClones,
+  getClone,
+  resetClone,
+  destroyClone,
+  listBranches,
+  createBranch,
+  deleteBranch,
+  branchLog,
+  listSnapshots,
+  createSnapshot,
+  destroySnapshot,
+} from "../lib/dblab";
+import { handleToolCall } from "../lib/mcp-server";
+
+const originalFetch = globalThis.fetch;
+const API = "https://api.example.com";
+
+interface Captured {
+  url: string;
+  options: RequestInit;
+}
+
+/** Stub fetch, returning `body` for every call, capturing the last request. */
+function stubFetch(body: unknown, status = 200): { get: () => Captured | null } {
+  let captured: Captured | null = null;
+  globalThis.fetch = mock((url: string, options: RequestInit) => {
+    captured = { url, options };
+    return Promise.resolve(
+      new Response(typeof body === "string" ? body : JSON.stringify(body), {
+        status,
+        headers: { "Content-Type": "application/json" },
+      })
+    );
+  }) as unknown as typeof fetch;
+  return { get: () => captured };
+}
+
+/** Route fetch by URL: `/rpc/projects_list` → projects, `/rpc/dblab_api_call` → reply. */
+function routeFetch(projects: unknown[], reply: unknown): { calls: Captured[] } {
+  const calls: Captured[] = [];
+  globalThis.fetch = mock((url: string, options: RequestInit) => {
+    calls.push({ url, options });
+    if (String(url).includes("/rpc/projects_list")) {
+      return Promise.resolve(new Response(JSON.stringify(projects), { status: 200 }));
+    }
+    return Promise.resolve(new Response(JSON.stringify(reply), { status: 200 }));
+  }) as unknown as typeof fetch;
+  return { calls };
+}
+
+function bodyOf(c: Captured | null): any {
+  return JSON.parse((c!.options.body as string) ?? "{}");
+}
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+// ---------------------------------------------------------------------------
+// resolveDblabInstanceId
+// ---------------------------------------------------------------------------
+
+describe("resolveDblabInstanceId", () => {
+  const PROJECTS = [
+    { project_id: 12, alias: "main-db", name: "Main DB", label: "Main DB", joe_ready: true, tunnel: false, instance_id: 1, dblab_instance_id: 7 },
+    { project_id: 34, alias: "analytics", name: "Analytics", label: null, joe_ready: false, tunnel: false, instance_id: null, dblab_instance_id: 9 },
+    { project_id: 56, alias: "no-dblab", name: "No DBLab", label: null, joe_ready: false, tunnel: false, instance_id: null, dblab_instance_id: null },
+  ];
+
+  test("throws when apiKey is missing", async () => {
+    await expect(
+      resolveDblabInstanceId({ apiKey: "", apiBaseUrl: API, project: "12" })
+    ).rejects.toThrow("API key is required");
+  });
+
+  test("throws when project is missing", async () => {
+    await expect(
+      resolveDblabInstanceId({ apiKey: "k", apiBaseUrl: API, project: "  " })
+    ).rejects.toThrow("project is required");
+  });
+
+  test("isNumericProjectRef distinguishes id from alias", () => {
+    expect(isNumericProjectRef("12")).toBe(true);
+    expect(isNumericProjectRef(" 34 ")).toBe(true);
+    expect(isNumericProjectRef("main-db")).toBe(false);
+  });
+
+  test("resolves a numeric project id to its dblab instance id (string) via projects_list", async () => {
+    const cap = stubFetch(PROJECTS);
+    const id = await resolveDblabInstanceId({ apiKey: "k", apiBaseUrl: API, project: "34" });
+    expect(id).toBe("9");
+    const c = cap.get()!;
+    expect(c.url).toBe(`${API}/rpc/projects_list`);
+    expect(c.options.method).toBe("POST");
+    expect((c.options.headers as Record<string, string>)["access-token"]).toBe("k");
+  });
+
+  test("resolves an alias (case-insensitive) to its dblab instance id", async () => {
+    stubFetch(PROJECTS);
+    const id = await resolveDblabInstanceId({ apiKey: "k", apiBaseUrl: API, project: "Main-DB" });
+    expect(id).toBe("7");
+  });
+
+  test("resolves a project name to its dblab instance id", async () => {
+    stubFetch(PROJECTS);
+    const id = await resolveDblabInstanceId({ apiKey: "k", apiBaseUrl: API, project: "analytics" });
+    expect(id).toBe("9");
+  });
+
+  test("passes org_id in the rpc body when orgId is provided", async () => {
+    const cap = stubFetch(PROJECTS);
+    await resolveDblabInstanceId({ apiKey: "k", apiBaseUrl: API, project: "12", orgId: 5 });
+    expect(bodyOf(cap.get()).org_id).toBe(5);
+  });
+
+  test("throws a helpful error when no project matches", async () => {
+    stubFetch(PROJECTS);
+    await expect(
+      resolveDblabInstanceId({ apiKey: "k", apiBaseUrl: API, project: "nope" })
+    ).rejects.toThrow(/No DBLab instance found for project 'nope'/);
+  });
+
+  test("throws when the project exists but has no active DBLab instance", async () => {
+    stubFetch(PROJECTS);
+    await expect(
+      resolveDblabInstanceId({ apiKey: "k", apiBaseUrl: API, project: "no-dblab" })
+    ).rejects.toThrow(/has no active DBLab instance/);
+  });
+
+  test("surfaces an HTTP error from the listing", async () => {
+    stubFetch('{"message":"boom"}', 500);
+    await expect(
+      resolveDblabInstanceId({ apiKey: "k", apiBaseUrl: API, project: "12" })
+    ).rejects.toThrow(/Failed to resolve project's DBLab instance/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// dblab_api_call proxy — action/method/data per verb
+// ---------------------------------------------------------------------------
+
+describe("clone verbs → dblab_api_call", () => {
+  const common = { apiKey: "k", apiBaseUrl: API, instanceId: "7" };
+
+  test("createClone posts /clone with a minimal data body", async () => {
+    const cap = stubFetch({ id: "c-1" });
+    await createClone({ ...common });
+    const c = cap.get()!;
+    expect(c.url).toBe(`${API}/rpc/dblab_api_call`);
+    expect(c.options.method).toBe("POST");
+    const b = bodyOf(c);
+    expect(b.instance_id).toBe("7");
+    expect(b.action).toBe("/clone");
+    expect(b.method).toBe("post");
+    expect(b.data).toEqual({ protected: false });
+  });
+
+  test("createClone maps branch / snapshot / db / protected into data", async () => {
+    const cap = stubFetch({ id: "c-1" });
+    await createClone({
+      ...common,
+      cloneId: "c-1",
+      branch: "feature-idx",
+      snapshotId: "s-9",
+      dbUser: "u",
+      dbPassword: "p",
+      isProtected: true,
+    });
+    expect(bodyOf(cap.get()).data).toEqual({
+      protected: true,
+      id: "c-1",
+      branch: "feature-idx",
+      snapshot: { id: "s-9" },
+      db: { username: "u", password: "p" },
+    });
+  });
+
+  test("listClones gets /clones with no data", async () => {
+    const cap = stubFetch([]);
+    await listClones({ ...common });
+    const b = bodyOf(cap.get());
+    expect(b.action).toBe("/clones");
+    expect(b.method).toBe("get");
+    expect(b.data).toBeUndefined();
+  });
+
+  test("getClone gets /clone/<id> (url-encoded)", async () => {
+    const cap = stubFetch({ id: "c/1" });
+    await getClone({ ...common, cloneId: "c/1" });
+    const b = bodyOf(cap.get());
+    expect(b.action).toBe("/clone/c%2F1");
+    expect(b.method).toBe("get");
+  });
+
+  test("resetClone posts /clone/<id>/reset with latest:true when no snapshot", async () => {
+    const cap = stubFetch(true);
+    await resetClone({ ...common, cloneId: "c-1" });
+    const b = bodyOf(cap.get());
+    expect(b.action).toBe("/clone/c-1/reset");
+    expect(b.method).toBe("post");
+    expect(b.data).toEqual({ latest: true });
+  });
+
+  test("resetClone with a snapshot sends snapshotID + latest:false", async () => {
+    const cap = stubFetch(true);
+    await resetClone({ ...common, cloneId: "c-1", snapshotId: "s-3" });
+    expect(bodyOf(cap.get()).data).toEqual({ latest: false, snapshotID: "s-3" });
+  });
+
+  test("destroyClone deletes /clone/<id>", async () => {
+    const cap = stubFetch("");
+    await destroyClone({ ...common, cloneId: "c-1" });
+    const b = bodyOf(cap.get());
+    expect(b.action).toBe("/clone/c-1");
+    expect(b.method).toBe("delete");
+  });
+
+  test("destroyClone requires cloneId", async () => {
+    await expect(destroyClone({ ...common, cloneId: "" })).rejects.toThrow("cloneId is required");
+  });
+});
+
+describe("branch verbs → dblab_api_call", () => {
+  const common = { apiKey: "k", apiBaseUrl: API, instanceId: "7" };
+
+  test("listBranches gets /branches", async () => {
+    const cap = stubFetch([]);
+    await listBranches({ ...common });
+    const b = bodyOf(cap.get());
+    expect(b.action).toBe("/branches");
+    expect(b.method).toBe("get");
+  });
+
+  test("createBranch posts /branch with branchName and optional base/snapshot", async () => {
+    const cap = stubFetch({ name: "feature-idx" });
+    await createBranch({ ...common, branchName: "feature-idx", baseBranch: "main", snapshotId: "s-1" });
+    const b = bodyOf(cap.get());
+    expect(b.action).toBe("/branch");
+    expect(b.method).toBe("post");
+    expect(b.data).toEqual({ branchName: "feature-idx", baseBranch: "main", snapshotID: "s-1" });
+  });
+
+  test("createBranch omits base/snapshot when not given", async () => {
+    const cap = stubFetch({ name: "b" });
+    await createBranch({ ...common, branchName: "b" });
+    expect(bodyOf(cap.get()).data).toEqual({ branchName: "b" });
+  });
+
+  test("deleteBranch deletes /branch/<name> (encoded)", async () => {
+    const cap = stubFetch(true);
+    await deleteBranch({ ...common, branchName: "feature/x" });
+    const b = bodyOf(cap.get());
+    expect(b.action).toBe("/branch/feature%2Fx");
+    expect(b.method).toBe("delete");
+  });
+
+  test("branchLog gets /branch/<name>/log", async () => {
+    const cap = stubFetch([]);
+    await branchLog({ ...common, branchName: "feature-idx" });
+    const b = bodyOf(cap.get());
+    expect(b.action).toBe("/branch/feature-idx/log");
+    expect(b.method).toBe("get");
+  });
+});
+
+describe("snapshot verbs → dblab_api_call", () => {
+  const common = { apiKey: "k", apiBaseUrl: API, instanceId: "7" };
+
+  test("listSnapshots gets /snapshots (no query when unfiltered)", async () => {
+    const cap = stubFetch([]);
+    await listSnapshots({ ...common });
+    const b = bodyOf(cap.get());
+    expect(b.action).toBe("/snapshots");
+    expect(b.method).toBe("get");
+  });
+
+  test("listSnapshots appends branch and dataset query params", async () => {
+    const cap = stubFetch([]);
+    await listSnapshots({ ...common, branchName: "main", dataset: "ds1" });
+    expect(bodyOf(cap.get()).action).toBe("/snapshots?branch=main&dataset=ds1");
+  });
+
+  test("createSnapshot posts /branch/snapshot with cloneID + message", async () => {
+    const cap = stubFetch({ snapshotID: "s-1" });
+    await createSnapshot({ ...common, cloneId: "c-1", message: "before idx" });
+    const b = bodyOf(cap.get());
+    expect(b.action).toBe("/branch/snapshot");
+    expect(b.method).toBe("post");
+    expect(b.data).toEqual({ cloneID: "c-1", message: "before idx" });
+  });
+
+  test("destroySnapshot deletes /snapshot/<id>?force=<bool>", async () => {
+    const cap = stubFetch(true);
+    await destroySnapshot({ ...common, snapshotId: "s-1", force: true });
+    const b = bodyOf(cap.get());
+    expect(b.action).toBe("/snapshot/s-1?force=true");
+    expect(b.method).toBe("delete");
+  });
+
+  test("destroySnapshot passes a multi-segment zfs snapshot id RAW (no percent-encoding)", async () => {
+    const cap = stubFetch(true);
+    await destroySnapshot({ ...common, snapshotId: "dblab_pool/branch/main/c-1/r0@20260707065703" });
+    // The engine 400s on %2F/%40 — the Console passes the id raw and so must we.
+    expect(bodyOf(cap.get()).action).toBe("/snapshot/dblab_pool/branch/main/c-1/r0@20260707065703?force=false");
+  });
+
+  test("destroySnapshot defaults force=false", async () => {
+    const cap = stubFetch(true);
+    await destroySnapshot({ ...common, snapshotId: "s-1" });
+    expect(bodyOf(cap.get()).action).toBe("/snapshot/s-1?force=false");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// error / scope-gating paths
+// ---------------------------------------------------------------------------
+
+describe("proxy error paths", () => {
+  const common = { apiKey: "k", apiBaseUrl: API, instanceId: "7" };
+
+  test("a PT403 (scope) surfaces as a formatted 403 error", async () => {
+    stubFetch('{"message":"insufficient scope: joe:admin required"}', 403);
+    await expect(destroyClone({ ...common, cloneId: "c-1" })).rejects.toThrow(/Failed to destroy clone/);
+  });
+
+  test("a 500 surfaces the operation label", async () => {
+    stubFetch('{"message":"boom"}', 500);
+    await expect(listClones({ ...common })).rejects.toThrow(/Failed to list clones/);
+  });
+
+  test("proxy requires an instanceId", async () => {
+    await expect(listClones({ ...common, instanceId: "" })).rejects.toThrow("instanceId is required");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// --debug credential redaction
+//
+// `--debug` writes the raw request/response bodies to stderr — and in the MCP
+// server the debug flag is CALLER-controlled (`args.debug`), so an agent can
+// turn it on. Credential fields must be masked the same way the access-token
+// header already is: the clone-create request embeds `data.db.password`
+// (--db-password), and clone create/status replies carry the live clone's
+// `db.password` / `db.connStr`.
+// ---------------------------------------------------------------------------
+
+describe("--debug credential redaction", () => {
+  function captureStderr() {
+    const spy = spyOn(console, "error").mockImplementation(() => {});
+    return {
+      logged: () => spy.mock.calls.map((c) => c.map(String).join(" ")).join("\n"),
+      restore: () => spy.mockRestore(),
+    };
+  }
+
+  test("clone create --debug does not log the --db-password (request body redacted)", async () => {
+    const cap = captureStderr();
+    try {
+      stubFetch({ id: "c1" });
+      await createClone({
+        apiKey: "k-0123456789abcdef",
+        apiBaseUrl: API,
+        instanceId: "7",
+        cloneId: "c1",
+        dbUser: "clone_user",
+        dbPassword: "hunter2-cleartext",
+        debug: true,
+      });
+      const logged = cap.logged();
+      expect(logged).toContain("Debug: Request body");
+      expect(logged).not.toContain("hunter2-cleartext");
+      // The rest of the body still logs (redaction, not suppression).
+      expect(logged).toContain("clone_user");
+    } finally {
+      cap.restore();
+    }
+  });
+
+  test("clone status --debug does not log the clone's credentials from the response (password/connStr)", async () => {
+    const cap = captureStderr();
+    try {
+      stubFetch({
+        id: "c1",
+        status: { code: "OK" },
+        db: {
+          connStr: "host=dblab port=6002 user=joe password=resp-secret-xyz",
+          password: "resp-secret-xyz",
+          username: "joe",
+        },
+      });
+      await getClone({ apiKey: "k-0123456789abcdef", apiBaseUrl: API, instanceId: "7", cloneId: "c1", debug: true });
+      const logged = cap.logged();
+      expect(logged).toContain("Debug: Response body");
+      expect(logged).not.toContain("resp-secret-xyz");
+      expect(logged).toContain("username");
+    } finally {
+      cap.restore();
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolve → proxy end-to-end (project → instance → call)
+// ---------------------------------------------------------------------------
+
+describe("project → instance → dblab_api_call", () => {
+  test("a verb driven off a resolved instance sends both requests", async () => {
+    const projects = [{ project_id: 12, alias: "main-db", dblab_instance_id: 7 }];
+    const { calls } = routeFetch(projects, { id: "c-1", status: "ready" });
+    const instanceId = await resolveDblabInstanceId({ apiKey: "k", apiBaseUrl: API, project: "main-db" });
+    await createClone({ apiKey: "k", apiBaseUrl: API, instanceId });
+    expect(calls.length).toBe(2);
+    expect(calls[0].url).toContain("/rpc/projects_list");
+    expect(calls[1].url).toBe(`${API}/rpc/dblab_api_call`);
+    expect(bodyOf(calls[1]).instance_id).toBe("7");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// MCP tool parity — each tool resolves the instance then proxies dblab_api_call
+// ---------------------------------------------------------------------------
+
+describe("MCP DBLab tools (handleToolCall)", () => {
+  const rootOpts = { apiKey: "k", apiBaseUrl: API };
+
+  test("clone_create resolves project then proxies /clone POST", async () => {
+    const projects = [{ project_id: 12, alias: "main-db", dblab_instance_id: 7 }];
+    const { calls } = routeFetch(projects, { ok: true });
+    const res = await handleToolCall(
+      { params: { name: "clone_create", arguments: { project: "main-db" } } },
+      rootOpts
+    );
+    expect(res.isError).toBeFalsy();
+    expect(calls[0].url).toContain("/rpc/projects_list");
+    const b = bodyOf(calls[1]);
+    expect(b.instance_id).toBe("7");
+    expect(b.action).toBe("/clone");
+    expect(b.method).toBe("post");
+  });
+
+  test("clone_destroy proxies /clone/<id> DELETE", async () => {
+    const projects = [{ project_id: 12, alias: "main-db", dblab_instance_id: 7 }];
+    const { calls } = routeFetch(projects, { ok: true });
+    const res = await handleToolCall(
+      { params: { name: "clone_destroy", arguments: { project: "main-db", clone_id: "c-1" } } },
+      rootOpts
+    );
+    expect(res.isError).toBeFalsy();
+    const b = bodyOf(calls[1]);
+    expect(b.action).toBe("/clone/c-1");
+    expect(b.method).toBe("delete");
+  });
+
+  test("snapshot_create proxies /branch/snapshot POST with cloneID", async () => {
+    const projects = [{ project_id: 12, alias: "main-db", dblab_instance_id: 7 }];
+    const { calls } = routeFetch(projects, { ok: true });
+    await handleToolCall(
+      { params: { name: "snapshot_create", arguments: { project: "main-db", clone_id: "c-1", message: "m" } } },
+      rootOpts
+    );
+    const b = bodyOf(calls[1]);
+    expect(b.action).toBe("/branch/snapshot");
+    expect(b.data).toEqual({ cloneID: "c-1", message: "m" });
+  });
+
+  test("a DBLab tool without project returns an isError response", async () => {
+    const res = await handleToolCall(
+      { params: { name: "clone_list", arguments: {} } },
+      rootOpts
+    );
+    expect(res.isError).toBe(true);
+    expect(res.content[0].text).toContain("project is required");
+  });
+
+  test("clone_status requires clone_id", async () => {
+    const res = await handleToolCall(
+      { params: { name: "clone_status", arguments: { project: "main-db" } } },
+      rootOpts
+    );
+    expect(res.isError).toBe(true);
+    expect(res.content[0].text).toContain("clone_id is required");
+  });
+});

package/test/e2e/pgai-e2e-smoke.sh

@@ -0,0 +1,192 @@
+#!/usr/bin/env bash
+#
+# pgai-e2e-smoke.sh — end-to-end smoke test for the `pgai` (Joe API v2) CLI.
+#
+# Exercises the FULL grouped CLI surface against a live platform + DBLab + Joe
+# stack and asserts expected outputs / exit codes:
+#   * projects
+#   * every `pgai joe` verb (plan, explain, exec, hypo, activity, describe,
+#     terminate, reset, history, status, result)
+#   * every `pgai dblab` verb (clone create/list/status/reset/destroy,
+#     branch list/create/log/delete, snapshot list/create/destroy)
+#   * an MCP tools/list handshake over stdio
+#
+# It is IDEMPOTENT and SAFE TO RE-RUN: every clone/branch/snapshot it creates
+# gets a unique, run-scoped name and is destroyed on exit (even on failure), and
+# it uses a throwaway XDG_CONFIG_HOME so it never touches real user state.
+#
+# Required env:
+#   PGAI_API_BASE_URL   platform PostgREST base URL (e.g. http://host:9508)
+#   PGAI_API_KEY        opaque org API token (access-token header)
+# Optional env:
+#   PGAI_BIN            CLI invocation (default: "pgai"; e.g. "npx --yes pgai@dev"
+#                       or "node /path/cli/dist/bin/postgres-ai.js")
+#   PGAI_PROJECT        project id or alias (default: first joe_ready project)
+#   PGAI_TABLE          an existing table for describe/hypo (default: pgbench_accounts)
+#   PGAI_HYPO_COL       an indexable column on PGAI_TABLE (default: bid)
+#   SMOKE_SKIP_DBLAB    set to 1 to skip the DBLab verbs (Joe-only smoke)
+#
+# Exit code: 0 = all assertions passed, 1 = one or more failed / setup error.
+
+set -u
+: "${PGAI_API_BASE_URL:?set PGAI_API_BASE_URL}"
+: "${PGAI_API_KEY:?set PGAI_API_KEY}"
+PGAI_BIN="${PGAI_BIN:-pgai}"
+PGAI_TABLE="${PGAI_TABLE:-pgbench_accounts}"
+PGAI_HYPO_COL="${PGAI_HYPO_COL:-bid}"
+RUN="smoke$$-$(date +%s)"
+WORKDIR="$(mktemp -d "${TMPDIR:-/tmp}/pgai-smoke-XXXXXX")"
+export XDG_CONFIG_HOME="$WORKDIR/cfg"; mkdir -p "$XDG_CONFIG_HOME"
+PASS=0; FAIL=0
+CREATED_CLONES=(); CREATED_BRANCHES=(); CREATED_SNAPSHOTS=()
+
+# The CLI reads PGAI_API_BASE_URL / PGAI_API_KEY from the environment; export them
+# so subshells (bash -c, timeout, the MCP pipe) inherit the credentials.
+export PGAI_API_BASE_URL PGAI_API_KEY
+
+# Resolve a bare command name to an absolute path so the on-PATH wrapper below
+# does not recurse into itself.
+case "$PGAI_BIN" in
+  *" "*) : ;;  # multi-word (e.g. "node /path/postgres-ai.js") — leave as-is
+  *) PGAI_BIN="$(command -v "$PGAI_BIN" 2>/dev/null || echo "$PGAI_BIN")" ;;
+esac
+
+# Expose a real `pgai` executable on PATH (not a shell function) so every context
+# — direct calls, `bash -c "pgai …"`, and `timeout … pgai …` — resolves it.
+mkdir -p "$WORKDIR/bin"
+cat > "$WORKDIR/bin/pgai" <<EOF
+#!/usr/bin/env bash
+exec $PGAI_BIN "\$@"
+EOF
+chmod +x "$WORKDIR/bin/pgai"
+export PATH="$WORKDIR/bin:$PATH"
+
+# check <label> <expected_exit> <grep-pattern-or-.> -- <cmd...>
+check() {
+  local label="$1" want_exit="$2" pat="$3"; shift 3; [ "$1" = "--" ] && shift
+  local out rc
+  out="$("$@" 2>&1)"; rc=$?
+  local ok=1
+  [ "$rc" = "$want_exit" ] || ok=0
+  if [ "$pat" != "." ]; then printf '%s' "$out" | grep -qiE "$pat" || ok=0; fi
+  if [ "$ok" = 1 ]; then
+    PASS=$((PASS+1)); printf '  PASS  %-42s (exit %s)\n' "$label" "$rc"
+  else
+    FAIL=$((FAIL+1)); printf '  FAIL  %-42s (exit %s, want %s; pattern /%s/)\n' "$label" "$rc" "$want_exit" "$pat"
+    printf '        output: %s\n' "$(printf '%s' "$out" | head -3 | tr '\n' '|')"
+  fi
+}
+
+cleanup() {
+  local c b s
+  for c in "${CREATED_CLONES[@]:-}"; do [ -n "$c" ] && pgai dblab clone destroy "$c" --project "$PROJECT" >/dev/null 2>&1; done
+  for s in "${CREATED_SNAPSHOTS[@]:-}"; do [ -n "$s" ] && pgai dblab snapshot destroy "$s" --project "$PROJECT" --force >/dev/null 2>&1; done
+  for b in "${CREATED_BRANCHES[@]:-}"; do [ -n "$b" ] && pgai dblab branch delete "$b" --project "$PROJECT" >/dev/null 2>&1; done
+  rm -rf "$WORKDIR"
+}
+trap cleanup EXIT
+
+echo "== pgai E2E smoke =="
+echo "   bin=$PGAI_BIN  base=$PGAI_API_BASE_URL  run=$RUN"
+echo "   version: $(pgai --version 2>&1 | tail -1)"
+
+# ---- discover a target project ---------------------------------------------
+PROJECT="${PGAI_PROJECT:-}"
+if [ -z "$PROJECT" ]; then
+  PROJECT="$(pgai projects --json 2>/dev/null | jq -r 'map(select(.joe_ready==true))[0].project_id // empty')"
+fi
+if [ -z "$PROJECT" ]; then echo "FATAL: no joe_ready project found (set PGAI_PROJECT)"; exit 1; fi
+echo "   target project: $PROJECT   table: $PGAI_TABLE"
+
+echo; echo "-- org / projects --"
+check "projects (table)"        0 "PROJECT_ID" -- pgai projects
+check "projects (--json array)" 0 "."          -- bash -c 'pgai projects --json | jq -e "type==\"array\"" >/dev/null'
+
+echo; echo "-- joe verbs --"
+check "joe plan"        0 "cost="                 -- pgai joe plan "select 1" --project "$PROJECT"
+check "joe plan --json" 0 "."                      -- bash -c "pgai joe plan 'select 1' --project '$PROJECT' --json | jq -e '.plan_json' >/dev/null"
+check "joe explain"     0 "cost="                 -- pgai joe explain "select 1" --project "$PROJECT"
+check "joe exec"        0 "\"answer\": *42|answer" -- pgai joe exec "select 42 as answer" --project "$PROJECT" --json
+check "joe exec empty"  0 "0 rows"                 -- pgai joe exec "select 1 where false" --project "$PROJECT"
+check "joe hypo"        0 "hypothetical index"     -- pgai joe hypo "create index on $PGAI_TABLE ($PGAI_HYPO_COL)" --query "select * from $PGAI_TABLE where $PGAI_HYPO_COL = 1" --project "$PROJECT"
+check "joe activity"    0 "."                      -- pgai joe activity --project "$PROJECT"
+check "joe describe"    0 "$PGAI_TABLE"            -- pgai joe describe "$PGAI_TABLE" --project "$PROJECT"
+check "joe terminate (no such pid)" 0 "terminated no|pid" -- pgai joe terminate 999999 --project "$PROJECT"
+check "joe terminate (bad pid rejected)" 1 "pid must be a number" -- pgai joe terminate 12x --project "$PROJECT"
+check "joe history (M1b stub)" 1 "not available yet" -- pgai joe history "anything" --project "$PROJECT"
+
+# status/result on a real submitted command
+CID="$(pgai joe plan "select 2" --project "$PROJECT" --json 2>/dev/null | jq -r '.command_id // empty')"
+if [ -n "$CID" ]; then
+  check "joe status <id>" 0 "$CID" -- pgai joe status "$CID"
+  check "joe result <id>" 0 "cost=|done" -- pgai joe result "$CID"
+else
+  FAIL=$((FAIL+1)); echo "  FAIL  joe status/result (no command_id captured)"
+fi
+
+# reset re-snapshots the session clone (restores a pristine state)
+check "joe reset"       0 "reset ok"              -- pgai joe reset --project "$PROJECT"
+
+echo; echo "-- error surfacing / ergonomics --"
+check "wrong base url (ECONNREFUSED)" 1 "could not reach" -- pgai --api-base-url http://127.0.0.1:59999 projects
+check "exec syntax error (clean)"     1 "error|Query error" -- pgai joe exec "selct 1" --project "$PROJECT"
+check "plan unparsable (400)"         1 "parse|400"    -- pgai joe plan "not sql ;;;" --project "$PROJECT"
+
+if [ "${SMOKE_SKIP_DBLAB:-0}" != "1" ]; then
+  echo; echo "-- dblab verbs --"
+  check "dblab snapshot list" 0 "." -- bash -c "pgai dblab snapshot list --project '$PROJECT' --json | jq -e 'type==\"array\"' >/dev/null"
+  check "dblab branch list"   0 "main" -- pgai dblab branch list --project "$PROJECT"
+
+  CLONE="smoke-clone-$RUN"; PW='Zx9#mQ2!vLp7wRt3'
+  check "dblab clone create"  0 "$CLONE|CREATING|OK" -- pgai dblab clone create --project "$PROJECT" --id "$CLONE" --db-user smoke_u --db-password "$PW"
+  CREATED_CLONES+=("$CLONE")
+  # wait for the clone to reach OK (create is async)
+  for _ in $(seq 1 30); do
+    st="$(pgai dblab clone status "$CLONE" --project "$PROJECT" --json 2>/dev/null | jq -r '.status.code // .status // empty')"
+    [ "$st" = "OK" ] && break; sleep 2
+  done
+  check "dblab clone status (OK)" 0 "OK"     -- pgai dblab clone status "$CLONE" --project "$PROJECT"
+  check "dblab clone list (has it)" 0 "$CLONE" -- pgai dblab clone list --project "$PROJECT"
+
+  SNAP="$(pgai dblab snapshot create --project "$PROJECT" --clone "$CLONE" --message "smoke $RUN" --json 2>/dev/null | jq -r '.snapshotID // .id // empty')"
+  if [ -n "$SNAP" ]; then
+    CREATED_SNAPSHOTS+=("$SNAP"); PASS=$((PASS+1)); echo "  PASS  dblab snapshot create               ($SNAP)"
+    check "dblab snapshot destroy" 0 "destroyed|true|." -- pgai dblab snapshot destroy "$SNAP" --project "$PROJECT" --force
+    CREATED_SNAPSHOTS=()  # destroyed
+  else
+    echo "  SKIP  dblab snapshot create/destroy       (engine declined; non-fatal)"
+  fi
+
+  check "dblab clone reset"   0 "."           -- pgai dblab clone reset "$CLONE" --project "$PROJECT" --latest
+  check "dblab clone destroy" 0 "destroyed|true" -- pgai dblab clone destroy "$CLONE" --project "$PROJECT"
+  CREATED_CLONES=()  # destroyed
+
+  BR="smoke-branch-$RUN"
+  if pgai dblab branch create "$BR" --project "$PROJECT" --base-branch main >/dev/null 2>&1; then
+    CREATED_BRANCHES+=("$BR"); PASS=$((PASS+1)); echo "  PASS  dblab branch create                 ($BR)"
+    check "dblab branch log"    0 "."       -- pgai dblab branch log "$BR" --project "$PROJECT"
+    check "dblab branch delete" 0 "deleted|true|." -- pgai dblab branch delete "$BR" --project "$PROJECT"
+    CREATED_BRANCHES=()  # deleted
+  else
+    echo "  SKIP  dblab branch create/log/delete      (engine declined; non-fatal)"
+  fi
+fi
+
+echo; echo "-- MCP --"
+MCP_OUT="$WORKDIR/mcp.txt"
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"1"}}}' \
+  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
+  | timeout 30 pgai mcp start >"$MCP_OUT" 2>/dev/null
+N="$(grep '"id":2' "$MCP_OUT" | jq -r '.result.tools | length' 2>/dev/null)"
+HAS="$(grep '"id":2' "$MCP_OUT" | jq -r '[.result.tools[].name] | (index("plan_query")!=null and index("clone_create")!=null and index("list_projects")!=null)' 2>/dev/null)"
+if [ "${N:-0}" -ge 20 ] && [ "$HAS" = "true" ]; then
+  PASS=$((PASS+1)); echo "  PASS  mcp tools/list                      ($N tools; joe+dblab+projects present)"
+else
+  FAIL=$((FAIL+1)); echo "  FAIL  mcp tools/list                      (count=$N has_core=$HAS)"
+fi
+
+echo
+echo "== RESULT: $PASS passed, $FAIL failed =="
+[ "$FAIL" = 0 ] && exit 0 || exit 1