@databricks/appkit 0.5.4 → 0.7.0

package/dist/cli/commands/plugins-sync.js

@@ -0,0 +1,369 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { Lang, parse } from "@ast-grep/napi";
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+
+//#region src/cli/commands/plugins-sync.ts
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PLUGIN_MANIFEST_SCHEMA_PATH = path.join(__dirname, "..", "..", "..", "schemas", "plugin-manifest.schema.json");
+/**
+* Checks whether a resolved file path is within a given directory boundary.
+* Uses path.resolve + startsWith to prevent directory traversal.
+*
+* @param filePath - The path to check (will be resolved to absolute)
+* @param boundary - The directory that must contain filePath
+* @returns true if filePath is inside boundary (or equal to it)
+*/
+function isWithinDirectory(filePath, boundary) {
+	const resolvedPath = path.resolve(filePath);
+	const resolvedBoundary = path.resolve(boundary);
+	return resolvedPath === resolvedBoundary || resolvedPath.startsWith(`${resolvedBoundary}${path.sep}`);
+}
+let pluginManifestValidator = null;
+/**
+* Loads and compiles the plugin-manifest JSON schema (cached).
+* Returns the compiled validate function or null if the schema cannot be loaded.
+*/
+function getPluginManifestValidator() {
+	if (pluginManifestValidator) return pluginManifestValidator;
+	try {
+		const schemaRaw = fs.readFileSync(PLUGIN_MANIFEST_SCHEMA_PATH, "utf-8");
+		const schema = JSON.parse(schemaRaw);
+		const ajv = new Ajv({
+			allErrors: true,
+			strict: false
+		});
+		addFormats(ajv);
+		pluginManifestValidator = ajv.compile(schema);
+		return pluginManifestValidator;
+	} catch (err) {
+		console.warn("Warning: Could not load plugin-manifest schema for validation:", err instanceof Error ? err.message : err);
+		return null;
+	}
+}
+/**
+* Validates a parsed JSON object against the plugin-manifest JSON schema.
+* Returns the manifest if valid, or null and logs schema errors.
+*
+* @param obj - The parsed JSON object to validate
+* @param sourcePath - Path to the manifest file (for warning messages)
+* @returns A valid PluginManifest or null
+*/
+function validateManifestWithSchema(obj, sourcePath) {
+	if (!obj || typeof obj !== "object") {
+		console.warn(`Warning: Manifest at ${sourcePath} is not a valid object`);
+		return null;
+	}
+	const validate = getPluginManifestValidator();
+	if (!validate) {
+		const m = obj;
+		if (typeof m.name === "string" && m.name.length > 0 && typeof m.displayName === "string" && m.displayName.length > 0 && typeof m.description === "string" && m.description.length > 0 && m.resources && typeof m.resources === "object" && Array.isArray(m.resources.required)) return obj;
+		console.warn(`Warning: Manifest at ${sourcePath} has invalid structure`);
+		return null;
+	}
+	if (validate(obj)) return obj;
+	const message = (validate.errors ?? []).map((e) => `  ${e.instancePath || "/"} ${e.message}${e.params ? ` (${JSON.stringify(e.params)})` : ""}`).join("\n");
+	console.warn(`Warning: Manifest at ${sourcePath} failed schema validation:\n${message}`);
+	return null;
+}
+/**
+* Known packages that may contain AppKit plugins.
+* Always scanned for manifests, even if not imported in the server file.
+*/
+const KNOWN_PLUGIN_PACKAGES = ["@databricks/appkit"];
+/**
+* Candidate paths for the server entry file, relative to cwd.
+* Checked in order; the first that exists is used.
+*/
+const SERVER_FILE_CANDIDATES = ["server/server.ts"];
+/**
+* Find the server entry file by checking candidate paths in order.
+*
+* @param cwd - Current working directory
+* @returns Absolute path to the server file, or null if none found
+*/
+function findServerFile(cwd) {
+	for (const candidate of SERVER_FILE_CANDIDATES) {
+		const fullPath = path.join(cwd, candidate);
+		if (fs.existsSync(fullPath)) return fullPath;
+	}
+	return null;
+}
+/**
+* Extract all named imports from the AST root using structural node traversal.
+* Handles single/double quotes, multiline imports, and aliased imports.
+*
+* @param root - AST root node
+* @returns Array of parsed imports with name, original name, and source
+*/
+function parseImports(root) {
+	const imports = [];
+	const importStatements = root.findAll({ rule: { kind: "import_statement" } });
+	for (const stmt of importStatements) {
+		const sourceNode = stmt.find({ rule: { kind: "string" } });
+		if (!sourceNode) continue;
+		const source = sourceNode.text().replace(/^['"]|['"]$/g, "");
+		const namedImports = stmt.find({ rule: { kind: "named_imports" } });
+		if (!namedImports) continue;
+		const specifiers = namedImports.findAll({ rule: { kind: "import_specifier" } });
+		for (const specifier of specifiers) {
+			const children = specifier.children();
+			if (children.length >= 3) {
+				const originalName = children[0].text();
+				const localName = children[children.length - 1].text();
+				imports.push({
+					name: localName,
+					originalName,
+					source
+				});
+			} else {
+				const name = specifier.text();
+				imports.push({
+					name,
+					originalName: name,
+					source
+				});
+			}
+		}
+	}
+	return imports;
+}
+/**
+* Extract local names of plugins actually used in the `plugins: [...]` array
+* passed to `createApp()`. Uses structural AST traversal to find `pair` nodes
+* with key "plugins" and array values containing call expressions.
+*
+* @param root - AST root node
+* @returns Set of local variable names used as plugin calls in the plugins array
+*/
+function parsePluginUsages(root) {
+	const usedNames = /* @__PURE__ */ new Set();
+	const pairs = root.findAll({ rule: { kind: "pair" } });
+	for (const pair of pairs) {
+		const key = pair.find({ rule: { kind: "property_identifier" } });
+		if (!key || key.text() !== "plugins") continue;
+		const arrayNode = pair.find({ rule: { kind: "array" } });
+		if (!arrayNode) continue;
+		for (const child of arrayNode.children()) if (child.kind() === "call_expression") {
+			const callee = child.children()[0];
+			if (callee?.kind() === "identifier") usedNames.add(callee.text());
+		}
+	}
+	return usedNames;
+}
+/**
+* File extensions to try when resolving a relative import to a file path.
+*/
+const RESOLVE_EXTENSIONS = [
+	".ts",
+	".tsx",
+	".js",
+	".jsx"
+];
+/**
+* Resolve a relative import source to the plugin directory containing a manifest.json.
+* Follows the convention that plugins live in their own directory with a manifest.json.
+*
+* Resolution strategy:
+* 1. If the import path is a directory, look for manifest.json directly in it
+* 2. If the import path + extension is a file, look for manifest.json in its parent directory
+* 3. If the import path is a directory with an index file, look for manifest.json in that directory
+*
+* @param importSource - The relative import specifier (e.g. "./plugins/my-plugin")
+* @param serverFileDir - Absolute path to the directory containing the server file
+* @returns Absolute path to manifest.json, or null if not found
+*/
+function resolveLocalManifest(importSource, serverFileDir, projectRoot) {
+	const resolved = path.resolve(serverFileDir, importSource);
+	if (!isWithinDirectory(resolved, projectRoot || serverFileDir)) {
+		console.warn(`Warning: Skipping import "${importSource}" — resolves outside the project directory`);
+		return null;
+	}
+	if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
+		const manifestPath = path.join(resolved, "manifest.json");
+		if (fs.existsSync(manifestPath)) return manifestPath;
+	}
+	for (const ext of RESOLVE_EXTENSIONS) {
+		const filePath = `${resolved}${ext}`;
+		if (fs.existsSync(filePath) && fs.statSync(filePath).isFile()) {
+			const dir = path.dirname(filePath);
+			const manifestPath = path.join(dir, "manifest.json");
+			if (fs.existsSync(manifestPath)) return manifestPath;
+			break;
+		}
+	}
+	for (const ext of RESOLVE_EXTENSIONS) {
+		const indexPath = path.join(resolved, `index${ext}`);
+		if (fs.existsSync(indexPath)) {
+			const manifestPath = path.join(resolved, "manifest.json");
+			if (fs.existsSync(manifestPath)) return manifestPath;
+			break;
+		}
+	}
+	return null;
+}
+/**
+* Discover plugin manifests from local (relative) imports in the server file.
+* Resolves each relative import to a directory and looks for manifest.json.
+*
+* @param relativeImports - Parsed imports with relative sources (starting with . or /)
+* @param serverFileDir - Absolute path to the directory containing the server file
+* @param cwd - Current working directory (for computing relative paths in output)
+* @returns Map of plugin name to template plugin entry for local plugins
+*/
+function discoverLocalPlugins(relativeImports, serverFileDir, cwd) {
+	const plugins = {};
+	for (const imp of relativeImports) {
+		const manifestPath = resolveLocalManifest(imp.source, serverFileDir, cwd);
+		if (!manifestPath) continue;
+		try {
+			const content = fs.readFileSync(manifestPath, "utf-8");
+			const manifest = validateManifestWithSchema(JSON.parse(content), manifestPath);
+			if (!manifest) continue;
+			const relativePath = path.relative(cwd, path.dirname(manifestPath));
+			plugins[manifest.name] = {
+				name: manifest.name,
+				displayName: manifest.displayName,
+				description: manifest.description,
+				package: `./${relativePath}`,
+				resources: manifest.resources
+			};
+		} catch (error) {
+			console.warn(`Warning: Failed to parse manifest at ${manifestPath}:`, error instanceof Error ? error.message : error);
+		}
+	}
+	return plugins;
+}
+/**
+* Discover plugin manifests from a package's dist folder.
+* Looks for manifest.json files in dist/plugins/{plugin-name}/ directories.
+*
+* @param packagePath - Path to the package in node_modules
+* @returns Array of plugin manifests found in the package
+*/
+function discoverPluginManifests(packagePath) {
+	const pluginsDir = path.join(packagePath, "dist", "plugins");
+	const manifests = [];
+	if (!fs.existsSync(pluginsDir)) return manifests;
+	const entries = fs.readdirSync(pluginsDir, { withFileTypes: true });
+	for (const entry of entries) if (entry.isDirectory()) {
+		const manifestPath = path.join(pluginsDir, entry.name, "manifest.json");
+		if (fs.existsSync(manifestPath)) try {
+			const content = fs.readFileSync(manifestPath, "utf-8");
+			const manifest = validateManifestWithSchema(JSON.parse(content), manifestPath);
+			if (manifest) manifests.push(manifest);
+		} catch (error) {
+			console.warn(`Warning: Failed to parse manifest at ${manifestPath}:`, error instanceof Error ? error.message : error);
+		}
+	}
+	return manifests;
+}
+/**
+* Scan node_modules for packages with plugin manifests.
+*
+* @param cwd - Current working directory to search from
+* @param packages - Set of npm package names to scan for plugin manifests
+* @returns Map of plugin name to template plugin entry
+*/
+function scanForPlugins(cwd, packages) {
+	const plugins = {};
+	for (const packageName of packages) {
+		const packagePath = path.join(cwd, "node_modules", packageName);
+		if (!fs.existsSync(packagePath)) continue;
+		const manifests = discoverPluginManifests(packagePath);
+		for (const manifest of manifests) plugins[manifest.name] = {
+			name: manifest.name,
+			displayName: manifest.displayName,
+			description: manifest.description,
+			package: packageName,
+			resources: manifest.resources
+		};
+	}
+	return plugins;
+}
+/**
+* Run the plugins sync command.
+* Parses the server entry file to discover which packages to scan for plugin
+* manifests, then marks plugins that are actually used in the `plugins: [...]`
+* array as requiredByTemplate.
+*/
+function runPluginsSync(options) {
+	const cwd = process.cwd();
+	const outputPath = path.resolve(cwd, options.output || "appkit.plugins.json");
+	if (!isWithinDirectory(outputPath, cwd)) {
+		console.error(`Error: Output path "${options.output}" resolves outside the project directory.`);
+		process.exit(1);
+	}
+	console.log("Scanning for AppKit plugins...\n");
+	const serverFile = findServerFile(cwd);
+	let serverImports = [];
+	let pluginUsages = /* @__PURE__ */ new Set();
+	if (serverFile) {
+		const relativePath = path.relative(cwd, serverFile);
+		console.log(`Server entry file: ${relativePath}`);
+		const content = fs.readFileSync(serverFile, "utf-8");
+		const root = parse(serverFile.endsWith(".tsx") ? Lang.Tsx : Lang.TypeScript, content).root();
+		serverImports = parseImports(root);
+		pluginUsages = parsePluginUsages(root);
+	} else console.log("No server entry file found. Checked:", SERVER_FILE_CANDIDATES.join(", "));
+	const npmImports = serverImports.filter((i) => !i.source.startsWith(".") && !i.source.startsWith("/"));
+	const localImports = serverImports.filter((i) => i.source.startsWith(".") || i.source.startsWith("/"));
+	const npmPackages = new Set([...KNOWN_PLUGIN_PACKAGES, ...npmImports.map((i) => i.source)]);
+	const plugins = scanForPlugins(cwd, npmPackages);
+	if (serverFile && localImports.length > 0) {
+		const localPlugins = discoverLocalPlugins(localImports, path.dirname(serverFile), cwd);
+		Object.assign(plugins, localPlugins);
+	}
+	const pluginCount = Object.keys(plugins).length;
+	if (pluginCount === 0) {
+		console.log("No plugins found.");
+		console.log("\nMake sure you have plugin packages installed:");
+		for (const pkg of npmPackages) console.log(`  - ${pkg}`);
+		process.exit(1);
+	}
+	const serverFileDir = serverFile ? path.dirname(serverFile) : cwd;
+	for (const imp of serverImports) {
+		if (!pluginUsages.has(imp.name)) continue;
+		const isLocal = imp.source.startsWith(".") || imp.source.startsWith("/");
+		let plugin;
+		if (isLocal) {
+			const resolvedImportDir = path.resolve(serverFileDir, imp.source);
+			plugin = Object.values(plugins).find((p) => {
+				if (!p.package.startsWith(".")) return false;
+				return path.resolve(cwd, p.package) === resolvedImportDir && p.name === imp.originalName;
+			});
+		} else plugin = Object.values(plugins).find((p) => p.package === imp.source && p.name === imp.originalName);
+		if (plugin) plugin.requiredByTemplate = true;
+	}
+	console.log(`\nFound ${pluginCount} plugin(s):`);
+	for (const [name, manifest] of Object.entries(plugins)) {
+		const resourceCount = manifest.resources.required.length + manifest.resources.optional.length;
+		const resourceInfo = resourceCount > 0 ? ` [${resourceCount} resource(s)]` : "";
+		const mandatoryTag = manifest.requiredByTemplate ? " (mandatory)" : "";
+		console.log(`  ${manifest.requiredByTemplate ? "●" : "○"} ${manifest.displayName} (${name}) from ${manifest.package}${resourceInfo}${mandatoryTag}`);
+	}
+	const templateManifest = {
+		$schema: "https://databricks.github.io/appkit/schemas/template-plugins.schema.json",
+		version: "1.0",
+		plugins
+	};
+	if (options.write) {
+		fs.writeFileSync(outputPath, `${JSON.stringify(templateManifest, null, 2)}\n`);
+		console.log(`\n✓ Wrote ${outputPath}`);
+	} else {
+		console.log("\nTo write the manifest, run:");
+		console.log("  npx appkit plugins sync --write\n");
+		console.log("Preview:");
+		console.log("─".repeat(60));
+		console.log(JSON.stringify(templateManifest, null, 2));
+		console.log("─".repeat(60));
+	}
+}
+const pluginsSyncCommand = new Command("sync").description("Sync plugin manifests from installed packages into appkit.plugins.json").option("-w, --write", "Write the manifest file").option("-o, --output <path>", "Output file path (default: ./appkit.plugins.json)").action(runPluginsSync);
+
+//#endregion
+export { pluginsSyncCommand };
+//# sourceMappingURL=plugins-sync.js.map

package/dist/cli/commands/plugins-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins-sync.js","names":[],"sources":["../../../src/cli/commands/plugins-sync.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { Lang, parse, type SgNode } from \"@ast-grep/napi\";\nimport Ajv, { type ErrorObject } from \"ajv\";\nimport addFormats from \"ajv-formats\";\nimport { Command } from \"commander\";\n\nconst __dirname = path.dirname(fileURLToPath(import.meta.url));\n// Resolve to package schemas: from dist/cli/commands -> dist/schemas, from src/cli/commands -> shared/schemas\nconst PLUGIN_MANIFEST_SCHEMA_PATH = path.join(\n  __dirname,\n  \"..\",\n  \"..\",\n  \"..\",\n  \"schemas\",\n  \"plugin-manifest.schema.json\",\n);\n\n/**\n * Field entry in a resource requirement (env var + optional description)\n */\ninterface ResourceFieldEntry {\n  env: string;\n  description?: string;\n}\n\n/**\n * Resource requirement as defined in plugin manifests.\n * Uses fields (single key e.g. id, or multiple e.g. instance_name/database_name, scope/key).\n */\ninterface ResourceRequirement {\n  type: string;\n  alias: string;\n  resourceKey: string;\n  description: string;\n  permission: string;\n  fields: Record<string, ResourceFieldEntry>;\n}\n\n/**\n * Plugin manifest structure (from SDK plugin manifest.json files)\n */\ninterface PluginManifest {\n  name: string;\n  displayName: string;\n  description: string;\n  resources: {\n    required: ResourceRequirement[];\n    optional: ResourceRequirement[];\n  };\n  config?: { schema: unknown };\n}\n\n/**\n * Plugin entry in the template manifest (includes package source)\n */\ninterface TemplatePlugin extends Omit<PluginManifest, \"config\"> {\n  package: string;\n  /** When true, this plugin is required by the template and cannot be deselected during CLI init. */\n  requiredByTemplate?: boolean;\n}\n\n/**\n * Template plugins manifest structure\n */\ninterface TemplatePluginsManifest {\n  $schema: string;\n  version: string;\n  plugins: Record<string, TemplatePlugin>;\n}\n\n/**\n * Checks whether a resolved file path is within a given directory boundary.\n * Uses path.resolve + startsWith to prevent directory traversal.\n *\n * @param filePath - The path to check (will be resolved to absolute)\n * @param boundary - The directory that must contain filePath\n * @returns true if filePath is inside boundary (or equal to it)\n */\nfunction isWithinDirectory(filePath: string, boundary: string): boolean {\n  const resolvedPath = path.resolve(filePath);\n  const resolvedBoundary = path.resolve(boundary);\n  // Append separator to avoid prefix false-positives (e.g. /foo-bar matching /foo)\n  return (\n    resolvedPath === resolvedBoundary ||\n    resolvedPath.startsWith(`${resolvedBoundary}${path.sep}`)\n  );\n}\n\nlet pluginManifestValidator: ReturnType<Ajv[\"compile\"]> | null = null;\n\n/**\n * Loads and compiles the plugin-manifest JSON schema (cached).\n * Returns the compiled validate function or null if the schema cannot be loaded.\n */\nfunction getPluginManifestValidator(): ReturnType<Ajv[\"compile\"]> | null {\n  if (pluginManifestValidator) return pluginManifestValidator;\n  try {\n    const schemaRaw = fs.readFileSync(PLUGIN_MANIFEST_SCHEMA_PATH, \"utf-8\");\n    const schema = JSON.parse(schemaRaw) as object;\n    const ajv = new Ajv({ allErrors: true, strict: false });\n    addFormats(ajv);\n    pluginManifestValidator = ajv.compile(schema);\n    return pluginManifestValidator;\n  } catch (err) {\n    console.warn(\n      \"Warning: Could not load plugin-manifest schema for validation:\",\n      err instanceof Error ? err.message : err,\n    );\n    return null;\n  }\n}\n\n/**\n * Validates a parsed JSON object against the plugin-manifest JSON schema.\n * Returns the manifest if valid, or null and logs schema errors.\n *\n * @param obj - The parsed JSON object to validate\n * @param sourcePath - Path to the manifest file (for warning messages)\n * @returns A valid PluginManifest or null\n */\nfunction validateManifestWithSchema(\n  obj: unknown,\n  sourcePath: string,\n): PluginManifest | null {\n  if (!obj || typeof obj !== \"object\") {\n    console.warn(`Warning: Manifest at ${sourcePath} is not a valid object`);\n    return null;\n  }\n\n  const validate = getPluginManifestValidator();\n  if (!validate) {\n    // Schema not available (e.g. dev without build); fall back to basic shape check\n    const m = obj as Record<string, unknown>;\n    if (\n      typeof m.name === \"string\" &&\n      m.name.length > 0 &&\n      typeof m.displayName === \"string\" &&\n      m.displayName.length > 0 &&\n      typeof m.description === \"string\" &&\n      m.description.length > 0 &&\n      m.resources &&\n      typeof m.resources === \"object\" &&\n      Array.isArray((m.resources as { required?: unknown }).required)\n    ) {\n      return obj as PluginManifest;\n    }\n    console.warn(`Warning: Manifest at ${sourcePath} has invalid structure`);\n    return null;\n  }\n\n  const valid = validate(obj);\n  if (valid) return obj as PluginManifest;\n\n  const errors: ErrorObject[] = validate.errors ?? [];\n  const message = errors\n    .map(\n      (e: ErrorObject) =>\n        `  ${e.instancePath || \"/\"} ${e.message}${e.params ? ` (${JSON.stringify(e.params)})` : \"\"}`,\n    )\n    .join(\"\\n\");\n  console.warn(\n    `Warning: Manifest at ${sourcePath} failed schema validation:\\n${message}`,\n  );\n  return null;\n}\n\n/**\n * Known packages that may contain AppKit plugins.\n * Always scanned for manifests, even if not imported in the server file.\n */\nconst KNOWN_PLUGIN_PACKAGES = [\"@databricks/appkit\"];\n\n/**\n * Candidate paths for the server entry file, relative to cwd.\n * Checked in order; the first that exists is used.\n */\nconst SERVER_FILE_CANDIDATES = [\"server/server.ts\"];\n\n/**\n * Find the server entry file by checking candidate paths in order.\n *\n * @param cwd - Current working directory\n * @returns Absolute path to the server file, or null if none found\n */\nfunction findServerFile(cwd: string): string | null {\n  for (const candidate of SERVER_FILE_CANDIDATES) {\n    const fullPath = path.join(cwd, candidate);\n    if (fs.existsSync(fullPath)) {\n      return fullPath;\n    }\n  }\n  return null;\n}\n\n/**\n * Represents a single named import extracted from the server file.\n */\ninterface ParsedImport {\n  /** The imported name (or local alias if renamed) */\n  name: string;\n  /** The original exported name (differs from name when using `import { foo as bar }`) */\n  originalName: string;\n  /** The module specifier (package name or relative path) */\n  source: string;\n}\n\n/**\n * Extract all named imports from the AST root using structural node traversal.\n * Handles single/double quotes, multiline imports, and aliased imports.\n *\n * @param root - AST root node\n * @returns Array of parsed imports with name, original name, and source\n */\nfunction parseImports(root: SgNode): ParsedImport[] {\n  const imports: ParsedImport[] = [];\n\n  // Find all import_statement nodes in the AST\n  const importStatements = root.findAll({\n    rule: { kind: \"import_statement\" },\n  });\n\n  for (const stmt of importStatements) {\n    // Extract the module specifier (the string node, e.g. '@databricks/appkit')\n    const sourceNode = stmt.find({ rule: { kind: \"string\" } });\n    if (!sourceNode) continue;\n\n    // Strip surrounding quotes from the string node text\n    const source = sourceNode.text().replace(/^['\"]|['\"]$/g, \"\");\n\n    // Find named_imports block: { createApp, analytics, server }\n    const namedImports = stmt.find({ rule: { kind: \"named_imports\" } });\n    if (!namedImports) continue;\n\n    // Extract each import_specifier\n    const specifiers = namedImports.findAll({\n      rule: { kind: \"import_specifier\" },\n    });\n\n    for (const specifier of specifiers) {\n      const children = specifier.children();\n      if (children.length >= 3) {\n        // Aliased import: `foo as bar` — children are [name, \"as\", alias]\n        const originalName = children[0].text();\n        const localName = children[children.length - 1].text();\n        imports.push({ name: localName, originalName, source });\n      } else {\n        // Simple import: `foo`\n        const name = specifier.text();\n        imports.push({ name, originalName: name, source });\n      }\n    }\n  }\n\n  return imports;\n}\n\n/**\n * Extract local names of plugins actually used in the `plugins: [...]` array\n * passed to `createApp()`. Uses structural AST traversal to find `pair` nodes\n * with key \"plugins\" and array values containing call expressions.\n *\n * @param root - AST root node\n * @returns Set of local variable names used as plugin calls in the plugins array\n */\nfunction parsePluginUsages(root: SgNode): Set<string> {\n  const usedNames = new Set<string>();\n\n  // Find all property pairs in the AST\n  const pairs = root.findAll({ rule: { kind: \"pair\" } });\n\n  for (const pair of pairs) {\n    // Check if the property key is \"plugins\"\n    const key = pair.find({ rule: { kind: \"property_identifier\" } });\n    if (!key || key.text() !== \"plugins\") continue;\n\n    // Find the array value\n    const arrayNode = pair.find({ rule: { kind: \"array\" } });\n    if (!arrayNode) continue;\n\n    // Iterate direct children of the array to find call expressions\n    for (const child of arrayNode.children()) {\n      if (child.kind() === \"call_expression\") {\n        // The callee is the first child (the identifier being called)\n        const callee = child.children()[0];\n        if (callee?.kind() === \"identifier\") {\n          usedNames.add(callee.text());\n        }\n      }\n    }\n  }\n\n  return usedNames;\n}\n\n/**\n * File extensions to try when resolving a relative import to a file path.\n */\nconst RESOLVE_EXTENSIONS = [\".ts\", \".tsx\", \".js\", \".jsx\"];\n\n/**\n * Resolve a relative import source to the plugin directory containing a manifest.json.\n * Follows the convention that plugins live in their own directory with a manifest.json.\n *\n * Resolution strategy:\n * 1. If the import path is a directory, look for manifest.json directly in it\n * 2. If the import path + extension is a file, look for manifest.json in its parent directory\n * 3. If the import path is a directory with an index file, look for manifest.json in that directory\n *\n * @param importSource - The relative import specifier (e.g. \"./plugins/my-plugin\")\n * @param serverFileDir - Absolute path to the directory containing the server file\n * @returns Absolute path to manifest.json, or null if not found\n */\nfunction resolveLocalManifest(\n  importSource: string,\n  serverFileDir: string,\n  projectRoot?: string,\n): string | null {\n  const resolved = path.resolve(serverFileDir, importSource);\n\n  // Security: Reject paths that escape the project root\n  const boundary = projectRoot || serverFileDir;\n  if (!isWithinDirectory(resolved, boundary)) {\n    console.warn(\n      `Warning: Skipping import \"${importSource}\" — resolves outside the project directory`,\n    );\n    return null;\n  }\n\n  // Case 1: Import path is a directory with manifest.json\n  // e.g. ./plugins/my-plugin → ./plugins/my-plugin/manifest.json\n  if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {\n    const manifestPath = path.join(resolved, \"manifest.json\");\n    if (fs.existsSync(manifestPath)) return manifestPath;\n  }\n\n  // Case 2: Import path + extension resolves to a file\n  // e.g. ./plugins/my-plugin → ./plugins/my-plugin.ts\n  // Look for manifest.json in the same directory\n  for (const ext of RESOLVE_EXTENSIONS) {\n    const filePath = `${resolved}${ext}`;\n    if (fs.existsSync(filePath) && fs.statSync(filePath).isFile()) {\n      const dir = path.dirname(filePath);\n      const manifestPath = path.join(dir, \"manifest.json\");\n      if (fs.existsSync(manifestPath)) return manifestPath;\n      break;\n    }\n  }\n\n  // Case 3: Import path is a directory with an index file\n  // e.g. ./plugins/my-plugin → ./plugins/my-plugin/index.ts\n  for (const ext of RESOLVE_EXTENSIONS) {\n    const indexPath = path.join(resolved, `index${ext}`);\n    if (fs.existsSync(indexPath)) {\n      const manifestPath = path.join(resolved, \"manifest.json\");\n      if (fs.existsSync(manifestPath)) return manifestPath;\n      break;\n    }\n  }\n\n  return null;\n}\n\n/**\n * Discover plugin manifests from local (relative) imports in the server file.\n * Resolves each relative import to a directory and looks for manifest.json.\n *\n * @param relativeImports - Parsed imports with relative sources (starting with . or /)\n * @param serverFileDir - Absolute path to the directory containing the server file\n * @param cwd - Current working directory (for computing relative paths in output)\n * @returns Map of plugin name to template plugin entry for local plugins\n */\nfunction discoverLocalPlugins(\n  relativeImports: ParsedImport[],\n  serverFileDir: string,\n  cwd: string,\n): TemplatePluginsManifest[\"plugins\"] {\n  const plugins: TemplatePluginsManifest[\"plugins\"] = {};\n\n  for (const imp of relativeImports) {\n    const manifestPath = resolveLocalManifest(imp.source, serverFileDir, cwd);\n    if (!manifestPath) continue;\n\n    try {\n      const content = fs.readFileSync(manifestPath, \"utf-8\");\n      const parsed = JSON.parse(content);\n      const manifest = validateManifestWithSchema(parsed, manifestPath);\n      if (!manifest) continue;\n\n      const relativePath = path.relative(cwd, path.dirname(manifestPath));\n\n      plugins[manifest.name] = {\n        name: manifest.name,\n        displayName: manifest.displayName,\n        description: manifest.description,\n        package: `./${relativePath}`,\n        resources: manifest.resources,\n      };\n    } catch (error) {\n      console.warn(\n        `Warning: Failed to parse manifest at ${manifestPath}:`,\n        error instanceof Error ? error.message : error,\n      );\n    }\n  }\n\n  return plugins;\n}\n\n/**\n * Discover plugin manifests from a package's dist folder.\n * Looks for manifest.json files in dist/plugins/{plugin-name}/ directories.\n *\n * @param packagePath - Path to the package in node_modules\n * @returns Array of plugin manifests found in the package\n */\nfunction discoverPluginManifests(packagePath: string): PluginManifest[] {\n  const pluginsDir = path.join(packagePath, \"dist\", \"plugins\");\n  const manifests: PluginManifest[] = [];\n\n  if (!fs.existsSync(pluginsDir)) {\n    return manifests;\n  }\n\n  const entries = fs.readdirSync(pluginsDir, { withFileTypes: true });\n  for (const entry of entries) {\n    if (entry.isDirectory()) {\n      const manifestPath = path.join(pluginsDir, entry.name, \"manifest.json\");\n      if (fs.existsSync(manifestPath)) {\n        try {\n          const content = fs.readFileSync(manifestPath, \"utf-8\");\n          const parsed = JSON.parse(content);\n          const manifest = validateManifestWithSchema(parsed, manifestPath);\n          if (manifest) {\n            manifests.push(manifest);\n          }\n        } catch (error) {\n          console.warn(\n            `Warning: Failed to parse manifest at ${manifestPath}:`,\n            error instanceof Error ? error.message : error,\n          );\n        }\n      }\n    }\n  }\n\n  return manifests;\n}\n\n/**\n * Scan node_modules for packages with plugin manifests.\n *\n * @param cwd - Current working directory to search from\n * @param packages - Set of npm package names to scan for plugin manifests\n * @returns Map of plugin name to template plugin entry\n */\nfunction scanForPlugins(\n  cwd: string,\n  packages: Iterable<string>,\n): TemplatePluginsManifest[\"plugins\"] {\n  const plugins: TemplatePluginsManifest[\"plugins\"] = {};\n\n  for (const packageName of packages) {\n    const packagePath = path.join(cwd, \"node_modules\", packageName);\n    if (!fs.existsSync(packagePath)) {\n      continue;\n    }\n\n    const manifests = discoverPluginManifests(packagePath);\n    for (const manifest of manifests) {\n      // Convert to template plugin format (exclude config schema)\n      plugins[manifest.name] = {\n        name: manifest.name,\n        displayName: manifest.displayName,\n        description: manifest.description,\n        package: packageName,\n        resources: manifest.resources,\n      };\n    }\n  }\n\n  return plugins;\n}\n\n/**\n * Run the plugins sync command.\n * Parses the server entry file to discover which packages to scan for plugin\n * manifests, then marks plugins that are actually used in the `plugins: [...]`\n * array as requiredByTemplate.\n */\nfunction runPluginsSync(options: { write?: boolean; output?: string }) {\n  const cwd = process.cwd();\n  const outputPath = path.resolve(cwd, options.output || \"appkit.plugins.json\");\n\n  // Security: Reject output paths that escape the project root\n  if (!isWithinDirectory(outputPath, cwd)) {\n    console.error(\n      `Error: Output path \"${options.output}\" resolves outside the project directory.`,\n    );\n    process.exit(1);\n  }\n\n  console.log(\"Scanning for AppKit plugins...\\n\");\n\n  // Step 1: Parse server file to discover imports and plugin usages\n  const serverFile = findServerFile(cwd);\n  let serverImports: ParsedImport[] = [];\n  let pluginUsages = new Set<string>();\n\n  if (serverFile) {\n    const relativePath = path.relative(cwd, serverFile);\n    console.log(`Server entry file: ${relativePath}`);\n\n    const content = fs.readFileSync(serverFile, \"utf-8\");\n    const lang = serverFile.endsWith(\".tsx\") ? Lang.Tsx : Lang.TypeScript;\n    const ast = parse(lang, content);\n    const root = ast.root();\n\n    serverImports = parseImports(root);\n    pluginUsages = parsePluginUsages(root);\n  } else {\n    console.log(\n      \"No server entry file found. Checked:\",\n      SERVER_FILE_CANDIDATES.join(\", \"),\n    );\n  }\n\n  // Step 2: Split imports into npm packages and local (relative) imports\n  const npmImports = serverImports.filter(\n    (i) => !i.source.startsWith(\".\") && !i.source.startsWith(\"/\"),\n  );\n  const localImports = serverImports.filter(\n    (i) => i.source.startsWith(\".\") || i.source.startsWith(\"/\"),\n  );\n\n  // Step 3: Scan npm packages for plugin manifests\n  const npmPackages = new Set([\n    ...KNOWN_PLUGIN_PACKAGES,\n    ...npmImports.map((i) => i.source),\n  ]);\n  const plugins = scanForPlugins(cwd, npmPackages);\n\n  // Step 4: Discover local plugin manifests from relative imports\n  if (serverFile && localImports.length > 0) {\n    const serverFileDir = path.dirname(serverFile);\n    const localPlugins = discoverLocalPlugins(localImports, serverFileDir, cwd);\n    Object.assign(plugins, localPlugins);\n  }\n\n  const pluginCount = Object.keys(plugins).length;\n\n  if (pluginCount === 0) {\n    console.log(\"No plugins found.\");\n    console.log(\"\\nMake sure you have plugin packages installed:\");\n    for (const pkg of npmPackages) {\n      console.log(`  - ${pkg}`);\n    }\n    process.exit(1);\n  }\n\n  // Step 5: Mark plugins that are imported AND used in the plugins array as mandatory.\n  // For npm imports, match by package name + plugin name.\n  // For local imports, resolve both paths to absolute and compare.\n  const serverFileDir = serverFile ? path.dirname(serverFile) : cwd;\n\n  for (const imp of serverImports) {\n    if (!pluginUsages.has(imp.name)) continue;\n\n    const isLocal = imp.source.startsWith(\".\") || imp.source.startsWith(\"/\");\n    let plugin: TemplatePlugin | undefined;\n\n    if (isLocal) {\n      // Resolve the import source to an absolute path from the server file directory\n      const resolvedImportDir = path.resolve(serverFileDir, imp.source);\n      plugin = Object.values(plugins).find((p) => {\n        if (!p.package.startsWith(\".\")) return false;\n        const resolvedPluginDir = path.resolve(cwd, p.package);\n        return (\n          resolvedPluginDir === resolvedImportDir && p.name === imp.originalName\n        );\n      });\n    } else {\n      // npm import: direct string comparison\n      plugin = Object.values(plugins).find(\n        (p) => p.package === imp.source && p.name === imp.originalName,\n      );\n    }\n\n    if (plugin) {\n      plugin.requiredByTemplate = true;\n    }\n  }\n\n  console.log(`\\nFound ${pluginCount} plugin(s):`);\n  for (const [name, manifest] of Object.entries(plugins)) {\n    const resourceCount =\n      manifest.resources.required.length + manifest.resources.optional.length;\n    const resourceInfo =\n      resourceCount > 0 ? ` [${resourceCount} resource(s)]` : \"\";\n    const mandatoryTag = manifest.requiredByTemplate ? \" (mandatory)\" : \"\";\n    console.log(\n      `  ${manifest.requiredByTemplate ? \"●\" : \"○\"} ${manifest.displayName} (${name}) from ${manifest.package}${resourceInfo}${mandatoryTag}`,\n    );\n  }\n\n  const templateManifest: TemplatePluginsManifest = {\n    $schema:\n      \"https://databricks.github.io/appkit/schemas/template-plugins.schema.json\",\n    version: \"1.0\",\n    plugins,\n  };\n\n  if (options.write) {\n    fs.writeFileSync(\n      outputPath,\n      `${JSON.stringify(templateManifest, null, 2)}\\n`,\n    );\n    console.log(`\\n✓ Wrote ${outputPath}`);\n  } else {\n    console.log(\"\\nTo write the manifest, run:\");\n    console.log(\"  npx appkit plugins sync --write\\n\");\n    console.log(\"Preview:\");\n    console.log(\"─\".repeat(60));\n    console.log(JSON.stringify(templateManifest, null, 2));\n    console.log(\"─\".repeat(60));\n  }\n}\n\n/** Exported for testing: path boundary check, AST parsing. */\nexport { isWithinDirectory, parseImports, parsePluginUsages };\n\nexport const pluginsSyncCommand = new Command(\"sync\")\n  .description(\n    \"Sync plugin manifests from installed packages into appkit.plugins.json\",\n  )\n  .option(\"-w, --write\", \"Write the manifest file\")\n  .option(\n    \"-o, --output <path>\",\n    \"Output file path (default: ./appkit.plugins.json)\",\n  )\n  .action(runPluginsSync);\n"],"mappings":"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"}

