@databricks/appkit 0.22.0 → 0.23.0

package/dist/type-generator/serving/generator.js

@@ -0,0 +1,185 @@
+import { createLogger } from "../../logging/logger.js";
+import { CACHE_VERSION, hashSchema, loadServingCache, saveServingCache } from "./cache.js";
+import { convertRequestSchema, convertResponseSchema, deriveChunkType, extractRequestKeys } from "./converter.js";
+import { fetchOpenApiSchema } from "./fetcher.js";
+import { WorkspaceClient } from "@databricks/sdk-experimental";
+import fs from "node:fs/promises";
+import pc from "picocolors";
+
+//#region src/type-generator/serving/generator.ts
+const logger = createLogger("type-generator:serving");
+const GENERIC_REQUEST = "Record<string, unknown>";
+const GENERIC_RESPONSE = "unknown";
+const GENERIC_CHUNK = "unknown";
+/**
+* Generates TypeScript type declarations for serving endpoints
+* by fetching their OpenAPI schemas and converting to TypeScript.
+*/
+async function generateServingTypes(options) {
+	const { outFile, noCache } = options;
+	const endpoints = options.endpoints ?? resolveDefaultEndpoints();
+	if (Object.keys(endpoints).length === 0) {
+		logger.debug("No serving endpoints configured, skipping type generation");
+		return;
+	}
+	const startTime = performance.now();
+	const cache = noCache ? {
+		version: CACHE_VERSION,
+		endpoints: {}
+	} : await loadServingCache();
+	let client;
+	let updated = false;
+	const registryEntries = [];
+	const logEntries = [];
+	for (const [alias, config] of Object.entries(endpoints)) {
+		client ??= new WorkspaceClient({});
+		const result = await processEndpoint(alias, config, client, cache);
+		if (result.cacheUpdated) updated = true;
+		registryEntries.push(result.entry);
+		logEntries.push(result.log);
+	}
+	printLogTable(logEntries, startTime);
+	const output = generateTypeDeclarations(registryEntries);
+	await fs.writeFile(outFile, output, "utf-8");
+	if (registryEntries.length === 0) logger.debug("Wrote empty serving types to %s (no endpoints resolved)", outFile);
+	else logger.debug("Wrote serving types to %s", outFile);
+	if (updated) await saveServingCache(cache);
+}
+function genericEntry(alias) {
+	return buildRegistryEntry(alias, GENERIC_REQUEST, GENERIC_RESPONSE, GENERIC_CHUNK);
+}
+async function processEndpoint(alias, config, client, cache) {
+	const endpointName = process.env[config.env];
+	if (!endpointName) return {
+		entry: genericEntry(alias),
+		log: {
+			alias,
+			status: "MISS",
+			error: `env ${config.env} not set`
+		},
+		cacheUpdated: false
+	};
+	const result = await fetchOpenApiSchema(client, endpointName, config.servedModel);
+	if (!result) return {
+		entry: genericEntry(alias),
+		log: {
+			alias,
+			status: "MISS",
+			error: "schema fetch failed"
+		},
+		cacheUpdated: false
+	};
+	const { spec, pathKey } = result;
+	const hash = hashSchema(JSON.stringify(spec));
+	const cached = cache.endpoints[alias];
+	if (cached && cached.hash === hash) return {
+		entry: buildRegistryEntry(alias, cached.requestType, cached.responseType, cached.chunkType),
+		log: {
+			alias,
+			status: "HIT"
+		},
+		cacheUpdated: false
+	};
+	const operation = spec.paths[pathKey]?.post;
+	if (!operation) return {
+		entry: genericEntry(alias),
+		log: {
+			alias,
+			status: "MISS",
+			error: "no POST operation"
+		},
+		cacheUpdated: false
+	};
+	try {
+		const requestType = convertRequestSchema(operation);
+		const responseType = convertResponseSchema(operation);
+		const chunkType = deriveChunkType(operation);
+		const requestKeys = extractRequestKeys(operation);
+		cache.endpoints[alias] = {
+			hash,
+			requestType,
+			responseType,
+			chunkType,
+			requestKeys
+		};
+		return {
+			entry: buildRegistryEntry(alias, requestType, responseType, chunkType),
+			log: {
+				alias,
+				status: "MISS"
+			},
+			cacheUpdated: true
+		};
+	} catch (convErr) {
+		logger.warn("Schema conversion failed for '%s': %s", alias, convErr.message);
+		return {
+			entry: genericEntry(alias),
+			log: {
+				alias,
+				status: "MISS",
+				error: "schema conversion failed"
+			},
+			cacheUpdated: false
+		};
+	}
+}
+function printLogTable(logEntries, startTime) {
+	if (logEntries.length === 0) return;
+	const maxNameLen = Math.max(...logEntries.map((e) => e.alias.length));
+	const separator = pc.dim("─".repeat(50));
+	console.log("");
+	console.log(`  ${pc.bold("Typegen Serving")} ${pc.dim(`(${logEntries.length})`)}`);
+	console.log(`  ${separator}`);
+	for (const entry of logEntries) {
+		const tag = entry.status === "HIT" ? `cache ${pc.bold(pc.green("HIT  "))}` : `cache ${pc.bold(pc.yellow("MISS "))}`;
+		const rawName = entry.alias.padEnd(maxNameLen);
+		const reason = entry.error ? `  ${pc.dim(entry.error)}` : "";
+		console.log(`  ${tag}  ${rawName}${reason}`);
+	}
+	const elapsed = ((performance.now() - startTime) / 1e3).toFixed(2);
+	const newCount = logEntries.filter((e) => e.status === "MISS").length;
+	const cacheCount = logEntries.filter((e) => e.status === "HIT").length;
+	console.log(`  ${separator}`);
+	console.log(`  ${newCount} new, ${cacheCount} from cache. ${pc.dim(`${elapsed}s`)}`);
+	console.log("");
+}
+function resolveDefaultEndpoints() {
+	if (process.env.DATABRICKS_SERVING_ENDPOINT_NAME) return { default: { env: "DATABRICKS_SERVING_ENDPOINT_NAME" } };
+	return {};
+}
+function buildRegistryEntry(alias, requestType, responseType, chunkType) {
+	const indent = "      ";
+	const chunkEntry = chunkType ? chunkType : "unknown";
+	return `    ${alias}: {
+${indent}request: ${indentType(requestType, indent)};
+${indent}response: ${indentType(responseType, indent)};
+${indent}chunk: ${indentType(chunkEntry, indent)};
+    };`;
+}
+function indentType(typeStr, baseIndent) {
+	if (!typeStr.includes("\n")) return typeStr;
+	return typeStr.split("\n").map((line, i) => i === 0 ? line : `${baseIndent}${line}`).join("\n");
+}
+function generateTypeDeclarations(entries) {
+	return `// Auto-generated by AppKit - DO NOT EDIT
+// Generated from serving endpoint OpenAPI schemas
+import "@databricks/appkit";
+import "@databricks/appkit-ui/react";
+
+declare module "@databricks/appkit" {
+  interface ServingEndpointRegistry {
+${entries.join("\n")}
+  }
+}
+
+declare module "@databricks/appkit-ui/react" {
+  interface ServingEndpointRegistry {
+${entries.join("\n")}
+  }
+}
+`;
+}
+
+//#endregion
+export { generateServingTypes };
+//# sourceMappingURL=generator.js.map

