@databricks/appkit 0.5.4 → 0.7.0

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

@@ -1 +1 @@
-{"version":3,"file":"analytics.js","names":[],"sources":["../../../src/plugins/analytics/analytics.ts"],"sourcesContent":["import type { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport type express from \"express\";\nimport type {\n  IAppRouter,\n  PluginExecuteConfig,\n  SQLTypeMarker,\n  StreamExecutionSettings,\n} from \"shared\";\nimport { SQLWarehouseConnector } from \"../../connectors\";\nimport {\n  getCurrentUserId,\n  getWarehouseId,\n  getWorkspaceClient,\n} from \"../../context\";\nimport { createLogger } from \"../../logging/logger\";\nimport { Plugin, toPlugin } from \"../../plugin\";\nimport { queryDefaults } from \"./defaults\";\nimport { QueryProcessor } from \"./query\";\nimport type {\n  AnalyticsQueryResponse,\n  IAnalyticsConfig,\n  IAnalyticsQueryRequest,\n} from \"./types\";\n\nconst logger = createLogger(\"analytics\");\n\nexport class AnalyticsPlugin extends Plugin {\n  name = \"analytics\";\n  protected envVars: string[] = [];\n\n  protected static description = \"Analytics plugin for data analysis\";\n  protected declare config: IAnalyticsConfig;\n\n  // analytics services\n  private SQLClient: SQLWarehouseConnector;\n  private queryProcessor: QueryProcessor;\n\n  constructor(config: IAnalyticsConfig) {\n    super(config);\n    this.config = config;\n    this.queryProcessor = new QueryProcessor();\n\n    this.SQLClient = new SQLWarehouseConnector({\n      timeout: config.timeout,\n      telemetry: config.telemetry,\n    });\n  }\n\n  injectRoutes(router: IAppRouter) {\n    // Service principal endpoints\n    this.route(router, {\n      name: \"arrow\",\n      method: \"get\",\n      path: \"/arrow-result/:jobId\",\n      handler: async (req: express.Request, res: express.Response) => {\n        await this._handleArrowRoute(req, res);\n      },\n    });\n\n    this.route<AnalyticsQueryResponse>(router, {\n      name: \"query\",\n      method: \"post\",\n      path: \"/query/:query_key\",\n      handler: async (req: express.Request, res: express.Response) => {\n        await this._handleQueryRoute(req, res);\n      },\n    });\n  }\n\n  /**\n   * Handle Arrow data download requests.\n   * When called via asUser(req), uses the user's Databricks credentials.\n   */\n  async _handleArrowRoute(\n    req: express.Request,\n    res: express.Response,\n  ): Promise<void> {\n    try {\n      const { jobId } = req.params;\n      const workspaceClient = getWorkspaceClient();\n\n      logger.debug(\"Processing Arrow job request for jobId=%s\", jobId);\n\n      const event = logger.event(req);\n      event?.setComponent(\"analytics\", \"getArrowData\").setContext(\"analytics\", {\n        job_id: jobId,\n        plugin: this.name,\n      });\n\n      const result = await this.getArrowData(workspaceClient, jobId);\n\n      res.setHeader(\"Content-Type\", \"application/octet-stream\");\n      res.setHeader(\"Content-Length\", result.data.length.toString());\n      res.setHeader(\"Cache-Control\", \"public, max-age=3600\");\n\n      logger.debug(\n        \"Sending Arrow buffer: %d bytes for job %s\",\n        result.data.length,\n        jobId,\n      );\n      res.send(Buffer.from(result.data));\n    } catch (error) {\n      logger.error(\"Arrow job error: %O\", error);\n      res.status(404).json({\n        error: error instanceof Error ? error.message : \"Arrow job not found\",\n        plugin: this.name,\n      });\n    }\n  }\n\n  /**\n   * Handle SQL query execution requests.\n   * When called via asUser(req), uses the user's Databricks credentials.\n   */\n  async _handleQueryRoute(\n    req: express.Request,\n    res: express.Response,\n  ): Promise<void> {\n    const { query_key } = req.params;\n    const { parameters, format = \"JSON\" } = req.body as IAnalyticsQueryRequest;\n\n    // Request-scoped logging with WideEvent tracking\n    logger.debug(req, \"Executing query: %s (format=%s)\", query_key, format);\n\n    const event = logger.event(req);\n    event?.setComponent(\"analytics\", \"executeQuery\").setContext(\"analytics\", {\n      query_key,\n      format,\n      parameter_count: parameters ? Object.keys(parameters).length : 0,\n      plugin: this.name,\n    });\n\n    if (!query_key) {\n      res.status(400).json({ error: \"query_key is required\" });\n      return;\n    }\n\n    const queryResult = await this.app.getAppQuery(\n      query_key,\n      req,\n      this.devFileReader,\n    );\n\n    if (!queryResult) {\n      res.status(404).json({ error: \"Query not found\" });\n      return;\n    }\n\n    const { query, isAsUser } = queryResult;\n\n    // get execution context - user-scoped if .obo.sql, otherwise service principal\n    const executor = isAsUser ? this.asUser(req) : this;\n    const userKey = getCurrentUserId();\n    const executorKey = isAsUser ? userKey : \"global\";\n\n    const queryParameters =\n      format === \"ARROW\"\n        ? {\n            formatParameters: {\n              disposition: \"EXTERNAL_LINKS\",\n              format: \"ARROW_STREAM\",\n            },\n            type: \"arrow\",\n          }\n        : {\n            type: \"result\",\n          };\n\n    const hashedQuery = this.queryProcessor.hashQuery(query);\n\n    const defaultConfig: PluginExecuteConfig = {\n      ...queryDefaults,\n      cache: {\n        ...queryDefaults.cache,\n        cacheKey: [\n          \"analytics:query\",\n          query_key,\n          JSON.stringify(parameters),\n          JSON.stringify(format),\n          hashedQuery,\n          executorKey,\n        ],\n      },\n    };\n\n    const streamExecutionSettings: StreamExecutionSettings = {\n      default: defaultConfig,\n    };\n\n    await executor.executeStream(\n      res,\n      async (signal) => {\n        const processedParams = await this.queryProcessor.processQueryParams(\n          query,\n          parameters,\n        );\n\n        const result = await executor.query(\n          query,\n          processedParams,\n          queryParameters.formatParameters,\n          signal,\n        );\n\n        return { type: queryParameters.type, ...result };\n      },\n      streamExecutionSettings,\n      executorKey,\n    );\n  }\n\n  /**\n   * Execute a SQL query using the current execution context.\n   *\n   * When called directly: uses service principal credentials.\n   * When called via asUser(req).query(...): uses user's credentials.\n   *\n   * @example\n   * ```typescript\n   * // Service principal execution\n   * const result = await analytics.query(\"SELECT * FROM table\")\n   *\n   * // User context execution (in route handler)\n   * const result = await this.asUser(req).query(\"SELECT * FROM table\")\n   * ```\n   */\n  async query(\n    query: string,\n    parameters?: Record<string, SQLTypeMarker | null | undefined>,\n    formatParameters?: Record<string, any>,\n    signal?: AbortSignal,\n  ): Promise<any> {\n    const workspaceClient = getWorkspaceClient();\n    const warehouseId = await getWarehouseId();\n\n    const { statement, parameters: sqlParameters } =\n      this.queryProcessor.convertToSQLParameters(query, parameters);\n\n    const response = await this.SQLClient.executeStatement(\n      workspaceClient,\n      {\n        statement,\n        warehouse_id: warehouseId,\n        parameters: sqlParameters,\n        ...formatParameters,\n      },\n      signal,\n    );\n\n    return response.result;\n  }\n\n  /**\n   * Get Arrow-formatted data for a completed query job.\n   */\n  protected async getArrowData(\n    workspaceClient: WorkspaceClient,\n    jobId: string,\n    signal?: AbortSignal,\n  ): Promise<ReturnType<typeof this.SQLClient.getArrowData>> {\n    return await this.SQLClient.getArrowData(workspaceClient, jobId, signal);\n  }\n\n  async shutdown(): Promise<void> {\n    this.streamManager.abortAll();\n  }\n\n  /**\n   * Returns the public exports for the analytics plugin.\n   * Note: `asUser()` is automatically added by AppKit.\n   */\n  exports() {\n    return {\n      /**\n       * Execute a SQL query using service principal credentials.\n       */\n      query: this.query,\n    };\n  }\n}\n\n/**\n * @internal\n */\nexport const analytics = toPlugin<\n  typeof AnalyticsPlugin,\n  IAnalyticsConfig,\n  \"analytics\"\n>(AnalyticsPlugin, \"analytics\");\n"],"mappings":"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"}
+{"version":3,"file":"analytics.js","names":[],"sources":["../../../src/plugins/analytics/analytics.ts"],"sourcesContent":["import type { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport type express from \"express\";\nimport type {\n  IAppRouter,\n  PluginExecuteConfig,\n  SQLTypeMarker,\n  StreamExecutionSettings,\n} from \"shared\";\nimport { SQLWarehouseConnector } from \"../../connectors\";\nimport {\n  getCurrentUserId,\n  getWarehouseId,\n  getWorkspaceClient,\n} from \"../../context\";\nimport { createLogger } from \"../../logging/logger\";\nimport { Plugin, toPlugin } from \"../../plugin\";\nimport { queryDefaults } from \"./defaults\";\nimport { analyticsManifest } from \"./manifest\";\nimport { QueryProcessor } from \"./query\";\nimport type {\n  AnalyticsQueryResponse,\n  IAnalyticsConfig,\n  IAnalyticsQueryRequest,\n} from \"./types\";\n\nconst logger = createLogger(\"analytics\");\n\nexport class AnalyticsPlugin extends Plugin {\n  name = \"analytics\";\n\n  /** Plugin manifest declaring metadata and resource requirements */\n  static manifest = analyticsManifest;\n\n  protected static description = \"Analytics plugin for data analysis\";\n  protected declare config: IAnalyticsConfig;\n\n  // analytics services\n  private SQLClient: SQLWarehouseConnector;\n  private queryProcessor: QueryProcessor;\n\n  constructor(config: IAnalyticsConfig) {\n    super(config);\n    this.config = config;\n    this.queryProcessor = new QueryProcessor();\n\n    this.SQLClient = new SQLWarehouseConnector({\n      timeout: config.timeout,\n      telemetry: config.telemetry,\n    });\n  }\n\n  injectRoutes(router: IAppRouter) {\n    // Service principal endpoints\n    this.route(router, {\n      name: \"arrow\",\n      method: \"get\",\n      path: \"/arrow-result/:jobId\",\n      handler: async (req: express.Request, res: express.Response) => {\n        await this._handleArrowRoute(req, res);\n      },\n    });\n\n    this.route<AnalyticsQueryResponse>(router, {\n      name: \"query\",\n      method: \"post\",\n      path: \"/query/:query_key\",\n      handler: async (req: express.Request, res: express.Response) => {\n        await this._handleQueryRoute(req, res);\n      },\n    });\n  }\n\n  /**\n   * Handle Arrow data download requests.\n   * When called via asUser(req), uses the user's Databricks credentials.\n   */\n  async _handleArrowRoute(\n    req: express.Request,\n    res: express.Response,\n  ): Promise<void> {\n    try {\n      const { jobId } = req.params;\n      const workspaceClient = getWorkspaceClient();\n\n      logger.debug(\"Processing Arrow job request for jobId=%s\", jobId);\n\n      const event = logger.event(req);\n      event?.setComponent(\"analytics\", \"getArrowData\").setContext(\"analytics\", {\n        job_id: jobId,\n        plugin: this.name,\n      });\n\n      const result = await this.getArrowData(workspaceClient, jobId);\n\n      res.setHeader(\"Content-Type\", \"application/octet-stream\");\n      res.setHeader(\"Content-Length\", result.data.length.toString());\n      res.setHeader(\"Cache-Control\", \"public, max-age=3600\");\n\n      logger.debug(\n        \"Sending Arrow buffer: %d bytes for job %s\",\n        result.data.length,\n        jobId,\n      );\n      res.send(Buffer.from(result.data));\n    } catch (error) {\n      logger.error(\"Arrow job error: %O\", error);\n      res.status(404).json({\n        error: error instanceof Error ? error.message : \"Arrow job not found\",\n        plugin: this.name,\n      });\n    }\n  }\n\n  /**\n   * Handle SQL query execution requests.\n   * When called via asUser(req), uses the user's Databricks credentials.\n   */\n  async _handleQueryRoute(\n    req: express.Request,\n    res: express.Response,\n  ): Promise<void> {\n    const { query_key } = req.params;\n    const { parameters, format = \"JSON\" } = req.body as IAnalyticsQueryRequest;\n\n    // Request-scoped logging with WideEvent tracking\n    logger.debug(req, \"Executing query: %s (format=%s)\", query_key, format);\n\n    const event = logger.event(req);\n    event?.setComponent(\"analytics\", \"executeQuery\").setContext(\"analytics\", {\n      query_key,\n      format,\n      parameter_count: parameters ? Object.keys(parameters).length : 0,\n      plugin: this.name,\n    });\n\n    if (!query_key) {\n      res.status(400).json({ error: \"query_key is required\" });\n      return;\n    }\n\n    const queryResult = await this.app.getAppQuery(\n      query_key,\n      req,\n      this.devFileReader,\n    );\n\n    if (!queryResult) {\n      res.status(404).json({ error: \"Query not found\" });\n      return;\n    }\n\n    const { query, isAsUser } = queryResult;\n\n    // get execution context - user-scoped if .obo.sql, otherwise service principal\n    const executor = isAsUser ? this.asUser(req) : this;\n    const userKey = getCurrentUserId();\n    const executorKey = isAsUser ? userKey : \"global\";\n\n    const queryParameters =\n      format === \"ARROW\"\n        ? {\n            formatParameters: {\n              disposition: \"EXTERNAL_LINKS\",\n              format: \"ARROW_STREAM\",\n            },\n            type: \"arrow\",\n          }\n        : {\n            type: \"result\",\n          };\n\n    const hashedQuery = this.queryProcessor.hashQuery(query);\n\n    const defaultConfig: PluginExecuteConfig = {\n      ...queryDefaults,\n      cache: {\n        ...queryDefaults.cache,\n        cacheKey: [\n          \"analytics:query\",\n          query_key,\n          JSON.stringify(parameters),\n          JSON.stringify(format),\n          hashedQuery,\n          executorKey,\n        ],\n      },\n    };\n\n    const streamExecutionSettings: StreamExecutionSettings = {\n      default: defaultConfig,\n    };\n\n    await executor.executeStream(\n      res,\n      async (signal) => {\n        const processedParams = await this.queryProcessor.processQueryParams(\n          query,\n          parameters,\n        );\n\n        const result = await executor.query(\n          query,\n          processedParams,\n          queryParameters.formatParameters,\n          signal,\n        );\n\n        return { type: queryParameters.type, ...result };\n      },\n      streamExecutionSettings,\n      executorKey,\n    );\n  }\n\n  /**\n   * Execute a SQL query using the current execution context.\n   *\n   * When called directly: uses service principal credentials.\n   * When called via asUser(req).query(...): uses user's credentials.\n   *\n   * @example\n   * ```typescript\n   * // Service principal execution\n   * const result = await analytics.query(\"SELECT * FROM table\")\n   *\n   * // User context execution (in route handler)\n   * const result = await this.asUser(req).query(\"SELECT * FROM table\")\n   * ```\n   */\n  async query(\n    query: string,\n    parameters?: Record<string, SQLTypeMarker | null | undefined>,\n    formatParameters?: Record<string, any>,\n    signal?: AbortSignal,\n  ): Promise<any> {\n    const workspaceClient = getWorkspaceClient();\n    const warehouseId = await getWarehouseId();\n\n    const { statement, parameters: sqlParameters } =\n      this.queryProcessor.convertToSQLParameters(query, parameters);\n\n    const response = await this.SQLClient.executeStatement(\n      workspaceClient,\n      {\n        statement,\n        warehouse_id: warehouseId,\n        parameters: sqlParameters,\n        ...formatParameters,\n      },\n      signal,\n    );\n\n    return response.result;\n  }\n\n  /**\n   * Get Arrow-formatted data for a completed query job.\n   */\n  protected async getArrowData(\n    workspaceClient: WorkspaceClient,\n    jobId: string,\n    signal?: AbortSignal,\n  ): Promise<ReturnType<typeof this.SQLClient.getArrowData>> {\n    return await this.SQLClient.getArrowData(workspaceClient, jobId, signal);\n  }\n\n  async shutdown(): Promise<void> {\n    this.streamManager.abortAll();\n  }\n\n  /**\n   * Returns the public exports for the analytics plugin.\n   * Note: `asUser()` is automatically added by AppKit.\n   */\n  exports() {\n    return {\n      /**\n       * Execute a SQL query using service principal credentials.\n       */\n      query: this.query,\n    };\n  }\n}\n\n/**\n * @internal\n */\nexport const analytics = toPlugin<\n  typeof AnalyticsPlugin,\n  IAnalyticsConfig,\n  \"analytics\"\n>(AnalyticsPlugin, \"analytics\");\n"],"mappings":"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"}

