@dbx-tools/shared 0.1.18

package/README.md

@@ -0,0 +1,234 @@
+# @dbx-tools/shared
+
+Shared utilities used by the other `@dbx-tools/appkit-*` plugins. The
+package has zero AppKit runtime dependency (it lists `@databricks/appkit`
+as a peer) so it's safe to consume from any plugin or app code.
+
+Each utility module is exported as a namespace so call sites read
+naturally and never collide with similarly named helpers from other
+libraries:
+
+```ts
+import {
+  apiUtils,
+  appkitUtils,
+  commonUtils,
+  httpUtils,
+  logUtils,
+  netUtils,
+  projectUtils,
+  stringUtils,
+} from "@dbx-tools/shared";
+```
+
+> `apiUtils` and `projectUtils` import Node-only modules (`@databricks/appkit`,
+> `node:fs`) and are intentionally **not** re-exported from the browser
+> entry. Vite / Webpack / esbuild builds that honor the `browser`
+> condition will resolve `@dbx-tools/shared` to a barrel that
+> omits both - import them only from server-side code.
+
+## `appkitUtils` - typed sibling-plugin lookup
+
+AppKit's `this.context.getPlugins()` returns `ReadonlyMap<string, BasePlugin>`,
+so every cross-plugin call ends up writing the same
+`as InstanceType<ReturnType<typeof someFactory>["plugin"]>` cast.
+`appkitUtils.instance` / `appkitUtils.require` absorb that boilerplate:
+
+```ts
+import { lakebase } from "@databricks/appkit";
+import { appkitUtils } from "@dbx-tools/shared";
+
+const lake = appkitUtils.instance(this.context, lakebase);
+//    ^^ inferred as LakebasePlugin | undefined
+const pool = lake?.exports().pool;
+
+// Throws "<caller>: required plugin not registered: lakebase" when missing.
+const pool2 = appkitUtils
+  .require(this.context, lakebase, "mastra")
+  .exports().pool;
+```
+
+`appkitUtils.data(factory)` caches the static `{ plugin, name }` descriptor
+per factory so repeated lookups don't allocate. Use it directly when you
+need the registered name for a manifest dependency.
+
+## `httpUtils` - framework-neutral header helpers
+
+Public surface: `forEachHeaderValue`, `parseCookies`. The header-shaped
+helpers work uniformly against any of:
+
+- Express `req` (Node-style `req.headers`)
+- Web Fetch `Request` (`Headers` instance)
+- Hono `Context.req` (`c.req.raw.headers`)
+- `node:http` `IncomingMessage`
+- Plain `Record<string, string | string[] | undefined>`
+
+```ts
+import { httpUtils } from "@dbx-tools/shared";
+
+app.use((req, res, next) => {
+  const session = httpUtils.parseCookies(req).session;
+
+  // Walk every value of a (possibly repeated) header without committing
+  // to a specific framework's accessor shape.
+  let bearer: string | undefined;
+  httpUtils.forEachHeaderValue(req, "authorization", (value) => {
+    if (value.startsWith("Bearer ")) bearer = value.slice(7);
+  });
+});
+```
+
+## `netUtils` - URL parsing + free-port helpers
+
+Public surface: `joinUrl`, `parseUrl`, plus the server-only
+`getRandomPort`. The URL helpers are pure JS and ship in the
+browser bundle too; `getRandomPort` binds a transient `node:net`
+listener and is therefore server-only (importing `netUtils` from
+the browser entry simply omits it).
+
+```ts
+import { netUtils } from "@dbx-tools/shared";
+
+// Tolerant URL coercion - bare hostnames, partial inputs, or
+// objects with a `.url` field all round-trip through. Returns
+// `null` on failure (matches WHATWG `URL.parse(...)` semantics).
+const url = netUtils.parseUrl("example.com");  // https://example.com/
+
+// Path-segment join: nullish/blank inputs are skipped, leading /
+// trailing slashes are normalized, nested arrays recurse.
+netUtils.joinUrl("/api/", ["v2", "items"], null); // "/api/v2/items"
+
+// Grab a free local port (server only).
+const port = await netUtils.getRandomPort();
+```
+
+## `apiUtils` - authenticated Databricks REST calls (server only)
+
+Wraps `fetch` against `https://<workspace-host>/api/2.0/<path>` with the
+auth header your AppKit execution context already carries, plus an
+optional `CacheManager.getOrExecute` hook so per-user TTL'd reads are a
+single positional arg:
+
+```ts
+import { apiUtils } from "@dbx-tools/shared";
+
+// Bare GET against the workspace /api/2.0 namespace - leading /api/2.0
+// is auto-stripped so you can pass either form.
+const data = await apiUtils.fetchApi<{ endpoints?: unknown[] }>(
+  "serving-endpoints",
+);
+
+// With a per-user cache (useful for "list everything" calls):
+const cached = await apiUtils.fetchApi<{ endpoints?: unknown[] }>(
+  "serving-endpoints",
+  undefined,
+  { userKey: req.userId, options: { ttl: 300 } },
+);
+
+// POST + custom client (e.g. service-account script outside a request).
+await apiUtils.fetchApi<{ id: string }>(
+  ["serving-endpoints", endpointName, "invocations"],
+  {
+    body: JSON.stringify({ inputs }),
+    headers: { "Content-Type": "application/json" },
+  },
+  undefined,
+  serviceClient,
+);
+```
+
+Defaults to `POST` when `init.body` is set, `GET` otherwise. The wrapper
+needs an active `getExecutionContext()` to resolve the workspace client
+unless a `WorkspaceClient` is passed in explicitly, so it's server-only.
+
+## `stringUtils` - identifier + slug helpers
+
+`toIdentifier` / `toSlug` are deterministic, length-bounded, and always
+lower-case at the type level (the `lowerCase` option literal is fixed to
+`true` so an explicit `false` is a compile error):
+
+```ts
+import { stringUtils } from "@dbx-tools/shared";
+
+stringUtils.toIdentifier("My Cool Project!"); // "my_cool_project"
+stringUtils.toSlug("My Cool Project!"); // "my-cool-project"
+
+stringUtils.toIdentifierWithOptions({ maxLength: 12 }, "very long project name");
+// "very_long_43c1"  <- hash suffix when truncated
+```
+
+## `projectUtils` - project name + git-remote parsing
+
+```ts
+import { projectUtils } from "@dbx-tools/shared";
+
+// Discovers a stable name for the current project. Order:
+// 1. `package.json` name (root of an npm/bun workspace if applicable)
+// 2. Closest `git remote origin` repo name
+// 3. Process `cwd` basename
+const name = await projectUtils.name();
+
+// Strip "owner/" + ".git" from a remote URL.
+projectUtils.parseGitRemote("git@github.com:org/my-repo.git"); // "my-repo"
+```
+
+## `commonUtils` - memoize + hashing
+
+```ts
+import { commonUtils } from "@dbx-tools/shared";
+
+// Memoize by all-args; sync results cache forever, async failures bust.
+const fetchUser = commonUtils.memoize(async (id: string) => loadUser(id));
+
+// Short, deterministic hash for cache keys / slug suffixes / etc.
+// Pure-JS FNV-1a in Crockford-style base-32 (digits + lowercase
+// alphabet minus i/l/o/u). Browser-safe.
+commonUtils.fnvHash("databricks-claude-sonnet-4-6"); // e.g. "k3p9q7"
+commonUtils.fnvHashWithOptions({ length: 4 }, "user@example.com");
+```
+
+`@memoized` is a TC39 stage-1 method decorator built on the same
+`memoize` (requires `experimentalDecorators: true` in `tsconfig.json`).
+`fnvHash` is intentionally **not** cryptographically secure - use it for
+keys and slugs, never for tokens or signatures.
+
+## `logUtils` - tagged console logger
+
+`logger(plugin)` returns a leveled `{ debug, info, warn, error }` interface
+that auto-tags every line with the plugin's name:
+
+```ts
+import { logUtils } from "@dbx-tools/shared";
+
+class MyPlugin extends Plugin<MyConfig> {
+  private log = logUtils.logger(this); // tags as "[my-plugin]"
+  override async setup() {
+    this.log.info("setup", { mode: this.config.mode });
+  }
+}
+```
+
+The logger is intentionally console-backed (no extra deps). For richer
+sinks pass your own `{ debug, info, warn, error }` object - the plugins
+in this repo accept any matching shape.
+
+### `LOG_LEVEL` filtering
+
+Each call checks `process.env.LOG_LEVEL` (case-insensitive, default
+`info`) and drops anything below the threshold *before* string
+formatting, so leaving `log.debug({...heavy details})` calls in
+production code costs nothing as long as `LOG_LEVEL` isn't `debug`.
+
+```bash
+LOG_LEVEL=debug bun dev    # full verbosity
+LOG_LEVEL=warn  bun start  # production: hide info chatter
+```
+
+The lookup is per-call (not module-load), so test runners can flip
+the threshold after the module has been imported. In browser bundles
+where `process.env.LOG_LEVEL` is undefined, the default `info`
+threshold applies.
+
+## License
+
+Apache-2.0