package/dist/cli/commands/plugins.js

@@ -0,0 +1,19 @@
+import { pluginsSyncCommand } from "./plugins-sync.js";
+import { Command } from "commander";
+
+//#region src/cli/commands/plugins.ts
+/**
+* Parent command for plugin management operations.
+* Subcommands:
+*   - sync: Aggregate plugin manifests into appkit.plugins.json
+*
+* Future subcommands may include:
+*   - add: Add a plugin to an existing project
+*   - remove: Remove a plugin from a project
+*   - list: List available plugins
+*/
+const pluginsCommand = new Command("plugins").description("Plugin management commands").addCommand(pluginsSyncCommand);
+
+//#endregion
+export { pluginsCommand };
+//# sourceMappingURL=plugins.js.map

package/dist/cli/commands/plugins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.js","names":[],"sources":["../../../src/cli/commands/plugins.ts"],"sourcesContent":["import { Command } from \"commander\";\nimport { pluginsSyncCommand } from \"./plugins-sync.js\";\n\n/**\n * Parent command for plugin management operations.\n * Subcommands:\n *   - sync: Aggregate plugin manifests into appkit.plugins.json\n *\n * Future subcommands may include:\n *   - add: Add a plugin to an existing project\n *   - remove: Remove a plugin from a project\n *   - list: List available plugins\n */\nexport const pluginsCommand = new Command(\"plugins\")\n  .description(\"Plugin management commands\")\n  .addCommand(pluginsSyncCommand);\n"],"mappings":";;;;;;;;;;;;;;AAaA,MAAa,iBAAiB,IAAI,QAAQ,UAAU,CACjD,YAAY,6BAA6B,CACzC,WAAW,mBAAmB"}