package/dist/type-generator/serving/generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.js","names":[],"sources":["../../../src/type-generator/serving/generator.ts"],"sourcesContent":["import fs from \"node:fs/promises\";\nimport { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport pc from \"picocolors\";\nimport { createLogger } from \"../../logging/logger\";\nimport type { EndpointConfig } from \"../../plugins/serving/types\";\nimport {\n  CACHE_VERSION,\n  hashSchema,\n  loadServingCache,\n  type ServingCache,\n  saveServingCache,\n} from \"./cache\";\nimport {\n  convertRequestSchema,\n  convertResponseSchema,\n  deriveChunkType,\n  extractRequestKeys,\n} from \"./converter\";\nimport { fetchOpenApiSchema } from \"./fetcher\";\n\nconst logger = createLogger(\"type-generator:serving\");\n\nconst GENERIC_REQUEST = \"Record<string, unknown>\";\nconst GENERIC_RESPONSE = \"unknown\";\nconst GENERIC_CHUNK = \"unknown\";\n\ninterface GenerateServingTypesOptions {\n  outFile: string;\n  endpoints?: Record<string, EndpointConfig>;\n  noCache?: boolean;\n}\n\n/**\n * Generates TypeScript type declarations for serving endpoints\n * by fetching their OpenAPI schemas and converting to TypeScript.\n */\nexport async function generateServingTypes(\n  options: GenerateServingTypesOptions,\n): Promise<void> {\n  const { outFile, noCache } = options;\n\n  // Resolve endpoints from config or env\n  const endpoints = options.endpoints ?? resolveDefaultEndpoints();\n  if (Object.keys(endpoints).length === 0) {\n    logger.debug(\"No serving endpoints configured, skipping type generation\");\n    return;\n  }\n\n  const startTime = performance.now();\n\n  const cache = noCache\n    ? { version: CACHE_VERSION, endpoints: {} }\n    : await loadServingCache();\n\n  let client: WorkspaceClient | undefined;\n  let updated = false;\n\n  const registryEntries: string[] = [];\n  const logEntries: Array<{\n    alias: string;\n    status: \"HIT\" | \"MISS\";\n    error?: string;\n  }> = [];\n\n  for (const [alias, config] of Object.entries(endpoints)) {\n    client ??= new WorkspaceClient({});\n    const result = await processEndpoint(alias, config, client, cache);\n    if (result.cacheUpdated) updated = true;\n    registryEntries.push(result.entry);\n    logEntries.push(result.log);\n  }\n\n  printLogTable(logEntries, startTime);\n\n  const output = generateTypeDeclarations(registryEntries);\n  await fs.writeFile(outFile, output, \"utf-8\");\n\n  if (registryEntries.length === 0) {\n    logger.debug(\n      \"Wrote empty serving types to %s (no endpoints resolved)\",\n      outFile,\n    );\n  } else {\n    logger.debug(\"Wrote serving types to %s\", outFile);\n  }\n\n  if (updated) {\n    await saveServingCache(cache as ServingCache);\n  }\n}\n\ninterface EndpointResult {\n  entry: string;\n  log: { alias: string; status: \"HIT\" | \"MISS\"; error?: string };\n  cacheUpdated: boolean;\n}\n\nfunction genericEntry(alias: string): string {\n  return buildRegistryEntry(\n    alias,\n    GENERIC_REQUEST,\n    GENERIC_RESPONSE,\n    GENERIC_CHUNK,\n  );\n}\n\nasync function processEndpoint(\n  alias: string,\n  config: EndpointConfig,\n  client: WorkspaceClient,\n  cache: { endpoints: Record<string, any> },\n): Promise<EndpointResult> {\n  const endpointName = process.env[config.env];\n  if (!endpointName) {\n    return {\n      entry: genericEntry(alias),\n      log: { alias, status: \"MISS\", error: `env ${config.env} not set` },\n      cacheUpdated: false,\n    };\n  }\n\n  const result = await fetchOpenApiSchema(\n    client,\n    endpointName,\n    config.servedModel,\n  );\n  if (!result) {\n    return {\n      entry: genericEntry(alias),\n      log: { alias, status: \"MISS\", error: \"schema fetch failed\" },\n      cacheUpdated: false,\n    };\n  }\n\n  const { spec, pathKey } = result;\n  const hash = hashSchema(JSON.stringify(spec));\n\n  // Cache hit\n  const cached = cache.endpoints[alias];\n  if (cached && cached.hash === hash) {\n    return {\n      entry: buildRegistryEntry(\n        alias,\n        cached.requestType,\n        cached.responseType,\n        cached.chunkType,\n      ),\n      log: { alias, status: \"HIT\" },\n      cacheUpdated: false,\n    };\n  }\n\n  // Cache miss — convert schema to types\n  const operation = spec.paths[pathKey]?.post;\n  if (!operation) {\n    return {\n      entry: genericEntry(alias),\n      log: { alias, status: \"MISS\", error: \"no POST operation\" },\n      cacheUpdated: false,\n    };\n  }\n\n  try {\n    const requestType = convertRequestSchema(operation);\n    const responseType = convertResponseSchema(operation);\n    const chunkType = deriveChunkType(operation);\n    const requestKeys = extractRequestKeys(operation);\n\n    cache.endpoints[alias] = {\n      hash,\n      requestType,\n      responseType,\n      chunkType,\n      requestKeys,\n    };\n\n    return {\n      entry: buildRegistryEntry(alias, requestType, responseType, chunkType),\n      log: { alias, status: \"MISS\" },\n      cacheUpdated: true,\n    };\n  } catch (convErr) {\n    logger.warn(\n      \"Schema conversion failed for '%s': %s\",\n      alias,\n      (convErr as Error).message,\n    );\n    return {\n      entry: genericEntry(alias),\n      log: { alias, status: \"MISS\", error: \"schema conversion failed\" },\n      cacheUpdated: false,\n    };\n  }\n}\n\nfunction printLogTable(\n  logEntries: Array<{ alias: string; status: \"HIT\" | \"MISS\"; error?: string }>,\n  startTime: number,\n): void {\n  if (logEntries.length === 0) return;\n\n  const maxNameLen = Math.max(...logEntries.map((e) => e.alias.length));\n  const separator = pc.dim(\"─\".repeat(50));\n  console.log(\"\");\n  console.log(\n    `  ${pc.bold(\"Typegen Serving\")} ${pc.dim(`(${logEntries.length})`)}`,\n  );\n  console.log(`  ${separator}`);\n  for (const entry of logEntries) {\n    const tag =\n      entry.status === \"HIT\"\n        ? `cache ${pc.bold(pc.green(\"HIT  \"))}`\n        : `cache ${pc.bold(pc.yellow(\"MISS \"))}`;\n    const rawName = entry.alias.padEnd(maxNameLen);\n    const reason = entry.error ? `  ${pc.dim(entry.error)}` : \"\";\n    console.log(`  ${tag}  ${rawName}${reason}`);\n  }\n  const elapsed = ((performance.now() - startTime) / 1000).toFixed(2);\n  const newCount = logEntries.filter((e) => e.status === \"MISS\").length;\n  const cacheCount = logEntries.filter((e) => e.status === \"HIT\").length;\n  console.log(`  ${separator}`);\n  console.log(\n    `  ${newCount} new, ${cacheCount} from cache. ${pc.dim(`${elapsed}s`)}`,\n  );\n  console.log(\"\");\n}\n\nfunction resolveDefaultEndpoints(): Record<string, EndpointConfig> {\n  if (process.env.DATABRICKS_SERVING_ENDPOINT_NAME) {\n    return { default: { env: \"DATABRICKS_SERVING_ENDPOINT_NAME\" } };\n  }\n  return {};\n}\n\nfunction buildRegistryEntry(\n  alias: string,\n  requestType: string,\n  responseType: string,\n  chunkType: string | null,\n): string {\n  const indent = \"      \";\n  const chunkEntry = chunkType ? chunkType : \"unknown\";\n  return `    ${alias}: {\n${indent}request: ${indentType(requestType, indent)};\n${indent}response: ${indentType(responseType, indent)};\n${indent}chunk: ${indentType(chunkEntry, indent)};\n    };`;\n}\n\nfunction indentType(typeStr: string, baseIndent: string): string {\n  if (!typeStr.includes(\"\\n\")) return typeStr;\n  return typeStr\n    .split(\"\\n\")\n    .map((line, i) => (i === 0 ? line : `${baseIndent}${line}`))\n    .join(\"\\n\");\n}\n\nfunction generateTypeDeclarations(entries: string[]): string {\n  return `// Auto-generated by AppKit - DO NOT EDIT\n// Generated from serving endpoint OpenAPI schemas\nimport \"@databricks/appkit\";\nimport \"@databricks/appkit-ui/react\";\n\ndeclare module \"@databricks/appkit\" {\n  interface ServingEndpointRegistry {\n${entries.join(\"\\n\")}\n  }\n}\n\ndeclare module \"@databricks/appkit-ui/react\" {\n  interface ServingEndpointRegistry {\n${entries.join(\"\\n\")}\n  }\n}\n`;\n}\n"],"mappings":"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"}