package/dist/plugins/analytics/index.js

@@ -1,3 +1,4 @@
+import { analyticsManifest } from "./manifest.js";
 import { AnalyticsPlugin, analytics } from "./analytics.js";
 
 export {  };

package/dist/plugins/analytics/manifest.js

@@ -0,0 +1,21 @@
+import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+//#region src/plugins/analytics/manifest.ts
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+* Analytics plugin manifest.
+*
+* The analytics plugin requires a SQL Warehouse for executing queries
+* against Databricks data sources.
+*
+* @remarks
+* The source of truth for this manifest is `manifest.json` in the same directory.
+* This file loads the JSON and exports it with proper TypeScript typing.
+*/
+const analyticsManifest = JSON.parse(readFileSync(join(__dirname, "manifest.json"), "utf-8"));
+
+//#endregion
+export { analyticsManifest };
+//# sourceMappingURL=manifest.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","names":[],"sources":["../../../src/plugins/analytics/manifest.ts"],"sourcesContent":["import { readFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport type { PluginManifest } from \"../../registry\";\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\n\n/**\n * Analytics plugin manifest.\n *\n * The analytics plugin requires a SQL Warehouse for executing queries\n * against Databricks data sources.\n *\n * @remarks\n * The source of truth for this manifest is `manifest.json` in the same directory.\n * This file loads the JSON and exports it with proper TypeScript typing.\n */\nexport const analyticsManifest: PluginManifest = JSON.parse(\n  readFileSync(join(__dirname, \"manifest.json\"), \"utf-8\"),\n) as PluginManifest;\n"],"mappings":";;;;;AAKA,MAAM,YAAY,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC;;;;;;;;;;;AAYzD,MAAa,oBAAoC,KAAK,MACpD,aAAa,KAAK,WAAW,gBAAgB,EAAE,QAAQ,CACxD"}

package/dist/plugins/analytics/manifest.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://databricks.github.io/appkit/schemas/plugin-manifest.schema.json",
+  "name": "analytics",
+  "displayName": "Analytics Plugin",
+  "description": "SQL query execution against Databricks SQL Warehouses",
+  "resources": {
+    "required": [
+      {
+        "type": "sql_warehouse",
+        "alias": "SQL Warehouse",
+        "resourceKey": "sql-warehouse",
+        "description": "SQL Warehouse for executing analytics queries",
+        "permission": "CAN_USE",
+        "fields": {
+          "id": {
+            "env": "DATABRICKS_WAREHOUSE_ID",
+            "description": "SQL Warehouse ID"
+          }
+        }
+      }
+    ],
+    "optional": []
+  },
+  "config": {
+    "schema": {
+      "type": "object",
+      "properties": {
+        "timeout": {
+          "type": "number",
+          "default": 30000,
+          "description": "Query execution timeout in milliseconds"
+        }
+      }
+    }
+  }
+}

package/dist/plugins/index.js

@@ -1,5 +1,7 @@
+import { analyticsManifest } from "./analytics/manifest.js";
 import { AnalyticsPlugin, analytics } from "./analytics/analytics.js";
 import "./analytics/index.js";
+import { serverManifest } from "./server/manifest.js";
 import { ServerPlugin, server } from "./server/index.js";
 
 export {  };

package/dist/plugins/server/index.d.ts