package/dist/cli/index.js

@@ -2,6 +2,7 @@
 import { docsCommand } from "./commands/docs.js";
 import { generateTypesCommand } from "./commands/generate-types.js";
 import { lintCommand } from "./commands/lint.js";
+import { pluginsCommand } from "./commands/plugins.js";
 import { setupCommand } from "./commands/setup.js";
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -17,6 +18,7 @@ cmd.addCommand(setupCommand);
 cmd.addCommand(generateTypesCommand);
 cmd.addCommand(lintCommand);
 cmd.addCommand(docsCommand);
+cmd.addCommand(pluginsCommand);
 cmd.parse();
 
 //#endregion

package/dist/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/cli/index.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport { readFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { Command } from \"commander\";\nimport { docsCommand } from \"./commands/docs.js\";\nimport { generateTypesCommand } from \"./commands/generate-types.js\";\nimport { lintCommand } from \"./commands/lint.js\";\nimport { setupCommand } from \"./commands/setup.js\";\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\nconst pkgPath = join(__dirname, \"../../package.json\");\nconst pkg = JSON.parse(readFileSync(pkgPath, \"utf-8\"));\n\nconst cmd = new Command();\n\ncmd\n  .name(\"appkit\")\n  .description(\"CLI tools for Databricks AppKit\")\n  .version(pkg.version);\n\ncmd.addCommand(setupCommand);\ncmd.addCommand(generateTypesCommand);\ncmd.addCommand(lintCommand);\ncmd.addCommand(docsCommand);\n\ncmd.parse();\n"],"mappings":";;;;;;;;;;;AAYA,MAAM,UAAU,KADE,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC,EACzB,qBAAqB;AACrD,MAAM,MAAM,KAAK,MAAM,aAAa,SAAS,QAAQ,CAAC;AAEtD,MAAM,MAAM,IAAI,SAAS;AAEzB,IACG,KAAK,SAAS,CACd,YAAY,kCAAkC,CAC9C,QAAQ,IAAI,QAAQ;AAEvB,IAAI,WAAW,aAAa;AAC5B,IAAI,WAAW,qBAAqB;AACpC,IAAI,WAAW,YAAY;AAC3B,IAAI,WAAW,YAAY;AAE3B,IAAI,OAAO"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/cli/index.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport { readFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { Command } from \"commander\";\nimport { docsCommand } from \"./commands/docs.js\";\nimport { generateTypesCommand } from \"./commands/generate-types.js\";\nimport { lintCommand } from \"./commands/lint.js\";\nimport { pluginsCommand } from \"./commands/plugins.js\";\nimport { setupCommand } from \"./commands/setup.js\";\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\nconst pkgPath = join(__dirname, \"../../package.json\");\nconst pkg = JSON.parse(readFileSync(pkgPath, \"utf-8\"));\n\nconst cmd = new Command();\n\ncmd\n  .name(\"appkit\")\n  .description(\"CLI tools for Databricks AppKit\")\n  .version(pkg.version);\n\ncmd.addCommand(setupCommand);\ncmd.addCommand(generateTypesCommand);\ncmd.addCommand(lintCommand);\ncmd.addCommand(docsCommand);\ncmd.addCommand(pluginsCommand);\n\ncmd.parse();\n"],"mappings":";;;;;;;;;;;;AAaA,MAAM,UAAU,KADE,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC,EACzB,qBAAqB;AACrD,MAAM,MAAM,KAAK,MAAM,aAAa,SAAS,QAAQ,CAAC;AAEtD,MAAM,MAAM,IAAI,SAAS;AAEzB,IACG,KAAK,SAAS,CACd,YAAY,kCAAkC,CAC9C,QAAQ,IAAI,QAAQ;AAEvB,IAAI,WAAW,aAAa;AAC5B,IAAI,WAAW,qBAAqB;AACpC,IAAI,WAAW,YAAY;AAC3B,IAAI,WAAW,YAAY;AAC3B,IAAI,WAAW,eAAe;AAE9B,IAAI,OAAO"}

