@dbx-tools/appkit 0.3.43 → 0.4.0

package/lib/src/create-app.js

@@ -0,0 +1,120 @@
+/**
+ * `createApp` wrapper: runs dbx-tools auto-configuration, then delegates to
+ * AppKit's own `createApp` with the exact same arguments.
+ *
+ * Drop it in as a one-for-one replacement for `@databricks/appkit`'s
+ * `createApp` - same parameters, same return type, full plugin-export inference
+ * preserved:
+ *
+ * ```ts
+ * import { createApp } from "@dbx-tools/appkit";
+ * import { lakebase, server } from "@databricks/appkit";
+ *
+ * await createApp.createApp({ plugins: [server(), lakebase()] });
+ * ```
+ *
+ * Auto-configuration runs BEFORE delegating so plugins see a fully populated
+ * `process.env` during their synchronous `setup()`. Lakebase Postgres runs when
+ * a `lakebase` plugin is present, or when {@link AutoConfigureMode} is set
+ * explicitly on the config object.
+ *
+ * @module
+ */
+import { createApp as appkitCreateApp, getUsernameWithApiLookup } from "@databricks/appkit";
+import { async, log } from "@dbx-tools/shared-core";
+import { applyLakebaseToEnv, resolveLakebaseConnection, } from "./lakebase-resolver.js";
+import { provisionCacheSchema } from "./provision.js";
+const logger = log.logger("create-app");
+const LAKEBASE_PLUGIN = "lakebase";
+const DEFAULT_AUTO_CONFIGURE = "provision";
+/**
+ * Upper bound on boot-time auto-configuration. It runs as the service principal
+ * before any plugin is constructed, so it sits outside AppKit's interceptor
+ * chain and inherits no timeout, retry, or telemetry from it. The budget covers
+ * the resolver's own worst case (create a project, then wait for its endpoint)
+ * plus the cache-schema grants.
+ */
+const AUTO_CONFIGURE_TIMEOUT_MS = 11 * 60_000;
+function usesPlugin(config, name) {
+    return Boolean(config?.plugins?.some((entry) => entry.name === name));
+}
+/**
+ * Run enabled auto-configuration steps without calling AppKit's `createApp`.
+ *
+ * Lakebase Postgres resolves when {@link CreateAppConfig.autoConfigure} is set
+ * explicitly or a `lakebase` plugin is listed in `config.plugins`. `signal`
+ * cancels the resolution; it is combined with an internal boot timeout either
+ * way.
+ *
+ * @example
+ * import { createApp } from "@dbx-tools/appkit";
+ *
+ * // Populate PGHOST / PGDATABASE / LAKEBASE_ENDPOINT without booting AppKit.
+ * await createApp.autoConfigure({ autoConfigure: "env" });
+ */
+export async function autoConfigure(config, signal) {
+    const mode = config?.autoConfigure ?? DEFAULT_AUTO_CONFIGURE;
+    const explicit = config?.autoConfigure !== undefined;
+    const lakebasePluginPresent = usesPlugin(config, LAKEBASE_PLUGIN);
+    if (mode === false || !(explicit || lakebasePluginPresent)) {
+        logger.info("ready", {
+            autoConfigure: mode,
+            lakebasePluginPresent,
+            provisioned: false,
+            skippedReason: mode === false ? "disabled" : "no lakebase plugin",
+        });
+        return;
+    }
+    const controller = new AbortController();
+    async.tieAbortSignal(controller, signal);
+    async.tieAbortSignal(controller, AbortSignal.timeout(AUTO_CONFIGURE_TIMEOUT_MS));
+    const provision = mode === "provision";
+    await autoConfigureLakebase(provision, controller.signal);
+    logger.info("ready", { autoConfigure: mode, lakebasePluginPresent, provisioned: provision });
+}
+/**
+ * Resolve Lakebase Postgres connection info, write the resolved values to
+ * `process.env`, and return the record. Used by {@link autoConfigure}; call
+ * {@link resolveLakebaseConnection} and {@link applyLakebaseToEnv} directly when
+ * finer control is needed.
+ */
+async function autoConfigureLakebase(provision, signal) {
+    const resolved = await resolveLakebaseConnection(undefined, signal);
+    applyLakebaseToEnv(resolved);
+    const user = await getUsernameWithApiLookup({});
+    if (user)
+        process.env.PGUSER ??= user;
+    logger.info("env updated", { ...redactLakebaseConnection(resolved), user });
+    if (provision) {
+        await provisionCacheSchema(user, logger);
+    }
+    return resolved;
+}
+function redactLakebaseConnection(resolved) {
+    return {
+        project: resolved.project,
+        branch: resolved.branch,
+        endpoint: resolved.endpoint,
+        database: resolved.database,
+        host: resolved.host,
+        port: resolved.port,
+        sslMode: resolved.sslMode,
+    };
+}
+/**
+ * Auto-configuring drop-in for AppKit's `createApp`: same config, same typed
+ * plugin-export map, with {@link autoConfigure} run first.
+ *
+ * @example
+ * import { createApp } from "@dbx-tools/appkit";
+ * import { lakebase, server } from "@databricks/appkit";
+ *
+ * const app = await createApp.createApp({ plugins: [server(), lakebase()] });
+ */
+export async function createApp(config) {
+    await autoConfigure(config);
+    const appConfig = { ...config };
+    delete appConfig.autoConfigure;
+    return appkitCreateApp(appConfig);
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY3JlYXRlLWFwcC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9jcmVhdGUtYXBwLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0FxQkc7QUFFSCxPQUFPLEVBQUUsU0FBUyxJQUFJLGVBQWUsRUFBRSx3QkFBd0IsRUFBRSxNQUFNLG9CQUFvQixDQUFDO0FBSTVGLE9BQU8sRUFBRSxLQUFLLEVBQUUsR0FBRyxFQUFFLE1BQU0sd0JBQXdCLENBQUM7QUFFcEQsT0FBTyxFQUNMLGtCQUFrQixFQUNsQix5QkFBeUIsR0FFMUIsTUFBTSxxQkFBcUIsQ0FBQztBQUM3QixPQUFPLEVBQUUsb0JBQW9CLEVBQUUsTUFBTSxhQUFhLENBQUM7QUE2Qm5ELE1BQU0sTUFBTSxHQUFHLEdBQUcsQ0FBQyxNQUFNLENBQUMsWUFBWSxDQUFDLENBQUM7QUFFeEMsTUFBTSxlQUFlLEdBQUcsVUFBVSxDQUFDO0FBQ25DLE1BQU0sc0JBQXNCLEdBQXNCLFdBQVcsQ0FBQztBQUU5RDs7Ozs7O0dBTUc7QUFDSCxNQUFNLHlCQUF5QixHQUFHLEVBQUUsR0FBRyxNQUFNLENBQUM7QUFFOUMsU0FBUyxVQUFVLENBQ2pCLE1BQXNDLEVBQ3RDLElBQVk7SUFFWixPQUFPLE9BQU8sQ0FBQyxNQUFNLEVBQUUsT0FBTyxFQUFFLElBQUksQ0FBQyxDQUFDLEtBQUssRUFBRSxFQUFFLENBQUMsS0FBSyxDQUFDLElBQUksS0FBSyxJQUFJLENBQUMsQ0FBQyxDQUFDO0FBQ3hFLENBQUM7QUFFRDs7Ozs7Ozs7Ozs7OztHQWFHO0FBQ0gsTUFBTSxDQUFDLEtBQUssVUFBVSxhQUFhLENBQ2pDLE1BQTJCLEVBQzNCLE1BQW9CO0lBRXBCLE1BQU0sSUFBSSxHQUFHLE1BQU0sRUFBRSxhQUFhLElBQUksc0JBQXNCLENBQUM7SUFDN0QsTUFBTSxRQUFRLEdBQUcsTUFBTSxFQUFFLGFBQWEsS0FBSyxTQUFTLENBQUM7SUFDckQsTUFBTSxxQkFBcUIsR0FBRyxVQUFVLENBQUMsTUFBTSxFQUFFLGVBQWUsQ0FBQyxDQUFDO0lBQ2xFLElBQUksSUFBSSxLQUFLLEtBQUssSUFBSSxDQUFDLENBQUMsUUFBUSxJQUFJLHFCQUFxQixDQUFDLEVBQUUsQ0FBQztRQUMzRCxNQUFNLENBQUMsSUFBSSxDQUFDLE9BQU8sRUFBRTtZQUNuQixhQUFhLEVBQUUsSUFBSTtZQUNuQixxQkFBcUI7WUFDckIsV0FBVyxFQUFFLEtBQUs7WUFDbEIsYUFBYSxFQUFFLElBQUksS0FBSyxLQUFLLENBQUMsQ0FBQyxDQUFDLFVBQVUsQ0FBQyxDQUFDLENBQUMsb0JBQW9CO1NBQ2xFLENBQUMsQ0FBQztRQUNILE9BQU87SUFDVCxDQUFDO0lBRUQsTUFBTSxVQUFVLEdBQUcsSUFBSSxlQUFlLEVBQUUsQ0FBQztJQUN6QyxLQUFLLENBQUMsY0FBYyxDQUFDLFVBQVUsRUFBRSxNQUFNLENBQUMsQ0FBQztJQUN6QyxLQUFLLENBQUMsY0FBYyxDQUFDLFVBQVUsRUFBRSxXQUFXLENBQUMsT0FBTyxDQUFDLHlCQUF5QixDQUFDLENBQUMsQ0FBQztJQUVqRixNQUFNLFNBQVMsR0FBRyxJQUFJLEtBQUssV0FBVyxDQUFDO0lBQ3ZDLE1BQU0scUJBQXFCLENBQUMsU0FBUyxFQUFFLFVBQVUsQ0FBQyxNQUFNLENBQUMsQ0FBQztJQUMxRCxNQUFNLENBQUMsSUFBSSxDQUFDLE9BQU8sRUFBRSxFQUFFLGFBQWEsRUFBRSxJQUFJLEVBQUUscUJBQXFCLEVBQUUsV0FBVyxFQUFFLFNBQVMsRUFBRSxDQUFDLENBQUM7QUFDL0YsQ0FBQztBQUVEOzs7OztHQUtHO0FBQ0gsS0FBSyxVQUFVLHFCQUFxQixDQUNsQyxTQUFrQixFQUNsQixNQUFtQjtJQUVuQixNQUFNLFFBQVEsR0FBRyxNQUFNLHlCQUF5QixDQUFDLFNBQVMsRUFBRSxNQUFNLENBQUMsQ0FBQztJQUNwRSxrQkFBa0IsQ0FBQyxRQUFRLENBQUMsQ0FBQztJQUM3QixNQUFNLElBQUksR0FBRyxNQUFNLHdCQUF3QixDQUFDLEVBQUUsQ0FBQyxDQUFDO0lBQ2hELElBQUksSUFBSTtRQUFFLE9BQU8sQ0FBQyxHQUFHLENBQUMsTUFBTSxLQUFLLElBQUksQ0FBQztJQUN0QyxNQUFNLENBQUMsSUFBSSxDQUFDLGFBQWEsRUFBRSxFQUFFLEdBQUcsd0JBQXdCLENBQUMsUUFBUSxDQUFDLEVBQUUsSUFBSSxFQUFFLENBQUMsQ0FBQztJQUM1RSxJQUFJLFNBQVMsRUFBRSxDQUFDO1FBQ2QsTUFBTSxvQkFBb0IsQ0FBQyxJQUFJLEVBQUUsTUFBTSxDQUFDLENBQUM7SUFDM0MsQ0FBQztJQUNELE9BQU8sUUFBUSxDQUFDO0FBQ2xCLENBQUM7QUFFRCxTQUFTLHdCQUF3QixDQUFDLFFBQTRCO0lBQzVELE9BQU87UUFDTCxPQUFPLEVBQUUsUUFBUSxDQUFDLE9BQU87UUFDekIsTUFBTSxFQUFFLFFBQVEsQ0FBQyxNQUFNO1FBQ3ZCLFFBQVEsRUFBRSxRQUFRLENBQUMsUUFBUTtRQUMzQixRQUFRLEVBQUUsUUFBUSxDQUFDLFFBQVE7UUFDM0IsSUFBSSxFQUFFLFFBQVEsQ0FBQyxJQUFJO1FBQ25CLElBQUksRUFBRSxRQUFRLENBQUMsSUFBSTtRQUNuQixPQUFPLEVBQUUsUUFBUSxDQUFDLE9BQU87S0FDMUIsQ0FBQztBQUNKLENBQUM7QUFFRDs7Ozs7Ozs7O0dBU0c7QUFDSCxNQUFNLENBQUMsS0FBSyxVQUFVLFNBQVMsQ0FDN0IsTUFBMkI7SUFFM0IsTUFBTSxhQUFhLENBQUMsTUFBTSxDQUFDLENBQUM7SUFDNUIsTUFBTSxTQUFTLEdBQUcsRUFBRSxHQUFHLE1BQU0sRUFBRSxDQUFDO0lBQ2hDLE9BQU8sU0FBUyxDQUFDLGFBQWEsQ0FBQztJQUMvQixPQUFPLGVBQWUsQ0FBSSxTQUFTLENBQUMsQ0FBQztBQUN2QyxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBgY3JlYXRlQXBwYCB3cmFwcGVyOiBydW5zIGRieC10b29scyBhdXRvLWNvbmZpZ3VyYXRpb24sIHRoZW4gZGVsZWdhdGVzIHRvXG4gKiBBcHBLaXQncyBvd24gYGNyZWF0ZUFwcGAgd2l0aCB0aGUgZXhhY3Qgc2FtZSBhcmd1bWVudHMuXG4gKlxuICogRHJvcCBpdCBpbiBhcyBhIG9uZS1mb3Itb25lIHJlcGxhY2VtZW50IGZvciBgQGRhdGFicmlja3MvYXBwa2l0YCdzXG4gKiBgY3JlYXRlQXBwYCAtIHNhbWUgcGFyYW1ldGVycywgc2FtZSByZXR1cm4gdHlwZSwgZnVsbCBwbHVnaW4tZXhwb3J0IGluZmVyZW5jZVxuICogcHJlc2VydmVkOlxuICpcbiAqIGBgYHRzXG4gKiBpbXBvcnQgeyBjcmVhdGVBcHAgfSBmcm9tIFwiQGRieC10b29scy9hcHBraXRcIjtcbiAqIGltcG9ydCB7IGxha2ViYXNlLCBzZXJ2ZXIgfSBmcm9tIFwiQGRhdGFicmlja3MvYXBwa2l0XCI7XG4gKlxuICogYXdhaXQgY3JlYXRlQXBwLmNyZWF0ZUFwcCh7IHBsdWdpbnM6IFtzZXJ2ZXIoKSwgbGFrZWJhc2UoKV0gfSk7XG4gKiBgYGBcbiAqXG4gKiBBdXRvLWNvbmZpZ3VyYXRpb24gcnVucyBCRUZPUkUgZGVsZWdhdGluZyBzbyBwbHVnaW5zIHNlZSBhIGZ1bGx5IHBvcHVsYXRlZFxuICogYHByb2Nlc3MuZW52YCBkdXJpbmcgdGhlaXIgc3luY2hyb25vdXMgYHNldHVwKClgLiBMYWtlYmFzZSBQb3N0Z3JlcyBydW5zIHdoZW5cbiAqIGEgYGxha2ViYXNlYCBwbHVnaW4gaXMgcHJlc2VudCwgb3Igd2hlbiB7QGxpbmsgQXV0b0NvbmZpZ3VyZU1vZGV9IGlzIHNldFxuICogZXhwbGljaXRseSBvbiB0aGUgY29uZmlnIG9iamVjdC5cbiAqXG4gKiBAbW9kdWxlXG4gKi9cblxuaW1wb3J0IHsgY3JlYXRlQXBwIGFzIGFwcGtpdENyZWF0ZUFwcCwgZ2V0VXNlcm5hbWVXaXRoQXBpTG9va3VwIH0gZnJvbSBcIkBkYXRhYnJpY2tzL2FwcGtpdFwiO1xuLy8gQXBwS2l0J3Mgcm9vdCBiYXJyZWwgcmUtZXhwb3J0cyBgUGx1Z2luRGF0YWAgYnV0IG5vdCBgUGx1Z2luTWFwYDsgdGhlIHBhY2thZ2Vcbi8vIHB1Ymxpc2hlcyB0aGlzIHN1YnBhdGggZm9yIGV4YWN0bHkgdGhhdCB0eXBlLlxuaW1wb3J0IHR5cGUgeyBQbHVnaW5NYXAgfSBmcm9tIFwiQGRhdGFicmlja3MvYXBwa2l0L2Rpc3Qvc2hhcmVkL3NyYy9wbHVnaW5cIjtcbmltcG9ydCB7IGFzeW5jLCBsb2cgfSBmcm9tIFwiQGRieC10b29scy9zaGFyZWQtY29yZVwiO1xuXG5pbXBvcnQge1xuICBhcHBseUxha2ViYXNlVG9FbnYsXG4gIHJlc29sdmVMYWtlYmFzZUNvbm5lY3Rpb24sXG4gIHR5cGUgTGFrZWJhc2VDb25uZWN0aW9uLFxufSBmcm9tIFwiLi9sYWtlYmFzZS1yZXNvbHZlclwiO1xuaW1wb3J0IHsgcHJvdmlzaW9uQ2FjaGVTY2hlbWEgfSBmcm9tIFwiLi9wcm92aXNpb25cIjtcblxudHlwZSBBcHBLaXRDcmVhdGVBcHBDb25maWcgPSBOb25OdWxsYWJsZTxQYXJhbWV0ZXJzPHR5cGVvZiBhcHBraXRDcmVhdGVBcHA+WzBdPjtcbnR5cGUgQXBwS2l0UGx1Z2lucyA9IE5vbk51bGxhYmxlPEFwcEtpdENyZWF0ZUFwcENvbmZpZ1tcInBsdWdpbnNcIl0+O1xuXG4vKipcbiAqIFdoYXQgYXV0by1jb25maWd1cmF0aW9uIGRvZXMgYmVmb3JlIEFwcEtpdCBib290cy5cbiAqXG4gKiAtIGBcInByb3Zpc2lvblwiYDogcmVzb2x2ZSB0aGUgTGFrZWJhc2UgY29ubmVjdGlvbiBpbnRvIGBwcm9jZXNzLmVudmAsIHRoZW5cbiAqICAgZ3JhbnQgdGhlIEFwcEtpdCBjYWNoZSBzY2hlbWEgdG8gdGhlIGNvbm5lY3Rpbmcgcm9sZS5cbiAqIC0gYFwiZW52XCJgOiByZXNvbHZlIHRoZSBMYWtlYmFzZSBjb25uZWN0aW9uIGludG8gYHByb2Nlc3MuZW52YCBvbmx5LlxuICpcbiAqIE9taXQgaXQgdG8gZ2V0IGBcInByb3Zpc2lvblwiYCBnYXRlZCBvbiBhIGBsYWtlYmFzZWAgcGx1Z2luIGJlaW5nIHJlZ2lzdGVyZWQ7XG4gKiBzZXQgaXQgZXhwbGljaXRseSB0byBydW4gcmVnYXJkbGVzcyBvZiB0aGUgcGx1Z2luIGxpc3QsIG9yIHBhc3MgYGZhbHNlYCB0b1xuICogc2tpcCBhdXRvLWNvbmZpZ3VyYXRpb24gZW50aXJlbHkuXG4gKi9cbmV4cG9ydCB0eXBlIEF1dG9Db25maWd1cmVNb2RlID0gXCJlbnZcIiB8IFwicHJvdmlzaW9uXCI7XG5cbi8qKiBBcHBLaXQncyBgY3JlYXRlQXBwYCBjb25maWcgcGx1cyB0aGUgZGJ4LXRvb2xzIGF1dG8tY29uZmlndXJhdGlvbiBzd2l0Y2guICovXG5leHBvcnQgdHlwZSBDcmVhdGVBcHBDb25maWc8VCBleHRlbmRzIEFwcEtpdFBsdWdpbnMgPSBBcHBLaXRQbHVnaW5zPiA9IE9taXQ8XG4gIEFwcEtpdENyZWF0ZUFwcENvbmZpZyxcbiAgXCJwbHVnaW5zXCIgfCBcIm9uUGx1Z2luc1JlYWR5XCJcbj4gJiB7XG4gIHBsdWdpbnM/OiBUO1xuICBvblBsdWdpbnNSZWFkeT86IChhcHBraXQ6IFBsdWdpbk1hcDxUPikgPT4gdm9pZCB8IFByb21pc2U8dm9pZD47XG4gIC8qKiBBdXRvLWNvbmZpZ3VyYXRpb24gdG8gcnVuIGJlZm9yZSBBcHBLaXQgYm9vdHMuIERlZmF1bHRzIHRvIGBcInByb3Zpc2lvblwiYC4gKi9cbiAgYXV0b0NvbmZpZ3VyZT86IEF1dG9Db25maWd1cmVNb2RlIHwgZmFsc2U7XG59O1xuXG5jb25zdCBsb2dnZXIgPSBsb2cubG9nZ2VyKFwiY3JlYXRlLWFwcFwiKTtcblxuY29uc3QgTEFLRUJBU0VfUExVR0lOID0gXCJsYWtlYmFzZVwiO1xuY29uc3QgREVGQVVMVF9BVVRPX0NPTkZJR1VSRTogQXV0b0NvbmZpZ3VyZU1vZGUgPSBcInByb3Zpc2lvblwiO1xuXG4vKipcbiAqIFVwcGVyIGJvdW5kIG9uIGJvb3QtdGltZSBhdXRvLWNvbmZpZ3VyYXRpb24uIEl0IHJ1bnMgYXMgdGhlIHNlcnZpY2UgcHJpbmNpcGFsXG4gKiBiZWZvcmUgYW55IHBsdWdpbiBpcyBjb25zdHJ1Y3RlZCwgc28gaXQgc2l0cyBvdXRzaWRlIEFwcEtpdCdzIGludGVyY2VwdG9yXG4gKiBjaGFpbiBhbmQgaW5oZXJpdHMgbm8gdGltZW91dCwgcmV0cnksIG9yIHRlbGVtZXRyeSBmcm9tIGl0LiBUaGUgYnVkZ2V0IGNvdmVyc1xuICogdGhlIHJlc29sdmVyJ3Mgb3duIHdvcnN0IGNhc2UgKGNyZWF0ZSBhIHByb2plY3QsIHRoZW4gd2FpdCBmb3IgaXRzIGVuZHBvaW50KVxuICogcGx1cyB0aGUgY2FjaGUtc2NoZW1hIGdyYW50cy5cbiAqL1xuY29uc3QgQVVUT19DT05GSUdVUkVfVElNRU9VVF9NUyA9IDExICogNjBfMDAwO1xuXG5mdW5jdGlvbiB1c2VzUGx1Z2luPFQgZXh0ZW5kcyBBcHBLaXRQbHVnaW5zPihcbiAgY29uZmlnOiBDcmVhdGVBcHBDb25maWc8VD4gfCB1bmRlZmluZWQsXG4gIG5hbWU6IHN0cmluZyxcbik6IGJvb2xlYW4ge1xuICByZXR1cm4gQm9vbGVhbihjb25maWc/LnBsdWdpbnM/LnNvbWUoKGVudHJ5KSA9PiBlbnRyeS5uYW1lID09PSBuYW1lKSk7XG59XG5cbi8qKlxuICogUnVuIGVuYWJsZWQgYXV0by1jb25maWd1cmF0aW9uIHN0ZXBzIHdpdGhvdXQgY2FsbGluZyBBcHBLaXQncyBgY3JlYXRlQXBwYC5cbiAqXG4gKiBMYWtlYmFzZSBQb3N0Z3JlcyByZXNvbHZlcyB3aGVuIHtAbGluayBDcmVhdGVBcHBDb25maWcuYXV0b0NvbmZpZ3VyZX0gaXMgc2V0XG4gKiBleHBsaWNpdGx5IG9yIGEgYGxha2ViYXNlYCBwbHVnaW4gaXMgbGlzdGVkIGluIGBjb25maWcucGx1Z2luc2AuIGBzaWduYWxgXG4gKiBjYW5jZWxzIHRoZSByZXNvbHV0aW9uOyBpdCBpcyBjb21iaW5lZCB3aXRoIGFuIGludGVybmFsIGJvb3QgdGltZW91dCBlaXRoZXJcbiAqIHdheS5cbiAqXG4gKiBAZXhhbXBsZVxuICogaW1wb3J0IHsgY3JlYXRlQXBwIH0gZnJvbSBcIkBkYngtdG9vbHMvYXBwa2l0XCI7XG4gKlxuICogLy8gUG9wdWxhdGUgUEdIT1NUIC8gUEdEQVRBQkFTRSAvIExBS0VCQVNFX0VORFBPSU5UIHdpdGhvdXQgYm9vdGluZyBBcHBLaXQuXG4gKiBhd2FpdCBjcmVhdGVBcHAuYXV0b0NvbmZpZ3VyZSh7IGF1dG9Db25maWd1cmU6IFwiZW52XCIgfSk7XG4gKi9cbmV4cG9ydCBhc3luYyBmdW5jdGlvbiBhdXRvQ29uZmlndXJlPFQgZXh0ZW5kcyBBcHBLaXRQbHVnaW5zPihcbiAgY29uZmlnPzogQ3JlYXRlQXBwQ29uZmlnPFQ+LFxuICBzaWduYWw/OiBBYm9ydFNpZ25hbCxcbik6IFByb21pc2U8dm9pZD4ge1xuICBjb25zdCBtb2RlID0gY29uZmlnPy5hdXRvQ29uZmlndXJlID8/IERFRkFVTFRfQVVUT19DT05GSUdVUkU7XG4gIGNvbnN0IGV4cGxpY2l0ID0gY29uZmlnPy5hdXRvQ29uZmlndXJlICE9PSB1bmRlZmluZWQ7XG4gIGNvbnN0IGxha2ViYXNlUGx1Z2luUHJlc2VudCA9IHVzZXNQbHVnaW4oY29uZmlnLCBMQUtFQkFTRV9QTFVHSU4pO1xuICBpZiAobW9kZSA9PT0gZmFsc2UgfHwgIShleHBsaWNpdCB8fCBsYWtlYmFzZVBsdWdpblByZXNlbnQpKSB7XG4gICAgbG9nZ2VyLmluZm8oXCJyZWFkeVwiLCB7XG4gICAgICBhdXRvQ29uZmlndXJlOiBtb2RlLFxuICAgICAgbGFrZWJhc2VQbHVnaW5QcmVzZW50LFxuICAgICAgcHJvdmlzaW9uZWQ6IGZhbHNlLFxuICAgICAgc2tpcHBlZFJlYXNvbjogbW9kZSA9PT0gZmFsc2UgPyBcImRpc2FibGVkXCIgOiBcIm5vIGxha2ViYXNlIHBsdWdpblwiLFxuICAgIH0pO1xuICAgIHJldHVybjtcbiAgfVxuXG4gIGNvbnN0IGNvbnRyb2xsZXIgPSBuZXcgQWJvcnRDb250cm9sbGVyKCk7XG4gIGFzeW5jLnRpZUFib3J0U2lnbmFsKGNvbnRyb2xsZXIsIHNpZ25hbCk7XG4gIGFzeW5jLnRpZUFib3J0U2lnbmFsKGNvbnRyb2xsZXIsIEFib3J0U2lnbmFsLnRpbWVvdXQoQVVUT19DT05GSUdVUkVfVElNRU9VVF9NUykpO1xuXG4gIGNvbnN0IHByb3Zpc2lvbiA9IG1vZGUgPT09IFwicHJvdmlzaW9uXCI7XG4gIGF3YWl0IGF1dG9Db25maWd1cmVMYWtlYmFzZShwcm92aXNpb24sIGNvbnRyb2xsZXIuc2lnbmFsKTtcbiAgbG9nZ2VyLmluZm8oXCJyZWFkeVwiLCB7IGF1dG9Db25maWd1cmU6IG1vZGUsIGxha2ViYXNlUGx1Z2luUHJlc2VudCwgcHJvdmlzaW9uZWQ6IHByb3Zpc2lvbiB9KTtcbn1cblxuLyoqXG4gKiBSZXNvbHZlIExha2ViYXNlIFBvc3RncmVzIGNvbm5lY3Rpb24gaW5mbywgd3JpdGUgdGhlIHJlc29sdmVkIHZhbHVlcyB0b1xuICogYHByb2Nlc3MuZW52YCwgYW5kIHJldHVybiB0aGUgcmVjb3JkLiBVc2VkIGJ5IHtAbGluayBhdXRvQ29uZmlndXJlfTsgY2FsbFxuICoge0BsaW5rIHJlc29sdmVMYWtlYmFzZUNvbm5lY3Rpb259IGFuZCB7QGxpbmsgYXBwbHlMYWtlYmFzZVRvRW52fSBkaXJlY3RseSB3aGVuXG4gKiBmaW5lciBjb250cm9sIGlzIG5lZWRlZC5cbiAqL1xuYXN5bmMgZnVuY3Rpb24gYXV0b0NvbmZpZ3VyZUxha2ViYXNlKFxuICBwcm92aXNpb246IGJvb2xlYW4sXG4gIHNpZ25hbDogQWJvcnRTaWduYWwsXG4pOiBQcm9taXNlPExha2ViYXNlQ29ubmVjdGlvbj4ge1xuICBjb25zdCByZXNvbHZlZCA9IGF3YWl0IHJlc29sdmVMYWtlYmFzZUNvbm5lY3Rpb24odW5kZWZpbmVkLCBzaWduYWwpO1xuICBhcHBseUxha2ViYXNlVG9FbnYocmVzb2x2ZWQpO1xuICBjb25zdCB1c2VyID0gYXdhaXQgZ2V0VXNlcm5hbWVXaXRoQXBpTG9va3VwKHt9KTtcbiAgaWYgKHVzZXIpIHByb2Nlc3MuZW52LlBHVVNFUiA/Pz0gdXNlcjtcbiAgbG9nZ2VyLmluZm8oXCJlbnYgdXBkYXRlZFwiLCB7IC4uLnJlZGFjdExha2ViYXNlQ29ubmVjdGlvbihyZXNvbHZlZCksIHVzZXIgfSk7XG4gIGlmIChwcm92aXNpb24pIHtcbiAgICBhd2FpdCBwcm92aXNpb25DYWNoZVNjaGVtYSh1c2VyLCBsb2dnZXIpO1xuICB9XG4gIHJldHVybiByZXNvbHZlZDtcbn1cblxuZnVuY3Rpb24gcmVkYWN0TGFrZWJhc2VDb25uZWN0aW9uKHJlc29sdmVkOiBMYWtlYmFzZUNvbm5lY3Rpb24pOiBSZWNvcmQ8c3RyaW5nLCB1bmtub3duPiB7XG4gIHJldHVybiB7XG4gICAgcHJvamVjdDogcmVzb2x2ZWQucHJvamVjdCxcbiAgICBicmFuY2g6IHJlc29sdmVkLmJyYW5jaCxcbiAgICBlbmRwb2ludDogcmVzb2x2ZWQuZW5kcG9pbnQsXG4gICAgZGF0YWJhc2U6IHJlc29sdmVkLmRhdGFiYXNlLFxuICAgIGhvc3Q6IHJlc29sdmVkLmhvc3QsXG4gICAgcG9ydDogcmVzb2x2ZWQucG9ydCxcbiAgICBzc2xNb2RlOiByZXNvbHZlZC5zc2xNb2RlLFxuICB9O1xufVxuXG4vKipcbiAqIEF1dG8tY29uZmlndXJpbmcgZHJvcC1pbiBmb3IgQXBwS2l0J3MgYGNyZWF0ZUFwcGA6IHNhbWUgY29uZmlnLCBzYW1lIHR5cGVkXG4gKiBwbHVnaW4tZXhwb3J0IG1hcCwgd2l0aCB7QGxpbmsgYXV0b0NvbmZpZ3VyZX0gcnVuIGZpcnN0LlxuICpcbiAqIEBleGFtcGxlXG4gKiBpbXBvcnQgeyBjcmVhdGVBcHAgfSBmcm9tIFwiQGRieC10b29scy9hcHBraXRcIjtcbiAqIGltcG9ydCB7IGxha2ViYXNlLCBzZXJ2ZXIgfSBmcm9tIFwiQGRhdGFicmlja3MvYXBwa2l0XCI7XG4gKlxuICogY29uc3QgYXBwID0gYXdhaXQgY3JlYXRlQXBwLmNyZWF0ZUFwcCh7IHBsdWdpbnM6IFtzZXJ2ZXIoKSwgbGFrZWJhc2UoKV0gfSk7XG4gKi9cbmV4cG9ydCBhc3luYyBmdW5jdGlvbiBjcmVhdGVBcHA8VCBleHRlbmRzIEFwcEtpdFBsdWdpbnM+KFxuICBjb25maWc/OiBDcmVhdGVBcHBDb25maWc8VD4sXG4pOiBQcm9taXNlPFBsdWdpbk1hcDxUPj4ge1xuICBhd2FpdCBhdXRvQ29uZmlndXJlKGNvbmZpZyk7XG4gIGNvbnN0IGFwcENvbmZpZyA9IHsgLi4uY29uZmlnIH07XG4gIGRlbGV0ZSBhcHBDb25maWcuYXV0b0NvbmZpZ3VyZTtcbiAgcmV0dXJuIGFwcGtpdENyZWF0ZUFwcDxUPihhcHBDb25maWcpO1xufVxuIl19

package/lib/src/databricks.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Generic Databricks SDK glue (no AppKit): adapt WHATWG cancellation
+ * (`AbortSignal` / `AbortController`) into the SDK's `Context` /
+ * `CancellationToken` shapes so a single `AbortController` can drive every
+ * in-flight SDK call, plus Databricks runtime-environment detection.
+ *
+ * Server-only: leans on the Databricks SDK `Context`. Lives in node-appkit so
+ * the browser-safe shared-core stays SDK-free.
+ *
+ * @module
+ */
+import { Context } from "@databricks/sdk-experimental";
+/** Highest valid TCP port number. */
+export declare const MAX_TCP_PORT = 65535;
+/**
+ * Detect the Databricks App runtime from environment shape: requires a
+ * non-empty `DATABRICKS_APP_NAME`, a `DATABRICKS_HOST` that parses as an
+ * `http`/`https` URL, and a `DATABRICKS_APP_PORT` that is a valid TCP port.
+ * Reads `process.env` when no `env` is passed.
+ *
+ * @example
+ * import { databricks } from "@dbx-tools/appkit";
+ *
+ * // Skip bundle / app.yaml discovery when the app is already deployed.
+ * const local = !databricks.isAppEnv();
+ */
+export declare function isAppEnv(env?: Record<string, string | undefined>): boolean;
+/** Either an SDK `Context` or a WHATWG `AbortSignal`. */
+export type ContextLike = Context | AbortSignal;
+/**
+ * Wrap a `Context` (returned as-is) or `AbortSignal` (adapted) as an SDK `Context`.
+ *
+ * @example
+ * import { databricks } from "@dbx-tools/appkit";
+ * import { getWorkspaceClient } from "@databricks/appkit";
+ *
+ * await getWorkspaceClient({}).apiClient.request(
+ *   { path: "/api/2.0/serving-endpoints", method: "GET", headers: new Headers(), raw: false },
+ *   databricks.toContext(request.signal),
+ * );
+ */
+export declare function toContext(input: ContextLike): Context;
+/**
+ * Derive an SDK `Context` from `controller.signal`, optionally tying `input`
+ * into the controller so the controller becomes the single cancellation
+ * source for downstream SDK calls:
+ *
+ *   - `AbortSignal`: aborting it propagates into `controller` (and from there
+ *     into every SDK call you pass the returned context to).
+ *   - `Context`: its `cancellationToken` is tied into `controller`, and its
+ *     other fields (`logger`, `opName`, `rootClassName`, `rootFnName`, `opId`)
+ *     are preserved in the returned `Context`. The returned context's
+ *     `cancellationToken` is replaced with one backed by `controller.signal`.
+ *
+ * The tie is one-way (parent -> child): aborting `controller` directly does
+ * NOT cancel `input`. So a request-level cancel (your loop's `try/finally {
+ * controller.abort() }`) won't tear down a caller-supplied AbortSignal it
+ * didn't own.
+ */
+export declare function toContext(controller: AbortController, input?: ContextLike): Context;

package/lib/src/databricks.js

@@ -0,0 +1,107 @@
+/**
+ * Generic Databricks SDK glue (no AppKit): adapt WHATWG cancellation
+ * (`AbortSignal` / `AbortController`) into the SDK's `Context` /
+ * `CancellationToken` shapes so a single `AbortController` can drive every
+ * in-flight SDK call, plus Databricks runtime-environment detection.
+ *
+ * Server-only: leans on the Databricks SDK `Context`. Lives in node-appkit so
+ * the browser-safe shared-core stays SDK-free.
+ *
+ * @module
+ */
+import { Context } from "@databricks/sdk-experimental";
+import { async, log } from "@dbx-tools/shared-core";
+const logger = log.logger("databricks");
+/** Highest valid TCP port number. */
+export const MAX_TCP_PORT = 65_535;
+/**
+ * Detect the Databricks App runtime from environment shape: requires a
+ * non-empty `DATABRICKS_APP_NAME`, a `DATABRICKS_HOST` that parses as an
+ * `http`/`https` URL, and a `DATABRICKS_APP_PORT` that is a valid TCP port.
+ * Reads `process.env` when no `env` is passed.
+ *
+ * @example
+ * import { databricks } from "@dbx-tools/appkit";
+ *
+ * // Skip bundle / app.yaml discovery when the app is already deployed.
+ * const local = !databricks.isAppEnv();
+ */
+export function isAppEnv(env = process.env) {
+    const appName = env.DATABRICKS_APP_NAME?.trim();
+    const host = env.DATABRICKS_HOST?.trim();
+    const port = env.DATABRICKS_APP_PORT?.trim();
+    if (!appName || !host || !port) {
+        return false;
+    }
+    try {
+        const url = new URL(host);
+        if (!["http:", "https:"].includes(url.protocol)) {
+            logger.debug("app env rejected: host is not an http(s) URL");
+            return false;
+        }
+    }
+    catch {
+        logger.debug("app env rejected: host is not a URL");
+        return false;
+    }
+    const portNumber = Number(port);
+    if (!Number.isInteger(portNumber) || portNumber < 1 || portNumber > MAX_TCP_PORT) {
+        logger.debug("app env rejected: DATABRICKS_APP_PORT is not a TCP port");
+        return false;
+    }
+    return true;
+}
+export function toContext(source, input) {
+    if (!(source instanceof AbortController)) {
+        if (source instanceof Context)
+            return source;
+        return new Context({ cancellationToken: signalToCancellationToken(source) });
+    }
+    if (input instanceof AbortSignal) {
+        async.tieAbortSignal(source, input);
+    }
+    else if (input instanceof Context) {
+        const token = input.cancellationToken;
+        if (token)
+            tieCancellationToken(source, token);
+        const merged = input.copy();
+        merged.setItems({ cancellationToken: signalToCancellationToken(source.signal) });
+        return merged;
+    }
+    return new Context({ cancellationToken: signalToCancellationToken(source.signal) });
+}
+/**
+ * Adapt a WHATWG `AbortSignal` to the Databricks SDK's `CancellationToken`
+ * interface. The SDK's `api-client.ts` internally creates an `AbortController`
+ * and wires `cancellationToken.onCancellationRequested` to it, so this adapter
+ * is the one-line bridge from "platform-standard cancellation" to "the SDK
+ * aborts the fetch on your behalf".
+ */
+function signalToCancellationToken(signal) {
+    return {
+        get isCancellationRequested() {
+            return signal.aborted;
+        },
+        onCancellationRequested(cb) {
+            if (signal.aborted) {
+                cb(signal.reason);
+                return;
+            }
+            signal.addEventListener("abort", () => cb(signal.reason), { once: true });
+        },
+    };
+}
+/**
+ * Tie the SDK's `CancellationToken` interface back into an `AbortController`.
+ * Mirrors `async.tieAbortSignal` but for the SDK's cancellation shape, used
+ * when a caller hands us a pre-built `Context` whose token we want to fold into
+ * our own controller.
+ */
+function tieCancellationToken(controller, token) {
+    if (token.isCancellationRequested) {
+        controller.abort();
+        return;
+    }
+    token.onCancellationRequested((reason) => controller.abort(reason));
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGF0YWJyaWNrcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9kYXRhYnJpY2tzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7Ozs7O0dBVUc7QUFHSCxPQUFPLEVBQUUsT0FBTyxFQUFFLE1BQU0sOEJBQThCLENBQUM7QUFDdkQsT0FBTyxFQUFFLEtBQUssRUFBRSxHQUFHLEVBQUUsTUFBTSx3QkFBd0IsQ0FBQztBQUVwRCxNQUFNLE1BQU0sR0FBRyxHQUFHLENBQUMsTUFBTSxDQUFDLFlBQVksQ0FBQyxDQUFDO0FBRXhDLHFDQUFxQztBQUNyQyxNQUFNLENBQUMsTUFBTSxZQUFZLEdBQUcsTUFBTSxDQUFDO0FBRW5DOzs7Ozs7Ozs7OztHQVdHO0FBQ0gsTUFBTSxVQUFVLFFBQVEsQ0FBQyxNQUEwQyxPQUFPLENBQUMsR0FBRztJQUM1RSxNQUFNLE9BQU8sR0FBRyxHQUFHLENBQUMsbUJBQW1CLEVBQUUsSUFBSSxFQUFFLENBQUM7SUFDaEQsTUFBTSxJQUFJLEdBQUcsR0FBRyxDQUFDLGVBQWUsRUFBRSxJQUFJLEVBQUUsQ0FBQztJQUN6QyxNQUFNLElBQUksR0FBRyxHQUFHLENBQUMsbUJBQW1CLEVBQUUsSUFBSSxFQUFFLENBQUM7SUFFN0MsSUFBSSxDQUFDLE9BQU8sSUFBSSxDQUFDLElBQUksSUFBSSxDQUFDLElBQUksRUFBRSxDQUFDO1FBQy9CLE9BQU8sS0FBSyxDQUFDO0lBQ2YsQ0FBQztJQUVELElBQUksQ0FBQztRQUNILE1BQU0sR0FBRyxHQUFHLElBQUksR0FBRyxDQUFDLElBQUksQ0FBQyxDQUFDO1FBQzFCLElBQUksQ0FBQyxDQUFDLE9BQU8sRUFBRSxRQUFRLENBQUMsQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFDLFFBQVEsQ0FBQyxFQUFFLENBQUM7WUFDaEQsTUFBTSxDQUFDLEtBQUssQ0FBQyw4Q0FBOEMsQ0FBQyxDQUFDO1lBQzdELE9BQU8sS0FBSyxDQUFDO1FBQ2YsQ0FBQztJQUNILENBQUM7SUFBQyxNQUFNLENBQUM7UUFDUCxNQUFNLENBQUMsS0FBSyxDQUFDLHFDQUFxQyxDQUFDLENBQUM7UUFDcEQsT0FBTyxLQUFLLENBQUM7SUFDZixDQUFDO0lBRUQsTUFBTSxVQUFVLEdBQUcsTUFBTSxDQUFDLElBQUksQ0FBQyxDQUFDO0lBQ2hDLElBQUksQ0FBQyxNQUFNLENBQUMsU0FBUyxDQUFDLFVBQVUsQ0FBQyxJQUFJLFVBQVUsR0FBRyxDQUFDLElBQUksVUFBVSxHQUFHLFlBQVksRUFBRSxDQUFDO1FBQ2pGLE1BQU0sQ0FBQyxLQUFLLENBQUMseURBQXlELENBQUMsQ0FBQztRQUN4RSxPQUFPLEtBQUssQ0FBQztJQUNmLENBQUM7SUFFRCxPQUFPLElBQUksQ0FBQztBQUNkLENBQUM7QUFvQ0QsTUFBTSxVQUFVLFNBQVMsQ0FBQyxNQUFxQyxFQUFFLEtBQW1CO0lBQ2xGLElBQUksQ0FBQyxDQUFDLE1BQU0sWUFBWSxlQUFlLENBQUMsRUFBRSxDQUFDO1FBQ3pDLElBQUksTUFBTSxZQUFZLE9BQU87WUFBRSxPQUFPLE1BQU0sQ0FBQztRQUM3QyxPQUFPLElBQUksT0FBTyxDQUFDLEVBQUUsaUJBQWlCLEVBQUUseUJBQXlCLENBQUMsTUFBTSxDQUFDLEVBQUUsQ0FBQyxDQUFDO0lBQy9FLENBQUM7SUFDRCxJQUFJLEtBQUssWUFBWSxXQUFXLEVBQUUsQ0FBQztRQUNqQyxLQUFLLENBQUMsY0FBYyxDQUFDLE1BQU0sRUFBRSxLQUFLLENBQUMsQ0FBQztJQUN0QyxDQUFDO1NBQU0sSUFBSSxLQUFLLFlBQVksT0FBTyxFQUFFLENBQUM7UUFDcEMsTUFBTSxLQUFLLEdBQUcsS0FBSyxDQUFDLGlCQUFpQixDQUFDO1FBQ3RDLElBQUksS0FBSztZQUFFLG9CQUFvQixDQUFDLE1BQU0sRUFBRSxLQUFLLENBQUMsQ0FBQztRQUMvQyxNQUFNLE1BQU0sR0FBRyxLQUFLLENBQUMsSUFBSSxFQUFFLENBQUM7UUFDNUIsTUFBTSxDQUFDLFFBQVEsQ0FBQyxFQUFFLGlCQUFpQixFQUFFLHlCQUF5QixDQUFDLE1BQU0sQ0FBQyxNQUFNLENBQUMsRUFBRSxDQUFDLENBQUM7UUFDakYsT0FBTyxNQUFNLENBQUM7SUFDaEIsQ0FBQztJQUNELE9BQU8sSUFBSSxPQUFPLENBQUMsRUFBRSxpQkFBaUIsRUFBRSx5QkFBeUIsQ0FBQyxNQUFNLENBQUMsTUFBTSxDQUFDLEVBQUUsQ0FBQyxDQUFDO0FBQ3RGLENBQUM7QUFFRDs7Ozs7O0dBTUc7QUFDSCxTQUFTLHlCQUF5QixDQUFDLE1BQW1CO0lBQ3BELE9BQU87UUFDTCxJQUFJLHVCQUF1QjtZQUN6QixPQUFPLE1BQU0sQ0FBQyxPQUFPLENBQUM7UUFDeEIsQ0FBQztRQUNELHVCQUF1QixDQUFDLEVBQUU7WUFDeEIsSUFBSSxNQUFNLENBQUMsT0FBTyxFQUFFLENBQUM7Z0JBQ25CLEVBQUUsQ0FBQyxNQUFNLENBQUMsTUFBTSxDQUFDLENBQUM7Z0JBQ2xCLE9BQU87WUFDVCxDQUFDO1lBQ0QsTUFBTSxDQUFDLGdCQUFnQixDQUFDLE9BQU8sRUFBRSxHQUFHLEVBQUUsQ0FBQyxFQUFFLENBQUMsTUFBTSxDQUFDLE1BQU0sQ0FBQyxFQUFFLEVBQUUsSUFBSSxFQUFFLElBQUksRUFBRSxDQUFDLENBQUM7UUFDNUUsQ0FBQztLQUNGLENBQUM7QUFDSixDQUFDO0FBRUQ7Ozs7O0dBS0c7QUFDSCxTQUFTLG9CQUFvQixDQUFDLFVBQTJCLEVBQUUsS0FBd0I7SUFDakYsSUFBSSxLQUFLLENBQUMsdUJBQXVCLEVBQUUsQ0FBQztRQUNsQyxVQUFVLENBQUMsS0FBSyxFQUFFLENBQUM7UUFDbkIsT0FBTztJQUNULENBQUM7SUFDRCxLQUFLLENBQUMsdUJBQXVCLENBQUMsQ0FBQyxNQUFNLEVBQUUsRUFBRSxDQUFDLFVBQVUsQ0FBQyxLQUFLLENBQUMsTUFBTSxDQUFDLENBQUMsQ0FBQztBQUN0RSxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBHZW5lcmljIERhdGFicmlja3MgU0RLIGdsdWUgKG5vIEFwcEtpdCk6IGFkYXB0IFdIQVRXRyBjYW5jZWxsYXRpb25cbiAqIChgQWJvcnRTaWduYWxgIC8gYEFib3J0Q29udHJvbGxlcmApIGludG8gdGhlIFNESydzIGBDb250ZXh0YCAvXG4gKiBgQ2FuY2VsbGF0aW9uVG9rZW5gIHNoYXBlcyBzbyBhIHNpbmdsZSBgQWJvcnRDb250cm9sbGVyYCBjYW4gZHJpdmUgZXZlcnlcbiAqIGluLWZsaWdodCBTREsgY2FsbCwgcGx1cyBEYXRhYnJpY2tzIHJ1bnRpbWUtZW52aXJvbm1lbnQgZGV0ZWN0aW9uLlxuICpcbiAqIFNlcnZlci1vbmx5OiBsZWFucyBvbiB0aGUgRGF0YWJyaWNrcyBTREsgYENvbnRleHRgLiBMaXZlcyBpbiBub2RlLWFwcGtpdCBzb1xuICogdGhlIGJyb3dzZXItc2FmZSBzaGFyZWQtY29yZSBzdGF5cyBTREstZnJlZS5cbiAqXG4gKiBAbW9kdWxlXG4gKi9cblxuaW1wb3J0IHR5cGUgeyBDYW5jZWxsYXRpb25Ub2tlbiB9IGZyb20gXCJAZGF0YWJyaWNrcy9zZGstZXhwZXJpbWVudGFsXCI7XG5pbXBvcnQgeyBDb250ZXh0IH0gZnJvbSBcIkBkYXRhYnJpY2tzL3Nkay1leHBlcmltZW50YWxcIjtcbmltcG9ydCB7IGFzeW5jLCBsb2cgfSBmcm9tIFwiQGRieC10b29scy9zaGFyZWQtY29yZVwiO1xuXG5jb25zdCBsb2dnZXIgPSBsb2cubG9nZ2VyKFwiZGF0YWJyaWNrc1wiKTtcblxuLyoqIEhpZ2hlc3QgdmFsaWQgVENQIHBvcnQgbnVtYmVyLiAqL1xuZXhwb3J0IGNvbnN0IE1BWF9UQ1BfUE9SVCA9IDY1XzUzNTtcblxuLyoqXG4gKiBEZXRlY3QgdGhlIERhdGFicmlja3MgQXBwIHJ1bnRpbWUgZnJvbSBlbnZpcm9ubWVudCBzaGFwZTogcmVxdWlyZXMgYVxuICogbm9uLWVtcHR5IGBEQVRBQlJJQ0tTX0FQUF9OQU1FYCwgYSBgREFUQUJSSUNLU19IT1NUYCB0aGF0IHBhcnNlcyBhcyBhblxuICogYGh0dHBgL2BodHRwc2AgVVJMLCBhbmQgYSBgREFUQUJSSUNLU19BUFBfUE9SVGAgdGhhdCBpcyBhIHZhbGlkIFRDUCBwb3J0LlxuICogUmVhZHMgYHByb2Nlc3MuZW52YCB3aGVuIG5vIGBlbnZgIGlzIHBhc3NlZC5cbiAqXG4gKiBAZXhhbXBsZVxuICogaW1wb3J0IHsgZGF0YWJyaWNrcyB9IGZyb20gXCJAZGJ4LXRvb2xzL2FwcGtpdFwiO1xuICpcbiAqIC8vIFNraXAgYnVuZGxlIC8gYXBwLnlhbWwgZGlzY292ZXJ5IHdoZW4gdGhlIGFwcCBpcyBhbHJlYWR5IGRlcGxveWVkLlxuICogY29uc3QgbG9jYWwgPSAhZGF0YWJyaWNrcy5pc0FwcEVudigpO1xuICovXG5leHBvcnQgZnVuY3Rpb24gaXNBcHBFbnYoZW52OiBSZWNvcmQ8c3RyaW5nLCBzdHJpbmcgfCB1bmRlZmluZWQ+ID0gcHJvY2Vzcy5lbnYpOiBib29sZWFuIHtcbiAgY29uc3QgYXBwTmFtZSA9IGVudi5EQVRBQlJJQ0tTX0FQUF9OQU1FPy50cmltKCk7XG4gIGNvbnN0IGhvc3QgPSBlbnYuREFUQUJSSUNLU19IT1NUPy50cmltKCk7XG4gIGNvbnN0IHBvcnQgPSBlbnYuREFUQUJSSUNLU19BUFBfUE9SVD8udHJpbSgpO1xuXG4gIGlmICghYXBwTmFtZSB8fCAhaG9zdCB8fCAhcG9ydCkge1xuICAgIHJldHVybiBmYWxzZTtcbiAgfVxuXG4gIHRyeSB7XG4gICAgY29uc3QgdXJsID0gbmV3IFVSTChob3N0KTtcbiAgICBpZiAoIVtcImh0dHA6XCIsIFwiaHR0cHM6XCJdLmluY2x1ZGVzKHVybC5wcm90b2NvbCkpIHtcbiAgICAgIGxvZ2dlci5kZWJ1ZyhcImFwcCBlbnYgcmVqZWN0ZWQ6IGhvc3QgaXMgbm90IGFuIGh0dHAocykgVVJMXCIpO1xuICAgICAgcmV0dXJuIGZhbHNlO1xuICAgIH1cbiAgfSBjYXRjaCB7XG4gICAgbG9nZ2VyLmRlYnVnKFwiYXBwIGVudiByZWplY3RlZDogaG9zdCBpcyBub3QgYSBVUkxcIik7XG4gICAgcmV0dXJuIGZhbHNlO1xuICB9XG5cbiAgY29uc3QgcG9ydE51bWJlciA9IE51bWJlcihwb3J0KTtcbiAgaWYgKCFOdW1iZXIuaXNJbnRlZ2VyKHBvcnROdW1iZXIpIHx8IHBvcnROdW1iZXIgPCAxIHx8IHBvcnROdW1iZXIgPiBNQVhfVENQX1BPUlQpIHtcbiAgICBsb2dnZXIuZGVidWcoXCJhcHAgZW52IHJlamVjdGVkOiBEQVRBQlJJQ0tTX0FQUF9QT1JUIGlzIG5vdCBhIFRDUCBwb3J0XCIpO1xuICAgIHJldHVybiBmYWxzZTtcbiAgfVxuXG4gIHJldHVybiB0cnVlO1xufVxuXG4vKiogRWl0aGVyIGFuIFNESyBgQ29udGV4dGAgb3IgYSBXSEFUV0cgYEFib3J0U2lnbmFsYC4gKi9cbmV4cG9ydCB0eXBlIENvbnRleHRMaWtlID0gQ29udGV4dCB8IEFib3J0U2lnbmFsO1xuXG4vKipcbiAqIFdyYXAgYSBgQ29udGV4dGAgKHJldHVybmVkIGFzLWlzKSBvciBgQWJvcnRTaWduYWxgIChhZGFwdGVkKSBhcyBhbiBTREsgYENvbnRleHRgLlxuICpcbiAqIEBleGFtcGxlXG4gKiBpbXBvcnQgeyBkYXRhYnJpY2tzIH0gZnJvbSBcIkBkYngtdG9vbHMvYXBwa2l0XCI7XG4gKiBpbXBvcnQgeyBnZXRXb3Jrc3BhY2VDbGllbnQgfSBmcm9tIFwiQGRhdGFicmlja3MvYXBwa2l0XCI7XG4gKlxuICogYXdhaXQgZ2V0V29ya3NwYWNlQ2xpZW50KHt9KS5hcGlDbGllbnQucmVxdWVzdChcbiAqICAgeyBwYXRoOiBcIi9hcGkvMi4wL3NlcnZpbmctZW5kcG9pbnRzXCIsIG1ldGhvZDogXCJHRVRcIiwgaGVhZGVyczogbmV3IEhlYWRlcnMoKSwgcmF3OiBmYWxzZSB9LFxuICogICBkYXRhYnJpY2tzLnRvQ29udGV4dChyZXF1ZXN0LnNpZ25hbCksXG4gKiApO1xuICovXG5leHBvcnQgZnVuY3Rpb24gdG9Db250ZXh0KGlucHV0OiBDb250ZXh0TGlrZSk6IENvbnRleHQ7XG4vKipcbiAqIERlcml2ZSBhbiBTREsgYENvbnRleHRgIGZyb20gYGNvbnRyb2xsZXIuc2lnbmFsYCwgb3B0aW9uYWxseSB0eWluZyBgaW5wdXRgXG4gKiBpbnRvIHRoZSBjb250cm9sbGVyIHNvIHRoZSBjb250cm9sbGVyIGJlY29tZXMgdGhlIHNpbmdsZSBjYW5jZWxsYXRpb25cbiAqIHNvdXJjZSBmb3IgZG93bnN0cmVhbSBTREsgY2FsbHM6XG4gKlxuICogICAtIGBBYm9ydFNpZ25hbGA6IGFib3J0aW5nIGl0IHByb3BhZ2F0ZXMgaW50byBgY29udHJvbGxlcmAgKGFuZCBmcm9tIHRoZXJlXG4gKiAgICAgaW50byBldmVyeSBTREsgY2FsbCB5b3UgcGFzcyB0aGUgcmV0dXJuZWQgY29udGV4dCB0bykuXG4gKiAgIC0gYENvbnRleHRgOiBpdHMgYGNhbmNlbGxhdGlvblRva2VuYCBpcyB0aWVkIGludG8gYGNvbnRyb2xsZXJgLCBhbmQgaXRzXG4gKiAgICAgb3RoZXIgZmllbGRzIChgbG9nZ2VyYCwgYG9wTmFtZWAsIGByb290Q2xhc3NOYW1lYCwgYHJvb3RGbk5hbWVgLCBgb3BJZGApXG4gKiAgICAgYXJlIHByZXNlcnZlZCBpbiB0aGUgcmV0dXJuZWQgYENvbnRleHRgLiBUaGUgcmV0dXJuZWQgY29udGV4dCdzXG4gKiAgICAgYGNhbmNlbGxhdGlvblRva2VuYCBpcyByZXBsYWNlZCB3aXRoIG9uZSBiYWNrZWQgYnkgYGNvbnRyb2xsZXIuc2lnbmFsYC5cbiAqXG4gKiBUaGUgdGllIGlzIG9uZS13YXkgKHBhcmVudCAtPiBjaGlsZCk6IGFib3J0aW5nIGBjb250cm9sbGVyYCBkaXJlY3RseSBkb2VzXG4gKiBOT1QgY2FuY2VsIGBpbnB1dGAuIFNvIGEgcmVxdWVzdC1sZXZlbCBjYW5jZWwgKHlvdXIgbG9vcCdzIGB0cnkvZmluYWxseSB7XG4gKiBjb250cm9sbGVyLmFib3J0KCkgfWApIHdvbid0IHRlYXIgZG93biBhIGNhbGxlci1zdXBwbGllZCBBYm9ydFNpZ25hbCBpdFxuICogZGlkbid0IG93bi5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIHRvQ29udGV4dChjb250cm9sbGVyOiBBYm9ydENvbnRyb2xsZXIsIGlucHV0PzogQ29udGV4dExpa2UpOiBDb250ZXh0O1xuZXhwb3J0IGZ1bmN0aW9uIHRvQ29udGV4dChzb3VyY2U6IEFib3J0Q29udHJvbGxlciB8IENvbnRleHRMaWtlLCBpbnB1dD86IENvbnRleHRMaWtlKTogQ29udGV4dCB7XG4gIGlmICghKHNvdXJjZSBpbnN0YW5jZW9mIEFib3J0Q29udHJvbGxlcikpIHtcbiAgICBpZiAoc291cmNlIGluc3RhbmNlb2YgQ29udGV4dCkgcmV0dXJuIHNvdXJjZTtcbiAgICByZXR1cm4gbmV3IENvbnRleHQoeyBjYW5jZWxsYXRpb25Ub2tlbjogc2lnbmFsVG9DYW5jZWxsYXRpb25Ub2tlbihzb3VyY2UpIH0pO1xuICB9XG4gIGlmIChpbnB1dCBpbnN0YW5jZW9mIEFib3J0U2lnbmFsKSB7XG4gICAgYXN5bmMudGllQWJvcnRTaWduYWwoc291cmNlLCBpbnB1dCk7XG4gIH0gZWxzZSBpZiAoaW5wdXQgaW5zdGFuY2VvZiBDb250ZXh0KSB7XG4gICAgY29uc3QgdG9rZW4gPSBpbnB1dC5jYW5jZWxsYXRpb25Ub2tlbjtcbiAgICBpZiAodG9rZW4pIHRpZUNhbmNlbGxhdGlvblRva2VuKHNvdXJjZSwgdG9rZW4pO1xuICAgIGNvbnN0IG1lcmdlZCA9IGlucHV0LmNvcHkoKTtcbiAgICBtZXJnZWQuc2V0SXRlbXMoeyBjYW5jZWxsYXRpb25Ub2tlbjogc2lnbmFsVG9DYW5jZWxsYXRpb25Ub2tlbihzb3VyY2Uuc2lnbmFsKSB9KTtcbiAgICByZXR1cm4gbWVyZ2VkO1xuICB9XG4gIHJldHVybiBuZXcgQ29udGV4dCh7IGNhbmNlbGxhdGlvblRva2VuOiBzaWduYWxUb0NhbmNlbGxhdGlvblRva2VuKHNvdXJjZS5zaWduYWwpIH0pO1xufVxuXG4vKipcbiAqIEFkYXB0IGEgV0hBVFdHIGBBYm9ydFNpZ25hbGAgdG8gdGhlIERhdGFicmlja3MgU0RLJ3MgYENhbmNlbGxhdGlvblRva2VuYFxuICogaW50ZXJmYWNlLiBUaGUgU0RLJ3MgYGFwaS1jbGllbnQudHNgIGludGVybmFsbHkgY3JlYXRlcyBhbiBgQWJvcnRDb250cm9sbGVyYFxuICogYW5kIHdpcmVzIGBjYW5jZWxsYXRpb25Ub2tlbi5vbkNhbmNlbGxhdGlvblJlcXVlc3RlZGAgdG8gaXQsIHNvIHRoaXMgYWRhcHRlclxuICogaXMgdGhlIG9uZS1saW5lIGJyaWRnZSBmcm9tIFwicGxhdGZvcm0tc3RhbmRhcmQgY2FuY2VsbGF0aW9uXCIgdG8gXCJ0aGUgU0RLXG4gKiBhYm9ydHMgdGhlIGZldGNoIG9uIHlvdXIgYmVoYWxmXCIuXG4gKi9cbmZ1bmN0aW9uIHNpZ25hbFRvQ2FuY2VsbGF0aW9uVG9rZW4oc2lnbmFsOiBBYm9ydFNpZ25hbCk6IENhbmNlbGxhdGlvblRva2VuIHtcbiAgcmV0dXJuIHtcbiAgICBnZXQgaXNDYW5jZWxsYXRpb25SZXF1ZXN0ZWQoKSB7XG4gICAgICByZXR1cm4gc2lnbmFsLmFib3J0ZWQ7XG4gICAgfSxcbiAgICBvbkNhbmNlbGxhdGlvblJlcXVlc3RlZChjYikge1xuICAgICAgaWYgKHNpZ25hbC5hYm9ydGVkKSB7XG4gICAgICAgIGNiKHNpZ25hbC5yZWFzb24pO1xuICAgICAgICByZXR1cm47XG4gICAgICB9XG4gICAgICBzaWduYWwuYWRkRXZlbnRMaXN0ZW5lcihcImFib3J0XCIsICgpID0+IGNiKHNpZ25hbC5yZWFzb24pLCB7IG9uY2U6IHRydWUgfSk7XG4gICAgfSxcbiAgfTtcbn1cblxuLyoqXG4gKiBUaWUgdGhlIFNESydzIGBDYW5jZWxsYXRpb25Ub2tlbmAgaW50ZXJmYWNlIGJhY2sgaW50byBhbiBgQWJvcnRDb250cm9sbGVyYC5cbiAqIE1pcnJvcnMgYGFzeW5jLnRpZUFib3J0U2lnbmFsYCBidXQgZm9yIHRoZSBTREsncyBjYW5jZWxsYXRpb24gc2hhcGUsIHVzZWRcbiAqIHdoZW4gYSBjYWxsZXIgaGFuZHMgdXMgYSBwcmUtYnVpbHQgYENvbnRleHRgIHdob3NlIHRva2VuIHdlIHdhbnQgdG8gZm9sZCBpbnRvXG4gKiBvdXIgb3duIGNvbnRyb2xsZXIuXG4gKi9cbmZ1bmN0aW9uIHRpZUNhbmNlbGxhdGlvblRva2VuKGNvbnRyb2xsZXI6IEFib3J0Q29udHJvbGxlciwgdG9rZW46IENhbmNlbGxhdGlvblRva2VuKTogdm9pZCB7XG4gIGlmICh0b2tlbi5pc0NhbmNlbGxhdGlvblJlcXVlc3RlZCkge1xuICAgIGNvbnRyb2xsZXIuYWJvcnQoKTtcbiAgICByZXR1cm47XG4gIH1cbiAgdG9rZW4ub25DYW5jZWxsYXRpb25SZXF1ZXN0ZWQoKHJlYXNvbikgPT4gY29udHJvbGxlci5hYm9ydChyZWFzb24pKTtcbn1cbiJdfQ==

package/lib/src/lakebase-resolver.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Lakebase Postgres connection resolver.
+ *
+ * Reads the same env vars the `lakebase` plugin consumes (`PGHOST`,
+ * `PGDATABASE`, `PGPORT`, `PGSSLMODE`, `LAKEBASE_ENDPOINT`) and fills in
+ * whichever pieces are missing using the Lakebase Autoscaling REST API
+ * under `/api/2.0/postgres/` via the Databricks workspace client.
+ *
+ * `LAKEBASE_ENDPOINT` (and `config.endpoint`) accept anything
+ * {@link parseAddress} understands - canonical resource paths, Postgres
+ * URIs, bare hostnames, or bare project ids. The resolver layers
+ * whatever pieces fall out of parsing under explicit config / env
+ * values, then fills the remaining gaps via the API:
+ *
+ *   1. Reverse-lookup: when a host is known but no resource path is,
+ *      scan projects -> branches -> endpoints for a matching
+ *      `status.hosts.host` and recover the owning project/branch/endpoint.
+ *   2. Pick: when a project is known but child resources aren't, prefer
+ *      the server-side default (`status.default`, `ENDPOINT_TYPE_READ_WRITE`,
+ *      `databricks_postgres`) and fall back to "the only one" when a
+ *      listing returns a single result.
+ *   3. Auto-create: when no projects exist at all, create one whose
+ *      id defaults to `project.name()` slugified (override
+ *      with `config.autoCreate: "my-id"` or disable with
+ *      `config.autoCreate: false`). The create call is idempotent - an
+ *      `ALREADY_EXISTS` response from a concurrent boot is treated as
+ *      success. Then poll the default endpoint until it reports
+ *      `current_state` `READY` or `IDLE`.
+ *
+ * {@link applyLakebaseToEnv} writes the resolved values back to
+ * `process.env` so the downstream `lakebase` plugin picks them up.
+ *
+ * @see https://docs.databricks.com/api/workspace/postgres
+ *
+ * @module
+ */
+import { type LakebaseConnectionInputs, type SslMode } from "./pgaddress.js";
+/**
+ * User-supplied Lakebase inputs (config or env) before any API resolution.
+ * Extends {@link LakebaseConnectionInputs} with resolver-only options.
+ * {@link resolveLakebaseConnection} fills gaps from the Lakebase API when
+ * it has enough context (typically a `project`).
+ */
+export interface LakebaseResolverInputs extends LakebaseConnectionInputs {
+    /**
+     * What to do when no project exists in the workspace at all.
+     * - `undefined` (default): derive a project id from
+     *   {@link project.name} (the host repo's `package.json`
+     *   name) slugified to Lakebase id constraints, then create it.
+     * - `string`: create a new project with this exact id.
+     * - `false`: skip creation and throw with a clear error message.
+     */
+    autoCreate?: string | false;
+}
+/** Fully-resolved Lakebase Postgres connection. */
+export interface LakebaseConnection extends LakebaseConnectionInputs {
+    port: number;
+    sslMode: SslMode;
+}
+/**
+ * Validate a `PGPORT`-shaped value. Returns `undefined` when unset, and throws
+ * a {@link ValidationError} naming `PGPORT` for anything that is not a TCP
+ * port, so a typo cannot reach the connection record as `NaN`.
+ */
+export declare function parsePort(value: string | number | undefined): number | undefined;
+/**
+ * Validate a `PGSSLMODE`-shaped value. Returns `undefined` when unset, and
+ * throws a {@link ValidationError} naming `PGSSLMODE` for an unsupported mode
+ * rather than handing `pg` a value it will reject at connect time.
+ */
+export declare function parseSslMode(value: string | undefined): SslMode | undefined;
+/**
+ * Delay before the next poll attempt: exponential backoff capped at
+ * {@link POLL_MAX_DELAY_MS}, plus jitter so several apps booting against the
+ * same workspace do not retry in lockstep.
+ */
+export declare function nextPollDelay(attempt: number, baseMs: number): number;
+/**
+ * Wait out {@link nextPollDelay} before the next attempt. Rejects with the
+ * signal's reason when the caller cancels mid-wait, so a poll loop unwinds
+ * instead of finishing its backoff first.
+ */
+export declare function pollDelay(attempt: number, baseMs: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Pull resolver inputs from `process.env`, parse the address blob, and
+ * layer explicit config on top with this precedence:
+ *
+ *   `config.<field>` > `config.resolveConfigValue` (`env`, then bundle
+ *   validate JSON) > whatever {@link parseAddress} recovered from the
+ *   `endpoint` / `LAKEBASE_ENDPOINT` blob.
+ *
+ * Set `config.endpoint` (or `LAKEBASE_ENDPOINT`) to any input
+ * {@link parseAddress} understands: canonical resource paths, Postgres
+ * URIs, bare hostnames, or bare project ids.
+ */
+export declare function readLakebaseInputs(config?: LakebaseResolverInputs): Promise<LakebaseResolverInputs>;
+/**
+ * Resolve a fully-populated Postgres connection record from config + env.
+ *
+ * Returns immediately without network traffic when env already supplies
+ * `endpoint`, `host`, and `database`. Otherwise issues REST calls and
+ * may auto-create a project (see module docstring).
+ *
+ * `signal` cancels every REST call and inter-poll sleep.
+ *
+ * @example
+ * import { lakebaseResolver } from "@dbx-tools/appkit";
+ *
+ * const resolved = await lakebaseResolver.resolveLakebaseConnection(
+ *   { autoCreate: false },
+ *   AbortSignal.timeout(60_000),
+ * );
+ * lakebaseResolver.applyLakebaseToEnv(resolved);
+ */
+export declare function resolveLakebaseConnection(config?: LakebaseResolverInputs, signal?: AbortSignal): Promise<LakebaseConnection>;
+/**
+ * Write resolved values back to `process.env` so the `lakebase` plugin
+ * (which reads env directly) picks them up during its own `setup()`.
+ * Existing env values are preserved; only missing keys are filled in,
+ * which keeps explicit overrides authoritative.
+ */
+export declare function applyLakebaseToEnv(resolved: LakebaseConnection): void;