package/dist/index.client.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Browser-safe entry point for `@dbx-tools/shared`. Mirrors
+ * the server-side {@link ./index.ts} barrel except `projectUtils` is
+ * absent - it imports `node:fs` / `node:child_process` / `node:path` /
+ * `node:util` at module load, which Vite stubs for browsers and which
+ * blows up at the first property access from the stub.
+ *
+ * Resolution: the package's `exports` map points the `browser`
+ * condition at this file. Vite (and any other browser-aware bundler
+ * that honors `exports.<entry>.browser`) picks it up automatically;
+ * Node always uses `index.ts`. Don't import `./src/project.js` from
+ * here, even transitively - that's the entire point of the split.
+ *
+ * Other utility namespaces are re-exported as-is. `common.ts` ships a
+ * pure-JS FNV-1a `fnvHash` (no `node:crypto`) that `string.ts` uses
+ * for slug suffixes, so the whole barrel is safe in the browser;
+ * `http.ts` / `log.ts` already had no node-only imports.
+ *
+ * `apiUtils` and `appkitUtils` are intentionally **not** re-exported
+ * here. Both import from `@databricks/appkit`, whose main barrel
+ * re-exports server-only typegen helpers
+ * (`extractServingEndpoints`, the `appKit*TypesPlugin` Vite plugins)
+ * that transitively load `@ast-grep/napi`'s native `.node` binary.
+ * Letting either land in the browser bundle drags the entire appkit
+ * tree (including ast-grep) into the client. They live only on
+ * `index.ts` (the server entry).
+ */
+export * as commonUtils from "./src/common.js";
+export * as httpUtils from "./src/http.js";
+export * as logUtils from "./src/log.js";
+export * as netUtils from "./src/net.browser.js";
+export * as stringUtils from "./src/string.js";