package/dist/connectors/index.js

@@ -1,5 +1,5 @@
-import { LakebaseConnector } from "./lakebase/client.js";
-import "./lakebase/index.js";
+import { RequestedClaimsPermissionSet, createLakebasePool, generateDatabaseCredential, getLakebaseOrmConfig, getLakebasePgConfig, getWorkspaceClient } from "./lakebase/index.js";
+import "./lakebase-v1/index.js";
 import { SQLWarehouseConnector } from "./sql-warehouse/client.js";
 import "./sql-warehouse/index.js";
 

package/dist/connectors/lakebase/index.d.ts

@@ -0,0 +1,16 @@
+import { DatabaseCredential, GenerateDatabaseCredentialRequest, LakebasePoolConfig, LakebasePoolConfig as LakebasePoolConfig$1, RequestedClaims, RequestedClaimsPermissionSet, RequestedResource, generateDatabaseCredential, getLakebaseOrmConfig, getLakebasePgConfig, getWorkspaceClient } from "@databricks/lakebase";
+import pg from "pg";
+
+//#region src/connectors/lakebase/index.d.ts
+
+/**
+ * Create a Lakebase pool with appkit's logger integration.
+ * Telemetry automatically uses appkit's OpenTelemetry configuration via global registry.
+ *
+ * @param config - Lakebase pool configuration
+ * @returns PostgreSQL pool with appkit integration
+ */
+declare function createLakebasePool$1(config?: Partial<LakebasePoolConfig>): pg.Pool;
+//#endregion
+export { type DatabaseCredential, type GenerateDatabaseCredentialRequest, type LakebasePoolConfig$1 as LakebasePoolConfig, type RequestedClaims, RequestedClaimsPermissionSet, type RequestedResource, createLakebasePool$1 as createLakebasePool, generateDatabaseCredential, getLakebaseOrmConfig, getLakebasePgConfig, getWorkspaceClient };
+//# sourceMappingURL=index.d.ts.map