@@ -1,5 +1,6 @@
 import { PluginPhase, TelemetryOptions, ToPlugin } from "../../shared/src/plugin.js";
 import { Plugin } from "../../plugin/plugin.js";
+import { PluginManifest } from "../../registry/types.js";
 import { ServerConfig } from "./types.js";
 import express from "express";
 import { Server } from "node:http";
@@ -26,8 +27,9 @@ declare class ServerPlugin extends Plugin {
     host: string;
     port: number;
   };
+  /** Plugin manifest declaring metadata and resource requirements */
+  static manifest: PluginManifest;
   name: "server";
-  protected envVars: string[];
   private serverApplication;
   private server;
   private viteDevServer?;

package/dist/plugins/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/plugins/server/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AAkCA;;;;;;;;;;;;AAwDiB,cAxDJ,YAAA,SAAqB,MAAA,CAwDjB;SAsPM,cAAQ,EAAA;IAxMhB,SAAA,EAAA,OAAA;IAAU,IAAA,EAAA,MAAA;IAtGS,IAAA,EAAA,MAAA;EAAM,CAAA;EA+T3B,IAAA,EAAA,QAGZ;EAAA,UAAA,OAAA,EAAA,MAAA,EAAA;UAHkB,iBAAA;UAAA,MAAA;UAAA,aAAA;EAAA,QAAA,sBAAA;oBAlTS;;gBAEZ;sBAEM;;WAaT;;;;;;;;;gBAAA;;;;;;;;;;;;WA0BI,QAAQ,OAAA,CAAQ;;;;;;;;;eA8ClB;;;;;;;;mBAmBI,OAAA,CAAQ;;;;;;;;;;;;;;;;;;;;;;;;iBAjEV,QAAQ,OAAA,CAAQ;;qBAsPV,OAAA,CAAQ;;qBAxMhB;;;;;;;;;kBAAU;;;;;;;cAyNZ,QAAM,gBAAA,cAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/plugins/server/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;AAmCA;;;;;;;;;;;AA2HmB,cA3HN,YAAA,SAAqB,MAAA,CA2HP;SAjEF,cAAQ,EAAA;IAAhB,SAAA,EAAA,OAAA;IAsPM,IAAA,EAAA,MAAQ;IAxMhB,IAAA,EAAA,MAAA;;;EAxGyB,OAAA,QAAA,EAAd,cAAc;EAiU3B,IAAA,EAAA,QAGZ;EAAA,QAAA,iBAAA;UAHkB,MAAA;UAAA,aAAA;UAAA,sBAAA;EAAA,UAAA,MAAA,EAlTS,YAkTT;;gBAhTH;sBAEM;;WAaT;;;;;;;;;gBAAA;;;;;;;;;;;;WA0BI,QAAQ,OAAA,CAAQ;;;;;;;;;eA8ClB;;;;;;;;mBAmBI,OAAA,CAAQ;;;;;;;;;;;;;;;;;;;;;;;;iBAjEV,QAAQ,OAAA,CAAQ;;qBAsPV,OAAA,CAAQ;;qBAxMhB;;;;;;;;;kBAAU;;;;;;;cAyNZ,QAAM,gBAAA,cAAA"}

package/dist/plugins/server/index.js

@@ -1,11 +1,12 @@
-import { instrumentations } from "../../telemetry/instrumentations.js";
 import { createLogger } from "../../logging/logger.js";
-import "../../telemetry/index.js";
 import { ServerError } from "../../errors/server.js";
 import { init_errors } from "../../errors/index.js";
+import { instrumentations } from "../../telemetry/instrumentations.js";
+import "../../telemetry/index.js";
 import { Plugin } from "../../plugin/plugin.js";
 import { toPlugin } from "../../plugin/to-plugin.js";
 import "../../plugin/index.js";
+import { serverManifest } from "./manifest.js";
 import { RemoteTunnelController } from "./remote-tunnel/remote-tunnel-controller.js";
 import { getRoutes } from "./utils.js";
 import { StaticServer } from "./static-server.js";
@@ -39,8 +40,9 @@ var ServerPlugin = class ServerPlugin extends Plugin {
 		host: process.env.FLASK_RUN_HOST || "0.0.0.0",
 		port: Number(process.env.DATABRICKS_APP_PORT) || 8e3
 	};
+	/** Plugin manifest declaring metadata and resource requirements */
+	static manifest = serverManifest;
 	name = "server";
-	envVars = [];
 	serverApplication;
 	server;
 	viteDevServer;

