@databricks/appkit 0.20.2 → 0.21.0

package/dist/stream/index.d.ts

@@ -1,3 +1 @@
-import "./arrow-stream-processor.js";
-import { StreamManager } from "./stream-manager.js";
-import "./types.js";
+import { StreamManager } from "./stream-manager.js";

package/dist/stream/index.js

@@ -1,6 +1,3 @@
-import { ArrowStreamProcessor } from "./arrow-stream-processor.js";
-import { streamDefaults } from "./defaults.js";
-import { SSEWarningCode } from "./types.js";
 import { StreamManager } from "./stream-manager.js";
 
 export {  };

package/dist/stream/stream-manager.js

@@ -1,5 +1,5 @@
-import { streamDefaults } from "./defaults.js";
 import { EventRingBuffer } from "./buffers.js";
+import { streamDefaults } from "./defaults.js";
 import { SSEErrorCode } from "./types.js";
 import { StreamValidator } from "./validator.js";
 import { SSEWriter } from "./sse-writer.js";

package/dist/stream/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":[],"sources":["../../src/stream/types.ts"],"sourcesContent":["import type { Context } from \"@opentelemetry/api\";\nimport type { IAppResponse } from \"shared\";\nimport type { EventRingBuffer } from \"./buffers\";\n\nexport const SSEWarningCode = {\n  BUFFER_OVERFLOW_RESTART: \"BUFFER_OVERFLOW_RESTART\",\n} as const satisfies Record<string, string>;\n\nexport type SSEWarningCode =\n  (typeof SSEWarningCode)[keyof typeof SSEWarningCode];\n\nexport const SSEErrorCode = {\n  TEMPORARY_UNAVAILABLE: \"TEMPORARY_UNAVAILABLE\",\n  TIMEOUT: \"TIMEOUT\",\n  INTERNAL_ERROR: \"INTERNAL_ERROR\",\n  INVALID_REQUEST: \"INVALID_REQUEST\",\n  STREAM_ABORTED: \"STREAM_ABORTED\",\n  STREAM_EVICTED: \"STREAM_EVICTED\",\n} as const satisfies Record<string, string>;\n\nexport type SSEErrorCode = (typeof SSEErrorCode)[keyof typeof SSEErrorCode];\n\nexport interface SSEError {\n  error: string;\n  code: SSEErrorCode;\n}\n\nexport interface BufferedEvent {\n  id: string;\n  type: string;\n  data: string;\n  timestamp: number;\n}\n\nexport interface StreamEntry {\n  streamId: string;\n  generator: AsyncGenerator<any, void, unknown>;\n  eventBuffer: EventRingBuffer;\n  clients: Set<IAppResponse>;\n  isCompleted: boolean;\n  lastAccess: number;\n  abortController: AbortController;\n  traceContext: Context;\n}\n\nexport interface BufferEntry {\n  buffer: EventRingBuffer;\n  lastAccess: number;\n}\n\nexport interface StreamOperation {\n  controller: AbortController;\n  type: \"query\" | \"stream\";\n  heartbeat?: NodeJS.Timeout;\n}\n"],"mappings":";AAIA,MAAa,iBAAiB,EAC5B,yBAAyB,2BAC1B;AAKD,MAAa,eAAe;CAC1B,uBAAuB;CACvB,SAAS;CACT,gBAAgB;CAChB,iBAAiB;CACjB,gBAAgB;CAChB,gBAAgB;CACjB"}
+{"version":3,"file":"types.js","names":[],"sources":["../../src/stream/types.ts"],"sourcesContent":["import type { Context } from \"@opentelemetry/api\";\nimport type { IAppResponse } from \"shared\";\nimport type { EventRingBuffer } from \"./buffers\";\n\nexport const SSEWarningCode = {\n  BUFFER_OVERFLOW_RESTART: \"BUFFER_OVERFLOW_RESTART\",\n} as const satisfies Record<string, string>;\n\nexport type SSEWarningCode =\n  (typeof SSEWarningCode)[keyof typeof SSEWarningCode];\n\nexport const SSEErrorCode = {\n  TEMPORARY_UNAVAILABLE: \"TEMPORARY_UNAVAILABLE\",\n  TIMEOUT: \"TIMEOUT\",\n  INTERNAL_ERROR: \"INTERNAL_ERROR\",\n  INVALID_REQUEST: \"INVALID_REQUEST\",\n  STREAM_ABORTED: \"STREAM_ABORTED\",\n  STREAM_EVICTED: \"STREAM_EVICTED\",\n} as const satisfies Record<string, string>;\n\nexport type SSEErrorCode = (typeof SSEErrorCode)[keyof typeof SSEErrorCode];\n\nexport interface SSEError {\n  error: string;\n  code: SSEErrorCode;\n}\n\nexport interface BufferedEvent {\n  id: string;\n  type: string;\n  data: string;\n  timestamp: number;\n}\n\nexport interface StreamEntry {\n  streamId: string;\n  generator: AsyncGenerator<any, void, unknown>;\n  eventBuffer: EventRingBuffer;\n  clients: Set<IAppResponse>;\n  isCompleted: boolean;\n  lastAccess: number;\n  abortController: AbortController;\n  traceContext: Context;\n}\n\nexport interface StreamOperation {\n  controller: AbortController;\n  type: \"query\" | \"stream\";\n  heartbeat?: NodeJS.Timeout;\n}\n"],"mappings":";AAIA,MAAa,iBAAiB,EAC5B,yBAAyB,2BAC1B;AAKD,MAAa,eAAe;CAC1B,uBAAuB;CACvB,SAAS;CACT,gBAAgB;CAChB,iBAAiB;CACjB,gBAAgB;CAChB,gBAAgB;CACjB"}

package/dist/telemetry/config.js

@@ -1,4 +1,5 @@
 //#region src/telemetry/config.ts
+/** Converts a TelemetryOptions value (boolean, object, or undefined) into a fully resolved config with explicit traces/metrics/logs flags. Defaults to all enabled. */
 function normalizeTelemetryOptions(config) {
 	if (typeof config === "undefined" || typeof config === "boolean") {
 		const value = config ?? true;

package/dist/telemetry/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","names":[],"sources":["../../src/telemetry/config.ts"],"sourcesContent":["import type { TelemetryOptions } from \"shared\";\n\nexport interface TelemetryProviderConfig {\n  traces: boolean;\n  metrics: boolean;\n  logs: boolean;\n}\n\nexport function normalizeTelemetryOptions(\n  config?: TelemetryOptions,\n): TelemetryProviderConfig {\n  if (typeof config === \"undefined\" || typeof config === \"boolean\") {\n    const value = config ?? true;\n    return {\n      traces: value,\n      metrics: value,\n      logs: value,\n    };\n  }\n\n  return {\n    traces: config?.traces ?? true,\n    metrics: config?.metrics ?? true,\n    logs: config?.logs ?? true,\n  };\n}\n"],"mappings":";AAQA,SAAgB,0BACd,QACyB;AACzB,KAAI,OAAO,WAAW,eAAe,OAAO,WAAW,WAAW;EAChE,MAAM,QAAQ,UAAU;AACxB,SAAO;GACL,QAAQ;GACR,SAAS;GACT,MAAM;GACP;;AAGH,QAAO;EACL,QAAQ,QAAQ,UAAU;EAC1B,SAAS,QAAQ,WAAW;EAC5B,MAAM,QAAQ,QAAQ;EACvB"}
+{"version":3,"file":"config.js","names":[],"sources":["../../src/telemetry/config.ts"],"sourcesContent":["import type { TelemetryOptions } from \"shared\";\n\nexport interface TelemetryProviderConfig {\n  traces: boolean;\n  metrics: boolean;\n  logs: boolean;\n}\n\n/** Converts a TelemetryOptions value (boolean, object, or undefined) into a fully resolved config with explicit traces/metrics/logs flags. Defaults to all enabled. */\nexport function normalizeTelemetryOptions(\n  config?: TelemetryOptions,\n): TelemetryProviderConfig {\n  if (typeof config === \"undefined\" || typeof config === \"boolean\") {\n    const value = config ?? true;\n    return {\n      traces: value,\n      metrics: value,\n      logs: value,\n    };\n  }\n\n  return {\n    traces: config?.traces ?? true,\n    metrics: config?.metrics ?? true,\n    logs: config?.logs ?? true,\n  };\n}\n"],"mappings":";;AASA,SAAgB,0BACd,QACyB;AACzB,KAAI,OAAO,WAAW,eAAe,OAAO,WAAW,WAAW;EAChE,MAAM,QAAQ,UAAU;AACxB,SAAO;GACL,QAAQ;GACR,SAAS;GACT,MAAM;GACP;;AAGH,QAAO;EACL,QAAQ,QAAQ,UAAU;EAC1B,SAAS,QAAQ,WAAW;EAC5B,MAAM,QAAQ,QAAQ;EACvB"}

package/dist/telemetry/index.d.ts

@@ -1,6 +1,6 @@
 import "./config.js";
 import "./instrumentations.js";
