@dbx-tools/appkit 0.6.69 → 0.6.71

package/README.md

@@ -50,16 +50,16 @@ Use this package when the friction is around bootstrapping and reuse:
 
 ## Create An Auto-Configured App
 
-`createApp.createApp` is a drop-in wrapper around AppKit `createApp` with the
+`appkit.createApp` is a drop-in wrapper around AppKit `createApp` with the
 same config and the same typed plugin-export map. It runs
-`createApp.autoConfigure()` first so enabled capabilities can populate
+`appkit.autoConfigure()` first so enabled capabilities can populate
 environment variables before plugin setup runs.
 
 ```ts
 import { lakebase, server } from "@databricks/appkit";
-import { createApp } from "@dbx-tools/appkit";
+import { appkit } from "@dbx-tools/appkit";
 
-await createApp.createApp({
+await appkit.createApp({
   plugins: [server(), lakebase()],
 });
 ```
@@ -76,7 +76,7 @@ Databricks Asset Bundle validation, and deployed Apps.
 
 Boot-time resolution runs as the service principal before any plugin exists, so
 it sits outside AppKit's interceptor chain. It carries its own timeout, and
-`createApp.autoConfigure()` accepts an `AbortSignal` when a caller wants to
+`appkit.autoConfigure()` accepts an `AbortSignal` when a caller wants to
 cancel it earlier.
 
 Use the lower-level functions when you need to inspect or customize the result:
@@ -110,7 +110,7 @@ reason.
 
 ## Configuration
 
-`createApp.createApp()` accepts everything AppKit's `createApp` does, plus:
+`appkit.createApp()` accepts everything AppKit's `createApp` does, plus:
 
 | Option          | Type                            | Default       | Description                                                                                                                                                                                                                                                                                                                 |
 | --------------- | ------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -324,11 +324,10 @@ is shared. `@dbx-tools/appkit-mastra` exposes this as its `genieIdentity` option
 
 | Module             | Responsibility                                                                                                                                  |
 | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `createApp`        | `createApp()` wrapper and `autoConfigure()`.                                                                                                    |
+| `appkit`           | `createApp()` / `autoConfigure()`, plus execution context lookup and initialization.                                                            |
 | `lakebaseResolver` | Lakebase connection discovery, default picking, optional auto-create, and env application (`applyLakebaseEnv()` for the full set a pool needs). |
 | `pgaddress`        | Permissive Lakebase/Postgres address parser.                                                                                                    |
 | `config`           | Local/env/bundle/app-yaml config lookup.                                                                                                        |
-| `appkit`           | Execution context lookup and initialization.                                                                                                    |
 | `databricks`       | App env detection and SDK context cancellation adapters.                                                                                        |
 | `plugin`           | Typed AppKit plugin data, instance, and required-instance lookup.                                                                               |
 | `provision`        | Cache schema provisioning helpers.                                                                                                              |

package/index.ts

@@ -4,7 +4,6 @@
 
 export * as appkit from "./src/appkit.ts";
 export * as config from "./src/config.ts";
-export * as createApp from "./src/create-app.ts";
 export * as databricks from "./src/databricks.ts";
 export * as identity from "./src/identity.ts";
 export * as interceptor from "./src/interceptor.ts";
@@ -12,9 +11,8 @@ export * as lakebaseResolver from "./src/lakebase-resolver.ts";
 export * as pgaddress from "./src/pgaddress.ts";
 export * as plugin from "./src/plugin.ts";
 export * as provision from "./src/provision.ts";
-export type { ExecutionContextLike, WorkspaceClientLike } from "./src/appkit.ts";
+export type { AutoConfigureMode, CreateAppConfig, ExecutionContextLike, WorkspaceClientLike } from "./src/appkit.ts";
 export type { BundleValidateJson, ConfigFile, ConfigSource, ConfigMapValue, ResolveConfigValueOptions } from "./src/config.ts";
-export type { AutoConfigureMode, CreateAppConfig } from "./src/create-app.ts";
 export { MAX_TCP_PORT } from "./src/databricks.ts";
 export type { ContextLike } from "./src/databricks.ts";
 export { ACCESS_TOKEN_HEADER, USER_ID_HEADER, USER_EMAIL_HEADER, IDENTITY_MODES, DEFAULT_IDENTITY_MODE } from "./src/identity.ts";

package/lib/index.d.ts

@@ -1,6 +1,5 @@
 export * as appkit from "./src/appkit.ts";
 export * as config from "./src/config.ts";
-export * as createApp from "./src/create-app.ts";
 export * as databricks from "./src/databricks.ts";
 export * as identity from "./src/identity.ts";
 export * as interceptor from "./src/interceptor.ts";
@@ -8,9 +7,8 @@ export * as lakebaseResolver from "./src/lakebase-resolver.ts";
 export * as pgaddress from "./src/pgaddress.ts";
 export * as plugin from "./src/plugin.ts";
 export * as provision from "./src/provision.ts";
-export type { ExecutionContextLike, WorkspaceClientLike } from "./src/appkit.ts";
+export type { AutoConfigureMode, CreateAppConfig, ExecutionContextLike, WorkspaceClientLike } from "./src/appkit.ts";
 export type { BundleValidateJson, ConfigFile, ConfigSource, ConfigMapValue, ResolveConfigValueOptions } from "./src/config.ts";
-export type { AutoConfigureMode, CreateAppConfig } from "./src/create-app.ts";
 export { MAX_TCP_PORT } from "./src/databricks.ts";
 export type { ContextLike } from "./src/databricks.ts";
 export { ACCESS_TOKEN_HEADER, USER_ID_HEADER, USER_EMAIL_HEADER, IDENTITY_MODES, DEFAULT_IDENTITY_MODE } from "./src/identity.ts";

package/lib/index.js

@@ -3,7 +3,6 @@
 // Hand edits are overwritten on the next watch; this file is read-only.
 export * as appkit from "./src/appkit.js";
 export * as config from "./src/config.js";
-export * as createApp from "./src/create-app.js";
 export * as databricks from "./src/databricks.js";
 export * as identity from "./src/identity.js";
 export * as interceptor from "./src/interceptor.js";