package/dist/plugins/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../src/plugins/server/index.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport type { Server as HTTPServer } from \"node:http\";\nimport path from \"node:path\";\nimport dotenv from \"dotenv\";\nimport express from \"express\";\nimport type { PluginPhase } from \"shared\";\nimport { ServerError } from \"../../errors\";\nimport { createLogger } from \"../../logging/logger\";\nimport { Plugin, toPlugin } from \"../../plugin\";\nimport { instrumentations } from \"../../telemetry\";\nimport { RemoteTunnelController } from \"./remote-tunnel/remote-tunnel-controller\";\nimport { StaticServer } from \"./static-server\";\nimport type { ServerConfig } from \"./types\";\nimport { getRoutes, type PluginEndpoints } from \"./utils\";\nimport { ViteDevServer } from \"./vite-dev-server\";\n\ndotenv.config({ path: path.resolve(process.cwd(), \"./.env\") });\n\nconst logger = createLogger(\"server\");\n\n/**\n * Server plugin for the AppKit.\n *\n * This plugin is responsible for starting the server and serving the static files.\n * It also handles the remote tunneling for development purposes.\n *\n * @example\n * ```ts\n * createApp({\n *   plugins: [server(), telemetryExamples(), analytics({})],\n * });\n * ```\n *\n */\nexport class ServerPlugin extends Plugin {\n  public static DEFAULT_CONFIG = {\n    autoStart: true,\n    host: process.env.FLASK_RUN_HOST || \"0.0.0.0\",\n    port: Number(process.env.DATABRICKS_APP_PORT) || 8000,\n  };\n\n  public name = \"server\" as const;\n  protected envVars: string[] = [];\n  private serverApplication: express.Application;\n  private server: HTTPServer | null;\n  private viteDevServer?: ViteDevServer;\n  private remoteTunnelController?: RemoteTunnelController;\n  protected declare config: ServerConfig;\n  private serverExtensions: ((app: express.Application) => void)[] = [];\n  static phase: PluginPhase = \"deferred\";\n\n  constructor(config: ServerConfig) {\n    super(config);\n    this.config = config;\n    this.serverApplication = express();\n    this.server = null;\n    this.serverExtensions = [];\n    this.telemetry.registerInstrumentations([\n      instrumentations.http,\n      instrumentations.express,\n    ]);\n  }\n\n  /** Setup the server plugin. */\n  async setup() {\n    if (this.shouldAutoStart()) {\n      await this.start();\n    }\n  }\n\n  /** Get the server configuration. */\n  getConfig() {\n    const { plugins: _plugins, ...config } = this.config;\n\n    return config;\n  }\n\n  /** Check if the server should auto start. */\n  shouldAutoStart() {\n    return this.config.autoStart;\n  }\n\n  /**\n   * Start the server.\n   *\n   * This method starts the server and sets up the frontend.\n   * It also sets up the remote tunneling if enabled.\n   *\n   * @returns The express application.\n   */\n  async start(): Promise<express.Application> {\n    this.serverApplication.use(express.json());\n\n    const endpoints = await this.extendRoutes();\n\n    for (const extension of this.serverExtensions) {\n      extension(this.serverApplication);\n    }\n\n    // register remote tunnel controller (before static/vite)\n    this.remoteTunnelController = new RemoteTunnelController(\n      this.devFileReader,\n    );\n    this.serverApplication.use(this.remoteTunnelController.middleware);\n\n    await this.setupFrontend(endpoints);\n\n    const server = this.serverApplication.listen(\n      this.config.port ?? ServerPlugin.DEFAULT_CONFIG.port,\n      this.config.host ?? ServerPlugin.DEFAULT_CONFIG.host,\n      () => this.logStartupInfo(),\n    );\n\n    this.server = server;\n\n    // attach server to remote tunnel controller\n    this.remoteTunnelController.setServer(server);\n\n    process.on(\"SIGTERM\", () => this._gracefulShutdown());\n    process.on(\"SIGINT\", () => this._gracefulShutdown());\n\n    if (process.env.NODE_ENV === \"development\") {\n      const allRoutes = getRoutes(this.serverApplication._router.stack);\n      console.dir(allRoutes, { depth: null });\n    }\n    return this.serverApplication;\n  }\n\n  /**\n   * Get the low level node.js http server instance.\n   *\n   * Only use this method if you need to access the server instance for advanced usage like a custom websocket server, etc.\n   *\n   * @throws {Error} If the server is not started or autoStart is true.\n   * @returns {HTTPServer} The server instance.\n   */\n  getServer(): HTTPServer {\n    if (this.shouldAutoStart()) {\n      throw ServerError.autoStartConflict(\"get server\");\n    }\n\n    if (!this.server) {\n      throw ServerError.notStarted();\n    }\n\n    return this.server;\n  }\n\n  /**\n   * Extend the server with custom routes or middleware.\n   *\n   * @param fn - A function that receives the express application.\n   * @returns The server plugin instance for chaining.\n   * @throws {Error} If autoStart is true.\n   */\n  extend(fn: (app: express.Application) => void) {\n    if (this.shouldAutoStart()) {\n      throw ServerError.autoStartConflict(\"extend server\");\n    }\n\n    this.serverExtensions.push(fn);\n    return this;\n  }\n\n  /**\n   * Setup the routes with the plugins.\n   *\n   * This method goes through all the plugins and injects the routes into the server application.\n   * Returns a map of plugin names to their registered named endpoints.\n   */\n  private async extendRoutes(): Promise<PluginEndpoints> {\n    const endpoints: PluginEndpoints = {};\n\n    if (!this.config.plugins) return endpoints;\n\n    this.serverApplication.get(\"/health\", (_, res) => {\n      res.status(200).json({ status: \"ok\" });\n    });\n    this.registerEndpoint(\"health\", \"/health\");\n\n    for (const plugin of Object.values(this.config.plugins)) {\n      if (EXCLUDED_PLUGINS.includes(plugin.name)) continue;\n\n      if (plugin?.injectRoutes && typeof plugin.injectRoutes === \"function\") {\n        const router = express.Router();\n\n        plugin.injectRoutes(router);\n\n        const basePath = `/api/${plugin.name}`;\n        this.serverApplication.use(basePath, router);\n\n        // Collect named endpoints from the plugin\n        endpoints[plugin.name] = plugin.getEndpoints();\n      }\n    }\n\n    return endpoints;\n  }\n\n  /**\n   * Setup frontend serving based on environment:\n   * - If staticPath is explicitly provided: use static server\n   * - Dev mode (no staticPath): Vite for HMR\n   * - Production (no staticPath): Static files auto-detected\n   */\n  private async setupFrontend(endpoints: PluginEndpoints) {\n    const isDev = process.env.NODE_ENV === \"development\";\n    const hasExplicitStaticPath = this.config.staticPath !== undefined;\n\n    // explict static path provided\n    if (hasExplicitStaticPath) {\n      const staticServer = new StaticServer(\n        this.serverApplication,\n        this.config.staticPath as string,\n        endpoints,\n      );\n      staticServer.setup();\n      return;\n    }\n\n    // auto-detection based on environment\n    if (isDev) {\n      this.viteDevServer = new ViteDevServer(this.serverApplication, endpoints);\n      await this.viteDevServer.setup();\n      return;\n    }\n\n    // auto-detection based on static path\n    const staticPath = ServerPlugin.findStaticPath();\n    if (staticPath) {\n      const staticServer = new StaticServer(\n        this.serverApplication,\n        staticPath,\n        endpoints,\n      );\n\n      staticServer.setup();\n    }\n  }\n\n  private static findStaticPath() {\n    const staticPaths = [\"dist\", \"client/dist\", \"build\", \"public\", \"out\"];\n    const cwd = process.cwd();\n    for (const p of staticPaths) {\n      const fullPath = path.resolve(cwd, p);\n      if (fs.existsSync(path.resolve(fullPath, \"index.html\"))) {\n        logger.debug(\"Static files: serving from %s\", fullPath);\n        return fullPath;\n      }\n    }\n    return undefined;\n  }\n\n  private logStartupInfo() {\n    const isDev = process.env.NODE_ENV === \"development\";\n    const hasExplicitStaticPath = this.config.staticPath !== undefined;\n    const port = this.config.port ?? ServerPlugin.DEFAULT_CONFIG.port;\n    const host = this.config.host ?? ServerPlugin.DEFAULT_CONFIG.host;\n\n    logger.info(\"Server running on http://%s:%d\", host, port);\n\n    if (hasExplicitStaticPath) {\n      logger.info(\"Mode: static (%s)\", this.config.staticPath);\n    } else if (isDev) {\n      logger.info(\"Mode: development (Vite HMR)\");\n    } else {\n      logger.info(\"Mode: production (static)\");\n    }\n\n    const remoteServerController = this.remoteTunnelController;\n    if (!remoteServerController) {\n      logger.debug(\"Remote tunnel: disabled (controller not initialized)\");\n    } else {\n      logger.debug(\n        \"Remote tunnel: %s; %s\",\n        remoteServerController.isAllowedByEnv() ? \"allowed\" : \"blocked\",\n        remoteServerController.isActive() ? \"active\" : \"inactive\",\n      );\n    }\n  }\n\n  private async _gracefulShutdown() {\n    logger.info(\"Starting graceful shutdown...\");\n\n    if (this.viteDevServer) {\n      await this.viteDevServer.close();\n    }\n\n    if (this.remoteTunnelController) {\n      this.remoteTunnelController.cleanup();\n    }\n\n    // 1. abort active operations from plugins\n    if (this.config.plugins) {\n      for (const plugin of Object.values(this.config.plugins)) {\n        if (plugin.abortActiveOperations) {\n          try {\n            plugin.abortActiveOperations();\n          } catch (err) {\n            logger.error(\n              \"Error aborting operations for plugin %s: %O\",\n              plugin.name,\n              err,\n            );\n          }\n        }\n      }\n    }\n\n    // 2. close the server\n    if (this.server) {\n      this.server.close(() => {\n        logger.debug(\"Server closed gracefully\");\n        process.exit(0);\n      });\n\n      // 3. timeout to force shutdown after 15 seconds\n      setTimeout(() => {\n        logger.debug(\"Force shutdown after timeout\");\n        process.exit(1);\n      }, 15000);\n    } else {\n      process.exit(0);\n    }\n  }\n\n  /**\n   * Returns the public exports for the server plugin.\n   * Exposes server management methods.\n   */\n  exports() {\n    const self = this;\n    return {\n      /** Start the server */\n      start: this.start,\n      /** Extend the server with custom routes or middleware */\n      extend(fn: (app: express.Application) => void) {\n        self.extend(fn);\n        return this;\n      },\n      /** Get the underlying HTTP server instance */\n      getServer: this.getServer,\n      /** Get the server configuration */\n      getConfig: this.getConfig,\n    };\n  }\n}\n\nconst EXCLUDED_PLUGINS = [ServerPlugin.name];\n\n/**\n * @internal\n */\nexport const server = toPlugin<typeof ServerPlugin, ServerConfig, \"server\">(\n  ServerPlugin,\n  \"server\",\n);\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/plugins/server/index.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport type { Server as HTTPServer } from \"node:http\";\nimport path from \"node:path\";\nimport dotenv from \"dotenv\";\nimport express from \"express\";\nimport type { PluginPhase } from \"shared\";\nimport { ServerError } from \"../../errors\";\nimport { createLogger } from \"../../logging/logger\";\nimport { Plugin, toPlugin } from \"../../plugin\";\nimport { instrumentations } from \"../../telemetry\";\nimport { serverManifest } from \"./manifest\";\nimport { RemoteTunnelController } from \"./remote-tunnel/remote-tunnel-controller\";\nimport { StaticServer } from \"./static-server\";\nimport type { ServerConfig } from \"./types\";\nimport { getRoutes, type PluginEndpoints } from \"./utils\";\nimport { ViteDevServer } from \"./vite-dev-server\";\n\ndotenv.config({ path: path.resolve(process.cwd(), \"./.env\") });\n\nconst logger = createLogger(\"server\");\n\n/**\n * Server plugin for the AppKit.\n *\n * This plugin is responsible for starting the server and serving the static files.\n * It also handles the remote tunneling for development purposes.\n *\n * @example\n * ```ts\n * createApp({\n *   plugins: [server(), telemetryExamples(), analytics({})],\n * });\n * ```\n *\n */\nexport class ServerPlugin extends Plugin {\n  public static DEFAULT_CONFIG = {\n    autoStart: true,\n    host: process.env.FLASK_RUN_HOST || \"0.0.0.0\",\n    port: Number(process.env.DATABRICKS_APP_PORT) || 8000,\n  };\n\n  /** Plugin manifest declaring metadata and resource requirements */\n  static manifest = serverManifest;\n\n  public name = \"server\" as const;\n  private serverApplication: express.Application;\n  private server: HTTPServer | null;\n  private viteDevServer?: ViteDevServer;\n  private remoteTunnelController?: RemoteTunnelController;\n  protected declare config: ServerConfig;\n  private serverExtensions: ((app: express.Application) => void)[] = [];\n  static phase: PluginPhase = \"deferred\";\n\n  constructor(config: ServerConfig) {\n    super(config);\n    this.config = config;\n    this.serverApplication = express();\n    this.server = null;\n    this.serverExtensions = [];\n    this.telemetry.registerInstrumentations([\n      instrumentations.http,\n      instrumentations.express,\n    ]);\n  }\n\n  /** Setup the server plugin. */\n  async setup() {\n    if (this.shouldAutoStart()) {\n      await this.start();\n    }\n  }\n\n  /** Get the server configuration. */\n  getConfig() {\n    const { plugins: _plugins, ...config } = this.config;\n\n    return config;\n  }\n\n  /** Check if the server should auto start. */\n  shouldAutoStart() {\n    return this.config.autoStart;\n  }\n\n  /**\n   * Start the server.\n   *\n   * This method starts the server and sets up the frontend.\n   * It also sets up the remote tunneling if enabled.\n   *\n   * @returns The express application.\n   */\n  async start(): Promise<express.Application> {\n    this.serverApplication.use(express.json());\n\n    const endpoints = await this.extendRoutes();\n\n    for (const extension of this.serverExtensions) {\n      extension(this.serverApplication);\n    }\n\n    // register remote tunnel controller (before static/vite)\n    this.remoteTunnelController = new RemoteTunnelController(\n      this.devFileReader,\n    );\n    this.serverApplication.use(this.remoteTunnelController.middleware);\n\n    await this.setupFrontend(endpoints);\n\n    const server = this.serverApplication.listen(\n      this.config.port ?? ServerPlugin.DEFAULT_CONFIG.port,\n      this.config.host ?? ServerPlugin.DEFAULT_CONFIG.host,\n      () => this.logStartupInfo(),\n    );\n\n    this.server = server;\n\n    // attach server to remote tunnel controller\n    this.remoteTunnelController.setServer(server);\n\n    process.on(\"SIGTERM\", () => this._gracefulShutdown());\n    process.on(\"SIGINT\", () => this._gracefulShutdown());\n\n    if (process.env.NODE_ENV === \"development\") {\n      const allRoutes = getRoutes(this.serverApplication._router.stack);\n      console.dir(allRoutes, { depth: null });\n    }\n    return this.serverApplication;\n  }\n\n  /**\n   * Get the low level node.js http server instance.\n   *\n   * Only use this method if you need to access the server instance for advanced usage like a custom websocket server, etc.\n   *\n   * @throws {Error} If the server is not started or autoStart is true.\n   * @returns {HTTPServer} The server instance.\n   */\n  getServer(): HTTPServer {\n    if (this.shouldAutoStart()) {\n      throw ServerError.autoStartConflict(\"get server\");\n    }\n\n    if (!this.server) {\n      throw ServerError.notStarted();\n    }\n\n    return this.server;\n  }\n\n  /**\n   * Extend the server with custom routes or middleware.\n   *\n   * @param fn - A function that receives the express application.\n   * @returns The server plugin instance for chaining.\n   * @throws {Error} If autoStart is true.\n   */\n  extend(fn: (app: express.Application) => void) {\n    if (this.shouldAutoStart()) {\n      throw ServerError.autoStartConflict(\"extend server\");\n    }\n\n    this.serverExtensions.push(fn);\n    return this;\n  }\n\n  /**\n   * Setup the routes with the plugins.\n   *\n   * This method goes through all the plugins and injects the routes into the server application.\n   * Returns a map of plugin names to their registered named endpoints.\n   */\n  private async extendRoutes(): Promise<PluginEndpoints> {\n    const endpoints: PluginEndpoints = {};\n\n    if (!this.config.plugins) return endpoints;\n\n    this.serverApplication.get(\"/health\", (_, res) => {\n      res.status(200).json({ status: \"ok\" });\n    });\n    this.registerEndpoint(\"health\", \"/health\");\n\n    for (const plugin of Object.values(this.config.plugins)) {\n      if (EXCLUDED_PLUGINS.includes(plugin.name)) continue;\n\n      if (plugin?.injectRoutes && typeof plugin.injectRoutes === \"function\") {\n        const router = express.Router();\n\n        plugin.injectRoutes(router);\n\n        const basePath = `/api/${plugin.name}`;\n        this.serverApplication.use(basePath, router);\n\n        // Collect named endpoints from the plugin\n        endpoints[plugin.name] = plugin.getEndpoints();\n      }\n    }\n\n    return endpoints;\n  }\n\n  /**\n   * Setup frontend serving based on environment:\n   * - If staticPath is explicitly provided: use static server\n   * - Dev mode (no staticPath): Vite for HMR\n   * - Production (no staticPath): Static files auto-detected\n   */\n  private async setupFrontend(endpoints: PluginEndpoints) {\n    const isDev = process.env.NODE_ENV === \"development\";\n    const hasExplicitStaticPath = this.config.staticPath !== undefined;\n\n    // explict static path provided\n    if (hasExplicitStaticPath) {\n      const staticServer = new StaticServer(\n        this.serverApplication,\n        this.config.staticPath as string,\n        endpoints,\n      );\n      staticServer.setup();\n      return;\n    }\n\n    // auto-detection based on environment\n    if (isDev) {\n      this.viteDevServer = new ViteDevServer(this.serverApplication, endpoints);\n      await this.viteDevServer.setup();\n      return;\n    }\n\n    // auto-detection based on static path\n    const staticPath = ServerPlugin.findStaticPath();\n    if (staticPath) {\n      const staticServer = new StaticServer(\n        this.serverApplication,\n        staticPath,\n        endpoints,\n      );\n\n      staticServer.setup();\n    }\n  }\n\n  private static findStaticPath() {\n    const staticPaths = [\"dist\", \"client/dist\", \"build\", \"public\", \"out\"];\n    const cwd = process.cwd();\n    for (const p of staticPaths) {\n      const fullPath = path.resolve(cwd, p);\n      if (fs.existsSync(path.resolve(fullPath, \"index.html\"))) {\n        logger.debug(\"Static files: serving from %s\", fullPath);\n        return fullPath;\n      }\n    }\n    return undefined;\n  }\n\n  private logStartupInfo() {\n    const isDev = process.env.NODE_ENV === \"development\";\n    const hasExplicitStaticPath = this.config.staticPath !== undefined;\n    const port = this.config.port ?? ServerPlugin.DEFAULT_CONFIG.port;\n    const host = this.config.host ?? ServerPlugin.DEFAULT_CONFIG.host;\n\n    logger.info(\"Server running on http://%s:%d\", host, port);\n\n    if (hasExplicitStaticPath) {\n      logger.info(\"Mode: static (%s)\", this.config.staticPath);\n    } else if (isDev) {\n      logger.info(\"Mode: development (Vite HMR)\");\n    } else {\n      logger.info(\"Mode: production (static)\");\n    }\n\n    const remoteServerController = this.remoteTunnelController;\n    if (!remoteServerController) {\n      logger.debug(\"Remote tunnel: disabled (controller not initialized)\");\n    } else {\n      logger.debug(\n        \"Remote tunnel: %s; %s\",\n        remoteServerController.isAllowedByEnv() ? \"allowed\" : \"blocked\",\n        remoteServerController.isActive() ? \"active\" : \"inactive\",\n      );\n    }\n  }\n\n  private async _gracefulShutdown() {\n    logger.info(\"Starting graceful shutdown...\");\n\n    if (this.viteDevServer) {\n      await this.viteDevServer.close();\n    }\n\n    if (this.remoteTunnelController) {\n      this.remoteTunnelController.cleanup();\n    }\n\n    // 1. abort active operations from plugins\n    if (this.config.plugins) {\n      for (const plugin of Object.values(this.config.plugins)) {\n        if (plugin.abortActiveOperations) {\n          try {\n            plugin.abortActiveOperations();\n          } catch (err) {\n            logger.error(\n              \"Error aborting operations for plugin %s: %O\",\n              plugin.name,\n              err,\n            );\n          }\n        }\n      }\n    }\n\n    // 2. close the server\n    if (this.server) {\n      this.server.close(() => {\n        logger.debug(\"Server closed gracefully\");\n        process.exit(0);\n      });\n\n      // 3. timeout to force shutdown after 15 seconds\n      setTimeout(() => {\n        logger.debug(\"Force shutdown after timeout\");\n        process.exit(1);\n      }, 15000);\n    } else {\n      process.exit(0);\n    }\n  }\n\n  /**\n   * Returns the public exports for the server plugin.\n   * Exposes server management methods.\n   */\n  exports() {\n    const self = this;\n    return {\n      /** Start the server */\n      start: this.start,\n      /** Extend the server with custom routes or middleware */\n      extend(fn: (app: express.Application) => void) {\n        self.extend(fn);\n        return this;\n      },\n      /** Get the underlying HTTP server instance */\n      getServer: this.getServer,\n      /** Get the server configuration */\n      getConfig: this.getConfig,\n    };\n  }\n}\n\nconst EXCLUDED_PLUGINS = [ServerPlugin.name];\n\n/**\n * @internal\n */\nexport const server = toPlugin<typeof ServerPlugin, ServerConfig, \"server\">(\n  ServerPlugin,\n  \"server\",\n);\n\n// Export manifest and types\nexport { serverManifest } from \"./manifest\";\nexport type { ServerConfig } from \"./types\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;aAM2C;AAW3C,OAAO,OAAO,EAAE,MAAM,KAAK,QAAQ,QAAQ,KAAK,EAAE,SAAS,EAAE,CAAC;AAE9D,MAAM,SAAS,aAAa,SAAS;;;;;;;;;;;;;;;AAgBrC,IAAa,eAAb,MAAa,qBAAqB,OAAO;CACvC,OAAc,iBAAiB;EAC7B,WAAW;EACX,MAAM,QAAQ,IAAI,kBAAkB;EACpC,MAAM,OAAO,QAAQ,IAAI,oBAAoB,IAAI;EAClD;;CAGD,OAAO,WAAW;CAElB,AAAO,OAAO;CACd,AAAQ;CACR,AAAQ;CACR,AAAQ;CACR,AAAQ;CAER,AAAQ,mBAA2D,EAAE;CACrE,OAAO,QAAqB;CAE5B,YAAY,QAAsB;AAChC,QAAM,OAAO;AACb,OAAK,SAAS;AACd,OAAK,oBAAoB,SAAS;AAClC,OAAK,SAAS;AACd,OAAK,mBAAmB,EAAE;AAC1B,OAAK,UAAU,yBAAyB,CACtC,iBAAiB,MACjB,iBAAiB,QAClB,CAAC;;;CAIJ,MAAM,QAAQ;AACZ,MAAI,KAAK,iBAAiB,CACxB,OAAM,KAAK,OAAO;;;CAKtB,YAAY;EACV,MAAM,EAAE,SAAS,UAAU,GAAG,WAAW,KAAK;AAE9C,SAAO;;;CAIT,kBAAkB;AAChB,SAAO,KAAK,OAAO;;;;;;;;;;CAWrB,MAAM,QAAsC;AAC1C,OAAK,kBAAkB,IAAI,QAAQ,MAAM,CAAC;EAE1C,MAAM,YAAY,MAAM,KAAK,cAAc;AAE3C,OAAK,MAAM,aAAa,KAAK,iBAC3B,WAAU,KAAK,kBAAkB;AAInC,OAAK,yBAAyB,IAAI,uBAChC,KAAK,cACN;AACD,OAAK,kBAAkB,IAAI,KAAK,uBAAuB,WAAW;AAElE,QAAM,KAAK,cAAc,UAAU;EAEnC,MAAM,SAAS,KAAK,kBAAkB,OACpC,KAAK,OAAO,QAAQ,aAAa,eAAe,MAChD,KAAK,OAAO,QAAQ,aAAa,eAAe,YAC1C,KAAK,gBAAgB,CAC5B;AAED,OAAK,SAAS;AAGd,OAAK,uBAAuB,UAAU,OAAO;AAE7C,UAAQ,GAAG,iBAAiB,KAAK,mBAAmB,CAAC;AACrD,UAAQ,GAAG,gBAAgB,KAAK,mBAAmB,CAAC;AAEpD,MAAI,QAAQ,IAAI,aAAa,eAAe;GAC1C,MAAM,YAAY,UAAU,KAAK,kBAAkB,QAAQ,MAAM;AACjE,WAAQ,IAAI,WAAW,EAAE,OAAO,MAAM,CAAC;;AAEzC,SAAO,KAAK;;;;;;;;;;CAWd,YAAwB;AACtB,MAAI,KAAK,iBAAiB,CACxB,OAAM,YAAY,kBAAkB,aAAa;AAGnD,MAAI,CAAC,KAAK,OACR,OAAM,YAAY,YAAY;AAGhC,SAAO,KAAK;;;;;;;;;CAUd,OAAO,IAAwC;AAC7C,MAAI,KAAK,iBAAiB,CACxB,OAAM,YAAY,kBAAkB,gBAAgB;AAGtD,OAAK,iBAAiB,KAAK,GAAG;AAC9B,SAAO;;;;;;;;CAST,MAAc,eAAyC;EACrD,MAAM,YAA6B,EAAE;AAErC,MAAI,CAAC,KAAK,OAAO,QAAS,QAAO;AAEjC,OAAK,kBAAkB,IAAI,YAAY,GAAG,QAAQ;AAChD,OAAI,OAAO,IAAI,CAAC,KAAK,EAAE,QAAQ,MAAM,CAAC;IACtC;AACF,OAAK,iBAAiB,UAAU,UAAU;AAE1C,OAAK,MAAM,UAAU,OAAO,OAAO,KAAK,OAAO,QAAQ,EAAE;AACvD,OAAI,iBAAiB,SAAS,OAAO,KAAK,CAAE;AAE5C,OAAI,QAAQ,gBAAgB,OAAO,OAAO,iBAAiB,YAAY;IACrE,MAAM,SAAS,QAAQ,QAAQ;AAE/B,WAAO,aAAa,OAAO;IAE3B,MAAM,WAAW,QAAQ,OAAO;AAChC,SAAK,kBAAkB,IAAI,UAAU,OAAO;AAG5C,cAAU,OAAO,QAAQ,OAAO,cAAc;;;AAIlD,SAAO;;;;;;;;CAST,MAAc,cAAc,WAA4B;EACtD,MAAM,QAAQ,QAAQ,IAAI,aAAa;AAIvC,MAH8B,KAAK,OAAO,eAAe,QAG9B;AAMzB,GALqB,IAAI,aACvB,KAAK,mBACL,KAAK,OAAO,YACZ,UACD,CACY,OAAO;AACpB;;AAIF,MAAI,OAAO;AACT,QAAK,gBAAgB,IAAI,cAAc,KAAK,mBAAmB,UAAU;AACzE,SAAM,KAAK,cAAc,OAAO;AAChC;;EAIF,MAAM,aAAa,aAAa,gBAAgB;AAChD,MAAI,WAOF,CANqB,IAAI,aACvB,KAAK,mBACL,YACA,UACD,CAEY,OAAO;;CAIxB,OAAe,iBAAiB;EAC9B,MAAM,cAAc;GAAC;GAAQ;GAAe;GAAS;GAAU;GAAM;EACrE,MAAM,MAAM,QAAQ,KAAK;AACzB,OAAK,MAAM,KAAK,aAAa;GAC3B,MAAM,WAAW,KAAK,QAAQ,KAAK,EAAE;AACrC,OAAI,GAAG,WAAW,KAAK,QAAQ,UAAU,aAAa,CAAC,EAAE;AACvD,WAAO,MAAM,iCAAiC,SAAS;AACvD,WAAO;;;;CAMb,AAAQ,iBAAiB;EACvB,MAAM,QAAQ,QAAQ,IAAI,aAAa;EACvC,MAAM,wBAAwB,KAAK,OAAO,eAAe;EACzD,MAAM,OAAO,KAAK,OAAO,QAAQ,aAAa,eAAe;EAC7D,MAAM,OAAO,KAAK,OAAO,QAAQ,aAAa,eAAe;AAE7D,SAAO,KAAK,kCAAkC,MAAM,KAAK;AAEzD,MAAI,sBACF,QAAO,KAAK,qBAAqB,KAAK,OAAO,WAAW;WAC/C,MACT,QAAO,KAAK,+BAA+B;MAE3C,QAAO,KAAK,4BAA4B;EAG1C,MAAM,yBAAyB,KAAK;AACpC,MAAI,CAAC,uBACH,QAAO,MAAM,uDAAuD;MAEpE,QAAO,MACL,yBACA,uBAAuB,gBAAgB,GAAG,YAAY,WACtD,uBAAuB,UAAU,GAAG,WAAW,WAChD;;CAIL,MAAc,oBAAoB;AAChC,SAAO,KAAK,gCAAgC;AAE5C,MAAI,KAAK,cACP,OAAM,KAAK,cAAc,OAAO;AAGlC,MAAI,KAAK,uBACP,MAAK,uBAAuB,SAAS;AAIvC,MAAI,KAAK,OAAO,SACd;QAAK,MAAM,UAAU,OAAO,OAAO,KAAK,OAAO,QAAQ,CACrD,KAAI,OAAO,sBACT,KAAI;AACF,WAAO,uBAAuB;YACvB,KAAK;AACZ,WAAO,MACL,+CACA,OAAO,MACP,IACD;;;AAOT,MAAI,KAAK,QAAQ;AACf,QAAK,OAAO,YAAY;AACtB,WAAO,MAAM,2BAA2B;AACxC,YAAQ,KAAK,EAAE;KACf;AAGF,oBAAiB;AACf,WAAO,MAAM,+BAA+B;AAC5C,YAAQ,KAAK,EAAE;MACd,KAAM;QAET,SAAQ,KAAK,EAAE;;;;;;CAQnB,UAAU;EACR,MAAM,OAAO;AACb,SAAO;GAEL,OAAO,KAAK;GAEZ,OAAO,IAAwC;AAC7C,SAAK,OAAO,GAAG;AACf,WAAO;;GAGT,WAAW,KAAK;GAEhB,WAAW,KAAK;GACjB;;;AAIL,MAAM,mBAAmB,CAAC,aAAa,KAAK;;;;AAK5C,MAAa,SAAS,SACpB,cACA,SACD"}