package/dist/index.client.js

@@ -0,0 +1,32 @@
+/**
+ * Browser-safe entry point for `@dbx-tools/shared`. Mirrors
+ * the server-side {@link ./index.ts} barrel except `projectUtils` is
+ * absent - it imports `node:fs` / `node:child_process` / `node:path` /
+ * `node:util` at module load, which Vite stubs for browsers and which
+ * blows up at the first property access from the stub.
+ *
+ * Resolution: the package's `exports` map points the `browser`
+ * condition at this file. Vite (and any other browser-aware bundler
+ * that honors `exports.<entry>.browser`) picks it up automatically;
+ * Node always uses `index.ts`. Don't import `./src/project.js` from
+ * here, even transitively - that's the entire point of the split.
+ *
+ * Other utility namespaces are re-exported as-is. `common.ts` ships a
+ * pure-JS FNV-1a `fnvHash` (no `node:crypto`) that `string.ts` uses
+ * for slug suffixes, so the whole barrel is safe in the browser;
+ * `http.ts` / `log.ts` already had no node-only imports.
+ *
+ * `apiUtils` and `appkitUtils` are intentionally **not** re-exported
+ * here. Both import from `@databricks/appkit`, whose main barrel
+ * re-exports server-only typegen helpers
+ * (`extractServingEndpoints`, the `appKit*TypesPlugin` Vite plugins)
+ * that transitively load `@ast-grep/napi`'s native `.node` binary.
+ * Letting either land in the browser bundle drags the entire appkit
+ * tree (including ast-grep) into the client. They live only on
+ * `index.ts` (the server entry).
+ */
+export * as commonUtils from "./src/common.js";
+export * as httpUtils from "./src/http.js";
+export * as logUtils from "./src/log.js";
+export * as netUtils from "./src/net.browser.js";
+export * as stringUtils from "./src/string.js";

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Server-side entry point for `@dbx-tools/shared`. Re-exports
+ * everything from the browser-safe {@link ./index.client.ts} barrel
+ * and adds the server-only namespaces:
+ *   - `projectUtils` imports `node:fs` / `node:child_process` /
+ *     `node:path` / `node:util`.
+ *   - `apiUtils` / `appkitUtils` both import from `@databricks/appkit`,
+ *     whose barrel transitively pulls in the typegen helpers and the
+ *     `@ast-grep/napi` native binary. Keeping them out of the
+ *     browser entry stops that whole subtree from being bundled
+ *     for the client.
+ *
+ * Resolution: this file is the `import` / `default` target in the
+ * package's `exports` map. Vite (and any other browser-aware
+ * bundler that honors `exports.<entry>.browser`) picks
+ * `index.client.ts` instead, so the node-only branches never ship
+ * to the client. Add new browser-safe helpers to `index.client.ts`
+ * to keep this file as the thin server-only delta.
+ */
+export * as appkitUtils from "./src/appkit.js";
+export * as apiUtils from "./src/api.js";
+export * as netUtils from "./src/net.js";
+export * as projectUtils from "./src/project.js";
+export * from "./index.client.js";

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * Server-side entry point for `@dbx-tools/shared`. Re-exports
+ * everything from the browser-safe {@link ./index.client.ts} barrel
+ * and adds the server-only namespaces:
+ *   - `projectUtils` imports `node:fs` / `node:child_process` /
+ *     `node:path` / `node:util`.
+ *   - `apiUtils` / `appkitUtils` both import from `@databricks/appkit`,
+ *     whose barrel transitively pulls in the typegen helpers and the
+ *     `@ast-grep/napi` native binary. Keeping them out of the
+ *     browser entry stops that whole subtree from being bundled
+ *     for the client.
+ *
+ * Resolution: this file is the `import` / `default` target in the
+ * package's `exports` map. Vite (and any other browser-aware
+ * bundler that honors `exports.<entry>.browser`) picks
+ * `index.client.ts` instead, so the node-only branches never ship
+ * to the client. Add new browser-safe helpers to `index.client.ts`
+ * to keep this file as the thin server-only delta.
+ */
+export * as appkitUtils from "./src/appkit.js";
+export * as apiUtils from "./src/api.js";
+export * as netUtils from "./src/net.js";
+export * as projectUtils from "./src/project.js";
+export * from "./index.client.js";