@@ -15,4 +14,4 @@ export { MAX_TCP_PORT } from "./src/databricks.js";
 export { ACCESS_TOKEN_HEADER, USER_ID_HEADER, USER_EMAIL_HEADER, IDENTITY_MODES, DEFAULT_IDENTITY_MODE } from "./src/identity.js";
 export { LifecycleBridgePlugin, lifecycleBridge } from "./src/interceptor.js";
 export { SSL_MODES } from "./src/pgaddress.js";
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssTUFBTSxNQUFNLGlCQUFpQixDQUFDO0FBQzFDLE9BQU8sS0FBSyxNQUFNLE1BQU0saUJBQWlCLENBQUM7QUFDMUMsT0FBTyxLQUFLLFNBQVMsTUFBTSxxQkFBcUIsQ0FBQztBQUNqRCxPQUFPLEtBQUssVUFBVSxNQUFNLHFCQUFxQixDQUFDO0FBQ2xELE9BQU8sS0FBSyxRQUFRLE1BQU0sbUJBQW1CLENBQUM7QUFDOUMsT0FBTyxLQUFLLFdBQVcsTUFBTSxzQkFBc0IsQ0FBQztBQUNwRCxPQUFPLEtBQUssZ0JBQWdCLE1BQU0sNEJBQTRCLENBQUM7QUFDL0QsT0FBTyxLQUFLLFNBQVMsTUFBTSxvQkFBb0IsQ0FBQztBQUNoRCxPQUFPLEtBQUssTUFBTSxNQUFNLGlCQUFpQixDQUFDO0FBQzFDLE9BQU8sS0FBSyxTQUFTLE1BQU0sb0JBQW9CLENBQUM7QUFJaEQsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLHFCQUFxQixDQUFDO0FBRW5ELE9BQU8sRUFBRSxtQkFBbUIsRUFBRSxjQUFjLEVBQUUsaUJBQWlCLEVBQUUsY0FBYyxFQUFFLHFCQUFxQixFQUFFLE1BQU0sbUJBQW1CLENBQUM7QUFFbEksT0FBTyxFQUFFLHFCQUFxQixFQUFFLGVBQWUsRUFBRSxNQUFNLHNCQUFzQixDQUFDO0FBRzlFLE9BQU8sRUFBRSxTQUFTLEVBQUUsTUFBTSxvQkFBb0IsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIEdFTkVSQVRFRCBieSBwcm9qZW4gd2F0Y2ggLSBETyBOT1QgRURJVC5cbi8vIFJlZ2VuZXJhdGVkIGZyb20gdGhlIGV4cG9ydGluZyBtb2R1bGVzIGluIC4vc3JjLlxuLy8gSGFuZCBlZGl0cyBhcmUgb3ZlcndyaXR0ZW4gb24gdGhlIG5leHQgd2F0Y2g7IHRoaXMgZmlsZSBpcyByZWFkLW9ubHkuXG5cbmV4cG9ydCAqIGFzIGFwcGtpdCBmcm9tIFwiLi9zcmMvYXBwa2l0LnRzXCI7XG5leHBvcnQgKiBhcyBjb25maWcgZnJvbSBcIi4vc3JjL2NvbmZpZy50c1wiO1xuZXhwb3J0ICogYXMgY3JlYXRlQXBwIGZyb20gXCIuL3NyYy9jcmVhdGUtYXBwLnRzXCI7XG5leHBvcnQgKiBhcyBkYXRhYnJpY2tzIGZyb20gXCIuL3NyYy9kYXRhYnJpY2tzLnRzXCI7XG5leHBvcnQgKiBhcyBpZGVudGl0eSBmcm9tIFwiLi9zcmMvaWRlbnRpdHkudHNcIjtcbmV4cG9ydCAqIGFzIGludGVyY2VwdG9yIGZyb20gXCIuL3NyYy9pbnRlcmNlcHRvci50c1wiO1xuZXhwb3J0ICogYXMgbGFrZWJhc2VSZXNvbHZlciBmcm9tIFwiLi9zcmMvbGFrZWJhc2UtcmVzb2x2ZXIudHNcIjtcbmV4cG9ydCAqIGFzIHBnYWRkcmVzcyBmcm9tIFwiLi9zcmMvcGdhZGRyZXNzLnRzXCI7XG5leHBvcnQgKiBhcyBwbHVnaW4gZnJvbSBcIi4vc3JjL3BsdWdpbi50c1wiO1xuZXhwb3J0ICogYXMgcHJvdmlzaW9uIGZyb20gXCIuL3NyYy9wcm92aXNpb24udHNcIjtcbmV4cG9ydCB0eXBlIHsgRXhlY3V0aW9uQ29udGV4dExpa2UsIFdvcmtzcGFjZUNsaWVudExpa2UgfSBmcm9tIFwiLi9zcmMvYXBwa2l0LnRzXCI7XG5leHBvcnQgdHlwZSB7IEJ1bmRsZVZhbGlkYXRlSnNvbiwgQ29uZmlnRmlsZSwgQ29uZmlnU291cmNlLCBDb25maWdNYXBWYWx1ZSwgUmVzb2x2ZUNvbmZpZ1ZhbHVlT3B0aW9ucyB9IGZyb20gXCIuL3NyYy9jb25maWcudHNcIjtcbmV4cG9ydCB0eXBlIHsgQXV0b0NvbmZpZ3VyZU1vZGUsIENyZWF0ZUFwcENvbmZpZyB9IGZyb20gXCIuL3NyYy9jcmVhdGUtYXBwLnRzXCI7XG5leHBvcnQgeyBNQVhfVENQX1BPUlQgfSBmcm9tIFwiLi9zcmMvZGF0YWJyaWNrcy50c1wiO1xuZXhwb3J0IHR5cGUgeyBDb250ZXh0TGlrZSB9IGZyb20gXCIuL3NyYy9kYXRhYnJpY2tzLnRzXCI7XG5leHBvcnQgeyBBQ0NFU1NfVE9LRU5fSEVBREVSLCBVU0VSX0lEX0hFQURFUiwgVVNFUl9FTUFJTF9IRUFERVIsIElERU5USVRZX01PREVTLCBERUZBVUxUX0lERU5USVRZX01PREUgfSBmcm9tIFwiLi9zcmMvaWRlbnRpdHkudHNcIjtcbmV4cG9ydCB0eXBlIHsgSWRlbnRpdHlNb2RlLCBIZWFkZXJCZWFyaW5nIH0gZnJvbSBcIi4vc3JjL2lkZW50aXR5LnRzXCI7XG5leHBvcnQgeyBMaWZlY3ljbGVCcmlkZ2VQbHVnaW4sIGxpZmVjeWNsZUJyaWRnZSB9IGZyb20gXCIuL3NyYy9pbnRlcmNlcHRvci50c1wiO1xuZXhwb3J0IHR5cGUgeyBMaWZlY3ljbGVFdmVudCwgTGlmZWN5Y2xlSGFuZGxlciwgUmVzb2x2ZWRBcHBFbnYsIEJpbmRhYmxlUHJvY2VzcywgSW50ZXJjZXB0b3JDb250ZXh0LCBJbnRlcmNlcHRvciwgSW50ZXJjZXB0b3JSdW50aW1lIH0gZnJvbSBcIi4vc3JjL2ludGVyY2VwdG9yLnRzXCI7XG5leHBvcnQgdHlwZSB7IExha2ViYXNlUmVzb2x2ZXJJbnB1dHMsIExha2ViYXNlQ29ubmVjdGlvbiB9IGZyb20gXCIuL3NyYy9sYWtlYmFzZS1yZXNvbHZlci50c1wiO1xuZXhwb3J0IHsgU1NMX01PREVTIH0gZnJvbSBcIi4vc3JjL3BnYWRkcmVzcy50c1wiO1xuZXhwb3J0IHR5cGUgeyBTc2xNb2RlLCBMYWtlYmFzZUNvbm5lY3Rpb25JbnB1dHMsIFBhcnNlZEFkZHJlc3MgfSBmcm9tIFwiLi9zcmMvcGdhZGRyZXNzLnRzXCI7XG5leHBvcnQgdHlwZSB7IFBsdWdpbkNvbnRleHRMaWtlIH0gZnJvbSBcIi4vc3JjL3BsdWdpbi50c1wiO1xuIl19
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssTUFBTSxNQUFNLGlCQUFpQixDQUFDO0FBQzFDLE9BQU8sS0FBSyxNQUFNLE1BQU0saUJBQWlCLENBQUM7QUFDMUMsT0FBTyxLQUFLLFVBQVUsTUFBTSxxQkFBcUIsQ0FBQztBQUNsRCxPQUFPLEtBQUssUUFBUSxNQUFNLG1CQUFtQixDQUFDO0FBQzlDLE9BQU8sS0FBSyxXQUFXLE1BQU0sc0JBQXNCLENBQUM7QUFDcEQsT0FBTyxLQUFLLGdCQUFnQixNQUFNLDRCQUE0QixDQUFDO0FBQy9ELE9BQU8sS0FBSyxTQUFTLE1BQU0sb0JBQW9CLENBQUM7QUFDaEQsT0FBTyxLQUFLLE1BQU0sTUFBTSxpQkFBaUIsQ0FBQztBQUMxQyxPQUFPLEtBQUssU0FBUyxNQUFNLG9CQUFvQixDQUFDO0FBR2hELE9BQU8sRUFBRSxZQUFZLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQUVuRCxPQUFPLEVBQUUsbUJBQW1CLEVBQUUsY0FBYyxFQUFFLGlCQUFpQixFQUFFLGNBQWMsRUFBRSxxQkFBcUIsRUFBRSxNQUFNLG1CQUFtQixDQUFDO0FBRWxJLE9BQU8sRUFBRSxxQkFBcUIsRUFBRSxlQUFlLEVBQUUsTUFBTSxzQkFBc0IsQ0FBQztBQUc5RSxPQUFPLEVBQUUsU0FBUyxFQUFFLE1BQU0sb0JBQW9CLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBHRU5FUkFURUQgYnkgcHJvamVuIHdhdGNoIC0gRE8gTk9UIEVESVQuXG4vLyBSZWdlbmVyYXRlZCBmcm9tIHRoZSBleHBvcnRpbmcgbW9kdWxlcyBpbiAuL3NyYy5cbi8vIEhhbmQgZWRpdHMgYXJlIG92ZXJ3cml0dGVuIG9uIHRoZSBuZXh0IHdhdGNoOyB0aGlzIGZpbGUgaXMgcmVhZC1vbmx5LlxuXG5leHBvcnQgKiBhcyBhcHBraXQgZnJvbSBcIi4vc3JjL2FwcGtpdC50c1wiO1xuZXhwb3J0ICogYXMgY29uZmlnIGZyb20gXCIuL3NyYy9jb25maWcudHNcIjtcbmV4cG9ydCAqIGFzIGRhdGFicmlja3MgZnJvbSBcIi4vc3JjL2RhdGFicmlja3MudHNcIjtcbmV4cG9ydCAqIGFzIGlkZW50aXR5IGZyb20gXCIuL3NyYy9pZGVudGl0eS50c1wiO1xuZXhwb3J0ICogYXMgaW50ZXJjZXB0b3IgZnJvbSBcIi4vc3JjL2ludGVyY2VwdG9yLnRzXCI7XG5leHBvcnQgKiBhcyBsYWtlYmFzZVJlc29sdmVyIGZyb20gXCIuL3NyYy9sYWtlYmFzZS1yZXNvbHZlci50c1wiO1xuZXhwb3J0ICogYXMgcGdhZGRyZXNzIGZyb20gXCIuL3NyYy9wZ2FkZHJlc3MudHNcIjtcbmV4cG9ydCAqIGFzIHBsdWdpbiBmcm9tIFwiLi9zcmMvcGx1Z2luLnRzXCI7XG5leHBvcnQgKiBhcyBwcm92aXNpb24gZnJvbSBcIi4vc3JjL3Byb3Zpc2lvbi50c1wiO1xuZXhwb3J0IHR5cGUgeyBBdXRvQ29uZmlndXJlTW9kZSwgQ3JlYXRlQXBwQ29uZmlnLCBFeGVjdXRpb25Db250ZXh0TGlrZSwgV29ya3NwYWNlQ2xpZW50TGlrZSB9IGZyb20gXCIuL3NyYy9hcHBraXQudHNcIjtcbmV4cG9ydCB0eXBlIHsgQnVuZGxlVmFsaWRhdGVKc29uLCBDb25maWdGaWxlLCBDb25maWdTb3VyY2UsIENvbmZpZ01hcFZhbHVlLCBSZXNvbHZlQ29uZmlnVmFsdWVPcHRpb25zIH0gZnJvbSBcIi4vc3JjL2NvbmZpZy50c1wiO1xuZXhwb3J0IHsgTUFYX1RDUF9QT1JUIH0gZnJvbSBcIi4vc3JjL2RhdGFicmlja3MudHNcIjtcbmV4cG9ydCB0eXBlIHsgQ29udGV4dExpa2UgfSBmcm9tIFwiLi9zcmMvZGF0YWJyaWNrcy50c1wiO1xuZXhwb3J0IHsgQUNDRVNTX1RPS0VOX0hFQURFUiwgVVNFUl9JRF9IRUFERVIsIFVTRVJfRU1BSUxfSEVBREVSLCBJREVOVElUWV9NT0RFUywgREVGQVVMVF9JREVOVElUWV9NT0RFIH0gZnJvbSBcIi4vc3JjL2lkZW50aXR5LnRzXCI7XG5leHBvcnQgdHlwZSB7IElkZW50aXR5TW9kZSwgSGVhZGVyQmVhcmluZyB9IGZyb20gXCIuL3NyYy9pZGVudGl0eS50c1wiO1xuZXhwb3J0IHsgTGlmZWN5Y2xlQnJpZGdlUGx1Z2luLCBsaWZlY3ljbGVCcmlkZ2UgfSBmcm9tIFwiLi9zcmMvaW50ZXJjZXB0b3IudHNcIjtcbmV4cG9ydCB0eXBlIHsgTGlmZWN5Y2xlRXZlbnQsIExpZmVjeWNsZUhhbmRsZXIsIFJlc29sdmVkQXBwRW52LCBCaW5kYWJsZVByb2Nlc3MsIEludGVyY2VwdG9yQ29udGV4dCwgSW50ZXJjZXB0b3IsIEludGVyY2VwdG9yUnVudGltZSB9IGZyb20gXCIuL3NyYy9pbnRlcmNlcHRvci50c1wiO1xuZXhwb3J0IHR5cGUgeyBMYWtlYmFzZVJlc29sdmVySW5wdXRzLCBMYWtlYmFzZUNvbm5lY3Rpb24gfSBmcm9tIFwiLi9zcmMvbGFrZWJhc2UtcmVzb2x2ZXIudHNcIjtcbmV4cG9ydCB7IFNTTF9NT0RFUyB9IGZyb20gXCIuL3NyYy9wZ2FkZHJlc3MudHNcIjtcbmV4cG9ydCB0eXBlIHsgU3NsTW9kZSwgTGFrZWJhc2VDb25uZWN0aW9uSW5wdXRzLCBQYXJzZWRBZGRyZXNzIH0gZnJvbSBcIi4vc3JjL3BnYWRkcmVzcy50c1wiO1xuZXhwb3J0IHR5cGUgeyBQbHVnaW5Db250ZXh0TGlrZSB9IGZyb20gXCIuL3NyYy9wbHVnaW4udHNcIjtcbiJdfQ==