package/dist/connectors/lakebase/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/connectors/lakebase/index.ts"],"sourcesContent":[],"mappings":";;;;;;;AAcA;;;;;AAEU,iBAFM,oBAAA,CAEN,MAAA,CAAA,EADC,OACD,CADS,kBACT,CAAA,CAAA,EAAP,EAAA,CAAG,IAAI"}

package/dist/connectors/lakebase/index.js

@@ -1,3 +1,22 @@
-import { LakebaseConnector } from "./client.js";
+import { createLogger } from "../../logging/logger.js";
+import { RequestedClaimsPermissionSet, createLakebasePool, generateDatabaseCredential, getLakebaseOrmConfig, getLakebasePgConfig, getWorkspaceClient } from "@databricks/lakebase";
 
-export {  };
+//#region src/connectors/lakebase/index.ts
+/**
+* Create a Lakebase pool with appkit's logger integration.
+* Telemetry automatically uses appkit's OpenTelemetry configuration via global registry.
+*
+* @param config - Lakebase pool configuration
+* @returns PostgreSQL pool with appkit integration
+*/
+function createLakebasePool$1(config) {
+	const logger = createLogger("connectors:lakebase");
+	return createLakebasePool({
+		...config,
+		logger
+	});
+}
+
+//#endregion
+export { RequestedClaimsPermissionSet, createLakebasePool$1 as createLakebasePool, generateDatabaseCredential, getLakebaseOrmConfig, getLakebasePgConfig, getWorkspaceClient };
+//# sourceMappingURL=index.js.map

