chore: implement manifest loader (#83)

Implement manifest loader with validation and error handling.
All plugins must have a static manifest property.

Features:
- getPluginManifest() - loads and validates plugin manifests
- getResourceRequirements() - extracts resource requirements
- Comprehensive validation with clear error messages
- Unit tests and integration tests with core plugins

Author: MarioCadenas

packages/appkit/src/core/tests/databricks.test.ts

@@ -2,20 +2,19 @@ import { mockServiceContext, setupDatabricksEnv } from "@tools/test-helpers";
 import type { BasePlugin } from "shared";
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import { ServiceContext } from "../../context/service-context";
+import type { PluginManifest } from "../../registry/types";
 import { AppKit, createApp } from "../appkit";
 
-// Helper function to create test manifests
-function createTestManifest(name: string, displayName: string) {
-  return {
-    name,
-    displayName,
-    description: `Test plugin for ${name}`,
-    resources: {
-      required: [],
-      optional: [],
-    },
-  };
-}
+// Generic test manifest for test plugins
+const createTestManifest = (name: string): PluginManifest => ({
+  name,
+  displayName: `${name} Test Plugin`,
+  description: `Test plugin for ${name}`,
+  resources: {
+    required: [],
+    optional: [],
+  },
+});
 
 // Mock environment validation
 vi.mock("../utils", () => ({
@@ -45,7 +44,7 @@ vi.mock("@databricks-apps/cache", () => ({
 class CoreTestPlugin implements BasePlugin {
   static DEFAULT_CONFIG = { coreDefault: "core-value" };
   static phase = "core" as const;
-  static manifest = createTestManifest("coreTest", "Core Test Plugin");
+  static manifest = createTestManifest("coreTest");
   name = "coreTest";
   setupCalled = false;
   validateEnvCalled = false;
@@ -82,7 +81,7 @@ class CoreTestPlugin implements BasePlugin {
 class NormalTestPlugin implements BasePlugin {
   static DEFAULT_CONFIG = { normalDefault: "normal-value" };
   static phase = "normal" as const;
-  static manifest = createTestManifest("normalTest", "Normal Test Plugin");
+  static manifest = createTestManifest("normalTest");
   name = "normalTest";
   setupCalled = false;
   validateEnvCalled = false;
@@ -118,7 +117,7 @@ class NormalTestPlugin implements BasePlugin {
 class DeferredTestPlugin implements BasePlugin {
   static DEFAULT_CONFIG = { deferredDefault: "deferred-value" };
   static phase = "deferred" as const;
-  static manifest = createTestManifest("deferredTest", "Deferred Test Plugin");
+  static manifest = createTestManifest("deferredTest");
   name = "deferredTest";
   setupCalled = false;
   validateEnvCalled = false;
@@ -156,7 +155,7 @@ class DeferredTestPlugin implements BasePlugin {
 
 class SlowSetupPlugin implements BasePlugin {
   static DEFAULT_CONFIG = {};
-  static manifest = createTestManifest("slowSetup", "Slow Setup Plugin");
+  static manifest = createTestManifest("slowSetup");
   name = "slowSetup";
   setupDelay: number;
   setupCalled = false;
@@ -187,7 +186,7 @@ class SlowSetupPlugin implements BasePlugin {
 
 class FailingPlugin implements BasePlugin {
   static DEFAULT_CONFIG = {};
-  static manifest = createTestManifest("failing", "Failing Plugin");
+  static manifest = createTestManifest("failing");
   name = "failing";
 
   validateEnv() {
@@ -545,10 +544,7 @@ describe("AppKit", () => {
     test("should bind SDK methods to plugin instance", async () => {
       class ContextTestPlugin implements BasePlugin {
         static DEFAULT_CONFIG = {};
-        static manifest = createTestManifest(
-          "contextTest",
-          "Context Test Plugin",
-        );
+        static manifest = createTestManifest("contextTest");
         name = "contextTest";
         private counter = 0;
 
@@ -589,10 +585,7 @@ describe("AppKit", () => {
     test("should maintain context when SDK method is passed as callback", async () => {
       class CallbackTestPlugin implements BasePlugin {
         static DEFAULT_CONFIG = {};
-        static manifest = createTestManifest(
-          "callbackTest",
-          "Callback Test Plugin",
-        );
+        static manifest = createTestManifest("callbackTest");
         name = "callbackTest";
         private values: number[] = [];
 

packages/appkit/src/index.ts

@@ -31,7 +31,7 @@ export {
 // Plugin authoring
 export { Plugin, toPlugin } from "./plugin";
 export { analytics, server } from "./plugins";
-// Registry types for plugin manifests
+// Registry types and utilities for plugin manifests
 export type {
   ConfigSchema,
   ConfigSchemaProperty,
@@ -41,7 +41,11 @@ export type {
   ResourceRequirement,
   ValidationResult,
 } from "./registry";
-export { ResourceType } from "./registry";
+export {
+  getPluginManifest,
+  getResourceRequirements,
+  ResourceType,
+} from "./registry";
 // Telemetry (for advanced custom telemetry)
 export {
   type Counter,

packages/appkit/src/plugin/plugin.ts

@@ -62,15 +62,15 @@ const EXCLUDED_FROM_PROXY = new Set([
 /**
  * Base abstract class for creating AppKit plugins.
  *
- * Plugins can optionally declare their resource requirements through:
- * 1. A static `manifest` property - recommended for all plugins
- * 2. A static `getResourceRequirements()` method - for dynamic requirements
+ * All plugins must declare a static `manifest` property with their metadata
+ * and resource requirements. Plugins can also implement a static
+ * `getResourceRequirements()` method for dynamic requirements based on config.
  *
  * @example
  * ```typescript
  * import { Plugin, toPlugin, PluginManifest, ResourceType } from '@databricks/appkit';
  *
- * // Define manifest
+ * // Define manifest (required)
  * const myManifest: PluginManifest = {
  *   name: 'myPlugin',
  *   displayName: 'My Plugin',
@@ -90,9 +90,21 @@ const EXCLUDED_FROM_PROXY = new Set([
  * };
  *
  * class MyPlugin extends Plugin<MyConfig> {
- *   static manifest = myManifest;
- *   // ... implementation
+ *   static manifest = myManifest;  // Required!
+ *
+ *   name = 'myPlugin';
+ *   protected envVars: string[] = [];
+ *
+ *   async setup() {
+ *     // Initialize your plugin
+ *   }
+ *
+ *   injectRoutes(router: Router) {
+ *     // Register HTTP endpoints
+ *   }
  * }
+ *
+ * export const myPlugin = toPlugin(MyPlugin, 'myPlugin');
  * ```
  */
 export abstract class Plugin<

packages/appkit/src/plugins/server/tests/server.integration.test.ts

@@ -98,18 +98,14 @@ describe("ServerPlugin with custom plugin", () => {
 
     // Create a simple test plugin
     class TestPlugin extends Plugin {
-      name = "test-plugin" as const;
-      envVars: string[] = [];
-
       static manifest = {
         name: "test-plugin",
         displayName: "Test Plugin",
         description: "Test plugin for integration tests",
-        resources: {
-          required: [],
-          optional: [],
-        },
+        resources: { required: [], optional: [] },
       };
+      name = "test-plugin" as const;
+      envVars: string[] = [];
 
       injectRoutes(router: any) {
         router.get("/echo", (_req: any, res: any) => {

packages/appkit/src/registry/index.ts

@@ -6,9 +6,10 @@
  *
  * Components:
  * - Type definitions for resources, manifests, and validation
+ * - Manifest loader for reading plugin declarations
  * - (Future) ResourceRegistry singleton for tracking requirements
- * - (Future) Manifest loader for reading plugin declarations
  * - (Future) Config generators for app.yaml, databricks.yml, .env.example
  */
 
+export { getPluginManifest, getResourceRequirements } from "./manifest-loader";
 export * from "./types";

packages/appkit/src/registry/manifest-loader.ts

@@ -0,0 +1,164 @@
+import type { PluginConstructor } from "shared";
+import { ConfigurationError } from "../errors";
+import { createLogger } from "../logging/logger";
+import type { PluginManifest } from "./types";
+
+const logger = createLogger("manifest-loader");
+
+/**
+ * Loads and validates the manifest from a plugin constructor.
+ *
+ * All plugins must have a static `manifest` property that declares their
+ * metadata and resource requirements.
+ *
+ * @param plugin - The plugin constructor class
+ * @returns The validated plugin manifest
+ * @throws {ConfigurationError} If the manifest is missing or invalid
+ *
+ * @example
+ * ```typescript
+ * import { AnalyticsPlugin } from '@databricks/appkit';
+ * import { getPluginManifest } from './manifest-loader';
+ *
+ * const manifest = getPluginManifest(AnalyticsPlugin);
+ * console.log('Required resources:', manifest.resources.required);
+ * ```
+ */
+export function getPluginManifest(plugin: PluginConstructor): PluginManifest {
+  const pluginName = plugin.name || "unknown";
+
+  try {
+    // Check for static manifest property
+    if (!plugin.manifest) {
+      throw new ConfigurationError(
+        `Plugin ${pluginName} is missing a manifest. All plugins must declare a static manifest property.`,
+      );
+    }
+
+    // Validate manifest structure
+    const manifest = plugin.manifest;
+
+    if (!manifest.name || typeof manifest.name !== "string") {
+      throw new ConfigurationError(
+        `Plugin ${pluginName} manifest has missing or invalid 'name' field`,
+      );
+    }
+
+    if (!manifest.displayName || typeof manifest.displayName !== "string") {
+      throw new ConfigurationError(
+        `Plugin ${manifest.name} manifest has missing or invalid 'displayName' field`,
+      );
+    }
+
+    if (!manifest.description || typeof manifest.description !== "string") {
+      throw new ConfigurationError(
+        `Plugin ${manifest.name} manifest has missing or invalid 'description' field`,
+      );
+    }
+
+    if (!manifest.resources) {
+      throw new ConfigurationError(
+        `Plugin ${manifest.name} manifest is missing 'resources' field`,
+      );
+    }
+
+    if (!Array.isArray(manifest.resources.required)) {
+      throw new ConfigurationError(
+        `Plugin ${manifest.name} manifest has invalid 'resources.required' field (expected array)`,
+      );
+    }
+
+    if (
+      manifest.resources.optional &&
+      !Array.isArray(manifest.resources.optional)
+    ) {
+      throw new ConfigurationError(
+        `Plugin ${manifest.name} manifest has invalid 'resources.optional' field (expected array)`,
+      );
+    }
+
+    logger.debug(
+      "Loaded manifest for plugin %s: %d required resources, %d optional resources",
+      manifest.name,
+      manifest.resources.required.length,
+      manifest.resources.optional?.length || 0,
+    );
+
+    // Cast to appkit PluginManifest type (structurally compatible, just more specific types)
+    return manifest as unknown as PluginManifest;
+  } catch (error) {
+    if (error instanceof ConfigurationError) {
+      throw error;
+    }
+    throw new ConfigurationError(
+      `Error loading manifest from plugin ${pluginName}: ${error}`,
+    );
+  }
+}
+
+/**
+ * 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})`);
+ * }
+ * ```
+ */
+export function getResourceRequirements(plugin: PluginConstructor) {
+  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];
+}
+
+/**
+ * Validates a manifest object structure.
+ *
+ * @param manifest - The manifest object to validate
+ * @returns true if the manifest is valid, false otherwise
+ *
+ * @internal
+ */
+export function isValidManifest(manifest: unknown): manifest is PluginManifest {
+  if (!manifest || typeof manifest !== "object") {
+    return false;
+  }
+
+  const m = manifest as Record<string, unknown>;
+
+  // Check required fields
+  if (typeof m.name !== "string") return false;
+  if (typeof m.displayName !== "string") return false;
+  if (typeof m.description !== "string") return false;
+
+  // Check resources structure
+  if (!m.resources || typeof m.resources !== "object") return false;
+
+  const resources = m.resources as Record<string, unknown>;
+  if (!Array.isArray(resources.required)) return false;
+
+  // Optional field can be missing or must be an array
+  if (resources.optional !== undefined && !Array.isArray(resources.optional)) {
+    return false;
+  }
+
+  return true;
+}