-import { ITelemetry, InstrumentConfig, TelemetryConfig } from "./types.js";
+import { ITelemetry, TelemetryConfig } from "./types.js";
 import "./telemetry-provider.js";
 import "./telemetry-manager.js";
 import { Counter, Histogram, Span as Span$1, SpanStatusCode } from "@opentelemetry/api";

package/dist/telemetry/noop.js.map

@@ -1 +1 @@
-{"version":3,"file":"noop.js","names":[],"sources":["../../src/telemetry/noop.ts"],"sourcesContent":["// Our own noop tracer implementation.\n// Why?\n// Unfortunately, noop tracer is not exported from the api package, unlike noop meter and noop logger.\n// Read more: https://github.com/open-telemetry/opentelemetry-js/issues/3455\n// and https://github.com/open-telemetry/opentelemetry-js/issues/4518\n//\n// The original implementation is here: https://github.com/open-telemetry/opentelemetry-js/blob/a7acd9355cd0c1da63d285dfb960efeacc3cbc15/api/src/trace/NoopTracer.ts#L32\n// licensed under the Apache License 2.0.\n// Our own implementation is much simpler but will do the job for our needs.\n\nimport type {\n  Context,\n  Span,\n  SpanContext,\n  SpanOptions,\n  Tracer,\n} from \"@opentelemetry/api\";\nimport {\n  createNoopMeter,\n  INVALID_SPAN_CONTEXT,\n  type SpanStatusCode,\n} from \"@opentelemetry/api\";\n\nclass NonRecordingSpan implements Span {\n  private readonly _spanContext: SpanContext;\n\n  constructor(spanContext: SpanContext = INVALID_SPAN_CONTEXT) {\n    this._spanContext = spanContext;\n  }\n\n  spanContext(): SpanContext {\n    return this._spanContext;\n  }\n\n  setAttribute(_key: string, _value: any): this {\n    return this;\n  }\n\n  setAttributes(_attributes: any): this {\n    return this;\n  }\n\n  addEvent(\n    _name: string,\n    _attributesOrStartTime?: any,\n    _startTime?: any,\n  ): this {\n    return this;\n  }\n\n  addLink(_link: any): this {\n    return this;\n  }\n\n  addLinks(_links: any[]): this {\n    return this;\n  }\n\n  setStatus(_status: { code: SpanStatusCode; message?: string }): this {\n    return this;\n  }\n\n  updateName(_name: string): this {\n    return this;\n  }\n\n  end(_endTime?: number): void {}\n\n  isRecording(): boolean {\n    return false;\n  }\n\n  recordException(_exception: any, _time?: number): void {}\n}\n\nexport class NoopTracer implements Tracer {\n  startSpan(_name: string, _options?: SpanOptions, _context?: Context): Span {\n    return new NonRecordingSpan(INVALID_SPAN_CONTEXT);\n  }\n\n  startActiveSpan<F extends (span: Span) => any>(\n    _name: string,\n    ...args: [F] | [SpanOptions, F] | [SpanOptions, Context, F]\n  ): ReturnType<F> | undefined {\n    const fn = args[args.length - 1] as F;\n\n    if (typeof fn !== \"function\") {\n      return undefined as ReturnType<F>;\n    }\n\n    return fn(new NonRecordingSpan(INVALID_SPAN_CONTEXT));\n  }\n}\n\nexport const NOOP_TRACER = new NoopTracer();\nexport const NOOP_METER = createNoopMeter();\nexport { NOOP_LOGGER } from \"@opentelemetry/api-logs\";\n"],"mappings":";;;;AAuBA,IAAM,mBAAN,MAAuC;CACrC,AAAiB;CAEjB,YAAY,cAA2B,sBAAsB;AAC3D,OAAK,eAAe;;CAGtB,cAA2B;AACzB,SAAO,KAAK;;CAGd,aAAa,MAAc,QAAmB;AAC5C,SAAO;;CAGT,cAAc,aAAwB;AACpC,SAAO;;CAGT,SACE,OACA,wBACA,YACM;AACN,SAAO;;CAGT,QAAQ,OAAkB;AACxB,SAAO;;CAGT,SAAS,QAAqB;AAC5B,SAAO;;CAGT,UAAU,SAA2D;AACnE,SAAO;;CAGT,WAAW,OAAqB;AAC9B,SAAO;;CAGT,IAAI,UAAyB;CAE7B,cAAuB;AACrB,SAAO;;CAGT,gBAAgB,YAAiB,OAAsB;;AAGzD,IAAa,aAAb,MAA0C;CACxC,UAAU,OAAe,UAAwB,UAA0B;AACzE,SAAO,IAAI,iBAAiB,qBAAqB;;CAGnD,gBACE,OACA,GAAG,MACwB;EAC3B,MAAM,KAAK,KAAK,KAAK,SAAS;AAE9B,MAAI,OAAO,OAAO,WAChB;AAGF,SAAO,GAAG,IAAI,iBAAiB,qBAAqB,CAAC;;;AAIzD,MAAa,cAAc,IAAI,YAAY;AAC3C,MAAa,aAAa,iBAAiB"}
+{"version":3,"file":"noop.js","names":[],"sources":["../../src/telemetry/noop.ts"],"sourcesContent":["// Our own noop tracer implementation.\n// Why?\n// Unfortunately, noop tracer is not exported from the api package, unlike noop meter and noop logger.\n// Read more: https://github.com/open-telemetry/opentelemetry-js/issues/3455\n// and https://github.com/open-telemetry/opentelemetry-js/issues/4518\n//\n// The original implementation is here: https://github.com/open-telemetry/opentelemetry-js/blob/a7acd9355cd0c1da63d285dfb960efeacc3cbc15/api/src/trace/NoopTracer.ts#L32\n// licensed under the Apache License 2.0.\n// Our own implementation is much simpler but will do the job for our needs.\n\nimport type {\n  Context,\n  Span,\n  SpanContext,\n  SpanOptions,\n  Tracer,\n} from \"@opentelemetry/api\";\nimport {\n  createNoopMeter,\n  INVALID_SPAN_CONTEXT,\n  type SpanStatusCode,\n} from \"@opentelemetry/api\";\n\nclass NonRecordingSpan implements Span {\n  private readonly _spanContext: SpanContext;\n\n  constructor(spanContext: SpanContext = INVALID_SPAN_CONTEXT) {\n    this._spanContext = spanContext;\n  }\n\n  spanContext(): SpanContext {\n    return this._spanContext;\n  }\n\n  setAttribute(_key: string, _value: any): this {\n    return this;\n  }\n\n  setAttributes(_attributes: any): this {\n    return this;\n  }\n\n  addEvent(\n    _name: string,\n    _attributesOrStartTime?: any,\n    _startTime?: any,\n  ): this {\n    return this;\n  }\n\n  addLink(_link: any): this {\n    return this;\n  }\n\n  addLinks(_links: any[]): this {\n    return this;\n  }\n\n  setStatus(_status: { code: SpanStatusCode; message?: string }): this {\n    return this;\n  }\n\n  updateName(_name: string): this {\n    return this;\n  }\n\n  end(_endTime?: number): void {}\n\n  isRecording(): boolean {\n    return false;\n  }\n\n  recordException(_exception: any, _time?: number): void {}\n}\n\nclass NoopTracer implements Tracer {\n  startSpan(_name: string, _options?: SpanOptions, _context?: Context): Span {\n    return new NonRecordingSpan(INVALID_SPAN_CONTEXT);\n  }\n\n  startActiveSpan<F extends (span: Span) => any>(\n    _name: string,\n    ...args: [F] | [SpanOptions, F] | [SpanOptions, Context, F]\n  ): ReturnType<F> | undefined {\n    const fn = args[args.length - 1] as F;\n\n    if (typeof fn !== \"function\") {\n      return undefined as ReturnType<F>;\n    }\n\n    return fn(new NonRecordingSpan(INVALID_SPAN_CONTEXT));\n  }\n}\n\nexport const NOOP_TRACER = new NoopTracer();\nexport const NOOP_METER = createNoopMeter();\nexport { NOOP_LOGGER } from \"@opentelemetry/api-logs\";\n"],"mappings":";;;;AAuBA,IAAM,mBAAN,MAAuC;CACrC,AAAiB;CAEjB,YAAY,cAA2B,sBAAsB;AAC3D,OAAK,eAAe;;CAGtB,cAA2B;AACzB,SAAO,KAAK;;CAGd,aAAa,MAAc,QAAmB;AAC5C,SAAO;;CAGT,cAAc,aAAwB;AACpC,SAAO;;CAGT,SACE,OACA,wBACA,YACM;AACN,SAAO;;CAGT,QAAQ,OAAkB;AACxB,SAAO;;CAGT,SAAS,QAAqB;AAC5B,SAAO;;CAGT,UAAU,SAA2D;AACnE,SAAO;;CAGT,WAAW,OAAqB;AAC9B,SAAO;;CAGT,IAAI,UAAyB;CAE7B,cAAuB;AACrB,SAAO;;CAGT,gBAAgB,YAAiB,OAAsB;;AAGzD,IAAM,aAAN,MAAmC;CACjC,UAAU,OAAe,UAAwB,UAA0B;AACzE,SAAO,IAAI,iBAAiB,qBAAqB;;CAGnD,gBACE,OACA,GAAG,MACwB;EAC3B,MAAM,KAAK,KAAK,KAAK,SAAS;AAE9B,MAAI,OAAO,OAAO,WAChB;AAGF,SAAO,GAAG,IAAI,iBAAiB,qBAAqB,CAAC;;;AAIzD,MAAa,cAAc,IAAI,YAAY;AAC3C,MAAa,aAAa,iBAAiB"}