package/dist/plugins/server/manifest.js

@@ -0,0 +1,21 @@
+import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+//#region src/plugins/server/manifest.ts
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+* Server plugin manifest.
+*
+* The server plugin doesn't require any Databricks resources - it only
+* provides HTTP server functionality and static file serving.
+*
+* @remarks
+* The source of truth for this manifest is `manifest.json` in the same directory.
+* This file loads the JSON and exports it with proper TypeScript typing.
+*/
+const serverManifest = JSON.parse(readFileSync(join(__dirname, "manifest.json"), "utf-8"));
+
+//#endregion
+export { serverManifest };
+//# sourceMappingURL=manifest.js.map

package/dist/plugins/server/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","names":[],"sources":["../../../src/plugins/server/manifest.ts"],"sourcesContent":["import { readFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport type { PluginManifest } from \"../../registry\";\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\n\n/**\n * Server plugin manifest.\n *\n * The server plugin doesn't require any Databricks resources - it only\n * provides HTTP server functionality and static file serving.\n *\n * @remarks\n * The source of truth for this manifest is `manifest.json` in the same directory.\n * This file loads the JSON and exports it with proper TypeScript typing.\n */\nexport const serverManifest: PluginManifest = JSON.parse(\n  readFileSync(join(__dirname, \"manifest.json\"), \"utf-8\"),\n) as PluginManifest;\n"],"mappings":";;;;;AAKA,MAAM,YAAY,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC;;;;;;;;;;;AAYzD,MAAa,iBAAiC,KAAK,MACjD,aAAa,KAAK,WAAW,gBAAgB,EAAE,QAAQ,CACxD"}

