@dbx-tools/appkit 0.3.29 → 0.3.30

package/README.md

@@ -6,7 +6,7 @@ Import this package when backend code needs AppKit execution context, typed
 plugin lookup, Databricks SDK cancellation, layered config resolution, or
 Lakebase auto-configuration without taking on a heavier feature package.
 
-Key features:
+**Key features:**
 
 - Auto-configuration before AppKit setup, especially for Lakebase/Postgres env
   values that AppKit plugins read during initialization.
@@ -21,7 +21,7 @@ Key features:
 - Lakebase cache-schema provisioning for deployments where the app identity must
   be granted access before persistent cache initialization.
 
-## Why Not Just AppKit?
+## Why Use This Over Native AppKit
 
 Use native AppKit directly when your app can read its required env vars before
 `createApp()` and does not need extra setup around plugin exports or config
@@ -41,7 +41,8 @@ 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`. It runs
+`createApp.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
 environment variables before plugin setup runs.
 
@@ -64,6 +65,11 @@ explicit options, and local-only discovery is skipped inside a Databricks App
 environment. This makes the same entrypoint usable in local development,
 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
+cancel it earlier.
+
 Use the lower-level functions when you need to inspect or customize the result:
 
 ```ts
@@ -77,16 +83,54 @@ const resolved = await lakebaseResolver.resolveLakebaseConnection({
 lakebaseResolver.applyLakebaseToEnv(resolved);
 ```
 
+## Configuration
+
+`createApp.createApp()` accepts everything AppKit's `createApp` does, plus:
+
+| Option          | Type                            | Default       | Description                                                                                                                                                                                                                                                                                                                 |
+| --------------- | ------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `autoConfigure` | `"provision" \| "env" \| false` | `"provision"` | What to run before AppKit boots. `"provision"` resolves the Lakebase connection into `process.env` and grants the AppKit cache schema; `"env"` resolves the connection only; `false` skips auto-configuration. Omit it to gate the default on a `lakebase` plugin being registered, or set it explicitly to run regardless. |
+
+`lakebaseResolver.resolveLakebaseConnection()` accepts:
+
+| Option       | Type                                 | Default                                  | Description                                                                                                    |
+| ------------ | ------------------------------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `endpoint`   | `string`                             | `LAKEBASE_ENDPOINT`                      | Any address `pgaddress.parseAddress()` understands: resource path, Postgres URI, hostname, or bare project id. |
+| `project`    | `string`                             | discovered                               | Lakebase project id. Resolved from the workspace when unset.                                                   |
+| `branch`     | `string`                             | project default                          | Branch id within the project.                                                                                  |
+| `database`   | `string`                             | `PGDATABASE`, else `databricks_postgres` | Postgres database name.                                                                                        |
+| `host`       | `string`                             | `PGHOST`, else the endpoint's host       | Postgres hostname.                                                                                             |
+| `port`       | `number`                             | `PGPORT`, else `5432`                    | Postgres port.                                                                                                 |
+| `sslMode`    | `"require" \| "disable" \| "prefer"` | `PGSSLMODE`, else `require`              | Postgres TLS mode.                                                                                             |
+| `autoCreate` | `string \| false`                    | slug of the package name                 | Project id to create when the workspace has none. `false` fails instead of creating.                           |
+
+Environment variables read during resolution:
+
+| Variable            | Description                                                                                      |
+| ------------------- | ------------------------------------------------------------------------------------------------ |
+| `LAKEBASE_ENDPOINT` | Endpoint resource path, Postgres URI, hostname, or project id.                                   |
+| `PGHOST`            | Postgres hostname. Skips the endpoint lookup when set with `PGDATABASE` and `LAKEBASE_ENDPOINT`. |
+| `PGDATABASE`        | Postgres database name.                                                                          |
+| `PGPORT`            | Postgres port. A value outside 1-65535 fails with a `ValidationError`.                           |
+| `PGSSLMODE`         | `require`, `disable`, or `prefer`. Any other value fails with a `ValidationError`.               |
+| `PGUSER`            | Connecting role. Filled from the workspace identity when unset.                                  |
+
+Resolved values are written back to `process.env` by
+`lakebaseResolver.applyLakebaseToEnv()`, which never overwrites a variable that
+is already set.
+
 ## Resolve Local And Bundle Config
 
 `config.resolveConfigValue()` checks explicit options, CLI overrides, env vars,
