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

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