@dbx-tools/appkit 0.6.69 → 0.6.71

package/src/_cache-storage.ts

@@ -0,0 +1,129 @@
+/**
+ * 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, type CacheConfig } 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(): boolean {
+  return log.isLevelEnabled("debug");
+}
+
+type LakebasePool = ReturnType<typeof createLakebasePool>;
+type CacheStorage = NonNullable<CacheConfig["storage"]>;
+
+/** AppKit's internal persistent storage surface. */
+type PersistentStorageBase = CacheStorage & {
+  initialize(): Promise<void>;
+  initialized: boolean;
+};
+
+type PersistentStorageConstructor = new (
+  config: CacheConfig,
+  pool: LakebasePool,
+) => PersistentStorageBase;
+
+let persistentStorageCtor: PersistentStorageConstructor | undefined | null = null;
+
+/**
+ * Lazily resolve AppKit's internal `PersistentStorage` constructor. `null`
+ * means the lookup already failed; `undefined` means not attempted yet.
+ */
+function loadPersistentStorage(): PersistentStorageConstructor | undefined {
+  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 as
+      PersistentStorageConstructor | undefined;
+    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: PersistentStorageBase): void {
+  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: CacheConfig | undefined,
+): Promise<CacheStorage | undefined> {
+  const PersistentStorage = loadPersistentStorage();
+  if (!PersistentStorage) {
+    return undefined;
+  }
+
+  let pool: LakebasePool | undefined;
+  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;
+  }
+}

package/src/appkit.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
@@ -11,11 +27,323 @@
  * @module
  */
 
-import { createApp, getExecutionContext, InitializationError } from "@databricks/appkit";
-import { log } from "@dbx-tools/shared-core";
+import {
+  createApp as appkitCreateApp,
+  getExecutionContext,
+  InitializationError,
+} from "@databricks/appkit";
+// 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 {
+  createInterceptorContext,
+  type Interceptor,
+  type InterceptorRuntime,
+  lifecycleBridge,
+  type ResolvedAppEnv,
+} from "./interceptor.ts";
+import { createSoftPersistentStorage } from "./_cache-storage.ts";
+import { applyLakebaseEnv, type LakebaseConnection } from "./lakebase-resolver.ts";
+import { provisionCacheSchema } from "./provision.ts";
 
 const logger = log.logger("appkit");
 