package/dist/plugins/server/manifest.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://databricks.github.io/appkit/schemas/plugin-manifest.schema.json",
+  "name": "server",
+  "displayName": "Server Plugin",
+  "description": "HTTP server with Express, static file serving, and Vite dev mode support",
+  "resources": {
+    "required": [],
+    "optional": []
+  },
+  "config": {
+    "schema": {
+      "type": "object",
+      "properties": {
+        "autoStart": {
+          "type": "boolean",
+          "default": true,
+          "description": "Automatically start the server on plugin setup"
+        },
+        "host": {
+          "type": "string",
+          "default": "0.0.0.0",
+          "description": "Host address to bind the server to"
+        },
+        "port": {
+          "type": "number",
+          "default": 8000,
+          "description": "Port number for the server"
+        },
+        "staticPath": {
+          "type": "string",
+          "description": "Path to static files directory (auto-detected if not provided)"
+        }
+      }
+    }
+  }
+}

package/dist/registry/index.js

@@ -0,0 +1,5 @@
+import { PERMISSIONS_BY_TYPE, PERMISSION_HIERARCHY_BY_TYPE, ResourceType } from "./types.js";
+import { getPluginManifest, getResourceRequirements } from "./manifest-loader.js";
+import { ResourceRegistry } from "./resource-registry.js";
+
+export {  };

package/dist/registry/manifest-loader.d.ts

@@ -0,0 +1,44 @@
+import { PluginConstructor } from "../shared/src/plugin.js";
+import { PluginManifest, ResourceFieldEntry, ResourcePermission, ResourceType } from "./types.js";
+
+//#region src/registry/manifest-loader.d.ts
+
+/**
+ * Loads and validates the manifest from a plugin constructor.
+ * Normalizes string type/permission to strict ResourceType/ResourcePermission.
+ *
+ * @param plugin - The plugin constructor class
+ * @returns The validated, normalized plugin manifest
+ * @throws {ConfigurationError} If the manifest is missing, invalid, or has invalid resource type/permission
+ */
+declare function getPluginManifest(plugin: PluginConstructor): PluginManifest;
+/**
+ * Gets the resource requirements from a plugin's manifest.
+ *
+ * Combines required and optional resources into a single array with the
+ * `required` flag set appropriately.
+ *
+ * @param plugin - The plugin constructor class
+ * @returns Combined array of required and optional resources
+ * @throws {ConfigurationError} If the plugin manifest is missing or invalid
+ *
+ * @example
+ * ```typescript
+ * const resources = getResourceRequirements(AnalyticsPlugin);
+ * for (const resource of resources) {
+ *   console.log(`${resource.type}: ${resource.description} (required: ${resource.required})`);
+ * }
+ * ```
+ */
+declare function getResourceRequirements(plugin: PluginConstructor): {
+  required: boolean;
+  type: ResourceType;
+  alias: string;
+  resourceKey: string;
+  description: string;
+  permission: ResourcePermission;
+  fields: Record<string, ResourceFieldEntry>;
+}[];
+//#endregion
+export { getPluginManifest, getResourceRequirements };
+//# sourceMappingURL=manifest-loader.d.ts.map

package/dist/registry/manifest-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-loader.d.ts","names":[],"sources":["../../src/registry/manifest-loader.ts"],"sourcesContent":[],"mappings":";;;;;;AA4DA;;;;;AA4FA;;AAAgD,iBA5FhC,iBAAA,CA4FgC,MAAA,EA5FN,iBA4FM,CAAA,EA5Fc,cA4Fd;;;;;;;;;;;;;;;;;;;iBAAhC,uBAAA,SAAgC"}