package/dist/type-generator/serving/server-file-extractor.d.ts

@@ -0,0 +1,22 @@
+import { EndpointConfig } from "../../plugins/serving/types.js";
+
+//#region src/type-generator/serving/server-file-extractor.d.ts
+/**
+ * Find the server entry file by checking candidate paths in order.
+ *
+ * @param basePath - Project root directory to search from
+ * @returns Absolute path to the server file, or null if none found
+ */
+declare function findServerFile(basePath: string): string | null;
+/**
+ * Extract serving endpoint config from a server file by AST-parsing it.
+ * Looks for `serving({ endpoints: { alias: { env: "..." }, ... } })` calls
+ * and extracts the endpoint alias names and their environment variable mappings.
+ *
+ * @param serverFilePath - Absolute path to the server entry file
+ * @returns Extracted endpoint config, or null if not found or not extractable
+ */
+declare function extractServingEndpoints(serverFilePath: string): Record<string, EndpointConfig> | null;
+//#endregion
+export { extractServingEndpoints, findServerFile };
+//# sourceMappingURL=server-file-extractor.d.ts.map

package/dist/type-generator/serving/server-file-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-file-extractor.d.ts","names":[],"sources":["../../../src/type-generator/serving/server-file-extractor.ts"],"mappings":";;;;;AAqBA;;;;iBAAgB,cAAA,CAAe,QAAA;AAkB/B;;;;;;;;AAAA,iBAAgB,uBAAA,CACd,cAAA,WACC,MAAA,SAAe,cAAA"}

