refactor(shared): relocate the Databricks SDK facade to shared

biome.json

@@ -53,7 +53,7 @@
                   "@databricks/sdk-experimental",
                   "@databricks/sdk-experimental/**"
                 ],
-                "message": "Import the Databricks SDK only through the wrapper in packages/appkit/src/workspace-client. Add a re-export there if you need a new symbol."
+                "message": "Import the Databricks SDK only through the wrapper in packages/shared/src/workspace-client. Add a re-export there if you need a new symbol."
               }
             ]
           }
@@ -77,7 +77,7 @@
   "overrides": [
     {
       "includes": [
-        "packages/appkit/src/workspace-client/**",
+        "packages/shared/src/workspace-client/**",
         "packages/lakebase/**"
       ],
       "linter": {

docs/docusaurus.config.ts

@@ -1,16 +1,27 @@
+import { builtinModules } from "node:module";
 import path from "node:path";
 import type * as Preset from "@docusaurus/preset-classic";
 import type { Config } from "@docusaurus/types";
 import type { PluginOptions } from "@signalwire/docusaurus-plugin-llms-txt/public";
 import { themes as prismThemes } from "prism-react-renderer";
 import webpack from "webpack";
 
+// appkit is a Node/server package; the docs only reference its API (they never
+// execute the SDK in the browser). Stub every Node built-in for the client
+// bundle so webpack doesn't try to bundle `@databricks/sdk-experimental`'s
+// Node deps (fs, crypto, stream, …). `fallback` only triggers when a module is
+// unresolvable, so it's a no-op for the Node-target server bundle.
+const nodeBuiltinFallbacks = Object.fromEntries(
+  builtinModules.map((m) => [m, false]),
+) as Record<string, false>;
+
 function appKitAliasPlugin() {
   return {
     name: "appkit-aliases",
     configureWebpack() {
       return {
         resolve: {
+          fallback: nodeBuiltinFallbacks,
           alias: {
             "@": path.resolve(__dirname, "../packages/appkit-ui/src"),
             shared: path.resolve(__dirname, "../packages/shared/src"),
@@ -34,6 +45,11 @@ function appKitAliasPlugin() {
             "import.meta.env.DEV": JSON.stringify(false),
             "import.meta.hot": JSON.stringify(undefined),
           }),
+          // Rewrite `node:fs` → `fs` so scheme imports fall through to the
+          // built-in fallbacks above instead of erroring as unhandled schemes.
+          new webpack.NormalModuleReplacementPlugin(/^node:/, (resource) => {
+            resource.request = resource.request.replace(/^node:/, "");
+          }),
         ],
       };
     },

packages/appkit/package.json

@@ -61,7 +61,6 @@
   "dependencies": {
     "@ast-grep/napi": "0.37.0",
     "@databricks/lakebase": "workspace:*",
-    "@databricks/sdk-experimental": "0.17.0",
     "@opentelemetry/api": "1.9.0",
     "@opentelemetry/api-logs": "0.219.0",
     "@opentelemetry/auto-instrumentations-node": "0.77.0",

packages/appkit/src/workspace-client/index.ts

@@ -4,26 +4,24 @@
  * to `./legacy.ts` so services can migrate to the modular SDK incrementally
  * behind a stable facade.
  */
-export { ApiError } from "./errors";
-export { createWorkspaceClient } from "./factory";
-export type {
-  CancellationToken,
-  ClientOptions,
-  GenieMessage,
-  Waiter,
-  WorkspaceClientOptions,
-} from "./legacy";
-// SDK value + type re-exports so AppKit modules import them from the wrapper.
+
 export {
+  ApiError,
   ConfigError,
   Context,
+  createWorkspaceClient,
   Time,
   TimeUnits,
-} from "./legacy";
+} from "shared";
 export type {
+  CancellationToken,
+  ClientOptions,
   files,
+  GenieMessage,
   jobs,
   serving,
   sql,
+  Waiter,
   WorkspaceClient,
-} from "./types";
+  WorkspaceClientOptions,
+} from "shared/workspace-client";

packages/shared/package.json

@@ -15,6 +15,10 @@
       "development": "./src/cli/index.ts",
       "default": "./dist/cli/index.js"
     },
+    "./workspace-client": {
+      "development": "./src/workspace-client/index.ts",
+      "default": "./dist/workspace-client/index.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -36,13 +40,15 @@
     "exports": {
       ".": "./dist/index.js",
       "./cli": "./dist/cli/index.js",
+      "./workspace-client": "./dist/workspace-client/index.js",
       "./package.json": "./package.json"
     }
   },
   "dependencies": {
     "@ast-grep/napi": "0.37.0",
-    "@standard-schema/spec": "1.1.0",
     "@clack/prompts": "1.0.1",
+    "@databricks/sdk-experimental": "0.17.0",
+    "@standard-schema/spec": "1.1.0",
     "commander": "12.1.0",
     "dotenv": "16.6.1",
     "js-yaml": "4.2.0",

packages/shared/src/index.ts

@@ -8,3 +8,16 @@ export * from "./plugin";
 export * from "./sql";
 export * from "./sse/analytics";
 export * from "./tunnel";
+// Re-export the workspace-client's runtime *values* from the root so AppKit
+// (and other consumers) reach them via `shared` — the import style the bundler
+// inlines. Only values: the SDK `sql` type would collide with the `sql` query
+// helper from `./sql`, so workspace-client types stay on `shared/workspace-client`
+// (type-only imports carry no runtime cost).
+export {
+  ApiError,
+  ConfigError,
+  Context,
+  createWorkspaceClient,
+  Time,
+  TimeUnits,
+} from "./workspace-client";

packages/shared/src/workspace-client/index.ts

@@ -0,0 +1,30 @@
+/**
+ * AppKit workspace-client wrapper — the single entry point every AppKit module
+ * uses to reach a Databricks SDK client. Isolates `@databricks/sdk-experimental`
+ * to `./legacy.ts` so services can migrate to the modular SDK incrementally
+ * behind a stable facade.
+ */
+export { ApiError } from "./errors";
+export { createWorkspaceClient } from "./factory";
+export type {
+  CancellationToken,
+  ClientOptions,
+  GenieMessage,
+  LegacyWorkspaceClient,
+  Waiter,
+  WorkspaceClientOptions,
+} from "./legacy";
+// SDK value + type re-exports so AppKit modules import them from the wrapper.
+export {
+  ConfigError,
+  Context,
+  Time,
+  TimeUnits,
+} from "./legacy";
+export type {
+  files,
+  jobs,
+  serving,
+  sql,
+  WorkspaceClient,
+} from "./types";

packages/appkit/src/workspace-client/legacy.ts → packages/shared/src/workspace-client/legacy.ts

@@ -29,6 +29,8 @@ export type LegacyWorkspaceClient = SdkWorkspaceClient;
 export interface WorkspaceClientOptions {
   /** Databricks host, e.g. https://my-workspace.cloud.databricks.com. Defaults to DATABRICKS_HOST / profile resolution. */
   host?: string;
+  /** `~/.databrickscfg` profile name. Used when no host/token is provided. */
+  profile?: string;
   /** Bearer token. When set, `authType` defaults to "pat". */
   token?: string;
   /** Authentication strategy passed to the legacy client. */
@@ -60,7 +62,9 @@ export function buildLegacyWorkspaceClient(
       ? { host: opts.host, token: opts.token, authType: opts.authType ?? "pat" }
       : opts.host
         ? { host: opts.host }
-        : {};
+        : opts.profile
+          ? { profile: opts.profile }
+          : {};
   return new SdkWorkspaceClientCtor(cfg, opts.clientOptions);
 }
 

packages/shared/tsdown.config.ts

@@ -2,7 +2,7 @@ import { defineConfig } from "tsdown";
 
 export default defineConfig({
   name: "shared",
-  entry: ["src/index.ts", "src/cli/index.ts"],
+  entry: ["src/index.ts", "src/cli/index.ts", "src/workspace-client/index.ts"],
   outDir: "dist",
   minify: false,
   format: "esm",