package/dist/registry/manifest-loader.js

@@ -0,0 +1,97 @@
+import { createLogger } from "../logging/logger.js";
+import { ConfigurationError } from "../errors/configuration.js";
+import { init_errors } from "../errors/index.js";
+import { PERMISSIONS_BY_TYPE, ResourceType } from "./types.js";
+
+//#region src/registry/manifest-loader.ts
+init_errors();
+const logger = createLogger("manifest-loader");
+function normalizeType(s) {
+	const v = Object.values(ResourceType).find((x) => x === s);
+	if (v !== void 0) return v;
+	throw new ConfigurationError(`Invalid resource type: "${s}". Valid: ${Object.values(ResourceType).join(", ")}`);
+}
+function normalizePermission(type, s) {
+	const allowed = PERMISSIONS_BY_TYPE[type];
+	if (allowed.includes(s)) return s;
+	throw new ConfigurationError(`Invalid permission "${s}" for type ${type}. Valid: ${allowed.join(", ")}`);
+}
+function normalizeResource(r) {
+	const type = normalizeType(r.type);
+	const permission = normalizePermission(type, r.permission);
+	return {
+		...r,
+		type,
+		permission,
+		required: false
+	};
+}
+/**
+* Loads and validates the manifest from a plugin constructor.
+* Normalizes string type/permission to strict ResourceType/ResourcePermission.
+*
+* @param plugin - The plugin constructor class
+* @returns The validated, normalized plugin manifest
+* @throws {ConfigurationError} If the manifest is missing, invalid, or has invalid resource type/permission
+*/
+function getPluginManifest(plugin) {
+	const pluginName = plugin.name || "unknown";
+	if (!plugin.manifest) throw new ConfigurationError(`Plugin ${pluginName} is missing a manifest. All plugins must declare a static manifest property.`);
+	const raw = plugin.manifest;
+	if (!raw.name || typeof raw.name !== "string") throw new ConfigurationError(`Plugin ${pluginName} manifest has missing or invalid 'name' field`);
+	if (!raw.displayName || typeof raw.displayName !== "string") throw new ConfigurationError(`Plugin ${raw.name} manifest has missing or invalid 'displayName' field`);
+	if (!raw.description || typeof raw.description !== "string") throw new ConfigurationError(`Plugin ${raw.name} manifest has missing or invalid 'description' field`);
+	if (!raw.resources) throw new ConfigurationError(`Plugin ${raw.name} manifest is missing 'resources' field`);
+	if (!Array.isArray(raw.resources.required)) throw new ConfigurationError(`Plugin ${raw.name} manifest has invalid 'resources.required' field (expected array)`);
+	if (raw.resources.optional !== void 0 && !Array.isArray(raw.resources.optional)) throw new ConfigurationError(`Plugin ${raw.name} manifest has invalid 'resources.optional' field (expected array)`);
+	const required = raw.resources.required.map((r) => {
+		const { required: _, ...rest } = normalizeResource(r);
+		return rest;
+	});
+	const optional = (raw.resources.optional || []).map((r) => {
+		const { required: _, ...rest } = normalizeResource(r);
+		return rest;
+	});
+	logger.debug("Loaded manifest for plugin %s: %d required resources, %d optional resources", raw.name, required.length, optional.length);
+	return {
+		...raw,
+		resources: {
+			required,
+			optional
+		}
+	};
+}
+/**
+* Gets the resource requirements from a plugin's manifest.
+*
+* Combines required and optional resources into a single array with the
+* `required` flag set appropriately.
+*
+* @param plugin - The plugin constructor class
+* @returns Combined array of required and optional resources
+* @throws {ConfigurationError} If the plugin manifest is missing or invalid
+*
+* @example
+* ```typescript
+* const resources = getResourceRequirements(AnalyticsPlugin);
+* for (const resource of resources) {
+*   console.log(`${resource.type}: ${resource.description} (required: ${resource.required})`);
+* }
+* ```
+*/
+function getResourceRequirements(plugin) {
+	const manifest = getPluginManifest(plugin);
+	const required = manifest.resources.required.map((r) => ({
+		...r,
+		required: true
+	}));
+	const optional = (manifest.resources.optional || []).map((r) => ({
+		...r,
+		required: false
+	}));
+	return [...required, ...optional];
+}
+
+//#endregion
+export { getPluginManifest, getResourceRequirements };
+//# sourceMappingURL=manifest-loader.js.map

package/dist/registry/manifest-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-loader.js","names":[],"sources":["../../src/registry/manifest-loader.ts"],"sourcesContent":["import type { PluginConstructor } from \"shared\";\nimport { ConfigurationError } from \"../errors\";\nimport { createLogger } from \"../logging/logger\";\nimport type {\n  PluginManifest,\n  ResourcePermission,\n  ResourceRequirement,\n} from \"./types\";\nimport { PERMISSIONS_BY_TYPE, ResourceType } from \"./types\";\n\nconst logger = createLogger(\"manifest-loader\");\n\n/** Loose resource from shared/manifest (string type and permission). */\ninterface LooseResource {\n  type: string;\n  alias: string;\n  resourceKey: string;\n  description: string;\n  permission: string;\n  fields: Record<string, { env: string; description?: string }>;\n}\n\nfunction normalizeType(s: string): ResourceType {\n  const v = Object.values(ResourceType).find((x) => x === s);\n  if (v !== undefined) return v;\n  throw new ConfigurationError(\n    `Invalid resource type: \"${s}\". Valid: ${Object.values(ResourceType).join(\", \")}`,\n  );\n}\n\nfunction normalizePermission(\n  type: ResourceType,\n  s: string,\n): ResourcePermission {\n  const allowed = PERMISSIONS_BY_TYPE[type];\n  if (allowed.includes(s as ResourcePermission)) return s as ResourcePermission;\n  throw new ConfigurationError(\n    `Invalid permission \"${s}\" for type ${type}. Valid: ${allowed.join(\", \")}`,\n  );\n}\n\nfunction normalizeResource(r: LooseResource): ResourceRequirement {\n  const type = normalizeType(r.type);\n  const permission = normalizePermission(type, r.permission);\n  return {\n    ...r,\n    type,\n    permission,\n    required: false,\n  };\n}\n\n/**\n * Loads and validates the manifest from a plugin constructor.\n * Normalizes string type/permission to strict ResourceType/ResourcePermission.\n *\n * @param plugin - The plugin constructor class\n * @returns The validated, normalized plugin manifest\n * @throws {ConfigurationError} If the manifest is missing, invalid, or has invalid resource type/permission\n */\nexport function getPluginManifest(plugin: PluginConstructor): PluginManifest {\n  const pluginName = plugin.name || \"unknown\";\n\n  if (!plugin.manifest) {\n    throw new ConfigurationError(\n      `Plugin ${pluginName} is missing a manifest. All plugins must declare a static manifest property.`,\n    );\n  }\n\n  const raw = plugin.manifest;\n\n  if (!raw.name || typeof raw.name !== \"string\") {\n    throw new ConfigurationError(\n      `Plugin ${pluginName} manifest has missing or invalid 'name' field`,\n    );\n  }\n\n  if (!raw.displayName || typeof raw.displayName !== \"string\") {\n    throw new ConfigurationError(\n      `Plugin ${raw.name} manifest has missing or invalid 'displayName' field`,\n    );\n  }\n\n  if (!raw.description || typeof raw.description !== \"string\") {\n    throw new ConfigurationError(\n      `Plugin ${raw.name} manifest has missing or invalid 'description' field`,\n    );\n  }\n\n  if (!raw.resources) {\n    throw new ConfigurationError(\n      `Plugin ${raw.name} manifest is missing 'resources' field`,\n    );\n  }\n\n  if (!Array.isArray(raw.resources.required)) {\n    throw new ConfigurationError(\n      `Plugin ${raw.name} manifest has invalid 'resources.required' field (expected array)`,\n    );\n  }\n\n  if (\n    raw.resources.optional !== undefined &&\n    !Array.isArray(raw.resources.optional)\n  ) {\n    throw new ConfigurationError(\n      `Plugin ${raw.name} manifest has invalid 'resources.optional' field (expected array)`,\n    );\n  }\n\n  const required = raw.resources.required.map((r) => {\n    const norm = normalizeResource(r as LooseResource);\n    const { required: _, ...rest } = norm;\n    return rest;\n  });\n  const optional = (raw.resources.optional || []).map((r) => {\n    const norm = normalizeResource(r as LooseResource);\n    const { required: _, ...rest } = norm;\n    return rest;\n  });\n\n  logger.debug(\n    \"Loaded manifest for plugin %s: %d required resources, %d optional resources\",\n    raw.name,\n    required.length,\n    optional.length,\n  );\n\n  return {\n    ...raw,\n    resources: { required, optional },\n  };\n}\n\n/**\n * Gets the resource requirements from a plugin's manifest.\n *\n * Combines required and optional resources into a single array with the\n * `required` flag set appropriately.\n *\n * @param plugin - The plugin constructor class\n * @returns Combined array of required and optional resources\n * @throws {ConfigurationError} If the plugin manifest is missing or invalid\n *\n * @example\n * ```typescript\n * const resources = getResourceRequirements(AnalyticsPlugin);\n * for (const resource of resources) {\n *   console.log(`${resource.type}: ${resource.description} (required: ${resource.required})`);\n * }\n * ```\n */\nexport function getResourceRequirements(plugin: PluginConstructor) {\n  const manifest = getPluginManifest(plugin);\n\n  const required = manifest.resources.required.map((r) => ({\n    ...r,\n    required: true,\n  }));\n  const optional = (manifest.resources.optional || []).map((r) => ({\n    ...r,\n    required: false,\n  }));\n\n  return [...required, ...optional];\n}\n\n/**\n * Validates a manifest object structure.\n *\n * @param manifest - The manifest object to validate\n * @returns true if the manifest is valid, false otherwise\n *\n * @internal\n */\nexport function isValidManifest(manifest: unknown): manifest is PluginManifest {\n  if (!manifest || typeof manifest !== \"object\") {\n    return false;\n  }\n\n  const m = manifest as Record<string, unknown>;\n\n  // Check required fields\n  if (typeof m.name !== \"string\") return false;\n  if (typeof m.displayName !== \"string\") return false;\n  if (typeof m.description !== \"string\") return false;\n\n  // Check resources structure\n  if (!m.resources || typeof m.resources !== \"object\") return false;\n\n  const resources = m.resources as Record<string, unknown>;\n  if (!Array.isArray(resources.required)) return false;\n\n  // Optional field can be missing or must be an array\n  if (resources.optional !== undefined && !Array.isArray(resources.optional)) {\n    return false;\n  }\n\n  return true;\n}\n"],"mappings":";;;;;;aAC+C;AAS/C,MAAM,SAAS,aAAa,kBAAkB;AAY9C,SAAS,cAAc,GAAyB;CAC9C,MAAM,IAAI,OAAO,OAAO,aAAa,CAAC,MAAM,MAAM,MAAM,EAAE;AAC1D,KAAI,MAAM,OAAW,QAAO;AAC5B,OAAM,IAAI,mBACR,2BAA2B,EAAE,YAAY,OAAO,OAAO,aAAa,CAAC,KAAK,KAAK,GAChF;;AAGH,SAAS,oBACP,MACA,GACoB;CACpB,MAAM,UAAU,oBAAoB;AACpC,KAAI,QAAQ,SAAS,EAAwB,CAAE,QAAO;AACtD,OAAM,IAAI,mBACR,uBAAuB,EAAE,aAAa,KAAK,WAAW,QAAQ,KAAK,KAAK,GACzE;;AAGH,SAAS,kBAAkB,GAAuC;CAChE,MAAM,OAAO,cAAc,EAAE,KAAK;CAClC,MAAM,aAAa,oBAAoB,MAAM,EAAE,WAAW;AAC1D,QAAO;EACL,GAAG;EACH;EACA;EACA,UAAU;EACX;;;;;;;;;;AAWH,SAAgB,kBAAkB,QAA2C;CAC3E,MAAM,aAAa,OAAO,QAAQ;AAElC,KAAI,CAAC,OAAO,SACV,OAAM,IAAI,mBACR,UAAU,WAAW,8EACtB;CAGH,MAAM,MAAM,OAAO;AAEnB,KAAI,CAAC,IAAI,QAAQ,OAAO,IAAI,SAAS,SACnC,OAAM,IAAI,mBACR,UAAU,WAAW,+CACtB;AAGH,KAAI,CAAC,IAAI,eAAe,OAAO,IAAI,gBAAgB,SACjD,OAAM,IAAI,mBACR,UAAU,IAAI,KAAK,sDACpB;AAGH,KAAI,CAAC,IAAI,eAAe,OAAO,IAAI,gBAAgB,SACjD,OAAM,IAAI,mBACR,UAAU,IAAI,KAAK,sDACpB;AAGH,KAAI,CAAC,IAAI,UACP,OAAM,IAAI,mBACR,UAAU,IAAI,KAAK,wCACpB;AAGH,KAAI,CAAC,MAAM,QAAQ,IAAI,UAAU,SAAS,CACxC,OAAM,IAAI,mBACR,UAAU,IAAI,KAAK,mEACpB;AAGH,KACE,IAAI,UAAU,aAAa,UAC3B,CAAC,MAAM,QAAQ,IAAI,UAAU,SAAS,CAEtC,OAAM,IAAI,mBACR,UAAU,IAAI,KAAK,mEACpB;CAGH,MAAM,WAAW,IAAI,UAAU,SAAS,KAAK,MAAM;EAEjD,MAAM,EAAE,UAAU,GAAG,GAAG,SADX,kBAAkB,EAAmB;AAElD,SAAO;GACP;CACF,MAAM,YAAY,IAAI,UAAU,YAAY,EAAE,EAAE,KAAK,MAAM;EAEzD,MAAM,EAAE,UAAU,GAAG,GAAG,SADX,kBAAkB,EAAmB;AAElD,SAAO;GACP;AAEF,QAAO,MACL,+EACA,IAAI,MACJ,SAAS,QACT,SAAS,OACV;AAED,QAAO;EACL,GAAG;EACH,WAAW;GAAE;GAAU;GAAU;EAClC;;;;;;;;;;;;;;;;;;;;AAqBH,SAAgB,wBAAwB,QAA2B;CACjE,MAAM,WAAW,kBAAkB,OAAO;CAE1C,MAAM,WAAW,SAAS,UAAU,SAAS,KAAK,OAAO;EACvD,GAAG;EACH,UAAU;EACX,EAAE;CACH,MAAM,YAAY,SAAS,UAAU,YAAY,EAAE,EAAE,KAAK,OAAO;EAC/D,GAAG;EACH,UAAU;EACX,EAAE;AAEH,QAAO,CAAC,GAAG,UAAU,GAAG,SAAS"}

