postgresai 0.16.0-dev.3 → 0.16.0-dev.5

package/lib/dblab.ts

@@ -24,6 +24,7 @@
  */
 
 import { formatHttpError, maskSecret, normalizeBaseUrl } from "./util";
+import { listProjects, type ProjectListItem } from "./joe";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -51,14 +52,12 @@ interface DblabCommon {
 // ---------------------------------------------------------------------------
 // Project → DBLab instance resolution
 //
-// MINIMAL LOCAL RESOLVER (dedupe note for the merge into dev/joe-api-v2):
-// The Joe-commands MR adds `resolveProjectId(--project)` (project id|alias →
-// numeric project_id) and the projects-API (finding M-4) is slated to surface
-// each project's single DBLab instance id. Neither has merged yet, so this
-// module resolves `--project` → DBLab `instance_id` locally against the existing
-// `v1.dblab_instances` view (the same list the Console reads). Once the shared
-// resolver + per-project instance surfacing land, collapse this into that shared
-// path so `--project` id/alias resolution lives in exactly one place.
+// Resolution rides the org-level projects listing rpc (`v1.projects_list`,
+// S.1): its rows carry each project's `dblab_instance_id` (DB.4), and the rpc
+// authenticates with the CLI's opaque org `access-token` header. The previous
+// interim resolver read the `v1.dblab_instances` PostgREST view, which is
+// JWT-scoped — permanently empty/403 for a token-only caller — so it never
+// worked outside mocks and was dropped at wiring (dedupe note resolved).
 // ---------------------------------------------------------------------------
 
 /** A bare numeric `--project` value is a project id; anything else is an alias/name. */
@@ -71,23 +70,21 @@ export interface ResolveDblabInstanceParams {
   apiBaseUrl: string;
   /** `--project <id|alias>` — a numeric project id, or a project alias/name. */
   project: string;
-  /** Optional org scope (narrows the instance listing). */
+  /** Optional org scope (narrows the projects listing). */
   orgId?: number;
   debug?: boolean;
 }
 
 /**
- * Resolve `--project <id|alias>` to its single DBLab `instance_id`.
+ * Resolve `--project <id|alias>` to the project's single DBLab `instance_id`.
  *
- * Reuses the existing `v1.dblab_instances` listing (the same one the Console
- * reads): a numeric ref matches on `project_id`; an alias/name matches
- * `project_alias` / `project_name` / `project_label_or_name` (case-insensitive).
- * There is exactly one DBLab instance per project, so the first match is the
- * instance. The returned id is a string so a 64-bit id survives without JS
- * number-precision loss.
+ * Lists the org's projects via `v1.projects_list` (the same call behind
+ * `pgai projects`): a numeric ref matches `project_id`; anything else matches
+ * `alias` / `name` / `label` (case-insensitive). Each project has at most one
+ * active DBLab instance (`dblab_instance_id`). The returned id is a string so
+ * a 64-bit id survives without JS number-precision loss.
  */
 export async function resolveDblabInstanceId(params: ResolveDblabInstanceParams): Promise<string> {
-  // TODO(joe-v2): unify --project resolution once projects_list (S.1) returns the dblab instance id
   const { apiKey, apiBaseUrl, orgId, debug } = params;
   if (!apiKey) {
     throw new Error("API key is required");
@@ -97,55 +94,24 @@ export async function resolveDblabInstanceId(params: ResolveDblabInstanceParams)
     throw new Error("project is required (--project <id|alias>)");
   }
 
-  const base = normalizeBaseUrl(apiBaseUrl);
-  const url = new URL(`${base}/dblab_instances`);
-  url.searchParams.set("select", "id,project_id,project_name,project_alias,project_label_or_name,org_id");
-  if (typeof orgId === "number") {
-    url.searchParams.set("org_id", `eq.${orgId}`);
-  }
-
-  const headers: Record<string, string> = {
-    "access-token": apiKey,
-    "Content-Type": "application/json",
-    "Connection": "close",
-  };
-
-  if (debug) {
-    const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
-    console.error(`Debug: GET URL: ${url.toString()}`);
-    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
-  }
-
-  const response = await fetch(url.toString(), { method: "GET", headers });
-  const text = await response.text();
-
-  if (debug) {
-    console.error(`Debug: Response status: ${response.status}`);
-    console.error(`Debug: Response body: ${text}`);
-  }
-
-  if (!response.ok) {
-    throw new Error(formatHttpError("Failed to resolve project's DBLab instance", response.status, text));
-  }
-
-  let rows: DblabInstanceRow[];
+  let projects: ProjectListItem[];
   try {
-    const parsed = JSON.parse(text);
-    rows = Array.isArray(parsed) ? parsed : [];
-  } catch {
-    throw new Error(`Failed to parse DBLab instances response: ${text}`);
+    projects = await listProjects({ apiKey, apiBaseUrl, orgId, debug });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to resolve project's DBLab instance: ${message}`);
   }
 
   const numeric = isNumericProjectRef(ref);
   const needle = ref.toLowerCase();
-  const match = rows.find((r) => {
+  const match = projects.find((p) => {
     if (numeric) {
-      return String(r.project_id ?? "") === ref;
+      return String(p.project_id) === ref;
     }
     return (
-      (r.project_alias != null && String(r.project_alias).toLowerCase() === needle) ||
-      (r.project_name != null && String(r.project_name).toLowerCase() === needle) ||
-      (r.project_label_or_name != null && String(r.project_label_or_name).toLowerCase() === needle)
+      (p.alias !== null && p.alias.toLowerCase() === needle) ||
+      (p.name !== null && p.name.toLowerCase() === needle) ||
+      (p.label !== null && p.label.toLowerCase() === needle)
     );
   });
 
@@ -154,7 +120,12 @@ export async function resolveDblabInstanceId(params: ResolveDblabInstanceParams)
       `No DBLab instance found for project '${ref}'. Run 'pgai projects' to see available projects.`
     );
   }
-  return String(match.id);
+  if (match.dblab_instance_id == null) {
+    throw new Error(
+      `Project '${ref}' has no active DBLab instance. Register a DBLab instance for it in the Console first.`
+    );
+  }
+  return String(match.dblab_instance_id);
 }
 
 // ---------------------------------------------------------------------------
@@ -444,11 +415,17 @@ export interface DestroySnapshotParams extends DblabCommon {
   force?: boolean;
 }
 
-/** Destroy a snapshot — `/snapshot/<id>?force=<bool>` DELETE (Console `destroySnapshot`). */
+/** Destroy a snapshot — `/snapshot/<id>?force=<bool>` DELETE (Console `destroySnapshot`).
+ *
+ * The snapshot id is a MULTI-SEGMENT zfs path (`pool/branch/<b>/<clone>/r0@snap`),
+ * which the DBLab engine routes as a wildcard path — it must be passed RAW,
+ * exactly as the Console does. `encodeURIComponent` here turned `/`→`%2F` and
+ * `@`→`%40`, which the engine rejects with 400 `invalid snapshot name given`
+ * (verified live against DBLab CE 4.1.3). */
 export async function destroySnapshot<T = unknown>(params: DestroySnapshotParams): Promise<T> {
   const { apiKey, apiBaseUrl, instanceId, snapshotId, force, debug } = params;
   if (!snapshotId) throw new Error("snapshotId is required");
-  const action = `/snapshot/${encodeURIComponent(snapshotId)}?force=${Boolean(force)}`;
+  const action = `/snapshot/${snapshotId}?force=${Boolean(force)}`;
   return callDblabApi<T>({
     apiKey, apiBaseUrl, instanceId,
     action, method: "delete",

package/lib/joe.ts

@@ -119,6 +119,11 @@ export interface ProjectListItem {
   joe_ready: boolean;
   /** Whether the project's DBLab tunnel is connected. */
   tunnel: boolean;
+  /** The project's active JOE instance id (the M1a submit/status/result target). */
+  instance_id: number | null;
+  /** The project's active DBLAB instance id — the SPEC §8 DBLab-companion resolver
+   * passes this to `v1.dblab_api_call` (distinct from the Joe `instance_id`). */
+  dblab_instance_id: number | null;
 }
 
 // ---------------------------------------------------------------------------
@@ -285,6 +290,8 @@ interface RawProjectRow {
   joe_api_v2_enabled?: boolean;
   tunnel?: boolean;
   tunnel_ready?: boolean;
+  instance_id?: number | null;
+  dblab_instance_id?: number | null;
 }
 
 function normalizeProjectRow(row: RawProjectRow): ProjectListItem {
@@ -296,6 +303,8 @@ function normalizeProjectRow(row: RawProjectRow): ProjectListItem {
     label: row.label ?? null,
     joe_ready: Boolean(row.joe_ready ?? row.joe_api_v2_enabled ?? false),
     tunnel: Boolean(row.tunnel ?? row.tunnel_ready ?? false),
+    instance_id: row.instance_id == null ? null : Number(row.instance_id),
+    dblab_instance_id: row.dblab_instance_id == null ? null : Number(row.dblab_instance_id),
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresai",
-  "version": "0.16.0-dev.3",
+  "version": "0.16.0-dev.5",
   "description": "postgres_ai CLI",
   "license": "Apache-2.0",
   "private": false,

package/test/dblab.cli.test.ts

@@ -48,14 +48,14 @@ interface Recorded {
 }
 
 /**
- * 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.
+ * Fake Platform API: serves the `/rpc/projects_list` resolver listing (rows
+ * carry `dblab_instance_id`, S.1/DB.4) 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[]) {
+async function startFakeApi(projects?: 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 rows = 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 },
   ];
 
   const server = Bun.serve({
@@ -68,7 +68,7 @@ async function startFakeApi(instances?: unknown[]) {
       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")) {
+      if (req.method === "POST" && url.pathname.endsWith("/rpc/projects_list")) {
         return new Response(JSON.stringify(rows), { status: 200, headers: { "Content-Type": "application/json" } });
       }
       if (req.method === "POST" && url.pathname.endsWith("/rpc/dblab_api_call")) {
@@ -88,7 +88,7 @@ async function startFakeApi(instances?: unknown[]) {
     baseUrl,
     requests,
     proxyCalls: () => requests.filter((r) => r.pathname.endsWith("/rpc/dblab_api_call")),
-    resolverCalls: () => requests.filter((r) => r.pathname.endsWith("/dblab_instances")),
+    resolverCalls: () => requests.filter((r) => r.pathname.endsWith("/rpc/projects_list")),
     stop: () => server.stop(true),
   };
 }
@@ -318,8 +318,8 @@ describe("CLI DBLab companion command groups", () => {
       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 });
+        if (req.method === "POST" && url.pathname.endsWith("/rpc/projects_list")) {
+          return new Response(JSON.stringify([{ project_id: 12, alias: "main-db", dblab_instance_id: 7 }]), { status: 200 });
         }
         return new Response('{"message":"insufficient scope: joe:admin required"}', { status: 403 });
       },

package/test/dblab.test.ts

@@ -40,13 +40,13 @@ function stubFetch(body: unknown, status = 200): { get: () => Captured | null }
   return { get: () => captured };
 }
 
-/** Route fetch by URL: `/dblab_instances` → instances, `/rpc/dblab_api_call` → reply. */
-function routeFetch(instances: unknown[], reply: unknown): { calls: 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("/dblab_instances")) {
-      return Promise.resolve(new Response(JSON.stringify(instances), { status: 200 }));
+    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;
@@ -66,9 +66,10 @@ afterEach(() => {
 // ---------------------------------------------------------------------------
 
 describe("resolveDblabInstanceId", () => {
-  const INSTANCES = [
-    { id: 7, project_id: 12, project_name: "Main DB", project_alias: "main-db", project_label_or_name: "Main DB" },
-    { id: 9, project_id: 34, project_name: "Analytics", project_alias: "analytics", project_label_or_name: "Analytics" },
+  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 () => {
@@ -89,42 +90,48 @@ describe("resolveDblabInstanceId", () => {
     expect(isNumericProjectRef("main-db")).toBe(false);
   });
 
-  test("resolves a numeric project id to its instance id (string)", async () => {
-    const cap = stubFetch(INSTANCES);
+  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).toContain(`${API}/dblab_instances`);
-    expect(c.url).toContain("select=");
-    expect(c.options.method).toBe("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 instance id", async () => {
-    stubFetch(INSTANCES);
+  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 instance id", async () => {
-    stubFetch(INSTANCES);
+  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("adds an org_id filter when orgId is provided", async () => {
-    const cap = stubFetch(INSTANCES);
+  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(decodeURIComponent(cap.get()!.url)).toContain("org_id=eq.5");
+    expect(bodyOf(cap.get()).org_id).toBe(5);
   });
 
-  test("throws a helpful error when no instance matches", async () => {
-    stubFetch(INSTANCES);
+  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(
@@ -295,6 +302,13 @@ describe("snapshot verbs → dblab_api_call", () => {
     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" });
@@ -330,12 +344,12 @@ describe("proxy error paths", () => {
 
 describe("project → instance → dblab_api_call", () => {
   test("a verb driven off a resolved instance sends both requests", async () => {
-    const instances = [{ id: 7, project_id: 12, project_alias: "main-db" }];
-    const { calls } = routeFetch(instances, { id: "c-1", status: "ready" });
+    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("/dblab_instances");
+    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");
   });
@@ -349,14 +363,14 @@ describe("MCP DBLab tools (handleToolCall)", () => {
   const rootOpts = { apiKey: "k", apiBaseUrl: API };
 
   test("clone_create resolves project then proxies /clone POST", async () => {
-    const instances = [{ id: 7, project_id: 12, project_alias: "main-db" }];
-    const { calls } = routeFetch(instances, { ok: true });
+    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("/dblab_instances");
+    expect(calls[0].url).toContain("/rpc/projects_list");
     const b = bodyOf(calls[1]);
     expect(b.instance_id).toBe("7");
     expect(b.action).toBe("/clone");
@@ -364,8 +378,8 @@ describe("MCP DBLab tools (handleToolCall)", () => {
   });
 
   test("clone_destroy proxies /clone/<id> DELETE", async () => {
-    const instances = [{ id: 7, project_id: 12, project_alias: "main-db" }];
-    const { calls } = routeFetch(instances, { ok: true });
+    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
@@ -377,8 +391,8 @@ describe("MCP DBLab tools (handleToolCall)", () => {
   });
 
   test("snapshot_create proxies /branch/snapshot POST with cloneID", async () => {
-    const instances = [{ id: 7, project_id: 12, project_alias: "main-db" }];
-    const { calls } = routeFetch(instances, { ok: true });
+    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

package/test/joe.test.ts

@@ -176,14 +176,14 @@ describe("listProjects", () => {
     installFetch({
       projects_list: () =>
         json([
-          { id: 12, alias: "main-db", name: "Main DB", label: "Main DB", joe_api_v2_enabled: true, tunnel_ready: true },
+          { id: 12, alias: "main-db", name: "Main DB", label: "Main DB", joe_api_v2_enabled: true, tunnel_ready: true, instance_id: 3, dblab_instance_id: 7 },
           { project_id: 13, alias: "dw", name: "Warehouse", joe_ready: false, tunnel: false },
         ]),
     });
     const projects = await listProjects({ apiKey: "k", apiBaseUrl: BASE });
     expect(projects).toEqual([
-      { project_id: 12, alias: "main-db", name: "Main DB", label: "Main DB", joe_ready: true, tunnel: true },
-      { project_id: 13, alias: "dw", name: "Warehouse", label: null, joe_ready: false, tunnel: false },
+      { project_id: 12, alias: "main-db", name: "Main DB", label: "Main DB", joe_ready: true, tunnel: true, instance_id: 3, dblab_instance_id: 7 },
+      { project_id: 13, alias: "dw", name: "Warehouse", label: null, joe_ready: false, tunnel: false, instance_id: null, dblab_instance_id: null },
     ]);
   });
 
@@ -498,7 +498,7 @@ describe("presentation helpers", () => {
 
   test("formatProjectsTable renders the brief's column header", () => {
     const table = formatProjectsTable([
-      { project_id: 12, alias: "main-db", name: "Main DB", label: null, joe_ready: true, tunnel: true },
+      { project_id: 12, alias: "main-db", name: "Main DB", label: null, joe_ready: true, tunnel: true, instance_id: null, dblab_instance_id: 7 },
     ]);
     const [header, row] = table.split("\n");
     expect(header).toContain("PROJECT_ID");