@databricks-solutions/lakebase-scm-utils 0.2.44 → 0.2.46

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

@@ -79276,6 +79276,7 @@ var DEFAULT_DATABASE = "databricks_postgres";
 var DEFAULT_ENDPOINT = "primary";
 var CONSORT_APPLICATION_NAME = "consort";
 var SCM_UTILS_APPLICATION_NAME = "scm-utils";
+var SCM_CLIENT_ENV = "LAKEBASE_SCM_CLIENT";
 var CONSORT_VERSION_ENV = "CONSORT_VERSION";
 
 // scripts/lakebase/self-version.ts
@@ -79287,8 +79288,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.2.44".length > 0) {
-    cached = "0.2.44";
+  if ("0.2.46".length > 0) {
+    cached = "0.2.46";
     return cached;
   }
   cached = "unknown";
@@ -79316,9 +79317,17 @@ function substrateSelfVersion() {
 }
 
 // scripts/lakebase/get-connection.ts
+function sanitizeApplicationName(raw) {
+  const cleaned = raw.replace(/[^\x21-\x7e]+/g, "-").replace(/^-+|-+$/g, "");
+  if (!cleaned) return `${SCM_UTILS_APPLICATION_NAME}/${substrateSelfVersion()}`;
+  return cleaned.length > 63 ? cleaned.slice(0, 63) : cleaned;
+}
 function connectionApplicationName() {
+  const client = process.env[SCM_CLIENT_ENV]?.trim();
+  if (client) return sanitizeApplicationName(client);
   const consortVersion = process.env[CONSORT_VERSION_ENV]?.trim();
-  return consortVersion ? `${CONSORT_APPLICATION_NAME}/${consortVersion}` : `${SCM_UTILS_APPLICATION_NAME}/${substrateSelfVersion()}`;
+  if (consortVersion) return `${CONSORT_APPLICATION_NAME}/${consortVersion}`;
+  return `${SCM_UTILS_APPLICATION_NAME}/${substrateSelfVersion()}`;
 }
 async function getConnection(args) {
   const endpointName = args.endpointName ?? DEFAULT_ENDPOINT;

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

@@ -378,6 +378,7 @@ var DEFAULT_DATABASE = "databricks_postgres";
 var DEFAULT_ENDPOINT = "primary";
 var CONSORT_APPLICATION_NAME = "consort";
 var SCM_UTILS_APPLICATION_NAME = "scm-utils";
+var SCM_CLIENT_ENV = "LAKEBASE_SCM_CLIENT";
 var CONSORT_VERSION_ENV = "CONSORT_VERSION";
 
 // scripts/lakebase/self-version.ts
@@ -388,8 +389,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.2.44".length > 0) {
-    cached = "0.2.44";
+  if ("0.2.46".length > 0) {
+    cached = "0.2.46";
     return cached;
   }
   cached = "unknown";
@@ -417,9 +418,17 @@ function substrateSelfVersion() {
 }
 
 // scripts/lakebase/get-connection.ts
+function sanitizeApplicationName(raw) {
+  const cleaned = raw.replace(/[^\x21-\x7e]+/g, "-").replace(/^-+|-+$/g, "");
+  if (!cleaned) return `${SCM_UTILS_APPLICATION_NAME}/${substrateSelfVersion()}`;
+  return cleaned.length > 63 ? cleaned.slice(0, 63) : cleaned;
+}
 function connectionApplicationName() {
+  const client = process.env[SCM_CLIENT_ENV]?.trim();
+  if (client) return sanitizeApplicationName(client);
   const consortVersion = process.env[CONSORT_VERSION_ENV]?.trim();
-  return consortVersion ? `${CONSORT_APPLICATION_NAME}/${consortVersion}` : `${SCM_UTILS_APPLICATION_NAME}/${substrateSelfVersion()}`;
+  if (consortVersion) return `${CONSORT_APPLICATION_NAME}/${consortVersion}`;
+  return `${SCM_UTILS_APPLICATION_NAME}/${substrateSelfVersion()}`;
 }
 async function getConnection(args) {
   const endpointName = args.endpointName ?? DEFAULT_ENDPOINT;

package/dist/scripts/util/index.cjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@databricks-solutions/lakebase-scm-utils",
-  "version": "0.2.44",
+  "version": "0.2.46",
   "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/lakebase/constants.ts

@@ -58,10 +58,15 @@ export const DEFAULT_ENDPOINT = "primary";
 // branch/schema/ping connections this package opens). The full label is
 // `<brand>/<version>` , see `connectionApplicationName()` in get-connection.ts , and it
 // reflects WHICH tool opened the connection:
-//   - `consort/<consort-version>` when the connection is made UNDER a Consort run (Consort
-//     exports its version via CONSORT_VERSION_ENV; scm-utils reads it);
-//   - `scm-utils/<scm-utils-version>` when scm-utils is used DIRECTLY (the VS Code extension,
-//     a bare `lakebase-*` CLI) , no env set, so the label falls back to this package's brand.
+//   - ANY consumer that sets SCM_CLIENT_ENV (`LAKEBASE_SCM_CLIENT="<brand>/<version>"`) — the
+//     GENERIC, extensible path: a new consumer self-brands with NO scm-utils change. scm-utils
+//     sanitizes the value and uses it verbatim (e.g. the VS Code / Cursor extension sets
+//     `scm-extension/<ext-version>`);
+//   - `consort/<consort-version>` — BACK-COMPAT for Consort, which sets CONSORT_VERSION_ENV
+//     (older Consorts predate the generic env; keeping this means Consort needs no change);
+//   - `scm-utils/<scm-utils-version>` when nothing is set — a bare `lakebase-*` CLI falls back
+//     to this package's own brand.
+// Precedence: SCM_CLIENT_ENV > CONSORT_VERSION_ENV > scm-utils default.
 // A TRANSPARENT label , standard practice (psql, ORMs set one) , visible to the database OWNER
 // in their own `pg_stat_activity`, so support + the owner's own diagnostics can tell which
 // tooling connected versus their application. Reads no table contents; carries only brand + version.
@@ -69,9 +74,22 @@ export const DEFAULT_ENDPOINT = "primary";
 /** Brand when the connection is made under a Consort run (CONSORT_VERSION_ENV set). */
 export const CONSORT_APPLICATION_NAME = "consort";
 
-/** Brand when scm-utils is used directly (extension / bare CLI); the default. */
+/** Brand when scm-utils is used directly via a bare `lakebase-*` CLI; the default. */
 export const SCM_UTILS_APPLICATION_NAME = "scm-utils";
 
+/**
+ * GENERIC consumer-brand env: any tool that opens substrate connections can set
+ * `LAKEBASE_SCM_CLIENT="<brand>/<version>"` (e.g. the VS Code / Cursor extension sets
+ * `scm-extension/<ext-version>`), and connectionApplicationName() uses it (sanitized) as the
+ * Postgres application_name. This is the extensibility point: adding a NEW consumer needs ZERO
+ * scm-utils changes — the consumer just sets this env before its first connection. Takes
+ * precedence over the CONSORT_VERSION back-compat path. The value is a full `<brand>/<version>`
+ * label owned by the consumer (scm-utils no longer hardcodes per-consumer brand constants).
+ * Brand convention: drop the `lakebase-` package prefix (lakebase-scm-utils -> scm-utils,
+ * lakebase-scm-extension -> scm-extension).
+ */
+export const SCM_CLIENT_ENV = "LAKEBASE_SCM_CLIENT";
+
 /**
  * Env var Consort sets to its OWN version so a connection opened under a Consort run is
  * labelled `consort/<consort-version>` rather than `scm-utils/<scm-utils-version>`. This is

package/scripts/lakebase/doctor.ts

@@ -628,7 +628,7 @@ function checkWorkflowDrift(projectDir: string): CheckResult {
       status: "warn",
       message: `Scaffolded workflows drift from kit: ${drifted} drifted, ${missing} missing`,
       detail: { files: report.files.map((f) => ({ name: f.name, status: f.status })) },
-      hint: "Inspect via the lakebase_workflow_drift MCP tool (or detectWorkflowDrift import). Refresh manually until updateWorkflows lands.",
+      hint: "Refresh with updateWorkflows (or the lakebase_workflow_drift MCP tool). A stale merge.yml calling 'lakebase-schema-migrate apply' (not 'apply-tier') makes the promote's migrate-target fail on the tier guard; the scm-merge promote also self-heals drifted workflows onto the PR head before merging.",
     };
   } catch (err) {
     return {

package/scripts/lakebase/get-connection.ts

@@ -23,6 +23,7 @@ import {
   DEFAULT_DATABASE,
   DEFAULT_ENDPOINT,
   POSTGRES_PORT,
+  SCM_CLIENT_ENV,
   SCM_UTILS_APPLICATION_NAME,
 } from "./constants.js";
 import { substrateSelfVersion } from "./self-version.js";
@@ -39,11 +40,24 @@ import { KIT_TIMEOUTS } from "./kit-config.js";
  * `pg_stat_activity`. Never throws (an unreadable scm-utils version -> `scm-utils/unknown`; a
  * blank env is ignored), so labelling can never break a connection.
  */
+/** Sanitize a consumer-provided application_name label: printable ASCII only (runs of control
+ *  chars / whitespace collapse to a single '-'), trimmed of leading/trailing '-', and capped to
+ *  Postgres's 63-byte application_name limit. Empty after cleaning -> the scm-utils default. */
+function sanitizeApplicationName(raw: string): string {
+  const cleaned = raw.replace(/[^\x21-\x7e]+/g, "-").replace(/^-+|-+$/g, "");
+  if (!cleaned) return `${SCM_UTILS_APPLICATION_NAME}/${substrateSelfVersion()}`;
+  // Printable-ASCII only, so byte length == char length; trim to the 63-byte cap.
+  return cleaned.length > 63 ? cleaned.slice(0, 63) : cleaned;
+}
+
 export function connectionApplicationName(): string {
+  // Precedence: a consumer's generic self-brand > Consort back-compat > scm-utils default.
+  // A NEW consumer just sets LAKEBASE_SCM_CLIENT="<brand>/<version>" — no scm-utils change needed.
+  const client = process.env[SCM_CLIENT_ENV]?.trim();
+  if (client) return sanitizeApplicationName(client);
   const consortVersion = process.env[CONSORT_VERSION_ENV]?.trim();
-  return consortVersion
-    ? `${CONSORT_APPLICATION_NAME}/${consortVersion}`
-    : `${SCM_UTILS_APPLICATION_NAME}/${substrateSelfVersion()}`;
+  if (consortVersion) return `${CONSORT_APPLICATION_NAME}/${consortVersion}`;
+  return `${SCM_UTILS_APPLICATION_NAME}/${substrateSelfVersion()}`;
 }
 // AppKit / @databricks/lakebase re-exports a WorkspaceClient type that
 // matches what createLakebasePool expects. We accept `unknown` at the API

package/scripts/lakebase/scm-merge.ts

@@ -20,7 +20,9 @@ import { getOwnerRepo } from "../git/remote.js";
 import { pollUntil } from "../util/poll-until.js";
 import { exec } from "../util/exec.js";
 import { getCurrentBranch } from "../git/inspect.js";
+import { pushCurrentBranchForPr } from "../git/sync.js";
 import { resolveGitBase } from "./scm-git-base.js";
+import { detectWorkflowDrift, updateWorkflows } from "./workflow-drift.js";
 
 /**
  * Fast-forward the local tier ref to origin/<tier> after a remote merge, WITHOUT
@@ -149,6 +151,21 @@ export interface MergeArgs {
    * already on the parent branch after the merge).
    */
   localMigrateFallback?: () => Promise<{ ok: boolean; detail?: string }>;
+  /**
+   * Pre-merge workflow self-heal. Bumping SCM_UTILS_REF upgrades the CLI (e.g.
+   * the tier-migration guard) but leaves a scaffolded project's committed
+   * `.github/workflows/*.yml` at their older shape — so the promote's
+   * `migrate-target` can run a stale `lakebase-schema-migrate apply` against the
+   * parent TIER, which the guard refuses (CI red, cleanup skipped). This step
+   * refreshes drifted workflow files to the pinned template (so the promote uses
+   * `apply-tier`) and commits+pushes them onto the PR head BEFORE the merge, so
+   * the merge commit carries the corrected workflow and the triggered `<tier>
+   * Merge` run passes. BEST-EFFORT: it never blocks the merge — a detect/refresh/
+   * push failure is recorded as a warning and the merge proceeds (the local
+   * migrate fallback still keeps git and schema in sync). Defaults to the built-in
+   * implementation ({@link defaultRefreshPromoteWorkflows}); injected in tests.
+   */
+  refreshWorkflows?: () => Promise<{ refreshed: boolean; detail?: string }>;
 }
 
 export interface MergeResult {
@@ -221,6 +238,43 @@ function shaMigratePredicate(
   };
 }
 
+/**
+ * Built-in {@link MergeArgs.refreshWorkflows}. Refreshes drifted scaffolded
+ * `.github/workflows/*.yml` to the pinned template and commits + pushes them onto
+ * the PR head, so the merge commit carries the corrected promote workflow (the
+ * `migrate-target` step's `lakebase-schema-migrate apply-tier`) and the triggered
+ * `<tier> Merge` run passes instead of failing on the tier guard. No-op when
+ * nothing drifted. Scoped to `.github/workflows` so it never sweeps unrelated
+ * working-tree changes. Callers invoke it BEST-EFFORT — a failure here must never
+ * block the merge (the local migrate fallback still keeps git + schema in sync).
+ */
+export async function defaultRefreshPromoteWorkflows(
+  projectDir: string,
+): Promise<{ refreshed: boolean; detail?: string }> {
+  const drift = detectWorkflowDrift({ projectDir });
+  // Only self-heal a stale EXISTING workflow (drifted). A project with no
+  // scaffolded workflows at all (all "missing") is not the stale-apply case, so
+  // the promote never scaffolds files it doesn't own.
+  const touched = drift.files.filter((f) => f.status === "drifted").map((f) => f.name);
+  if (touched.length === 0) return { refreshed: false };
+  const result = updateWorkflows({ projectDir });
+  if (!result.changed) return { refreshed: false };
+  await exec(`git add ${shellEscape(".github/workflows")}`, { cwd: projectDir, timeout: 10_000 });
+  const staged = await exec("git diff --cached --name-only -- .github/workflows", {
+    cwd: projectDir,
+    timeout: 10_000,
+  });
+  if (!staged.trim()) return { refreshed: false };
+  await exec(
+    `git commit -m ${shellEscape(
+      "chore(ci): refresh scaffolded workflows to pinned substrate (promote uses apply-tier)",
+    )} -- .github/workflows`,
+    { cwd: projectDir, timeout: 15_000 },
+  );
+  await pushCurrentBranchForPr({ cwd: projectDir });
+  return { refreshed: true, detail: `refreshed + pushed ${touched.join(", ") || "workflow(s)"} onto the PR head` };
+}
+
 export async function mergeFeature(args: MergeArgs): Promise<MergeResult> {
   const current = readWorkflowState(args.projectDir);
   if (!current) {
@@ -297,6 +351,31 @@ export async function mergeFeature(args: MergeArgs): Promise<MergeResult> {
     authVerified = true;
   }
 
+  // ─── Pre-merge workflow self-heal ───
+  // A scaffolded project's committed workflows can lag the pinned substrate ref
+  // (SCM_UTILS_REF bumped, workflow files not regenerated), so the promote's
+  // migrate-target runs a stale `lakebase-schema-migrate apply` against the parent
+  // TIER, which the guard refuses (CI red, cleanup skipped). Refresh drifted
+  // workflows onto the PR head BEFORE the merge so the merge commit carries the
+  // corrected `apply-tier` step. BEST-EFFORT: never blocks the merge.
+  // Runs regardless of waitMigrate: the promote workflow triggers on the tier
+  // push either way, so a stale merge.yml fails CI whether or not the caller waits.
+  const preflightNotes: string[] = [];
+  {
+    const refresh = args.refreshWorkflows ?? (() => defaultRefreshPromoteWorkflows(args.projectDir));
+    try {
+      const r = await refresh();
+      if (r.refreshed) {
+        preflightNotes.push(`Refreshed stale CI workflows before merge${r.detail ? ` (${r.detail})` : ""}.`);
+      }
+    } catch (err) {
+      preflightNotes.push(
+        `Workflow self-heal skipped (${err instanceof Error ? err.message : String(err)}); if the promote's ` +
+          `migrate-target fails on the tier guard, refresh .github/workflows (merge.yml must call 'lakebase-schema-migrate apply-tier').`,
+      );
+    }
+  }
+
   let paired: Awaited<ReturnType<typeof mergePairedPullRequest>>;
   try {
     paired = await mergePairedPullRequest({
@@ -312,7 +391,7 @@ export async function mergeFeature(args: MergeArgs): Promise<MergeResult> {
     );
   }
 
-  const warnings: string[] = [...paired.warnings];
+  const warnings: string[] = [...preflightNotes, ...paired.warnings];
   let localBranchDeleted = false;
   let headAfter = current.branch;
   if (!args.skipLocalCleanup) {

package/skills/lakebase-scm-workflows/README.md

@@ -228,7 +228,8 @@ The same flow applies to the `--enable-e2e`-scaffolded `playwright.config.ts` +
 | `lakebase-infra-runner` | Run the `[Infra]`-tag suite (schema-diff + migration status + endpoint readiness) for a branch. Used by scaffolded `test:infra` scripts. |
 | `lakebase-update-commands` | Refresh a scaffolded project's `.claude/commands/{design,build}.md` from the kit's current templates. Interactive per-file confirm by default; `--force` skips prompts, `--dry-run` previews, `--json` emits a structured report. Hook files (`<name>.{pre,post}-hook.md`) are NEVER touched. |
 | `lakebase-feature-status` | One-screen snapshot of a TDD feature's workflow state. Pairs with `consort`. |
-| `lakebase-mcp-server` | Stdio MCP server exposing the full tool surface (parity with the CLI bins). For Claude Desktop / OpenAI Codex / Cursor-via-MCP / Genie Code consumers. |
+
+> An MCP presentation of this same substrate surface ships in the `consort` package as `lakebase-mcp-server` (stdio; for Claude Desktop / OpenAI Codex / Cursor-via-MCP / Genie Code consumers). It is not an scm-utils bin.
 
 ## JS/TS exports
 

package/templates/project/nodejs/package.json

@@ -14,7 +14,9 @@
     "dotenv": "^16.4.0",
     "express": "^4.21.0",
     "knex": "^3.1.0",
-    "pg": "^8.13.0"
+    "pg": "^8.13.0",
+    "swagger-jsdoc": "^6.2.8",
+    "swagger-ui-express": "^5.0.1"
   },
   "devDependencies": {
     "jest": "^29.7.0",

package/templates/project/nodejs/src/index.js

@@ -1,11 +1,19 @@
 require('dotenv').config();
 const express = require('express');
+const swaggerUi = require('swagger-ui-express');
+const openapiSpec = require('./openapi');
 const healthRoutes = require('./routes/health');
 
 const app = express();
 app.use(express.json());
 app.use('/', healthRoutes);
 
+// Swagger / OpenAPI UI for acceptance review (parity with FastAPI's /docs): the interactive UI at
+// /docs and the raw spec at /openapi.json, both derived from the route @openapi annotations. For an
+// API-only story, the acceptance gate points the reviewer here to exercise the endpoints.
+app.use('/docs', swaggerUi.serve, swaggerUi.setup(openapiSpec));
+app.get('/openapi.json', (req, res) => res.json(openapiSpec));
+
 const PORT = process.env.PORT || 3000;
 
 if (require.main === module) {

package/templates/project/nodejs/src/openapi.js

@@ -0,0 +1,20 @@
+const path = require('path');
+const swaggerJsdoc = require('swagger-jsdoc');
+
+// The OpenAPI spec is built from the `@openapi` JSDoc blocks on the route files, so the Swagger UI
+// at /docs reflects the real endpoints as they are added — the Express analogue of FastAPI's
+// automatic /docs. Annotate every route you add with an `@openapi` block (see src/routes/health.js
+// for the pattern); it then appears in /docs and /openapi.json with no extra wiring.
+const spec = swaggerJsdoc({
+  definition: {
+    openapi: '3.0.3',
+    info: {
+      title: '{{PROJECT_NAME}}',
+      version: '1.0.0',
+      description: 'API surface for acceptance review (Swagger UI at /docs).',
+    },
+  },
+  apis: [path.join(__dirname, 'routes', '*.js')],
+});
+
+module.exports = spec;

package/templates/project/nodejs/src/routes/health.js

@@ -1,6 +1,24 @@
 const express = require('express');
 const router = express.Router();
 
+/**
+ * @openapi
+ * /health:
+ *   get:
+ *     summary: Liveness probe
+ *     description: Returns ok when the service is up. Pattern for annotating routes so they appear in /docs.
+ *     responses:
+ *       200:
+ *         description: Service is up
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 status:
+ *                   type: string
+ *                   example: ok
+ */
 router.get('/health', (req, res) => {
   res.json({ status: 'ok' });
 });

package/templates/project/nodejs/tests/app.test.js

@@ -8,3 +8,19 @@ describe('Health check', () => {
     expect(res.body.status).toBe('ok');
   });
 });
+
+describe('API docs (Swagger UI for acceptance review)', () => {
+  test('GET /openapi.json exposes the OpenAPI spec, including annotated routes', async () => {
+    const res = await request(app).get('/openapi.json');
+    expect(res.statusCode).toBe(200);
+    expect(res.body.openapi).toBeDefined();
+    // The @openapi annotation on the health route is picked up by swagger-jsdoc.
+    expect(res.body.paths['/health']).toBeDefined();
+  });
+
+  test('GET /docs/ serves the Swagger UI', async () => {
+    const res = await request(app).get('/docs/');
+    expect(res.statusCode).toBe(200);
+    expect(res.text).toMatch(/swagger-ui/i);
+  });
+});