package/dist/telemetry/types.d.ts

@@ -71,5 +71,5 @@ interface ITelemetry {
   registerInstrumentations(instrumentations: Instrumentation[]): void;
 }
 //#endregion
-export { ITelemetry, InstrumentConfig, TelemetryConfig };
+export { ITelemetry, TelemetryConfig };
 //# sourceMappingURL=types.d.ts.map

package/dist/type-generator/query-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"query-registry.js","names":[],"sources":["../../src/type-generator/query-registry.ts"],"sourcesContent":["import fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport pc from \"picocolors\";\nimport { createLogger } from \"../logging/logger\";\nimport { CACHE_VERSION, hashSQL, loadCache, saveCache } from \"./cache\";\nimport { Spinner } from \"./spinner\";\nimport {\n  type DatabricksStatementExecutionResponse,\n  type QuerySchema,\n  sqlTypeToHelper,\n  sqlTypeToMarker,\n} from \"./types\";\n\nconst logger = createLogger(\"type-generator:query-registry\");\n\n/**\n * Parse a raw API/SDK error into a structured code + message.\n * Handles Databricks-style JSON bodies embedded in the message string,\n * e.g. `Response from server (Bad Request) {\"error_code\":\"...\",\"message\":\"...\"}`.\n */\nfunction parseError(raw: string): { code?: string; message: string } {\n  const jsonMatch = raw.match(/\\{[\\s\\S]*\\}/);\n  if (jsonMatch) {\n    try {\n      const parsed = JSON.parse(jsonMatch[0]);\n      if (parsed.error_code || parsed.message) {\n        return {\n          code: parsed.error_code,\n          message: parsed.message || raw,\n        };\n      }\n    } catch {\n      // not valid JSON, fall through\n    }\n  }\n  return { message: raw };\n}\n\n/**\n * Extract parameters from a SQL query\n * @param sql - the SQL query to extract parameters from\n * @returns an array of parameter names\n */\nexport function extractParameters(sql: string): string[] {\n  const matches = sql.matchAll(/:([a-zA-Z_]\\w*)/g);\n  const params = new Set<string>();\n  for (const match of matches) {\n    params.add(match[1]);\n  }\n  return Array.from(params);\n}\n\n// parameters that are injected by the server\nexport const SERVER_INJECTED_PARAMS = [\"workspaceId\"];\n\n/**\n * Generates the TypeScript type literal for query parameters from SQL.\n * Shared by both the success and failure paths.\n */\nfunction formatParametersType(sql: string): string {\n  const params = extractParameters(sql).filter(\n    (p) => !SERVER_INJECTED_PARAMS.includes(p),\n  );\n  const paramTypes = extractParameterTypes(sql);\n\n  return params.length > 0\n    ? `{\\n      ${params\n        .map((p) => {\n          const sqlType = paramTypes[p];\n          const markerType = sqlType\n            ? sqlTypeToMarker[sqlType]\n            : \"SQLTypeMarker\";\n          const helper = sqlType ? sqlTypeToHelper[sqlType] : \"sql.*()\";\n          return `/** ${sqlType || \"any\"} - use ${helper} */\\n      ${p}: ${markerType}`;\n        })\n        .join(\";\\n      \")};\\n    }`\n    : \"Record<string, never>\";\n}\n\nexport function convertToQueryType(\n  result: DatabricksStatementExecutionResponse,\n  sql: string,\n  queryName: string,\n): { type: string; hasResults: boolean } {\n  const dataRows = result.result?.data_array || [];\n  const columns = dataRows.map((row) => ({\n    name: row[0] || \"\",\n    type_name: row[1]?.toUpperCase() || \"STRING\",\n    comment: row[2] || undefined,\n  }));\n\n  const paramsType = formatParametersType(sql);\n\n  // generate result fields with JSDoc\n  const resultFields = columns.map((column) => {\n    const normalizedType = normalizeTypeName(column.type_name);\n    const mappedType = typeMap[normalizedType] || \"unknown\";\n    // validate column name is a valid identifier\n    const name = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(column.name)\n      ? column.name\n      : `\"${column.name}\"`;\n\n    // generate comment for column\n    const comment = column.comment\n      ? `/** ${column.comment} */\\n      `\n      : `/** @sqlType ${column.type_name} */\\n      `;\n\n    return `${comment}${name}: ${mappedType}`;\n  });\n\n  const hasResults = resultFields.length > 0;\n\n  const type = `{\n    name: \"${queryName}\";\n    parameters: ${paramsType};\n    result: ${\n      hasResults\n        ? `Array<{\n      ${resultFields.join(\";\\n      \")};\n    }>`\n        : \"unknown\"\n    };\n  }`;\n\n  return { type, hasResults };\n}\n\n/**\n * Used when DESCRIBE QUERY fails so the query still appears in QueryRegistry.\n * Generates a type with unknown result from SQL alone (no warehouse call).\n */\nfunction generateUnknownResultQuery(sql: string, queryName: string): string {\n  const paramsType = formatParametersType(sql);\n\n  return `{\n    name: \"${queryName}\";\n    parameters: ${paramsType};\n    result: unknown;\n  }`;\n}\n\nexport function extractParameterTypes(sql: string): Record<string, string> {\n  const paramTypes: Record<string, string> = {};\n  const regex =\n    /--\\s*@param\\s+(\\w+)\\s+(STRING|NUMERIC|BOOLEAN|DATE|TIMESTAMP|BINARY)/gi;\n  const matches = sql.matchAll(regex);\n  for (const match of matches) {\n    const [, paramName, paramType] = match;\n    paramTypes[paramName] = paramType.toUpperCase();\n  }\n\n  return paramTypes;\n}\n\n/**\n * Generate query schemas from a folder of SQL files\n * It uses DESCRIBE QUERY to get the schema without executing the query\n * @param queryFolder - the folder containing the SQL files\n * @param warehouseId - the warehouse id to use for schema analysis\n * @param options - options for the query generation\n * @param options.noCache - if true, skip the cache and regenerate all types\n * @returns an array of query schemas\n */\nexport async function generateQueriesFromDescribe(\n  queryFolder: string,\n  warehouseId: string,\n  options: { noCache?: boolean; concurrency?: number } = {},\n): Promise<QuerySchema[]> {\n  const { noCache = false, concurrency: rawConcurrency = 10 } = options;\n  const concurrency =\n    typeof rawConcurrency === \"number\" && Number.isFinite(rawConcurrency)\n      ? Math.max(1, Math.floor(rawConcurrency))\n      : 10;\n\n  // read all query files and cache in parallel\n  const [allFiles, cache] = await Promise.all([\n    fs.readdir(queryFolder),\n    noCache\n      ? ({ version: CACHE_VERSION, queries: {} } as Awaited<\n          ReturnType<typeof loadCache>\n        >)\n      : loadCache(),\n  ]);\n\n  const queryFiles = allFiles.filter((file) => file.endsWith(\".sql\"));\n  logger.debug(\"Found %d SQL queries\", queryFiles.length);\n\n  const client = new WorkspaceClient({});\n  const spinner = new Spinner();\n\n  // Read all SQL files in parallel\n  const sqlContents = await Promise.all(\n    queryFiles.map((file) => fs.readFile(path.join(queryFolder, file), \"utf8\")),\n  );\n\n  const startTime = performance.now();\n\n  // Phase 1: Check cache, separate cached vs uncached\n  const cachedResults: Array<{ index: number; schema: QuerySchema }> = [];\n  const uncachedQueries: Array<{\n    index: number;\n    queryName: string;\n    sql: string;\n    sqlHash: string;\n    cleanedSql: string;\n  }> = [];\n  const logEntries: Array<{\n    queryName: string;\n    status: \"HIT\" | \"MISS\";\n    failed?: boolean;\n    error?: { code?: string; message: string };\n  }> = [];\n\n  for (let i = 0; i < queryFiles.length; i++) {\n    const file = queryFiles[i];\n    const rawName = path.basename(file, \".sql\");\n    const queryName = normalizeQueryName(rawName);\n\n    const sql = sqlContents[i];\n    const sqlHash = hashSQL(sql);\n\n    const cached = cache.queries[queryName];\n    if (cached && cached.hash === sqlHash && !cached.retry) {\n      cachedResults.push({\n        index: i,\n        schema: { name: queryName, type: cached.type },\n      });\n      logEntries.push({ queryName, status: \"HIT\" });\n    } else {\n      const sqlWithDefaults = sql.replace(/:([a-zA-Z_]\\w*)/g, \"''\");\n      const cleanedSql = sqlWithDefaults.trim().replace(/;\\s*$/, \"\");\n      uncachedQueries.push({ index: i, queryName, sql, sqlHash, cleanedSql });\n    }\n  }\n\n  // Phase 2: Execute all uncached DESCRIBE calls in parallel\n  type DescribeResult =\n    | {\n        status: \"ok\";\n        index: number;\n        schema: QuerySchema;\n        cacheEntry: { hash: string; type: string; retry: boolean };\n      }\n    | {\n        status: \"fail\";\n        index: number;\n        schema: QuerySchema;\n        cacheEntry: { hash: string; type: string; retry: boolean };\n        error: { code?: string; message: string };\n      };\n\n  const freshResults: Array<{ index: number; schema: QuerySchema }> = [];\n\n  if (uncachedQueries.length > 0) {\n    let completed = 0;\n    const total = uncachedQueries.length;\n    spinner.start(\n      `Describing ${total} ${total === 1 ? \"query\" : \"queries\"} (0/${total})`,\n    );\n\n    const describeOne = async ({\n      index,\n      queryName,\n      sql,\n      sqlHash,\n      cleanedSql,\n    }: (typeof uncachedQueries)[number]): Promise<DescribeResult> => {\n      const result = (await client.statementExecution.executeStatement({\n        statement: `DESCRIBE QUERY ${cleanedSql}`,\n        warehouse_id: warehouseId,\n      })) as DatabricksStatementExecutionResponse;\n\n      completed++;\n      spinner.update(\n        `Describing ${total} ${total === 1 ? \"query\" : \"queries\"} (${completed}/${total})`,\n      );\n\n      logger.debug(\n        \"DESCRIBE result for %s: state=%s, rows=%d\",\n        queryName,\n        result.status.state,\n        result.result?.data_array?.length ?? 0,\n      );\n\n      if (result.status.state === \"FAILED\") {\n        const sqlError =\n          result.status.error?.message || \"Query execution failed\";\n        logger.warn(\"DESCRIBE failed for %s: %s\", queryName, sqlError);\n        const type = generateUnknownResultQuery(sql, queryName);\n        return {\n          status: \"fail\",\n          index,\n          schema: { name: queryName, type },\n          cacheEntry: { hash: sqlHash, type, retry: true },\n          error: parseError(sqlError),\n        };\n      }\n\n      const { type, hasResults } = convertToQueryType(result, sql, queryName);\n      return {\n        status: \"ok\",\n        index,\n        schema: { name: queryName, type },\n        cacheEntry: { hash: sqlHash, type, retry: !hasResults },\n      };\n    };\n\n    // Process in chunks, saving cache after each chunk\n    const processBatchResults = (\n      settled: PromiseSettledResult<DescribeResult>[],\n      batchOffset: number,\n    ) => {\n      for (let i = 0; i < settled.length; i++) {\n        const entry = settled[i];\n        const { queryName } = uncachedQueries[batchOffset + i];\n\n        if (entry.status === \"fulfilled\") {\n          const res = entry.value;\n          freshResults.push({ index: res.index, schema: res.schema });\n          cache.queries[queryName] = res.cacheEntry;\n          logEntries.push({\n            queryName,\n            status: \"MISS\",\n            failed: res.status === \"fail\",\n            error: res.status === \"fail\" ? res.error : undefined,\n          });\n        } else {\n          const { sql, sqlHash, index } = uncachedQueries[batchOffset + i];\n          const reason =\n            entry.reason instanceof Error\n              ? entry.reason.message\n              : String(entry.reason);\n          logger.warn(\"DESCRIBE rejected for %s: %s\", queryName, reason);\n          const type = generateUnknownResultQuery(sql, queryName);\n          freshResults.push({ index, schema: { name: queryName, type } });\n          cache.queries[queryName] = { hash: sqlHash, type, retry: true };\n          logEntries.push({\n            queryName,\n            status: \"MISS\",\n            failed: true,\n            error: parseError(reason),\n          });\n        }\n      }\n    };\n\n    if (uncachedQueries.length > concurrency) {\n      for (let b = 0; b < uncachedQueries.length; b += concurrency) {\n        const batch = uncachedQueries.slice(b, b + concurrency);\n        const batchResults = await Promise.allSettled(batch.map(describeOne));\n        processBatchResults(batchResults, b);\n        await saveCache(cache);\n      }\n    } else {\n      const settled = await Promise.allSettled(\n        uncachedQueries.map(describeOne),\n      );\n      processBatchResults(settled, 0);\n      await saveCache(cache);\n    }\n\n    spinner.stop(\"\");\n  }\n\n  const elapsed = ((performance.now() - startTime) / 1000).toFixed(2);\n\n  // Print formatted table\n  if (logEntries.length > 0) {\n    const maxNameLen = Math.max(...logEntries.map((e) => e.queryName.length));\n    const separator = pc.dim(\"─\".repeat(50));\n    console.log(\"\");\n    console.log(\n      `  ${pc.bold(\"Typegen Queries\")} ${pc.dim(`(${logEntries.length})`)}`,\n    );\n    console.log(`  ${separator}`);\n    for (const entry of logEntries) {\n      const tag = entry.failed\n        ? pc.bold(pc.red(\"ERROR\"))\n        : entry.status === \"HIT\"\n          ? `cache ${pc.bold(pc.green(\"HIT  \"))}`\n          : `cache ${pc.bold(pc.yellow(\"MISS \"))}`;\n      const rawName = entry.queryName.padEnd(maxNameLen);\n      const name = entry.failed ? pc.dim(pc.strikethrough(rawName)) : rawName;\n      const errorCode = entry.error?.message.match(/\\[([^\\]]+)\\]/)?.[1];\n      const reason = errorCode ? `  ${pc.dim(errorCode)}` : \"\";\n      console.log(`  ${tag}  ${name}${reason}`);\n    }\n    const newCount = logEntries.filter(\n      (e) => e.status === \"MISS\" && !e.failed,\n    ).length;\n    const cacheCount = logEntries.filter(\n      (e) => e.status === \"HIT\" && !e.failed,\n    ).length;\n    const errorCount = logEntries.filter((e) => e.failed).length;\n    console.log(`  ${separator}`);\n    const parts = [`${newCount} new`, `${cacheCount} from cache`];\n    if (errorCount > 0)\n      parts.push(`${errorCount} ${errorCount === 1 ? \"error\" : \"errors\"}`);\n    console.log(`  ${parts.join(\", \")}. ${pc.dim(`${elapsed}s`)}`);\n    console.log(\"\");\n  }\n\n  // Merge and sort by original file index for deterministic output\n  return [...cachedResults, ...freshResults]\n    .sort((a, b) => a.index - b.index)\n    .map((r) => r.schema);\n}\n\n/**\n * Normalize query name by removing the .obo extension\n * @param queryName - the query name to normalize\n * @returns the normalized query name\n */\nexport function normalizeQueryName(fileName: string): string {\n  return fileName.replace(/\\.obo$/, \"\");\n}\n\n/**\n * Normalize SQL type name by removing parameters/generics\n * Examples:\n *   DECIMAL(38,6) -> DECIMAL\n *   ARRAY<STRING> -> ARRAY\n *   MAP<STRING,INT> -> MAP\n *   STRUCT<name:STRING> -> STRUCT\n *   INTERVAL DAY TO SECOND -> INTERVAL\n *   GEOGRAPHY(4326) -> GEOGRAPHY\n */\nexport function normalizeTypeName(typeName: string): string {\n  return typeName\n    .replace(/\\(.*\\)$/, \"\") // remove (p, s) eg: DECIMAL(38,6) -> DECIMAL\n    .replace(/<.*>$/, \"\") // remove <T> eg: ARRAY<STRING> -> ARRAY\n    .split(\" \")[0]; // take first word eg: INTERVAL DAY TO SECOND -> INTERVAL\n}\n\n/** Type Map for Databricks data types to JavaScript types */\nconst typeMap: Record<string, string> = {\n  // string types\n  STRING: \"string\",\n  BINARY: \"string\",\n  // boolean\n  BOOLEAN: \"boolean\",\n  // numeric types\n  TINYINT: \"number\",\n  SMALLINT: \"number\",\n  INT: \"number\",\n  BIGINT: \"number\",\n  FLOAT: \"number\",\n  DOUBLE: \"number\",\n  DECIMAL: \"number\",\n  // date/time types\n  DATE: \"string\",\n  TIMESTAMP: \"string\",\n  TIMESTAMP_NTZ: \"string\",\n  INTERVAL: \"string\",\n  // complex types\n  ARRAY: \"unknown[]\",\n  MAP: \"Record<string, unknown>\",\n  STRUCT: \"Record<string, unknown>\",\n  OBJECT: \"Record<string, unknown>\",\n  VARIANT: \"unknown\",\n  // spatial types\n  GEOGRAPHY: \"unknown\",\n  GEOMETRY: \"unknown\",\n  // null type\n  VOID: \"null\",\n};\n"],"mappings":"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"}
+{"version":3,"file":"query-registry.js","names":[],"sources":["../../src/type-generator/query-registry.ts"],"sourcesContent":["import fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport pc from \"picocolors\";\nimport { createLogger } from \"../logging/logger\";\nimport { CACHE_VERSION, hashSQL, loadCache, saveCache } from \"./cache\";\nimport { Spinner } from \"./spinner\";\nimport {\n  type DatabricksStatementExecutionResponse,\n  type QuerySchema,\n  sqlTypeToHelper,\n  sqlTypeToMarker,\n} from \"./types\";\n\nconst logger = createLogger(\"type-generator:query-registry\");\n\n/**\n * Parse a raw API/SDK error into a structured code + message.\n * Handles Databricks-style JSON bodies embedded in the message string,\n * e.g. `Response from server (Bad Request) {\"error_code\":\"...\",\"message\":\"...\"}`.\n */\nfunction parseError(raw: string): { code?: string; message: string } {\n  const jsonMatch = raw.match(/\\{[\\s\\S]*\\}/);\n  if (jsonMatch) {\n    try {\n      const parsed = JSON.parse(jsonMatch[0]);\n      if (parsed.error_code || parsed.message) {\n        return {\n          code: parsed.error_code,\n          message: parsed.message || raw,\n        };\n      }\n    } catch {\n      // not valid JSON, fall through\n    }\n  }\n  return { message: raw };\n}\n\n/**\n * Extract parameters from a SQL query\n * @param sql - the SQL query to extract parameters from\n * @returns an array of parameter names\n */\nexport function extractParameters(sql: string): string[] {\n  const matches = sql.matchAll(/:([a-zA-Z_]\\w*)/g);\n  const params = new Set<string>();\n  for (const match of matches) {\n    params.add(match[1]);\n  }\n  return Array.from(params);\n}\n\n// parameters that are injected by the server\nexport const SERVER_INJECTED_PARAMS = [\"workspaceId\"];\n\n/**\n * Generates the TypeScript type literal for query parameters from SQL.\n * Shared by both the success and failure paths.\n */\nfunction formatParametersType(sql: string): string {\n  const params = extractParameters(sql).filter(\n    (p) => !SERVER_INJECTED_PARAMS.includes(p),\n  );\n  const paramTypes = extractParameterTypes(sql);\n\n  return params.length > 0\n    ? `{\\n      ${params\n        .map((p) => {\n          const sqlType = paramTypes[p];\n          const markerType = sqlType\n            ? sqlTypeToMarker[sqlType]\n            : \"SQLTypeMarker\";\n          const helper = sqlType ? sqlTypeToHelper[sqlType] : \"sql.*()\";\n          return `/** ${sqlType || \"any\"} - use ${helper} */\\n      ${p}: ${markerType}`;\n        })\n        .join(\";\\n      \")};\\n    }`\n    : \"Record<string, never>\";\n}\n\nexport function convertToQueryType(\n  result: DatabricksStatementExecutionResponse,\n  sql: string,\n  queryName: string,\n): { type: string; hasResults: boolean } {\n  const dataRows = result.result?.data_array || [];\n  const columns = dataRows.map((row) => ({\n    name: row[0] || \"\",\n    type_name: row[1]?.toUpperCase() || \"STRING\",\n    comment: row[2] || undefined,\n  }));\n\n  const paramsType = formatParametersType(sql);\n\n  // generate result fields with JSDoc\n  const resultFields = columns.map((column) => {\n    const normalizedType = normalizeTypeName(column.type_name);\n    const mappedType = typeMap[normalizedType] || \"unknown\";\n    // validate column name is a valid identifier\n    const name = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(column.name)\n      ? column.name\n      : `\"${column.name}\"`;\n\n    // generate comment for column\n    const comment = column.comment\n      ? `/** ${column.comment} */\\n      `\n      : `/** @sqlType ${column.type_name} */\\n      `;\n\n    return `${comment}${name}: ${mappedType}`;\n  });\n\n  const hasResults = resultFields.length > 0;\n\n  const type = `{\n    name: \"${queryName}\";\n    parameters: ${paramsType};\n    result: ${\n      hasResults\n        ? `Array<{\n      ${resultFields.join(\";\\n      \")};\n    }>`\n        : \"unknown\"\n    };\n  }`;\n\n  return { type, hasResults };\n}\n\n/**\n * Used when DESCRIBE QUERY fails so the query still appears in QueryRegistry.\n * Generates a type with unknown result from SQL alone (no warehouse call).\n */\nfunction generateUnknownResultQuery(sql: string, queryName: string): string {\n  const paramsType = formatParametersType(sql);\n\n  return `{\n    name: \"${queryName}\";\n    parameters: ${paramsType};\n    result: unknown;\n  }`;\n}\n\nexport function extractParameterTypes(sql: string): Record<string, string> {\n  const paramTypes: Record<string, string> = {};\n  const regex =\n    /--\\s*@param\\s+(\\w+)\\s+(STRING|NUMERIC|BOOLEAN|DATE|TIMESTAMP|BINARY)/gi;\n  const matches = sql.matchAll(regex);\n  for (const match of matches) {\n    const [, paramName, paramType] = match;\n    paramTypes[paramName] = paramType.toUpperCase();\n  }\n\n  return paramTypes;\n}\n\n/**\n * Generate query schemas from a folder of SQL files\n * It uses DESCRIBE QUERY to get the schema without executing the query\n * @param queryFolder - the folder containing the SQL files\n * @param warehouseId - the warehouse id to use for schema analysis\n * @param options - options for the query generation\n * @param options.noCache - if true, skip the cache and regenerate all types\n * @returns an array of query schemas\n */\nexport async function generateQueriesFromDescribe(\n  queryFolder: string,\n  warehouseId: string,\n  options: { noCache?: boolean; concurrency?: number } = {},\n): Promise<QuerySchema[]> {\n  const { noCache = false, concurrency: rawConcurrency = 10 } = options;\n  const concurrency =\n    typeof rawConcurrency === \"number\" && Number.isFinite(rawConcurrency)\n      ? Math.max(1, Math.floor(rawConcurrency))\n      : 10;\n\n  // read all query files and cache in parallel\n  const [allFiles, cache] = await Promise.all([\n    fs.readdir(queryFolder),\n    noCache\n      ? ({ version: CACHE_VERSION, queries: {} } as Awaited<\n          ReturnType<typeof loadCache>\n        >)\n      : loadCache(),\n  ]);\n\n  const queryFiles = allFiles.filter((file) => file.endsWith(\".sql\"));\n  logger.debug(\"Found %d SQL queries\", queryFiles.length);\n\n  const client = new WorkspaceClient({});\n  const spinner = new Spinner();\n\n  // Read all SQL files in parallel\n  const sqlContents = await Promise.all(\n    queryFiles.map((file) => fs.readFile(path.join(queryFolder, file), \"utf8\")),\n  );\n\n  const startTime = performance.now();\n\n  // Phase 1: Check cache, separate cached vs uncached\n  const cachedResults: Array<{ index: number; schema: QuerySchema }> = [];\n  const uncachedQueries: Array<{\n    index: number;\n    queryName: string;\n    sql: string;\n    sqlHash: string;\n    cleanedSql: string;\n  }> = [];\n  const logEntries: Array<{\n    queryName: string;\n    status: \"HIT\" | \"MISS\";\n    failed?: boolean;\n    error?: { code?: string; message: string };\n  }> = [];\n\n  for (let i = 0; i < queryFiles.length; i++) {\n    const file = queryFiles[i];\n    const rawName = path.basename(file, \".sql\");\n    const queryName = normalizeQueryName(rawName);\n\n    const sql = sqlContents[i];\n    const sqlHash = hashSQL(sql);\n\n    const cached = cache.queries[queryName];\n    if (cached && cached.hash === sqlHash && !cached.retry) {\n      cachedResults.push({\n        index: i,\n        schema: { name: queryName, type: cached.type },\n      });\n      logEntries.push({ queryName, status: \"HIT\" });\n    } else {\n      const sqlWithDefaults = sql.replace(/:([a-zA-Z_]\\w*)/g, \"''\");\n      const cleanedSql = sqlWithDefaults.trim().replace(/;\\s*$/, \"\");\n      uncachedQueries.push({ index: i, queryName, sql, sqlHash, cleanedSql });\n    }\n  }\n\n  // Phase 2: Execute all uncached DESCRIBE calls in parallel\n  type DescribeResult =\n    | {\n        status: \"ok\";\n        index: number;\n        schema: QuerySchema;\n        cacheEntry: { hash: string; type: string; retry: boolean };\n      }\n    | {\n        status: \"fail\";\n        index: number;\n        schema: QuerySchema;\n        cacheEntry: { hash: string; type: string; retry: boolean };\n        error: { code?: string; message: string };\n      };\n\n  const freshResults: Array<{ index: number; schema: QuerySchema }> = [];\n\n  if (uncachedQueries.length > 0) {\n    let completed = 0;\n    const total = uncachedQueries.length;\n    spinner.start(\n      `Describing ${total} ${total === 1 ? \"query\" : \"queries\"} (0/${total})`,\n    );\n\n    const describeOne = async ({\n      index,\n      queryName,\n      sql,\n      sqlHash,\n      cleanedSql,\n    }: (typeof uncachedQueries)[number]): Promise<DescribeResult> => {\n      const result = (await client.statementExecution.executeStatement({\n        statement: `DESCRIBE QUERY ${cleanedSql}`,\n        warehouse_id: warehouseId,\n      })) as DatabricksStatementExecutionResponse;\n\n      completed++;\n      spinner.update(\n        `Describing ${total} ${total === 1 ? \"query\" : \"queries\"} (${completed}/${total})`,\n      );\n\n      logger.debug(\n        \"DESCRIBE result for %s: state=%s, rows=%d\",\n        queryName,\n        result.status.state,\n        result.result?.data_array?.length ?? 0,\n      );\n\n      if (result.status.state === \"FAILED\") {\n        const sqlError =\n          result.status.error?.message || \"Query execution failed\";\n        logger.warn(\"DESCRIBE failed for %s: %s\", queryName, sqlError);\n        const type = generateUnknownResultQuery(sql, queryName);\n        return {\n          status: \"fail\",\n          index,\n          schema: { name: queryName, type },\n          cacheEntry: { hash: sqlHash, type, retry: true },\n          error: parseError(sqlError),\n        };\n      }\n\n      const { type, hasResults } = convertToQueryType(result, sql, queryName);\n      return {\n        status: \"ok\",\n        index,\n        schema: { name: queryName, type },\n        cacheEntry: { hash: sqlHash, type, retry: !hasResults },\n      };\n    };\n\n    // Process in chunks, saving cache after each chunk\n    const processBatchResults = (\n      settled: PromiseSettledResult<DescribeResult>[],\n      batchOffset: number,\n    ) => {\n      for (let i = 0; i < settled.length; i++) {\n        const entry = settled[i];\n        const { queryName } = uncachedQueries[batchOffset + i];\n\n        if (entry.status === \"fulfilled\") {\n          const res = entry.value;\n          freshResults.push({ index: res.index, schema: res.schema });\n          cache.queries[queryName] = res.cacheEntry;\n          logEntries.push({\n            queryName,\n            status: \"MISS\",\n            failed: res.status === \"fail\",\n            error: res.status === \"fail\" ? res.error : undefined,\n          });\n        } else {\n          const { sql, sqlHash, index } = uncachedQueries[batchOffset + i];\n          const reason =\n            entry.reason instanceof Error\n              ? entry.reason.message\n              : String(entry.reason);\n          logger.warn(\"DESCRIBE rejected for %s: %s\", queryName, reason);\n          const type = generateUnknownResultQuery(sql, queryName);\n          freshResults.push({ index, schema: { name: queryName, type } });\n          cache.queries[queryName] = { hash: sqlHash, type, retry: true };\n          logEntries.push({\n            queryName,\n            status: \"MISS\",\n            failed: true,\n            error: parseError(reason),\n          });\n        }\n      }\n    };\n\n    if (uncachedQueries.length > concurrency) {\n      for (let b = 0; b < uncachedQueries.length; b += concurrency) {\n        const batch = uncachedQueries.slice(b, b + concurrency);\n        const batchResults = await Promise.allSettled(batch.map(describeOne));\n        processBatchResults(batchResults, b);\n        await saveCache(cache);\n      }\n    } else {\n      const settled = await Promise.allSettled(\n        uncachedQueries.map(describeOne),\n      );\n      processBatchResults(settled, 0);\n      await saveCache(cache);\n    }\n\n    spinner.stop(\"\");\n  }\n\n  const elapsed = ((performance.now() - startTime) / 1000).toFixed(2);\n\n  // Print formatted table\n  if (logEntries.length > 0) {\n    const maxNameLen = Math.max(...logEntries.map((e) => e.queryName.length));\n    const separator = pc.dim(\"─\".repeat(50));\n    console.log(\"\");\n    console.log(\n      `  ${pc.bold(\"Typegen Queries\")} ${pc.dim(`(${logEntries.length})`)}`,\n    );\n    console.log(`  ${separator}`);\n    for (const entry of logEntries) {\n      const tag = entry.failed\n        ? pc.bold(pc.red(\"ERROR\"))\n        : entry.status === \"HIT\"\n          ? `cache ${pc.bold(pc.green(\"HIT  \"))}`\n          : `cache ${pc.bold(pc.yellow(\"MISS \"))}`;\n      const rawName = entry.queryName.padEnd(maxNameLen);\n      const name = entry.failed ? pc.dim(pc.strikethrough(rawName)) : rawName;\n      const errorCode = entry.error?.message.match(/\\[([^\\]]+)\\]/)?.[1];\n      const reason = errorCode ? `  ${pc.dim(errorCode)}` : \"\";\n      console.log(`  ${tag}  ${name}${reason}`);\n    }\n    const newCount = logEntries.filter(\n      (e) => e.status === \"MISS\" && !e.failed,\n    ).length;\n    const cacheCount = logEntries.filter(\n      (e) => e.status === \"HIT\" && !e.failed,\n    ).length;\n    const errorCount = logEntries.filter((e) => e.failed).length;\n    console.log(`  ${separator}`);\n    const parts = [`${newCount} new`, `${cacheCount} from cache`];\n    if (errorCount > 0)\n      parts.push(`${errorCount} ${errorCount === 1 ? \"error\" : \"errors\"}`);\n    console.log(`  ${parts.join(\", \")}. ${pc.dim(`${elapsed}s`)}`);\n    console.log(\"\");\n  }\n\n  // Merge and sort by original file index for deterministic output\n  return [...cachedResults, ...freshResults]\n    .sort((a, b) => a.index - b.index)\n    .map((r) => r.schema);\n}\n\n/**\n * Normalize query name by removing the .obo extension\n * @param queryName - the query name to normalize\n * @returns the normalized query name\n */\nfunction normalizeQueryName(fileName: string): string {\n  return fileName.replace(/\\.obo$/, \"\");\n}\n\n/**\n * Normalize SQL type name by removing parameters/generics\n * Examples:\n *   DECIMAL(38,6) -> DECIMAL\n *   ARRAY<STRING> -> ARRAY\n *   MAP<STRING,INT> -> MAP\n *   STRUCT<name:STRING> -> STRUCT\n *   INTERVAL DAY TO SECOND -> INTERVAL\n *   GEOGRAPHY(4326) -> GEOGRAPHY\n */\nexport function normalizeTypeName(typeName: string): string {\n  return typeName\n    .replace(/\\(.*\\)$/, \"\") // remove (p, s) eg: DECIMAL(38,6) -> DECIMAL\n    .replace(/<.*>$/, \"\") // remove <T> eg: ARRAY<STRING> -> ARRAY\n    .split(\" \")[0]; // take first word eg: INTERVAL DAY TO SECOND -> INTERVAL\n}\n\n/** Type Map for Databricks data types to JavaScript types */\nconst typeMap: Record<string, string> = {\n  // string types\n  STRING: \"string\",\n  BINARY: \"string\",\n  // boolean\n  BOOLEAN: \"boolean\",\n  // numeric types\n  TINYINT: \"number\",\n  SMALLINT: \"number\",\n  INT: \"number\",\n  BIGINT: \"number\",\n  FLOAT: \"number\",\n  DOUBLE: \"number\",\n  DECIMAL: \"number\",\n  // date/time types\n  DATE: \"string\",\n  TIMESTAMP: \"string\",\n  TIMESTAMP_NTZ: \"string\",\n  INTERVAL: \"string\",\n  // complex types\n  ARRAY: \"unknown[]\",\n  MAP: \"Record<string, unknown>\",\n  STRUCT: \"Record<string, unknown>\",\n  OBJECT: \"Record<string, unknown>\",\n  VARIANT: \"unknown\",\n  // spatial types\n  GEOGRAPHY: \"unknown\",\n  GEOMETRY: \"unknown\",\n  // null type\n  VOID: \"null\",\n};\n"],"mappings":"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"}