package/dist/registry/resource-registry.d.ts

@@ -0,0 +1,133 @@
+import { PluginConstructor, PluginData } from "../shared/src/plugin.js";
+import { ResourceEntry, ResourceRequirement, ValidationResult } from "./types.js";
+
+//#region src/registry/resource-registry.d.ts
+
+/**
+ * Central registry for tracking plugin resource requirements.
+ * Deduplication uses type + resourceKey (machine-stable); alias is for display only.
+ */
+declare class ResourceRegistry {
+  private resources;
+  /**
+   * Registers a resource requirement for a plugin.
+   * If a resource with the same type+resourceKey already exists, merges them:
+   * - Combines plugin names (comma-separated)
+   * - Uses the most permissive permission (per-type hierarchy)
+   * - Marks as required if any plugin requires it
+   * - Combines descriptions if they differ
+   * - Merges fields; warns when same field name uses different env vars
+   *
+   * @param plugin - Name of the plugin registering the resource
+   * @param resource - Resource requirement specification
+   */
+  register(plugin: string, resource: ResourceRequirement): void;
+  /**
+   * Collects and registers resource requirements from an array of plugins.
+   * For each plugin, loads its manifest (required) and runtime resource requirements.
+   *
+   * @param rawPlugins - Array of plugin data entries from createApp configuration
+   * @throws {ConfigurationError} If any plugin is missing a manifest or manifest is invalid
+   */
+  collectResources(rawPlugins: PluginData<PluginConstructor, unknown, string>[]): void;
+  /**
+   * Merges a new resource requirement with an existing entry.
+   * Applies intelligent merging logic for conflicting properties.
+   */
+  private mergeResources;
+  /**
+   * Retrieves all registered resources.
+   * Returns a copy of the array to prevent external mutations.
+   *
+   * @returns Array of all registered resource entries
+   */
+  getAll(): ResourceEntry[];
+  /**
+   * Gets a specific resource by type and resourceKey (dedup key).
+   *
+   * @param type - Resource type
+   * @param resourceKey - Stable machine key (not alias; alias is for display only)
+   * @returns The resource entry if found, undefined otherwise
+   */
+  get(type: string, resourceKey: string): ResourceEntry | undefined;
+  /**
+   * Clears all registered resources.
+   * Useful for testing or when rebuilding the registry.
+   */
+  clear(): void;
+  /**
+   * Returns the number of registered resources.
+   */
+  size(): number;
+  /**
+   * Gets all resources required by a specific plugin.
+   *
+   * @param pluginName - Name of the plugin
+   * @returns Array of resources where the plugin is listed as a requester
+   */
+  getByPlugin(pluginName: string): ResourceEntry[];
+  /**
+   * Gets all required resources (where required=true).
+   *
+   * @returns Array of required resource entries
+   */
+  getRequired(): ResourceEntry[];
+  /**
+   * Gets all optional resources (where required=false).
+   *
+   * @returns Array of optional resource entries
+   */
+  getOptional(): ResourceEntry[];
+  /**
+   * Validates all registered resources against the environment.
+   *
+   * Checks each resource's field environment variables to determine if it's resolved.
+   * Updates the `resolved` and `values` fields on each resource entry.
+   *
+   * Only required resources affect the `valid` status - optional resources
+   * are checked but don't cause validation failure.
+   *
+   * @returns ValidationResult with validity status, missing resources, and all resources
+   *
+   * @example
+   * ```typescript
+   * const registry = ResourceRegistry.getInstance();
+   * const result = registry.validate();
+   *
+   * if (!result.valid) {
+   *   console.error("Missing resources:", result.missing.map(r => Object.values(r.fields).map(f => f.env)));
+   * }
+   * ```
+   */
+  validate(): ValidationResult;
+  /**
+   * Validates all registered resources and enforces the result.
+   *
+   * - In production: throws a {@link ConfigurationError} if any required resources are missing.
+   * - In development (`NODE_ENV=development`): logs a warning but continues, unless
+   *   `APPKIT_STRICT_VALIDATION=true` is set, in which case throws like production.
+   * - When all resources are valid: logs a debug message with the count.
+   *
+   * @returns ValidationResult with validity status, missing resources, and all resources
+   * @throws {ConfigurationError} In production when required resources are missing, or in dev when APPKIT_STRICT_VALIDATION=true
+   */
+  enforceValidation(): ValidationResult;
+  /**
+   * Formats missing resources into a human-readable error message.
+   *
+   * @param missing - Array of missing resource entries
+   * @returns Formatted error message string
+   */
+  static formatMissingResources(missing: ResourceEntry[]): string;
+  /**
+   * Formats a highly visible warning banner for dev-mode missing resources.
+   * Uses box drawing to ensure the message is impossible to miss in scrolling logs.
+   *
+   * @param missing - Array of missing resource entries
+   * @returns Formatted banner string
+   */
+  static formatDevWarningBanner(missing: ResourceEntry[]): string;
+}
+//#endregion
+export { ResourceRegistry };
+//# sourceMappingURL=resource-registry.d.ts.map

package/dist/registry/resource-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-registry.d.ts","names":[],"sources":["../../src/registry/resource-registry.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAsbgD,cAjYnC,gBAAA,CAiYmC;EAAa,QAAA,SAAA;;;;;;;;;;;;;qCAlXjB;;;;;;;;+BA4B5B,WAAW;;;;;;;;;;;;YAqIR;;;;;;;;0CAW8B;;;;;;;;;;;;;;;;mCAyBP;;;;;;iBAWlB;;;;;;iBASA;;;;;;;;;;;;;;;;;;;;;;cAyBH;;;;;;;;;;;;uBA8DS;;;;;;;yCA6CkB;;;;;;;;yCAqBA"}