-Databricks Asset Bundle validation output, and `app.yaml` env entries.
+Databricks Asset Bundle validation output, and `app.yaml` env entries, in AppKit's
+precedence order: explicit config, then environment variable, then the app or
+bundle definition.
 
 ```ts
 import { config } from "@dbx-tools/appkit";
 
-const warehouseId = await config.resolveConfigValue("SQL_WAREHOUSE_ID", {
-  cli: { SQL_WAREHOUSE_ID: flags.warehouse },
+const warehouseId = await config.resolveConfigValue("DATABRICKS_WAREHOUSE_ID", {
+  cli: { DATABRICKS_WAREHOUSE_ID: flags.warehouse },
   sources: config.withCliSources(),
 });
 ```
@@ -136,14 +180,15 @@ Databricks SDK calls accept a `Context`. Many app and web APIs use
 ```ts
 import { databricks } from "@dbx-tools/appkit";
 
-const context = databricks.toContext(request.signal);
-await client.apiClient.request({
-  path: "/api/2.0/serving-endpoints",
-  method: "GET",
-  headers: new Headers(),
-  raw: false,
-  context,
-});
+await client.apiClient.request(
+  {
+    path: "/api/2.0/serving-endpoints",
+    method: "GET",
+    headers: new Headers(),
+    raw: false,
+  },
+  databricks.toContext(request.signal),
+);
 ```
 
 `databricks.isAppEnv()` checks the Databricks App environment shape for setup
@@ -166,7 +211,9 @@ const required = plugin.require(this.context, lakebase, "my-plugin").exports();
 ```
 
 Use this in AppKit plugins that depend on sibling plugin exports but should not
-hard-code registered names or casts at every call site.
+hard-code registered names or casts at every call site. A missing required
+plugin throws AppKit's `ConfigurationError`, naming both the caller and the
+plugin to register.
 
 ## Provision Lakebase Cache Schema
 
@@ -176,25 +223,26 @@ been resolved and before AppKit initializes its persistent cache.
 
 ```ts
 import { provision } from "@dbx-tools/appkit";
-import { log } from "@dbx-tools/shared-core";
 
