@databricks/appkit 0.46.0 → 0.47.0

package/dist/app/index.d.ts

@@ -12,9 +12,23 @@ interface QueryResult {
   isAsUser: boolean;
 }
 declare class AppManager {
-  private readonly queriesDir;
+  private readonly _queriesDir;
+  private readonly _metricViewsDir;
+  constructor(queriesDir?: string, metricViewsDir?: string);
+  get queriesDir(): string;
+  get metricViewsDir(): string;
   /**
-   * Validates that a file path is within the queries directory
+   * Whether `req` is a dev-tunnel (`?dev`) request. Internal `?dev` predicate
+   * shared by {@link createFsAdapter} (tunnel-vs-`fs` branch) and
+   * {@link isNotFoundError} (dev's message-match not-found classification).
+   */
+  private isDevRequest;
+  /**
+   * Validates that a file path is within the given base directory. The
+   * `baseDir` is passed explicitly (rather than pinned to `queriesDir`) so the
+   * same traversal guard protects reads from any config directory —
+   * `config/queries/` for `.sql` files and `config/metric-views/` for the
+   * metric-view definitions.
    */
   private validatePath;
   /**
@@ -30,6 +44,39 @@ declare class AppManager {
    * @returns The query content and execution mode (as user or as service principal)
    */
   getAppQuery(queryKey: string, req?: RequestLike, devFileReader?: DevFileReader): Promise<QueryResult | null>;
+  /**
+   * Read a single config file from a given base directory, dev-tunnel-aware.
+   * Shared core behind {@link readConfigFile} (queries dir) and
+   * {@link readMetricViewsConfig} (metric-views dir).
+   *
+   * @param baseDir - The config directory the file must resolve within.
+   * @param fileName - File name (or relative path) within `baseDir`.
+   * @param req - Optional request object to detect dev mode.
+   * @param devFileReader - Optional DevFileReader to read via the WebSocket tunnel.
+   * @returns The raw file contents, or `null` when the file is absent / the path is rejected.
+   */
+  private readFileFromDir;
+  /**
+   * Read a single config file from the queries directory, dev-tunnel-aware.
+   *
+   * @param fileName - File name (or relative path) within the queries directory.
+   * @param req - Optional request object to detect dev mode.
+   * @param devFileReader - Optional DevFileReader to read via the WebSocket tunnel.
+   * @returns The raw file contents, or `null` when the file is absent / the path is rejected.
+   */
+  readConfigFile(fileName: string, req?: RequestLike, devFileReader?: DevFileReader): Promise<string | null>;
+  /**
+   * Read a single config file from the metric-views directory
+   * (`config/metric-views/`), dev-tunnel-aware. Same absent-file/traversal
+   * semantics as {@link readConfigFile}, but rooted at {@link metricViewsDir}.
+   *
+   * @param fileName - File name (or relative path) within the metric-views directory.
+   * @param req - Optional request object to detect dev mode.
+   * @param devFileReader - Optional DevFileReader to read via the WebSocket tunnel.
+   * @returns The raw file contents, or `null` when the file is absent / the path is rejected.
+   */
+  readMetricViewsConfig(fileName: string, req?: RequestLike, devFileReader?: DevFileReader): Promise<string | null>;
+  private isNotFoundError;
 }
 //#endregion
 export { AppManager };

package/dist/app/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/app/index.ts"],"mappings":";UAMU,WAAA;EACR,KAAA,GAAQ,MAAA;EACR,OAAA,EAAS,MAAA;AAAA;AAAA,UAGD,aAAA;EACR,QAAA,CAAS,QAAA,UAAkB,GAAA,EAAK,WAAA,GAAc,OAAA;EAC9C,OAAA,CAAQ,OAAA,UAAiB,GAAA,EAAK,WAAA,GAAc,OAAA;AAAA;AAAA,UAGpC,WAAA;EACR,KAAA;EACA,QAAA;AAAA;AAAA,cAWW,UAAA;EAAA,iBACM,UAAA;EAlBe;;;EAAA,QAuBxB,YAAA;EAtB2C;;;EAAA,QAsC3C,eAAA;EAvCwB;;;;;;;;EA0E1B,WAAA,CACJ,QAAA,UACA,GAAA,GAAM,WAAA,EACN,aAAA,GAAgB,aAAA,GACf,OAAA,CAAQ,WAAA;AAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/app/index.ts"],"mappings":";UAMU,WAAA;EACR,KAAA,GAAQ,MAAA;EACR,OAAA,EAAS,MAAA;AAAA;AAAA,UAGD,aAAA;EACR,QAAA,CAAS,QAAA,UAAkB,GAAA,EAAK,WAAA,GAAc,OAAA;EAC9C,OAAA,CAAQ,OAAA,UAAiB,GAAA,EAAK,WAAA,GAAc,OAAA;AAAA;AAAA,UAGpC,WAAA;EACR,KAAA;EACA,QAAA;AAAA;AAAA,cAWW,UAAA;EAAA,iBACM,WAAA;EAAA,iBACA,eAAA;cAGf,UAAA,WAMA,cAAA;EAAA,IASE,UAAA,CAAA;EAAA,IAIA,cAAA,CAAA;EAxC+C;;;;;EAAA,QAiD3C,YAAA;EAlDsC;;;;;;;EAAA,QA6DtC,YAAA;EAzDA;;;EAAA,QAyEA,eAAA;EAvEA;AAWV;;;;;;;EA+FQ,WAAA,CACJ,QAAA,UACA,GAAA,GAAM,WAAA,EACN,aAAA,GAAgB,aAAA,GACf,OAAA,CAAQ,WAAA;EAoHO;;;;;;;;;;;EAAA,QArCJ,eAAA;EA9JV;;;;;;;;EAgME,cAAA,CACJ,QAAA,UACA,GAAA,GAAM,WAAA,EACN,aAAA,GAAgB,aAAA,GACf,OAAA;EAtHe;;;;;;;;;;EAoIZ,qBAAA,CACJ,QAAA,UACA,GAAA,GAAM,WAAA,EACN,aAAA,GAAgB,aAAA,GACf,OAAA;EAAA,QASK,eAAA;AAAA"}