package/dist/connectors/lakebase/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["createLakebasePool","createLakebasePoolBase"],"sources":["../../../src/connectors/lakebase/index.ts"],"sourcesContent":["import {\n  createLakebasePool as createLakebasePoolBase,\n  type LakebasePoolConfig,\n} from \"@databricks/lakebase\";\nimport type pg from \"pg\";\nimport { createLogger } from \"@/logging/logger\";\n\n/**\n * Create a Lakebase pool with appkit's logger integration.\n * Telemetry automatically uses appkit's OpenTelemetry configuration via global registry.\n *\n * @param config - Lakebase pool configuration\n * @returns PostgreSQL pool with appkit integration\n */\nexport function createLakebasePool(\n  config?: Partial<LakebasePoolConfig>,\n): pg.Pool {\n  const logger = createLogger(\"connectors:lakebase\");\n\n  return createLakebasePoolBase({\n    ...config,\n    logger,\n  });\n}\n\n// Re-export everything else from lakebase\nexport {\n  createTokenRefreshCallback,\n  type DatabaseCredential,\n  type DriverTelemetry,\n  type GenerateDatabaseCredentialRequest,\n  generateDatabaseCredential,\n  getLakebaseOrmConfig,\n  getLakebasePgConfig,\n  getWorkspaceClient,\n  type LakebasePoolConfig,\n  type Logger,\n  type RequestedClaims,\n  RequestedClaimsPermissionSet,\n  type RequestedResource,\n  type TokenRefreshDeps,\n} from \"@databricks/lakebase\";\n"],"mappings":";;;;;;;;;;;AAcA,SAAgBA,qBACd,QACS;CACT,MAAM,SAAS,aAAa,sBAAsB;AAElD,QAAOC,mBAAuB;EAC5B,GAAG;EACH;EACD,CAAC"}

package/dist/connectors/lakebase-v1/client.js

@@ -0,0 +1,13 @@
+import { createLogger } from "../../logging/logger.js";
+import "../../telemetry/index.js";
+import "../../context/index.js";
+import { randomUUID } from "node:crypto";
+import "@databricks/sdk-experimental";
+import pg from "pg";
+
+//#region src/connectors/lakebase-v1/client.ts
+const logger = createLogger("connectors:lakebase-v1");
+
+//#endregion
+export {  };
+//# sourceMappingURL=client.js.map