package/dist/utils/path-exclusions.js.map

@@ -1 +1 @@
-{"version":3,"file":"path-exclusions.js","names":[],"sources":["../../src/utils/path-exclusions.ts"],"sourcesContent":["import type { IncomingMessage } from \"node:http\";\n\n/**\n * Paths and patterns to exclude from tracing and logging.\n * Requests matching these will not create spans or WideEvents.\n */\nexport const EXCLUDED_PATH_PREFIXES = [\n  // Vite dev server internals\n  \"/@fs/\",\n  \"/@vite/\",\n  \"/@id/\",\n  \"/@react-refresh\",\n  \"/src/\", // Vite HMR source files\n  \"/node_modules/\",\n\n  // Static assets and common paths\n  \"/favicon.ico\",\n  \"/_next/\",\n  \"/static/\",\n\n  // Health checks\n  \"/health\",\n  \"/metrics\",\n];\n\n/**\n * File extensions to exclude from tracing.\n * These are typically static assets that don't need tracing.\n */\nexport const EXCLUDED_EXTENSIONS = [\n  \".svg\",\n  \".png\",\n  \".jpg\",\n  \".jpeg\",\n  \".gif\",\n  \".webp\",\n  \".ico\",\n  \".css\",\n  \".woff\",\n  \".woff2\",\n  \".ttf\",\n  \".eot\",\n  \".map\", // Source maps\n  \".js\", // Static JS files (not API endpoints)\n];\n\n/**\n * Check if a request should be ignored for tracing.\n * This is the primary filter used by HttpInstrumentation.\n */\nexport function shouldIgnoreRequest(request: IncomingMessage): boolean {\n  const url = request.url;\n  if (!url) return false;\n\n  // Remove query string for path matching\n  const path = url.split(\"?\")[0];\n\n  return shouldExcludePath(path);\n}\n\n/**\n * Check if a path should be excluded from tracing/logging.\n * Returns true if path should be excluded, false otherwise.\n */\nexport function shouldExcludePath(path: string | undefined): boolean {\n  if (typeof path !== \"string\") return false;\n\n  // Remove query string\n  const cleanPath = path.split(\"?\")[0];\n  const lowerPath = cleanPath.toLowerCase();\n\n  // Check path prefixes\n  for (const prefix of EXCLUDED_PATH_PREFIXES) {\n    if (cleanPath.includes(prefix)) {\n      return true;\n    }\n  }\n\n  // Check file extensions (but not for /api/ routes)\n  if (!cleanPath.startsWith(\"/api/\")) {\n    for (const ext of EXCLUDED_EXTENSIONS) {\n      if (lowerPath.endsWith(ext)) {\n        return true;\n      }\n    }\n  }\n\n  return false;\n}\n"],"mappings":";;;;;AAMA,MAAa,yBAAyB;CAEpC;CACA;CACA;CACA;CACA;CACA;CAGA;CACA;CACA;CAGA;CACA;CACD;;;;;AAMD,MAAa,sBAAsB;CACjC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;AAMD,SAAgB,oBAAoB,SAAmC;CACrE,MAAM,MAAM,QAAQ;AACpB,KAAI,CAAC,IAAK,QAAO;CAGjB,MAAM,OAAO,IAAI,MAAM,IAAI,CAAC;AAE5B,QAAO,kBAAkB,KAAK;;;;;;AAOhC,SAAgB,kBAAkB,MAAmC;AACnE,KAAI,OAAO,SAAS,SAAU,QAAO;CAGrC,MAAM,YAAY,KAAK,MAAM,IAAI,CAAC;CAClC,MAAM,YAAY,UAAU,aAAa;AAGzC,MAAK,MAAM,UAAU,uBACnB,KAAI,UAAU,SAAS,OAAO,CAC5B,QAAO;AAKX,KAAI,CAAC,UAAU,WAAW,QAAQ,EAChC;OAAK,MAAM,OAAO,oBAChB,KAAI,UAAU,SAAS,IAAI,CACzB,QAAO;;AAKb,QAAO"}
+{"version":3,"file":"path-exclusions.js","names":[],"sources":["../../src/utils/path-exclusions.ts"],"sourcesContent":["import type { IncomingMessage } from \"node:http\";\n\n/**\n * Paths and patterns to exclude from tracing and logging.\n * Requests matching these will not create spans or WideEvents.\n */\nconst EXCLUDED_PATH_PREFIXES = [\n  // Vite dev server internals\n  \"/@fs/\",\n  \"/@vite/\",\n  \"/@id/\",\n  \"/@react-refresh\",\n  \"/src/\", // Vite HMR source files\n  \"/node_modules/\",\n\n  // Static assets and common paths\n  \"/favicon.ico\",\n  \"/_next/\",\n  \"/static/\",\n\n  // Health checks\n  \"/health\",\n  \"/metrics\",\n];\n\n/**\n * File extensions to exclude from tracing.\n * These are typically static assets that don't need tracing.\n */\nconst EXCLUDED_EXTENSIONS = [\n  \".svg\",\n  \".png\",\n  \".jpg\",\n  \".jpeg\",\n  \".gif\",\n  \".webp\",\n  \".ico\",\n  \".css\",\n  \".woff\",\n  \".woff2\",\n  \".ttf\",\n  \".eot\",\n  \".map\", // Source maps\n  \".js\", // Static JS files (not API endpoints)\n];\n\n/**\n * Check if a request should be ignored for tracing.\n * This is the primary filter used by HttpInstrumentation.\n */\nexport function shouldIgnoreRequest(request: IncomingMessage): boolean {\n  const url = request.url;\n  if (!url) return false;\n\n  // Remove query string for path matching\n  const path = url.split(\"?\")[0];\n\n  return shouldExcludePath(path);\n}\n\n/**\n * Check if a path should be excluded from tracing/logging.\n * Returns true if path should be excluded, false otherwise.\n */\nexport function shouldExcludePath(path: string | undefined): boolean {\n  if (typeof path !== \"string\") return false;\n\n  // Remove query string\n  const cleanPath = path.split(\"?\")[0];\n  const lowerPath = cleanPath.toLowerCase();\n\n  // Check path prefixes\n  for (const prefix of EXCLUDED_PATH_PREFIXES) {\n    if (cleanPath.includes(prefix)) {\n      return true;\n    }\n  }\n\n  // Check file extensions (but not for /api/ routes)\n  if (!cleanPath.startsWith(\"/api/\")) {\n    for (const ext of EXCLUDED_EXTENSIONS) {\n      if (lowerPath.endsWith(ext)) {\n        return true;\n      }\n    }\n  }\n\n  return false;\n}\n"],"mappings":";;;;;AAMA,MAAM,yBAAyB;CAE7B;CACA;CACA;CACA;CACA;CACA;CAGA;CACA;CACA;CAGA;CACA;CACD;;;;;AAMD,MAAM,sBAAsB;CAC1B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;AAMD,SAAgB,oBAAoB,SAAmC;CACrE,MAAM,MAAM,QAAQ;AACpB,KAAI,CAAC,IAAK,QAAO;CAGjB,MAAM,OAAO,IAAI,MAAM,IAAI,CAAC;AAE5B,QAAO,kBAAkB,KAAK;;;;;;AAOhC,SAAgB,kBAAkB,MAAmC;AACnE,KAAI,OAAO,SAAS,SAAU,QAAO;CAGrC,MAAM,YAAY,KAAK,MAAM,IAAI,CAAC;CAClC,MAAM,YAAY,UAAU,aAAa;AAGzC,MAAK,MAAM,UAAU,uBACnB,KAAI,UAAU,SAAS,OAAO,CAC5B,QAAO;AAKX,KAAI,CAAC,UAAU,WAAW,QAAQ,EAChC;OAAK,MAAM,OAAO,oBAChB,KAAI,UAAU,SAAS,IAAI,CACzB,QAAO;;AAKb,QAAO"}

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