-await provision.provisionCacheSchema(
-  log.logger("appkit-cache"),
-  "app-service-principal@databricks.com",
-);
+await provision.provisionCacheSchema("app-service-principal@databricks.com");
 ```
 
+Pass a second argument to report progress on your own logger. The grants are
+skipped inside a Databricks App, and any failure is logged rather than thrown so
+a degraded cache never blocks startup.
+
 ## Modules
 
-- `createApp` - `createApp()` wrapper and `autoConfigure()`.
-- `lakebaseResolver` - Lakebase connection discovery, default picking, optional
-  auto-create, and env application.
-- `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.
+| Module             | Responsibility                                                                             |
+| ------------------ | ------------------------------------------------------------------------------------------ |
+| `createApp`        | `createApp()` wrapper and `autoConfigure()`.                                               |
+| `lakebaseResolver` | Lakebase connection discovery, default picking, optional auto-create, and env application. |
+| `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.                                                         |
 
 The shell-facing wrapper for auto-config is
 [`@dbx-tools/cli-appkit-env`](../../cli/appkit-env). Higher-level agent composition

package/index.ts

@@ -12,6 +12,7 @@ export * as plugin from "./src/plugin";
 export * as provision from "./src/provision";
 export type { ExecutionContextLike, WorkspaceClientLike } from "./src/appkit";
 export type { BundleValidateJson, ConfigFile, ConfigSource, ConfigMapValue, ResolveConfigValueOptions } from "./src/config";
+export type { AutoConfigureMode, CreateAppConfig } from "./src/create-app";
 export type { ContextLike } from "./src/databricks";
 export type { LakebaseResolverInputs, LakebaseConnection } from "./src/lakebase-resolver";
 export type { SslMode, LakebaseConnectionInputs, ParsedAddress } from "./src/pgaddress";

package/package.json

@@ -17,16 +17,16 @@
   "dependencies": {
     "@databricks/sdk-experimental": "^0.17.0",
     "yaml": "^2.9.0",
-    "zod": "^4.3.6",
-    "@dbx-tools/shared-core": "0.3.29",
-    "@dbx-tools/core": "0.3.29"
+    "zod": "4.3.6",
+    "@dbx-tools/core": "0.3.30",
+    "@dbx-tools/shared-core": "0.3.30"
   },
   "main": "index.ts",
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.29",
+  "version": "0.3.30",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/appkit.ts

@@ -12,6 +12,9 @@
  */
 
 import { createApp, getExecutionContext, InitializationError } from "@databricks/appkit";
+import { log } from "@dbx-tools/shared-core";
+
+const logger = log.logger("appkit");
 
 /**
  * The AppKit per-request execution context returned by `getExecutionContext()`
@@ -33,7 +36,14 @@ export type WorkspaceClientLike = ExecutionContextLike["client"];
 /**
  * The current AppKit execution context, or `undefined` when AppKit isn't
  * initialized (outside a request scope). Swallows AppKit's
- * `InitializationError`; any other error propagates.
+ * {@link InitializationError}; any other error propagates.
+ *
+ * @example
+ * import { appkit } from "@dbx-tools/appkit";
+ * import { WorkspaceClient } from "@databricks/sdk-experimental";
+ *
+ * // OBO-scoped inside a request, service principal from a CLI or script.
+ * const client = appkit.tryGetExecutionContext()?.client ?? new WorkspaceClient({});
  */
 export function tryGetExecutionContext(): ExecutionContextLike | undefined {
   try {
@@ -49,9 +59,18 @@ export function tryGetExecutionContext(): ExecutionContextLike | undefined {
   return undefined;
 }
 
-/** Initialize a bare AppKit app (no plugins) when none is running yet. */
+/**
+ * Initialize a bare AppKit app (no plugins) when none is running yet.
+ *
+ * @example
+ * import { appkit } from "@dbx-tools/appkit";
+ *
+ * await appkit.ensureInitialized();
+ * const client = appkit.tryGetExecutionContext()?.client;
+ */
 export async function ensureInitialized(): Promise<void> {
   if (!tryGetExecutionContext()) {
+    logger.debug("initializing a bare AppKit app");
     await createApp({ plugins: [] });
   }
 }

package/src/config.ts

@@ -2,9 +2,9 @@
  * Layered configuration resolution for local development against a Databricks
  * App / Asset Bundle.
  *
- * Default sources: `env`, then Databricks App `config.env` (from {@link bundle})
- * and hard-coded `app.yaml` env entries (from {@link appYaml}). Opt in to `cli`
- * when a dev command wants flag overrides.
+ * Default sources: `explicit`, then `env`, then Databricks App `config.env`
+ * (from {@link bundle}) and hard-coded `app.yaml` env entries (from
+ * {@link appYaml}). Opt in to `cli` when a dev command wants flag overrides.
  *
  * Server-only (`node:child_process`, bundle root discovery). Databricks-app
  * specific, so it lives in node-appkit rather than shared-core.
@@ -15,6 +15,7 @@
 import { spawnSync } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
+import { ValidationError } from "@databricks/appkit";
 import { file, project } from "@dbx-tools/core";
 import { functionModule, json, object, log, string } from "@dbx-tools/shared-core";
 import { parse as parseYamlText } from "yaml";
@@ -36,7 +37,7 @@ export interface ConfigFile {
 /** Supported configuration sources, consulted in array order. */
 export type ConfigSource = "explicit" | "cli" | "env" | "bundle";
 
-const defaultConfigSources: ConfigSource[] = ["env", "bundle"];
+const defaultConfigSources: ConfigSource[] = ["explicit", "env", "bundle"];
 
 const APP_YAML_NAMES = ["app.yaml", "app.yml"] as const;
 
@@ -113,9 +114,12 @@ export interface ResolveConfigValueOptions {
   bundleData?: ConfigFile;
   /** Parsed `app.yaml` contents. Defaults to {@link appYaml} (skipped inside a Databricks App). */
   appData?: ConfigFile;
-  /** Sources to consult, first truthy string wins. Defaults to `env`, then `bundle`. */
+  /**
+   * Sources to consult, first truthy string wins. Defaults to `explicit`, then
+   * `env`, then `bundle`.
+   */
   sources?: ConfigSource[];
-  /** Programmatic overrides. When set, `explicit` is appended to `sources` unless already listed. */
+  /** Programmatic overrides. When set, `explicit` is prepended to `sources` unless already listed. */
   explicit?: Record<string, ConfigMapValue>;
   /** CLI flag values (when `cli` is listed in `sources`). */
   cli?: Record<string, ConfigMapValue>;
@@ -184,7 +188,7 @@ function readAppEnv(keys: Iterable<string>, envMap: Record<string, string>): str
 }
 
 function parseYaml(text: string): unknown {
-  return parseYamlText(text) as unknown;
+  return parseYamlText(text);
 }
 
 function pickAppResourceId(apps: Record<string, BundleApp>): string | undefined {
@@ -318,10 +322,10 @@ async function loadAppYaml(cwd: string): Promise<ConfigFile | undefined> {
     try {
       const text = await readFile(configFile, "utf8");
       const data = parseYaml(text);
-      if (typeof data !== "object" || data === null || Array.isArray(data)) {
+      if (!object.isRecord(data)) {
         return undefined;
       }
-      return { path: configFile, data: data as Record<string, unknown> };
+      return { path: configFile, data };
     } catch {
       logger.warn("failed to parse app yaml", { path: configFile });
     }
@@ -369,14 +373,13 @@ export function getBundlePath(data: BundleValidateJson, path: string): string |
 
   let current: unknown = data;
   for (let i = 0; i < parts.length; i++) {
-    if (typeof current !== "object" || current === null) return undefined;
-    const record = current as Record<string, unknown>;
+    if (!object.isRecord(current)) return undefined;
     const part = parts[i]!;
-    const next = record[part];
+    const next = current[part];
     if (i === parts.length - 1) {
       if (typeof next === "string" && next) return next;
-      if (typeof next === "object" && next !== null && "value" in next) {
-        const value = (next as { value?: unknown }).value;
+      if (object.isRecord(next)) {
+        const value = next.value;
         return typeof value === "string" && value ? value : undefined;
       }
       return undefined;
@@ -399,7 +402,7 @@ async function resolveAppEnvMap(
 function resolveSources(options: ResolveConfigValueOptions): ConfigSource[] {
   const sources = [...(options.sources ?? defaultConfigSources)];
   if (options.explicit !== undefined && !sources.includes("explicit")) {
-    sources.push("explicit");
+    sources.unshift("explicit");
   }
   return sources;
 }
@@ -407,6 +410,17 @@ function resolveSources(options: ResolveConfigValueOptions): ConfigSource[] {
 /**
  * Resolve a configuration string from the configured sources. Returns the first
  * non-empty value, or `undefined` when nothing matches.
+ *
+ * Precedence follows AppKit's: explicit config, then environment variable, then
+ * whatever the Databricks App / bundle definition supplies.
+ *
+ * @example
+ * import { config } from "@dbx-tools/appkit";
+ *
+ * const warehouseId = await config.resolveConfigValue("DATABRICKS_WAREHOUSE_ID", {
+ *   cli: { DATABRICKS_WAREHOUSE_ID: flags.warehouse },
+ *   sources: config.withCliSources(),
+ * });
  */
 export async function resolveConfigValue(
   name: string,
@@ -433,7 +447,11 @@ export async function resolveConfigValue(
           yield readAppEnv(keys, appEnvMap);
           break;
         default:
-          throw new Error(`Unknown config source: ${source}`);
+          throw ValidationError.invalidValue(
+            "sources",
+            source,
+            "one of: explicit, cli, env, bundle",
+          );
       }
     }
   })();

package/src/create-app.ts

@@ -10,19 +10,22 @@
  * import { createApp } from "@dbx-tools/appkit";
  * import { lakebase, server } from "@databricks/appkit";
  *
- * await createApp({ plugins: [server(), lakebase()] });
+ * 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 `autoConfigure: true` is set on the
- * config object.
+ * 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 { log } from "@dbx-tools/shared-core";
+// AppKit's root barrel re-exports `PluginData` but not `PluginMap`; the package
+// publishes this subpath for exactly that type.
+import type { PluginMap } from "@databricks/appkit/dist/shared/src/plugin";
+import { async, log } from "@dbx-tools/shared-core";
 
 import {
   applyLakebaseToEnv,
@@ -31,31 +34,92 @@ import {
 } from "./lakebase-resolver";
 import { provisionCacheSchema } from "./provision";
 
-type CreateAppConfig = Parameters<typeof appkitCreateApp>[0] & {
-  autoConfigure?: boolean | "provision";
+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.
+ */
+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;
 };
 
 const logger = log.logger("create-app");
 
 const LAKEBASE_PLUGIN = "lakebase";
+const DEFAULT_AUTO_CONFIGURE: AutoConfigureMode = "provision";
 
-function usesPlugin(config: CreateAppConfig | undefined, name: string): boolean {
+/**
+ * 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<T extends AppKitPlugins>(
+  config: CreateAppConfig<T> | undefined,
+  name: string,
+): boolean {
   return Boolean(config?.plugins?.some((entry) => entry.name === name));
 }
 
 /**
  * Run enabled auto-configuration steps without calling AppKit's `createApp`.
- * Lakebase Postgres resolves when `autoConfigure` is `true` or a `lakebase`
- * plugin is listed in `config.plugins`. Defaults to `"provision"` (Lakebase env
- * + optional cache schema). Pass `autoConfigure: false` to skip entirely.
+ *
+ * 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?: CreateAppConfig): Promise<void> {
-  const { autoConfigure = "provision" } = config ?? {};
-  if (autoConfigure !== false) {
-    if (autoConfigure === true || usesPlugin(config, LAKEBASE_PLUGIN)) {
-      await autoConfigureLakebase(autoConfigure === "provision");
-    }
+export async function autoConfigure<T extends AppKitPlugins>(
+  config?: CreateAppConfig<T>,
+  signal?: AbortSignal,
+): Promise<void> {
+  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 });
 }
 
 /**
@@ -64,23 +128,21 @@ export async function autoConfigure(config?: CreateAppConfig): Promise<void> {
  * {@link resolveLakebaseConnection} and {@link applyLakebaseToEnv} directly when
  * finer control is needed.
  */
-async function autoConfigureLakebase(provision: boolean): Promise<LakebaseConnection> {
-  const resolved = await resolveLakebaseConnection();
+async function autoConfigureLakebase(
+  provision: boolean,
+  signal: AbortSignal,
+): Promise<LakebaseConnection> {
+  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(logger, user);
+    await provisionCacheSchema(user, logger);
   }
   return resolved;
 }
 
-const create = async (config?: CreateAppConfig) => {
-  await autoConfigure(config);
-  return appkitCreateApp(config);
-};
-
 function redactLakebaseConnection(resolved: LakebaseConnection): Record<string, unknown> {
   return {
     project: resolved.project,
@@ -93,5 +155,21 @@ function redactLakebaseConnection(resolved: LakebaseConnection): Record<string,
   };
 }
 
-/** Auto-configuring drop-in for AppKit's `createApp`. */
-export const createApp = create as unknown as typeof appkitCreateApp;
+/**
+ * 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<T extends AppKitPlugins>(
+  config?: CreateAppConfig<T>,
+): Promise<PluginMap<T>> {
+  await autoConfigure(config);
+  const appConfig = { ...config };
+  delete appConfig.autoConfigure;
+  return appkitCreateApp<T>(appConfig);
+}

package/src/databricks.ts

@@ -12,13 +12,24 @@
 
 import type { CancellationToken } from "@databricks/sdk-experimental";
 import { Context } from "@databricks/sdk-experimental";
-import { async } from "@dbx-tools/shared-core";
+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: Record<string, string | undefined> = process.env): boolean {
   const appName = env.DATABRICKS_APP_NAME?.trim();
@@ -32,14 +43,17 @@ export function isAppEnv(env: Record<string, string | undefined> = process.env):
   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 > 65535) {
+  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;
   }
 
@@ -49,7 +63,18 @@ export function isAppEnv(env: Record<string, string | undefined> = process.env):
 /** 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`. */
+/**
+ * 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 function toContext(input: ContextLike): Context;
 /**
  * Derive an SDK `Context` from `controller.signal`, optionally tying `input`