package/dist/src/api.d.ts

@@ -0,0 +1,90 @@
+import type { WorkspaceClient } from "@databricks/sdk-experimental";
+import { Context } from "@databricks/sdk-experimental";
+import { CacheManager } from "@databricks/appkit";
+type GetOrExecuteParams = Parameters<CacheManager["getOrExecute"]>;
+type ApiRequestInit = RequestInit & {
+    cache?: {
+        key?: GetOrExecuteParams[0];
+        userKey?: GetOrExecuteParams[2];
+        options: GetOrExecuteParams[3];
+    };
+    workspaceClient?: WorkspaceClient;
+};
+/**
+ * Build the absolute `URL` for a Databricks workspace REST endpoint
+ * without issuing a request. Mirrors {@link fetchApi}'s path handling
+ * (single string or array of segments, leading `/api/2.0` stripped)
+ * so callers can construct request URLs that match what `fetchApi`
+ * would have used. Resolves the host from the supplied
+ * `WorkspaceClient` or, when omitted, from the active
+ * `getExecutionContext().client`.
+ */
+export declare function apiUrl(path: string[] | string, workspaceClient?: WorkspaceClient): Promise<URL>;
+/**
+ * Issue an authenticated request against a Databricks workspace REST
+ * endpoint, resolving the host from the supplied `WorkspaceClient`
+ * and stamping the OAuth/PAT auth header in for you. The response
+ * body is returned parsed as JSON.
+ *
+ * `path` may be a single string or an array of segments. A leading
+ * `/api/2.0` is auto-stripped so callers can pass either style
+ * (`"/api/2.0/serving-endpoints"` or `"/serving-endpoints"`) without
+ * doubling it in the final URL.
+ *
+ * `init` is an optional WHATWG `RequestInit`. Useful fields:
+ *
+ *   - `body`: request payload. Strings / `Buffer` / `FormData` /
+ *     `URLSearchParams` pass through; for JSON, stringify the object
+ *     yourself and set `headers["Content-Type"] = "application/json"`.
+ *   - `headers`: extra request headers, merged in **before** the auth
+ *     header is applied so the workspace's `Authorization` always
+ *     wins on conflict.
+ *   - `method`: HTTP verb. If omitted, defaults to `POST` when
+ *     `init.body` is present and `GET` otherwise.
+ *
+ * `cache` is an optional handle to `CacheManager.getOrExecute`: pass
+ * `{ options: { ttl: 300 } }` for a per-user, time-boxed cache; the
+ * `userId` from the active execution context becomes part of the
+ * cache key by default.
+ *
+ * `workspaceClient` is optional; when omitted the request uses the
+ * caller's `getExecutionContext().client` (i.e. the per-request
+ * OBO client). Pass an explicit client for service-account work
+ * outside a request.
+ *
+ * @example
+ * await fetchApi("/serving-endpoints");
+ *
+ * await fetchApi(["/serving-endpoints", endpointName, "invocations"], {
+ *   body: JSON.stringify({ inputs: [...] }),
+ *   headers: { "Content-Type": "application/json" },
+ * });
+ *
+ * await fetchApi("/serving-endpoints", undefined,
+ *   { options: { ttl: 300 } }
+ * );
+ */
+export declare function fetchApi<T>(target: URL | string[] | string, init?: ApiRequestInit): Promise<T>;
+export type ContextLike = Context | AbortSignal;
+/** Wrap a `Context` (returned as-is) or `AbortSignal` (adapted) as an SDK `Context`. */
+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;
+export {};