@@ -1,6 +1,6 @@
 # Interface: CacheConfig
 
-Configuration for caching
+Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup.
 
 ## Indexable[​](#indexable "Direct link to Indexable")
 

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

@@ -1,6 +1,15 @@
 # Interface: PluginManifest\<TName>
 
-Plugin manifest that declares metadata and resource requirements. Attached to plugin classes as a static property.
+Plugin manifest that declares metadata and resource requirements. Attached to plugin classes as a static property. Extends the shared PluginManifest with strict resource types.
+
+## See[​](#see "Direct link to See")
+
+* `packages/shared/src/schemas/plugin-manifest.generated.ts` `PluginManifest` — generated base
+* SharedPluginManifest — shared re-export with JSONSchema7 config
+
+## Extends[​](#extends "Direct link to Extends")
+
+* `Omit`<`SharedPluginManifest`, `"resources"` | `"config"`>
 
 ## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
 
@@ -17,7 +26,14 @@ optional author: string;
 
 ```
 
-Optional metadata for community plugins
+Author name or organization
+
+#### Inherited from[​](#inherited-from "Direct link to Inherited from")
+
+```ts
+Omit.author
+
+```
 
 ***
 
@@ -30,7 +46,7 @@ optional config: {
 
 ```
 
-Configuration schema for the plugin. Defines the shape and validation rules for plugin config.
+Configuration schema for the plugin. Uses JSONSchema7 instead of the generated ConfigSchema (which is too restrictive).
 
 #### schema[​](#schema "Direct link to schema")
 
