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

package/dist/scripts/lakebase/schema-migrate.cli.js

@@ -427,8 +427,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.10".length > 0) {
-    cached = "0.3.10";
+  if ("0.3.11".length > 0) {
+    cached = "0.3.11";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/scm-claim-feature.cli.cjs

@@ -79816,8 +79816,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.10".length > 0) {
-    cached = "0.3.10";
+  if ("0.3.11".length > 0) {
+    cached = "0.3.11";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/scm-claim-feature.cli.js

@@ -897,8 +897,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.10".length > 0) {
-    cached = "0.3.10";
+  if ("0.3.11".length > 0) {
+    cached = "0.3.11";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/scm-doctor.cli.cjs

@@ -88273,8 +88273,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.10".length > 0) {
-    cached = "0.3.10";
+  if ("0.3.11".length > 0) {
+    cached = "0.3.11";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/scm-doctor.cli.js

@@ -9426,8 +9426,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.10".length > 0) {
-    cached = "0.3.10";
+  if ("0.3.11".length > 0) {
+    cached = "0.3.11";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/scm-merge.cli.cjs

@@ -88825,8 +88825,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.10".length > 0) {
-    cached = "0.3.10";
+  if ("0.3.11".length > 0) {
+    cached = "0.3.11";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/scm-merge.cli.js

@@ -9978,8 +9978,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.10".length > 0) {
-    cached = "0.3.10";
+  if ("0.3.11".length > 0) {
+    cached = "0.3.11";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/scm-reconcile-tier.cli.cjs

@@ -79288,8 +79288,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.10".length > 0) {
-    cached = "0.3.10";
+  if ("0.3.11".length > 0) {
+    cached = "0.3.11";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/scm-reconcile-tier.cli.js

@@ -389,8 +389,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.10".length > 0) {
-    cached = "0.3.10";
+  if ("0.3.11".length > 0) {
+    cached = "0.3.11";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/util/index.cjs

@@ -1667,8 +1667,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.10".length > 0) {
-    cached = "0.3.10";
+  if ("0.3.11".length > 0) {
+    cached = "0.3.11";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/util/index.js

@@ -1630,8 +1630,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.10".length > 0) {
-    cached = "0.3.10";
+  if ("0.3.11".length > 0) {
+    cached = "0.3.11";
     return cached;
   }
   cached = "unknown";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@databricks-solutions/lakebase-scm-utils",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "description": "Lakebase SCM + substrate engine: database branching, paired-branch SCM workflows, connection/credential minting, schema migration, project scaffold + deploy primitives, and the git/github utility layer. Extracted from consort for portable, standalone consumption by lakebase-scm-extension and the SFTDD orchestration.",
   "type": "module",
   "private": false,

package/scripts/git/commit-push.ts

@@ -45,24 +45,70 @@ export class WorkflowScopeError extends Error {
  * For non-initial-commit flows, prefer the primitives in ./commits.ts.
  */
 export async function commitAndPush(args: CommitAndPushArgs): Promise<void> {
-  await exec("git add -A", { cwd: args.projectDir });
-  await exec(`git commit -m ${JSON.stringify(args.message)}`, {
-    cwd: args.projectDir,
+  await commitInitial(args.projectDir, args.message);
+  if (args.push === false) return;
+  await pushInitial({ projectDir: args.projectDir, remote: args.remote, branch: args.branch });
+}
+
+/** Stage everything and make the initial commit (no push). */
+export async function commitInitial(projectDir: string, message: string): Promise<void> {
+  await exec("git add -A", { cwd: projectDir });
+  await exec(`git commit -m ${JSON.stringify(message)}`, {
+    cwd: projectDir,
     timeout: 30_000,
   });
-  if (args.push === false) return;
+}
+
+export interface PushInitialArgs {
+  projectDir: string;
+  /** Remote name. Default: "origin". */
+  remote?: string;
+  /** Branch name. Default: "main". */
+  branch?: string;
+  /**
+   * Total push attempts (>= 1). Default 1 (preserves commitAndPush's behavior).
+   * The create flow passes 2: the FIRST push fires the project's pre-push hook,
+   * which triggers the one-time cold download of the Consort toolkit — that race
+   * can fail the push, but the toolkit is CACHED afterward, so a single retry then
+   * sails through (the cold-download incident). A `workflow`-scope rejection is a
+   * real auth gap, never retried.
+   */
+  attempts?: number;
+  /** Delay between attempts (ms). Default 1500. Injected in tests. */
+  delayMs?: number;
+  /** Injectable sleep (tests). */
+  sleep?: (ms: number) => Promise<void>;
+  /** Injectable runner (tests); defaults to the real `git push`. */
+  run?: (cmd: string, cwd: string) => Promise<void>;
+}
+
+/**
+ * Push the initial branch with `-u`, retrying a transient failure up to
+ * `attempts` times. Maps the GitHub `workflow`-scope rejection to
+ * {@link WorkflowScopeError} (thrown immediately, never retried). Throws the last
+ * error after the final attempt.
+ */
+export async function pushInitial(args: PushInitialArgs): Promise<void> {
   const remote = args.remote ?? "origin";
   const branch = args.branch ?? "main";
-  try {
-    await exec(`git push -u ${remote} ${branch}`, {
-      cwd: args.projectDir,
-      timeout: 30_000,
-    });
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    if (/without `?workflow`? scope|workflow scope/i.test(msg)) {
-      throw new WorkflowScopeError(args.projectDir);
+  const attempts = Math.max(1, args.attempts ?? 1);
+  const sleep = args.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const run =
+    args.run ??
+    ((cmd: string, cwd: string) => exec(cmd, { cwd, timeout: 30_000 }).then(() => undefined));
+  let lastErr: unknown;
+  for (let i = 1; i <= attempts; i++) {
+    try {
+      await run(`git push -u ${remote} ${branch}`, args.projectDir);
+      return;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (/without `?workflow`? scope|workflow scope/i.test(msg)) {
+        throw new WorkflowScopeError(args.projectDir);
+      }
+      lastErr = err;
+      if (i < attempts) await sleep(args.delayMs ?? 1500);
     }
-    throw err;
   }
+  throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
 }

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;
+  }
+}