package/dist/connectors/lakebase-v1/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","names":[],"sources":["../../../src/connectors/lakebase-v1/client.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport type { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport { ApiClient, Config } from \"@databricks/sdk-experimental\";\nimport pg from \"pg\";\nimport {\n  type Counter,\n  type Histogram,\n  SpanStatusCode,\n  TelemetryManager,\n  type TelemetryProvider,\n} from \"@/telemetry\";\nimport {\n  AppKitError,\n  AuthenticationError,\n  ConfigurationError,\n  ConnectionError,\n  ValidationError,\n} from \"../../errors\";\nimport { createLogger } from \"../../logging/logger\";\nimport { deepMerge } from \"../../utils\";\nimport { lakebaseV1Defaults } from \"./defaults\";\nimport type {\n  LakebaseV1Config,\n  LakebaseV1ConnectionConfig,\n  LakebaseV1Credentials,\n} from \"./types\";\n\nconst logger = createLogger(\"connectors:lakebase-v1\");\n\n/**\n * Enterprise-grade connector for Databricks Lakebase Provisioned\n *\n * @deprecated This connector is for Lakebase Provisioned only.\n * For new projects, use Lakebase Autoscaling instead: https://docs.databricks.com/aws/en/oltp/projects/\n *\n * This connector is compatible with Lakebase Provisioned: https://docs.databricks.com/aws/en/oltp/instances/\n *\n * Lakebase Autoscaling offers:\n * - Automatic compute scaling\n * - Scale-to-zero for cost optimization\n * - Database branching for development\n * - Instant restore capabilities\n *\n * Use the new LakebaseConnector (coming in a future release) for Lakebase Autoscaling support.\n *\n * @example Simplest - everything from env/context\n * ```typescript\n * const connector = new LakebaseV1Connector();\n * await connector.query('SELECT * FROM users');\n * ```\n *\n * @example With explicit connection string\n * ```typescript\n * const connector = new LakebaseV1Connector({\n *   connectionString: 'postgresql://...'\n * });\n * ```\n */\nexport class LakebaseV1Connector {\n  private readonly name: string = \"lakebase-v1\";\n  private readonly CACHE_BUFFER_MS = 2 * 60 * 1000;\n  private readonly config: LakebaseV1Config;\n  private readonly connectionConfig: LakebaseV1ConnectionConfig;\n  private pool: pg.Pool | null = null;\n  private credentials: LakebaseV1Credentials | null = null;\n\n  // telemetry\n  private readonly telemetry: TelemetryProvider;\n  private readonly telemetryMetrics: {\n    queryCount: Counter;\n    queryDuration: Histogram;\n  };\n\n  constructor(userConfig?: Partial<LakebaseV1Config>) {\n    this.config = deepMerge(lakebaseV1Defaults, userConfig);\n    this.connectionConfig = this.parseConnectionConfig();\n\n    this.telemetry = TelemetryManager.getProvider(\n      this.name,\n      this.config.telemetry,\n    );\n    this.telemetryMetrics = {\n      queryCount: this.telemetry\n        .getMeter()\n        .createCounter(\"lakebase.v1.query.count\", {\n          description: \"Total number of queries executed\",\n          unit: \"1\",\n        }),\n      queryDuration: this.telemetry\n        .getMeter()\n        .createHistogram(\"lakebase.v1.query.duration\", {\n          description: \"Duration of queries executed\",\n          unit: \"ms\",\n        }),\n    };\n\n    // validate configuration\n    if (this.config.maxPoolSize < 1) {\n      throw ValidationError.invalidValue(\n        \"maxPoolSize\",\n        this.config.maxPoolSize,\n        \"at least 1\",\n      );\n    }\n  }\n\n  /**\n   * Execute a SQL query\n   *\n   * @example\n   * ```typescript\n   * const users = await connector.query('SELECT * FROM users');\n   * const user = await connector.query('SELECT * FROM users WHERE id = $1', [123]);\n   * ```\n   */\n  async query<T extends pg.QueryResultRow>(\n    sql: string,\n    params?: any[],\n    retryCount: number = 0,\n  ): Promise<pg.QueryResult<T>> {\n    const startTime = Date.now();\n\n    return this.telemetry.startActiveSpan(\n      \"lakebase.v1.query\",\n      {\n        attributes: {\n          \"db.system\": \"lakebase-v1\",\n          \"db.statement\": sql.substring(0, 500),\n          \"db.retry_count\": retryCount,\n        },\n      },\n      async (span) => {\n        try {\n          const pool = await this.getPool();\n          const result = await pool.query<T>(sql, params);\n          span.setAttribute(\"db.rows_affected\", result.rowCount ?? 0);\n          span.setStatus({ code: SpanStatusCode.OK });\n          return result;\n        } catch (error) {\n          // retry on auth failure\n          if (this.isAuthError(error)) {\n            span.addEvent(\"auth_error_retry\");\n            await this.rotateCredentials();\n            const newPool = await this.getPool();\n            const result = await newPool.query<T>(sql, params);\n            span.setAttribute(\"db.rows_affected\", result.rowCount ?? 0);\n            span.setStatus({ code: SpanStatusCode.OK });\n            return result;\n          }\n\n          // retry on transient errors, but only once\n          if (this.isTransientError(error) && retryCount < 1) {\n            span.addEvent(\"transient_error_retry\");\n            await new Promise((resolve) => setTimeout(resolve, 100));\n            return await this.query<T>(sql, params, retryCount + 1);\n          }\n\n          span.recordException(error as Error);\n          span.setStatus({ code: SpanStatusCode.ERROR });\n\n          if (error instanceof AppKitError) {\n            throw error;\n          }\n          throw ConnectionError.queryFailed(error as Error);\n        } finally {\n          const duration = Date.now() - startTime;\n          this.telemetryMetrics.queryCount.add(1);\n          this.telemetryMetrics.queryDuration.record(duration);\n          span.end();\n        }\n      },\n    );\n  }\n\n  /**\n   * Execute a transaction\n   *\n   * COMMIT and ROLLBACK are automatically managed by the transaction function.\n   *\n   * @param callback - Callback function to execute within the transaction context\n   * @example\n   * ```typescript\n   * await connector.transaction(async (client) => {\n   *   await client.query('INSERT INTO accounts (name) VALUES ($1)', ['Alice']);\n   *   await client.query('INSERT INTO logs (action) VALUES ($1)', ['Created Alice']);\n   * });\n   * ```\n   */\n  async transaction<T>(\n    callback: (client: pg.PoolClient) => Promise<T>,\n    retryCount: number = 0,\n  ): Promise<T> {\n    const startTime = Date.now();\n    return this.telemetry.startActiveSpan(\n      \"lakebase.v1.transaction\",\n      {\n        attributes: {\n          \"db.system\": \"lakebase-v1\",\n          \"db.retry_count\": retryCount,\n        },\n      },\n      async (span) => {\n        const pool = await this.getPool();\n        const client = await pool.connect();\n        try {\n          await client.query(\"BEGIN\");\n          const result = await callback(client);\n          await client.query(\"COMMIT\");\n          span.setStatus({ code: SpanStatusCode.OK });\n          return result;\n        } catch (error) {\n          try {\n            await client.query(\"ROLLBACK\");\n          } catch {}\n          // retry on auth failure\n          if (this.isAuthError(error)) {\n            span.addEvent(\"auth_error_retry\");\n            client.release();\n            await this.rotateCredentials();\n            const newPool = await this.getPool();\n            const retryClient = await newPool.connect();\n            try {\n              await client.query(\"BEGIN\");\n              const result = await callback(retryClient);\n              await client.query(\"COMMIT\");\n              span.setStatus({ code: SpanStatusCode.OK });\n              return result;\n            } catch (retryError) {\n              try {\n                await retryClient.query(\"ROLLBACK\");\n              } catch {}\n              throw retryError;\n            } finally {\n              retryClient.release();\n            }\n          }\n\n          // retry on transient errors, but only once\n          if (this.isTransientError(error) && retryCount < 1) {\n            span.addEvent(\"transaction_error_retry\");\n            client.release();\n            await new Promise((resolve) => setTimeout(resolve, 100));\n            return await this.transaction<T>(callback, retryCount + 1);\n          }\n          span.recordException(error as Error);\n          span.setStatus({ code: SpanStatusCode.ERROR });\n\n          if (error instanceof AppKitError) {\n            throw error;\n          }\n          throw ConnectionError.transactionFailed(error as Error);\n        } finally {\n          client.release();\n          const duration = Date.now() - startTime;\n          this.telemetryMetrics.queryCount.add(1);\n          this.telemetryMetrics.queryDuration.record(duration);\n          span.end();\n        }\n      },\n    );\n  }\n\n  /** Check if database connection is healthy */\n  async healthCheck(): Promise<boolean> {\n    return this.telemetry.startActiveSpan(\n      \"lakebase.v1.healthCheck\",\n      {},\n      async (span) => {\n        try {\n          const result = await this.query<{ result: number }>(\n            \"SELECT 1 as result\",\n          );\n          const healthy = result.rows[0]?.result === 1;\n          span.setAttribute(\"db.healthy\", healthy);\n          span.setStatus({ code: SpanStatusCode.OK });\n          return healthy;\n        } catch {\n          span.setAttribute(\"db.healthy\", false);\n          span.setStatus({ code: SpanStatusCode.ERROR });\n          return false;\n        } finally {\n          span.end();\n        }\n      },\n    );\n  }\n\n  /** Close connection pool (call on shutdown) */\n  async close(): Promise<void> {\n    if (this.pool) {\n      await this.pool.end().catch((error: unknown) => {\n        logger.error(\"Error closing connection pool: %O\", error);\n      });\n      this.pool = null;\n    }\n    this.credentials = null;\n  }\n\n  /** Setup graceful shutdown to close connection pools */\n  shutdown(): void {\n    process.on(\"SIGTERM\", () => this.close());\n    process.on(\"SIGINT\", () => this.close());\n    this.close();\n  }\n\n  /** Get Databricks workspace client - from config or execution context */\n  private getWorkspaceClient(): WorkspaceClient {\n    if (this.config.workspaceClient) {\n      return this.config.workspaceClient;\n    }\n\n    try {\n      const { getWorkspaceClient: getClient } = require(\"../../context\");\n      const client = getClient();\n\n      // cache it for subsequent calls\n      this.config.workspaceClient = client;\n      return client;\n    } catch (_error) {\n      throw ConnectionError.clientUnavailable(\n        \"Databricks workspace client\",\n        \"Either pass it in config or ensure ServiceContext is initialized\",\n      );\n    }\n  }\n\n  /** Get or create connection pool */\n  private async getPool(): Promise<pg.Pool> {\n    if (!this.connectionConfig) {\n      throw ConfigurationError.invalidConnection(\n        \"Lakebase\",\n        \"Set PGHOST, PGDATABASE, PGAPPNAME env vars, provide a connectionString, or pass explicit config\",\n      );\n    }\n\n    if (!this.pool) {\n      const creds = await this.getCredentials();\n      this.pool = this.createPool(creds);\n    }\n    return this.pool;\n  }\n\n  /** Create PostgreSQL pool */\n  private createPool(credentials: {\n    username: string;\n    password: string;\n  }): pg.Pool {\n    const { host, database, port, sslMode } = this.connectionConfig;\n\n    const pool = new pg.Pool({\n      host,\n      port,\n      database,\n      user: credentials.username,\n      password: credentials.password,\n      max: this.config.maxPoolSize,\n      idleTimeoutMillis: this.config.idleTimeoutMs,\n      connectionTimeoutMillis: this.config.connectionTimeoutMs,\n      ssl: sslMode === \"require\" ? { rejectUnauthorized: true } : false,\n    });\n\n    pool.on(\"error\", (error: Error & { code?: string }) => {\n      logger.error(\n        \"Connection pool error: %s (code: %s)\",\n        error.message,\n        error.code,\n      );\n    });\n\n    return pool;\n  }\n\n  /** Get or fetch credentials with caching */\n  private async getCredentials(): Promise<{\n    username: string;\n    password: string;\n  }> {\n    const now = Date.now();\n\n    // return cached if still valid\n    if (\n      this.credentials &&\n      now < this.credentials.expiresAt - this.CACHE_BUFFER_MS\n    ) {\n      return this.credentials;\n    }\n\n    // fetch new credentials\n    const username = await this.fetchUsername();\n    const { token, expiresAt } = await this.fetchPassword();\n\n    this.credentials = {\n      username,\n      password: token,\n      expiresAt,\n    };\n\n    return { username, password: token };\n  }\n\n  /** Rotate credentials and recreate pool */\n  private async rotateCredentials(): Promise<void> {\n    // clear cached credentials\n    this.credentials = null;\n\n    if (this.pool) {\n      const oldPool = this.pool;\n      this.pool = null;\n      oldPool.end().catch((error: unknown) => {\n        logger.error(\n          \"Error closing old connection pool during rotation: %O\",\n          error,\n        );\n      });\n    }\n  }\n\n  /** Fetch username from Databricks */\n  private async fetchUsername(): Promise<string> {\n    const workspaceClient = this.getWorkspaceClient();\n    const user = await workspaceClient.currentUser.me();\n    if (!user.userName) {\n      throw AuthenticationError.userLookupFailed();\n    }\n    return user.userName;\n  }\n\n  /** Fetch password (OAuth token) from Databricks */\n  private async fetchPassword(): Promise<{ token: string; expiresAt: number }> {\n    const workspaceClient = this.getWorkspaceClient();\n    const config = new Config({ host: workspaceClient.config.host });\n    const apiClient = new ApiClient(config);\n\n    if (!this.connectionConfig.appName) {\n      throw ConfigurationError.resourceNotFound(\"Database app name\");\n    }\n\n    const credentials = await apiClient.request({\n      path: `/api/2.0/database/credentials`,\n      method: \"POST\",\n      headers: new Headers(),\n      raw: false,\n      payload: {\n        instance_names: [this.connectionConfig.appName],\n        request_id: randomUUID(),\n      },\n    });\n\n    if (!this.validateCredentials(credentials)) {\n      throw AuthenticationError.credentialsFailed(\n        this.connectionConfig.appName,\n      );\n    }\n\n    const expiresAt = new Date(credentials.expiration_time).getTime();\n\n    return { token: credentials.token, expiresAt };\n  }\n\n  /** Check if error is auth failure */\n  private isAuthError(error: unknown): boolean {\n    return (\n      typeof error === \"object\" &&\n      error !== null &&\n      \"code\" in error &&\n      (error as any).code === \"28P01\"\n    );\n  }\n\n  /** Check if error is transient */\n  private isTransientError(error: unknown): boolean {\n    if (typeof error !== \"object\" || error === null || !(\"code\" in error)) {\n      return false;\n    }\n\n    const code = (error as any).code;\n    return (\n      code === \"ECONNRESET\" ||\n      code === \"ECONNREFUSED\" ||\n      code === \"ETIMEDOUT\" ||\n      code === \"57P01\" || // admin_shutdown\n      code === \"57P03\" || // cannot_connect_now\n      code === \"08006\" || // connection_failure\n      code === \"08003\" || // connection_does_not_exist\n      code === \"08000\" // connection_exception\n    );\n  }\n\n  /** Type guard for credentials */\n  private validateCredentials(\n    value: unknown,\n  ): value is { token: string; expiration_time: string } {\n    if (typeof value !== \"object\" || value === null) {\n      return false;\n    }\n\n    const credentials = value as { token: string; expiration_time: string };\n    return (\n      \"token\" in credentials &&\n      typeof credentials.token === \"string\" &&\n      \"expiration_time\" in credentials &&\n      typeof credentials.expiration_time === \"string\" &&\n      new Date(credentials.expiration_time).getTime() > Date.now()\n    );\n  }\n\n  /** Parse connection configuration from config or environment */\n  private parseConnectionConfig(): LakebaseV1ConnectionConfig {\n    if (this.config.connectionString) {\n      return this.parseConnectionString(this.config.connectionString);\n    }\n\n    // get connection from config\n    if (this.config.host && this.config.database && this.config.appName) {\n      return {\n        host: this.config.host,\n        database: this.config.database,\n        port: this.config.port ?? 5432,\n        sslMode: this.config.sslMode ?? \"require\",\n        appName: this.config.appName,\n      };\n    }\n\n    // get connection from environment variables\n    const pgHost = process.env.PGHOST;\n    const pgDatabase = process.env.PGDATABASE;\n    const pgAppName = process.env.PGAPPNAME;\n    if (!pgHost || !pgDatabase || !pgAppName) {\n      throw ConfigurationError.invalidConnection(\n        \"Lakebase\",\n        \"Required env vars: PGHOST, PGDATABASE, PGAPPNAME. Optional: PGPORT (default: 5432), PGSSLMODE (default: require)\",\n      );\n    }\n    const pgPort = process.env.PGPORT;\n    const port = pgPort ? parseInt(pgPort, 10) : 5432;\n\n    if (Number.isNaN(port)) {\n      throw ValidationError.invalidValue(\"port\", pgPort, \"a number\");\n    }\n\n    const pgSSLMode = process.env.PGSSLMODE;\n    const sslMode =\n      (pgSSLMode as \"require\" | \"disable\" | \"prefer\") || \"require\";\n\n    return {\n      host: pgHost,\n      database: pgDatabase,\n      port,\n      sslMode,\n      appName: pgAppName,\n    };\n  }\n\n  private parseConnectionString(\n    connectionString: string,\n  ): LakebaseV1ConnectionConfig {\n    const url = new URL(connectionString);\n    const appName = url.searchParams.get(\"appName\");\n    if (!appName) {\n      throw ConfigurationError.missingConnectionParam(\"appName\");\n    }\n\n    return {\n      host: url.hostname,\n      database: url.pathname.slice(1), // remove leading slash\n      port: url.port ? parseInt(url.port, 10) : 5432,\n      sslMode:\n        (url.searchParams.get(\"sslmode\") as \"require\" | \"disable\" | \"prefer\") ??\n        \"require\",\n      appName: appName,\n    };\n  }\n}\n"],"mappings":";;;;;;;;AA2BA,MAAM,SAAS,aAAa,yBAAyB"}

package/dist/connectors/lakebase-v1/index.js

@@ -0,0 +1,3 @@
+import "./client.js";
+
+export {  };

package/dist/connectors/sql-warehouse/client.js

@@ -1,11 +1,11 @@
 import { createLogger } from "../../logging/logger.js";
-import { TelemetryManager } from "../../telemetry/telemetry-manager.js";
-import { SpanKind, SpanStatusCode } from "../../telemetry/index.js";
 import { AppKitError } from "../../errors/base.js";
 import { ConnectionError } from "../../errors/connection.js";
 import { ExecutionError } from "../../errors/execution.js";
 import { ValidationError } from "../../errors/validation.js";
 import { init_errors } from "../../errors/index.js";
+import { TelemetryManager } from "../../telemetry/telemetry-manager.js";
+import { SpanKind, SpanStatusCode } from "../../telemetry/index.js";
 import { ArrowStreamProcessor } from "../../stream/arrow-stream-processor.js";
 import { executeStatementDefaults } from "./defaults.js";
 import { Context } from "@databricks/sdk-experimental";