@databricks-solutions/lakebase-scm-utils 0.3.4 → 0.3.6

package/scripts/lakebase/create-preflight.ts

@@ -19,6 +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";
 
 export interface PreflightResult {
   ok: boolean;
@@ -113,6 +114,50 @@ export async function checkDatabricksAuth(
   }
 }
 
+/** Injectable scope probe for checkGitHubWorkflowScope (defaults to the real GitHub API read). */
+type ScopeProbe = () => Promise<{ granted: string[] | null; missing: string[] }>;
+
+/**
+ * W-workflow-scope: preflight the GitHub token's `workflow` OAuth scope BEFORE
+ * any repo / Lakebase project is created. The scaffold's FINAL push commits
+ * `.github/workflows/*`, which GitHub REJECTS unless the token carries
+ * `workflow` — without this, that rejection only surfaces at the very end,
+ * after all the provisioning, forcing a full rollback. Gating the ONE scope the
+ * push needs here turns that into an immediate, actionable failure.
+ *
+ * Non-blocking in two cases (ok:true): a token that exposes NO OAuth scopes
+ * (fine-grained PAT / GitHub App token — `granted` null; its workflow
+ * permission isn't visible this way, so we can't assert), and any probe error
+ * (a genuinely bad/absent token surfaces clearly at repo creation, not here).
+ */
+export async function checkGitHubWorkflowScope(
+  probe: ScopeProbe = () => checkGitHubScopes(["workflow"]),
+): Promise<PreflightResult> {
+  try {
+    const { granted, missing } = await probe();
+    if (granted === null) return { ok: true }; // scopes not visible → can't assert, don't false-fail
+    if (missing.includes("workflow")) {
+      return { ok: false, reason: `token grants [${granted.join(", ") || "none"}] but not \`workflow\`` };
+    }
+    return { ok: true };
+  } catch {
+    return { ok: true }; // best-effort: a probe failure must not block scaffold
+  }
+}
+
+/** The actionable prereq message for a GitHub token missing the `workflow` scope. */
+export function githubWorkflowScopePrereqMessage(reason?: string): string {
+  return (
+    "The GitHub token lacks the `workflow` OAuth scope, required to push the project's " +
+    "`.github/workflows/*` CI files. (Without this check, scaffolding runs all the way to the " +
+    "final push, is rejected, and rolls back.) Grant the scope, then re-run:\n" +
+    "  - gh CLI:  gh auth refresh -h github.com -s workflow\n" +
+    "  - VS Code: re-sign in to GitHub and approve the workflow scope\n" +
+    "  - token:   set GITHUB_TOKEN to a PAT that includes the `workflow` scope" +
+    (reason ? `\n(${reason})` : "")
+  );
+}
+
 /** The actionable prereq message for a failed auth probe (W5). */
 export function databricksAuthPrereqMessage(host?: string, reason?: string): string {
   const hostFlag = host ? ` --host ${host.replace(/\/+$/, "")}` : "";

package/scripts/lakebase/create-project.ts

@@ -20,6 +20,8 @@ import {
 import {
   checkDatabricksAuth,
   databricksAuthPrereqMessage,
+  checkGitHubWorkflowScope,
+  githubWorkflowScopePrereqMessage,
   withLakebaseRollback,
   validateCreateInputs,
   dirIsEmpty,
@@ -289,6 +291,19 @@ 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).
+  if (useGithub) {
+    report("Checking GitHub token scopes...");
+    const scope = await checkGitHubWorkflowScope();
+    if (!scope.ok) {
+      throw new Error(githubWorkflowScopePrereqMessage(scope.reason));
+    }
+  }
+
   // ── Step 1+2: GitHub repo + clone, OR local-only setup ────────
   if (useGithub) {
     report("Creating GitHub repository...", fullRepoName);

package/scripts/lakebase/doctor.ts

@@ -14,6 +14,7 @@ import { listBranches } from "./branch-utils.js";
 import { verifyHooks } from "./project-verify.js";
 import { detectLanguage } from "./schema-migrate.js";
 import { detectWorkflowDrift } from "./workflow-drift.js";
+import { checkGitHubScopes } from "../github/repo.js";
 
 export type CheckStatus = "ok" | "warn" | "fail" | "skip";
 
@@ -593,6 +594,53 @@ async function checkGitRemote(projectDir: string): Promise<CheckResult> {
   }
 }
 
+/**
+ * Probe whether the GitHub token carries the `workflow` scope needed to push
+ * `.github/workflows/*`. A missing scope is exactly why a scaffold push (or any
+ * later workflow edit) gets rejected at the very end and rolls back. Best-effort:
+ * no token, OR a fine-grained / GitHub App token (no visible OAuth scopes), OR
+ * an API error → `skip`, never a false `fail`. `probe` is injectable for tests.
+ */
+export async function checkGitHubTokenScope(
+  probe: () => Promise<{ granted: string[] | null; missing: string[] }> = () =>
+    checkGitHubScopes(["workflow"])
+): Promise<CheckResult> {
+  try {
+    const { granted, missing } = await probe();
+    if (granted === null) {
+      return {
+        name: "github-token-scope",
+        status: "skip",
+        message:
+          "GitHub token scopes not visible (fine-grained PAT / App token) - `workflow` scope unverified",
+      };
+    }
+    if (missing.includes("workflow")) {
+      return {
+        name: "github-token-scope",
+        status: "fail",
+        message:
+          "GitHub token lacks the `workflow` scope - pushes touching .github/workflows/* will be rejected",
+        detail: { granted },
+        hint: "Grant it with `gh auth refresh -h github.com -s workflow`, re-sign in to GitHub in VS Code and approve the workflow scope, or set GITHUB_TOKEN to a PAT that includes `workflow`.",
+      };
+    }
+    return {
+      name: "github-token-scope",
+      status: "ok",
+      message: "GitHub token has the `workflow` scope",
+      detail: { granted },
+    };
+  } catch (err) {
+    return {
+      name: "github-token-scope",
+      status: "skip",
+      message: "GitHub token scope check skipped (no token resolved, or GitHub unreachable)",
+      detail: { error: (err as Error).message },
+    };
+  }
+}
+
 function checkLanguage(projectDir: string): CheckResult {
   try {
     const lang = detectLanguage(projectDir);
@@ -732,6 +780,7 @@ export async function runDoctor(args: DoctorArgs = {}): Promise<DoctorReport> {
     host
   );
   const gitRemote = await checkGitRemote(projectDir);
+  const githubTokenScope = await checkGitHubTokenScope();
   const language = checkLanguage(projectDir);
   const hooks = checkHooks(projectDir);
   const workflowDrift = checkWorkflowDrift(projectDir);
@@ -763,6 +812,7 @@ export async function runDoctor(args: DoctorArgs = {}): Promise<DoctorReport> {
     configProfile,
     lakebaseProject,
     gitRemote,
+    githubTokenScope,
     language,
     hooks,
     workflowDrift,

package/scripts/lakebase/enable-e2e.ts

@@ -202,6 +202,19 @@ const RUN_TESTS_E2E_MARKER = "# run Playwright E2E suite when configured";
  */
 const CLIENT_E2E_MARKER = "# run client Playwright E2E suite when configured";
 
+/**
+ * The markers matched ONLY as standalone lines (the appended block's own opening
+ * comment lines), never as substrings. The base run-tests.sh TEMPLATE documents the
+ * E2E-assembly contract in a header comment that QUOTES RUN_TESTS_E2E_MARKER verbatim
+ * inside backticks; a substring `includes`/`indexOf` match there matched the prose
+ * mention and truncated the ENTIRE primary-suite body (the run-tests.sh clobber that
+ * silently made every honest-GREEN + deploy verify exit 0). A line-anchored (`^…$`,
+ * multiline) match only ever finds the real block, never the documentation comment.
+ */
+const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const RUN_TESTS_E2E_MARKER_LINE = new RegExp(`^${escapeRe(RUN_TESTS_E2E_MARKER)}$`, "m");
+const CLIENT_E2E_MARKER_LINE = new RegExp(`^${escapeRe(CLIENT_E2E_MARKER)}$`, "m");
+
 /** The full E2E block appended to run-tests.sh (project-root layout + Python +
  *  the client-workspace layout). Built once so the fresh-insert and the in-place
  *  upgrade write byte-identical content. */
@@ -307,16 +320,33 @@ export function addE2eToRunTestsScript(
     return { patched: false, inserted: false };
   }
   const original = fs.readFileSync(scriptPath, "utf8");
-  const hasBase = original.includes(RUN_TESTS_E2E_MARKER);
-  const hasClient = original.includes(CLIENT_E2E_MARKER);
+  // Match markers as standalone LINES, not substrings (see RUN_TESTS_E2E_MARKER_LINE):
+  // a prose mention in the template header must never be treated as the block boundary.
+  const baseMarker = RUN_TESTS_E2E_MARKER_LINE.exec(original);
+  const hasBase = baseMarker !== null;
+  const hasClient = CLIENT_E2E_MARKER_LINE.test(original);
   if (hasBase && hasClient) {
     return { patched: true, inserted: false }; // already the current block
   }
   // Truncate an OLD block (base marker present, client branch missing) so we replace
   // rather than duplicate; else append to the end after the language-specific suite.
-  const cut = hasBase ? original.slice(0, original.indexOf(RUN_TESTS_E2E_MARKER)) : original;
+  const cut = hasBase ? original.slice(0, baseMarker!.index) : original;
   const base = cut.replace(/\n+$/, "\n");
-  fs.writeFileSync(scriptPath, base + runTestsE2eBlock(), "utf8");
+  const assembled = base + runTestsE2eBlock();
+  // FAIL-CLOSED: never ship a run-tests.sh that lost its primary suite. The base
+  // template assigns REPO_ROOT and runs the pytest/vitest body; if the ORIGINAL
+  // carried that body but the ASSEMBLED result would not, the cut dropped real
+  // content — throw rather than write a hollow, always-exit-0 harness (the clobber
+  // defect). A genuinely body-less original (nothing to preserve) is untouched.
+  const BODY_SENTINEL = 'REPO_ROOT="$(cd';
+  if (original.includes(BODY_SENTINEL) && !assembled.includes(BODY_SENTINEL)) {
+    throw new Error(
+      `addE2eToRunTestsScript: refusing to write ${scriptPath} — the E2E assembly would drop the ` +
+        `primary-suite body (REPO_ROOT/pytest/vitest). This is the marker-match clobber; the marker ` +
+        `must anchor to the appended block's own line, not a prose mention.`,
+    );
+  }
+  fs.writeFileSync(scriptPath, assembled, "utf8");
   return { patched: true, inserted: true };
 }
 

package/templates/project/common/.github/workflows/pr.yml

@@ -148,11 +148,6 @@ jobs:
       # the CI branch is provisioned and fail fast. `--if-present` no-ops a
       # client with no `test` script. The client's Playwright E2E runs later
       # (its own step, gated on client/playwright.config.ts).
-      - name: Run client unit tests
-        if: hashFiles('client/package.json') != ''
-        working-directory: client
-        run: npm run test --if-present
-
       # The official action installs to a user-writable path (no sudo). It's
       # a no-op if a compatible databricks CLI is already on PATH.
       - name: Install Databricks CLI
@@ -384,6 +379,20 @@ jobs:
             --pretty
           echo "Migrations completed."
 
+      - name: Run client unit tests
+        # The kit's client/vitest.globalSetup.ts boots a REAL backend over the /api
+        # boundary (never mock when a real counterpart exists), so the component suite
+        # NEEDS the CI Lakebase branch + DATABASE_URL. Run it AFTER datasource config +
+        # migrations, not before. No-op when there are no component tests (globalSetup
+        # returns early); skipped when there is no CI Lakebase branch (url empty).
+        if: hashFiles('client/package.json') != '' && steps.lakebase-db.outputs.url != ''
+        working-directory: client
+        env:
+          DATABASE_URL: ${{ env.DATABASE_URL }}
+          DB_USERNAME: ${{ env.DB_USERNAME }}
+          DB_PASSWORD: ${{ env.DB_PASSWORD }}
+        run: npm run test --if-present
+
       - name: Run tests
         env:
           DATABASE_URL: ${{ env.DATABASE_URL }}