package/dist/app/index.js

@@ -5,16 +5,39 @@ import path from "node:path";
 //#region src/app/index.ts
 const logger = createLogger("app");
 var AppManager = class {
-	queriesDir = path.resolve(process.cwd(), "config/queries");
+	_queriesDir;
+	_metricViewsDir;
+	constructor(queriesDir = path.resolve(process.cwd(), "config/queries"), metricViewsDir = path.resolve(path.dirname(queriesDir), "metric-views")) {
+		this._queriesDir = queriesDir;
+		this._metricViewsDir = metricViewsDir;
+	}
+	get queriesDir() {
+		return this._queriesDir;
+	}
+	get metricViewsDir() {
+		return this._metricViewsDir;
+	}
+	/**
+	* Whether `req` is a dev-tunnel (`?dev`) request. Internal `?dev` predicate
+	* shared by {@link createFsAdapter} (tunnel-vs-`fs` branch) and
+	* {@link isNotFoundError} (dev's message-match not-found classification).
+	*/
+	isDevRequest(req) {
+		return req?.query?.dev !== void 0;
+	}
 	/**
-	* Validates that a file path is within the queries directory
+	* Validates that a file path is within the given base directory. The
+	* `baseDir` is passed explicitly (rather than pinned to `queriesDir`) so the
+	* same traversal guard protects reads from any config directory —
+	* `config/queries/` for `.sql` files and `config/metric-views/` for the
+	* metric-view definitions.
 	*/
-	validatePath(fileName) {
-		const queryFilePath = path.join(this.queriesDir, fileName);
-		const resolvedPath = path.resolve(queryFilePath);
-		const resolvedQueriesDir = path.resolve(this.queriesDir);
-		if (!resolvedPath.startsWith(resolvedQueriesDir)) {
-			logger.error("Invalid query path: path traversal detected");
+	validatePath(fileName, baseDir) {
+		const filePath = path.join(baseDir, fileName);
+		const resolvedPath = path.resolve(filePath);
+		const resolvedBaseDir = path.resolve(baseDir);
+		if (!resolvedPath.startsWith(resolvedBaseDir)) {
+			logger.error("Invalid config path: path traversal detected");
 			return null;
 		}
 		return resolvedPath;
@@ -23,7 +46,7 @@ var AppManager = class {
 	* Creates a filesystem adapter based on dev mode or production mode
 	*/
 	createFsAdapter(req, devFileReader) {
-		if (req?.query?.dev !== void 0 && devFileReader && req) return {
+		if (this.isDevRequest(req) && devFileReader && req) return {
 			readdir: async (dirPath) => {
 				const relativePath = path.relative(process.cwd(), dirPath);
 				return devFileReader.readdir(relativePath, req);
@@ -75,7 +98,7 @@ var AppManager = class {
 			logger.error(`Query file not found: ${queryKey}`);
 			return null;
 		}
-		const resolvedPath = this.validatePath(queryFileName);
+		const resolvedPath = this.validatePath(queryFileName, this._queriesDir);
 		if (!resolvedPath) return null;
 		try {
 			return {
@@ -87,6 +110,60 @@ var AppManager = class {
 			return null;
 		}
 	}
+	/**
+	* Read a single config file from a given base directory, dev-tunnel-aware.
+	* Shared core behind {@link readConfigFile} (queries dir) and
+	* {@link readMetricViewsConfig} (metric-views dir).
+	*
+	* @param baseDir - The config directory the file must resolve within.
+	* @param fileName - File name (or relative path) within `baseDir`.
+	* @param req - Optional request object to detect dev mode.
+	* @param devFileReader - Optional DevFileReader to read via the WebSocket tunnel.
+	* @returns The raw file contents, or `null` when the file is absent / the path is rejected.
+	*/
+	async readFileFromDir(baseDir, fileName, req, devFileReader) {
+		const resolvedPath = this.validatePath(fileName, baseDir);
+		if (!resolvedPath) return null;
+		const fsAdapter = this.createFsAdapter(req, devFileReader);
+		try {
+			return await fsAdapter.readFile(resolvedPath);
+		} catch (error) {
+			if (this.isNotFoundError(error, req)) return null;
+			throw error;
+		}
+	}
+	/**
+	* Read a single config file from the queries directory, dev-tunnel-aware.
+	*
+	* @param fileName - File name (or relative path) within the queries directory.
+	* @param req - Optional request object to detect dev mode.
+	* @param devFileReader - Optional DevFileReader to read via the WebSocket tunnel.
+	* @returns The raw file contents, or `null` when the file is absent / the path is rejected.
+	*/
+	async readConfigFile(fileName, req, devFileReader) {
+		return this.readFileFromDir(this._queriesDir, fileName, req, devFileReader);
+	}
+	/**
+	* Read a single config file from the metric-views directory
+	* (`config/metric-views/`), dev-tunnel-aware. Same absent-file/traversal
+	* semantics as {@link readConfigFile}, but rooted at {@link metricViewsDir}.
+	*
+	* @param fileName - File name (or relative path) within the metric-views directory.
+	* @param req - Optional request object to detect dev mode.
+	* @param devFileReader - Optional DevFileReader to read via the WebSocket tunnel.
+	* @returns The raw file contents, or `null` when the file is absent / the path is rejected.
+	*/
+	async readMetricViewsConfig(fileName, req, devFileReader) {
+		return this.readFileFromDir(this._metricViewsDir, fileName, req, devFileReader);
+	}
+	isNotFoundError(error, req) {
+		if (error?.code === "ENOENT") return true;
+		if (this.isDevRequest(req)) {
+			const message = error?.message ?? "";
+			return /ENOENT|no such file/i.test(message);
+		}
+		return false;
+	}
 };
 
 //#endregion

package/dist/app/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/app/index.ts"],"sourcesContent":["import fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { createLogger } from \"../logging/logger\";\n\nconst logger = createLogger(\"app\");\n\ninterface RequestLike {\n  query?: Record<string, any>;\n  headers: Record<string, string | string[] | undefined>;\n}\n\ninterface DevFileReader {\n  readFile(filePath: string, req: RequestLike): Promise<string>;\n  readdir(dirPath: string, req: RequestLike): Promise<string[]>;\n}\n\ninterface QueryResult {\n  query: string;\n  isAsUser: boolean;\n}\n\n/**\n * Abstraction for filesystem operations that works in both dev and production modes\n */\ninterface FileSystemAdapter {\n  readdir(dirPath: string): Promise<string[]>;\n  readFile(filePath: string): Promise<string>;\n}\n\nexport class AppManager {\n  private readonly queriesDir = path.resolve(process.cwd(), \"config/queries\");\n\n  /**\n   * Validates that a file path is within the queries directory\n   */\n  private validatePath(fileName: string): string | null {\n    const queryFilePath = path.join(this.queriesDir, fileName);\n    const resolvedPath = path.resolve(queryFilePath);\n    const resolvedQueriesDir = path.resolve(this.queriesDir);\n\n    if (!resolvedPath.startsWith(resolvedQueriesDir)) {\n      logger.error(\"Invalid query path: path traversal detected\");\n      return null;\n    }\n\n    return resolvedPath;\n  }\n\n  /**\n   * Creates a filesystem adapter based on dev mode or production mode\n   */\n  private createFsAdapter(\n    req?: RequestLike,\n    devFileReader?: DevFileReader,\n  ): FileSystemAdapter {\n    const isDevMode = req?.query?.dev !== undefined;\n\n    if (isDevMode && devFileReader && req) {\n      // Dev mode: use WebSocket tunnel to read from local filesystem\n      return {\n        readdir: async (dirPath: string) => {\n          const relativePath = path.relative(process.cwd(), dirPath);\n          return devFileReader.readdir(relativePath, req);\n        },\n        readFile: async (filePath: string) => {\n          const relativePath = path.relative(process.cwd(), filePath);\n          return devFileReader.readFile(relativePath, req);\n        },\n      };\n    }\n\n    // Production mode: use server filesystem\n    return {\n      readdir: (dirPath: string) => fs.readdir(dirPath),\n      readFile: (filePath: string) => fs.readFile(filePath, \"utf8\"),\n    };\n  }\n\n  /**\n   * Retrieves a query file by key from the queries directory\n   * In dev mode with a request context, reads from local filesystem via WebSocket\n   * @param queryKey - The query file name (without extension)\n   * @param req - Optional request object to detect dev mode\n   * @param devFileReader - Optional DevFileReader instance to read files from local filesystem\n   * @returns The query content and execution mode (as user or as service principal)\n   */\n  async getAppQuery(\n    queryKey: string,\n    req?: RequestLike,\n    devFileReader?: DevFileReader,\n  ): Promise<QueryResult | null> {\n    // Security: Sanitize query key to prevent path traversal\n    if (!queryKey || !/^[a-zA-Z0-9_-]+$/.test(queryKey)) {\n      logger.error(\n        \"Invalid query key format: %s. Only alphanumeric characters, underscores, and hyphens are allowed.\",\n        queryKey,\n      );\n      return null;\n    }\n\n    // Create filesystem adapter for dev or production mode\n    const fsAdapter = this.createFsAdapter(req, devFileReader);\n\n    // Priority order: .obo.sql first (as user), then .sql (as service principal)\n    const oboFileName = `${queryKey}.obo.sql`;\n    const defaultFileName = `${queryKey}.sql`;\n\n    // List directory to find which query file exists\n    let files: string[];\n    try {\n      files = await fsAdapter.readdir(this.queriesDir);\n    } catch (error) {\n      logger.error(\n        `Failed to read queries directory: ${(error as Error).message}`,\n      );\n      return null;\n    }\n\n    // Determine which query file to use\n    let queryFileName: string | null = null;\n    let isAsUser = false;\n\n    if (files.includes(oboFileName)) {\n      queryFileName = oboFileName;\n      isAsUser = true;\n\n      // Warn if both variants exist\n      if (files.includes(defaultFileName)) {\n        logger.warn(\n          `Both ${oboFileName} and ${defaultFileName} found for query ${queryKey}. Using ${oboFileName}.`,\n        );\n      }\n    } else if (files.includes(defaultFileName)) {\n      queryFileName = defaultFileName;\n      isAsUser = false;\n    }\n\n    if (!queryFileName) {\n      logger.error(`Query file not found: ${queryKey}`);\n      return null;\n    }\n\n    // Validate and resolve the file path\n    const resolvedPath = this.validatePath(queryFileName);\n    if (!resolvedPath) {\n      return null;\n    }\n\n    // Read the query file\n    try {\n      const query = await fsAdapter.readFile(resolvedPath);\n      return { query, isAsUser };\n    } catch (error) {\n      logger.error(`Failed to read query file: ${(error as Error).message}`);\n      return null;\n    }\n  }\n}\n\nexport type { DevFileReader };\n"],"mappings":";;;;;AAIA,MAAM,SAAS,aAAa,MAAM;AAyBlC,IAAa,aAAb,MAAwB;CACtB,AAAiB,aAAa,KAAK,QAAQ,QAAQ,KAAK,EAAE,iBAAiB;;;;CAK3E,AAAQ,aAAa,UAAiC;EACpD,MAAM,gBAAgB,KAAK,KAAK,KAAK,YAAY,SAAS;EAC1D,MAAM,eAAe,KAAK,QAAQ,cAAc;EAChD,MAAM,qBAAqB,KAAK,QAAQ,KAAK,WAAW;AAExD,MAAI,CAAC,aAAa,WAAW,mBAAmB,EAAE;AAChD,UAAO,MAAM,8CAA8C;AAC3D,UAAO;;AAGT,SAAO;;;;;CAMT,AAAQ,gBACN,KACA,eACmB;AAGnB,MAFkB,KAAK,OAAO,QAAQ,UAErB,iBAAiB,IAEhC,QAAO;GACL,SAAS,OAAO,YAAoB;IAClC,MAAM,eAAe,KAAK,SAAS,QAAQ,KAAK,EAAE,QAAQ;AAC1D,WAAO,cAAc,QAAQ,cAAc,IAAI;;GAEjD,UAAU,OAAO,aAAqB;IACpC,MAAM,eAAe,KAAK,SAAS,QAAQ,KAAK,EAAE,SAAS;AAC3D,WAAO,cAAc,SAAS,cAAc,IAAI;;GAEnD;AAIH,SAAO;GACL,UAAU,YAAoB,GAAG,QAAQ,QAAQ;GACjD,WAAW,aAAqB,GAAG,SAAS,UAAU,OAAO;GAC9D;;;;;;;;;;CAWH,MAAM,YACJ,UACA,KACA,eAC6B;AAE7B,MAAI,CAAC,YAAY,CAAC,mBAAmB,KAAK,SAAS,EAAE;AACnD,UAAO,MACL,qGACA,SACD;AACD,UAAO;;EAIT,MAAM,YAAY,KAAK,gBAAgB,KAAK,cAAc;EAG1D,MAAM,cAAc,GAAG,SAAS;EAChC,MAAM,kBAAkB,GAAG,SAAS;EAGpC,IAAI;AACJ,MAAI;AACF,WAAQ,MAAM,UAAU,QAAQ,KAAK,WAAW;WACzC,OAAO;AACd,UAAO,MACL,qCAAsC,MAAgB,UACvD;AACD,UAAO;;EAIT,IAAI,gBAA+B;EACnC,IAAI,WAAW;AAEf,MAAI,MAAM,SAAS,YAAY,EAAE;AAC/B,mBAAgB;AAChB,cAAW;AAGX,OAAI,MAAM,SAAS,gBAAgB,CACjC,QAAO,KACL,QAAQ,YAAY,OAAO,gBAAgB,mBAAmB,SAAS,UAAU,YAAY,GAC9F;aAEM,MAAM,SAAS,gBAAgB,EAAE;AAC1C,mBAAgB;AAChB,cAAW;;AAGb,MAAI,CAAC,eAAe;AAClB,UAAO,MAAM,yBAAyB,WAAW;AACjD,UAAO;;EAIT,MAAM,eAAe,KAAK,aAAa,cAAc;AACrD,MAAI,CAAC,aACH,QAAO;AAIT,MAAI;AAEF,UAAO;IAAE,OADK,MAAM,UAAU,SAAS,aAAa;IACpC;IAAU;WACnB,OAAO;AACd,UAAO,MAAM,8BAA+B,MAAgB,UAAU;AACtE,UAAO"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/app/index.ts"],"sourcesContent":["import fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { createLogger } from \"../logging/logger\";\n\nconst logger = createLogger(\"app\");\n\ninterface RequestLike {\n  query?: Record<string, any>;\n  headers: Record<string, string | string[] | undefined>;\n}\n\ninterface DevFileReader {\n  readFile(filePath: string, req: RequestLike): Promise<string>;\n  readdir(dirPath: string, req: RequestLike): Promise<string[]>;\n}\n\ninterface QueryResult {\n  query: string;\n  isAsUser: boolean;\n}\n\n/**\n * Abstraction for filesystem operations that works in both dev and production modes\n */\ninterface FileSystemAdapter {\n  readdir(dirPath: string): Promise<string[]>;\n  readFile(filePath: string): Promise<string>;\n}\n\nexport class AppManager {\n  private readonly _queriesDir: string;\n  private readonly _metricViewsDir: string;\n\n  constructor(\n    queriesDir: string = path.resolve(process.cwd(), \"config/queries\"),\n    // Metric-view declarations live in a sibling `config/metric-views/`\n    // directory (next to `config/queries/` and `config/agents/`), NOT inside\n    // the queries folder. Default it as a sibling of `queriesDir` so a\n    // single-arg `new AppManager(dir)` (and every test that overrides only the\n    // queries dir) still resolves the metric-views dir consistently.\n    metricViewsDir: string = path.resolve(\n      path.dirname(queriesDir),\n      \"metric-views\",\n    ),\n  ) {\n    this._queriesDir = queriesDir;\n    this._metricViewsDir = metricViewsDir;\n  }\n\n  get queriesDir(): string {\n    return this._queriesDir;\n  }\n\n  get metricViewsDir(): string {\n    return this._metricViewsDir;\n  }\n\n  /**\n   * Whether `req` is a dev-tunnel (`?dev`) request. Internal `?dev` predicate\n   * shared by {@link createFsAdapter} (tunnel-vs-`fs` branch) and\n   * {@link isNotFoundError} (dev's message-match not-found classification).\n   */\n  private isDevRequest(req?: RequestLike): boolean {\n    return req?.query?.dev !== undefined;\n  }\n\n  /**\n   * Validates that a file path is within the given base directory. The\n   * `baseDir` is passed explicitly (rather than pinned to `queriesDir`) so the\n   * same traversal guard protects reads from any config directory —\n   * `config/queries/` for `.sql` files and `config/metric-views/` for the\n   * metric-view definitions.\n   */\n  private validatePath(fileName: string, baseDir: string): string | null {\n    const filePath = path.join(baseDir, fileName);\n    const resolvedPath = path.resolve(filePath);\n    const resolvedBaseDir = path.resolve(baseDir);\n\n    if (!resolvedPath.startsWith(resolvedBaseDir)) {\n      logger.error(\"Invalid config path: path traversal detected\");\n      return null;\n    }\n\n    return resolvedPath;\n  }\n\n  /**\n   * Creates a filesystem adapter based on dev mode or production mode\n   */\n  private createFsAdapter(\n    req?: RequestLike,\n    devFileReader?: DevFileReader,\n  ): FileSystemAdapter {\n    const isDevMode = this.isDevRequest(req);\n\n    if (isDevMode && devFileReader && req) {\n      // Dev mode: use WebSocket tunnel to read from local filesystem\n      return {\n        readdir: async (dirPath: string) => {\n          const relativePath = path.relative(process.cwd(), dirPath);\n          return devFileReader.readdir(relativePath, req);\n        },\n        readFile: async (filePath: string) => {\n          const relativePath = path.relative(process.cwd(), filePath);\n          return devFileReader.readFile(relativePath, req);\n        },\n      };\n    }\n\n    // Production mode: use server filesystem\n    return {\n      readdir: (dirPath: string) => fs.readdir(dirPath),\n      readFile: (filePath: string) => fs.readFile(filePath, \"utf8\"),\n    };\n  }\n\n  /**\n   * Retrieves a query file by key from the queries directory\n   * In dev mode with a request context, reads from local filesystem via WebSocket\n   * @param queryKey - The query file name (without extension)\n   * @param req - Optional request object to detect dev mode\n   * @param devFileReader - Optional DevFileReader instance to read files from local filesystem\n   * @returns The query content and execution mode (as user or as service principal)\n   */\n  async getAppQuery(\n    queryKey: string,\n    req?: RequestLike,\n    devFileReader?: DevFileReader,\n  ): Promise<QueryResult | null> {\n    // Security: Sanitize query key to prevent path traversal\n    if (!queryKey || !/^[a-zA-Z0-9_-]+$/.test(queryKey)) {\n      logger.error(\n        \"Invalid query key format: %s. Only alphanumeric characters, underscores, and hyphens are allowed.\",\n        queryKey,\n      );\n      return null;\n    }\n\n    // Create filesystem adapter for dev or production mode\n    const fsAdapter = this.createFsAdapter(req, devFileReader);\n\n    // Priority order: .obo.sql first (as user), then .sql (as service principal)\n    const oboFileName = `${queryKey}.obo.sql`;\n    const defaultFileName = `${queryKey}.sql`;\n\n    // List directory to find which query file exists\n    let files: string[];\n    try {\n      files = await fsAdapter.readdir(this.queriesDir);\n    } catch (error) {\n      logger.error(\n        `Failed to read queries directory: ${(error as Error).message}`,\n      );\n      return null;\n    }\n\n    // Determine which query file to use\n    let queryFileName: string | null = null;\n    let isAsUser = false;\n\n    if (files.includes(oboFileName)) {\n      queryFileName = oboFileName;\n      isAsUser = true;\n\n      // Warn if both variants exist\n      if (files.includes(defaultFileName)) {\n        logger.warn(\n          `Both ${oboFileName} and ${defaultFileName} found for query ${queryKey}. Using ${oboFileName}.`,\n        );\n      }\n    } else if (files.includes(defaultFileName)) {\n      queryFileName = defaultFileName;\n      isAsUser = false;\n    }\n\n    if (!queryFileName) {\n      logger.error(`Query file not found: ${queryKey}`);\n      return null;\n    }\n\n    // Validate and resolve the file path\n    const resolvedPath = this.validatePath(queryFileName, this._queriesDir);\n    if (!resolvedPath) {\n      return null;\n    }\n\n    // Read the query file\n    try {\n      const query = await fsAdapter.readFile(resolvedPath);\n      return { query, isAsUser };\n    } catch (error) {\n      logger.error(`Failed to read query file: ${(error as Error).message}`);\n      return null;\n    }\n  }\n\n  /**\n   * Read a single config file from a given base directory, dev-tunnel-aware.\n   * Shared core behind {@link readConfigFile} (queries dir) and\n   * {@link readMetricViewsConfig} (metric-views dir).\n   *\n   * @param baseDir - The config directory the file must resolve within.\n   * @param fileName - File name (or relative path) within `baseDir`.\n   * @param req - Optional request object to detect dev mode.\n   * @param devFileReader - Optional DevFileReader to read via the WebSocket tunnel.\n   * @returns The raw file contents, or `null` when the file is absent / the path is rejected.\n   */\n  private async readFileFromDir(\n    baseDir: string,\n    fileName: string,\n    req?: RequestLike,\n    devFileReader?: DevFileReader,\n  ): Promise<string | null> {\n    // Traversal guard: refuse to read outside the base directory.\n    const resolvedPath = this.validatePath(fileName, baseDir);\n    if (!resolvedPath) {\n      return null;\n    }\n\n    const fsAdapter = this.createFsAdapter(req, devFileReader);\n\n    try {\n      return await fsAdapter.readFile(resolvedPath);\n    } catch (error) {\n      if (this.isNotFoundError(error, req)) {\n        return null;\n      }\n      // Any other error (permission / IO / tunnel) is fatal: propagate so the\n      // caller can distinguish it from a dormant (absent) config.\n      throw error;\n    }\n  }\n\n  /**\n   * Read a single config file from the queries directory, dev-tunnel-aware.\n   *\n   * @param fileName - File name (or relative path) within the queries directory.\n   * @param req - Optional request object to detect dev mode.\n   * @param devFileReader - Optional DevFileReader to read via the WebSocket tunnel.\n   * @returns The raw file contents, or `null` when the file is absent / the path is rejected.\n   */\n  async readConfigFile(\n    fileName: string,\n    req?: RequestLike,\n    devFileReader?: DevFileReader,\n  ): Promise<string | null> {\n    return this.readFileFromDir(this._queriesDir, fileName, req, devFileReader);\n  }\n\n  /**\n   * Read a single config file from the metric-views directory\n   * (`config/metric-views/`), dev-tunnel-aware. Same absent-file/traversal\n   * semantics as {@link readConfigFile}, but rooted at {@link metricViewsDir}.\n   *\n   * @param fileName - File name (or relative path) within the metric-views directory.\n   * @param req - Optional request object to detect dev mode.\n   * @param devFileReader - Optional DevFileReader to read via the WebSocket tunnel.\n   * @returns The raw file contents, or `null` when the file is absent / the path is rejected.\n   */\n  async readMetricViewsConfig(\n    fileName: string,\n    req?: RequestLike,\n    devFileReader?: DevFileReader,\n  ): Promise<string | null> {\n    return this.readFileFromDir(\n      this._metricViewsDir,\n      fileName,\n      req,\n      devFileReader,\n    );\n  }\n\n  private isNotFoundError(error: unknown, req?: RequestLike): boolean {\n    if ((error as NodeJS.ErrnoException)?.code === \"ENOENT\") {\n      return true;\n    }\n    if (this.isDevRequest(req)) {\n      const message = (error as Error)?.message ?? \"\";\n      return /ENOENT|no such file/i.test(message);\n    }\n    return false;\n  }\n}\n\nexport type { DevFileReader, RequestLike };\n"],"mappings":"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"}

package/dist/appkit/package.js

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

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

@@ -1,3 +1,4 @@
+import { METRIC_CONFIG_FILE } from "../../schemas/metric-fqn.js";
 import { acquireSpawnLock, getSpawnLockPath, releaseSpawnLock } from "./spawn-lock.js";
 import fs from "node:fs";
 import path from "node:path";
@@ -33,16 +34,20 @@ async function runGenerateTypes(rootDir, outFile, warehouseId, options) {
 		if (resolvedWarehouseId) {
 			const resolvedOutFile = outFile || path.join(process.cwd(), "shared/appkit-types/analytics.d.ts");
 			const queryFolder = path.join(resolvedRootDir, "config/queries");
-			if (fs.existsSync(queryFolder)) {
+			const metricViewsFolder = path.join(resolvedRootDir, "config/metric-views");
+			const hasQueries = fs.existsSync(queryFolder);
+			const hasMetricViews = fs.existsSync(metricViewsFolder);
+			if (hasQueries || hasMetricViews) {
 				await typeGen.generateFromEntryPoint({
-					queryFolder,
+					queryFolder: hasQueries ? queryFolder : void 0,
+					metricViewsFolder: hasMetricViews ? metricViewsFolder : void 0,
 					outFile: resolvedOutFile,
 					warehouseId: resolvedWarehouseId,
 					noCache,
 					mode
 				});
-				console.log(`Generated query types: ${resolvedOutFile}`);
-				const metricConfig = path.join(queryFolder, "metric-views.json");
+				if (hasQueries) console.log(`Generated query types: ${resolvedOutFile}`);
+				const metricConfig = path.join(metricViewsFolder, METRIC_CONFIG_FILE);
 				if (fs.existsSync(metricConfig)) {
 					const typesDir = path.dirname(resolvedOutFile);
 					console.log(`Generated metric types: ${path.join(typesDir, "metric-views.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        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":"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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 { METRIC_CONFIG_FILE } from \"../../schemas/metric-fqn\";\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      const metricViewsFolder = path.join(\n        resolvedRootDir,\n        \"config/metric-views\",\n      );\n      const hasQueries = fs.existsSync(queryFolder);\n      const hasMetricViews = fs.existsSync(metricViewsFolder);\n\n      // Generate when either config surface exists. Metric-view types are\n      // independent of `.sql` queries — an app can declare metric views in\n      // `config/metric-views/` without a `config/queries/` folder.\n      if (hasQueries || hasMetricViews) {\n        await typeGen.generateFromEntryPoint({\n          queryFolder: hasQueries ? queryFolder : undefined,\n          metricViewsFolder: hasMetricViews ? metricViewsFolder : undefined,\n          outFile: resolvedOutFile,\n          warehouseId: resolvedWarehouseId,\n          noCache,\n          mode,\n        });\n\n        if (hasQueries) {\n          console.log(`Generated query types: ${resolvedOutFile}`);\n        }\n\n        const metricConfig = path.join(metricViewsFolder, METRIC_CONFIG_FILE);\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":"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"}

package/dist/plugins/analytics/analytics.d.ts

@@ -56,6 +56,22 @@ declare class AnalyticsPlugin extends Plugin implements ToolProvider {
    * When called via asUser(req), uses the user's Databricks credentials.
    */
   _handleQueryRoute(req: express.Request, res: express.Response): Promise<void>;
+  /**
+   * Handle metric-view execution requests (`POST /api/analytics/metric/:key`).
+   *
+   * Mirrors {@link _handleQueryRoute}'s JSON SSE path: the outer
+   * `executeStream` disables cache/retry and streams warehouse-readiness
+   * (`warehouse_status`) events, then the inner `execute` builds the metric SQL
+   * and delivers rows through {@link deliverJsonResult} as a `result` message.
+   * The `originalError` re-throw discipline preserves each error's structured
+   * `errorCode`/`clientMessage` for the SSE error payload.
+   *
+   * Lane dispatch is driven by the registration: an SP-lane metric runs as the
+   * app service principal (shared cache); an OBO-lane metric runs
+   * on-behalf-of the requesting user via `asUser(req)` (per-user cache keyed by
+   * a hash of the user identity).
+   */
+  _handleMetricRoute(req: express.Request, res: express.Response): Promise<void>;
   /**
    * JSON_ARRAY SSE path. Delegates the disposition/format fallback to
    * {@link deliverJsonResult} (INLINE JSON_ARRAY → on `needs-arrow-inline`,

package/dist/plugins/analytics/analytics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analytics.d.ts","names":[],"sources":["../../../src/plugins/analytics/analytics.ts"],"mappings":";;;;;;;;;;;;;;cAiGa,eAAA,SAAwB,MAAA,YAAkB,YAAA;;SAE9C,QAAA,EAAuB,cAAA;EAAA,iBAEb,WAAA;EAAA,UACC,MAAA,EAAQ,gBAAA;EAAA,QAGlB,SAAA;EAAA,QACA,cAAA;;;AATV;;;;;;UAmBU,gBAAA;cAEI,MAAA,EAAQ,gBAAA;EAWpB,YAAA,CAAa,MAAA,EAAQ,UAAA;EAiClB;;;;;;EAHG,mBAAA,CACJ,GAAA,EAAK,OAAA,CAAQ,OAAA,EACb,GAAA,EAAK,OAAA,CAAQ,QAAA,GACZ,OAAA;EA8jB2B;;;;;;;EAAA,QAziBhB,mBAAA;EAomBX;;;;;EAxkBG,eAAA,CAAgB,WAAA,WAAsB,OAAA;EA8gBvB;;;;EAtgBf,iBAAA,CACJ,GAAA,EAAK,OAAA,CAAQ,OAAA,EACb,GAAA,EAAK,OAAA,CAAQ,QAAA,GACZ,OAAA;EA7H8D;;;;;;EAAA,QAiVnD,qBAAA;EA5UI;;;;;;;;;EAAA,QAyWV,sBAAA;EA9UK;;;;;;;;;;;EAAA,QA8WC,uBAAA;EA5R8B;;;;;;;EAibtC,0BAAA,CAA2B,MAAA,EAAQ,WAAA,GAAc,OAAA;EAtapD;;;;;;;;;;;;;;;;;;EAAA,QAucK,qBAAA;EAmFF;;;;;;;;;;;;;;;EA1BA,KAAA,CACJ,KAAA,UACA,UAAA,GAAa,MAAA,SAAe,aAAA,sBAC5B,gBAAA,GAAmB,MAAA,eACnB,MAAA,GAAS,WAAA,GACR,OAAA;EAqBG,QAAA,CAAA,GAAY,OAAA;EAAA,QAIV,KAAA;EAuBR,aAAA,CAAA,GAAiB,mBAAA;EAIX,gBAAA,CACJ,IAAA,UACA,IAAA,WACA,MAAA,GAAS,WAAA,GACR,OAAA;EA3D2B;;;;;;;EAsE9B,OAAA,CAAQ,IAAA,GAXE,cAAA,GAWoD,MAAA,SAAA,YAAA;EAnEpD;AAyJZ;;;EA9EE,OAAA,CAAA;IA8EoB;;;2BA7JL,UAAA,GACA,MAAA,SAAe,aAAA,sBAAiC,gBAAA,GAC1C,MAAA,eAAmB,MAAA,GAC7B,WAAA,KACR,OAAA;EAAA;AAAA;;;;cAyJQ,SAAA,EAAS,QAAA,QAAA,eAAA,EAAA,gBAAA"}
+{"version":3,"file":"analytics.d.ts","names":[],"sources":["../../../src/plugins/analytics/analytics.ts"],"mappings":";;;;;;;;;;;;;;cAyGa,eAAA,SAAwB,MAAA,YAAkB,YAAA;;SAE9C,QAAA,EAAuB,cAAA;EAAA,iBAEb,WAAA;EAAA,UACC,MAAA,EAAQ,gBAAA;EAAA,QAGlB,SAAA;EAAA,QACA,cAAA;;;AATV;;;;;;UAmBU,gBAAA;cAEI,MAAA,EAAQ,gBAAA;EAWpB,YAAA,CAAa,MAAA,EAAQ,UAAA;EA2ClB;;;;;;EAHG,mBAAA,CACJ,GAAA,EAAK,OAAA,CAAQ,OAAA,EACb,GAAA,EAAK,OAAA,CAAQ,QAAA,GACZ,OAAA;EA4RA;;;;;;;EAAA,QAvQW,mBAAA;EAm0BI;;;;;EAvyBZ,eAAA,CAAgB,WAAA,WAAsB,OAAA;EAq1BkB;;;;EA70BxD,iBAAA,CACJ,GAAA,EAAK,OAAA,CAAQ,OAAA,EACb,GAAA,EAAK,OAAA,CAAQ,QAAA,GACZ,OAAA;EAuwBA;;;;;;;;;;;;;;;EA1iBG,kBAAA,CACJ,GAAA,EAAK,OAAA,CAAQ,OAAA,EACb,GAAA,EAAK,OAAA,CAAQ,QAAA,GACZ,OAAA;EAlViB;;;;;;EAAA,QAwkBN,qBAAA;EAphBC;;;;;;;;;EAAA,QAijBP,sBAAA;EAtfF;;;;;;;;;;;EAAA,QAshBQ,uBAAA;EApTP;;;;;;;EAycD,0BAAA,CAA2B,MAAA,EAAQ,WAAA,GAAc,OAAA;EAAd;;;;;;;;;;;;;;;;;;EAAA,QAiCjC,qBAAA;EAkHF;;;;;;;;;;;;;;;EAzDA,KAAA,CACJ,KAAA,UACA,UAAA,GAAa,MAAA,SAAe,aAAA,sBAC5B,gBAAA,GAAmB,MAAA,eACnB,MAAA,GAAS,WAAA,GACR,OAAA;EAqBG,QAAA,CAAA,GAAY,OAAA;EAAA,QAIV,KAAA;EAuBR,aAAA,CAAA,GAAiB,mBAAA;EAIX,gBAAA,CACJ,IAAA,UACA,IAAA,WACA,MAAA,GAAS,WAAA,GACR,OAAA;EA1DqC;;;;AA2J1C;;;EAtFE,OAAA,CAAQ,IAAA,GAXE,cAAA,GAWoD,MAAA,SAAA,YAAA;EAsF1C;;;;EA9EpB,OAAA,CAAA;IA8EoB;;;2BA7JL,UAAA,GACA,MAAA,SAAe,aAAA,sBAAiC,gBAAA,GAC1C,MAAA,eAAmB,MAAA,GAC7B,WAAA,KACR,OAAA;EAAA;AAAA;;;;cAyJQ,SAAA,EAAS,QAAA,QAAA,eAAA,EAAA,gBAAA"}

package/dist/plugins/analytics/analytics.js

@@ -15,9 +15,14 @@ import { defineTool, executeFromRegistry, toolsFromRegistry } from "../../core/a
 import { assertReadOnlySql } from "../../core/agent/tools/sql-policy.js";
 import { queryDefaults } from "./defaults.js";
 import manifest_default from "./manifest.js";
+import { buildMetricSql } from "./mv/formatters.js";
+import { composeMetricCacheKey, deriveMetricExecutorKey } from "./mv/cache.js";
+import { loadMetricRegistry } from "./mv/registry.js";
+import { normalizeAnalyticsFormat } from "./types.js";
+import { validateMetricRequest } from "./mv/schemas.js";
+import "./metric.js";
 import { QueryProcessor } from "./query.js";
 import { deliverArrowBytes, deliverJsonResult } from "./result-delivery.js";
-import { normalizeAnalyticsFormat } from "./types.js";
 import { z } from "zod";
 
 //#region src/plugins/analytics/analytics.ts
@@ -92,6 +97,14 @@ var AnalyticsPlugin = class extends Plugin {
 				await this._handleQueryRoute(req, res);
 			}
 		});
+		this.route(router, {
+			name: "metric",
+			method: "post",
+			path: "/metric/:key",
+			handler: async (req, res) => {
+				await this._handleMetricRoute(req, res);
+			}
+		});
 		this.route(router, {
 			name: "arrow-columns",
 			method: "get",
@@ -240,6 +253,154 @@ var AnalyticsPlugin = class extends Plugin {
 		}, streamExecutionSettings, executorKey);
 	}
 	/**
+	* Handle metric-view execution requests (`POST /api/analytics/metric/:key`).
+	*
+	* Mirrors {@link _handleQueryRoute}'s JSON SSE path: the outer
+	* `executeStream` disables cache/retry and streams warehouse-readiness
+	* (`warehouse_status`) events, then the inner `execute` builds the metric SQL
+	* and delivers rows through {@link deliverJsonResult} as a `result` message.
+	* The `originalError` re-throw discipline preserves each error's structured
+	* `errorCode`/`clientMessage` for the SSE error payload.
+	*
+	* Lane dispatch is driven by the registration: an SP-lane metric runs as the
+	* app service principal (shared cache); an OBO-lane metric runs
+	* on-behalf-of the requesting user via `asUser(req)` (per-user cache keyed by
+	* a hash of the user identity).
+	*/
+	async _handleMetricRoute(req, res) {
+		const { key } = req.params;
+		logger.debug(req, "Executing metric: %s", key);
+		const event = logger.event(req);
+		event?.setComponent("analytics", "executeMetric").setContext("analytics", {
+			metric_key: key,
+			plugin: this.name
+		});
+		if (!key) {
+			res.status(400).json({ error: "metric key is required" });
+			return;
+		}
+		let registry;
+		try {
+			registry = await loadMetricRegistry(this.app, req, this.devFileReader);
+		} catch (err) {
+			const reason = err instanceof Error ? err.message : String(err);
+			logger.warn(req, "Failed to load metric registry: %s", reason);
+			event?.setContext("analytics", { metric_registry_load_error: reason });
+			res.status(503).json({
+				error: "Metric registry not available",
+				code: "METRIC_REGISTRY_LOAD_FAILED"
+			});
+			return;
+		}
+		const registration = Object.hasOwn(registry, key) ? registry[key] : void 0;
+		if (!registration) {
+			event?.setContext("analytics", { unknown_metric_key: key });
+			res.status(404).json({ error: "Metric not found" });
+			return;
+		}
+		let request;
+		try {
+			request = validateMetricRequest(req.body ?? {});
+		} catch (err) {
+			if (err instanceof AppKitError) {
+				res.status(err.statusCode).json({
+					error: err.message,
+					code: err.code
+				});
+				return;
+			}
+			event?.setContext("analytics", {
+				unexpected_error: err instanceof Error ? err.message : String(err),
+				metric_key: key
+			});
+			logger.warn(req, "Unexpected throw during metric request validation for %s: %s", key, err instanceof Error ? err.message : String(err));
+			res.status(400).json({ error: "Invalid request body" });
+			return;
+		}
+		let executor;
+		let executorKey;
+		try {
+			const isObo = registration.lane === "obo";
+			executor = isObo ? this.asUser(req) : this;
+			executorKey = deriveMetricExecutorKey({
+				lane: registration.lane,
+				userIdentity: isObo ? this.resolveUserId(req) : void 0
+			});
+		} catch (err) {
+			if (err instanceof AppKitError) {
+				res.status(err.statusCode).json({
+					error: err.message,
+					code: err.code
+				});
+				return;
+			}
+			throw err;
+		}
+		const cacheConfig = {
+			...queryDefaults.cache,
+			cacheKey: composeMetricCacheKey({
+				metricKey: key,
+				source: registration.source,
+				measures: request.measures,
+				dimensions: request.dimensions,
+				timeGrain: request.timeGrain,
+				timeDimension: request.timeDimension,
+				filter: request.filter,
+				format: "JSON_ARRAY",
+				executorKey,
+				limit: request.limit
+			})
+		};
+		const sqlConfig = {
+			...queryDefaults,
+			cache: cacheConfig
+		};
+		const streamExecutionSettings = { default: {
+			cache: { enabled: false },
+			retry: { enabled: false }
+		} };
+		const startupTimeoutMs = this.config.warehouseStartupTimeoutMs ?? DEFAULT_WAREHOUSE_STARTUP_TIMEOUT_MS;
+		const autoStartWarehouse = this.config.autoStartWarehouse ?? true;
+		const self = this;
+		await executor.executeStream(res, async function* (signal) {
+			const workspaceClient = getWorkspaceClient();
+			const warehouseId = await getWarehouseId();
+			const readinessUpdates = streamCallbacks((emit) => self.SQLClient.ensureWarehouseRunning(workspaceClient, warehouseId, {
+				signal,
+				timeoutMs: startupTimeoutMs,
+				autoStart: autoStartWarehouse,
+				onStatus: emit
+			}));
+			for await (const update of readinessUpdates) yield {
+				type: "warehouse_status",
+				status: {
+					state: update.state,
+					elapsedMs: update.elapsedMs
+				}
+			};
+			let originalError;
+			const sqlResult = await executor.execute(async (sig) => {
+				try {
+					const { statement, parameters } = buildMetricSql(registration, request);
+					const processedParams = await self.queryProcessor.processQueryParams(statement, Object.keys(parameters).length > 0 ? parameters : void 0);
+					return await self._executeJsonArrayPath(executor, statement, processedParams, sig);
+				} catch (err) {
+					originalError = err;
+					throw err;
+				}
+			}, { default: sqlConfig }, executorKey);
+			if (!sqlResult.ok) {
+				const msg = sqlResult.message;
+				const lower = msg.toLowerCase();
+				if (lower.includes("operation was aborted") || lower.includes("the request was aborted") || lower.includes("statement was canceled")) throw new DOMException(lower.includes("canceled") ? msg : "The operation was aborted.", "AbortError");
+				if (originalError instanceof AppKitError) throw originalError;
+				const inner = msg.startsWith("Statement failed: ") ? msg.slice(18) : msg;
+				throw ExecutionError.statementFailed(inner);
+			}
+			yield sqlResult.data;
+		}, streamExecutionSettings, executorKey);
+	}
+	/**
 	* JSON_ARRAY SSE path. Delegates the disposition/format fallback to
 	* {@link deliverJsonResult} (INLINE JSON_ARRAY → on `needs-arrow-inline`,
 	* INLINE ARROW_STREAM decoded to rows) and wraps the rows in a `result`