@databricks-solutions/lakebase-scm-utils 0.3.9 → 0.3.11

package/scripts/lakebase/branch.cli.ts

@@ -39,6 +39,9 @@ interface ParsedArgs {
   instance?: string;
   branch?: string;
   parentBranch?: string;
+  fromSnapshot?: string;
+  atTime?: string;
+  atLsn?: string;
   ttl?: string;
   noExpiry?: boolean;
   cwd?: string;
@@ -85,6 +88,15 @@ function parseArgs(argv: string[]): ParsedArgs {
       case "--parent-branch":
         out.parentBranch = argv[++i];
         break;
+      case "--from-snapshot":
+        out.fromSnapshot = argv[++i];
+        break;
+      case "--at-time":
+        out.atTime = argv[++i];
+        break;
+      case "--at-lsn":
+        out.atLsn = argv[++i];
+        break;
       case "--ttl":
         out.ttl = argv[++i];
         break;
@@ -259,6 +271,9 @@ async function main(): Promise<number> {
           host: args.host,
           branch: args.branch!,
           parentBranch: args.parentBranch,
+          fromSnapshot: args.fromSnapshot,
+          sourceBranchTime: args.atTime,
+          sourceBranchLsn: args.atLsn,
           ttl: args.ttl,
           noExpiry: args.noExpiry,
         });

package/scripts/lakebase/create-preflight.ts

@@ -19,7 +19,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { deleteLakebaseProject } from "./lakebase-project.js";
 import { runDatabricks } from "./databricks-cli.js";
-import { checkGitHubScopes } from "../github/repo.js";
+import { checkGitHubScopes, getCurrentUser, repoExists, type GitHubScopeStatus } from "../github/repo.js";
 
 export interface PreflightResult {
   ok: boolean;
@@ -145,6 +145,134 @@ export async function checkGitHubWorkflowScope(
   }
 }
 
+export interface GitHubPreflightInput {
+  /** Target repo owner (user or org). */
+  owner: string;
+  /** Bare repo name (the project name). */
+  repoName: string;
+  /** Scopes whose absence BLOCKS the happy path (create + push). Default ["repo","workflow"]. */
+  hardScopes?: readonly string[];
+  /** Scopes whose absence only WARNS (e.g. delete_repo, needed for rollback repo-delete). Default ["delete_repo"]. */
+  advisoryScopes?: readonly string[];
+  /** Injected probes (default to the real GitHub reads). */
+  currentUser?: () => Promise<string>;
+  scopes?: (required: readonly string[]) => Promise<GitHubScopeStatus>;
+  repoExists?: (fullName: string) => Promise<boolean>;
+}
+
+export interface GitHubPreflightResult extends PreflightResult {
+  /** Non-blocking notes (org/owner mismatch, missing advisory scope, invisible scopes). */
+  warnings: string[];
+  /** The resolved authenticated login, when B1 succeeded. */
+  activeUser?: string;
+}
+
+/**
+ * One up-front GitHub preflight run BEFORE any repo / Lakebase project is created,
+ * so a missing requisite fails in seconds with a fix instead of mid-create (where
+ * it orphans partially-created artifacts). Supersedes the workflow-only check:
+ *
+ *   B1  active account   getCurrentUser() must resolve (a valid token) — else a
+ *                        wrong/absent token otherwise 403s LATE at the push.
+ *   B2  scope set        checkGitHubScopes([...hard, ...advisory]): a missing HARD
+ *                        scope (repo/workflow) fails; a missing ADVISORY scope
+ *                        (delete_repo) warns (rollback repo-delete unavailable);
+ *                        granted null (fine-grained PAT / App) can't be asserted.
+ *   B3  name availability  repoExists(owner/name) → fail before anything exists.
+ *   B4  owner note       login != owner ⇒ creating under an org/other account —
+ *                        surfaced (createRepo enforces the real org-create right).
+ *
+ * CONSERVATIVE: hard-fails ONLY on the clear blockers (invalid token, missing
+ * happy-path scope, name taken); every other uncertainty is a warning, never a
+ * false block (same ethos as checkGitHubWorkflowScope). All probes injected, so
+ * this is unit-testable with no network.
+ */
+export async function checkGitHubPreflight(input: GitHubPreflightInput): Promise<GitHubPreflightResult> {
+  const warnings: string[] = [];
+  const hard = input.hardScopes ?? ["repo", "workflow"];
+  const advisory = input.advisoryScopes ?? ["delete_repo"];
+  const currentUserProbe = input.currentUser ?? getCurrentUser;
+  const scopesProbe = input.scopes ?? ((req: readonly string[]) => checkGitHubScopes(req));
+  const repoExistsProbe = input.repoExists ?? repoExists;
+
+  // B1: active account — a valid token. Hard blocker; nothing downstream works without it.
+  let activeUser: string;
+  try {
+    activeUser = await currentUserProbe();
+  } catch (err) {
+    return {
+      ok: false,
+      warnings,
+      reason:
+        `GitHub authentication failed: ${err instanceof Error ? err.message : String(err)}. ` +
+        "Sign in with `gh auth login`, or set GITHUB_TOKEN to a valid token, then re-run.",
+    };
+  }
+
+  // B4 (note): a login different from the owner means an org (or another account).
+  // Not a hard block — createRepo surfaces the real org-create permission — but
+  // surface it so a wrong active account is visible BEFORE the push's late 403.
+  if (activeUser.toLowerCase() !== input.owner.toLowerCase()) {
+    warnings.push(
+      `Signed in to GitHub as "${activeUser}" but creating under "${input.owner}" (an org or another account); ` +
+        `ensure "${activeUser}" can create repositories there.`,
+    );
+  }
+
+  // B2: the full required scope set — not just `workflow`.
+  try {
+    const { granted, missing } = await scopesProbe([...hard, ...advisory]);
+    if (granted !== null) {
+      const missingHard = missing.filter((s) => hard.includes(s));
+      const missingAdvisory = missing.filter((s) => advisory.includes(s));
+      if (missingHard.length > 0) {
+        return {
+          ok: false,
+          warnings,
+          activeUser,
+          reason:
+            `GitHub token missing required scope(s): ${missingHard.join(", ")} ` +
+            `(grants [${granted.join(", ") || "none"}]). Fix: gh auth refresh -h github.com -s ${[...hard].join(",")}`,
+        };
+      }
+      if (missingAdvisory.length > 0) {
+        warnings.push(
+          `GitHub token missing the ${missingAdvisory.join(", ")} scope — automatic rollback of the repo on a failed ` +
+            "create is unavailable (you would delete it by hand). Grant it with: gh auth refresh -h github.com -s delete_repo",
+        );
+      }
+    } else {
+      warnings.push(
+        "GitHub token scopes are not visible (fine-grained PAT or App token); cannot pre-verify repo/workflow access , " +
+          "the create will surface any gap when it pushes.",
+      );
+    }
+  } catch {
+    warnings.push("Could not read GitHub token scopes (probe error); skipping the scope pre-check.");
+  }
+
+  // B3: name availability — fail before anything is created.
+  try {
+    if (await repoExistsProbe(`${input.owner}/${input.repoName}`)) {
+      return {
+        ok: false,
+        warnings,
+        activeUser,
+        reason:
+          `GitHub repo "${input.owner}/${input.repoName}" already exists. ` +
+          "Pick a different project name, or delete the existing repo first.",
+      };
+    }
+  } catch {
+    warnings.push(
+      `Could not check whether "${input.owner}/${input.repoName}" already exists (probe error); ` +
+        "the create will fail clearly if it does.",
+    );
+  }
+
+  return { ok: true, warnings, activeUser };
+}
+
 /** The actionable prereq message for a GitHub token missing the `workflow` scope. */
 export function githubWorkflowScopePrereqMessage(reason?: string): string {
   return (
@@ -258,3 +386,87 @@ export async function withLakebaseRollback<T>(opts: RollbackOptions, fn: () => P
     throw wrapped;
   }
 }
+
+export interface RollbackStep {
+  label: string;
+  undo: () => Promise<void> | void;
+}
+
+export interface RollbackLedger {
+  /** Record a teardown for a resource the moment it is created. */
+  register(label: string, undo: () => Promise<void> | void): void;
+  /** The steps, in registration order (teardown runs them REVERSED). */
+  steps(): readonly RollbackStep[];
+}
+
+/** A created-resources ledger for the full create flow (A3). */
+export function createRollbackLedger(): RollbackLedger {
+  const steps: RollbackStep[] = [];
+  return {
+    register: (label, undo) => {
+      steps.push({ label, undo });
+    },
+    steps: () => steps,
+  };
+}
+
+export interface CreateRollbackOptions {
+  report?: (step: string, detail?: string) => void;
+}
+
+/**
+ * A3: run `fn`; on a throw, tear down EVERY resource the ledger recorded, in
+ * REVERSE order (last-created first), then rethrow with a summary of what was
+ * and wasn't cleaned up.
+ *
+ * Unlike {@link withLakebaseRollback} (Lakebase project only), this undoes the
+ * GitHub repo, the self-hosted runner, the local dir, AND the Lakebase project
+ * together — so a genuine provisioning fault leaves a clean "name is free" state
+ * instead of orphaning three of the four artifacts (the exact 4-artifact manual
+ * cleanup the cold-download incident caused). A step's own failure is captured +
+ * reported, never thrown, so one stuck teardown can't block the others; a
+ * "not found" teardown counts as already-gone. The caller registers a step the
+ * instant each resource is created, so a failure anywhere inside `fn` rolls back
+ * exactly what existed at that point.
+ */
+export async function withCreateRollback<T>(
+  ledger: RollbackLedger,
+  opts: CreateRollbackOptions,
+  fn: () => Promise<T>,
+): Promise<T> {
+  try {
+    return await fn();
+  } catch (err) {
+    const report = opts.report ?? (() => {});
+    const steps = [...ledger.steps()].reverse();
+    const rolledBack: string[] = [];
+    const failed: string[] = [];
+    if (steps.length > 0) report(`Create failed; rolling back ${steps.length} created resource(s)...`);
+    for (const s of steps) {
+      try {
+        report(`  rolling back: ${s.label}`);
+        await s.undo();
+        rolledBack.push(s.label);
+      } catch (e) {
+        const m = e instanceof Error ? e.message : String(e);
+        if (/not.?found/i.test(m)) {
+          rolledBack.push(s.label);
+          continue;
+        }
+        failed.push(`${s.label} (${m})`);
+      }
+    }
+    const base = err instanceof Error ? err.message : String(err);
+    const parts: string[] = [];
+    if (rolledBack.length) parts.push(`rolled back: ${rolledBack.join(", ")}`);
+    if (failed.length) {
+      parts.push(
+        `COULD NOT roll back: ${failed.join("; ")} , clean these up by hand before retrying the same name`,
+      );
+    }
+    const suffix = parts.length ? ` (${parts.join("; ")})` : "";
+    const wrapped = err instanceof Error ? err : new Error(base);
+    wrapped.message = `${base}${suffix}`;
+    throw wrapped;
+  }
+}

package/scripts/lakebase/create-project.ts

@@ -9,20 +9,23 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { writeEnvFile } from "./env-file.js";
 import { verifyProject, verifyHooks, verifyWorkflows } from "./project-verify.js";
-import { createRepo, getRepoFullName, getCurrentUser } from "../github/repo.js";
+import { createRepo, getRepoFullName, getCurrentUser, deleteRepo } from "../github/repo.js";
 import { cloneRepo } from "../git/clone.js";
 import { gitInit } from "../git/init.js";
-import { commitAndPush } from "../git/commit-push.js";
+import { commitInitial, pushInitial, WorkflowScopeError } from "../git/commit-push.js";
 import {
   createLakebaseProject,
   getDefaultBranchId,
+  deleteLakebaseProject,
 } from "./lakebase-project.js";
 import {
   checkDatabricksAuth,
   databricksAuthPrereqMessage,
-  checkGitHubWorkflowScope,
-  githubWorkflowScopePrereqMessage,
-  withLakebaseRollback,
+  checkGitHubPreflight,
+  warmAndVerifyKit,
+  kitWarmWarning,
+  createRollbackLedger,
+  withCreateRollback,
   validateCreateInputs,
   dirIsEmpty,
 } from "./create-preflight.js";
@@ -32,7 +35,7 @@ import { createLongRunningBranch } from "./long-running-branch.js";
 import { enableE2eForProject } from "./enable-e2e.js";
 import { ensureClientLockfile } from "./client-lockfile.js";
 import { enableInfraForProject } from "./enable-infra.js";
-import { setupRunner } from "./runner-setup.js";
+import { setupRunner, removeRunner } from "./runner-setup.js";
 import { syncCiSecrets, missingCiSecrets } from "../util/ci-secrets.js";
 import { delay } from "../util/delay.js";
 import {
@@ -291,19 +294,33 @@ export async function createProject(
     throw new Error(databricksAuthPrereqMessage(host, auth.reason));
   }
 
-  // ── GitHub token `workflow` scope precondition ────────────────
-  // The scaffold's final push commits .github/workflows/*, which GitHub rejects
-  // unless the token carries the `workflow` OAuth scope. Check it HERE, before any
-  // GitHub repo or Lakebase project exists, so a missing scope fails in seconds with
-  // a fix instead of at the final push after all provisioning (which then rolls back).
+  // ── GitHub account + requisites precondition (B) ──────────────
+  // ONE up-front GitHub preflight, BEFORE any repo / Lakebase project exists, so a
+  // missing requisite fails in seconds with a fix instead of mid-create (where it
+  // orphans partial artifacts): the active account resolves (else a wrong/absent
+  // token 403s LATE at the push), the full required scope set is present (repo +
+  // workflow — not just workflow), and the repo name is free. Conservative: notes
+  // (owner/org mismatch, invisible/advisory scopes) are surfaced but never block.
   if (useGithub) {
-    report("Checking GitHub token scopes...");
-    const scope = await checkGitHubWorkflowScope();
-    if (!scope.ok) {
-      throw new Error(githubWorkflowScopePrereqMessage(scope.reason));
+    report("Checking GitHub account + token requisites...");
+    const gh = await checkGitHubPreflight({ owner: input.githubOwner!, repoName: input.projectName });
+    for (const w of gh.warnings) {
+      warnings.push(w);
+      report(`Note: ${w}`);
     }
+    if (!gh.ok) throw new Error(gh.reason);
   }
 
+  // The created-resources ledger (A3): each resource registers its teardown the
+  // moment it is created, and a genuine provisioning throw inside the wrapper below
+  // rolls back ALL of them in reverse — the GitHub repo, the runner, the local dir,
+  // AND the Lakebase project together — leaving a clean "name is free" state (not
+  // the old 4-artifact orphan where only the Lakebase project was undone). A
+  // push-only failure is caught locally below and is NOT a provisioning throw, so
+  // it never triggers a rollback.
+  const rollback = createRollbackLedger();
+  return await withCreateRollback(rollback, { report }, async (): Promise<CreateProjectResult> => {
+
   // ── Step 1+2: GitHub repo + clone, OR local-only setup ────────
   if (useGithub) {
     report("Creating GitHub repository...", fullRepoName);
@@ -311,6 +328,7 @@ export async function createProject(
       private: input.privateRepo !== false,
       description: `Lakebase project: ${input.projectName}`,
     });
+    rollback.register(`GitHub repo ${fullRepoName}`, () => deleteRepo(fullRepoName));
 
     report("Waiting for GitHub repo to be visible...", fullRepoName);
     const probeDelays = [1000, 2000, 3000, 5000, 8000];
@@ -349,25 +367,23 @@ export async function createProject(
       repoUrl: `https://github.com/${fullRepoName}.git`,
       parentDir: input.parentDir,
     });
+    rollback.register(`local project dir ${projectDir}`, () => fs.rmSync(projectDir, { recursive: true, force: true }));
   } else {
     report("Creating local project directory...", projectDir);
     // A pre-existing EMPTY dir is accepted (validated up front); mkdir with
     // recursive is a no-op on it. A non-empty dir was already rejected.
     fs.mkdirSync(projectDir, { recursive: true });
     await gitInit(projectDir);
+    rollback.register(`local project dir ${projectDir}`, () => fs.rmSync(projectDir, { recursive: true, force: true }));
   }
 
   // ── Step 3: Lakebase project ──────────────────────────────────
   report("Creating Lakebase database (provisioning Postgres)...", lakebaseProjectId);
   await createLakebaseProject({ projectId: lakebaseProjectId, host });
-
-  // From here on the Lakebase project EXISTS. If any later step throws, roll it
-  // back (W9) so the slug isn't orphaned , a retry with the same name would
-  // otherwise collide with the reserved/soft-deleted slug. The wrapper rethrows
-  // with rollback context.
-  return await withLakebaseRollback(
-    { projectId: lakebaseProjectId, host, report },
-    async (): Promise<CreateProjectResult> => {
+  // From here on the Lakebase project EXISTS; register its teardown so a later
+  // provisioning throw rolls it back (W9) alongside the repo + dir above — a retry
+  // with the same name would otherwise collide with the reserved/soft-deleted slug.
+  rollback.register(`Lakebase project ${lakebaseProjectId}`, () => deleteLakebaseProject({ projectId: lakebaseProjectId, host }));
 
   // ── Step 4: Default branch lookup (non-fatal if not ready yet) ─
   report("Resolving database endpoint...");
@@ -481,6 +497,11 @@ export async function createProject(
         projectName: input.projectName,
         report: (m) => report(m),
       });
+      // Registered only after a SUCCESSFUL setup, so a provisioning throw later
+      // tears the runner down (stop + deregister + rm dir) alongside the rest.
+      rollback.register(`self-hosted runner ${input.projectName}`, () =>
+        removeRunner({ fullRepoName, projectName: input.projectName }),
+      );
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       warnings.push(`Runner setup failed: ${msg}`);
@@ -594,6 +615,25 @@ export async function createProject(
     );
   }
 
+  // ── Step 7g: pre-warm the toolkit so the first push doesn't cold-download mid-hook (A1) ──
+  // The scaffolded project's pre-push hook runs `./scripts/lk`, which triggers the
+  // one-time cold download of the Consort toolkit (hundreds of npm fetches). If that
+  // very first `lk` is the PUSH's hook, the heavy download races the push and the push
+  // fails (the cold-download incident). Warming HERE — after the scaffold laid down
+  // scripts/lk, before the push — makes the hook find a populated cache. Best-effort
+  // with ONE retry: if warming still fails we do NOT block create (the push then
+  // cold-downloads itself, exactly as before, and the retriable push below absorbs it).
+  if (enableSftdd && useGithub) {
+    report("Warming the Consort toolkit (so the first push doesn't cold-download mid-hook)...");
+    let warm = warmAndVerifyKit(projectDir);
+    if (!warm.ok) warm = warmAndVerifyKit(projectDir);
+    if (!warm.ok) {
+      const m = kitWarmWarning(projectDir, warm.reason);
+      warnings.push(m);
+      report(`Note: ${m}`);
+    }
+  }
+
   // ── Step 8: Initial commit (+ push when GitHub configured) ────
   const langLabels: Record<string, string> = {
     java: "Java/Spring Boot",
@@ -622,11 +662,29 @@ export async function createProject(
   }
 
   report("Creating initial commit...");
-  await commitAndPush({
-    projectDir,
-    message: `Initial project scaffold (${langLabel} + Lakebase)`,
-    push: useGithub,
-  });
+  await commitInitial(projectDir, `Initial project scaffold (${langLabel} + Lakebase)`);
+  // The commit is now LOCAL on disk. A push failure after this point is RETRIABLE,
+  // NOT a provisioning fault (A2): repo + Lakebase + runner + scaffold all succeeded,
+  // so tearing them down for a transient first-push cold download is wrong. Push with
+  // ONE retry (the toolkit is cached after the warm above / the first hook run); if it
+  // STILL fails, leave every resource intact and print the one-line resume — do NOT
+  // throw (which would fire the rollback ledger). A real `workflow`-scope rejection is
+  // not transient and IS surfaced as a hard error.
+  let pushLanded = !useGithub; // local-only: nothing to push → treat as landed
+  if (useGithub) {
+    try {
+      await pushInitial({ projectDir, attempts: 2 });
+      pushLanded = true;
+    } catch (err) {
+      if (err instanceof WorkflowScopeError) throw err;
+      const msg = err instanceof Error ? err.message : String(err);
+      const m =
+        `Provisioning is complete, but the initial push did not land after a retry: ${msg}. ` +
+        `The project on disk is fine , finish it with: cd ${projectDir} && git push -u origin main`;
+      warnings.push(m);
+      report(`WARNING: ${m}`);
+    }
+  }
 
   // ── Step 8b: Long-running tier setup (architectural choice) ───
   // Tier semantics (features are NOT tiers, they are short-lived branches):
@@ -644,7 +702,17 @@ export async function createProject(
   // origin to already have the parent ref (e.g. main, staging).
   // tiers 2/3 with --no-github is rejected up front by validateCreateInputs, so
   // by here useGithub is guaranteed true for any tiers>1 request.
-  if (tiers === 2 || tiers === 3) {
+  // Skip cleanly when the initial push did NOT land (A2): createLongRunningBranch
+  // forks off origin/main, which does not exist yet — cutting a tier now would fail.
+  // Surface the deferral so the user cuts the tiers after finishing the push.
+  if ((tiers === 2 || tiers === 3) && !pushLanded) {
+    const m =
+      `INCOMPLETE TIERS: you requested ${tiers} tiers, but the initial push hasn't landed, so the ` +
+      `tier branches can't fork off origin yet. After you finish the push (above), cut them with ` +
+      `\`./scripts/lk lakebase-cut-tier --name staging --fork-from main\`${tiers === 3 ? " and \`--name dev --fork-from staging\`" : ""}.`;
+    warnings.push(m);
+    report(`WARNING: ${m}`);
+  } else if (tiers === 2 || tiers === 3) {
     report(`Cutting staging tier (tiers=${tiers}) via createLongRunningBranch...`);
     try {
       await createLongRunningBranch({
@@ -712,7 +780,7 @@ export async function createProject(
     warnings,
   };
 
-    } // end withLakebaseRollback closure
+    } // end withCreateRollback closure
   );
 }
 

package/scripts/lakebase/get-connection.ts

@@ -136,7 +136,6 @@ export async function getConnection(args: ConnectionArgs): Promise<DsnResult | P
 
   // output === "pool"
   const host = await resolveEndpointHost(args.instance, branchId);
-  const email = await resolveCurrentUser();
   // Label the POOLED path too , it is the PRIMARY one (schema-diff, reconcile-tier). Passing
   // application_name in createLakebasePool's config does NOT work: it builds its own pg
   // PoolConfig and drops the field (verified live , the pooled connection came back with an
@@ -145,17 +144,35 @@ export async function getConnection(args: ConnectionArgs): Promise<DsnResult | P
   // call time (not import) so CONSORT_VERSION , which Consort exports at its entry point , is
   // already in the env when connectionApplicationName() reads it.
   process.env.PGAPPNAME = connectionApplicationName();
-  return createLakebasePool({
-    endpoint: endpointPath,
-    host,
-    database,
-    user: email,
-    // workspaceClient is passed through verbatim. createLakebasePool falls
-    // back to environment / ServiceContext when omitted.
-    ...(args.workspaceClient !== undefined
-      ? { workspaceClient: args.workspaceClient as never }
-      : {}),
-  });
+
+  // AppKit OBO: an explicit workspaceClient is a pre-authenticated caller , keep the
+  // OAuth/token-rotation path with it verbatim.
+  if (args.workspaceClient !== undefined) {
+    const email = await resolveCurrentUser();
+    return createLakebasePool({
+      endpoint: endpointPath,
+      host,
+      database,
+      user: email,
+      workspaceClient: args.workspaceClient as never,
+    });
+  }
+
+  // CLI/kit path (no workspaceClient): DO NOT let createLakebasePool self-authenticate
+  // via the SDK default chain. That runs `databricks auth token --host <workspace-host>`
+  // WITHOUT a profile, so when several ~/.databrickscfg profiles match that host (e.g.
+  // DEFAULT + an adb-* + logfood all pointing at the same workspace) the CLI refuses
+  // ("Use --profile to specify which profile to use") and the pool connection fails
+  // ("default auth: databricks-cli: cannot get access token"). That silently broke
+  // schema-diff at deploy-verify (the diff came back empty, failing the schema-diff
+  // test) whenever the host was ambiguous. Instead MINT the credential through the
+  // kit's profile-threaded CLI wrapper (mintCredential -> runDatabricksSync -> the
+  // resolved `--profile`, the same unambiguous path the DSN output uses) and pass it as
+  // `password`: LakebasePoolConfig skips OAuth entirely when a password is supplied. The
+  // kit's pool consumers (schema-diff, reconcile-tier) are short batch reads, well inside
+  // the credential TTL, so forgoing token rotation here is safe.
+  const { token, email } = await mintCredential(endpointPath);
+  return createLakebasePool({ host, database, user: email, password: token });
 }
 
 /**

package/scripts/lakebase/snapshot.cli.ts

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// CLI for Lakebase SNAPSHOTS: `lakebase-snapshot <create|delete|list> ...`.
+//
+// A snapshot is an immutable point-in-time copy of a branch. Capture the
+// committed schema once, then branch copy-on-write from it per verify cycle
+// (`lakebase-branch create --from-snapshot <id>`) instead of re-running
+// `alembic upgrade head`. Prints JSON on stdout, errors on stderr.
+//   0 = success   1 = runtime error   2 = usage error
+import { createSnapshot, deleteSnapshot, listSnapshots } from "./snapshot.js";
+
+interface Args {
+  subcommand?: string;
+  instance?: string;
+  snapshot?: string;
+  branch?: string;
+  atTime?: string;
+  atLsn?: string;
+  ttl?: string;
+  noExpiry?: boolean;
+  host?: string;
+  pretty?: boolean;
+  help?: boolean;
+}
+
+function parseArgs(argv: string[]): Args {
+  const out: Args = {};
+  let i = 0;
+  if (argv[0] && !argv[0].startsWith("-")) {
+    out.subcommand = argv[0];
+    i = 1;
+  }
+  for (; i < argv.length; i++) {
+    switch (argv[i]) {
+      case "--instance": out.instance = argv[++i]; break;
+      case "--snapshot": out.snapshot = argv[++i]; break;
+      case "--branch": out.branch = argv[++i]; break;
+      case "--at-time": out.atTime = argv[++i]; break;
+      case "--at-lsn": out.atLsn = argv[++i]; break;
+      case "--ttl": out.ttl = argv[++i]; break;
+      case "--no-expiry": out.noExpiry = true; break;
+      case "--host": out.host = argv[++i]; break;
+      case "--pretty": out.pretty = true; break;
+      case "--help": case "-h": out.help = true; break;
+    }
+  }
+  return out;
+}
+
+const USAGE = `usage: lakebase-snapshot <create|delete|list> --instance <project> [flags]
+  create  --snapshot <id> --branch <src> [--at-time <iso> | --at-lsn <lsn>] [--ttl <s> | --no-expiry]
+  delete  --snapshot <id>
+  list
+Then branch from it: lakebase-branch create --branch <v> --from-snapshot <id> --instance <project>`;
+
+function out(result: unknown, pretty: boolean): void {
+  process.stdout.write(JSON.stringify(result, null, pretty ? 2 : undefined) + "\n");
+}
+function need(a: Args, keys: (keyof Args)[]): boolean {
+  const missing = keys.filter((k) => a[k] === undefined || a[k] === "");
+  if (missing.length) {
+    process.stderr.write(`missing ${missing.map((k) => "--" + String(k)).join(", ")}\n${USAGE}\n`);
+    return false;
+  }
+  return true;
+}
+
+async function main(): Promise<number> {
+  const a = parseArgs(process.argv.slice(2));
+  if (a.help || !a.subcommand) {
+    process.stderr.write(USAGE + "\n");
+    return a.help ? 0 : 2;
+  }
+  switch (a.subcommand) {
+    case "create": {
+      if (!need(a, ["instance", "snapshot", "branch"])) return 2;
+      const raw = await createSnapshot({
+        instance: a.instance!,
+        snapshot: a.snapshot!,
+        sourceBranch: a.branch!,
+        sourceBranchTime: a.atTime,
+        sourceBranchLsn: a.atLsn,
+        ttl: a.ttl,
+        noExpiry: a.noExpiry,
+        host: a.host,
+      });
+      out({ created: a.snapshot, raw: raw.trim() || undefined }, !!a.pretty);
+      return 0;
+    }
+    case "delete": {
+      if (!need(a, ["instance", "snapshot"])) return 2;
+      await deleteSnapshot({ instance: a.instance!, snapshot: a.snapshot!, host: a.host });
+      out({ deleted: a.snapshot }, !!a.pretty);
+      return 0;
+    }
+    case "list": {
+      if (!need(a, ["instance"])) return 2;
+      const raw = await listSnapshots({ instance: a.instance!, host: a.host });
+      try {
+        out(JSON.parse(raw), !!a.pretty);
+      } catch {
+        process.stdout.write(raw);
+      }
+      return 0;
+    }
+    default:
+      process.stderr.write(`unknown subcommand '${a.subcommand}'\n${USAGE}\n`);
+      return 2;
+  }
+}
+
+main().then(
+  (code) => process.exit(code),
+  (err) => {
+    process.stderr.write(String(err instanceof Error ? err.message : err) + "\n");
+    process.exit(1);
+  },
+);