+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[];
+};
+
+const LAKEBASE_PLUGIN = "lakebase";
+const DEFAULT_AUTO_CONFIGURE: AutoConfigureMode = "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<T extends AppKitPlugins>(
+  config: CreateAppConfig<T> | undefined,
+  name: string,
+): boolean {
+  return Boolean(config?.plugins?.some((entry) => entry.name === name));
+}
+
+/** Plugin names for boot logs (order preserved). */
+function pluginNames(config: CreateAppConfig | undefined): string[] {
+  return (config?.plugins ?? []).map((entry) => entry.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 { appkit } from "@dbx-tools/appkit";
+ *
+ * // Populate PGHOST / PGDATABASE / LAKEBASE_ENDPOINT without booting AppKit.
+ * await appkit.autoConfigure({ autoConfigure: "env" });
+ */
+export async function autoConfigure<T extends AppKitPlugins>(
+  config?: CreateAppConfig<T>,
+  signal?: AbortSignal,
+): Promise<LakebaseConnection | undefined> {
+  const mode = config?.autoConfigure ?? DEFAULT_AUTO_CONFIGURE;
+  const explicit = config?.autoConfigure !== undefined;
+  const lakebasePluginPresent = usesPlugin(config, LAKEBASE_PLUGIN);
+  const plugins = pluginNames(config);
+  logger.debug("autoConfigure: start", {
+    mode,
+    explicit,
+    lakebasePluginPresent,
+    plugins,
+    timeoutMs: AUTO_CONFIGURE_TIMEOUT_MS,
+    callerSignal: Boolean(signal),
+  });
+
+  if (mode === false || !(explicit || lakebasePluginPresent)) {
+    const skippedReason = mode === false ? "disabled" : "no lakebase plugin";
+    logger.debug("autoConfigure: skip", { skippedReason, mode, lakebasePluginPresent, plugins });
+    logger.info("ready", {
+      autoConfigure: mode,
+      lakebasePluginPresent,
+      provisioned: false,
+      skippedReason,
+    });
+    return undefined;
+  }
+
+  const controller = new AbortController();
+  async.tieAbortSignal(controller, signal);
+  async.tieAbortSignal(controller, AbortSignal.timeout(AUTO_CONFIGURE_TIMEOUT_MS));
+
+  const provision = mode === "provision";
+  logger.debug("autoConfigure: resolve lakebase", { provision, mode });
+  const resolved = await autoConfigureLakebase(provision, controller.signal);
+  logger.debug("autoConfigure: done", {
+    mode,
+    lakebasePluginPresent,
+    provisioned: provision,
+    ...redactLakebaseConnection(resolved),
+  });
+  logger.info("ready", { autoConfigure: mode, lakebasePluginPresent, provisioned: provision });
+  return resolved;
+}
+
+/**
+ * Resolve Lakebase Postgres connection info, write the resolved values to
+ * `process.env`, and return the record. Used by {@link autoConfigure}; call
+ * {@link applyLakebaseEnv} directly when finer control is needed (a different
+ * `autoCreate` policy, or a caller that wants the env without booting AppKit).
+ */
+async function autoConfigureLakebase(
+  provision: boolean,
+  signal: AbortSignal,
+): Promise<LakebaseConnection> {
+  logger.debug("autoConfigureLakebase: applyLakebaseEnv");
+  const { resolved, user } = await applyLakebaseEnv(undefined, signal);
+  logger.debug("autoConfigureLakebase: env applied", {
+    ...redactLakebaseConnection(resolved),
+    user,
+    env: {
+      LAKEBASE_ENDPOINT: process.env.LAKEBASE_ENDPOINT,
+      PGHOST: process.env.PGHOST,
+      PGPORT: process.env.PGPORT,
+      PGDATABASE: process.env.PGDATABASE,
+      PGUSER: process.env.PGUSER,
+      PGSSLMODE: process.env.PGSSLMODE,
+    },
+  });
+  logger.info("env updated", { ...redactLakebaseConnection(resolved), user });
+  if (provision) {
+    logger.debug("autoConfigureLakebase: provisionCacheSchema", { user });
+    await provisionCacheSchema(user, logger);
+    logger.debug("autoConfigureLakebase: provisionCacheSchema done");
+  } else {
+    logger.debug("autoConfigureLakebase: skip provision (mode=env)");
+  }
+  return resolved;
+}
+
+/**
+ * Whether `createApp` should inject soft-fail Lakebase cache storage.
+ *
+ * Skips when the caller disabled the cache, already supplied a storage
+ * backend (including in-memory), or Lakebase is not in play.
+ */
+function shouldInjectSoftPersistentCache(
+  config: CreateAppConfig | undefined,
+  lakebase: LakebaseConnection | undefined,
+): boolean {
+  const cache = config?.cache;
+  if (cache?.enabled === false) return false;
+  if (cache?.storage) return false;
+  return Boolean(lakebase) || usesPlugin(config, LAKEBASE_PLUGIN);
+}
+
+function redactLakebaseConnection(resolved: LakebaseConnection): Record<string, unknown> {
+  return {
+    project: resolved.project,
+    branch: resolved.branch,
+    endpoint: resolved.endpoint,
+    database: resolved.database,
+    host: resolved.host,
+    port: resolved.port,
+    sslMode: resolved.sslMode,
+  };
+}
+
+/** Build the {@link ResolvedAppEnv} interceptors read, from the auto-config result. */
+function resolvedAppEnv(lakebase: LakebaseConnection | undefined): ResolvedAppEnv {
+  return {
+    ...(lakebase ? { lakebase } : {}),
+    ...(process.env.DATABRICKS_HOST ? { databricksHost: process.env.DATABRICKS_HOST } : {}),
+  };
+}
+
+/** Normalize the `interceptor?: Interceptor | Interceptor[]` option to an array. */
+function interceptorList(interceptor: CreateAppConfig["interceptor"]): Interceptor[] {
+  if (!interceptor) return [];
+  return Array.isArray(interceptor) ? interceptor : [interceptor];
+}
+
+/**
+ * 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 async function createApp<T extends AppKitPlugins>(
+  config?: CreateAppConfig<T>,
+): Promise<PluginMap<T>> {
+  const plugins = pluginNames(config);
+  const interceptors = interceptorList(config?.interceptor);
+  logger.debug("createApp: start", {
+    plugins,
+    pluginCount: plugins.length,
+    interceptorCount: interceptors.length,
+    autoConfigure: config?.autoConfigure ?? "(default)",
+    hasOnPluginsReady: typeof config?.onPluginsReady === "function",
+  });
+
+  logger.debug("createApp: autoConfigure");
+  const lakebase = await autoConfigure(config);
+  logger.debug("createApp: autoConfigure returned", {
+    lakebase: lakebase ? redactLakebaseConnection(lakebase) : undefined,
+  });
+
+  const appConfig = { ...config };
+  delete appConfig.autoConfigure;
+  delete appConfig.interceptor;
+
+  if (shouldInjectSoftPersistentCache(config, lakebase)) {
+    logger.debug("createApp: inject soft persistent cache storage");
+    const storage = await createSoftPersistentStorage(config?.cache);
+    if (storage) {
+      appConfig.cache = { ...config?.cache, storage };
+      logger.debug("createApp: soft persistent cache storage ready");
+    } else {
+      logger.debug("createApp: soft persistent cache storage unavailable");
+    }
+  }
+
+  if (interceptors.length === 0) {
+    logger.debug("createApp: no interceptors; delegating to AppKit createApp", {
+      plugins: pluginNames(appConfig),
+    });
+    const result = await appkitCreateApp<T>(appConfig);
+    logger.debug("createApp: AppKit createApp returned", {
+      exportKeys: Object.keys(result ?? {}),
+    });
+    return result;
+  }
+
+  // Build the context from the computed env, run each interceptor (they register
+  // lifecycle handlers + bind processes), then inject the bridge that relays the
+  // REAL AppKit lifecycle into `runtime.emitLifecycle` during its `setup()`.
+  const env = resolvedAppEnv(lakebase);
+  logger.debug("createApp: interceptor context", {
+    hasLakebase: Boolean(env.lakebase),
+    databricksHost: env.databricksHost,
+    interceptorCount: interceptors.length,
+  });
+  const runtime: InterceptorRuntime = createInterceptorContext(env);
+  for (let i = 0; i < interceptors.length; i++) {
+    logger.debug("createApp: run interceptor", { index: i, of: interceptors.length });
+    await interceptors[i]!(runtime.context);
+    logger.debug("createApp: interceptor done", { index: i });
+  }
+  // Append the bridge to the plugins tuple. It is hidden and exports nothing, so
+  // the returned map still matches `PluginMap<T>`; the cast (through `unknown`) is
+  // only because appending widens the tuple type beyond `T`.
+  appConfig.plugins = [...(appConfig.plugins ?? []), lifecycleBridge({ runtime })] as unknown as T;
+  logger.debug("createApp: lifecycle bridge injected; delegating to AppKit createApp", {
+    plugins: pluginNames(appConfig),
+  });
+  const result = await appkitCreateApp<T>(appConfig);
+  logger.debug("createApp: AppKit createApp returned", {
+    exportKeys: Object.keys(result ?? {}),
+  });
+  return result;
+}
+
 /**
  * The AppKit per-request execution context returned by `getExecutionContext()`
  * - the OBO-scoped workspace client plus the surrounding request metadata.
@@ -69,8 +397,11 @@ export function tryGetExecutionContext(): ExecutionContextLike | undefined {
  * const client = appkit.tryGetExecutionContext()?.client;
  */
 export async function ensureInitialized(): Promise<void> {
-  if (!tryGetExecutionContext()) {
-    logger.debug("initializing a bare AppKit app");
-    await createApp({ plugins: [] });
+  if (tryGetExecutionContext()) {
+    logger.debug("ensureInitialized: already initialized");
+    return;
   }
+  logger.debug("ensureInitialized: booting bare AppKit app");
+  await createApp({ plugins: [], autoConfigure: false });
+  logger.debug("ensureInitialized: done");
 }

package/src/interceptor.ts

@@ -5,17 +5,17 @@
  * unit - concurrently-style, where any death takes the whole set down.
  *
  * An interceptor is a plain function `(ctx) => void | Promise<void>` passed to
- * {@link CreateAppConfig.interceptor} ("one or many"). {@link createApp} runs each
- * one AFTER auto-configuration has populated `process.env` but as part of booting
- * the app, so an interceptor sees the resolved connection and can bind processes
- * before or during setup.
+ * `appkit.createApp`'s `interceptor` option ("one or many"). `appkit.createApp`
+ * runs each one AFTER auto-configuration has populated `process.env` but as part
+ * of booting the app, so an interceptor sees the resolved connection and can bind
+ * processes before or during setup.
  *
  * The names here mirror AppKit's own vocabulary rather than inventing parallel
  * ones: {@link LifecycleEvent} and {@link InterceptorContext.onLifecycle} are the
  * exact shape of `PluginContext.onLifecycle` (`setup:complete` / `server:ready` /
  * `shutdown`). The bridge that makes that hook reachable from OUTSIDE a plugin -
  * where interceptors run - is {@link lifecycleBridge}, a tiny internal plugin
- * {@link createApp} injects to capture `this.context` and relay its events.
+ * `appkit.createApp` injects to capture `this.context` and relay its events.
  *
  * @module
  */
@@ -49,7 +49,7 @@ export type LifecycleHandler = () => void | Promise<void>;
  * they read COMPUTED values instead of re-reading `process.env` themselves.
  *
  * `lakebase` is the resolved Postgres connection when Lakebase auto-config ran
- * (see `create-app`'s `autoConfigure`), else `undefined`. `databricksHost` is the
+ * (see `appkit.autoConfigure`), else `undefined`. `databricksHost` is the
  * workspace host as resolved into the environment (`DATABRICKS_HOST`), which the
  * tunnel interceptor both reads and, when it must, sets.
  */
@@ -72,9 +72,9 @@ export type BindableProcess = Pick<ChildProcess, "pid" | "kill" | "killed" | "on
  * The handle passed to each interceptor.
  *
  * @example
- * import { createApp } from "@dbx-tools/appkit";
+ * import { appkit } from "@dbx-tools/appkit";
  *
- * await createApp({
+ * await appkit.createApp({
  *   plugins: [server()],
  *   interceptor: (ctx) => {
  *     const portr = spawnPortr(ctx.env.databricksHost);
@@ -120,7 +120,7 @@ const TEARDOWN_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"] as const;
 /**
  * The mutable machinery behind an {@link InterceptorContext}. Split out so
  * {@link createInterceptorContext} can hand the public context to interceptors
- * while `create-app` retains the `emitLifecycle` side-channel the bridge drives.
+ * while `appkit.createApp` retains the `emitLifecycle` side-channel the bridge drives.
  */
 export interface InterceptorRuntime {
   /** The context handed to each interceptor. */
@@ -227,7 +227,7 @@ function hasOnLifecycle(context: unknown): context is LifecycleContextLike {
 }
 
 /**
- * The internal plugin {@link createApp} injects to make AppKit's lifecycle
+ * The internal plugin `appkit.createApp` injects to make AppKit's lifecycle
  * reachable from interceptor code. On `setup()` it reads its own `this.context`
  * (the real `PluginContext`) and forwards each {@link LifecycleEvent} to the
  * interceptor runtime, so `ctx.onLifecycle(...)` handlers fire on the genuine

package/lib/src/create-app.d.ts

@@ -1,96 +0,0 @@
-/**
- * `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 } 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 { createApp } from "@dbx-tools/appkit";
- *
- * // Populate PGHOST / PGDATABASE / LAKEBASE_ENDPOINT without booting AppKit.
- * await createApp.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 { createApp } from "@dbx-tools/appkit";
- * import { lakebase, server } from "@databricks/appkit";
- *
- * const app = await createApp.createApp({ plugins: [server(), lakebase()] });
- */
-export declare function createApp<T extends AppKitPlugins>(config?: CreateAppConfig<T>): Promise<PluginMap<T>>;
-export {};