@@ -50,6 +66,13 @@ description: string;
 
 Brief description of what the plugin does
 
+#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")
+
+```ts
+Omit.description
+
+```
+
 ***
 
 ### displayName[​](#displayname "Direct link to displayName")
@@ -59,7 +82,14 @@ displayName: string;
 
 ```
 
-Human-readable display name for UI/CLI
+Human-readable display name for UI and CLI
+
+#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")
+
+```ts
+Omit.displayName
+
+```
 
 ***
 
@@ -70,7 +100,14 @@ optional hidden: boolean;
 
 ```
 
-When true, excluded from the template plugins manifest during sync.
+When true, this plugin is excluded from the template plugins manifest (appkit.plugins.json) during sync.
+
+#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")
+
+```ts
+Omit.hidden
+
+```
 
 ***
 
@@ -81,6 +118,15 @@ optional keywords: string[];
 
 ```
 
+Keywords for plugin discovery
+
+#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")
+
+```ts
+Omit.keywords
+
+```
+
 ***
 
 ### license?[​](#license "Direct link to license?")
@@ -90,6 +136,15 @@ optional license: string;
 
 ```
 
+SPDX license identifier
+
+#### Inherited from[​](#inherited-from-5 "Direct link to Inherited from")
+
+```ts
+Omit.license
+
+```
+
 ***
 
 ### name[​](#name "Direct link to name")