package/lib/src/_cache-storage.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Soft-fail Lakebase cache storage for AppKit's persistent cache.
+ *
+ * AppKit's `PersistentStorage.initialize()` runs DDL migrations and throws on
+ * any step failure. With `cache.strictPersistence: true` that throw makes
+ * `CacheManager` silently disable the cache. This wraps the same storage,
+ * still runs its migrations, but logs a failed step instead of throwing so a
+ * usable table keeps serving.
+ *
+ * `PersistentStorage` is not on AppKit's public export map. The deep load is
+ * lazy and best-effort: if the installed AppKit layout changes, this returns
+ * `undefined` and `createApp` leaves AppKit on its default cache path.
+ *
+ * @module
+ */
+import { type CacheConfig } from "@databricks/appkit";
+type CacheStorage = NonNullable<CacheConfig["storage"]>;
+/**
+ * Build a soft-fail Lakebase cache storage when a pool can be created and
+ * AppKit's PersistentStorage can be loaded. Returns `undefined` otherwise so
+ * AppKit can fall through to its normal cache path.
+ */
+export declare function createSoftPersistentStorage(cache: CacheConfig | undefined): Promise<CacheStorage | undefined>;
+export {};

package/lib/src/_cache-storage.js

@@ -0,0 +1,106 @@
+/**
+ * Soft-fail Lakebase cache storage for AppKit's persistent cache.
+ *
+ * AppKit's `PersistentStorage.initialize()` runs DDL migrations and throws on
+ * any step failure. With `cache.strictPersistence: true` that throw makes
+ * `CacheManager` silently disable the cache. This wraps the same storage,
+ * still runs its migrations, but logs a failed step instead of throwing so a
+ * usable table keeps serving.
+ *
+ * `PersistentStorage` is not on AppKit's public export map. The deep load is
+ * lazy and best-effort: if the installed AppKit layout changes, this returns
+ * `undefined` and `createApp` leaves AppKit on its default cache path.
+ *
+ * @module
+ */
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { createLakebasePool, getWorkspaceClient } from "@databricks/appkit";
+import { error, log } from "@dbx-tools/shared-core";
+const logger = log.logger("cache-storage");
+/** Whether `LOG_LEVEL` is currently at or below debug. */
+function isDebugEnabled() {
+    return log.isLevelEnabled("debug");
+}
+let persistentStorageCtor = null;
+/**
+ * Lazily resolve AppKit's internal `PersistentStorage` constructor. `null`
+ * means the lookup already failed; `undefined` means not attempted yet.
+ */
+function loadPersistentStorage() {
+    if (persistentStorageCtor !== null) {
+        return persistentStorageCtor;
+    }
+    try {
+        const require = createRequire(import.meta.url);
+        const modulePath = join(dirname(require.resolve("@databricks/appkit")), "cache/storage/persistent.js");
+        const loaded = require(modulePath).PersistentStorage;
+        if (typeof loaded !== "function") {
+            logger.debug("soft persistent cache skipped (PersistentStorage missing)");
+            persistentStorageCtor = undefined;
+            return undefined;
+        }
+        persistentStorageCtor = loaded;
+        return loaded;
+    }
+    catch (err) {
+        logger.debug("soft persistent cache skipped (PersistentStorage unavailable)", {
+            error: error.errorMessage(err),
+        });
+        persistentStorageCtor = undefined;
+        return undefined;
+    }
+}
+/** Soften `initialize()` so a migration failure is logged, not thrown. */
+function softenInitialize(storage) {
+    const originalInitialize = storage.initialize.bind(storage);
+    storage.initialize = async () => {
+        try {
+            await originalInitialize();
+        }
+        catch (err) {
+            if (isDebugEnabled()) {
+                logger.error("persistent cache migration failed", err);
+            }
+            else {
+                logger.warn("persistent cache migration failed", {
+                    error: error.errorMessage(err),
+                });
+            }
+            storage.initialized = true;
+        }
+    };
+}
+/**
+ * Build a soft-fail Lakebase cache storage when a pool can be created and
+ * AppKit's PersistentStorage can be loaded. Returns `undefined` otherwise so
+ * AppKit can fall through to its normal cache path.
+ */
+export async function createSoftPersistentStorage(cache) {
+    const PersistentStorage = loadPersistentStorage();
+    if (!PersistentStorage) {
+        return undefined;
+    }
+    let pool;
+    try {
+        pool = createLakebasePool({ workspaceClient: getWorkspaceClient({}) });
+        const storage = new PersistentStorage(cache ?? {}, pool);
+        softenInitialize(storage);
+        if (!(await storage.healthCheck())) {
+            await storage.close().catch(() => { });
+            return undefined;
+        }
+        await storage.initialize();
+        return storage;
+    }
+    catch (err) {
+        logger.debug("soft persistent cache unavailable", {
+            error: error.errorMessage(err),
+        });
+        if (pool) {
+            await pool.end().catch(() => { });
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiX2NhY2hlLXN0b3JhZ2UuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvX2NhY2hlLXN0b3JhZ2UudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7Ozs7Ozs7O0dBY0c7QUFFSCxPQUFPLEVBQUUsYUFBYSxFQUFFLE1BQU0sYUFBYSxDQUFDO0FBQzVDLE9BQU8sRUFBRSxPQUFPLEVBQUUsSUFBSSxFQUFFLE1BQU0sV0FBVyxDQUFDO0FBQzFDLE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxrQkFBa0IsRUFBb0IsTUFBTSxvQkFBb0IsQ0FBQztBQUM5RixPQUFPLEVBQUUsS0FBSyxFQUFFLEdBQUcsRUFBRSxNQUFNLHdCQUF3QixDQUFDO0FBRXBELE1BQU0sTUFBTSxHQUFHLEdBQUcsQ0FBQyxNQUFNLENBQUMsZUFBZSxDQUFDLENBQUM7QUFFM0MsMERBQTBEO0FBQzFELFNBQVMsY0FBYztJQUNyQixPQUFPLEdBQUcsQ0FBQyxjQUFjLENBQUMsT0FBTyxDQUFDLENBQUM7QUFDckMsQ0FBQztBQWdCRCxJQUFJLHFCQUFxQixHQUFvRCxJQUFJLENBQUM7QUFFbEY7OztHQUdHO0FBQ0gsU0FBUyxxQkFBcUI7SUFDNUIsSUFBSSxxQkFBcUIsS0FBSyxJQUFJLEVBQUUsQ0FBQztRQUNuQyxPQUFPLHFCQUFxQixDQUFDO0lBQy9CLENBQUM7SUFDRCxJQUFJLENBQUM7UUFDSCxNQUFNLE9BQU8sR0FBRyxhQUFhLENBQUMsTUFBTSxDQUFDLElBQUksQ0FBQyxHQUFHLENBQUMsQ0FBQztRQUMvQyxNQUFNLFVBQVUsR0FBRyxJQUFJLENBQ3JCLE9BQU8sQ0FBQyxPQUFPLENBQUMsT0FBTyxDQUFDLG9CQUFvQixDQUFDLENBQUMsRUFDOUMsNkJBQTZCLENBQzlCLENBQUM7UUFDRixNQUFNLE1BQU0sR0FBRyxPQUFPLENBQUMsVUFBVSxDQUFDLENBQUMsaUJBQ08sQ0FBQztRQUMzQyxJQUFJLE9BQU8sTUFBTSxLQUFLLFVBQVUsRUFBRSxD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IFNvZnQtZmFpbCBMYWtlYmFzZSBjYWNoZSBzdG9yYWdlIGZvciBBcHBLaXQncyBwZXJzaXN0ZW50IGNhY2hlLlxuICpcbiAqIEFwcEtpdCdzIGBQZXJzaXN0ZW50U3RvcmFnZS5pbml0aWFsaXplKClgIHJ1bnMgRERMIG1pZ3JhdGlvbnMgYW5kIHRocm93cyBvblxuICogYW55IHN0ZXAgZmFpbHVyZS4gV2l0aCBgY2FjaGUuc3RyaWN0UGVyc2lzdGVuY2U6IHRydWVgIHRoYXQgdGhyb3cgbWFrZXNcbiAqIGBDYWNoZU1hbmFnZXJgIHNpbGVudGx5IGRpc2FibGUgdGhlIGNhY2hlLiBUaGlzIHdyYXBzIHRoZSBzYW1lIHN0b3JhZ2UsXG4gKiBzdGlsbCBydW5zIGl0cyBtaWdyYXRpb25zLCBidXQgbG9ncyBhIGZhaWxlZCBzdGVwIGluc3RlYWQgb2YgdGhyb3dpbmcgc28gYVxuICogdXNhYmxlIHRhYmxlIGtlZXBzIHNlcnZpbmcuXG4gKlxuICogYFBlcnNpc3RlbnRTdG9yYWdlYCBpcyBub3Qgb24gQXBwS2l0J3MgcHVibGljIGV4cG9ydCBtYXAuIFRoZSBkZWVwIGxvYWQgaXNcbiAqIGxhenkgYW5kIGJlc3QtZWZmb3J0OiBpZiB0aGUgaW5zdGFsbGVkIEFwcEtpdCBsYXlvdXQgY2hhbmdlcywgdGhpcyByZXR1cm5zXG4gKiBgdW5kZWZpbmVkYCBhbmQgYGNyZWF0ZUFwcGAgbGVhdmVzIEFwcEtpdCBvbiBpdHMgZGVmYXVsdCBjYWNoZSBwYXRoLlxuICpcbiAqIEBtb2R1bGVcbiAqL1xuXG5pbXBvcnQgeyBjcmVhdGVSZXF1aXJlIH0gZnJvbSBcIm5vZGU6bW9kdWxlXCI7XG5pbXBvcnQgeyBkaXJuYW1lLCBqb2luIH0gZnJvbSBcIm5vZGU6cGF0aFwiO1xuaW1wb3J0IHsgY3JlYXRlTGFrZWJhc2VQb29sLCBnZXRXb3Jrc3BhY2VDbGllbnQsIHR5cGUgQ2FjaGVDb25maWcgfSBmcm9tIFwiQGRhdGFicmlja3MvYXBwa2l0XCI7XG5pbXBvcnQgeyBlcnJvciwgbG9nIH0gZnJvbSBcIkBkYngtdG9vbHMvc2hhcmVkLWNvcmVcIjtcblxuY29uc3QgbG9nZ2VyID0gbG9nLmxvZ2dlcihcImNhY2hlLXN0b3JhZ2VcIik7XG5cbi8qKiBXaGV0aGVyIGBMT0dfTEVWRUxgIGlzIGN1cnJlbnRseSBhdCBvciBiZWxvdyBkZWJ1Zy4gKi9cbmZ1bmN0aW9uIGlzRGVidWdFbmFibGVkKCk6IGJvb2xlYW4ge1xuICByZXR1cm4gbG9nLmlzTGV2ZWxFbmFibGVkKFwiZGVidWdcIik7XG59XG5cbnR5cGUgTGFrZWJhc2VQb29sID0gUmV0dXJuVHlwZTx0eXBlb2YgY3JlYXRlTGFrZWJhc2VQb29sPjtcbnR5cGUgQ2FjaGVTdG9yYWdlID0gTm9uTnVsbGFibGU8Q2FjaGVDb25maWdbXCJzdG9yYWdlXCJdPjtcblxuLyoqIEFwcEtpdCdzIGludGVybmFsIHBlcnNpc3RlbnQgc3RvcmFnZSBzdXJmYWNlLiAqL1xudHlwZSBQZXJzaXN0ZW50U3RvcmFnZUJhc2UgPSBDYWNoZVN0b3JhZ2UgJiB7XG4gIGluaXRpYWxpemUoKTogUHJvbWlzZTx2b2lkPjtcbiAgaW5pdGlhbGl6ZWQ6IGJvb2xlYW47XG59O1xuXG50eXBlIFBlcnNpc3RlbnRTdG9yYWdlQ29uc3RydWN0b3IgPSBuZXcgKFxuICBjb25maWc6IENhY2hlQ29uZmlnLFxuICBwb29sOiBMYWtlYmFzZVBvb2wsXG4pID0+IFBlcnNpc3RlbnRTdG9yYWdlQmFzZTtcblxubGV0IHBlcnNpc3RlbnRTdG9yYWdlQ3RvcjogUGVyc2lzdGVudFN0b3JhZ2VDb25zdHJ1Y3RvciB8IHVuZGVmaW5lZCB8IG51bGwgPSBudWxsO1xuXG4vKipcbiAqIExhemlseSByZXNvbHZlIEFwcEtpdCdzIGludGVybmFsIGBQZXJzaXN0ZW50U3RvcmFnZWAgY29uc3RydWN0b3IuIGBudWxsYFxuICogbWVhbnMgdGhlIGxvb2t1cCBhbHJlYWR5IGZhaWxlZDsgYHVuZGVmaW5lZGAgbWVhbnMgbm90IGF0dGVtcHRlZCB5ZXQuXG4gKi9cbmZ1bmN0aW9uIGxvYWRQZXJzaXN0ZW50U3RvcmFnZSgpOiBQZXJzaXN0ZW50U3RvcmFnZUNvbnN0cnVjdG9yIHwgdW5kZWZpbmVkIHtcbiAgaWYgKHBlcnNpc3RlbnRTdG9yYWdlQ3RvciAhPT0gbnVsbCkge1xuICAgIHJldHVybiBwZXJzaXN0ZW50U3RvcmFnZUN0b3I7XG4gIH1cbiAgdHJ5IHtcbiAgICBjb25zdCByZXF1aXJlID0gY3JlYXRlUmVxdWlyZShpbXBvcnQubWV0YS51cmwpO1xuICAgIGNvbnN0IG1vZHVsZVBhdGggPSBqb2luKFxuICAgICAgZGlybmFtZShyZXF1aXJlLnJlc29sdmUoXCJAZGF0YWJyaWNrcy9hcHBraXRcIikpLFxuICAgICAgXCJjYWNoZS9zdG9yYWdlL3BlcnNpc3RlbnQuanNcIixcbiAgICApO1xuICAgIGNvbnN0IGxvYWRlZCA9IHJlcXVpcmUobW9kdWxlUGF0aCkuUGVyc2lzdGVudFN0b3JhZ2UgYXNcbiAgICAgIFBlcnNpc3RlbnRTdG9yYWdlQ29uc3RydWN0b3IgfCB1bmRlZmluZWQ7XG4gICAgaWYgKHR5cGVvZiBsb2FkZWQgIT09IFwiZnVuY3Rpb25cIikge1xuICAgICAgbG9nZ2VyLmRlYnVnKFwic29mdCBwZXJzaXN0ZW50IGNhY2hlIHNraXBwZWQgKFBlcnNpc3RlbnRTdG9yYWdlIG1pc3NpbmcpXCIpO1xuICAgICAgcGVyc2lzdGVudFN0b3JhZ2VDdG9yID0gdW5kZWZpbmVkO1xuICAgICAgcmV0dXJuIHVuZGVmaW5lZDtcbiAgICB9XG4gICAgcGVyc2lzdGVudFN0b3JhZ2VDdG9yID0gbG9hZGVkO1xuICAgIHJldHVybiBsb2FkZWQ7XG4gIH0gY2F0Y2ggKGVycikge1xuICAgIGxvZ2dlci5kZWJ1ZyhcInNvZnQgcGVyc2lzdGVudCBjYWNoZSBza2lwcGVkIChQZXJzaXN0ZW50U3RvcmFnZSB1bmF2YWlsYWJsZSlcIiwge1xuICAgICAgZXJyb3I6IGVycm9yLmVycm9yTWVzc2FnZShlcnIpLFxuICAgIH0pO1xuICAgIHBlcnNpc3RlbnRTdG9yYWdlQ3RvciA9IHVuZGVmaW5lZDtcbiAgICByZXR1cm4gdW5kZWZpbmVkO1xuICB9XG59XG5cbi8qKiBTb2Z0ZW4gYGluaXRpYWxpemUoKWAgc28gYSBtaWdyYXRpb24gZmFpbHVyZSBpcyBsb2dnZWQsIG5vdCB0aHJvd24uICovXG5mdW5jdGlvbiBzb2Z0ZW5Jbml0aWFsaXplKHN0b3JhZ2U6IFBlcnNpc3RlbnRTdG9yYWdlQmFzZSk6IHZvaWQge1xuICBjb25zdCBvcmlnaW5hbEluaXRpYWxpemUgPSBzdG9yYWdlLmluaXRpYWxpemUuYmluZChzdG9yYWdlKTtcbiAgc3RvcmFnZS5pbml0aWFsaXplID0gYXN5bmMgKCkgPT4ge1xuICAgIHRyeSB7XG4gICAgICBhd2FpdCBvcmlnaW5hbEluaXRpYWxpemUoKTtcbiAgICB9IGNhdGNoIChlcnIpIHtcbiAgICAgIGlmIChpc0RlYnVnRW5hYmxlZCgpKSB7XG4gICAgICAgIGxvZ2dlci5lcnJvcihcInBlcnNpc3RlbnQgY2FjaGUgbWlncmF0aW9uIGZhaWxlZFwiLCBlcnIpO1xuICAgICAgfSBlbHNlIHtcbiAgICAgICAgbG9nZ2VyLndhcm4oXCJwZXJzaXN0ZW50IGNhY2hlIG1pZ3JhdGlvbiBmYWlsZWRcIiwge1xuICAgICAgICAgIGVycm9yOiBlcnJvci5lcnJvck1lc3NhZ2UoZXJyKSxcbiAgICAgICAgfSk7XG4gICAgICB9XG4gICAgICBzdG9yYWdlLmluaXRpYWxpemVkID0gdHJ1ZTtcbiAgICB9XG4gIH07XG59XG5cbi8qKlxuICogQnVpbGQgYSBzb2Z0LWZhaWwgTGFrZWJhc2UgY2FjaGUgc3RvcmFnZSB3aGVuIGEgcG9vbCBjYW4gYmUgY3JlYXRlZCBhbmRcbiAqIEFwcEtpdCdzIFBlcnNpc3RlbnRTdG9yYWdlIGNhbiBiZSBsb2FkZWQuIFJldHVybnMgYHVuZGVmaW5lZGAgb3RoZXJ3aXNlIHNvXG4gKiBBcHBLaXQgY2FuIGZhbGwgdGhyb3VnaCB0byBpdHMgbm9ybWFsIGNhY2hlIHBhdGguXG4gKi9cbmV4cG9ydCBhc3luYyBmdW5jdGlvbiBjcmVhdGVTb2Z0UGVyc2lzdGVudFN0b3JhZ2UoXG4gIGNhY2hlOiBDYWNoZUNvbmZpZyB8IHVuZGVmaW5lZCxcbik6IFByb21pc2U8Q2FjaGVTdG9yYWdlIHwgdW5kZWZpbmVkPiB7XG4gIGNvbnN0IFBlcnNpc3RlbnRTdG9yYWdlID0gbG9hZFBlcnNpc3RlbnRTdG9yYWdlKCk7XG4gIGlmICghUGVyc2lzdGVudFN0b3JhZ2UpIHtcbiAgICByZXR1cm4gdW5kZWZpbmVkO1xuICB9XG5cbiAgbGV0IHBvb2w6IExha2ViYXNlUG9vbCB8IHVuZGVmaW5lZDtcbiAgdHJ5IHtcbiAgICBwb29sID0gY3JlYXRlTGFrZWJhc2VQb29sKHsgd29ya3NwYWNlQ2xpZW50OiBnZXRXb3Jrc3BhY2VDbGllbnQoe30pIH0pO1xuICAgIGNvbnN0IHN0b3JhZ2UgPSBuZXcgUGVyc2lzdGVudFN0b3JhZ2UoY2FjaGUgPz8ge30sIHBvb2wpO1xuICAgIHNvZnRlbkluaXRpYWxpemUoc3RvcmFnZSk7XG4gICAgaWYgKCEoYXdhaXQgc3RvcmFnZS5oZWFsdGhDaGVjaygpKSkge1xuICAgICAgYXdhaXQgc3RvcmFnZS5jbG9zZSgpLmNhdGNoKCgpID0+IHt9KTtcbiAgICAgIHJldHVybiB1bmRlZmluZWQ7XG4gICAgfVxuICAgIGF3YWl0IHN0b3JhZ2UuaW5pdGlhbGl6ZSgpO1xuICAgIHJldHVybiBzdG9yYWdlO1xuICB9IGNhdGNoIChlcnIpIHtcbiAgICBsb2dnZXIuZGVidWcoXCJzb2Z0IHBlcnNpc3RlbnQgY2FjaGUgdW5hdmFpbGFibGVcIiwge1xuICAgICAgZXJyb3I6IGVycm9yLmVycm9yTWVzc2FnZShlcnIpLFxuICAgIH0pO1xuICAgIGlmIChwb29sKSB7XG4gICAgICBhd2FpdCBwb29sLmVuZCgpLmNhdGNoKCgpID0+IHt9KTtcbiAgICB9XG4gICAgcmV0dXJuIHVuZGVmaW5lZDtcbiAgfVxufVxuIl19

package/lib/src/appkit.d.ts

@@ -1,6 +1,22 @@
 /**
- * Generic AppKit runtime glue: the per-request execution context and the types
- * derived from it. Not plugin-specific - that lives in `./plugin`.
+ * AppKit runtime glue: the auto-configuring `createApp` drop-in, plus the
+ * per-request execution context helpers and types derived from it.
+ *
+ * `createApp` runs dbx-tools auto-configuration, then delegates to AppKit's own
+ * `createApp` with the same arguments and the same typed plugin-export map.
+ * Drop it in as a one-for-one replacement:
+ *
+ * ```ts
+ * import { lakebase, server } from "@databricks/appkit";
+ * import { appkit } from "@dbx-tools/appkit";
+ *
+ * await appkit.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.
  *
  * `getExecutionContext()` is AppKit's own accessor for the OBO-scoped workspace
  * client + request metadata; the wrappers here make it safe to call outside a
@@ -10,7 +26,79 @@
  *
  * @module
  */
-import { getExecutionContext } from "@databricks/appkit";
+import { createApp as appkitCreateApp, getExecutionContext } from "@databricks/appkit";
+import type { PluginMap } from "@databricks/appkit/dist/shared/src/plugin";
+import { type Interceptor } from "./interceptor.ts";
+import { type LakebaseConnection } from "./lakebase-resolver.ts";
+type AppKitCreateAppConfig = NonNullable<Parameters<typeof appkitCreateApp>[0]>;
+type AppKitPlugins = NonNullable<AppKitCreateAppConfig["plugins"]>;
+/**
+ * What auto-configuration does before AppKit boots.
+ *
+ * - `"provision"`: resolve the Lakebase connection into `process.env`, then
+ *   grant the AppKit cache schema to the connecting role.
+ * - `"env"`: resolve the Lakebase connection into `process.env` only.
+ *
+ * Omit it to get `"provision"` gated on a `lakebase` plugin being registered;
+ * set it explicitly to run regardless of the plugin list, or pass `false` to
+ * skip auto-configuration entirely.
+ *
+ * Set it EXPLICITLY on an app that has no `lakebase()` plugin but still wants
+ * AppKit's PERSISTENT cache. AppKit picks Lakebase for `CacheManager` only when
+ * `createLakebasePool()` can build a pool, and that reads `LAKEBASE_ENDPOINT` /
+ * `PGHOST` / `PGDATABASE` straight from `process.env` - so without this step the
+ * cache silently falls back to in-memory, and anything it holds (a session
+ * signing key, a one-time code) is lost on restart. `"env"` is the right mode
+ * there: the app SP cannot grant on the cache schema anyway.
+ */
+export type AutoConfigureMode = "env" | "provision";
+/** AppKit's `createApp` config plus the dbx-tools auto-configuration switch. */
+export type CreateAppConfig<T extends AppKitPlugins = AppKitPlugins> = Omit<AppKitCreateAppConfig, "plugins" | "onPluginsReady"> & {
+    plugins?: T;
+    onPluginsReady?: (appkit: PluginMap<T>) => void | Promise<void>;
+    /** Auto-configuration to run before AppKit boots. Defaults to `"provision"`. */
+    autoConfigure?: AutoConfigureMode | false;
+    /**
+     * One or many {@link Interceptor}s handed an {@link InterceptorContext} once
+     * auto-configuration has computed the env. Each receives the resolved env, an
+     * AppKit-lifecycle hook, and `bindProcess` for concurrently-style supervision -
+     * see `./interceptor`. The tunnel is the primary consumer.
+     */
+    interceptor?: Interceptor | Interceptor[];
+};
+/**
+ * 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 { appkit } from "@dbx-tools/appkit";
+ *
+ * // Populate PGHOST / PGDATABASE / LAKEBASE_ENDPOINT without booting AppKit.
+ * await appkit.autoConfigure({ autoConfigure: "env" });
+ */
+export declare function autoConfigure<T extends AppKitPlugins>(config?: CreateAppConfig<T>, signal?: AbortSignal): Promise<LakebaseConnection | undefined>;
+/**
+ * Auto-configuring drop-in for AppKit's `createApp`: same config, same typed
+ * plugin-export map, with {@link autoConfigure} run first.
+ *
+ * When {@link CreateAppConfig.interceptor}s are given, each is invoked with an
+ * {@link InterceptorContext} AFTER auto-configuration computes the env and BEFORE
+ * AppKit boots - so an interceptor can read the resolved connection, register
+ * lifecycle handlers, and `bindProcess` a child. A hidden {@link lifecycleBridge}
+ * plugin is injected so those `onLifecycle` handlers fire on the genuine AppKit
+ * events; it has no exports, so the returned {@link PluginMap} is unchanged.
+ *
+ * @example
+ * import { lakebase, server } from "@databricks/appkit";
+ * import { appkit } from "@dbx-tools/appkit";
+ *
+ * const app = await appkit.createApp({ plugins: [server(), lakebase()] });
+ */
+export declare function createApp<T extends AppKitPlugins>(config?: CreateAppConfig<T>): Promise<PluginMap<T>>;
 /**
  * The AppKit per-request execution context returned by `getExecutionContext()`
  * - the OBO-scoped workspace client plus the surrounding request metadata.
@@ -49,3 +137,4 @@ export declare function tryGetExecutionContext(): ExecutionContextLike | undefin
  * const client = appkit.tryGetExecutionContext()?.client;
  */
 export declare function ensureInitialized(): Promise<void>;
+export {};