@databricks/appkit 0.43.0 → 0.44.0

package/CLAUDE.md

@@ -211,7 +211,6 @@ npx @databricks/appkit docs <query>
 - [Calendar](./docs/api/appkit-ui/ui/Calendar.md): Date picker component for selecting single dates or date ranges
 - [Card](./docs/api/appkit-ui/ui/Card.md): Container for grouping related content with header, body, and footer sections
 - [Carousel](./docs/api/appkit-ui/ui/Carousel.md): Slideshow component for cycling through content with navigation controls
-- [ChartContainer](./docs/api/appkit-ui/ui/ChartContainer.md): Container for rendering data visualizations using Recharts
 - [Checkbox](./docs/api/appkit-ui/ui/Checkbox.md): Checkbox input for selecting multiple options
 - [Collapsible](./docs/api/appkit-ui/ui/Collapsible.md): Interactive component that expands and collapses content
 - [Command](./docs/api/appkit-ui/ui/Command.md): Command palette for keyboard-driven navigation and actions

package/NOTICE.md

@@ -59,6 +59,7 @@ This Software contains code from the following open source projects:
 | [commander](https://www.npmjs.com/package/commander) | 2.20.3, 5.1.0, 7.2.0, 8.3.0, 10.0.1, 12.1.0 | MIT | https://github.com/tj/commander.js#readme |
 | [dompurify](https://www.npmjs.com/package/dompurify) | 3.4.11 | (MPL-2.0 OR Apache-2.0) | https://github.com/cure53/DOMPurify |
 | [dotenv](https://www.npmjs.com/package/dotenv) | 16.6.1 | BSD-2-Clause | https://github.com/motdotla/dotenv#readme |
+| [drizzle-orm](https://www.npmjs.com/package/drizzle-orm) | 0.45.1 | Apache-2.0 | https://orm.drizzle.team |
 | [echarts](https://www.npmjs.com/package/echarts) | 6.0.0 | Apache-2.0 | https://echarts.apache.org |
 | [echarts-for-react](https://www.npmjs.com/package/echarts-for-react) | 3.0.5 | MIT | https://github.com/hustcc/echarts-for-react |
 | [embla-carousel-react](https://www.npmjs.com/package/embla-carousel-react) | 8.6.0 | MIT | https://www.embla-carousel.com |

package/dist/appkit/package.js

@@ -1,6 +1,6 @@
 //#region package.json
 var name = "@databricks/appkit";
-var version = "0.43.0";
+var version = "0.44.0";
 
 //#endregion
 export { name, version };

package/dist/cli/commands/generate-types.js

@@ -42,6 +42,11 @@ async function runGenerateTypes(rootDir, outFile, warehouseId, options) {
 					mode
 				});
 				console.log(`Generated query types: ${resolvedOutFile}`);
+				const metricConfig = path.join(queryFolder, "metric-views.json");
+				if (fs.existsSync(metricConfig)) {
+					const typesDir = path.dirname(resolvedOutFile);
+					console.log(`Generated metric types: ${path.join(typesDir, "metric-views.d.ts")}`);
+				}
 			}
 		} else console.error("Skipping query type generation: no warehouse ID. Set DATABRICKS_WAREHOUSE_ID or pass as argument.");
 		const servingOutFile = path.join(process.cwd(), "shared/appkit-types/serving.d.ts");

package/dist/cli/commands/generate-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"generate-types.js","names":[],"sources":["../../../src/cli/commands/generate-types.ts"],"sourcesContent":["import { spawn } from \"node:child_process\";\nimport fs from \"node:fs\";\nimport path from \"node:path\";\nimport { Command, Option } from \"commander\";\nimport {\n  acquireSpawnLock,\n  getSpawnLockPath,\n  releaseSpawnLock,\n} from \"./spawn-lock.js\";\n\n/**\n * Resolve the typegen pre-flight mode for the CLI. Defaults to \"non-blocking\" —\n * a one-shot CLI can't describe in the background, so by default it never\n * describes at all: it skips the warehouse probe AND every DESCRIBE, emits\n * best-available types (cache where the SQL hash matches, else `result: unknown`)\n * and returns immediately, never blocking on — or failing because of — a\n * warehouse, even a RUNNING one. Pass `--wait` (commander sets `wait: true`)\n * for a deliberate/CI invocation that should wait for a starting warehouse and\n * fail fast on a stopped one.\n */\nexport function resolveTypegenMode(options?: {\n  wait?: boolean;\n}): \"non-blocking\" | \"blocking\" {\n  return options?.wait ? \"blocking\" : \"non-blocking\";\n}\n\n/** Options parsed by commander for the generate-types command. */\ninterface GenerateTypesOptions {\n  noCache?: boolean;\n  wait?: boolean;\n  /**\n   * Internal: present only on the detached worker invocation. Carries the path\n   * of the single-flight lock this worker must release when it finishes. Its\n   * presence is what marks an invocation as \"the worker\" — workers always run\n   * with `--wait`, so they never spawn another worker (only non-blocking runs\n   * spawn), which terminates the recursion.\n   */\n  workerLock?: string;\n}\n\n/**\n * Generate types command implementation. Runs the library generate (which, in\n * non-blocking mode, writes degraded types and returns immediately). This is the\n * SAME work the worker performs in blocking mode in the background.\n */\nasync function runGenerateTypes(\n  rootDir?: string,\n  outFile?: string,\n  warehouseId?: string,\n  options?: GenerateTypesOptions,\n) {\n  try {\n    const resolvedRootDir = rootDir || process.cwd();\n    const noCache = options?.noCache || false;\n    const mode = resolveTypegenMode(options);\n\n    const typeGen = await import(\"@databricks/appkit/type-generator\");\n\n    // Generate analytics query types (requires warehouse ID)\n    const resolvedWarehouseId =\n      warehouseId || process.env.DATABRICKS_WAREHOUSE_ID;\n\n    if (resolvedWarehouseId) {\n      const resolvedOutFile =\n        outFile ||\n        path.join(process.cwd(), \"shared/appkit-types/analytics.d.ts\");\n\n      const queryFolder = path.join(resolvedRootDir, \"config/queries\");\n      if (fs.existsSync(queryFolder)) {\n        await typeGen.generateFromEntryPoint({\n          queryFolder,\n          outFile: resolvedOutFile,\n          warehouseId: resolvedWarehouseId,\n          noCache,\n          mode,\n        });\n        console.log(`Generated query types: ${resolvedOutFile}`);\n      }\n    } else {\n      console.error(\n        \"Skipping query type generation: no warehouse ID. Set DATABRICKS_WAREHOUSE_ID or pass as argument.\",\n      );\n    }\n\n    // Generate serving endpoint types (no warehouse required)\n    const servingOutFile = path.join(\n      process.cwd(),\n      \"shared/appkit-types/serving.d.ts\",\n    );\n    await typeGen.generateServingTypes({\n      outFile: servingOutFile,\n      noCache,\n    });\n    console.log(`Generated serving types: ${servingOutFile}`);\n  } catch (error) {\n    if (\n      error instanceof Error &&\n      error.message.includes(\"Cannot find module\")\n    ) {\n      console.error(\n        \"Error: The 'generate-types' command is only available in @databricks/appkit.\",\n      );\n      console.error(\"Please install @databricks/appkit to use this command.\");\n      process.exit(1);\n    }\n    // TypegenSyntaxError / TypegenFatalError carry a complete, actionable\n    // message (which queries failed and how to debug them). The stack trace\n    // points into appkit internals and is noise for app developers, so print\n    // only the message and exit non-zero instead of letting it bubble up.\n    if (\n      error instanceof Error &&\n      (error.name === \"TypegenSyntaxError\" ||\n        error.name === \"TypegenFatalError\")\n    ) {\n      console.error(error.message);\n      process.exit(1);\n    }\n    throw error;\n  }\n}\n\n/**\n * Spawn the detached blocking worker that refreshes real types in the background\n * after the foreground non-blocking generate has already written degraded types.\n *\n * Re-invokes THIS CLI (`process.execPath` + `process.argv[1]` — the bin entry\n * that launched us) with `generate-types --wait --worker-lock <lockPath>` plus\n * the same positional target options the foreground used, so the worker writes\n * to the same out file / reads the same query folder. The worker is:\n *  - `detached: true` + `.unref()` so it outlives this process (install/dev-setup\n *    can finish and exit while the worker keeps warming the warehouse).\n *  - `stdio: \"ignore\"` so it never holds the parent's pipes open or interleaves\n *    output into the install/dev log.\n *\n * Spawning is wrapped so any failure is non-fatal: the caller still has degraded\n * types and exits 0.\n *\n * @param lockPath - the acquired single-flight lock; passed to the worker so it\n *   releases the SAME lock when it finishes.\n * @param targets - the foreground's positional args, forwarded verbatim.\n * @returns true if the worker was spawned, false if spawning threw.\n */\nexport function spawnTypegenWorker(\n  lockPath: string,\n  targets: { rootDir?: string; outFile?: string; warehouseId?: string },\n): boolean {\n  // The script the runtime launched us with (the `appkit` bin shim). Re-running\n  // it under the same node binary reproduces this exact CLI in the worker.\n  const cliEntry = process.argv[1];\n\n  // Forward the positionals in declaration order (rootDir, outFile,\n  // warehouseId). Stop at the first undefined so we never pass a literal\n  // \"undefined\" — commander would treat it as a positional value. (rootDir is\n  // effectively always set by commander's default, but guard anyway.)\n  const positionals: string[] = [];\n  for (const value of [targets.rootDir, targets.outFile, targets.warehouseId]) {\n    if (value === undefined) break;\n    positionals.push(value);\n  }\n\n  const args = [\n    // Forward the parent's node/loader flags so the worker runs under the same\n    // runtime. Critically this carries tsx's `--require`/`--import` when the CLI\n    // is run from source (`tsx index.ts …`); without them the worker would be\n    // `node index.ts …`, which can't parse TypeScript and dies silently — the\n    // degraded types would then never refresh. Empty for the built bin (plain\n    // `node bin/appkit.js`), so production behaviour is unchanged.\n    ...process.execArgv,\n    cliEntry,\n    \"generate-types\",\n    \"--wait\",\n    \"--worker-lock\",\n    lockPath,\n    ...positionals,\n  ];\n\n  try {\n    const child = spawn(process.execPath, args, {\n      detached: true,\n      stdio: \"ignore\",\n    });\n    child.unref();\n    return true;\n  } catch (error) {\n    // Non-fatal: the foreground already wrote degraded types. Log and move on.\n    console.error(\n      `Could not start background type refresh: ${\n        error instanceof Error ? error.message : String(error)\n      }`,\n    );\n    return false;\n  }\n}\n\n/**\n * The command action. Orchestrates the non-blocking foreground contract:\n *  1. Run the library generate (writes degraded types immediately in non-blocking\n *     mode; does the full blocking lifecycle when this is the worker).\n *  2. If this is a non-blocking, non-worker invocation, try to spawn the detached\n *     blocking worker behind the single-flight lock. If the lock is already held\n *     by a live worker, skip (single-flight) with a one-line note. Either way the\n *     foreground returns normally (exit 0).\n *  3. If this IS the worker (`--worker-lock` present), it ran blocking above and\n *     releases the lock here (and via a process-exit guard, so a hard failure /\n *     process.exit still frees it).\n */\nasync function generateTypesAction(\n  rootDir: string | undefined,\n  outFile: string | undefined,\n  warehouseId: string | undefined,\n  options: GenerateTypesOptions,\n) {\n  const isWorker = typeof options.workerLock === \"string\";\n\n  // A worker must always free its lock, even if the blocking generate throws or\n  // calls process.exit (TypegenFatalError → exit 1). The exit handler covers the\n  // process.exit / uncaught paths; the finally covers the normal return.\n  if (isWorker && options.workerLock) {\n    const lockPath = options.workerLock;\n    process.once(\"exit\", () => releaseSpawnLock(lockPath));\n  }\n\n  try {\n    await runGenerateTypes(rootDir, outFile, warehouseId, options);\n  } finally {\n    if (isWorker && options.workerLock) {\n      releaseSpawnLock(options.workerLock);\n    }\n  }\n\n  // Only a non-blocking, non-worker invocation spawns. A worker is always\n  // --wait (so resolveTypegenMode → \"blocking\"), which both prevents recursion\n  // and means we never get here for a worker.\n  if (!isWorker && resolveTypegenMode(options) === \"non-blocking\") {\n    const resolvedRootDir = rootDir || process.cwd();\n    const lockPath = getSpawnLockPath(resolvedRootDir);\n\n    if (acquireSpawnLock(lockPath)) {\n      spawnTypegenWorker(lockPath, { rootDir, outFile, warehouseId });\n    } else {\n      console.log(\"Type refresh already in progress, skipping.\");\n    }\n  }\n}\n\nexport const generateTypesCommand = new Command(\"generate-types\")\n  .description(\"Generate TypeScript types from SQL queries\")\n  .argument(\"[rootDir]\", \"Root directory of the project\", process.cwd())\n  .argument(\n    \"[outFile]\",\n    \"Output file path\",\n    path.join(process.cwd(), \"shared/appkit-types/analytics.d.ts\"),\n  )\n  .argument(\"[warehouseId]\", \"Databricks warehouse ID\")\n  .option(\"--no-cache\", \"Disable caching for type generation\")\n  .option(\n    \"--wait\",\n    \"Wait for warehouse readiness instead of degrading (use for CI)\",\n  )\n  // Internal: marks the detached background worker and carries the lock it must\n  // release. Hidden from --help; users should never pass it.\n  .addOption(\n    new Option(\n      \"--worker-lock <path>\",\n      \"Internal: detached worker lock path\",\n    ).hideHelp(),\n  )\n  .addHelpText(\n    \"after\",\n    `\nExamples:\n  $ appkit generate-types\n  $ appkit generate-types . shared/appkit-types/analytics.d.ts\n  $ appkit generate-types . shared/appkit-types/analytics.d.ts my-warehouse-id\n  $ appkit generate-types --no-cache\n  $ appkit generate-types --wait   # CI: wait for the warehouse and fail on a cold one`,\n  )\n  .action(generateTypesAction);\n"],"mappings":"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"}
+{"version":3,"file":"generate-types.js","names":[],"sources":["../../../src/cli/commands/generate-types.ts"],"sourcesContent":["import { spawn } from \"node:child_process\";\nimport fs from \"node:fs\";\nimport path from \"node:path\";\nimport { Command, Option } from \"commander\";\nimport {\n  acquireSpawnLock,\n  getSpawnLockPath,\n  releaseSpawnLock,\n} from \"./spawn-lock.js\";\n\n/**\n * Resolve the typegen pre-flight mode for the CLI. Defaults to \"non-blocking\" —\n * a one-shot CLI can't describe in the background, so by default it never\n * describes at all: it skips the warehouse probe AND every DESCRIBE, emits\n * best-available types (cache where the SQL hash matches, else `result: unknown`)\n * and returns immediately, never blocking on — or failing because of — a\n * warehouse, even a RUNNING one. Pass `--wait` (commander sets `wait: true`)\n * for a deliberate/CI invocation that should wait for a starting warehouse and\n * fail fast on a stopped one.\n */\nexport function resolveTypegenMode(options?: {\n  wait?: boolean;\n}): \"non-blocking\" | \"blocking\" {\n  return options?.wait ? \"blocking\" : \"non-blocking\";\n}\n\n/** Options parsed by commander for the generate-types command. */\ninterface GenerateTypesOptions {\n  noCache?: boolean;\n  wait?: boolean;\n  /**\n   * Internal: present only on the detached worker invocation. Carries the path\n   * of the single-flight lock this worker must release when it finishes. Its\n   * presence is what marks an invocation as \"the worker\" — workers always run\n   * with `--wait`, so they never spawn another worker (only non-blocking runs\n   * spawn), which terminates the recursion.\n   */\n  workerLock?: string;\n}\n\n/**\n * Generate types command implementation. Runs the library generate (which, in\n * non-blocking mode, writes degraded types and returns immediately). This is the\n * SAME work the worker performs in blocking mode in the background.\n */\nasync function runGenerateTypes(\n  rootDir?: string,\n  outFile?: string,\n  warehouseId?: string,\n  options?: GenerateTypesOptions,\n) {\n  try {\n    const resolvedRootDir = rootDir || process.cwd();\n    const noCache = options?.noCache || false;\n    const mode = resolveTypegenMode(options);\n\n    const typeGen = await import(\"@databricks/appkit/type-generator\");\n\n    // Generate analytics query types (requires warehouse ID)\n    const resolvedWarehouseId =\n      warehouseId || process.env.DATABRICKS_WAREHOUSE_ID;\n\n    if (resolvedWarehouseId) {\n      const resolvedOutFile =\n        outFile ||\n        path.join(process.cwd(), \"shared/appkit-types/analytics.d.ts\");\n\n      const queryFolder = path.join(resolvedRootDir, \"config/queries\");\n      if (fs.existsSync(queryFolder)) {\n        await typeGen.generateFromEntryPoint({\n          queryFolder,\n          outFile: resolvedOutFile,\n          warehouseId: resolvedWarehouseId,\n          noCache,\n          mode,\n        });\n        console.log(`Generated query types: ${resolvedOutFile}`);\n\n        const metricConfig = path.join(queryFolder, \"metric-views.json\");\n        if (fs.existsSync(metricConfig)) {\n          const typesDir = path.dirname(resolvedOutFile);\n          console.log(\n            `Generated metric types: ${path.join(typesDir, \"metric-views.d.ts\")}`,\n          );\n        }\n      }\n    } else {\n      console.error(\n        \"Skipping query type generation: no warehouse ID. Set DATABRICKS_WAREHOUSE_ID or pass as argument.\",\n      );\n    }\n\n    // Generate serving endpoint types (no warehouse required)\n    const servingOutFile = path.join(\n      process.cwd(),\n      \"shared/appkit-types/serving.d.ts\",\n    );\n    await typeGen.generateServingTypes({\n      outFile: servingOutFile,\n      noCache,\n    });\n    console.log(`Generated serving types: ${servingOutFile}`);\n  } catch (error) {\n    if (\n      error instanceof Error &&\n      error.message.includes(\"Cannot find module\")\n    ) {\n      console.error(\n        \"Error: The 'generate-types' command is only available in @databricks/appkit.\",\n      );\n      console.error(\"Please install @databricks/appkit to use this command.\");\n      process.exit(1);\n    }\n    // TypegenSyntaxError / TypegenFatalError carry a complete, actionable\n    // message (which queries failed and how to debug them). The stack trace\n    // points into appkit internals and is noise for app developers, so print\n    // only the message and exit non-zero instead of letting it bubble up.\n    if (\n      error instanceof Error &&\n      (error.name === \"TypegenSyntaxError\" ||\n        error.name === \"TypegenFatalError\")\n    ) {\n      console.error(error.message);\n      process.exit(1);\n    }\n    throw error;\n  }\n}\n\n/**\n * Spawn the detached blocking worker that refreshes real types in the background\n * after the foreground non-blocking generate has already written degraded types.\n *\n * Re-invokes THIS CLI (`process.execPath` + `process.argv[1]` — the bin entry\n * that launched us) with `generate-types --wait --worker-lock <lockPath>` plus\n * the same positional target options the foreground used, so the worker writes\n * to the same out file / reads the same query folder. The worker is:\n *  - `detached: true` + `.unref()` so it outlives this process (install/dev-setup\n *    can finish and exit while the worker keeps warming the warehouse).\n *  - `stdio: \"ignore\"` so it never holds the parent's pipes open or interleaves\n *    output into the install/dev log.\n *\n * Spawning is wrapped so any failure is non-fatal: the caller still has degraded\n * types and exits 0.\n *\n * @param lockPath - the acquired single-flight lock; passed to the worker so it\n *   releases the SAME lock when it finishes.\n * @param targets - the foreground's positional args, forwarded verbatim.\n * @returns true if the worker was spawned, false if spawning threw.\n */\nexport function spawnTypegenWorker(\n  lockPath: string,\n  targets: { rootDir?: string; outFile?: string; warehouseId?: string },\n): boolean {\n  // The script the runtime launched us with (the `appkit` bin shim). Re-running\n  // it under the same node binary reproduces this exact CLI in the worker.\n  const cliEntry = process.argv[1];\n\n  // Forward the positionals in declaration order (rootDir, outFile,\n  // warehouseId). Stop at the first undefined so we never pass a literal\n  // \"undefined\" — commander would treat it as a positional value. (rootDir is\n  // effectively always set by commander's default, but guard anyway.)\n  const positionals: string[] = [];\n  for (const value of [targets.rootDir, targets.outFile, targets.warehouseId]) {\n    if (value === undefined) break;\n    positionals.push(value);\n  }\n\n  const args = [\n    // Forward the parent's node/loader flags so the worker runs under the same\n    // runtime. Critically this carries tsx's `--require`/`--import` when the CLI\n    // is run from source (`tsx index.ts …`); without them the worker would be\n    // `node index.ts …`, which can't parse TypeScript and dies silently — the\n    // degraded types would then never refresh. Empty for the built bin (plain\n    // `node bin/appkit.js`), so production behaviour is unchanged.\n    ...process.execArgv,\n    cliEntry,\n    \"generate-types\",\n    \"--wait\",\n    \"--worker-lock\",\n    lockPath,\n    ...positionals,\n  ];\n\n  try {\n    const child = spawn(process.execPath, args, {\n      detached: true,\n      stdio: \"ignore\",\n    });\n    child.unref();\n    return true;\n  } catch (error) {\n    // Non-fatal: the foreground already wrote degraded types. Log and move on.\n    console.error(\n      `Could not start background type refresh: ${\n        error instanceof Error ? error.message : String(error)\n      }`,\n    );\n    return false;\n  }\n}\n\n/**\n * The command action. Orchestrates the non-blocking foreground contract:\n *  1. Run the library generate (writes degraded types immediately in non-blocking\n *     mode; does the full blocking lifecycle when this is the worker).\n *  2. If this is a non-blocking, non-worker invocation, try to spawn the detached\n *     blocking worker behind the single-flight lock. If the lock is already held\n *     by a live worker, skip (single-flight) with a one-line note. Either way the\n *     foreground returns normally (exit 0).\n *  3. If this IS the worker (`--worker-lock` present), it ran blocking above and\n *     releases the lock here (and via a process-exit guard, so a hard failure /\n *     process.exit still frees it).\n */\nasync function generateTypesAction(\n  rootDir: string | undefined,\n  outFile: string | undefined,\n  warehouseId: string | undefined,\n  options: GenerateTypesOptions,\n) {\n  const isWorker = typeof options.workerLock === \"string\";\n\n  // A worker must always free its lock, even if the blocking generate throws or\n  // calls process.exit (TypegenFatalError → exit 1). The exit handler covers the\n  // process.exit / uncaught paths; the finally covers the normal return.\n  if (isWorker && options.workerLock) {\n    const lockPath = options.workerLock;\n    process.once(\"exit\", () => releaseSpawnLock(lockPath));\n  }\n\n  try {\n    await runGenerateTypes(rootDir, outFile, warehouseId, options);\n  } finally {\n    if (isWorker && options.workerLock) {\n      releaseSpawnLock(options.workerLock);\n    }\n  }\n\n  // Only a non-blocking, non-worker invocation spawns. A worker is always\n  // --wait (so resolveTypegenMode → \"blocking\"), which both prevents recursion\n  // and means we never get here for a worker.\n  if (!isWorker && resolveTypegenMode(options) === \"non-blocking\") {\n    const resolvedRootDir = rootDir || process.cwd();\n    const lockPath = getSpawnLockPath(resolvedRootDir);\n\n    if (acquireSpawnLock(lockPath)) {\n      spawnTypegenWorker(lockPath, { rootDir, outFile, warehouseId });\n    } else {\n      console.log(\"Type refresh already in progress, skipping.\");\n    }\n  }\n}\n\nexport const generateTypesCommand = new Command(\"generate-types\")\n  .description(\"Generate TypeScript types from SQL queries\")\n  .argument(\"[rootDir]\", \"Root directory of the project\", process.cwd())\n  .argument(\n    \"[outFile]\",\n    \"Output file path\",\n    path.join(process.cwd(), \"shared/appkit-types/analytics.d.ts\"),\n  )\n  .argument(\"[warehouseId]\", \"Databricks warehouse ID\")\n  .option(\"--no-cache\", \"Disable caching for type generation\")\n  .option(\n    \"--wait\",\n    \"Wait for warehouse readiness instead of degrading (use for CI)\",\n  )\n  // Internal: marks the detached background worker and carries the lock it must\n  // release. Hidden from --help; users should never pass it.\n  .addOption(\n    new Option(\n      \"--worker-lock <path>\",\n      \"Internal: detached worker lock path\",\n    ).hideHelp(),\n  )\n  .addHelpText(\n    \"after\",\n    `\nExamples:\n  $ appkit generate-types\n  $ appkit generate-types . shared/appkit-types/analytics.d.ts\n  $ appkit generate-types . shared/appkit-types/analytics.d.ts my-warehouse-id\n  $ appkit generate-types --no-cache\n  $ appkit generate-types --wait   # CI: wait for the warehouse and fail on a cold one`,\n  )\n  .action(generateTypesAction);\n"],"mappings":";;;;;;;;;;;;;;;;;AAoBA,SAAgB,mBAAmB,SAEH;AAC9B,QAAO,SAAS,OAAO,aAAa;;;;;;;AAsBtC,eAAe,iBACb,SACA,SACA,aACA,SACA;AACA,KAAI;EACF,MAAM,kBAAkB,WAAW,QAAQ,KAAK;EAChD,MAAM,UAAU,SAAS,WAAW;EACpC,MAAM,OAAO,mBAAmB,QAAQ;EAExC,MAAM,UAAU,MAAM,OAAO;EAG7B,MAAM,sBACJ,eAAe,QAAQ,IAAI;AAE7B,MAAI,qBAAqB;GACvB,MAAM,kBACJ,WACA,KAAK,KAAK,QAAQ,KAAK,EAAE,qCAAqC;GAEhE,MAAM,cAAc,KAAK,KAAK,iBAAiB,iBAAiB;AAChE,OAAI,GAAG,WAAW,YAAY,EAAE;AAC9B,UAAM,QAAQ,uBAAuB;KACnC;KACA,SAAS;KACT,aAAa;KACb;KACA;KACD,CAAC;AACF,YAAQ,IAAI,0BAA0B,kBAAkB;IAExD,MAAM,eAAe,KAAK,KAAK,aAAa,oBAAoB;AAChE,QAAI,GAAG,WAAW,aAAa,EAAE;KAC/B,MAAM,WAAW,KAAK,QAAQ,gBAAgB;AAC9C,aAAQ,IACN,2BAA2B,KAAK,KAAK,UAAU,oBAAoB,GACpE;;;QAIL,SAAQ,MACN,oGACD;EAIH,MAAM,iBAAiB,KAAK,KAC1B,QAAQ,KAAK,EACb,mCACD;AACD,QAAM,QAAQ,qBAAqB;GACjC,SAAS;GACT;GACD,CAAC;AACF,UAAQ,IAAI,4BAA4B,iBAAiB;UAClD,OAAO;AACd,MACE,iBAAiB,SACjB,MAAM,QAAQ,SAAS,qBAAqB,EAC5C;AACA,WAAQ,MACN,+EACD;AACD,WAAQ,MAAM,yDAAyD;AACvE,WAAQ,KAAK,EAAE;;AAMjB,MACE,iBAAiB,UAChB,MAAM,SAAS,wBACd,MAAM,SAAS,sBACjB;AACA,WAAQ,MAAM,MAAM,QAAQ;AAC5B,WAAQ,KAAK,EAAE;;AAEjB,QAAM;;;;;;;;;;;;;;;;;;;;;;;;AAyBV,SAAgB,mBACd,UACA,SACS;CAGT,MAAM,WAAW,QAAQ,KAAK;CAM9B,MAAM,cAAwB,EAAE;AAChC,MAAK,MAAM,SAAS;EAAC,QAAQ;EAAS,QAAQ;EAAS,QAAQ;EAAY,EAAE;AAC3E,MAAI,UAAU,OAAW;AACzB,cAAY,KAAK,MAAM;;CAGzB,MAAM,OAAO;EAOX,GAAG,QAAQ;EACX;EACA;EACA;EACA;EACA;EACA,GAAG;EACJ;AAED,KAAI;AAKF,EAJc,MAAM,QAAQ,UAAU,MAAM;GAC1C,UAAU;GACV,OAAO;GACR,CAAC,CACI,OAAO;AACb,SAAO;UACA,OAAO;AAEd,UAAQ,MACN,4CACE,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM,GAEzD;AACD,SAAO;;;;;;;;;;;;;;;AAgBX,eAAe,oBACb,SACA,SACA,aACA,SACA;CACA,MAAM,WAAW,OAAO,QAAQ,eAAe;AAK/C,KAAI,YAAY,QAAQ,YAAY;EAClC,MAAM,WAAW,QAAQ;AACzB,UAAQ,KAAK,cAAc,iBAAiB,SAAS,CAAC;;AAGxD,KAAI;AACF,QAAM,iBAAiB,SAAS,SAAS,aAAa,QAAQ;WACtD;AACR,MAAI,YAAY,QAAQ,WACtB,kBAAiB,QAAQ,WAAW;;AAOxC,KAAI,CAAC,YAAY,mBAAmB,QAAQ,KAAK,gBAAgB;EAE/D,MAAM,WAAW,iBADO,WAAW,QAAQ,KAAK,CACE;AAElD,MAAI,iBAAiB,SAAS,CAC5B,oBAAmB,UAAU;GAAE;GAAS;GAAS;GAAa,CAAC;MAE/D,SAAQ,IAAI,8CAA8C;;;AAKhE,MAAa,uBAAuB,IAAI,QAAQ,iBAAiB,CAC9D,YAAY,6CAA6C,CACzD,SAAS,aAAa,iCAAiC,QAAQ,KAAK,CAAC,CACrE,SACC,aACA,oBACA,KAAK,KAAK,QAAQ,KAAK,EAAE,qCAAqC,CAC/D,CACA,SAAS,iBAAiB,0BAA0B,CACpD,OAAO,cAAc,sCAAsC,CAC3D,OACC,UACA,iEACD,CAGA,UACC,IAAI,OACF,wBACA,sCACD,CAAC,UAAU,CACb,CACA,YACC,SACA;;;;;;wFAOD,CACA,OAAO,oBAAoB"}

package/dist/index.js

@@ -1,5 +1,4 @@
 import { isSQLTypeMarker, sql } from "./shared/src/sql/helpers.js";
-import "./shared/src/index.js";
 import { createLakebasePoolManager } from "./connectors/lakebase/pool-manager.js";
 import { AppKitError } from "./errors/base.js";
 import { AuthenticationError } from "./errors/authentication.js";

package/dist/plugins/analytics/query.js

@@ -1,5 +1,4 @@
 import { isSQLTypeMarker, sql } from "../../shared/src/sql/helpers.js";
-import "../../shared/src/index.js";
 import { ValidationError } from "../../errors/validation.js";
 import "../../errors/index.js";
 import { getWorkspaceId } from "../../context/execution-context.js";

package/dist/plugins/analytics/query.js.map

@@ -1 +1 @@
-{"version":3,"file":"query.js","names":["sqlHelpers"],"sources":["../../../src/plugins/analytics/query.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport type { sql } from \"@databricks/sdk-experimental\";\nimport { isSQLTypeMarker, type SQLTypeMarker, sql as sqlHelpers } from \"shared\";\nimport { getWorkspaceId } from \"../../context\";\nimport { ValidationError } from \"../../errors\";\n\ntype SQLParameterValue = SQLTypeMarker | null | undefined;\n\nexport class QueryProcessor {\n  async processQueryParams(\n    query: string,\n    parameters?: Record<string, SQLParameterValue>,\n  ): Promise<Record<string, SQLParameterValue>> {\n    const processed = { ...parameters };\n\n    // extract all params from the query\n    const paramMatches = query.matchAll(/:([a-zA-Z_]\\w*)/g);\n    const queryParams = new Set(Array.from(paramMatches, (m) => m[1]));\n\n    // auto-inject workspaceId if needed and not provided\n    if (queryParams.has(\"workspaceId\") && !processed.workspaceId) {\n      const workspaceId = await getWorkspaceId();\n      if (workspaceId) {\n        processed.workspaceId = sqlHelpers.string(workspaceId);\n      }\n    }\n\n    return processed;\n  }\n\n  hashQuery(query: string): string {\n    return createHash(\"md5\").update(query).digest(\"hex\");\n  }\n\n  convertToSQLParameters(\n    query: string,\n    parameters?: Record<string, SQLParameterValue>,\n  ): { statement: string; parameters: sql.StatementParameterListItem[] } {\n    const sqlParameters: sql.StatementParameterListItem[] = [];\n\n    if (parameters) {\n      // extract all params from the query\n      const queryParamMatches = query.matchAll(/:([a-zA-Z_]\\w*)/g);\n      const queryParams = new Set(Array.from(queryParamMatches, (m) => m[1]));\n\n      // only allow parameters that exist in the query\n      for (const key of Object.keys(parameters)) {\n        if (!queryParams.has(key)) {\n          const validParams = Array.from(queryParams).join(\", \") || \"none\";\n          throw ValidationError.invalidValue(\n            key,\n            parameters[key],\n            `a parameter defined in the query (valid: ${validParams})`,\n          );\n        }\n      }\n\n      // convert parameters to SQL parameters\n      for (const [key, value] of Object.entries(parameters)) {\n        const parameter = this._createParameter(key, value);\n        if (parameter) {\n          sqlParameters.push(parameter);\n        }\n      }\n    }\n\n    return { statement: query, parameters: sqlParameters };\n  }\n\n  private _createParameter(\n    key: string,\n    value: SQLParameterValue,\n  ): sql.StatementParameterListItem | null {\n    if (value === null || value === undefined) {\n      return null;\n    }\n\n    if (!isSQLTypeMarker(value)) {\n      throw ValidationError.invalidValue(\n        key,\n        value,\n        \"SQL type (use sql.string(), sql.number(), sql.date(), sql.timestamp(), or sql.boolean())\",\n      );\n    }\n\n    return {\n      name: key,\n      value: value.value,\n      type: value.__sql_type,\n    };\n  }\n}\n"],"mappings":";;;;;;;;;AAQA,IAAa,iBAAb,MAA4B;CAC1B,MAAM,mBACJ,OACA,YAC4C;EAC5C,MAAM,YAAY,EAAE,GAAG,YAAY;EAGnC,MAAM,eAAe,MAAM,SAAS,mBAAmB;AAIvD,MAHoB,IAAI,IAAI,MAAM,KAAK,eAAe,MAAM,EAAE,GAAG,CAAC,CAGlD,IAAI,cAAc,IAAI,CAAC,UAAU,aAAa;GAC5D,MAAM,cAAc,MAAM,gBAAgB;AAC1C,OAAI,YACF,WAAU,cAAcA,IAAW,OAAO,YAAY;;AAI1D,SAAO;;CAGT,UAAU,OAAuB;AAC/B,SAAO,WAAW,MAAM,CAAC,OAAO,MAAM,CAAC,OAAO,MAAM;;CAGtD,uBACE,OACA,YACqE;EACrE,MAAM,gBAAkD,EAAE;AAE1D,MAAI,YAAY;GAEd,MAAM,oBAAoB,MAAM,SAAS,mBAAmB;GAC5D,MAAM,cAAc,IAAI,IAAI,MAAM,KAAK,oBAAoB,MAAM,EAAE,GAAG,CAAC;AAGvE,QAAK,MAAM,OAAO,OAAO,KAAK,WAAW,CACvC,KAAI,CAAC,YAAY,IAAI,IAAI,EAAE;IACzB,MAAM,cAAc,MAAM,KAAK,YAAY,CAAC,KAAK,KAAK,IAAI;AAC1D,UAAM,gBAAgB,aACpB,KACA,WAAW,MACX,4CAA4C,YAAY,GACzD;;AAKL,QAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,WAAW,EAAE;IACrD,MAAM,YAAY,KAAK,iBAAiB,KAAK,MAAM;AACnD,QAAI,UACF,eAAc,KAAK,UAAU;;;AAKnC,SAAO;GAAE,WAAW;GAAO,YAAY;GAAe;;CAGxD,AAAQ,iBACN,KACA,OACuC;AACvC,MAAI,UAAU,QAAQ,UAAU,OAC9B,QAAO;AAGT,MAAI,CAAC,gBAAgB,MAAM,CACzB,OAAM,gBAAgB,aACpB,KACA,OACA,2FACD;AAGH,SAAO;GACL,MAAM;GACN,OAAO,MAAM;GACb,MAAM,MAAM;GACb"}
+{"version":3,"file":"query.js","names":["sqlHelpers"],"sources":["../../../src/plugins/analytics/query.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport type { sql } from \"@databricks/sdk-experimental\";\nimport { isSQLTypeMarker, type SQLTypeMarker, sql as sqlHelpers } from \"shared\";\nimport { getWorkspaceId } from \"../../context\";\nimport { ValidationError } from \"../../errors\";\n\ntype SQLParameterValue = SQLTypeMarker | null | undefined;\n\nexport class QueryProcessor {\n  async processQueryParams(\n    query: string,\n    parameters?: Record<string, SQLParameterValue>,\n  ): Promise<Record<string, SQLParameterValue>> {\n    const processed = { ...parameters };\n\n    // extract all params from the query\n    const paramMatches = query.matchAll(/:([a-zA-Z_]\\w*)/g);\n    const queryParams = new Set(Array.from(paramMatches, (m) => m[1]));\n\n    // auto-inject workspaceId if needed and not provided\n    if (queryParams.has(\"workspaceId\") && !processed.workspaceId) {\n      const workspaceId = await getWorkspaceId();\n      if (workspaceId) {\n        processed.workspaceId = sqlHelpers.string(workspaceId);\n      }\n    }\n\n    return processed;\n  }\n\n  hashQuery(query: string): string {\n    return createHash(\"md5\").update(query).digest(\"hex\");\n  }\n\n  convertToSQLParameters(\n    query: string,\n    parameters?: Record<string, SQLParameterValue>,\n  ): { statement: string; parameters: sql.StatementParameterListItem[] } {\n    const sqlParameters: sql.StatementParameterListItem[] = [];\n\n    if (parameters) {\n      // extract all params from the query\n      const queryParamMatches = query.matchAll(/:([a-zA-Z_]\\w*)/g);\n      const queryParams = new Set(Array.from(queryParamMatches, (m) => m[1]));\n\n      // only allow parameters that exist in the query\n      for (const key of Object.keys(parameters)) {\n        if (!queryParams.has(key)) {\n          const validParams = Array.from(queryParams).join(\", \") || \"none\";\n          throw ValidationError.invalidValue(\n            key,\n            parameters[key],\n            `a parameter defined in the query (valid: ${validParams})`,\n          );\n        }\n      }\n\n      // convert parameters to SQL parameters\n      for (const [key, value] of Object.entries(parameters)) {\n        const parameter = this._createParameter(key, value);\n        if (parameter) {\n          sqlParameters.push(parameter);\n        }\n      }\n    }\n\n    return { statement: query, parameters: sqlParameters };\n  }\n\n  private _createParameter(\n    key: string,\n    value: SQLParameterValue,\n  ): sql.StatementParameterListItem | null {\n    if (value === null || value === undefined) {\n      return null;\n    }\n\n    if (!isSQLTypeMarker(value)) {\n      throw ValidationError.invalidValue(\n        key,\n        value,\n        \"SQL type (use sql.string(), sql.number(), sql.date(), sql.timestamp(), or sql.boolean())\",\n      );\n    }\n\n    return {\n      name: key,\n      value: value.value,\n      type: value.__sql_type,\n    };\n  }\n}\n"],"mappings":";;;;;;;;AAQA,IAAa,iBAAb,MAA4B;CAC1B,MAAM,mBACJ,OACA,YAC4C;EAC5C,MAAM,YAAY,EAAE,GAAG,YAAY;EAGnC,MAAM,eAAe,MAAM,SAAS,mBAAmB;AAIvD,MAHoB,IAAI,IAAI,MAAM,KAAK,eAAe,MAAM,EAAE,GAAG,CAAC,CAGlD,IAAI,cAAc,IAAI,CAAC,UAAU,aAAa;GAC5D,MAAM,cAAc,MAAM,gBAAgB;AAC1C,OAAI,YACF,WAAU,cAAcA,IAAW,OAAO,YAAY;;AAI1D,SAAO;;CAGT,UAAU,OAAuB;AAC/B,SAAO,WAAW,MAAM,CAAC,OAAO,MAAM,CAAC,OAAO,MAAM;;CAGtD,uBACE,OACA,YACqE;EACrE,MAAM,gBAAkD,EAAE;AAE1D,MAAI,YAAY;GAEd,MAAM,oBAAoB,MAAM,SAAS,mBAAmB;GAC5D,MAAM,cAAc,IAAI,IAAI,MAAM,KAAK,oBAAoB,MAAM,EAAE,GAAG,CAAC;AAGvE,QAAK,MAAM,OAAO,OAAO,KAAK,WAAW,CACvC,KAAI,CAAC,YAAY,IAAI,IAAI,EAAE;IACzB,MAAM,cAAc,MAAM,KAAK,YAAY,CAAC,KAAK,KAAK,IAAI;AAC1D,UAAM,gBAAgB,aACpB,KACA,WAAW,MACX,4CAA4C,YAAY,GACzD;;AAKL,QAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,WAAW,EAAE;IACrD,MAAM,YAAY,KAAK,iBAAiB,KAAK,MAAM;AACnD,QAAI,UACF,eAAc,KAAK,UAAU;;;AAKnC,SAAO;GAAE,WAAW;GAAO,YAAY;GAAe;;CAGxD,AAAQ,iBACN,KACA,OACuC;AACvC,MAAI,UAAU,QAAQ,UAAU,OAC9B,QAAO;AAGT,MAAI,CAAC,gBAAgB,MAAM,CACzB,OAAM,gBAAgB,aACpB,KACA,OACA,2FACD;AAGH,SAAO;GACL,MAAM;GACN,OAAO,MAAM;GACb,MAAM,MAAM;GACb"}

package/dist/type-generator/cache.js

@@ -12,12 +12,7 @@ const logger = createLogger("type-generator:cache");
 * hand-edits, truncation, or a stale writer can leave entries whose shape no
 * longer matches {@link MetricCacheEntry}. A malformed entry must read as a
 * cache MISS (re-describe) rather than crash the pass or render revived
-* garbage into the artifacts. Checks exactly what the renderers and the
-* metadata bundle consume: `hash` string, `retry` boolean, and a schema with
-* `key`/`source` strings, a valid lane, an optional boolean `degraded`, and
-* measure/dimension arrays whose elements carry `name`/`type` strings
-* (other column fields are optional). Deliberately inline — the shared Zod
-* schemas must not enter the type-generator's runtime path.
+* garbage into the artifacts.
 */
 function isRevivableMetricCacheEntry(entry) {
 	if (typeof entry !== "object" || entry === null) return false;

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

@@ -1 +1 @@
-{"version":3,"file":"cache.js","names":[],"sources":["../../src/type-generator/cache.ts"],"sourcesContent":["import crypto from \"node:crypto\";\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { createLogger } from \"../logging/logger\";\nimport type { MetricSchema } from \"./mv-registry/types\";\n\nconst logger = createLogger(\"type-generator:cache\");\n\n/**\n * Cache types\n * @property hash - the hash of the SQL query\n * @property type - the type of the query\n * @property retry - when true the entry never satisfies a cache hit, so the\n *   query is re-described on the next pass; fresh successful describes\n *   persist `retry: false`\n */\ninterface CacheEntry {\n  hash: string;\n  type: string;\n  retry: boolean;\n}\n\n/**\n * One cached metric-view DESCRIBE outcome.\n *\n * `hash` is md5 over `\"<source>|<lane>\"` — the two config inputs that\n * determine a DESCRIBE — so editing either invalidates the entry. `schema`\n * is the full {@link MetricSchema} persisted verbatim (it is JSON-safe by\n * design), letting a warm pass regenerate both metric artifacts without a\n * single warehouse call. `retry: true` marks a SELF-CONVERGING degraded\n * outcome (DESCRIBE skipped behind a not-running warehouse, unanswered, or\n * transiently failed): the cached schema still renders artifacts, but the\n * next eligible pass re-describes exactly these keys so degraded schemas\n * converge to real ones. A degraded schema with `retry: false` is a STICKY\n * failure — a deterministic DESCRIBE failure (bad FQN, unparseable\n * response, zero columns) or a deleted warehouse — that re-describing the\n * unchanged entry cannot fix; it hits like any cached entry until the\n * config hash changes or the cache is bypassed, and the type generator\n * warns about it on every pass that serves it.\n */\nexport interface MetricCacheEntry {\n  hash: string;\n  schema: MetricSchema;\n  retry: boolean;\n}\n\n/**\n * Structural gate for reviving a cached metric entry at partition time.\n *\n * The cache file lives in `node_modules/.databricks` and is plain JSON —\n * hand-edits, truncation, or a stale writer can leave entries whose shape no\n * longer matches {@link MetricCacheEntry}. A malformed entry must read as a\n * cache MISS (re-describe) rather than crash the pass or render revived\n * garbage into the artifacts. Checks exactly what the renderers and the\n * metadata bundle consume: `hash` string, `retry` boolean, and a schema with\n * `key`/`source` strings, a valid lane, an optional boolean `degraded`, and\n * measure/dimension arrays whose elements carry `name`/`type` strings\n * (other column fields are optional). Deliberately inline — the shared Zod\n * schemas must not enter the type-generator's runtime path.\n */\nexport function isRevivableMetricCacheEntry(entry: unknown): boolean {\n  if (typeof entry !== \"object\" || entry === null) return false;\n  const e = entry as Record<string, unknown>;\n  if (typeof e.hash !== \"string\" || typeof e.retry !== \"boolean\") {\n    return false;\n  }\n  const schema = e.schema;\n  if (typeof schema !== \"object\" || schema === null || Array.isArray(schema)) {\n    return false;\n  }\n  const s = schema as Record<string, unknown>;\n  const isColumnArray = (value: unknown): boolean =>\n    Array.isArray(value) &&\n    value.every(\n      (col) =>\n        typeof col === \"object\" &&\n        col !== null &&\n        typeof (col as Record<string, unknown>).name === \"string\" &&\n        typeof (col as Record<string, unknown>).type === \"string\",\n    );\n  return (\n    typeof s.key === \"string\" &&\n    typeof s.source === \"string\" &&\n    (s.lane === \"sp\" || s.lane === \"obo\") &&\n    (s.degraded === undefined || typeof s.degraded === \"boolean\") &&\n    isColumnArray(s.measures) &&\n    isColumnArray(s.dimensions)\n  );\n}\n\n/**\n * Cache interface\n * @property version - the version of the cache\n * @property queries - the queries in the cache\n * @property metrics - cached metric-view schemas keyed by metric key.\n *   OPTIONAL on purpose: version \"3\" files written before this section\n *   existed load unchanged (absent ⇒ treated as empty by the metric path),\n *   and the query path's `noCache` reinit literal stays valid as-is. The\n *   section rides through the query path's load → mutate → save cycle as a\n *   plain sibling key, so query-side saves preserve it byte-for-byte.\n */\ninterface Cache {\n  version: string;\n  queries: Record<string, CacheEntry>;\n  metrics?: Record<string, MetricCacheEntry>;\n}\n\nexport const CACHE_VERSION = \"3\";\nconst CACHE_FILE = \".appkit-types-cache.json\";\nconst CACHE_DIR = path.join(\n  process.cwd(),\n  \"node_modules\",\n  \".databricks\",\n  \"appkit\",\n);\n\n/**\n * Hash the SQL query\n * Uses MD5 to hash the SQL query\n * @param sql - the SQL query to hash\n * @returns - the hash of the SQL query\n */\nexport function hashSQL(sql: string): string {\n  return crypto.createHash(\"md5\").update(sql).digest(\"hex\");\n}\n\n/**\n * Change detector stored on {@link MetricCacheEntry.hash}: md5 over\n * `\"<source>|<lane>\"` — the two config inputs that determine a DESCRIBE —\n * so editing either invalidates the entry.\n */\nexport function metricCacheHash(source: string, lane: string): string {\n  return hashSQL(`${source}|${lane}`);\n}\n\n/**\n * Load the cache from the file system\n * If the cache is not found, run the query explain\n * @returns - the cache\n */\nexport async function loadCache(): Promise<Cache> {\n  const cachePath = path.join(CACHE_DIR, CACHE_FILE);\n  try {\n    await fs.mkdir(CACHE_DIR, { recursive: true });\n\n    const raw = await fs.readFile(cachePath, \"utf8\");\n    const cache = JSON.parse(raw) as Cache;\n    if (cache.version === CACHE_VERSION) {\n      return cache;\n    }\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code !== \"ENOENT\") {\n      logger.warn(\"Cache file is corrupted, flushing cache completely.\");\n    }\n  }\n  return { version: CACHE_VERSION, queries: {} };\n}\n\n/**\n * Save the cache to the file system\n * @param cache - cache object to save\n */\nexport async function saveCache(cache: Cache): Promise<void> {\n  const cachePath = path.join(CACHE_DIR, CACHE_FILE);\n  await fs.writeFile(cachePath, JSON.stringify(cache, null, 2), \"utf8\");\n}\n"],"mappings":";;;;;;AAMA,MAAM,SAAS,aAAa,uBAAuB;;;;;;;;;;;;;;;AAsDnD,SAAgB,4BAA4B,OAAyB;AACnE,KAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;CACxD,MAAM,IAAI;AACV,KAAI,OAAO,EAAE,SAAS,YAAY,OAAO,EAAE,UAAU,UACnD,QAAO;CAET,MAAM,SAAS,EAAE;AACjB,KAAI,OAAO,WAAW,YAAY,WAAW,QAAQ,MAAM,QAAQ,OAAO,CACxE,QAAO;CAET,MAAM,IAAI;CACV,MAAM,iBAAiB,UACrB,MAAM,QAAQ,MAAM,IACpB,MAAM,OACH,QACC,OAAO,QAAQ,YACf,QAAQ,QACR,OAAQ,IAAgC,SAAS,YACjD,OAAQ,IAAgC,SAAS,SACpD;AACH,QACE,OAAO,EAAE,QAAQ,YACjB,OAAO,EAAE,WAAW,aACnB,EAAE,SAAS,QAAQ,EAAE,SAAS,WAC9B,EAAE,aAAa,UAAa,OAAO,EAAE,aAAa,cACnD,cAAc,EAAE,SAAS,IACzB,cAAc,EAAE,WAAW;;AAqB/B,MAAa,gBAAgB;AAC7B,MAAM,aAAa;AACnB,MAAM,YAAY,KAAK,KACrB,QAAQ,KAAK,EACb,gBACA,eACA,SACD;;;;;;;AAQD,SAAgB,QAAQ,KAAqB;AAC3C,QAAO,OAAO,WAAW,MAAM,CAAC,OAAO,IAAI,CAAC,OAAO,MAAM;;;;;;;AAQ3D,SAAgB,gBAAgB,QAAgB,MAAsB;AACpE,QAAO,QAAQ,GAAG,OAAO,GAAG,OAAO;;;;;;;AAQrC,eAAsB,YAA4B;CAChD,MAAM,YAAY,KAAK,KAAK,WAAW,WAAW;AAClD,KAAI;AACF,QAAM,GAAG,MAAM,WAAW,EAAE,WAAW,MAAM,CAAC;EAE9C,MAAM,MAAM,MAAM,GAAG,SAAS,WAAW,OAAO;EAChD,MAAM,QAAQ,KAAK,MAAM,IAAI;AAC7B,MAAI,MAAM,YAAY,cACpB,QAAO;UAEF,KAAK;AACZ,MAAK,IAA8B,SAAS,SAC1C,QAAO,KAAK,sDAAsD;;AAGtE,QAAO;EAAE,SAAS;EAAe,SAAS,EAAE;EAAE;;;;;;AAOhD,eAAsB,UAAU,OAA6B;CAC3D,MAAM,YAAY,KAAK,KAAK,WAAW,WAAW;AAClD,OAAM,GAAG,UAAU,WAAW,KAAK,UAAU,OAAO,MAAM,EAAE,EAAE,OAAO"}
+{"version":3,"file":"cache.js","names":[],"sources":["../../src/type-generator/cache.ts"],"sourcesContent":["import crypto from \"node:crypto\";\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { createLogger } from \"../logging/logger\";\nimport type { MetricSchema } from \"./mv-registry/types\";\n\nconst logger = createLogger(\"type-generator:cache\");\n\n/**\n * Cache types\n * @property hash - the hash of the SQL query\n * @property type - the type of the query\n * @property retry - when true the entry never satisfies a cache hit, so the\n *   query is re-described on the next pass; fresh successful describes\n *   persist `retry: false`\n */\ninterface CacheEntry {\n  hash: string;\n  type: string;\n  retry: boolean;\n}\n\n/**\n * One cached metric-view DESCRIBE outcome.\n *\n * `hash` is md5 over `\"<source>|<lane>\"` — the two config inputs that\n * determine a DESCRIBE — so editing either invalidates the entry. `schema`\n * is the full {@link MetricSchema} persisted verbatim (it is JSON-safe by\n * design), letting a warm pass regenerate the metric artifact without a\n * single warehouse call.\n */\nexport interface MetricCacheEntry {\n  hash: string;\n  schema: MetricSchema;\n  retry: boolean;\n}\n\n/**\n * Structural gate for reviving a cached metric entry at partition time.\n *\n * The cache file lives in `node_modules/.databricks` and is plain JSON —\n * hand-edits, truncation, or a stale writer can leave entries whose shape no\n * longer matches {@link MetricCacheEntry}. A malformed entry must read as a\n * cache MISS (re-describe) rather than crash the pass or render revived\n * garbage into the artifacts.\n */\nexport function isRevivableMetricCacheEntry(entry: unknown): boolean {\n  if (typeof entry !== \"object\" || entry === null) return false;\n  const e = entry as Record<string, unknown>;\n  if (typeof e.hash !== \"string\" || typeof e.retry !== \"boolean\") {\n    return false;\n  }\n  const schema = e.schema;\n  if (typeof schema !== \"object\" || schema === null || Array.isArray(schema)) {\n    return false;\n  }\n  const s = schema as Record<string, unknown>;\n  const isColumnArray = (value: unknown): boolean =>\n    Array.isArray(value) &&\n    value.every(\n      (col) =>\n        typeof col === \"object\" &&\n        col !== null &&\n        typeof (col as Record<string, unknown>).name === \"string\" &&\n        typeof (col as Record<string, unknown>).type === \"string\",\n    );\n  return (\n    typeof s.key === \"string\" &&\n    typeof s.source === \"string\" &&\n    (s.lane === \"sp\" || s.lane === \"obo\") &&\n    (s.degraded === undefined || typeof s.degraded === \"boolean\") &&\n    isColumnArray(s.measures) &&\n    isColumnArray(s.dimensions)\n  );\n}\n\n/**\n * Cache interface\n * @property version - the version of the cache\n * @property queries - the queries in the cache\n * @property metrics - cached metric-view schemas keyed by metric key.\n */\ninterface Cache {\n  version: string;\n  queries: Record<string, CacheEntry>;\n  metrics?: Record<string, MetricCacheEntry>;\n}\n\nexport const CACHE_VERSION = \"3\";\nconst CACHE_FILE = \".appkit-types-cache.json\";\nconst CACHE_DIR = path.join(\n  process.cwd(),\n  \"node_modules\",\n  \".databricks\",\n  \"appkit\",\n);\n\n/**\n * Hash the SQL query\n * Uses MD5 to hash the SQL query\n * @param sql - the SQL query to hash\n * @returns - the hash of the SQL query\n */\nexport function hashSQL(sql: string): string {\n  return crypto.createHash(\"md5\").update(sql).digest(\"hex\");\n}\n\n/**\n * Change detector stored on {@link MetricCacheEntry.hash}: md5 over\n * `\"<source>|<lane>\"` — the two config inputs that determine a DESCRIBE —\n * so editing either invalidates the entry.\n */\nexport function metricCacheHash(source: string, lane: string): string {\n  return hashSQL(`${source}|${lane}`);\n}\n\n/**\n * Load the cache from the file system\n * If the cache is not found, run the query explain\n * @returns - the cache\n */\nexport async function loadCache(): Promise<Cache> {\n  const cachePath = path.join(CACHE_DIR, CACHE_FILE);\n  try {\n    await fs.mkdir(CACHE_DIR, { recursive: true });\n\n    const raw = await fs.readFile(cachePath, \"utf8\");\n    const cache = JSON.parse(raw) as Cache;\n    if (cache.version === CACHE_VERSION) {\n      return cache;\n    }\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code !== \"ENOENT\") {\n      logger.warn(\"Cache file is corrupted, flushing cache completely.\");\n    }\n  }\n  return { version: CACHE_VERSION, queries: {} };\n}\n\n/**\n * Save the cache to the file system\n * @param cache - cache object to save\n */\nexport async function saveCache(cache: Cache): Promise<void> {\n  const cachePath = path.join(CACHE_DIR, CACHE_FILE);\n  await fs.writeFile(cachePath, JSON.stringify(cache, null, 2), \"utf8\");\n}\n"],"mappings":";;;;;;AAMA,MAAM,SAAS,aAAa,uBAAuB;;;;;;;;;;AAwCnD,SAAgB,4BAA4B,OAAyB;AACnE,KAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;CACxD,MAAM,IAAI;AACV,KAAI,OAAO,EAAE,SAAS,YAAY,OAAO,EAAE,UAAU,UACnD,QAAO;CAET,MAAM,SAAS,EAAE;AACjB,KAAI,OAAO,WAAW,YAAY,WAAW,QAAQ,MAAM,QAAQ,OAAO,CACxE,QAAO;CAET,MAAM,IAAI;CACV,MAAM,iBAAiB,UACrB,MAAM,QAAQ,MAAM,IACpB,MAAM,OACH,QACC,OAAO,QAAQ,YACf,QAAQ,QACR,OAAQ,IAAgC,SAAS,YACjD,OAAQ,IAAgC,SAAS,SACpD;AACH,QACE,OAAO,EAAE,QAAQ,YACjB,OAAO,EAAE,WAAW,aACnB,EAAE,SAAS,QAAQ,EAAE,SAAS,WAC9B,EAAE,aAAa,UAAa,OAAO,EAAE,aAAa,cACnD,cAAc,EAAE,SAAS,IACzB,cAAc,EAAE,WAAW;;AAgB/B,MAAa,gBAAgB;AAC7B,MAAM,aAAa;AACnB,MAAM,YAAY,KAAK,KACrB,QAAQ,KAAK,EACb,gBACA,eACA,SACD;;;;;;;AAQD,SAAgB,QAAQ,KAAqB;AAC3C,QAAO,OAAO,WAAW,MAAM,CAAC,OAAO,IAAI,CAAC,OAAO,MAAM;;;;;;;AAQ3D,SAAgB,gBAAgB,QAAgB,MAAsB;AACpE,QAAO,QAAQ,GAAG,OAAO,GAAG,OAAO;;;;;;;AAQrC,eAAsB,YAA4B;CAChD,MAAM,YAAY,KAAK,KAAK,WAAW,WAAW;AAClD,KAAI;AACF,QAAM,GAAG,MAAM,WAAW,EAAE,WAAW,MAAM,CAAC;EAE9C,MAAM,MAAM,MAAM,GAAG,SAAS,WAAW,OAAO;EAChD,MAAM,QAAQ,KAAK,MAAM,IAAI;AAC7B,MAAI,MAAM,YAAY,cACpB,QAAO;UAEF,KAAK;AACZ,MAAK,IAA8B,SAAS,SAC1C,QAAO,KAAK,sDAAsD;;AAGtE,QAAO;EAAE,SAAS;EAAe,SAAS,EAAE;EAAE;;;;;;AAOhD,eAAsB,UAAU,OAA6B;CAC3D,MAAM,YAAY,KAAK,KAAK,WAAW,WAAW;AAClD,OAAM,GAAG,UAAU,WAAW,KAAK,UAAU,OAAO,MAAM,EAAE,EAAE,OAAO"}

package/dist/type-generator/index.js

@@ -4,7 +4,6 @@ import { getErrorDiagnostic, isConnectivityError } from "./errors.js";
 import { migrateProjectConfig, removeOldGeneratedTypes, resolveProjectRoot } from "./migration.js";
 import { readMetricConfig, resolveMetricConfig } from "./mv-registry/config.js";
 import { createWorkspaceDescribeFetcher } from "./mv-registry/describe.js";
-import { generateMetricsMetadataJson } from "./mv-registry/metadata.js";
 import { generateMetricTypeDeclarations } from "./mv-registry/render-types.js";
 import { emptyMetricSchema, syncMetrics } from "./mv-registry/sync.js";
 import { decidePreflight } from "./preflight.js";
@@ -21,7 +20,7 @@ import dotenv from "dotenv";
 dotenv.config();
 const logger = createLogger("type-generator");
 /**
-* Upper bound (~5 min) on how long the metric path's `blocking`-mode preflight
+* Upper bound (~5 min) on how long the Metric Views path's `blocking`-mode preflight
 * waits for a warehouse to reach RUNNING. Mirrors the query path's (unexported)
 * `PREFLIGHT_WAIT_MAX_MS` in query-registry.ts.
 */
@@ -147,20 +146,15 @@ declare module "@databricks/appkit-ui/react" {
 `;
 }
 /**
-* Status-only probe for the metric-view gate in {@link generateFromEntryPoint}:
-* what state is the warehouse in right now?
+* Status-only probe for the metric-view gate in {@link generateFromEntryPoint}
 *
-* Uses {@link getWarehouseState} (`warehouses.get`) — a read-only GET that can
-* never start the warehouse — unlike the metric DESCRIBE statements it guards,
-* whose execution auto-starts a stopped warehouse and waits on it.
+* Uses {@link getWarehouseState} (`warehouses.get`) —
+* a read-only GET that can never start the warehouse
 *
-* Returns the observed state so the gate can distinguish a transient
-* not-running state (STOPPED/STARTING/... → degraded entries that retry) from a
-* terminal one (DELETED/DELETING → degraded entries pinned sticky). Takes the
-* lazy client *getter* (not a client) so the probe also absorbs client
-* construction failure. A connectivity blip returns `undefined`, which the gate
-* reads as transient not-running; a deterministic failure (auth, bad id) is
-* re-thrown so the gate can classify it fatal rather than silently degrading.
+* Takes the lazy client *getter* so the probe also absorbs client construction failure.
+* A connectivity blip returns `undefined`, which the gate reads as transient not-running;
+* a deterministic failure (auth, bad id) is re-thrown so the gate can classify it
+* fatal rather than silently degrading.
 */
 async function probeWarehouseState(getClient, warehouseId) {
 	try {
@@ -186,12 +180,8 @@ async function probeWarehouseState(getClient, warehouseId) {
 *   degraded types immediately. `"blocking"` waits for / starts the warehouse
 *   first, failing the build only for a deleted/deleting one.
 * @param options.mvOutFile - optional output file for the MetricRegistry
-*   augmentation. Defaults to a sibling `metric.d.ts` file under the same
+*   augmentation. Defaults to a sibling `metric-views.d.ts` file under the same
 *   directory as `outFile`. Skipped entirely if `metric-views.json` is absent.
-* @param options.mvMetadataOutFile - optional output file for the
-*   build-time semantic metadata JSON bundle (`metrics.metadata.json`).
-*   Defaults to a sibling of `mvOutFile`. Skipped entirely if
-*   `metric-views.json` is absent.
 * @param options.metricFetcher - optional DescribeFetcher used by
 *   {@link syncMetrics} (tests inject a mock; production lazily builds a
 *   default WorkspaceClient-backed one). An injected fetcher always runs: it
@@ -199,7 +189,7 @@ async function probeWarehouseState(getClient, warehouseId) {
 *   blocking preflight.
 */
 async function generateFromEntryPoint(options) {
-	const { outFile, queryFolder, warehouseId, noCache, mode = "non-blocking", mvOutFile, mvMetadataOutFile, metricFetcher } = options;
+	const { outFile, queryFolder, warehouseId, noCache, mode = "non-blocking", mvOutFile, metricFetcher } = options;
 	const projectRoot = resolveProjectRoot(outFile);
 	logger.debug("Starting type generation...");
 	let queryRegistry = [];
@@ -218,119 +208,28 @@ async function generateFromEntryPoint(options) {
 	await fs.mkdir(path.dirname(outFile), { recursive: true });
 	await fs.writeFile(outFile, typeDeclarations, "utf-8");
 	if (queryFolder) {
-		const mvConfig = await readMetricConfig(queryFolder);
-		if (mvConfig) {
-			const resolution = resolveMetricConfig(mvConfig);
-			const cache = await loadCache();
-			const mvCacheSection = Object.create(null);
-			if (!noCache && cache.metrics) for (const key of Object.keys(cache.metrics)) mvCacheSection[key] = cache.metrics[key];
-			const hitSchemas = /* @__PURE__ */ new Map();
-			const describeNeeded = [];
-			const stickyDegradedHits = [];
-			for (const entry of resolution.entries) {
-				const prior = mvCacheSection[entry.key];
-				if (prior !== void 0 && isRevivableMetricCacheEntry(prior) && prior.hash === metricCacheHash(entry.source, entry.lane) && !prior.retry) {
-					hitSchemas.set(entry.key, prior.schema);
-					if (prior.schema.degraded === true) stickyDegradedHits.push(entry.key);
-				} else describeNeeded.push(entry);
-			}
-			if (stickyDegradedHits.length > 0) logger.warn("cached failure for %s — fix the entry in metric-views.json or run with --no-cache to retry.", stickyDegradedHits.join(", "));
-			let mvClient;
-			const getMvClient = () => {
-				mvClient ??= new WorkspaceClient({});
-				return mvClient;
-			};
-			let preflightFatalMessage;
-			if (mode === "blocking" && metricFetcher === void 0 && describeNeeded.length > 0) try {
-				const state = await getWarehouseState(getMvClient(), warehouseId);
-				const decision = decidePreflight(state, mode);
-				if (decision === "fatal") preflightFatalMessage = `warehouse ${warehouseId} is ${state}`;
-				else if (decision === "startWaitProceed") {
-					await startWarehouse(getMvClient(), warehouseId);
-					const settled = await waitUntilRunning(getMvClient(), warehouseId, {
-						maxMs: MV_PREFLIGHT_WAIT_MAX_MS,
-						treatStoppedAsTransient: true
-					});
-					if (settled !== "RUNNING") preflightFatalMessage = `warehouse ${warehouseId} is ${settled}`;
-				} else if (decision === "waitThenProceed") {
-					const settled = await waitUntilRunning(getMvClient(), warehouseId, { maxMs: MV_PREFLIGHT_WAIT_MAX_MS });
-					if (settled === "DELETED" || settled === "DELETING") preflightFatalMessage = `warehouse ${warehouseId} is ${settled}`;
-				}
-			} catch (err) {
-				if (!isConnectivityError(err)) preflightFatalMessage = `warehouse ${warehouseId}: ${getErrorDiagnostic(err)}`;
-			}
-			let gateState;
-			let describeNow = metricFetcher !== void 0 || mode !== "non-blocking" || describeNeeded.length === 0;
-			if (!describeNow) {
-				try {
-					gateState = await probeWarehouseState(getMvClient, warehouseId);
-				} catch (err) {
-					preflightFatalMessage = `warehouse ${warehouseId}: ${getErrorDiagnostic(err)}`;
-				}
-				describeNow = gateState === "RUNNING";
-			}
-			let described;
-			let failures = [];
-			let terminalSkip = false;
-			if (preflightFatalMessage !== void 0) {
-				described = describeNeeded.map(emptyMetricSchema);
-				terminalSkip = true;
-				for (const entry of describeNeeded) fatalErrors.push({
-					name: entry.key,
-					message: preflightFatalMessage
-				});
-			} else if (describeNeeded.length === 0) described = [];
-			else if (describeNow) {
-				const fetcher = metricFetcher ?? createWorkspaceDescribeFetcher(getMvClient(), warehouseId);
-				({schemas: described, failures} = await syncMetrics({ entries: describeNeeded }, fetcher));
-				if (failures.length > 0) for (const f of failures) logger.warn("metric sync failed for %s (%s): %s", f.key, f.source, f.reason);
-				const failedKeys = new Set(failures.map((f) => f.key));
-				const degradedKeys = described.filter((s) => s.degraded && !failedKeys.has(s.key)).map((s) => s.key);
-				if (degradedKeys.length > 0) logger.info("Warehouse %s did not return schemas for %d metric view(s) (%s) — wrote degraded metric types (permissive); they will refresh once the warehouse is available.", warehouseId, degradedKeys.length, degradedKeys.join(", "));
-			} else {
-				described = describeNeeded.map(emptyMetricSchema);
-				terminalSkip = gateState === "DELETED" || gateState === "DELETING";
-				logger.info("Warehouse %s is not running — wrote degraded metric types (permissive) for %d metric view(s) (%s); they will refresh once the warehouse is available.", warehouseId, describeNeeded.length, describeNeeded.map((e) => e.key).join(", "));
-			}
-			const failureByKey = /* @__PURE__ */ new Map();
-			for (const failure of failures) failureByKey.set(failure.key, failure);
-			for (let i = 0; i < describeNeeded.length; i++) {
-				const entry = describeNeeded[i];
-				const failure = failureByKey.get(entry.key);
-				mvCacheSection[entry.key] = {
-					hash: metricCacheHash(entry.source, entry.lane),
-					schema: described[i],
-					retry: described[i].degraded === true && !terminalSkip && (failure === void 0 || failure.transient === true)
-				};
-			}
-			const configuredKeys = new Set(resolution.entries.map((e) => e.key));
-			let prunedCount = 0;
-			for (const key of Object.keys(mvCacheSection)) if (!configuredKeys.has(key)) {
-				delete mvCacheSection[key];
-				prunedCount++;
-			}
-			if (describeNeeded.length > 0 || noCache || prunedCount > 0) {
-				cache.metrics = mvCacheSection;
-				await saveCache(cache);
-			}
-			const describedByKey = /* @__PURE__ */ new Map();
-			for (const schema of described) describedByKey.set(schema.key, schema);
-			const mvSchemas = resolution.entries.map((entry) => {
-				const schema = hitSchemas.get(entry.key) ?? describedByKey.get(entry.key);
-				if (schema !== void 0) return schema;
-				logger.warn("no schema resolved for metric key %s — emitting degraded types (should not happen)", entry.key);
-				return emptyMetricSchema(entry);
+		const mvFile = mvOutFile ?? path.join(path.dirname(outFile), METRIC_TYPES_FILE);
+		let mvResult;
+		try {
+			mvResult = await syncMetricViewsTypes({
+				queryFolder,
+				warehouseId,
+				metricOutFile: mvFile,
+				cache: !noCache,
+				metricFetcher,
+				mode
 			});
-			const mvFile = mvOutFile ?? path.join(path.dirname(outFile), METRIC_TYPES_FILE);
-			const mvDeclarations = generateMetricTypeDeclarations(mvSchemas);
-			await fs.mkdir(path.dirname(mvFile), { recursive: true });
-			await fs.writeFile(mvFile, mvDeclarations, "utf-8");
-			const mvMetadataFile = mvMetadataOutFile ?? path.join(path.dirname(mvFile), METRIC_METADATA_FILE);
-			const metadataJson = generateMetricsMetadataJson(mvSchemas);
-			await fs.mkdir(path.dirname(mvMetadataFile), { recursive: true });
-			await fs.writeFile(mvMetadataFile, metadataJson, "utf-8");
-			logger.debug("Wrote MetricRegistry augmentation + metadata bundle for %d metric(s)%s", mvSchemas.length, failures.length > 0 ? ` (${failures.length} failure(s))` : "");
+		} catch (configError) {
+			throw new TypegenFatalError([{
+				name: "metric-views.json",
+				message: getErrorDiagnostic(configError)
+			}], warehouseId);
 		}
+		for (const fe of mvResult.fatalErrors) fatalErrors.push(fe);
+		if (mode === "blocking") for (const failure of mvResult.failures) fatalErrors.push({
+			name: failure.key,
+			message: `metric view ${failure.key} (${failure.source}) could not be described: ${failure.reason}`
+		});
 	}
 	await removeOldGeneratedTypes(projectRoot, "appKitTypes.d.ts");
 	await migrateProjectConfig(projectRoot);
@@ -338,25 +237,142 @@ async function generateFromEntryPoint(options) {
 	if (fatalErrors.length > 0) throw new TypegenFatalError(fatalErrors, warehouseId);
 	logger.debug("Type generation complete!");
 }
+/**
+* Unified metric-view type-generation pipeline behind {@link
+* generateFromEntryPoint}'s metric section (which forwards its
+* `"non-blocking"`/`"blocking"` mode). Also directly callable with the default
+* `"describe-now"` mode for a focused, always-converge metric refresh.
+*
+*
+* @param options.queryFolder - folder that holds `metric-views.json` (`<root>/config/queries`).
+* @param options.warehouseId - SQL warehouse used for `DESCRIBE TABLE EXTENDED`.
+* @param options.metricOutFile - output path for the MetricRegistry `.d.ts`.
+* @param options.cache - cache toggle, default ON. Only `cache === false` disables it (so `undefined`/`true` keep caching).
+* @param options.metricFetcher - optional injected {@link DescribeFetcher}
+* @param options.mode - preflight/gate policy, default `"describe-now"`.
+*/
+async function syncMetricViewsTypes(options) {
+	const { queryFolder, warehouseId, metricOutFile, cache: cacheEnabled, metricFetcher, mode = "describe-now" } = options;
+	const noCache = cacheEnabled === false;
+	const mvConfig = await readMetricConfig(queryFolder);
+	if (!mvConfig) return {
+		schemas: [],
+		failures: [],
+		fatalErrors: [],
+		noConfig: true
+	};
+	const resolution = resolveMetricConfig(mvConfig);
+	const fatalErrors = [];
+	const cache = await loadCache();
+	const mvCacheSection = Object.create(null);
+	if (!noCache && cache.metrics) for (const key of Object.keys(cache.metrics)) mvCacheSection[key] = cache.metrics[key];
+	const hitSchemas = /* @__PURE__ */ new Map();
+	const describeNeeded = [];
+	for (const entry of resolution.entries) {
+		const prior = mvCacheSection[entry.key];
+		if (prior !== void 0 && isRevivableMetricCacheEntry(prior) && prior.hash === metricCacheHash(entry.source, entry.lane) && prior.schema.degraded !== true) hitSchemas.set(entry.key, prior.schema);
+		else describeNeeded.push(entry);
+	}
+	let mvClient;
+	const getMvClient = () => {
+		mvClient ??= new WorkspaceClient({});
+		return mvClient;
+	};
+	let preflightFatalMessage;
+	if (mode === "blocking" && metricFetcher === void 0 && describeNeeded.length > 0) try {
+		const state = await getWarehouseState(getMvClient(), warehouseId);
+		const decision = decidePreflight(state, mode);
+		if (decision === "fatal") preflightFatalMessage = `warehouse ${warehouseId} is ${state}`;
+		else if (decision === "startWaitProceed") {
+			await startWarehouse(getMvClient(), warehouseId);
+			const settled = await waitUntilRunning(getMvClient(), warehouseId, {
+				maxMs: MV_PREFLIGHT_WAIT_MAX_MS,
+				treatStoppedAsTransient: true
+			});
+			if (settled !== "RUNNING") preflightFatalMessage = `warehouse ${warehouseId} is ${settled}`;
+		} else if (decision === "waitThenProceed") {
+			const settled = await waitUntilRunning(getMvClient(), warehouseId, { maxMs: MV_PREFLIGHT_WAIT_MAX_MS });
+			if (settled === "DELETED" || settled === "DELETING") preflightFatalMessage = `warehouse ${warehouseId} is ${settled}`;
+		}
+	} catch (err) {
+		if (!isConnectivityError(err)) preflightFatalMessage = `warehouse ${warehouseId}: ${getErrorDiagnostic(err)}`;
+	}
+	let gateState;
+	let describeNow = metricFetcher !== void 0 || mode !== "non-blocking" || describeNeeded.length === 0;
+	if (!describeNow) {
+		try {
+			gateState = await probeWarehouseState(getMvClient, warehouseId);
+		} catch (err) {
+			preflightFatalMessage = `warehouse ${warehouseId}: ${getErrorDiagnostic(err)}`;
+		}
+		describeNow = gateState === "RUNNING";
+	}
+	let described;
+	let failures = [];
+	if (preflightFatalMessage !== void 0) {
+		described = describeNeeded.map(emptyMetricSchema);
+		for (const entry of describeNeeded) fatalErrors.push({
+			name: entry.key,
+			message: preflightFatalMessage
+		});
+	} else if (describeNeeded.length === 0) described = [];
+	else if (describeNow) {
+		const fetcher = metricFetcher ?? createWorkspaceDescribeFetcher(getMvClient(), warehouseId);
+		({schemas: described, failures} = await syncMetrics({ entries: describeNeeded }, fetcher));
+		if (failures.length > 0) for (const f of failures) logger.warn("metric sync failed for %s (%s): %s", f.key, f.source, f.reason);
+		const failedKeys = new Set(failures.map((f) => f.key));
+		const degradedKeys = described.filter((s) => s.degraded && !failedKeys.has(s.key)).map((s) => s.key);
+		if (degradedKeys.length > 0) logger.info("Warehouse %s did not return schemas for %d metric view(s) (%s) — wrote degraded metric types (permissive); they will refresh once the warehouse is available.", warehouseId, degradedKeys.length, degradedKeys.join(", "));
+	} else {
+		described = describeNeeded.map(emptyMetricSchema);
+		logger.info("Warehouse %s is not running — wrote degraded metric types (permissive) for %d metric view(s) (%s); they will refresh once the warehouse is available.", warehouseId, describeNeeded.length, describeNeeded.map((e) => e.key).join(", "));
+	}
+	for (let i = 0; i < describeNeeded.length; i++) {
+		const entry = describeNeeded[i];
+		if (described[i].degraded === true) {
+			delete mvCacheSection[entry.key];
+			continue;
+		}
+		mvCacheSection[entry.key] = {
+			hash: metricCacheHash(entry.source, entry.lane),
+			schema: described[i],
+			retry: false
+		};
+	}
+	const configuredKeys = new Set(resolution.entries.map((e) => e.key));
+	let prunedCount = 0;
+	for (const key of Object.keys(mvCacheSection)) if (!configuredKeys.has(key)) {
+		delete mvCacheSection[key];
+		prunedCount++;
+	}
+	if (describeNeeded.length > 0 || noCache || prunedCount > 0) {
+		cache.metrics = mvCacheSection;
+		await saveCache(cache);
+	}
+	const describedByKey = /* @__PURE__ */ new Map();
+	for (const schema of described) describedByKey.set(schema.key, schema);
+	const schemas = resolution.entries.map((entry) => {
+		const schema = hitSchemas.get(entry.key) ?? describedByKey.get(entry.key);
+		if (schema !== void 0) return schema;
+		logger.warn("no schema resolved for metric key %s — emitting degraded types (should not happen)", entry.key);
+		return emptyMetricSchema(entry);
+	});
+	await fs.mkdir(path.dirname(metricOutFile), { recursive: true });
+	await fs.writeFile(metricOutFile, generateMetricTypeDeclarations(schemas), "utf-8");
+	logger.debug("Wrote MetricRegistry augmentation for %d metric(s)%s", schemas.length, failures.length > 0 ? ` (${failures.length} failure(s))` : "");
+	return {
+		metricOutFile,
+		schemas,
+		failures,
+		fatalErrors,
+		noConfig: false
+	};
+}
 const generateServingTypes = generateServingTypes$1;
-/** Directory name for generated AppKit type declaration files. */
 const TYPES_DIR = "appkit-types";
-/** Default filename for analytics query type declarations. */
 const ANALYTICS_TYPES_FILE = "analytics.d.ts";
-/** Default filename for serving endpoint type declarations. */
 const SERVING_TYPES_FILE = "serving.d.ts";
-/** Default filename for metric-view registry type declarations. */
-const METRIC_TYPES_FILE = "metric.d.ts";
-/**
-* Default filename for the build-time semantic-metadata JSON bundle, sibling of
-* {@link METRIC_TYPES_FILE}. Shape is `Record<metricKey, { measures,
-* dimensions }>` (UC FQN and execution lane are server-side concerns, kept out
-* of this client-shipped artifact). The consuming app imports it at build time
-* and registers it via `@databricks/appkit-ui/format`'s
-* `registerMetricsMetadata()`, so the React hook returns per-metric `metadata`
-* without a second network round-trip.
-*/
-const METRIC_METADATA_FILE = "metrics.metadata.json";
+const METRIC_TYPES_FILE = "metric-views.d.ts";
 
 //#endregion
 export { ANALYTICS_TYPES_FILE, SERVING_TYPES_FILE, TYPES_DIR, TypegenFatalError, TypegenSyntaxError, generateFromEntryPoint, generateServingTypes };