postgresai 0.16.0-dev.2 → 0.16.0-dev.4

package/dist/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/dist/sql/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/lib/dblab.ts

@@ -0,0 +1,428 @@
+/**
+ * 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";
+import { listProjects, type ProjectListItem } from "./joe";
+
+// ---------------------------------------------------------------------------
+// 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
+//
+// 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. */
+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 projects listing). */
+  orgId?: number;
+  debug?: boolean;
+}
+
+/**
+ * Resolve `--project <id|alias>` to the project's single DBLab `instance_id`.
+ *
+ * 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> {
+  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>)");
+  }
+
+  let projects: ProjectListItem[];
+  try {
+    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 = projects.find((p) => {
+    if (numeric) {
+      return String(p.project_id) === ref;
+    }
+    return (
+      (p.alias !== null && p.alias.toLowerCase() === needle) ||
+      (p.name !== null && p.name.toLowerCase() === needle) ||
+      (p.label !== null && p.label.toLowerCase() === needle)
+    );
+  });
+
+  if (!match) {
+    throw new Error(
+      `No DBLab instance found for project '${ref}'. Run 'pgai projects' to see available projects.`
+    );
+  }
+  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);
+}
+
+// ---------------------------------------------------------------------------
+// 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,
+  });
+}