postgresai 0.16.0-dev.10 → 0.16.0-dev.11

package/test/schema-validation.test.ts

@@ -99,6 +99,46 @@ describe("Schema validation", () => {
     validateAgainstSchema(report, "F003");
   });
 
+  for (const checkId of ["F004", "F005"]) {
+    test(`${checkId} distinguishes a healthy empty result from missing schema`, async () => {
+      const healthyClient = createMockClient();
+      const healthy = await checkup.REPORT_GENERATORS[checkId](healthyClient as any, "node-01");
+      const healthyDb = healthy.results["node-01"].data.testdb;
+      expect(healthyDb.status).toEqual({ ok: true, reason: null, error: null });
+      validateAgainstSchema(healthy, checkId);
+
+      const missingSchemaClient = createMockClient({
+        bloatCapabilityRows: [
+          { schema_exists: false, schema_usage: false, view_exists: false, view_select: false },
+        ],
+      });
+      const degraded = await checkup.REPORT_GENERATORS[checkId](missingSchemaClient as any, "node-01");
+      const degradedDb = degraded.results["node-01"].data.testdb;
+      expect(degradedDb.status).toEqual({
+        ok: false,
+        reason: "missing_schema",
+        error: 'schema "postgres_ai" does not exist',
+      });
+      validateAgainstSchema(degraded, checkId);
+    });
+
+    test(`${checkId} exposes missing-grant degradation`, async () => {
+      const client = createMockClient({
+        bloatCapabilityRows: [
+          { schema_exists: true, schema_usage: true, view_exists: true, view_select: false },
+        ],
+      });
+      const report = await checkup.REPORT_GENERATORS[checkId](client as any, "node-01");
+      const dbEntry = report.results["node-01"].data.testdb;
+      expect(dbEntry.status).toEqual({
+        ok: false,
+        reason: "missing_grant",
+        error: "permission denied for relation postgres_ai.pg_statistic",
+      });
+      validateAgainstSchema(report, checkId);
+    });
+  }
+
   // Settings reports (D004, F001, G001) - single test each
   for (const checkId of ["D004", "F001", "G001"]) {
     test(`${checkId} validates against schema`, async () => {

package/test/test-utils.ts

@@ -19,6 +19,7 @@ export interface MockClientOptions {
   indexBloatRows?: any[];
   deadTuplesRows?: any[];
   vacuumStatsRows?: any[];
+  bloatCapabilityRows?: any[];
   deadlockStatsRows?: any[];
   pgStatStatementsExtensionRows?: any[];
   pgStatStatementsStatsRows?: any[];
@@ -61,6 +62,7 @@ export function createMockClient(options: MockClientOptions = {}) {
     indexBloatRows = [],
     deadTuplesRows = [],
     vacuumStatsRows = [],
+    bloatCapabilityRows = [{ schema_exists: true, schema_usage: true, view_exists: true, view_select: true }],
     deadlockStatsRows = [{ deadlocks: "0", conflicts: "0", stats_reset: null }],
     pgStatStatementsExtensionRows = [],
     pgStatStatementsStatsRows = [],
@@ -128,6 +130,9 @@ export function createMockClient(options: MockClientOptions = {}) {
         return { rows: deadTuplesRows };
       }
       // F004/F005: bloat metrics from metrics.yml
+      if (sql.includes("to_regnamespace('postgres_ai')") && sql.includes("view_select")) {
+        return { rows: bloatCapabilityRows };
+      }
       if (sql.includes("tag_idxname") && sql.includes("bloat_size")) {
         return { rows: indexBloatRows };
       }

package/test/util.test.ts

@@ -101,6 +101,62 @@ describe("formatHttpError", () => {
     const msg = formatHttpError("op", 403, undefined, "Forbidden");
     expect(msg).toContain("Forbidden - access denied");
   });
+
+  // Behind an h2/h3 proxy the reason phrase is dropped (statusText is empty),
+  // so the PTxyz body fields are all we get — `code` and `hint` must surface.
+  // CLI half of https://gitlab.com/postgres-ai/platform-all/-/issues/537.
+  test("surfaces JSON body code and hint when the reason phrase is dropped (h2)", () => {
+    const msg = formatHttpError(
+      "Failed to submit plan command",
+      403,
+      '{"code":"PT403","details":"AI features disabled for this org","hint":"Enable AI in AI Assistant Settings"}',
+      "" // h2: no reason phrase
+    );
+    expect(msg).toContain("HTTP 403");
+    expect(msg).toContain("PT403");
+    expect(msg).toContain("AI features disabled for this org");
+    expect(msg).toContain("Hint: Enable AI in AI Assistant Settings");
+  });
+
+  test("surfaces code and hint alongside a body message", () => {
+    const msg = formatHttpError(
+      "op",
+      429,
+      '{"code":"PT429","message":"Rate limited","hint":"Retry in 60s"}'
+    );
+    expect(msg).toContain("Rate limited");
+    expect(msg).toContain("PT429");
+    expect(msg).toContain("Hint: Retry in 60s");
+  });
+
+  test("falls back to the raw (redacted) JSON body when no known fields are present", () => {
+    // Pre-existing callers (issues.ts/reports.ts/storage.ts) rely on unknown
+    // JSON error shapes still being surfaced — a body with none of
+    // message/error/details/detail/code/hint must not be silently dropped.
+    const msg = formatHttpError("op", 500, '{"weird_field":"boom","password":"pw-x"}');
+    expect(msg).toContain("HTTP 500");
+    expect(msg).toContain("weird_field");
+    expect(msg).toContain("boom");
+    expect(msg).not.toContain("pw-x");
+    expect(msg).toContain("[REDACTED]");
+  });
+
+  test("redacts credentials from every structured JSON error field and the reason phrase", () => {
+    const msg = formatHttpError(
+      "op",
+      400,
+      JSON.stringify({
+        message: "connStr=postgresql://joe:message-pw@db/app",
+        details: "password=detail-pw",
+        hint: "token=hint-token",
+      }),
+      "dsn=postgresql://joe:reason-pw@db/app"
+    );
+    expect(msg).toContain("[REDACTED]");
+    for (const secret of ["message-pw", "detail-pw", "hint-token", "reason-pw"]) {
+      expect(msg).not.toContain(secret);
+    }
+  });
 });
 
 describe("redactSecretsForLog", () => {
@@ -141,6 +197,18 @@ describe("redactSecretsForLog", () => {
     expect(out).toContain('"ok":"keep"');
   });
 
+  test("redacts alternate auth and credential key names", () => {
+    const out = redactSecretsForLog(JSON.stringify({
+      auth_key: "a",
+      db_pass: "b",
+      access_key: "c",
+      credential: "d",
+      ok: "keep",
+    }));
+    for (const secret of ["a", "b", "c", "d"]) expect(out).not.toContain(`\"${secret}\"`);
+    expect(out).toContain('"ok":"keep"');
+  });
+
   test("traverses arrays (e.g. result rows carrying a password column)", () => {
     const out = redactSecretsForLog(JSON.stringify({ rows: [{ usename: "app", password: "s3cr3t" }] }));
     expect(out).not.toContain("s3cr3t");
@@ -151,4 +219,52 @@ describe("redactSecretsForLog", () => {
     expect(redactSecretsForLog(JSON.stringify({ password: null }))).toContain('"password":null');
     expect(redactSecretsForLog("plain text, not json")).toBe("plain text, not json");
   });
+
+  test("does not redact benign keys that merely contain a sensitive substring", () => {
+    // /auth/ must not eat author/authorized_at, /token/ must not eat
+    // token_count, /cred/ must not eat credits — these are legitimate data
+    // fields in exec_sql / DBLab / bot results.
+    const out = redactSecretsForLog(JSON.stringify({
+      author: "alice",
+      authored_by: "bob",
+      authorized_at: "2026-01-01",
+      author_id: 12,
+      author_name: "Ada",
+      token_count: 42,
+      token_type: "bearer",
+      tokens: ["word"],
+      total_tokens: 7,
+      credits: 3,
+      credited_at: "2026-01-02",
+      password: "s3cr3t",
+      auth_key: "k1",
+    }));
+    expect(out).toContain('"author":"alice"');
+    expect(out).toContain('"authored_by":"bob"');
+    expect(out).toContain('"authorized_at":"2026-01-01"');
+    expect(out).toContain('"author_id":12');
+    expect(out).toContain('"author_name":"Ada"');
+    expect(out).toContain('"token_count":42');
+    expect(out).toContain('"token_type":"bearer"');
+    expect(out).toContain('"tokens":["word"]');
+    expect(out).toContain('"total_tokens":7');
+    expect(out).toContain('"credits":3');
+    expect(out).toContain('"credited_at":"2026-01-02"');
+    // real credentials still go
+    expect(out).not.toContain("s3cr3t");
+    expect(out).not.toContain('"k1"');
+  });
+
+  test("scrubs credential patterns from non-JSON text (error-path bodies)", () => {
+    // A non-JSON body flows into thrown Errors (parse-failure paths), so the
+    // text fallback must still scrub key=value credentials and URL userinfo.
+    const out = redactSecretsForLog(
+      'clone failed: connStr=postgresql://joe:pw-abc@host:6002/db password=hunter2 "secret": "s3cr3t" user=joe'
+    );
+    expect(out).not.toContain("pw-abc");
+    expect(out).not.toContain("hunter2");
+    expect(out).not.toContain("s3cr3t");
+    expect(out).toContain("[REDACTED]");
+    expect(out).toContain("user=joe");
+  });
 });

package/lib/dblab.ts

@@ -1,449 +0,0 @@
-/**
- * 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`). The destructive verbs — the HTTP DELETEs: clone
- * destroy (`DELETE /clone/<id>`), branch delete (`DELETE /branch/<name>`),
- * snapshot destroy (`DELETE /snapshot/<id>`) — are gated server-side by the
- * `joe:admin` scope (user-approved tightening, !612); clone reset is a POST and
- * is NOT gated. Read/list/create stay at org-token + project-allowlist level.
- * A missing scope on a DELETE surfaces here as a `PT403` → HTTP 403.
- */
-
-import { formatHttpError, maskSecret, normalizeBaseUrl, describeFetchError, redactSecretsForLog } 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)}`);
-    // Redact credential fields (clone create embeds --db-password) — the MCP
-    // caller controls the debug flag, so the raw body must never hit the log.
-    console.error(`Debug: Request body: ${redactSecretsForLog(body)}`);
-  }
-
-  let response: Response;
-  try {
-    response = await fetch(url.toString(), { method: "POST", headers, body });
-  } catch (err) {
-    // Transport failure (connection refused, DNS, TLS, bad host/port) — surface
-    // the real cause + URL rather than undici's opaque "fetch failed".
-    throw new Error(describeFetchError(operation, base, err));
-  }
-  const text = await response.text();
-
-  if (debug) {
-    console.error(`Debug: Response status: ${response.status}`);
-    // Clone create/status replies carry the live clone's db.password/connStr.
-    console.error(`Debug: Response body: ${redactSecretsForLog(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. The
-    // RPC's user-facing message rides in the HTTP reason phrase (statusText),
-    // not the JSON body — pass it through.
-    throw new Error(formatHttpError(operation, response.status, text, response.statusText));
-  }
-
-  // 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`).
- *
- * 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/${snapshotId}?force=${Boolean(force)}`;
-  return callDblabApi<T>({
-    apiKey, apiBaseUrl, instanceId,
-    action, method: "delete",
-    operation: "Failed to destroy snapshot", debug,
-  });
-}