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

package/lib/dblab.ts

@@ -0,0 +1,457 @@
+/**
+ * DBLab companion command surface (Joe API v2 · SPEC §8).
+ *
+ * Thin CLI/MCP client that **proxies the existing Platform DBLab API** — the very
+ * same endpoints the Console (React) drives — to manage a project's own thin
+ * clones, branches, and snapshots. Every verb goes through the generic proxy rpc
+ * `v1.dblab_api_call(instance_id, method, action, data)` (the first-class
+ * `dblab_clone_*` rpcs are deprecated in favour of it), mirroring
+ * `packages/platform/src/api/{clones,branches,snapshots}/*` in the platform repo:
+ *
+ *   POST {base}/rpc/dblab_api_call
+ *   body: { instance_id, action, method, data? }
+ *
+ * `method` is a lowercase HTTP verb, `action` is the leading-slash DBLab engine
+ * path, and `data` (mutations only) is a nested JSON object — exactly the wire
+ * shape the Console sends. No net-new backend: this is the same pattern as the
+ * `postgresai` CLI already proxying issues/reports.
+ *
+ * Addressing is **project-centric**: callers pass `--project <id|alias>` and the
+ * project's single DBLab instance is resolved to an `instance_id` (see
+ * `resolveDblabInstanceId`). Destructive verbs (clone reset/destroy, branch
+ * delete, snapshot destroy) are gated server-side by the `joe:admin` scope; the
+ * read/create verbs by `joe:plan` — a `PT403` surfaces as an HTTP 403 here.
+ */
+
+import { formatHttpError, maskSecret, normalizeBaseUrl } from "./util";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A row of the `v1.dblab_instances` view (only the fields the resolver needs). */
+export interface DblabInstanceRow {
+  /** The DBLab instance id — this is the `instance_id` passed to `dblab_api_call`. */
+  id: number | string;
+  project_id?: number | null;
+  project_name?: string | null;
+  project_alias?: string | null;
+  project_label_or_name?: string | null;
+  org_id?: number | null;
+}
+
+interface DblabCommon {
+  apiKey: string;
+  apiBaseUrl: string;
+  /** Resolved DBLab instance id (see `resolveDblabInstanceId`). */
+  instanceId: string;
+  debug?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// 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.
+// ---------------------------------------------------------------------------
+
+/** A bare numeric `--project` value is a project id; anything else is an alias/name. */
+export function isNumericProjectRef(ref: string): boolean {
+  return /^[0-9]+$/.test(ref.trim());
+}
+
+export interface ResolveDblabInstanceParams {
+  apiKey: string;
+  apiBaseUrl: string;
+  /** `--project <id|alias>` — a numeric project id, or a project alias/name. */
+  project: string;
+  /** Optional org scope (narrows the instance listing). */
+  orgId?: number;
+  debug?: boolean;
+}
+
+/**
+ * Resolve `--project <id|alias>` to its 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.
+ */
+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");
+  }
+  const ref = String(params.project ?? "").trim();
+  if (!ref) {
+    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[];
+  try {
+    const parsed = JSON.parse(text);
+    rows = Array.isArray(parsed) ? parsed : [];
+  } catch {
+    throw new Error(`Failed to parse DBLab instances response: ${text}`);
+  }
+
+  const numeric = isNumericProjectRef(ref);
+  const needle = ref.toLowerCase();
+  const match = rows.find((r) => {
+    if (numeric) {
+      return String(r.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)
+    );
+  });
+
+  if (!match) {
+    throw new Error(
+      `No DBLab instance found for project '${ref}'. Run 'pgai projects' to see available projects.`
+    );
+  }
+  return String(match.id);
+}
+
+// ---------------------------------------------------------------------------
+// Low-level proxy caller — POST /rpc/dblab_api_call
+// ---------------------------------------------------------------------------
+
+interface DblabApiCallParams {
+  apiKey: string;
+  apiBaseUrl: string;
+  instanceId: string;
+  /** Leading-slash DBLab engine path, e.g. `/clone`, `/branches`, `/snapshots`. */
+  action: string;
+  /** Lowercase HTTP verb forwarded to the DBLab engine: get/post/patch/delete. */
+  method: string;
+  /** Optional request body (mutations only), forwarded as a nested JSON object. */
+  data?: Record<string, unknown>;
+  operation: string;
+  debug?: boolean;
+}
+
+/**
+ * Proxy a single call to the DBLab engine via `v1.dblab_api_call`, mirroring the
+ * Console's `request('/rpc/dblab_api_call', { body: {instance_id, action, method,
+ * data} })`. Returns the parsed JSON reply, or throws a formatted HTTP error.
+ */
+async function callDblabApi<T>(params: DblabApiCallParams): Promise<T> {
+  const { apiKey, apiBaseUrl, instanceId, action, method, data, operation, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  if (!instanceId) {
+    throw new Error("instanceId is required");
+  }
+
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/rpc/dblab_api_call`);
+
+  const bodyObj: Record<string, unknown> = {
+    instance_id: instanceId,
+    action,
+    method,
+  };
+  if (data !== undefined) {
+    bodyObj.data = data;
+  }
+  const body = JSON.stringify(bodyObj);
+
+  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: POST URL: ${url.toString()}`);
+    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.error(`Debug: Request body: ${body}`);
+  }
+
+  const response = await fetch(url.toString(), { method: "POST", headers, body });
+  const text = await response.text();
+
+  if (debug) {
+    console.error(`Debug: Response status: ${response.status}`);
+    console.error(`Debug: Response body: ${text}`);
+  }
+
+  if (!response.ok) {
+    // PostgREST maps custom `PTxyz` sqlstates to HTTP status `xyz`, so a missing
+    // `joe:admin` scope on a destructive verb surfaces here as HTTP 403.
+    throw new Error(formatHttpError(operation, response.status, text));
+  }
+
+  // Some DBLab actions (reset/destroy) reply with an empty body on success.
+  if (text.trim() === "") {
+    return null as unknown as T;
+  }
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    throw new Error(`${operation}: failed to parse response: ${text}`);
+  }
+}
+
+// ===========================================================================
+// Clones — create / list / status / reset / destroy
+// ===========================================================================
+
+export interface CreateCloneParams extends DblabCommon {
+  /** Optional caller-chosen clone id (DBLab generates one when omitted). */
+  cloneId?: string;
+  /** Branch to clone from. */
+  branch?: string;
+  /** Snapshot id to clone from. */
+  snapshotId?: string;
+  /** Clone DB user (paired with `dbPassword`). */
+  dbUser?: string;
+  /** Clone DB password (paired with `dbUser`). */
+  dbPassword?: string;
+  /** Protect the clone from auto-deletion. */
+  isProtected?: boolean;
+}
+
+/** Create a thin clone — `/clone` POST (Console `createClone`). */
+export async function createClone<T = unknown>(params: CreateCloneParams): Promise<T> {
+  const { apiKey, apiBaseUrl, instanceId, cloneId, branch, snapshotId, dbUser, dbPassword, isProtected, debug } = params;
+  const data: Record<string, unknown> = { protected: Boolean(isProtected) };
+  if (cloneId) data.id = cloneId;
+  if (branch) data.branch = branch;
+  if (snapshotId) data.snapshot = { id: snapshotId };
+  if (dbUser && dbPassword) data.db = { username: dbUser, password: dbPassword };
+  return callDblabApi<T>({
+    apiKey, apiBaseUrl, instanceId,
+    action: "/clone", method: "post", data,
+    operation: "Failed to create clone", debug,
+  });
+}
+
+/** List clones — `/clones` GET. */
+export async function listClones<T = unknown>(params: DblabCommon): Promise<T> {
+  const { apiKey, apiBaseUrl, instanceId, debug } = params;
+  return callDblabApi<T>({
+    apiKey, apiBaseUrl, instanceId,
+    action: "/clones", method: "get",
+    operation: "Failed to list clones", debug,
+  });
+}
+
+export interface CloneIdParams extends DblabCommon {
+  cloneId: string;
+}
+
+/** Get a clone's status — `/clone/<id>` GET (Console `getClone`). */
+export async function getClone<T = unknown>(params: CloneIdParams): Promise<T> {
+  const { apiKey, apiBaseUrl, instanceId, cloneId, debug } = params;
+  if (!cloneId) throw new Error("cloneId is required");
+  return callDblabApi<T>({
+    apiKey, apiBaseUrl, instanceId,
+    action: `/clone/${encodeURIComponent(cloneId)}`, method: "get",
+    operation: "Failed to get clone", debug,
+  });
+}
+
+export interface ResetCloneParams extends CloneIdParams {
+  /** Snapshot to reset to; when omitted, resets to the latest snapshot. */
+  snapshotId?: string;
+  /** Reset to the latest snapshot (defaults true when no `snapshotId` is given). */
+  latest?: boolean;
+}
+
+/** Reset a clone to a pristine snapshot — `/clone/<id>/reset` POST (Console `resetClone`). */
+export async function resetClone<T = unknown>(params: ResetCloneParams): Promise<T> {
+  const { apiKey, apiBaseUrl, instanceId, cloneId, snapshotId, latest, debug } = params;
+  if (!cloneId) throw new Error("cloneId is required");
+  const data: Record<string, unknown> = { latest: latest ?? !snapshotId };
+  if (snapshotId) data.snapshotID = snapshotId;
+  return callDblabApi<T>({
+    apiKey, apiBaseUrl, instanceId,
+    action: `/clone/${encodeURIComponent(cloneId)}/reset`, method: "post", data,
+    operation: "Failed to reset clone", debug,
+  });
+}
+
+/** Destroy a clone — `/clone/<id>` DELETE (Console `destroyClone`). */
+export async function destroyClone<T = unknown>(params: CloneIdParams): Promise<T> {
+  const { apiKey, apiBaseUrl, instanceId, cloneId, debug } = params;
+  if (!cloneId) throw new Error("cloneId is required");
+  return callDblabApi<T>({
+    apiKey, apiBaseUrl, instanceId,
+    action: `/clone/${encodeURIComponent(cloneId)}`, method: "delete",
+    operation: "Failed to destroy clone", debug,
+  });
+}
+
+// ===========================================================================
+// Branches — list / create / delete / log
+// ===========================================================================
+
+/** List branches — `/branches` GET (Console `getBranches`). */
+export async function listBranches<T = unknown>(params: DblabCommon): Promise<T> {
+  const { apiKey, apiBaseUrl, instanceId, debug } = params;
+  return callDblabApi<T>({
+    apiKey, apiBaseUrl, instanceId,
+    action: "/branches", method: "get",
+    operation: "Failed to list branches", debug,
+  });
+}
+
+export interface CreateBranchParams extends DblabCommon {
+  branchName: string;
+  /** Parent branch to fork from. */
+  baseBranch?: string;
+  /** Snapshot id to base the branch on. */
+  snapshotId?: string;
+}
+
+/** Create a branch — `/branch` POST (Console `createBranch`). */
+export async function createBranch<T = unknown>(params: CreateBranchParams): Promise<T> {
+  const { apiKey, apiBaseUrl, instanceId, branchName, baseBranch, snapshotId, debug } = params;
+  if (!branchName) throw new Error("branchName is required");
+  const data: Record<string, unknown> = { branchName };
+  if (baseBranch) data.baseBranch = baseBranch;
+  if (snapshotId) data.snapshotID = snapshotId;
+  return callDblabApi<T>({
+    apiKey, apiBaseUrl, instanceId,
+    action: "/branch", method: "post", data,
+    operation: "Failed to create branch", debug,
+  });
+}
+
+export interface BranchNameParams extends DblabCommon {
+  branchName: string;
+}
+
+/** Delete a branch — `/branch/<name>` DELETE (Console `deleteBranch`). */
+export async function deleteBranch<T = unknown>(params: BranchNameParams): Promise<T> {
+  const { apiKey, apiBaseUrl, instanceId, branchName, debug } = params;
+  if (!branchName) throw new Error("branchName is required");
+  return callDblabApi<T>({
+    apiKey, apiBaseUrl, instanceId,
+    action: `/branch/${encodeURIComponent(branchName)}`, method: "delete",
+    operation: "Failed to delete branch", debug,
+  });
+}
+
+/** List a branch's snapshot log — `/branch/<name>/log` GET (Console `getSnapshotList`). */
+export async function branchLog<T = unknown>(params: BranchNameParams): Promise<T> {
+  const { apiKey, apiBaseUrl, instanceId, branchName, debug } = params;
+  if (!branchName) throw new Error("branchName is required");
+  return callDblabApi<T>({
+    apiKey, apiBaseUrl, instanceId,
+    action: `/branch/${encodeURIComponent(branchName)}/log`, method: "get",
+    operation: "Failed to fetch branch log", debug,
+  });
+}
+
+// ===========================================================================
+// Snapshots — list / create / destroy
+// ===========================================================================
+
+export interface ListSnapshotsParams extends DblabCommon {
+  /** Filter snapshots by branch. */
+  branchName?: string;
+  /** Filter snapshots by dataset. */
+  dataset?: string;
+}
+
+/** List snapshots — `/snapshots[?branch=&dataset=]` GET (Console `getSnapshots`). */
+export async function listSnapshots<T = unknown>(params: ListSnapshotsParams): Promise<T> {
+  const { apiKey, apiBaseUrl, instanceId, branchName, dataset, debug } = params;
+  const qs = new URLSearchParams();
+  const branch = branchName?.trim();
+  if (branch) qs.append("branch", branch);
+  if (dataset) qs.append("dataset", dataset);
+  const action = `/snapshots${qs.toString() ? `?${qs.toString()}` : ""}`;
+  return callDblabApi<T>({
+    apiKey, apiBaseUrl, instanceId,
+    action, method: "get",
+    operation: "Failed to list snapshots", debug,
+  });
+}
+
+export interface CreateSnapshotParams extends DblabCommon {
+  /** Clone to snapshot. */
+  cloneId: string;
+  /** Optional snapshot message. */
+  message?: string;
+}
+
+/** Create a snapshot from a clone — `/branch/snapshot` POST (Console `createSnapshot`). */
+export async function createSnapshot<T = unknown>(params: CreateSnapshotParams): Promise<T> {
+  const { apiKey, apiBaseUrl, instanceId, cloneId, message, debug } = params;
+  if (!cloneId) throw new Error("cloneId is required");
+  const data: Record<string, unknown> = { cloneID: cloneId };
+  if (message) data.message = message;
+  return callDblabApi<T>({
+    apiKey, apiBaseUrl, instanceId,
+    action: "/branch/snapshot", method: "post", data,
+    operation: "Failed to create snapshot", debug,
+  });
+}
+
+export interface DestroySnapshotParams extends DblabCommon {
+  snapshotId: string;
+  /** Force-delete even when dependent clones exist. */
+  force?: boolean;
+}
+
+/** Destroy a snapshot — `/snapshot/<id>?force=<bool>` DELETE (Console `destroySnapshot`). */
+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)}`;
+  return callDblabApi<T>({
+    apiKey, apiBaseUrl, instanceId,
+    action, method: "delete",
+    operation: "Failed to destroy snapshot", debug,
+  });
+}

package/lib/init.ts

@@ -924,14 +924,6 @@ export async function verifyInitSetup(params: {
     }
 
     // Check for helper functions
-    const explainFnRes = await params.client.query(
-      "select has_function_privilege($1, 'postgres_ai.explain_generic(text, text, text)', 'EXECUTE') as ok",
-      [role]
-    );
-    if (!explainFnRes.rows?.[0]?.ok) {
-      missingRequired.push("EXECUTE on postgres_ai.explain_generic(text, text, text)");
-    }
-
     const tableDescribeFnRes = await params.client.query(
       "select has_function_privilege($1, 'postgres_ai.table_describe(text)', 'EXECUTE') as ok",
       [role]