package/dist/src/api.js

@@ -0,0 +1,165 @@
+import { Context } from "@databricks/sdk-experimental";
+import { CacheManager, getExecutionContext } from "@databricks/appkit";
+// Direct imports (not via the barrel). The package's NodeNext
+// module resolution wants explicit `.js` extensions on relative
+// imports, and reaching for `commonUtils` / `netUtils` through
+// `../index.client` confused the `noEmit` typecheck with a
+// missing-extension error. Direct sibling imports stay typed and
+// don't risk a future cycle.
+import { fnvHash, tieAbortSignal } from "./common.js";
+import { joinUrl, parseUrl } from "./net.browser.js";
+// ────────────────────────────────────────────────────────────────
+// Constants
+// ────────────────────────────────────────────────────────────────
+const API_PREFIX = "/api/2.0";
+/**
+ * Build the absolute `URL` for a Databricks workspace REST endpoint
+ * without issuing a request. Mirrors {@link fetchApi}'s path handling
+ * (single string or array of segments, leading `/api/2.0` stripped)
+ * so callers can construct request URLs that match what `fetchApi`
+ * would have used. Resolves the host from the supplied
+ * `WorkspaceClient` or, when omitted, from the active
+ * `getExecutionContext().client`.
+ */
+export async function apiUrl(path, workspaceClient) {
+    let joinedPath = joinUrl(path);
+    if (joinedPath === API_PREFIX || joinedPath.startsWith(API_PREFIX + "/")) {
+        joinedPath = joinedPath.slice(API_PREFIX.length);
+    }
+    if (!joinedPath) {
+        throw new Error(`Invalid path: ${path}`);
+    }
+    const client = workspaceClient ?? getExecutionContext().client;
+    const config = client.config;
+    const host = await config.getHost();
+    const url = parseUrl(host, API_PREFIX, joinedPath);
+    return url;
+}
+/**
+ * Issue an authenticated request against a Databricks workspace REST
+ * endpoint, resolving the host from the supplied `WorkspaceClient`
+ * and stamping the OAuth/PAT auth header in for you. The response
+ * body is returned parsed as JSON.
+ *
+ * `path` may be a single string or an array of segments. A leading
+ * `/api/2.0` is auto-stripped so callers can pass either style
+ * (`"/api/2.0/serving-endpoints"` or `"/serving-endpoints"`) without
+ * doubling it in the final URL.
+ *
+ * `init` is an optional WHATWG `RequestInit`. Useful fields:
+ *
+ *   - `body`: request payload. Strings / `Buffer` / `FormData` /
+ *     `URLSearchParams` pass through; for JSON, stringify the object
+ *     yourself and set `headers["Content-Type"] = "application/json"`.
+ *   - `headers`: extra request headers, merged in **before** the auth
+ *     header is applied so the workspace's `Authorization` always
+ *     wins on conflict.
+ *   - `method`: HTTP verb. If omitted, defaults to `POST` when
+ *     `init.body` is present and `GET` otherwise.
+ *
+ * `cache` is an optional handle to `CacheManager.getOrExecute`: pass
+ * `{ options: { ttl: 300 } }` for a per-user, time-boxed cache; the
+ * `userId` from the active execution context becomes part of the
+ * cache key by default.
+ *
+ * `workspaceClient` is optional; when omitted the request uses the
+ * caller's `getExecutionContext().client` (i.e. the per-request
+ * OBO client). Pass an explicit client for service-account work
+ * outside a request.
+ *
+ * @example
+ * await fetchApi("/serving-endpoints");
+ *
+ * await fetchApi(["/serving-endpoints", endpointName, "invocations"], {
+ *   body: JSON.stringify({ inputs: [...] }),
+ *   headers: { "Content-Type": "application/json" },
+ * });
+ *
+ * await fetchApi("/serving-endpoints", undefined,
+ *   { options: { ttl: 300 } }
+ * );
+ */
+export async function fetchApi(target, init) {
+    const client = init?.workspaceClient ?? getExecutionContext().client;
+    const config = client.config;
+    const url = target instanceof URL ? target : await apiUrl(target, client);
+    if (init?.cache) {
+        const { cache, ...executeInit } = init;
+        const executionContext = getExecutionContext();
+        const userId = "userId" in executionContext
+            ? executionContext.userId
+            : executionContext.serviceUserId;
+        const cacheInstance = await CacheManager.getInstance();
+        return cacheInstance.getOrExecute(cache.key ?? ["fetchApi", userId], async () => {
+            return fetchApi(url, { ...executeInit, workspaceClient: client });
+        }, cache.userKey ?? fnvHash(url.toString()), cache.options);
+    }
+    const headers = new Headers(init?.headers);
+    await config.authenticate(headers);
+    const method = init?.method?.toUpperCase() ?? (init?.body ? "POST" : "GET");
+    const response = await fetch(url.toString(), {
+        ...init,
+        method,
+        headers,
+    });
+    return response.json();
+}
+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) {
+        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".
+ *
+ * Kept private for now: the genie package is the only consumer in
+ * the workspace. Lift to `@dbx-tools/shared` (`apiUtils`) the
+ * moment a second package needs SDK-call cancellation.
+ */
+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 {@link 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));
+}