@@ -101,6 +156,31 @@ name: TName;
 
 Plugin identifier — the single source of truth for the plugin's name
 
+#### Overrides[​](#overrides "Direct link to Overrides")
+
+```ts
+Omit.name
+
+```
+
+***
+
+### onSetupMessage?[​](#onsetupmessage "Direct link to onSetupMessage?")
+
+```ts
+optional onSetupMessage: string;
+
+```
+
+Message displayed to the user after project initialization. Use this to inform about manual setup steps (e.g. environment variables, resource provisioning).
+
+#### Inherited from[​](#inherited-from-6 "Direct link to Inherited from")
+
+```ts
+Omit.onSetupMessage
+
+```
+
 ***
 
 ### repository?[​](#repository "Direct link to repository?")
@@ -110,6 +190,15 @@ optional repository: string;
 
 ```
 
+URL to the plugin's source repository
+
+#### Inherited from[​](#inherited-from-7 "Direct link to Inherited from")
+
+```ts
+Omit.repository
+
+```
+
 ***
 
 ### resources[​](#resources "Direct link to resources")
@@ -122,7 +211,7 @@ resources: {
 
 ```
 
-Resource requirements declaration
+Resource requirements declaration (with strict ResourceRequirement types)
 
 #### optional[​](#optional "Direct link to optional")
 
