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

package/dist/scripts/lakebase/index.js

@@ -2521,8 +2521,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.4".length > 0) {
-    cached = "0.3.4";
+  if ("0.3.6".length > 0) {
+    cached = "0.3.6";
     return cached;
   }
   cached = "unknown";
@@ -11015,6 +11015,113 @@ init_esm_shims();
 import { spawnSync } from "child_process";
 import * as fs5 from "fs";
 import * as path5 from "path";
+
+// scripts/github/repo.ts
+init_esm_shims();
+var GitHubRepoError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "GitHubRepoError";
+    this.status = status;
+  }
+};
+async function newContext() {
+  const token = await resolveGitHubToken();
+  return { octokit: new Octokit2({ auth: token }) };
+}
+function wrap2(err, context) {
+  if (err instanceof RequestError) {
+    throw new GitHubRepoError(`${context}: ${err.message}`, err.status);
+  }
+  if (err instanceof Error) {
+    throw new GitHubRepoError(`${context}: ${err.message}`);
+  }
+  throw new GitHubRepoError(context);
+}
+async function getLogin(ctx) {
+  if (!ctx.loginPromise) {
+    ctx.loginPromise = ctx.octokit.rest.users.getAuthenticated().then(({ data }) => data.login);
+  }
+  return ctx.loginPromise;
+}
+async function getCurrentUser() {
+  try {
+    const ctx = await newContext();
+    return await getLogin(ctx);
+  } catch (err) {
+    wrap2(err, "GitHub authentication failed");
+  }
+}
+async function checkGitHubScopes(required = GITHUB_SCOPES) {
+  try {
+    const ctx = await newContext();
+    const res = await ctx.octokit.rest.users.getAuthenticated();
+    const header = res.headers["x-oauth-scopes"];
+    if (header === void 0 || header === null) return { granted: null, missing: [] };
+    const granted = String(header).split(",").map((s) => s.trim()).filter(Boolean);
+    return { granted, missing: required.filter((s) => !granted.includes(s)) };
+  } catch (err) {
+    wrap2(err, "GitHub scope check failed");
+  }
+}
+async function createRepo(name, opts = {}) {
+  try {
+    const ctx = await newContext();
+    const isPrivate = opts.private !== false;
+    const description = opts.description;
+    if (name.includes("/")) {
+      const { owner, repo } = parseOwnerRepo(name);
+      const login = await getLogin(ctx);
+      let data2;
+      if (owner.toLowerCase() === login.toLowerCase()) {
+        ({ data: data2 } = await ctx.octokit.rest.repos.createForAuthenticatedUser({
+          name: repo,
+          private: isPrivate,
+          description
+        }));
+      } else {
+        ({ data: data2 } = await ctx.octokit.rest.repos.createInOrg({
+          org: owner,
+          name: repo,
+          private: isPrivate,
+          description
+        }));
+      }
+      return data2.html_url || `https://github.com/${formatOwnerRepo(owner, repo)}`;
+    }
+    const { data } = await ctx.octokit.rest.repos.createForAuthenticatedUser({
+      name,
+      private: isPrivate,
+      description
+    });
+    return data.html_url || `https://github.com/${data.full_name}`;
+  } catch (err) {
+    wrap2(err, `Failed to create repository "${name}"`);
+  }
+}
+async function getActionsEnabled(ownerRepo) {
+  try {
+    const { owner, repo } = parseOwnerRepo(ownerRepo);
+    const ctx = await newContext();
+    const { data } = await ctx.octokit.rest.actions.getGithubActionsPermissionsRepository({ owner, repo });
+    return data.enabled;
+  } catch {
+    return void 0;
+  }
+}
+async function getRepoFullName(name) {
+  try {
+    const { owner, repo } = parseOwnerRepo(name);
+    const ctx = await newContext();
+    const { data } = await ctx.octokit.rest.repos.get({ owner, repo });
+    return data.full_name || formatOwnerRepo(owner, repo);
+  } catch (err) {
+    wrap2(err, `Repository "${name}" is not visible`);
+  }
+}
+
+// scripts/lakebase/create-preflight.ts
 function validateCreateInputs(input) {
   if (input.useGithub && !input.githubOwner) {
     return { ok: false, reason: "GitHub owner is required when creating a GitHub repository" };
@@ -11049,6 +11156,22 @@ async function checkDatabricksAuth(host, run = (args) => runDatabricks(args, { h
     return { ok: false, reason: lastLines(e.stderr, 2) || e.message || "databricks auth token failed" };
   }
 }
+async function checkGitHubWorkflowScope(probe = () => checkGitHubScopes(["workflow"])) {
+  try {
+    const { granted, missing } = await probe();
+    if (granted === null) return { ok: true };
+    if (missing.includes("workflow")) {
+      return { ok: false, reason: `token grants [${granted.join(", ") || "none"}] but not \`workflow\`` };
+    }
+    return { ok: true };
+  } catch {
+    return { ok: true };
+  }
+}
+function githubWorkflowScopePrereqMessage(reason) {
+  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 ? `
+(${reason})` : "");
+}
 function databricksAuthPrereqMessage(host, reason) {
   const hostFlag = host ? ` --host ${host.replace(/\/+$/, "")}` : "";
   return `Databricks authentication is required before creating a project. Run: databricks auth login${hostFlag}` + (reason ? `
@@ -11148,99 +11271,6 @@ function verifyProject(projectDir) {
   return { hooks, workflows, warnings };
 }
 
-// scripts/github/repo.ts
-init_esm_shims();
-var GitHubRepoError = class extends Error {
-  status;
-  constructor(message, status) {
-    super(message);
-    this.name = "GitHubRepoError";
-    this.status = status;
-  }
-};
-async function newContext() {
-  const token = await resolveGitHubToken();
-  return { octokit: new Octokit2({ auth: token }) };
-}
-function wrap2(err, context) {
-  if (err instanceof RequestError) {
-    throw new GitHubRepoError(`${context}: ${err.message}`, err.status);
-  }
-  if (err instanceof Error) {
-    throw new GitHubRepoError(`${context}: ${err.message}`);
-  }
-  throw new GitHubRepoError(context);
-}
-async function getLogin(ctx) {
-  if (!ctx.loginPromise) {
-    ctx.loginPromise = ctx.octokit.rest.users.getAuthenticated().then(({ data }) => data.login);
-  }
-  return ctx.loginPromise;
-}
-async function getCurrentUser() {
-  try {
-    const ctx = await newContext();
-    return await getLogin(ctx);
-  } catch (err) {
-    wrap2(err, "GitHub authentication failed");
-  }
-}
-async function createRepo(name, opts = {}) {
-  try {
-    const ctx = await newContext();
-    const isPrivate = opts.private !== false;
-    const description = opts.description;
-    if (name.includes("/")) {
-      const { owner, repo } = parseOwnerRepo(name);
-      const login = await getLogin(ctx);
-      let data2;
-      if (owner.toLowerCase() === login.toLowerCase()) {
-        ({ data: data2 } = await ctx.octokit.rest.repos.createForAuthenticatedUser({
-          name: repo,
-          private: isPrivate,
-          description
-        }));
-      } else {
-        ({ data: data2 } = await ctx.octokit.rest.repos.createInOrg({
-          org: owner,
-          name: repo,
-          private: isPrivate,
-          description
-        }));
-      }
-      return data2.html_url || `https://github.com/${formatOwnerRepo(owner, repo)}`;
-    }
-    const { data } = await ctx.octokit.rest.repos.createForAuthenticatedUser({
-      name,
-      private: isPrivate,
-      description
-    });
-    return data.html_url || `https://github.com/${data.full_name}`;
-  } catch (err) {
-    wrap2(err, `Failed to create repository "${name}"`);
-  }
-}
-async function getActionsEnabled(ownerRepo) {
-  try {
-    const { owner, repo } = parseOwnerRepo(ownerRepo);
-    const ctx = await newContext();
-    const { data } = await ctx.octokit.rest.actions.getGithubActionsPermissionsRepository({ owner, repo });
-    return data.enabled;
-  } catch {
-    return void 0;
-  }
-}
-async function getRepoFullName(name) {
-  try {
-    const { owner, repo } = parseOwnerRepo(name);
-    const ctx = await newContext();
-    const { data } = await ctx.octokit.rest.repos.get({ owner, repo });
-    return data.full_name || formatOwnerRepo(owner, repo);
-  } catch (err) {
-    wrap2(err, `Repository "${name}" is not visible`);
-  }
-}
-
 // scripts/git/clone.ts
 init_esm_shims();
 async function cloneRepo(args) {
@@ -12318,6 +12348,9 @@ function ensurePythonBddDeps(args) {
 }
 var RUN_TESTS_E2E_MARKER = "# run Playwright E2E suite when configured";
 var CLIENT_E2E_MARKER = "# run client Playwright E2E suite when configured";
+var escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+var RUN_TESTS_E2E_MARKER_LINE = new RegExp(`^${escapeRe(RUN_TESTS_E2E_MARKER)}$`, "m");
+var CLIENT_E2E_MARKER_LINE = new RegExp(`^${escapeRe(CLIENT_E2E_MARKER)}$`, "m");
 function runTestsE2eBlock() {
   return [
     "",
@@ -12409,14 +12442,22 @@ function addE2eToRunTestsScript(args) {
     return { patched: false, inserted: false };
   }
   const original = fs14.readFileSync(scriptPath, "utf8");
-  const hasBase = original.includes(RUN_TESTS_E2E_MARKER);
-  const hasClient = original.includes(CLIENT_E2E_MARKER);
+  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 };
   }
-  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");
-  fs14.writeFileSync(scriptPath, base + runTestsE2eBlock(), "utf8");
+  const assembled = base + runTestsE2eBlock();
+  const BODY_SENTINEL = 'REPO_ROOT="$(cd';
+  if (original.includes(BODY_SENTINEL) && !assembled.includes(BODY_SENTINEL)) {
+    throw new Error(
+      `addE2eToRunTestsScript: refusing to write ${scriptPath} \u2014 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.`
+    );
+  }
+  fs14.writeFileSync(scriptPath, assembled, "utf8");
   return { patched: true, inserted: true };
 }
 function enableE2eForProject(args) {
@@ -13584,6 +13625,13 @@ async function createProject(input, progress) {
   if (!auth7.ok) {
     throw new Error(databricksAuthPrereqMessage(host, auth7.reason));
   }
+  if (useGithub) {
+    report("Checking GitHub token scopes...");
+    const scope = await checkGitHubWorkflowScope();
+    if (!scope.ok) {
+      throw new Error(githubWorkflowScopePrereqMessage(scope.reason));
+    }
+  }
   if (useGithub) {
     report("Creating GitHub repository...", fullRepoName);
     await createRepo(fullRepoName, {
@@ -18253,6 +18301,40 @@ async function checkGitRemote(projectDir) {
     };
   }
 }
+async function checkGitHubTokenScope(probe = () => checkGitHubScopes(["workflow"])) {
+  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.message }
+    };
+  }
+}
 function checkLanguage(projectDir) {
   try {
     const lang = detectLanguage(projectDir);
@@ -18362,6 +18444,7 @@ async function runDoctor2(args = {}) {
     host
   );
   const gitRemote = await checkGitRemote(projectDir);
+  const githubTokenScope = await checkGitHubTokenScope();
   const language = checkLanguage(projectDir);
   const hooks = checkHooks(projectDir);
   const workflowDrift = checkWorkflowDrift(projectDir);
@@ -18383,6 +18466,7 @@ async function runDoctor2(args = {}) {
     configProfile,
     lakebaseProject,
     gitRemote,
+    githubTokenScope,
     language,
     hooks,
     workflowDrift
@@ -18607,6 +18691,7 @@ export {
   catalogExists,
   catalogExplorerUrl,
   checkDatabricksAuth,
+  checkGitHubWorkflowScope,
   checkoutPaired,
   claimFeatureBranch,
   clearRetentionCache,
@@ -18689,6 +18774,7 @@ export {
   getRunnerInfo,
   getSchemaDiff,
   getTargetNames,
+  githubWorkflowScopePrereqMessage,
   grantLakebasePermission,
   grantUcCatalogPermission,
   hasDotnetMarker,

package/dist/scripts/lakebase/infra-runner.cli.cjs

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

package/dist/scripts/lakebase/infra-runner.cli.js

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

package/dist/scripts/lakebase/new-migration.cli.cjs

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

package/dist/scripts/lakebase/new-migration.cli.js

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

package/dist/scripts/lakebase/schema-diff.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.4".length > 0) {
-    cached = "0.3.4";
+  if ("0.3.6".length > 0) {
+    cached = "0.3.6";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/schema-diff.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.4".length > 0) {
-    cached = "0.3.4";
+  if ("0.3.6".length > 0) {
+    cached = "0.3.6";
     return cached;
   }
   cached = "unknown";

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

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

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.4".length > 0) {
-    cached = "0.3.4";
+  if ("0.3.6".length > 0) {
+    cached = "0.3.6";
     return cached;
   }
   cached = "unknown";

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

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

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

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

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

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

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

@@ -9393,8 +9393,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.4".length > 0) {
-    cached = "0.3.4";
+  if ("0.3.6".length > 0) {
+    cached = "0.3.6";
     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.4".length > 0) {
-    cached = "0.3.4";
+  if ("0.3.6".length > 0) {
+    cached = "0.3.6";
     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.4".length > 0) {
-    cached = "0.3.4";
+  if ("0.3.6".length > 0) {
+    cached = "0.3.6";
     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.4".length > 0) {
-    cached = "0.3.4";
+  if ("0.3.6".length > 0) {
+    cached = "0.3.6";
     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.4".length > 0) {
-    cached = "0.3.4";
+  if ("0.3.6".length > 0) {
+    cached = "0.3.6";
     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.4".length > 0) {
-    cached = "0.3.4";
+  if ("0.3.6".length > 0) {
+    cached = "0.3.6";
     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.4".length > 0) {
-    cached = "0.3.4";
+  if ("0.3.6".length > 0) {
+    cached = "0.3.6";
     return cached;
   }
   cached = "unknown";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@databricks-solutions/lakebase-scm-utils",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "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/github/repo.ts

@@ -4,7 +4,7 @@
 // (scripts/github/auth.ts).
 
 import { Octokit, RequestError } from "octokit";
-import { resolveGitHubToken } from "./auth.js";
+import { resolveGitHubToken, GITHUB_SCOPES } from "./auth.js";
 import { parseOwnerRepo, formatOwnerRepo } from "../util/parse-owner-repo.js";
 
 export class GitHubRepoError extends Error {
@@ -56,6 +56,42 @@ export async function getCurrentUser(): Promise<string> {
   }
 }
 
+export interface GitHubScopeStatus {
+  /** Granted OAuth scopes, or null when the token exposes NONE — a fine-grained
+   *  PAT or GitHub App token carries no OAuth scope header; its permissions
+   *  aren't a scope set, so callers MUST treat null as "unknown", never a miss. */
+  granted: string[] | null;
+  /** Required scopes absent from `granted` (empty when `granted` is null). */
+  missing: string[];
+}
+
+/**
+ * Read the authenticated token's granted OAuth scopes from the GitHub API
+ * `x-oauth-scopes` response header and diff them against `required`. A classic
+ * OAuth/PAT token returns a (possibly empty) comma-separated header; a
+ * fine-grained PAT / GitHub App token omits it entirely → `granted: null`.
+ * Reading your own user needs no special scope, so this succeeds for any VALID
+ * token regardless of scopes (and throws, like the other ops, on a bad token /
+ * network error — callers decide whether that is blocking).
+ */
+export async function checkGitHubScopes(
+  required: readonly string[] = GITHUB_SCOPES
+): Promise<GitHubScopeStatus> {
+  try {
+    const ctx = await newContext();
+    const res = await ctx.octokit.rest.users.getAuthenticated();
+    const header = (res.headers as Record<string, string | undefined>)["x-oauth-scopes"];
+    if (header === undefined || header === null) return { granted: null, missing: [] };
+    const granted = String(header)
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    return { granted, missing: required.filter((s) => !granted.includes(s)) };
+  } catch (err) {
+    wrap(err, "GitHub scope check failed");
+  }
+}
+
 export interface CreateRepoOptions {
   /** Make the repo private. Default: true. */
   private?: boolean;