package/dist/type-generator/serving/server-file-extractor.js

@@ -0,0 +1,131 @@
+import { createLogger } from "../../logging/logger.js";
+import path from "node:path";
+import fs from "node:fs";
+import { Lang, parse } from "@ast-grep/napi";
+
+//#region src/type-generator/serving/server-file-extractor.ts
+const logger = createLogger("type-generator:serving:extractor");
+/**
+* Candidate paths for the server entry file, relative to the project root.
+* Checked in order; the first that exists is used.
+* Same convention as plugin sync (sync.ts SERVER_FILE_CANDIDATES).
+*/
+const SERVER_FILE_CANDIDATES = ["server/index.ts", "server/server.ts"];
+/**
+* Find the server entry file by checking candidate paths in order.
+*
+* @param basePath - Project root directory to search from
+* @returns Absolute path to the server file, or null if none found
+*/
+function findServerFile(basePath) {
+	for (const candidate of SERVER_FILE_CANDIDATES) {
+		const fullPath = path.join(basePath, candidate);
+		if (fs.existsSync(fullPath)) return fullPath;
+	}
+	return null;
+}
+/**
+* Extract serving endpoint config from a server file by AST-parsing it.
+* Looks for `serving({ endpoints: { alias: { env: "..." }, ... } })` calls
+* and extracts the endpoint alias names and their environment variable mappings.
+*
+* @param serverFilePath - Absolute path to the server entry file
+* @returns Extracted endpoint config, or null if not found or not extractable
+*/
+function extractServingEndpoints(serverFilePath) {
+	let content;
+	try {
+		content = fs.readFileSync(serverFilePath, "utf-8");
+	} catch {
+		logger.debug("Could not read server file: %s", serverFilePath);
+		return null;
+	}
+	const servingCall = findServingCall(parse(serverFilePath.endsWith(".tsx") ? Lang.Tsx : Lang.TypeScript, content).root());
+	if (!servingCall) {
+		logger.debug("No serving() call found in %s", serverFilePath);
+		return null;
+	}
+	const args = servingCall.field("arguments");
+	if (!args) return null;
+	const configArg = args.children().find((child) => child.kind() === "object");
+	if (!configArg) return null;
+	const endpointsPair = findProperty(configArg, "endpoints");
+	if (!endpointsPair) return null;
+	const endpointsValue = getPropertyValue(endpointsPair);
+	if (!endpointsValue || endpointsValue.kind() !== "object") {
+		logger.debug("serving() endpoints is not an inline object literal in %s. Pass endpoints explicitly via appKitServingTypesPlugin({ endpoints }) in vite.config.ts.", serverFilePath);
+		return null;
+	}
+	const endpoints = {};
+	const pairs = endpointsValue.children().filter((child) => child.kind() === "pair");
+	for (const pair of pairs) {
+		const entry = extractEndpointEntry(pair);
+		if (entry) endpoints[entry.alias] = entry.config;
+	}
+	if (Object.keys(endpoints).length === 0) return null;
+	logger.debug("Extracted %d endpoint(s) from %s: %s", Object.keys(endpoints).length, serverFilePath, Object.keys(endpoints).join(", "));
+	return endpoints;
+}
+/**
+* Find the serving() call expression in the AST.
+* Looks for call expressions where the callee identifier is "serving".
+*/
+function findServingCall(root) {
+	const callExpressions = root.findAll({ rule: { kind: "call_expression" } });
+	for (const call of callExpressions) {
+		const callee = call.children()[0];
+		if (callee?.kind() === "identifier" && callee.text() === "serving") return call;
+	}
+	return null;
+}
+/**
+* Find a property (pair node) with the given key name in an object expression.
+*/
+function findProperty(objectNode, propertyName) {
+	const pairs = objectNode.children().filter((child) => child.kind() === "pair");
+	for (const pair of pairs) {
+		const key = pair.children()[0];
+		if (!key) continue;
+		if ((key.kind() === "property_identifier" ? key.text() : key.kind() === "string" ? key.text().replace(/^['"]|['"]$/g, "") : null) === propertyName) return pair;
+	}
+	return null;
+}
+/**
+* Get the value node from a pair (property: value).
+* The value is typically the last meaningful child after the colon.
+*/
+function getPropertyValue(pairNode) {
+	const children = pairNode.children();
+	return children.length >= 3 ? children[children.length - 1] : null;
+}
+/**
+* Extract a single endpoint entry from a pair node like:
+* `demo: { env: "DATABRICKS_SERVING_ENDPOINT_NAME", servedModel: "my-model" }`
+*/
+function extractEndpointEntry(pair) {
+	const children = pair.children();
+	if (children.length < 3) return null;
+	const keyNode = children[0];
+	const alias = keyNode.kind() === "property_identifier" ? keyNode.text() : keyNode.kind() === "string" ? keyNode.text().replace(/^['"]|['"]$/g, "") : null;
+	if (!alias) return null;
+	const valueNode = children[children.length - 1];
+	if (valueNode.kind() !== "object") return null;
+	const envPair = findProperty(valueNode, "env");
+	if (!envPair) return null;
+	const envValue = getPropertyValue(envPair);
+	if (!envValue || envValue.kind() !== "string") return null;
+	const config = { env: envValue.text().replace(/^['"]|['"]$/g, "") };
+	const servedModelPair = findProperty(valueNode, "servedModel");
+	if (servedModelPair) {
+		const servedModelValue = getPropertyValue(servedModelPair);
+		if (servedModelValue?.kind() === "string") config.servedModel = servedModelValue.text().replace(/^['"]|['"]$/g, "");
+	}
+	return {
+		alias,
+		config
+	};
+}
+
+//#endregion
+export { extractServingEndpoints, findServerFile };
+//# sourceMappingURL=server-file-extractor.js.map

package/dist/type-generator/serving/server-file-extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-file-extractor.js","names":[],"sources":["../../../src/type-generator/serving/server-file-extractor.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { Lang, parse, type SgNode } from \"@ast-grep/napi\";\nimport { createLogger } from \"../../logging/logger\";\nimport type { EndpointConfig } from \"../../plugins/serving/types\";\n\nconst logger = createLogger(\"type-generator:serving:extractor\");\n\n/**\n * Candidate paths for the server entry file, relative to the project root.\n * Checked in order; the first that exists is used.\n * Same convention as plugin sync (sync.ts SERVER_FILE_CANDIDATES).\n */\nconst SERVER_FILE_CANDIDATES = [\"server/index.ts\", \"server/server.ts\"];\n\n/**\n * Find the server entry file by checking candidate paths in order.\n *\n * @param basePath - Project root directory to search from\n * @returns Absolute path to the server file, or null if none found\n */\nexport function findServerFile(basePath: string): string | null {\n  for (const candidate of SERVER_FILE_CANDIDATES) {\n    const fullPath = path.join(basePath, candidate);\n    if (fs.existsSync(fullPath)) {\n      return fullPath;\n    }\n  }\n  return null;\n}\n\n/**\n * Extract serving endpoint config from a server file by AST-parsing it.\n * Looks for `serving({ endpoints: { alias: { env: \"...\" }, ... } })` calls\n * and extracts the endpoint alias names and their environment variable mappings.\n *\n * @param serverFilePath - Absolute path to the server entry file\n * @returns Extracted endpoint config, or null if not found or not extractable\n */\nexport function extractServingEndpoints(\n  serverFilePath: string,\n): Record<string, EndpointConfig> | null {\n  let content: string;\n  try {\n    content = fs.readFileSync(serverFilePath, \"utf-8\");\n  } catch {\n    logger.debug(\"Could not read server file: %s\", serverFilePath);\n    return null;\n  }\n\n  const lang = serverFilePath.endsWith(\".tsx\") ? Lang.Tsx : Lang.TypeScript;\n  const ast = parse(lang, content);\n  const root = ast.root();\n\n  // Find serving(...) call expressions\n  const servingCall = findServingCall(root);\n  if (!servingCall) {\n    logger.debug(\"No serving() call found in %s\", serverFilePath);\n    return null;\n  }\n\n  // Get the first argument (the config object)\n  const args = servingCall.field(\"arguments\");\n  if (!args) {\n    return null;\n  }\n\n  const configArg = args.children().find((child) => child.kind() === \"object\");\n  if (!configArg) {\n    // serving() called with no args or non-object arg\n    return null;\n  }\n\n  // Find the \"endpoints\" property in the config object\n  const endpointsPair = findProperty(configArg, \"endpoints\");\n  if (!endpointsPair) {\n    // Config object has no \"endpoints\" property (e.g. serving({ timeout: 5000 }))\n    return null;\n  }\n\n  // Get the value of the endpoints property\n  const endpointsValue = getPropertyValue(endpointsPair);\n  if (!endpointsValue || endpointsValue.kind() !== \"object\") {\n    // endpoints is a variable reference, not an inline object\n    logger.debug(\n      \"serving() endpoints is not an inline object literal in %s. \" +\n        \"Pass endpoints explicitly via appKitServingTypesPlugin({ endpoints }) in vite.config.ts.\",\n      serverFilePath,\n    );\n    return null;\n  }\n\n  // Extract each endpoint entry\n  const endpoints: Record<string, EndpointConfig> = {};\n  const pairs = endpointsValue\n    .children()\n    .filter((child) => child.kind() === \"pair\");\n\n  for (const pair of pairs) {\n    const entry = extractEndpointEntry(pair);\n    if (entry) {\n      endpoints[entry.alias] = entry.config;\n    }\n  }\n\n  if (Object.keys(endpoints).length === 0) {\n    return null;\n  }\n\n  logger.debug(\n    \"Extracted %d endpoint(s) from %s: %s\",\n    Object.keys(endpoints).length,\n    serverFilePath,\n    Object.keys(endpoints).join(\", \"),\n  );\n\n  return endpoints;\n}\n\n/**\n * Find the serving() call expression in the AST.\n * Looks for call expressions where the callee identifier is \"serving\".\n */\nfunction findServingCall(root: SgNode): SgNode | null {\n  const callExpressions = root.findAll({\n    rule: { kind: \"call_expression\" },\n  });\n\n  for (const call of callExpressions) {\n    const callee = call.children()[0];\n    if (callee?.kind() === \"identifier\" && callee.text() === \"serving\") {\n      return call;\n    }\n  }\n\n  return null;\n}\n\n/**\n * Find a property (pair node) with the given key name in an object expression.\n */\nfunction findProperty(objectNode: SgNode, propertyName: string): SgNode | null {\n  const pairs = objectNode\n    .children()\n    .filter((child) => child.kind() === \"pair\");\n\n  for (const pair of pairs) {\n    const key = pair.children()[0];\n    if (!key) continue;\n\n    const keyText =\n      key.kind() === \"property_identifier\"\n        ? key.text()\n        : key.kind() === \"string\"\n          ? key.text().replace(/^['\"]|['\"]$/g, \"\")\n          : null;\n\n    if (keyText === propertyName) {\n      return pair;\n    }\n  }\n\n  return null;\n}\n\n/**\n * Get the value node from a pair (property: value).\n * The value is typically the last meaningful child after the colon.\n */\nfunction getPropertyValue(pairNode: SgNode): SgNode | null {\n  const children = pairNode.children();\n  // pair children: [key, \":\", value]\n  return children.length >= 3 ? children[children.length - 1] : null;\n}\n\n/**\n * Extract a single endpoint entry from a pair node like:\n * `demo: { env: \"DATABRICKS_SERVING_ENDPOINT_NAME\", servedModel: \"my-model\" }`\n */\nfunction extractEndpointEntry(\n  pair: SgNode,\n): { alias: string; config: EndpointConfig } | null {\n  const children = pair.children();\n  if (children.length < 3) return null;\n\n  // Get alias name (the key)\n  const keyNode = children[0];\n  const alias =\n    keyNode.kind() === \"property_identifier\"\n      ? keyNode.text()\n      : keyNode.kind() === \"string\"\n        ? keyNode.text().replace(/^['\"]|['\"]$/g, \"\")\n        : null;\n\n  if (!alias) return null;\n\n  // Get the value (should be an object like { env: \"...\" })\n  const valueNode = children[children.length - 1];\n  if (valueNode.kind() !== \"object\") return null;\n\n  // Extract env field\n  const envPair = findProperty(valueNode, \"env\");\n  if (!envPair) return null;\n\n  const envValue = getPropertyValue(envPair);\n  if (!envValue || envValue.kind() !== \"string\") return null;\n\n  const env = envValue.text().replace(/^['\"]|['\"]$/g, \"\");\n\n  // Extract optional servedModel field\n  const config: EndpointConfig = { env };\n  const servedModelPair = findProperty(valueNode, \"servedModel\");\n  if (servedModelPair) {\n    const servedModelValue = getPropertyValue(servedModelPair);\n    if (servedModelValue?.kind() === \"string\") {\n      config.servedModel = servedModelValue.text().replace(/^['\"]|['\"]$/g, \"\");\n    }\n  }\n\n  return { alias, config };\n}\n"],"mappings":"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"}

package/dist/type-generator/serving/vite-plugin.d.ts

@@ -0,0 +1,24 @@
+import { EndpointConfig } from "../../plugins/serving/types.js";
+import { Plugin } from "vite";
+
+//#region src/type-generator/serving/vite-plugin.d.ts
+interface AppKitServingTypesPluginOptions {
+  /** Path to the output .d.ts file (relative to client root). Default: "src/appKitServingTypes.d.ts" */
+  outFile?: string;
+  /** Endpoint config override. If omitted, auto-discovers from the server file or falls back to DATABRICKS_SERVING_ENDPOINT_NAME env var. */
+  endpoints?: Record<string, EndpointConfig>;
+}
+/**
+ * Vite plugin to generate TypeScript types for AppKit serving endpoints.
+ * Fetches OpenAPI schemas from Databricks and generates a .d.ts with
+ * ServingEndpointRegistry module augmentation.
+ *
+ * Endpoint discovery order:
+ * 1. Explicit `endpoints` option (override)
+ * 2. AST extraction from server file (server/index.ts or server/server.ts)
+ * 3. DATABRICKS_SERVING_ENDPOINT_NAME env var (single default endpoint)
+ */
+declare function appKitServingTypesPlugin(options?: AppKitServingTypesPluginOptions): Plugin;
+//#endregion
+export { appKitServingTypesPlugin };
+//# sourceMappingURL=vite-plugin.d.ts.map

package/dist/type-generator/serving/vite-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-plugin.d.ts","names":[],"sources":["../../../src/type-generator/serving/vite-plugin.ts"],"mappings":";;;;UAYU,+BAAA;;EAER,OAAA;EAFuC;EAIvC,SAAA,GAAY,MAAA,SAAe,cAAA;AAAA;;;;;;;AAa7B;;;;iBAAgB,wBAAA,CACd,OAAA,GAAU,+BAAA,GACT,MAAA"}

package/dist/type-generator/serving/vite-plugin.js

@@ -0,0 +1,60 @@
+import { createLogger } from "../../logging/logger.js";
+import { generateServingTypes } from "../index.js";
+import { extractServingEndpoints, findServerFile } from "./server-file-extractor.js";
+import path from "node:path";
+
+//#region src/type-generator/serving/vite-plugin.ts
+const logger = createLogger("type-generator:serving:vite-plugin");
+/**
+* Vite plugin to generate TypeScript types for AppKit serving endpoints.
+* Fetches OpenAPI schemas from Databricks and generates a .d.ts with
+* ServingEndpointRegistry module augmentation.
+*
+* Endpoint discovery order:
+* 1. Explicit `endpoints` option (override)
+* 2. AST extraction from server file (server/index.ts or server/server.ts)
+* 3. DATABRICKS_SERVING_ENDPOINT_NAME env var (single default endpoint)
+*/
+function appKitServingTypesPlugin(options) {
+	let outFile;
+	let projectRoot;
+	async function generate() {
+		try {
+			let endpoints = options?.endpoints;
+			if (!endpoints) {
+				const serverFile = findServerFile(projectRoot);
+				if (serverFile) endpoints = extractServingEndpoints(serverFile) ?? void 0;
+			}
+			await generateServingTypes({
+				outFile,
+				endpoints,
+				noCache: false
+			});
+		} catch (error) {
+			if (process.env.NODE_ENV === "production") throw error;
+			logger.error("Error generating serving types: %O", error);
+		}
+	}
+	return {
+		name: "appkit-serving-types",
+		apply() {
+			if (options?.endpoints && Object.keys(options.endpoints).length > 0) return true;
+			if (process.env.DATABRICKS_SERVING_ENDPOINT_NAME) return true;
+			if (findServerFile(process.cwd())) return true;
+			if (findServerFile(path.resolve(process.cwd(), ".."))) return true;
+			logger.debug("No serving endpoints configured. Skipping type generation.");
+			return false;
+		},
+		configResolved(config) {
+			projectRoot = path.resolve(config.root, "..");
+			outFile = path.resolve(config.root, options?.outFile ?? "src/appKitServingTypes.d.ts");
+		},
+		async buildStart() {
+			await generate();
+		}
+	};
+}
+
+//#endregion
+export { appKitServingTypesPlugin };
+//# sourceMappingURL=vite-plugin.js.map

package/dist/type-generator/serving/vite-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-plugin.js","names":[],"sources":["../../../src/type-generator/serving/vite-plugin.ts"],"sourcesContent":["import path from \"node:path\";\nimport type { Plugin } from \"vite\";\nimport { createLogger } from \"../../logging/logger\";\nimport type { EndpointConfig } from \"../../plugins/serving/types\";\nimport { generateServingTypes } from \"../index\";\nimport {\n  extractServingEndpoints,\n  findServerFile,\n} from \"./server-file-extractor\";\n\nconst logger = createLogger(\"type-generator:serving:vite-plugin\");\n\ninterface AppKitServingTypesPluginOptions {\n  /** Path to the output .d.ts file (relative to client root). Default: \"src/appKitServingTypes.d.ts\" */\n  outFile?: string;\n  /** Endpoint config override. If omitted, auto-discovers from the server file or falls back to DATABRICKS_SERVING_ENDPOINT_NAME env var. */\n  endpoints?: Record<string, EndpointConfig>;\n}\n\n/**\n * Vite plugin to generate TypeScript types for AppKit serving endpoints.\n * Fetches OpenAPI schemas from Databricks and generates a .d.ts with\n * ServingEndpointRegistry module augmentation.\n *\n * Endpoint discovery order:\n * 1. Explicit `endpoints` option (override)\n * 2. AST extraction from server file (server/index.ts or server/server.ts)\n * 3. DATABRICKS_SERVING_ENDPOINT_NAME env var (single default endpoint)\n */\nexport function appKitServingTypesPlugin(\n  options?: AppKitServingTypesPluginOptions,\n): Plugin {\n  let outFile: string;\n  let projectRoot: string;\n\n  async function generate() {\n    try {\n      // Resolve endpoints: explicit option > server file AST > env var fallback (handled by generator)\n      let endpoints = options?.endpoints;\n      if (!endpoints) {\n        const serverFile = findServerFile(projectRoot);\n        if (serverFile) {\n          endpoints = extractServingEndpoints(serverFile) ?? undefined;\n        }\n      }\n\n      await generateServingTypes({\n        outFile,\n        endpoints,\n        noCache: false,\n      });\n    } catch (error) {\n      if (process.env.NODE_ENV === \"production\") {\n        throw error;\n      }\n      logger.error(\"Error generating serving types: %O\", error);\n    }\n  }\n\n  return {\n    name: \"appkit-serving-types\",\n\n    apply() {\n      // Fast checks — no AST parsing here\n      if (options?.endpoints && Object.keys(options.endpoints).length > 0) {\n        return true;\n      }\n\n      if (process.env.DATABRICKS_SERVING_ENDPOINT_NAME) {\n        return true;\n      }\n\n      // Check if a server file exists (may contain serving() config)\n      // Use process.cwd() for apply() since configResolved hasn't run yet\n      if (findServerFile(process.cwd())) {\n        return true;\n      }\n\n      // Also check parent dir (for when cwd is client/)\n      const parentDir = path.resolve(process.cwd(), \"..\");\n      if (findServerFile(parentDir)) {\n        return true;\n      }\n\n      logger.debug(\n        \"No serving endpoints configured. Skipping type generation.\",\n      );\n      return false;\n    },\n\n    configResolved(config) {\n      // Resolve project root: go up one level from Vite root (client dir)\n      // This handles both:\n      // - pnpm dev: process.cwd() is app root, config.root is client/\n      // - pnpm build: process.cwd() is client/ (cd client && vite build), config.root is client/\n      projectRoot = path.resolve(config.root, \"..\");\n      outFile = path.resolve(\n        config.root,\n        options?.outFile ?? \"src/appKitServingTypes.d.ts\",\n      );\n    },\n\n    async buildStart() {\n      await generate();\n    },\n\n    // No configureServer / watcher — schemas change on endpoint redeploy, not on file edit\n  };\n}\n"],"mappings":";;;;;;AAUA,MAAM,SAAS,aAAa,qCAAqC;;;;;;;;;;;AAmBjE,SAAgB,yBACd,SACQ;CACR,IAAI;CACJ,IAAI;CAEJ,eAAe,WAAW;AACxB,MAAI;GAEF,IAAI,YAAY,SAAS;AACzB,OAAI,CAAC,WAAW;IACd,MAAM,aAAa,eAAe,YAAY;AAC9C,QAAI,WACF,aAAY,wBAAwB,WAAW,IAAI;;AAIvD,SAAM,qBAAqB;IACzB;IACA;IACA,SAAS;IACV,CAAC;WACK,OAAO;AACd,OAAI,QAAQ,IAAI,aAAa,aAC3B,OAAM;AAER,UAAO,MAAM,sCAAsC,MAAM;;;AAI7D,QAAO;EACL,MAAM;EAEN,QAAQ;AAEN,OAAI,SAAS,aAAa,OAAO,KAAK,QAAQ,UAAU,CAAC,SAAS,EAChE,QAAO;AAGT,OAAI,QAAQ,IAAI,iCACd,QAAO;AAKT,OAAI,eAAe,QAAQ,KAAK,CAAC,CAC/B,QAAO;AAKT,OAAI,eADc,KAAK,QAAQ,QAAQ,KAAK,EAAE,KAAK,CACtB,CAC3B,QAAO;AAGT,UAAO,MACL,6DACD;AACD,UAAO;;EAGT,eAAe,QAAQ;AAKrB,iBAAc,KAAK,QAAQ,OAAO,MAAM,KAAK;AAC7C,aAAU,KAAK,QACb,OAAO,MACP,SAAS,WAAW,8BACrB;;EAGH,MAAM,aAAa;AACjB,SAAM,UAAU;;EAInB"}

package/docs/api/appkit/Class.Plugin.md

@@ -319,13 +319,18 @@ BasePlugin.clientConfig
 protected execute<T>(
    fn: (signal?: AbortSignal) => Promise<T>, 
    options: PluginExecutionSettings, 
-userKey?: string): Promise<T | undefined>;
+userKey?: string): Promise<ExecutionResult<T>>;
 
 ```
 
 Execute a function with the plugin's interceptor chain.
 
-All errors are caught and `undefined` is returned (production-safe). Route handlers should check for `undefined` and respond with an appropriate error status.
+Returns an [ExecutionResult](./docs/api/appkit/TypeAlias.ExecutionResult.md) discriminated union:
+
+* `{ ok: true, data: T }` on success
+* `{ ok: false, status: number, message: string }` on failure
+
+Errors are never thrown — the method is production-safe.
 
 #### Type Parameters[​](#type-parameters-1 "Direct link to Type Parameters")
 
@@ -343,7 +348,7 @@ All errors are caught and `undefined` is returned (production-safe). Route handl
 
 #### Returns[​](#returns-4 "Direct link to Returns")
 
-`Promise`<`T` | `undefined`>
+`Promise`<[`ExecutionResult`](./docs/api/appkit/TypeAlias.ExecutionResult.md)<`T`>>
 
 ***
 

package/docs/api/appkit/Function.appKitServingTypesPlugin.md

@@ -0,0 +1,24 @@
+# Function: appKitServingTypesPlugin()
+
+```ts
+function appKitServingTypesPlugin(options?: AppKitServingTypesPluginOptions): Plugin$1;
+
+```
+
+Vite plugin to generate TypeScript types for AppKit serving endpoints. Fetches OpenAPI schemas from Databricks and generates a .d.ts with ServingEndpointRegistry module augmentation.
+
+Endpoint discovery order:
+
+1. Explicit `endpoints` option (override)
+2. AST extraction from server file (server/index.ts or server/server.ts)
+3. DATABRICKS\_SERVING\_ENDPOINT\_NAME env var (single default endpoint)
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter  | Type                              |
+| ---------- | --------------------------------- |
+| `options?` | `AppKitServingTypesPluginOptions` |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`Plugin$1`

package/docs/api/appkit/Function.extractServingEndpoints.md

@@ -0,0 +1,22 @@
+# Function: extractServingEndpoints()
+
+```ts
+function extractServingEndpoints(serverFilePath: string): 
+  | Record<string, EndpointConfig>
+  | null;
+
+```
+
+Extract serving endpoint config from a server file by AST-parsing it. Looks for `serving({ endpoints: { alias: { env: "..." }, ... } })` calls and extracts the endpoint alias names and their environment variable mappings.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter        | Type     | Description                            |
+| ---------------- | -------- | -------------------------------------- |
+| `serverFilePath` | `string` | Absolute path to the server entry file |
+
+## Returns[​](#returns "Direct link to Returns")
+
+\| `Record`<`string`, [`EndpointConfig`](./docs/api/appkit/Interface.EndpointConfig.md)> | `null`
+
+Extracted endpoint config, or null if not found or not extractable

package/docs/api/appkit/Function.findServerFile.md

@@ -0,0 +1,20 @@
+# Function: findServerFile()
+
+```ts
+function findServerFile(basePath: string): string | null;
+
+```
+
+Find the server entry file by checking candidate paths in order.
+
+## Parameters[​](#parameters "Direct link to Parameters")
+
+| Parameter  | Type     | Description                           |
+| ---------- | -------- | ------------------------------------- |
+| `basePath` | `string` | Project root directory to search from |
+
+## Returns[​](#returns "Direct link to Returns")
+
+`string` | `null`
+
+Absolute path to the server file, or null if none found

package/docs/api/appkit/Interface.EndpointConfig.md

@@ -0,0 +1,23 @@
+# Interface: EndpointConfig
+
+## Properties[​](#properties "Direct link to Properties")
+
+### env[​](#env "Direct link to env")
+
+```ts
+env: string;
+
+```
+
+Environment variable holding the endpoint name.
+
+***
+
+### servedModel?[​](#servedmodel "Direct link to servedModel?")
+
+```ts
+optional servedModel: string;
+
+```
+
+Target a specific served model (bypasses traffic routing).

package/docs/api/appkit/Interface.ServingEndpointEntry.md

@@ -0,0 +1,30 @@
+# Interface: ServingEndpointEntry
+
+Shape of a single registry entry.
+
+## Properties[​](#properties "Direct link to Properties")
+
+### chunk[​](#chunk "Direct link to chunk")
+
+```ts
+chunk: unknown;
+
+```
+
+***
+
+### request[​](#request "Direct link to request")
+
+```ts
+request: Record<string, unknown>;
+
+```
+
+***
+
+### response[​](#response "Direct link to response")
+
+```ts
+response: unknown;
+
+```

package/docs/api/appkit/Interface.ServingEndpointRegistry.md

@@ -0,0 +1,3 @@
+# Interface: ServingEndpointRegistry
+
+Registry interface for serving endpoint type generation. Empty by default — augmented by the Vite type generator's `.d.ts` output via module augmentation. When populated, provides autocomplete for alias names and typed request/response/chunk per endpoint.