feat: metric-view runtime

apps/dev-playground/shared/appkit-types/metric-views.d.ts

@@ -30,23 +30,31 @@ declare module "@databricks/appkit-ui/react" {
         measures: {
       "active_accounts": {
         type: "bigint";
+        display_name: "Active Accounts";
+        format: "#,##0";
       };
       "churn_rate": {
         type: "decimal";
+        display_name: "Churn Rate";
       };
       "avg_ltv": {
         type: "double";
+        display_name: "Average LTV";
+        format: "$#,##0.00";
       };
     };
         dimensions: {
       "segment": {
         type: "string";
+        display_name: "Customer Segment";
       };
       "region": {
         type: "string";
+        display_name: "Region";
       };
       "csm_email": {
         type: "string";
+        display_name: "CSM Email";
       };
     };
       };
@@ -80,27 +88,38 @@ declare module "@databricks/appkit-ui/react" {
         measures: {
       "mrr": {
         type: "double";
+        display_name: "Monthly Recurring Revenue";
+        format: "$#,##0.00";
       };
       "arr": {
         type: "double";
+        display_name: "Annual Recurring Revenue";
+        format: "$#,##0.00";
         description: "Annualized contract value across all active subscriptions";
       };
       "new_arr": {
         type: "double";
+        display_name: "New ARR";
+        format: "$#,##0.00";
       };
       "churned_arr": {
         type: "double";
+        display_name: "Churned ARR";
+        format: "$#,##0.00";
       };
     };
         dimensions: {
       "region": {
         type: "string";
+        display_name: "Region";
       };
       "segment": {
         type: "string";
+        display_name: "Customer Segment";
       };
       "created_at": {
         type: "timestamp_ltz";
+        display_name: "Subscription Start";
         time_grain: readonly ["day", "hour", "minute", "month", "quarter", "week", "year"];
       };
     };

packages/appkit/src/app/index.ts

@@ -28,7 +28,26 @@ interface FileSystemAdapter {
 }
 
 export class AppManager {
-  private readonly queriesDir = path.resolve(process.cwd(), "config/queries");
+  private readonly _queriesDir: string;
+
+  constructor(
+    queriesDir: string = path.resolve(process.cwd(), "config/queries"),
+  ) {
+    this._queriesDir = queriesDir;
+  }
+
+  get queriesDir(): string {
+    return this._queriesDir;
+  }
+
+  /**
+   * 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(req?: RequestLike): boolean {
+    return req?.query?.dev !== undefined;
+  }
 
   /**
    * Validates that a file path is within the queries directory
@@ -53,7 +72,7 @@ export class AppManager {
     req?: RequestLike,
     devFileReader?: DevFileReader,
   ): FileSystemAdapter {
-    const isDevMode = req?.query?.dev !== undefined;
+    const isDevMode = this.isDevRequest(req);
 
     if (isDevMode && devFileReader && req) {
       // Dev mode: use WebSocket tunnel to read from local filesystem
@@ -155,6 +174,50 @@ export class AppManager {
       return null;
     }
   }
+
+  /**
+   * 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: string,
+    req?: RequestLike,
+    devFileReader?: DevFileReader,
+  ): Promise<string | null> {
+    // Traversal guard: refuse to read outside the queries directory.
+    const resolvedPath = this.validatePath(fileName);
+    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;
+      }
+      // Any other error (permission / IO / tunnel) is fatal: propagate so the
+      // caller can distinguish it from a dormant (absent) config.
+      throw error;
+    }
+  }
+
+  private isNotFoundError(error: unknown, req?: RequestLike): boolean {
+    if ((error as NodeJS.ErrnoException)?.code === "ENOENT") {
+      return true;
+    }
+    if (this.isDevRequest(req)) {
+      const message = (error as Error)?.message ?? "";
+      return /ENOENT|no such file/i.test(message);
+    }
+    return false;
+  }
 }
 
-export type { DevFileReader };
+export type { DevFileReader, RequestLike };

packages/appkit/src/app/tests/read-config-file.test.ts

@@ -0,0 +1,157 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import type { DevFileReader } from "../index";
+import { AppManager } from "../index";
+
+// NOTE: unlike the sibling `app.test.ts`, this spec deliberately does NOT mock
+// `node:fs/promises` — `readConfigFile` is exercised against real temp files so
+// the not-found-vs-throw distinction is driven by genuine errno codes.
+
+describe("AppManager.readConfigFile", () => {
+  let tmpDir: string;
+  let appManager: AppManager;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "appmgr-config-"));
+    appManager = new AppManager(tmpDir);
+  });
+
+  afterEach(async () => {
+    vi.restoreAllMocks();
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  describe("dir override + getter", () => {
+    test("queriesDir getter exposes the overridden directory", () => {
+      expect(appManager.queriesDir).toBe(tmpDir);
+    });
+
+    test("defaults to <cwd>/config/queries when no override is given", () => {
+      const defaultManager = new AppManager();
+      expect(defaultManager.queriesDir).toBe(
+        path.resolve(process.cwd(), "config/queries"),
+      );
+    });
+  });
+
+  describe("production mode (direct fs)", () => {
+    test("returns file contents for an existing file", async () => {
+      await fs.writeFile(
+        path.join(tmpDir, "metric-views.json"),
+        '{"hello":"world"}',
+        "utf8",
+      );
+
+      const result = await appManager.readConfigFile("metric-views.json");
+      expect(result).toBe('{"hello":"world"}');
+    });
+
+    test("returns null for a genuine not-found (ENOENT)", async () => {
+      const result = await appManager.readConfigFile("does-not-exist.json");
+      expect(result).toBeNull();
+    });
+
+    test("throws (does NOT return null) for a non-ENOENT error", async () => {
+      // Reading a directory as a file rejects with EISDIR — a real, non-ENOENT
+      // error that must propagate rather than be swallowed to null.
+      await fs.mkdir(path.join(tmpDir, "a-directory"));
+
+      await expect(appManager.readConfigFile("a-directory")).rejects.toThrow();
+    });
+
+    test("throws for a simulated EACCES (permission) error", async () => {
+      const err = Object.assign(new Error("permission denied"), {
+        code: "EACCES",
+      });
+      vi.spyOn(fs, "readFile").mockRejectedValueOnce(err);
+
+      await expect(
+        appManager.readConfigFile("metric-views.json"),
+      ).rejects.toThrow("permission denied");
+    });
+
+    test("reads via direct fs (not the dev reader) without ?dev", async () => {
+      await fs.writeFile(
+        path.join(tmpDir, "metric-views.json"),
+        "prod-contents",
+        "utf8",
+      );
+      const devFileReader: DevFileReader = {
+        readdir: vi.fn(),
+        readFile: vi.fn(),
+      };
+
+      const result = await appManager.readConfigFile(
+        "metric-views.json",
+        { query: {}, headers: {} },
+        devFileReader,
+      );
+
+      expect(result).toBe("prod-contents");
+      expect(devFileReader.readFile).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("path traversal protection", () => {
+    test("returns null and does not read outside the queries dir", async () => {
+      const readSpy = vi.spyOn(fs, "readFile");
+      const result = await appManager.readConfigFile("../../etc/passwd");
+
+      expect(result).toBeNull();
+      expect(readSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("dev mode (WebSocket tunnel)", () => {
+    const devReq = { query: { dev: "true" }, headers: {} };
+
+    test("reads via devFileReader in dev mode", async () => {
+      const devFileReader: DevFileReader = {
+        readdir: vi.fn(),
+        readFile: vi.fn().mockResolvedValue("dev-contents"),
+      };
+
+      const result = await appManager.readConfigFile(
+        "metric-views.json",
+        devReq,
+        devFileReader,
+      );
+
+      expect(result).toBe("dev-contents");
+      expect(devFileReader.readFile).toHaveBeenCalledWith(
+        expect.stringContaining("metric-views.json"),
+        devReq,
+      );
+    });
+
+    test("returns null for the dev tunnel's not-found signal (best-effort)", async () => {
+      const devFileReader: DevFileReader = {
+        readdir: vi.fn(),
+        readFile: vi
+          .fn()
+          .mockRejectedValue(new Error("ENOENT: no such file or directory")),
+      };
+
+      const result = await appManager.readConfigFile(
+        "metric-views.json",
+        devReq,
+        devFileReader,
+      );
+
+      expect(result).toBeNull();
+    });
+
+    test("throws for a non-not-found dev tunnel error", async () => {
+      const devFileReader: DevFileReader = {
+        readdir: vi.fn(),
+        readFile: vi.fn().mockRejectedValue(new Error("tunnel disconnected")),
+      };
+
+      await expect(
+        appManager.readConfigFile("metric-views.json", devReq, devFileReader),
+      ).rejects.toThrow("tunnel disconnected");
+    });
+  });
+});