@@ -150,3 +239,12 @@ Resources that must be available for the plugin to function
 optional version: string;
 
 ```
+
+Plugin version (semver format)
+
+#### Inherited from[​](#inherited-from-8 "Direct link to Inherited from")
+
+```ts
+Omit.version
+
+```

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

@@ -15,7 +15,7 @@ alias: string;
 
 ```
 
-Unique alias for this resource within the plugin (e.g., 'warehouse', 'secrets'). Used for UI/display.
+Human-readable label for UI/display only. Deduplication uses resourceKey, not alias.
 
 #### Inherited from[​](#inherited-from "Direct link to Inherited from")
 
@@ -45,7 +45,7 @@ fields: Record<string, ResourceFieldEntry>;
 
 ```
 
-Map of field name to env and optional description. Single-value types use one key (e.g. id); multi-value (database, secret) use multiple keys.
+Map of field name to env and optional description. Single-value types use one key (e.g. id); multi-value (database, secret) use multiple (e.g. instance\_name, database\_name or scope, key).
 
 #### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")
 
@@ -60,7 +60,7 @@ permission: ResourcePermission;
 
 ```
 
-Required permission level for the resource
+Required permission level for the resource (narrowed to union)
 
 #### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")
 
@@ -97,8 +97,6 @@ required: boolean;
 
 ```
 
-Whether this resource is required (true) or optional (false)
-
 #### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")
 
 [`ResourceRequirement`](./docs/api/appkit/Interface.ResourceRequirement.md).[`required`](./docs/api/appkit/Interface.ResourceRequirement.md#required)
@@ -123,7 +121,7 @@ resourceKey: string;
 
 ```
 
-Stable key for machine use (env naming, composite keys, app.yaml). Required.
+Stable key for machine use: deduplication, env naming, composite keys, app.yaml. Required for registry lookup.
 
 #### Inherited from[​](#inherited-from-5 "Direct link to Inherited from")
 
@@ -138,7 +136,7 @@ type: ResourceType;
 
 ```
 
-Type of Databricks resource required
+Type of Databricks resource required (narrowed to enum)
 
 #### Inherited from[​](#inherited-from-6 "Direct link to Inherited from")
 

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

@@ -2,6 +2,8 @@
 
 Defines a single field for a resource. Each field has its own environment variable and optional description. Single-value types use one key (e.g. id); multi-value types (database, secret) use multiple (e.g. instance\_name, database\_name or scope, key).
 
+This interface was referenced by `PluginManifest`'s JSON-Schema via the `definition` "resourceFieldEntry".
+
 ## Properties[​](#properties "Direct link to Properties")
 
 ### bundleIgnore?[​](#bundleignore "Direct link to bundleIgnore?")

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

@@ -1,6 +1,15 @@
 # Interface: ResourceRequirement
 
-Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements().
+Declares a resource requirement for a plugin. Can be defined statically in a manifest or dynamically via getResourceRequirements(). Narrows the generated base: type → ResourceType enum, permission → ResourcePermission union.
+
+## See[​](#see "Direct link to See")
+
+* `packages/shared/src/schemas/plugin-manifest.generated.ts` `ResourceRequirement` — generated base
+* SharedResourceRequirement — shared re-export with runtime `fields` and `required`
+
+## Extends[​](#extends "Direct link to Extends")
+
+* `ResourceRequirement`
 
 ## Extended by[​](#extended-by "Direct link to Extended by")
 
@@ -15,7 +24,14 @@ alias: string;
 
 ```
 
-Unique alias for this resource within the plugin (e.g., 'warehouse', 'secrets'). Used for UI/display.
+Human-readable label for UI/display only. Deduplication uses resourceKey, not alias.
+
+#### Inherited from[​](#inherited-from "Direct link to Inherited from")
+
+```ts
+SharedResourceRequirement.alias
+
+```
 
 ***
 
@@ -28,6 +44,13 @@ description: string;
 
 Human-readable description of why this resource is needed
 
+#### Inherited from[​](#inherited-from-1 "Direct link to Inherited from")
+
+```ts
+SharedResourceRequirement.description
+
+```
+
 ***
 
 ### fields[​](#fields "Direct link to fields")
@@ -37,7 +60,14 @@ fields: Record<string, ResourceFieldEntry>;
 
 ```
 
-Map of field name to env and optional description. Single-value types use one key (e.g. id); multi-value (database, secret) use multiple keys.
+Map of field name to env and optional description. Single-value types use one key (e.g. id); multi-value (database, secret) use multiple (e.g. instance\_name, database\_name or scope, key).
+
+#### Inherited from[​](#inherited-from-2 "Direct link to Inherited from")
+
+```ts
+SharedResourceRequirement.fields
+
+```
 
 ***
 
@@ -48,7 +78,14 @@ permission: ResourcePermission;
 
 ```
 
-Required permission level for the resource
+Required permission level for the resource (narrowed to union)
+
+#### Overrides[​](#overrides "Direct link to Overrides")
+
+```ts
+SharedResourceRequirement.permission
+
+```
 
 ***
 
@@ -59,7 +96,12 @@ required: boolean;
 
 ```
 
-Whether this resource is required (true) or optional (false)
+#### Inherited from[​](#inherited-from-3 "Direct link to Inherited from")
+
+```ts
+SharedResourceRequirement.required
+
+```
 
 ***
 
@@ -70,7 +112,14 @@ resourceKey: string;
 
 ```
 
-Stable key for machine use (env naming, composite keys, app.yaml). Required.
+Stable key for machine use: deduplication, env naming, composite keys, app.yaml. Required for registry lookup.
+
+#### Inherited from[​](#inherited-from-4 "Direct link to Inherited from")
+
+```ts
+SharedResourceRequirement.resourceKey
+
+```
 
 ***
 
@@ -81,4 +130,11 @@ type: ResourceType;
 
 ```
 
-Type of Databricks resource required
+Type of Databricks resource required (narrowed to enum)
+
+#### Overrides[​](#overrides-1 "Direct link to Overrides")
+
+```ts
+SharedResourceRequirement.type
+
+```

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

@@ -1,6 +1,6 @@
 # Interface: StreamExecutionSettings
 
-Configuration for streaming execution with default and user-scoped settings
+Execution settings for streaming endpoints. Extends PluginExecutionSettings with SSE stream configuration.
 
 ## Properties[​](#properties "Direct link to Properties")
 

package/docs/api/appkit/TypeAlias.PluginData.md

@@ -9,6 +9,8 @@ type PluginData<T, U, N> = {
 
 ```
 
+Tuple of plugin class, config, and name. Created by `toPlugin()` and passed to `createApp()`.
+
 ## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
 
 | Type Parameter |

package/docs/api/appkit/TypeAlias.ToPlugin.md

@@ -5,6 +5,8 @@ type ToPlugin<T, U, N> = (config?: U) => PluginData<T, U, N>;
 
 ```
 
+Factory function type returned by `toPlugin()`. Accepts optional config and returns a PluginData tuple.
+
 ## Type Parameters[​](#type-parameters "Direct link to Type Parameters")
 
 | Type Parameter         |