@dbx-tools/shared 0.1.18

package/index.client.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/index.ts

@@ -0,0 +1,26 @@
+/**
+ * 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/package.json

@@ -0,0 +1,54 @@
+{
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "browser": {
+        "types": "./dist/index.client.d.ts",
+        "default": "./dist/index.client.js"
+      },
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "source": {
+        "browser": "./index.client.ts",
+        "default": "./index.ts"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "name": "@dbx-tools/shared",
+  "version": "0.1.18",
+  "dependencies": {
+    "fast-deep-equal": "^3.1.3",
+    "lru-cache": "^11.5.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@databricks/sdk-experimental": "^0.17"
+  },
+  "module": "index.ts",
+  "peerDependencies": {
+    "@databricks/appkit": "*"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "index*.ts",
+    "src"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/reggie-db/dbx-tools-appkit#readme",
+  "bugs": {
+    "url": "https://github.com/reggie-db/dbx-tools-appkit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools-appkit.git",
+    "directory": "packages/shared"
+  }
+}

package/src/api.ts

@@ -0,0 +1,222 @@
+import type { CancellationToken, WorkspaceClient } from "@databricks/sdk-experimental";
+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";
+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 async function apiUrl(
+  path: string[] | string,
+  workspaceClient?: WorkspaceClient,
+): Promise<URL> {
+  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<T>(
+  target: URL | string[] | string,
+  init?: ApiRequestInit,
+): Promise<T> {
+  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() as Promise<T>;
+}
+
+export type ContextLike = Context | AbortSignal;
+
+/** Wrap a `Context` (returned as-is) or `AbortSignal` (adapted) as an SDK `Context`. */
+export 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 function toContext(controller: AbortController, input?: ContextLike): Context;
+export function toContext(
+  source: AbortController | ContextLike,
+  input?: ContextLike,
+): Context {
+  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: AbortSignal): CancellationToken {
+  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: AbortController,
+  token: CancellationToken,
+): void {
+  if (token.isCancellationRequested) {
+    controller.abort();
+    return;
+  }
+  token.onCancellationRequested((reason) => controller.abort(reason));
+}

package/src/appkit.ts

@@ -0,0 +1,161 @@
+// Helpers for working with the AppKit plugin context (`this.context` on
+// any class that extends `Plugin` from `@databricks/appkit`).
+//
+// Why these live here instead of in `@databricks/appkit`: AppKit exposes
+// `this.context.getPlugins()`, which returns
+// `ReadonlyMap<string, BasePlugin>`, but provides no typed lookup
+// helper. Every caller ends up writing the same
+// `as InstanceType<ReturnType<typeof someFactory>["plugin"]>` cast.
+// These wrappers absorb that boilerplate.
+//
+// API shape: pass the plugin's factory (`lakebase`, `serving`, `genie`,
+// or any `toPlugin(...)` result) directly. TypeScript infers both the
+// instance type (so `.exports()` resolves) and the registered name (so
+// the runtime lookup works) from that single value. No `<T>` annotation
+// or string literal needed at the call site.
+
+import {
+  CacheManager,
+  createApp,
+  getExecutionContext,
+  InitializationError,
+} from "@databricks/appkit";
+import type { NameLike } from "./common.js";
+import { memoize } from "./common.js";
+
+// Minimal structural shape of `this.context`. We mirror only the method
+// we touch instead of depending on AppKit's `PluginContext` type, which
+// is not part of the package's `exports` map and therefore cannot be
+// imported. Any compatible object (real `PluginContext`, mocks, tests)
+// satisfies this shape.
+export interface PluginContextLike {
+  getPlugins(): ReadonlyMap<string, unknown>;
+}
+
+type PluginData = {
+  plugin: abstract new (...args: never[]) => unknown;
+  name: string;
+};
+
+// Structural shape of an AppKit plugin factory (the result of
+// `toPlugin(SomePluginClass)`). Calling it returns a `PluginData` tuple
+// whose `plugin` field is the *class constructor* and whose `name`
+// field carries the registered plugin name as a literal string.
+//
+// Defined structurally so we don't pull `@databricks/appkit` into this
+// package as a runtime or type dependency. Any function returning the
+// same shape (e.g. `lakebase`, `serving`, `genie`, or a user-defined
+// `toPlugin(MyPlugin)`) satisfies the bound.
+type PluginDataFactory = (...args: never[]) => PluginData;
+
+// Maps a plugin factory back to the *instance* type of its plugin
+// class. Mirrors the inline pattern users would otherwise write:
+// `InstanceType<ReturnType<typeof factory>["plugin"]>`.
+type PluginInstanceOf<F extends PluginDataFactory> = InstanceType<
+  ReturnType<F>["plugin"]
+>;
+
+// Registry name returned by `factory().name`, keyed by the factory
+// function. Typical AppKit factories return stable metadata; caching
+// avoids invoking `factory()` on every sibling lookup (which would
+// allocate a fresh descriptor tuple each time).
+const dataCache = new WeakMap<PluginDataFactory, PluginData>();
+
+/**
+ * Returns the static `{ plugin, name }` descriptor for an AppKit plugin
+ * factory, caching per factory so repeated lookups do not allocate.
+ */
+export function data<F extends PluginDataFactory, D extends ReturnType<F>>(
+  factory: F,
+): D {
+  const cached = dataCache.get(factory);
+  if (cached !== undefined) {
+    return cached as D;
+  }
+  const result = factory();
+  dataCache.set(factory, result);
+  return result as 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 function instance<F extends PluginDataFactory>(
+  ctx: PluginContextLike | undefined,
+  factory: F,
+): PluginInstanceOf<F> | undefined {
+  if (!ctx) return undefined;
+  const name = data(factory).name;
+  return ctx.getPlugins().get(name) as 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 function require<F extends PluginDataFactory>(
+  ctx: PluginContextLike | undefined,
+  factory: F,
+  caller?: NameLike | string,
+): PluginInstanceOf<F> {
+  const plugin = instance(ctx, factory);
+  if (plugin) return plugin;
+  const prefix =
+    typeof caller === "string" ? `${caller}: ` : caller?.name ? `${caller.name}: ` : "";
+  const registeredName = data(factory).name;
+  throw new Error(`${prefix}required plugin not registered: ${registeredName}`);
+}
+
+export function isInitialized(): boolean {
+  try {
+    const ctx = getExecutionContext();
+    if (ctx?.client) {
+      return true;
+    }
+  } catch (error) {
+    if (!(error instanceof InitializationError)) {
+      throw error;
+    }
+  }
+  return false;
+}
+
+export async function ensureInitialized() {
+  if (!isInitialized()) {
+    await createApp({
+      plugins: [],
+    });
+  }
+}