package/dist/src/appkit.d.ts

@@ -0,0 +1,59 @@
+import type { NameLike } from "./common.js";
+export interface PluginContextLike {
+    getPlugins(): ReadonlyMap<string, unknown>;
+}
+type PluginData = {
+    plugin: abstract new (...args: never[]) => unknown;
+    name: string;
+};
+type PluginDataFactory = (...args: never[]) => PluginData;
+type PluginInstanceOf<F extends PluginDataFactory> = InstanceType<ReturnType<F>["plugin"]>;
+/**
+ * Returns the static `{ plugin, name }` descriptor for an AppKit plugin
+ * factory, caching per factory so repeated lookups do not allocate.
+ */
+export declare function data<F extends PluginDataFactory, D extends ReturnType<F>>(factory: F): D;
+/**
+ * Look up a sibling plugin instance from the AppKit plugin context,
+ * keyed off the factory's registered name and typed via its plugin
+ * class.
+ *
+ * Returns `undefined` when the context is missing or the plugin is not
+ * registered. For required siblings prefer {@link require}.
+ *
+ * @example
+ * ```ts
+ * import { lakebase } from "@databricks/appkit";
+ * import { appkitUtils } from "@dbx-tools/shared";
+ *
+ * const lake = appkitUtils.instance(this.context, lakebase);
+ * //    ^^ inferred as LakebasePlugin | undefined
+ * lake?.exports().pool;
+ * ```
+ */
+export declare function instance<F extends PluginDataFactory>(ctx: PluginContextLike | undefined, factory: F): PluginInstanceOf<F> | undefined;
+/**
+ * Like {@link instance} but throws when the plugin is not registered.
+ * Use for siblings whose absence is a wiring bug rather than a runtime
+ * condition (e.g. requiring `lakebase` when the caller has `storage` /
+ * `memory` enabled).
+ *
+ * `caller` is prepended to the error message so cross-plugin failures
+ * are easy to attribute in logs.
+ *
+ * Always accessed through the namespace as `appkitUtils.require(...)`;
+ * the bare identifier is legal here because this package is pure ESM.
+ *
+ * @example
+ * ```ts
+ * import { lakebase } from "@databricks/appkit";
+ * import { appkitUtils } from "@dbx-tools/shared";
+ *
+ * const pool = appkitUtils.require(this.context, lakebase, "mastra")
+ *   .exports().pool;
+ * ```
+ */
+export declare function require<F extends PluginDataFactory>(ctx: PluginContextLike | undefined, factory: F, caller?: NameLike | string): PluginInstanceOf<F>;
+export declare function isInitialized(): boolean;
+export declare function ensureInitialized(): Promise<void>;
+export {};