@databricks/appkit 0.5.4 → 0.7.0

package/dist/registry/resource-registry.js

@@ -0,0 +1,297 @@
+import { createLogger } from "../logging/logger.js";
+import { ConfigurationError } from "../errors/configuration.js";
+import { init_errors } from "../errors/index.js";
+import { PERMISSION_HIERARCHY_BY_TYPE } from "./types.js";
+import { getPluginManifest } from "./manifest-loader.js";
+
+//#region src/registry/resource-registry.ts
+init_errors();
+const logger = createLogger("resource-registry");
+/**
+* Dedup key for registry: type + resourceKey (machine-stable).
+* alias is for UI/display only.
+*/
+function getDedupKey(type, resourceKey) {
+	return `${type}:${resourceKey}`;
+}
+/**
+* Returns the most permissive permission for a given resource type.
+* Uses per-type hierarchy; unknown permissions are treated as least permissive.
+*/
+function getMostPermissivePermission(resourceType, p1, p2) {
+	const hierarchy = PERMISSION_HIERARCHY_BY_TYPE[resourceType];
+	return (hierarchy?.indexOf(p1) ?? -1) > (hierarchy?.indexOf(p2) ?? -1) ? p1 : p2;
+}
+/**
+* Central registry for tracking plugin resource requirements.
+* Deduplication uses type + resourceKey (machine-stable); alias is for display only.
+*/
+var ResourceRegistry = class ResourceRegistry {
+	resources = /* @__PURE__ */ new Map();
+	/**
+	* 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, resource) {
+		const key = getDedupKey(resource.type, resource.resourceKey);
+		const existing = this.resources.get(key);
+		if (existing) {
+			const merged = this.mergeResources(existing, plugin, resource);
+			this.resources.set(key, merged);
+		} else {
+			const entry = {
+				...resource,
+				plugin,
+				resolved: false,
+				permissionSources: { [plugin]: resource.permission }
+			};
+			this.resources.set(key, entry);
+		}
+	}
+	/**
+	* 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) {
+		for (const pluginData of rawPlugins) {
+			if (!pluginData?.plugin) continue;
+			const pluginName = pluginData.name;
+			const manifest = getPluginManifest(pluginData.plugin);
+			for (const resource of manifest.resources.required) this.register(pluginName, {
+				...resource,
+				required: true
+			});
+			for (const resource of manifest.resources.optional || []) this.register(pluginName, {
+				...resource,
+				required: false
+			});
+			if (typeof pluginData.plugin.getResourceRequirements === "function") {
+				const runtimeResources = pluginData.plugin.getResourceRequirements(pluginData.config);
+				for (const resource of runtimeResources) this.register(pluginName, resource);
+			}
+			logger.debug("Collected resources from plugin %s: %d total", pluginName, this.getByPlugin(pluginName).length);
+		}
+	}
+	/**
+	* Merges a new resource requirement with an existing entry.
+	* Applies intelligent merging logic for conflicting properties.
+	*/
+	mergeResources(existing, newPlugin, newResource) {
+		const plugins = existing.plugin.split(", ");
+		if (!plugins.includes(newPlugin)) plugins.push(newPlugin);
+		const permissionSources = {
+			...existing.permissionSources ?? {},
+			[newPlugin]: newResource.permission
+		};
+		const permission = getMostPermissivePermission(existing.type, existing.permission, newResource.permission);
+		if (permission !== existing.permission) logger.warn("Resource %s:%s permission escalated from \"%s\" to \"%s\" due to plugin \"%s\" (previously requested by: %s). Review plugin permissions to ensure least-privilege.", existing.type, existing.resourceKey, existing.permission, permission, newPlugin, existing.plugin);
+		const required = existing.required || newResource.required;
+		let description = existing.description;
+		if (newResource.description && newResource.description !== existing.description) {
+			if (!existing.description.includes(newResource.description)) description = `${existing.description}; ${newResource.description}`;
+		}
+		const fields = { ...existing.fields ?? {} };
+		for (const [fieldName, newField] of Object.entries(newResource.fields ?? {})) {
+			const existingField = fields[fieldName];
+			if (existingField) {
+				if (existingField.env !== newField.env) logger.warn("Resource %s:%s field \"%s\": conflicting env vars \"%s\" (from %s) vs \"%s\" (from %s). Using first.", existing.type, existing.resourceKey, fieldName, existingField.env, existing.plugin, newField.env, newPlugin);
+			} else fields[fieldName] = newField;
+		}
+		return {
+			...existing,
+			plugin: plugins.join(", "),
+			permission,
+			permissionSources,
+			required,
+			description,
+			fields
+		};
+	}
+	/**
+	* Retrieves all registered resources.
+	* Returns a copy of the array to prevent external mutations.
+	*
+	* @returns Array of all registered resource entries
+	*/
+	getAll() {
+		return Array.from(this.resources.values());
+	}
+	/**
+	* 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, resourceKey) {
+		return this.resources.get(getDedupKey(type, resourceKey));
+	}
+	/**
+	* Clears all registered resources.
+	* Useful for testing or when rebuilding the registry.
+	*/
+	clear() {
+		this.resources.clear();
+	}
+	/**
+	* Returns the number of registered resources.
+	*/
+	size() {
+		return this.resources.size;
+	}
+	/**
+	* 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) {
+		return this.getAll().filter((entry) => entry.plugin.split(", ").includes(pluginName));
+	}
+	/**
+	* Gets all required resources (where required=true).
+	*
+	* @returns Array of required resource entries
+	*/
+	getRequired() {
+		return this.getAll().filter((entry) => entry.required);
+	}
+	/**
+	* Gets all optional resources (where required=false).
+	*
+	* @returns Array of optional resource entries
+	*/
+	getOptional() {
+		return this.getAll().filter((entry) => !entry.required);
+	}
+	/**
+	* 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() {
+		const missing = [];
+		for (const entry of this.resources.values()) {
+			const values = {};
+			let allSet = true;
+			for (const [fieldName, fieldDef] of Object.entries(entry.fields)) {
+				const val = process.env[fieldDef.env];
+				if (val !== void 0 && val !== "") values[fieldName] = val;
+				else allSet = false;
+			}
+			if (allSet) {
+				entry.resolved = true;
+				entry.values = values;
+				logger.debug("Resource %s:%s resolved from fields", entry.type, entry.alias);
+			} else {
+				entry.resolved = false;
+				entry.values = Object.keys(values).length > 0 ? values : void 0;
+				if (entry.required) {
+					missing.push(entry);
+					logger.debug("Required resource %s:%s missing (fields: %s)", entry.type, entry.alias, Object.keys(entry.fields).join(", "));
+				} else logger.debug("Optional resource %s:%s not configured (fields: %s)", entry.type, entry.alias, Object.keys(entry.fields).join(", "));
+			}
+		}
+		return {
+			valid: missing.length === 0,
+			missing,
+			all: this.getAll()
+		};
+	}
+	/**
+	* 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() {
+		const validation = this.validate();
+		const isDevelopment = process.env.NODE_ENV === "development";
+		const strictValidation = process.env.APPKIT_STRICT_VALIDATION === "true" || process.env.APPKIT_STRICT_VALIDATION === "1";
+		if (!validation.valid) {
+			const errorMessage = ResourceRegistry.formatMissingResources(validation.missing);
+			if (!isDevelopment || strictValidation) throw new ConfigurationError(errorMessage, { context: { missingResources: validation.missing.map((r) => ({
+				type: r.type,
+				alias: r.alias,
+				plugin: r.plugin,
+				envVars: Object.values(r.fields).map((f) => f.env)
+			})) } });
+			const banner = ResourceRegistry.formatDevWarningBanner(validation.missing);
+			logger.warn("\n%s", banner);
+		} else if (this.size() > 0) logger.debug("All %d resources validated successfully", this.size());
+		return validation;
+	}
+	/**
+	* Formats missing resources into a human-readable error message.
+	*
+	* @param missing - Array of missing resource entries
+	* @returns Formatted error message string
+	*/
+	static formatMissingResources(missing) {
+		if (missing.length === 0) return "No missing resources";
+		return `Missing required resources:\n${missing.map((entry) => {
+			const envHint = ` (set ${Object.values(entry.fields).map((f) => f.env).join(", ")})`;
+			return `  - ${entry.type}:${entry.alias} [${entry.plugin}]${envHint}`;
+		}).join("\n")}`;
+	}
+	/**
+	* 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) {
+		const contentLines = ["MISSING REQUIRED RESOURCES (dev mode — would fail in production)", ""];
+		for (const entry of missing) {
+			const envVars = Object.values(entry.fields).map((f) => f.env);
+			contentLines.push(`  ${entry.type}:${entry.alias}  (plugin: ${entry.plugin})`);
+			contentLines.push(`    Set: ${envVars.join(", ")}`);
+		}
+		contentLines.push("");
+		contentLines.push("Add these to your .env file or environment to suppress this warning.");
+		const maxLen = Math.max(...contentLines.map((l) => l.length));
+		const border = "=".repeat(maxLen + 4);
+		return [
+			border,
+			...contentLines.map((line) => `| ${line.padEnd(maxLen)} |`),
+			border
+		].join("\n");
+	}
+};
+
+//#endregion
+export { ResourceRegistry };
+//# sourceMappingURL=resource-registry.js.map

package/dist/registry/resource-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-registry.js","names":[],"sources":["../../src/registry/resource-registry.ts"],"sourcesContent":["/**\n * Resource Registry\n *\n * Central registry that tracks all resource requirements across all plugins.\n * Provides visibility into Databricks resources needed by the application\n * and handles deduplication when multiple plugins require the same resource\n * (dedup key: type + resourceKey).\n *\n * Use `new ResourceRegistry()` for instance-scoped usage (e.g. createApp).\n * getInstance() / resetInstance() remain for backward compatibility in tests.\n */\n\nimport type { BasePluginConfig, PluginConstructor, PluginData } from \"shared\";\nimport { ConfigurationError } from \"../errors\";\nimport { createLogger } from \"../logging/logger\";\nimport { getPluginManifest } from \"./manifest-loader\";\nimport type {\n  ResourceEntry,\n  ResourcePermission,\n  ResourceRequirement,\n  ValidationResult,\n} from \"./types\";\nimport { PERMISSION_HIERARCHY_BY_TYPE, type ResourceType } from \"./types\";\n\nconst logger = createLogger(\"resource-registry\");\n\n/**\n * Dedup key for registry: type + resourceKey (machine-stable).\n * alias is for UI/display only.\n */\nfunction getDedupKey(type: string, resourceKey: string): string {\n  return `${type}:${resourceKey}`;\n}\n\n/**\n * Returns the most permissive permission for a given resource type.\n * Uses per-type hierarchy; unknown permissions are treated as least permissive.\n */\nfunction getMostPermissivePermission(\n  resourceType: ResourceType,\n  p1: ResourcePermission,\n  p2: ResourcePermission,\n): ResourcePermission {\n  const hierarchy = PERMISSION_HIERARCHY_BY_TYPE[resourceType as ResourceType];\n  const index1 = hierarchy?.indexOf(p1) ?? -1;\n  const index2 = hierarchy?.indexOf(p2) ?? -1;\n  return index1 > index2 ? p1 : p2;\n}\n\n/**\n * Central registry for tracking plugin resource requirements.\n * Deduplication uses type + resourceKey (machine-stable); alias is for display only.\n */\nexport class ResourceRegistry {\n  private resources: Map<string, ResourceEntry> = new Map();\n\n  /**\n   * Registers a resource requirement for a plugin.\n   * If a resource with the same type+resourceKey already exists, merges them:\n   * - Combines plugin names (comma-separated)\n   * - Uses the most permissive permission (per-type hierarchy)\n   * - Marks as required if any plugin requires it\n   * - Combines descriptions if they differ\n   * - Merges fields; warns when same field name uses different env vars\n   *\n   * @param plugin - Name of the plugin registering the resource\n   * @param resource - Resource requirement specification\n   */\n  public register(plugin: string, resource: ResourceRequirement): void {\n    const key = getDedupKey(resource.type, resource.resourceKey);\n    const existing = this.resources.get(key);\n\n    if (existing) {\n      // Merge with existing resource\n      const merged = this.mergeResources(existing, plugin, resource);\n      this.resources.set(key, merged);\n    } else {\n      // Create new resource entry with permission source tracking\n      const entry: ResourceEntry = {\n        ...resource,\n        plugin,\n        resolved: false,\n        permissionSources: { [plugin]: resource.permission },\n      };\n      this.resources.set(key, entry);\n    }\n  }\n\n  /**\n   * Collects and registers resource requirements from an array of plugins.\n   * For each plugin, loads its manifest (required) and runtime resource requirements.\n   *\n   * @param rawPlugins - Array of plugin data entries from createApp configuration\n   * @throws {ConfigurationError} If any plugin is missing a manifest or manifest is invalid\n   */\n  public collectResources(\n    rawPlugins: PluginData<PluginConstructor, unknown, string>[],\n  ): void {\n    for (const pluginData of rawPlugins) {\n      if (!pluginData?.plugin) continue;\n\n      const pluginName = pluginData.name;\n      const manifest = getPluginManifest(pluginData.plugin);\n\n      // Register required resources\n      for (const resource of manifest.resources.required) {\n        this.register(pluginName, { ...resource, required: true });\n      }\n\n      // Register optional resources\n      for (const resource of manifest.resources.optional || []) {\n        this.register(pluginName, { ...resource, required: false });\n      }\n\n      // Check for runtime resource requirements\n      if (typeof pluginData.plugin.getResourceRequirements === \"function\") {\n        const runtimeResources = pluginData.plugin.getResourceRequirements(\n          pluginData.config as BasePluginConfig,\n        );\n        for (const resource of runtimeResources) {\n          this.register(pluginName, resource as ResourceRequirement);\n        }\n      }\n\n      logger.debug(\n        \"Collected resources from plugin %s: %d total\",\n        pluginName,\n        this.getByPlugin(pluginName).length,\n      );\n    }\n  }\n\n  /**\n   * Merges a new resource requirement with an existing entry.\n   * Applies intelligent merging logic for conflicting properties.\n   */\n  private mergeResources(\n    existing: ResourceEntry,\n    newPlugin: string,\n    newResource: ResourceRequirement,\n  ): ResourceEntry {\n    // Combine plugin names if not already included\n    const plugins = existing.plugin.split(\", \");\n    if (!plugins.includes(newPlugin)) {\n      plugins.push(newPlugin);\n    }\n\n    // Track per-plugin permission sources\n    const permissionSources: Record<string, ResourcePermission> = {\n      ...(existing.permissionSources ?? {}),\n      [newPlugin]: newResource.permission,\n    };\n\n    // Use the most permissive permission for this resource type; warn when escalating\n    const permission = getMostPermissivePermission(\n      existing.type as ResourceType,\n      existing.permission,\n      newResource.permission,\n    );\n\n    if (permission !== existing.permission) {\n      logger.warn(\n        'Resource %s:%s permission escalated from \"%s\" to \"%s\" due to plugin \"%s\" ' +\n          \"(previously requested by: %s). Review plugin permissions to ensure least-privilege.\",\n        existing.type,\n        existing.resourceKey,\n        existing.permission,\n        permission,\n        newPlugin,\n        existing.plugin,\n      );\n    }\n\n    // Mark as required if any plugin requires it\n    const required = existing.required || newResource.required;\n\n    // Combine descriptions if they differ\n    let description = existing.description;\n    if (\n      newResource.description &&\n      newResource.description !== existing.description\n    ) {\n      if (!existing.description.includes(newResource.description)) {\n        description = `${existing.description}; ${newResource.description}`;\n      }\n    }\n\n    // Merge fields: union of field names; warn when same field name uses different env\n    const fields = { ...(existing.fields ?? {}) };\n    for (const [fieldName, newField] of Object.entries(\n      newResource.fields ?? {},\n    )) {\n      const existingField = fields[fieldName];\n      if (existingField) {\n        if (existingField.env !== newField.env) {\n          logger.warn(\n            'Resource %s:%s field \"%s\": conflicting env vars \"%s\" (from %s) vs \"%s\" (from %s). Using first.',\n            existing.type,\n            existing.resourceKey,\n            fieldName,\n            existingField.env,\n            existing.plugin,\n            newField.env,\n            newPlugin,\n          );\n        }\n        // keep existing\n      } else {\n        fields[fieldName] = newField;\n      }\n    }\n\n    return {\n      ...existing,\n      plugin: plugins.join(\", \"),\n      permission,\n      permissionSources,\n      required,\n      description,\n      fields,\n    };\n  }\n\n  /**\n   * Retrieves all registered resources.\n   * Returns a copy of the array to prevent external mutations.\n   *\n   * @returns Array of all registered resource entries\n   */\n  public getAll(): ResourceEntry[] {\n    return Array.from(this.resources.values());\n  }\n\n  /**\n   * Gets a specific resource by type and resourceKey (dedup key).\n   *\n   * @param type - Resource type\n   * @param resourceKey - Stable machine key (not alias; alias is for display only)\n   * @returns The resource entry if found, undefined otherwise\n   */\n  public get(type: string, resourceKey: string): ResourceEntry | undefined {\n    return this.resources.get(getDedupKey(type, resourceKey));\n  }\n\n  /**\n   * Clears all registered resources.\n   * Useful for testing or when rebuilding the registry.\n   */\n  public clear(): void {\n    this.resources.clear();\n  }\n\n  /**\n   * Returns the number of registered resources.\n   */\n  public size(): number {\n    return this.resources.size;\n  }\n\n  /**\n   * Gets all resources required by a specific plugin.\n   *\n   * @param pluginName - Name of the plugin\n   * @returns Array of resources where the plugin is listed as a requester\n   */\n  public getByPlugin(pluginName: string): ResourceEntry[] {\n    return this.getAll().filter((entry) =>\n      entry.plugin.split(\", \").includes(pluginName),\n    );\n  }\n\n  /**\n   * Gets all required resources (where required=true).\n   *\n   * @returns Array of required resource entries\n   */\n  public getRequired(): ResourceEntry[] {\n    return this.getAll().filter((entry) => entry.required);\n  }\n\n  /**\n   * Gets all optional resources (where required=false).\n   *\n   * @returns Array of optional resource entries\n   */\n  public getOptional(): ResourceEntry[] {\n    return this.getAll().filter((entry) => !entry.required);\n  }\n\n  /**\n   * Validates all registered resources against the environment.\n   *\n   * Checks each resource's field environment variables to determine if it's resolved.\n   * Updates the `resolved` and `values` fields on each resource entry.\n   *\n   * Only required resources affect the `valid` status - optional resources\n   * are checked but don't cause validation failure.\n   *\n   * @returns ValidationResult with validity status, missing resources, and all resources\n   *\n   * @example\n   * ```typescript\n   * const registry = ResourceRegistry.getInstance();\n   * const result = registry.validate();\n   *\n   * if (!result.valid) {\n   *   console.error(\"Missing resources:\", result.missing.map(r => Object.values(r.fields).map(f => f.env)));\n   * }\n   * ```\n   */\n  public validate(): ValidationResult {\n    const missing: ResourceEntry[] = [];\n\n    for (const entry of this.resources.values()) {\n      const values: Record<string, string> = {};\n      let allSet = true;\n      for (const [fieldName, fieldDef] of Object.entries(entry.fields)) {\n        const val = process.env[fieldDef.env];\n        if (val !== undefined && val !== \"\") {\n          values[fieldName] = val;\n        } else {\n          allSet = false;\n        }\n      }\n      if (allSet) {\n        entry.resolved = true;\n        entry.values = values;\n        logger.debug(\n          \"Resource %s:%s resolved from fields\",\n          entry.type,\n          entry.alias,\n        );\n      } else {\n        entry.resolved = false;\n        entry.values = Object.keys(values).length > 0 ? values : undefined;\n        if (entry.required) {\n          missing.push(entry);\n          logger.debug(\n            \"Required resource %s:%s missing (fields: %s)\",\n            entry.type,\n            entry.alias,\n            Object.keys(entry.fields).join(\", \"),\n          );\n        } else {\n          logger.debug(\n            \"Optional resource %s:%s not configured (fields: %s)\",\n            entry.type,\n            entry.alias,\n            Object.keys(entry.fields).join(\", \"),\n          );\n        }\n      }\n    }\n\n    return {\n      valid: missing.length === 0,\n      missing,\n      all: this.getAll(),\n    };\n  }\n\n  /**\n   * Validates all registered resources and enforces the result.\n   *\n   * - In production: throws a {@link ConfigurationError} if any required resources are missing.\n   * - In development (`NODE_ENV=development`): logs a warning but continues, unless\n   *   `APPKIT_STRICT_VALIDATION=true` is set, in which case throws like production.\n   * - When all resources are valid: logs a debug message with the count.\n   *\n   * @returns ValidationResult with validity status, missing resources, and all resources\n   * @throws {ConfigurationError} In production when required resources are missing, or in dev when APPKIT_STRICT_VALIDATION=true\n   */\n  public enforceValidation(): ValidationResult {\n    const validation = this.validate();\n    const isDevelopment = process.env.NODE_ENV === \"development\";\n    const strictValidation =\n      process.env.APPKIT_STRICT_VALIDATION === \"true\" ||\n      process.env.APPKIT_STRICT_VALIDATION === \"1\";\n\n    if (!validation.valid) {\n      const errorMessage = ResourceRegistry.formatMissingResources(\n        validation.missing,\n      );\n\n      const shouldThrow = !isDevelopment || strictValidation;\n\n      if (shouldThrow) {\n        throw new ConfigurationError(errorMessage, {\n          context: {\n            missingResources: validation.missing.map((r) => ({\n              type: r.type,\n              alias: r.alias,\n              plugin: r.plugin,\n              envVars: Object.values(r.fields).map((f) => f.env),\n            })),\n          },\n        });\n      }\n\n      // Dev mode without strict: use a visually prominent box so the warning can't be missed\n      const banner = ResourceRegistry.formatDevWarningBanner(\n        validation.missing,\n      );\n      logger.warn(\"\\n%s\", banner);\n    } else if (this.size() > 0) {\n      logger.debug(\"All %d resources validated successfully\", this.size());\n    }\n\n    return validation;\n  }\n\n  /**\n   * Formats missing resources into a human-readable error message.\n   *\n   * @param missing - Array of missing resource entries\n   * @returns Formatted error message string\n   */\n  public static formatMissingResources(missing: ResourceEntry[]): string {\n    if (missing.length === 0) {\n      return \"No missing resources\";\n    }\n\n    const lines = missing.map((entry) => {\n      const envVars = Object.values(entry.fields).map((f) => f.env);\n      const envHint = ` (set ${envVars.join(\", \")})`;\n      return `  - ${entry.type}:${entry.alias} [${entry.plugin}]${envHint}`;\n    });\n\n    return `Missing required resources:\\n${lines.join(\"\\n\")}`;\n  }\n\n  /**\n   * Formats a highly visible warning banner for dev-mode missing resources.\n   * Uses box drawing to ensure the message is impossible to miss in scrolling logs.\n   *\n   * @param missing - Array of missing resource entries\n   * @returns Formatted banner string\n   */\n  public static formatDevWarningBanner(missing: ResourceEntry[]): string {\n    const contentLines: string[] = [\n      \"MISSING REQUIRED RESOURCES (dev mode — would fail in production)\",\n      \"\",\n    ];\n\n    for (const entry of missing) {\n      const envVars = Object.values(entry.fields).map((f) => f.env);\n      contentLines.push(\n        `  ${entry.type}:${entry.alias}  (plugin: ${entry.plugin})`,\n      );\n      contentLines.push(`    Set: ${envVars.join(\", \")}`);\n    }\n\n    contentLines.push(\"\");\n    contentLines.push(\n      \"Add these to your .env file or environment to suppress this warning.\",\n    );\n\n    const maxLen = Math.max(...contentLines.map((l) => l.length));\n    const border = \"=\".repeat(maxLen + 4);\n\n    const boxed = contentLines.map((line) => `| ${line.padEnd(maxLen)} |`);\n\n    return [border, ...boxed, border].join(\"\\n\");\n  }\n}\n"],"mappings":"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"}

package/dist/registry/types.d.ts

@@ -0,0 +1,181 @@
+import { JSONSchema7 } from "json-schema";
+
+//#region src/registry/types.d.ts
+
+/**
+ * Resource Registry Type System
+ *
+ * This module defines the type system for the AppKit Resource Registry,
+ * which enables plugins to declare their Databricks resource requirements
+ * in a machine-readable format.
+ *
+ * Resource types are exposed as first-class citizens with their specific
+ * permissions, making it simple for users to declare dependencies.
+ * Internal tooling handles conversion to Databricks app.yaml format.
+ */
+/**
+ * Supported resource types that plugins can depend on.
+ * Each type has its own set of valid permissions.
+ */
+declare enum ResourceType {
+  /** Secret scope for secure credential storage */
+  SECRET = "secret",
+  /** Databricks Job for scheduled or triggered workflows */
+  JOB = "job",
+  /** Databricks SQL Warehouse for query execution */
+  SQL_WAREHOUSE = "sql_warehouse",
+  /** Model serving endpoint for ML inference */
+  SERVING_ENDPOINT = "serving_endpoint",
+  /** Unity Catalog Volume for file storage */
+  VOLUME = "volume",
+  /** Vector Search Index for similarity search */
+  VECTOR_SEARCH_INDEX = "vector_search_index",
+  /** Unity Catalog Function */
+  UC_FUNCTION = "uc_function",
+  /** Unity Catalog Connection for external data sources */
+  UC_CONNECTION = "uc_connection",
+  /** Database (Lakebase) for persistent storage */
+  DATABASE = "database",
+  /** Genie Space for AI assistant */
+  GENIE_SPACE = "genie_space",
+  /** MLflow Experiment for ML tracking */
+  EXPERIMENT = "experiment",
+  /** Databricks App dependency */
+  APP = "app",
+}
+/** Permissions for SECRET resources */
+type SecretPermission = "MANAGE" | "READ" | "WRITE";
+/** Permissions for JOB resources */
+type JobPermission = "CAN_MANAGE" | "CAN_MANAGE_RUN" | "CAN_VIEW";
+/** Permissions for SQL_WAREHOUSE resources */
+type SqlWarehousePermission = "CAN_MANAGE" | "CAN_USE";
+/** Permissions for SERVING_ENDPOINT resources */
+type ServingEndpointPermission = "CAN_MANAGE" | "CAN_QUERY" | "CAN_VIEW";
+/** Permissions for VOLUME resources */
+type VolumePermission = "READ_VOLUME" | "WRITE_VOLUME";
+/** Permissions for VECTOR_SEARCH_INDEX resources */
+type VectorSearchIndexPermission = "SELECT";
+/** Permissions for UC_FUNCTION resources */
+type UcFunctionPermission = "EXECUTE";
+/** Permissions for UC_CONNECTION resources */
+type UcConnectionPermission = "USE_CONNECTION";
+/** Permissions for DATABASE resources */
+type DatabasePermission = "CAN_CONNECT_AND_CREATE";
+/** Permissions for GENIE_SPACE resources */
+type GenieSpacePermission = "CAN_EDIT" | "CAN_VIEW" | "CAN_RUN" | "CAN_MANAGE";
+/** Permissions for EXPERIMENT resources */
+type ExperimentPermission = "CAN_READ" | "CAN_EDIT" | "CAN_MANAGE";
+/** Permissions for APP resources */
+type AppPermission = "CAN_USE";
+/**
+ * Union of all possible permission levels across all resource types.
+ */
+type ResourcePermission = SecretPermission | JobPermission | SqlWarehousePermission | ServingEndpointPermission | VolumePermission | VectorSearchIndexPermission | UcFunctionPermission | UcConnectionPermission | DatabasePermission | GenieSpacePermission | ExperimentPermission | AppPermission;
+/**
+ * Defines a single field for a resource. Each field has its own environment variable and optional description.
+ * Single-value types use one key (e.g. id); multi-value types (database, secret) use multiple (e.g. instance_name, database_name or scope, key).
+ */
+interface ResourceFieldEntry {
+  /** Environment variable name for this field */
+  env: string;
+  /** Human-readable description for this field */
+  description?: string;
+}
+/**
+ * Declares a resource requirement for a plugin.
+ * Can be defined statically in a manifest or dynamically via getResourceRequirements().
+ */
+interface ResourceRequirement {
+  /** Type of Databricks resource required */
+  type: ResourceType;
+  /** Unique alias for this resource within the plugin (e.g., 'warehouse', 'secrets'). Used for UI/display. */
+  alias: string;
+  /** Stable key for machine use (env naming, composite keys, app.yaml). Required. */
+  resourceKey: string;
+  /** Human-readable description of why this resource is needed */
+  description: string;
+  /** Required permission level for the resource */
+  permission: ResourcePermission;
+  /**
+   * Map of field name to env and optional description.
+   * Single-value types use one key (e.g. id); multi-value (database, secret) use multiple keys.
+   */
+  fields: Record<string, ResourceFieldEntry>;
+  /** Whether this resource is required (true) or optional (false) */
+  required: boolean;
+}
+/**
+ * Internal representation of a resource in the registry.
+ * Extends ResourceRequirement with resolution state and plugin ownership.
+ */
+interface ResourceEntry extends ResourceRequirement {
+  /** Plugin(s) that require this resource (comma-separated if multiple) */
+  plugin: string;
+  /** Whether the resource has been resolved (all field env vars set) */
+  resolved: boolean;
+  /** Resolved value per field name. Populated by validate() when all field env vars are set. */
+  values?: Record<string, string>;
+  /**
+   * Per-plugin permission tracking.
+   * Maps plugin name to the permission it originally requested.
+   * Populated when multiple plugins share the same resource.
+   */
+  permissionSources?: Record<string, ResourcePermission>;
+}
+/**
+ * Result of validating all registered resources against the environment.
+ */
+interface ValidationResult {
+  /** Whether all required resources are available */
+  valid: boolean;
+  /** List of missing required resources */
+  missing: ResourceEntry[];
+  /** Complete list of all registered resources (required and optional) */
+  all: ResourceEntry[];
+}
+/**
+ * Configuration schema definition for plugin config.
+ * Re-exported from the standard JSON Schema Draft 7 types.
+ *
+ * @see {@link https://json-schema.org/draft-07/json-schema-release-notes | JSON Schema Draft 7}
+ */
+type ConfigSchema = JSONSchema7;
+/**
+ * Plugin manifest that declares metadata and resource requirements.
+ * Attached to plugin classes as a static property.
+ */
+interface PluginManifest {
+  /** Plugin identifier (matches plugin.name) */
+  name: string;
+  /** Human-readable display name for UI/CLI */
+  displayName: string;
+  /** Brief description of what the plugin does */
+  description: string;
+  /**
+   * Resource requirements declaration
+   */
+  resources: {
+    /** Resources that must be available for the plugin to function */
+    required: Omit<ResourceRequirement, "required">[];
+    /** Resources that enhance functionality but are not mandatory */
+    optional: Omit<ResourceRequirement, "required">[];
+  };
+  /**
+   * Configuration schema for the plugin.
+   * Defines the shape and validation rules for plugin config.
+   */
+  config?: {
+    schema: ConfigSchema;
+  };
+  /**
+   * Optional metadata for community plugins
+   */
+  author?: string;
+  version?: string;
+  repository?: string;
+  keywords?: string[];
+  license?: string;
+}
+//#endregion
+export { ConfigSchema, PluginManifest, ResourceEntry, ResourceFieldEntry, ResourcePermission, ResourceRequirement, ResourceType, ValidationResult };
+//# sourceMappingURL=types.d.ts.map

package/dist/registry/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/registry/types.ts"],"sourcesContent":[],"mappings":";;;;;;;AAgBA;AA2CA;AAGA;AAGA;AAGA;AAGA;AAGA;AAGA;AAGA;AAGA;AAGA;AAOA;AAGY,aAhFA,YAAA;EAqFA;EAAkB,MAAA,GAAA,QAAA;;KAE1B,GAAA,KAAA;;eAEA,GAAA,eAAA;;kBAEA,GAAA,kBAAA;;QAEA,GAAA,QAAA;;qBAEA,GAAA,qBAAA;;aAEA,GAAA,aAAA;EAAa;EAmCA,aAAA,GAAA,eAAkB;EAWlB;EAAmB,QAAA,GAAA,UAAA;;aActB,GAAA,aAAA;;YAMJ,GAAA,YAAA;EAAM;EAUC,GAAA,GAAA,KAAA;;;AAeoB,KAjJzB,gBAAA,GAiJyB,QAAA,GAAA,MAAA,GAAA,OAAA;;AAfE,KA/H3B,aAAA,GA+H2B,YAAA,GAAA,gBAAA,GAAA,UAAA;;AAqBtB,KAjJL,sBAAA,GAiJqB,YAAA,GAAA,SAAA;;AAKtB,KAnJC,yBAAA,GAmJD,YAAA,GAAA,WAAA,GAAA,UAAA;;AAGS,KAnJR,gBAAA,GAmJQ,aAAA,GAAA,cAAA;AAWpB;AAMiB,KAjKL,2BAAA,GAiKmB,QAAA;;AAeZ,KA7KP,oBAAA,GA6KO,SAAA;;AAGA,KA7KP,sBAAA,GA6KO,gBAAA;;AAQP,KAlLA,kBAAA,GAkLA,wBAAA;;KA/KA,oBAAA;;KAOA,oBAAA;;KAGA,aAAA;;;;KAKA,kBAAA,GACR,mBACA,gBACA,yBACA,4BACA,mBACA,8BACA,uBACA,yBACA,qBACA,uBACA,uBACA;;;;;UAmCa,kBAAA;;;;;;;;;;UAWA,mBAAA;;QAET;;;;;;;;cAYM;;;;;UAMJ,eAAe;;;;;;;;UAUR,aAAA,SAAsB;;;;;;WAQ5B;;;;;;sBAOW,eAAe;;;;;UAMpB,gBAAA;;;;WAKN;;OAGJ;;;;;;;;KAWK,YAAA,GAAe;;;;;UAMV,cAAA;;;;;;;;;;;;cAeH,KAAK;;cAGL,KAAK;;;;;;;YAQP"}

package/dist/registry/types.js

@@ -0,0 +1,89 @@
+//#region src/registry/types.ts
+/**
+* Resource Registry Type System
+*
+* This module defines the type system for the AppKit Resource Registry,
+* which enables plugins to declare their Databricks resource requirements
+* in a machine-readable format.
+*
+* Resource types are exposed as first-class citizens with their specific
+* permissions, making it simple for users to declare dependencies.
+* Internal tooling handles conversion to Databricks app.yaml format.
+*/
+/**
+* Supported resource types that plugins can depend on.
+* Each type has its own set of valid permissions.
+*/
+let ResourceType = /* @__PURE__ */ function(ResourceType) {
+	/** Secret scope for secure credential storage */
+	ResourceType["SECRET"] = "secret";
+	/** Databricks Job for scheduled or triggered workflows */
+	ResourceType["JOB"] = "job";
+	/** Databricks SQL Warehouse for query execution */
+	ResourceType["SQL_WAREHOUSE"] = "sql_warehouse";
+	/** Model serving endpoint for ML inference */
+	ResourceType["SERVING_ENDPOINT"] = "serving_endpoint";
+	/** Unity Catalog Volume for file storage */
+	ResourceType["VOLUME"] = "volume";
+	/** Vector Search Index for similarity search */
+	ResourceType["VECTOR_SEARCH_INDEX"] = "vector_search_index";
+	/** Unity Catalog Function */
+	ResourceType["UC_FUNCTION"] = "uc_function";
+	/** Unity Catalog Connection for external data sources */
+	ResourceType["UC_CONNECTION"] = "uc_connection";
+	/** Database (Lakebase) for persistent storage */
+	ResourceType["DATABASE"] = "database";
+	/** Genie Space for AI assistant */
+	ResourceType["GENIE_SPACE"] = "genie_space";
+	/** MLflow Experiment for ML tracking */
+	ResourceType["EXPERIMENT"] = "experiment";
+	/** Databricks App dependency */
+	ResourceType["APP"] = "app";
+	return ResourceType;
+}({});
+/**
+* Permission hierarchy per resource type (weakest to strongest).
+* Used to compare permissions when merging; higher index = more permissive.
+* Unknown permissions are treated as less than any known permission.
+*/
+const PERMISSION_HIERARCHY_BY_TYPE = {
+	[ResourceType.SECRET]: [
+		"READ",
+		"WRITE",
+		"MANAGE"
+	],
+	[ResourceType.JOB]: [
+		"CAN_VIEW",
+		"CAN_MANAGE_RUN",
+		"CAN_MANAGE"
+	],
+	[ResourceType.SQL_WAREHOUSE]: ["CAN_USE", "CAN_MANAGE"],
+	[ResourceType.SERVING_ENDPOINT]: [
+		"CAN_VIEW",
+		"CAN_QUERY",
+		"CAN_MANAGE"
+	],
+	[ResourceType.VOLUME]: ["READ_VOLUME", "WRITE_VOLUME"],
+	[ResourceType.VECTOR_SEARCH_INDEX]: ["SELECT"],
+	[ResourceType.UC_FUNCTION]: ["EXECUTE"],
+	[ResourceType.UC_CONNECTION]: ["USE_CONNECTION"],
+	[ResourceType.DATABASE]: ["CAN_CONNECT_AND_CREATE"],
+	[ResourceType.GENIE_SPACE]: [
+		"CAN_VIEW",
+		"CAN_RUN",
+		"CAN_EDIT",
+		"CAN_MANAGE"
+	],
+	[ResourceType.EXPERIMENT]: [
+		"CAN_READ",
+		"CAN_EDIT",
+		"CAN_MANAGE"
+	],
+	[ResourceType.APP]: ["CAN_USE"]
+};
+/** Set of valid permissions per type (for validation). */
+const PERMISSIONS_BY_TYPE = PERMISSION_HIERARCHY_BY_TYPE;
+
+//#endregion
+export { PERMISSIONS_BY_TYPE, PERMISSION_HIERARCHY_BY_TYPE, ResourceType };
+//# sourceMappingURL=types.js.map

package/dist/registry/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":[],"sources":["../../src/registry/types.ts"],"sourcesContent":["/**\n * Resource Registry Type System\n *\n * This module defines the type system for the AppKit Resource Registry,\n * which enables plugins to declare their Databricks resource requirements\n * in a machine-readable format.\n *\n * Resource types are exposed as first-class citizens with their specific\n * permissions, making it simple for users to declare dependencies.\n * Internal tooling handles conversion to Databricks app.yaml format.\n */\n\n/**\n * Supported resource types that plugins can depend on.\n * Each type has its own set of valid permissions.\n */\nexport enum ResourceType {\n  /** Secret scope for secure credential storage */\n  SECRET = \"secret\",\n\n  /** Databricks Job for scheduled or triggered workflows */\n  JOB = \"job\",\n\n  /** Databricks SQL Warehouse for query execution */\n  SQL_WAREHOUSE = \"sql_warehouse\",\n\n  /** Model serving endpoint for ML inference */\n  SERVING_ENDPOINT = \"serving_endpoint\",\n\n  /** Unity Catalog Volume for file storage */\n  VOLUME = \"volume\",\n\n  /** Vector Search Index for similarity search */\n  VECTOR_SEARCH_INDEX = \"vector_search_index\",\n\n  /** Unity Catalog Function */\n  UC_FUNCTION = \"uc_function\",\n\n  /** Unity Catalog Connection for external data sources */\n  UC_CONNECTION = \"uc_connection\",\n\n  /** Database (Lakebase) for persistent storage */\n  DATABASE = \"database\",\n\n  /** Genie Space for AI assistant */\n  GENIE_SPACE = \"genie_space\",\n\n  /** MLflow Experiment for ML tracking */\n  EXPERIMENT = \"experiment\",\n\n  /** Databricks App dependency */\n  APP = \"app\",\n}\n\n// ============================================================================\n// Permissions per resource type\n// ============================================================================\n\n/** Permissions for SECRET resources */\nexport type SecretPermission = \"MANAGE\" | \"READ\" | \"WRITE\";\n\n/** Permissions for JOB resources */\nexport type JobPermission = \"CAN_MANAGE\" | \"CAN_MANAGE_RUN\" | \"CAN_VIEW\";\n\n/** Permissions for SQL_WAREHOUSE resources */\nexport type SqlWarehousePermission = \"CAN_MANAGE\" | \"CAN_USE\";\n\n/** Permissions for SERVING_ENDPOINT resources */\nexport type ServingEndpointPermission = \"CAN_MANAGE\" | \"CAN_QUERY\" | \"CAN_VIEW\";\n\n/** Permissions for VOLUME resources */\nexport type VolumePermission = \"READ_VOLUME\" | \"WRITE_VOLUME\";\n\n/** Permissions for VECTOR_SEARCH_INDEX resources */\nexport type VectorSearchIndexPermission = \"SELECT\";\n\n/** Permissions for UC_FUNCTION resources */\nexport type UcFunctionPermission = \"EXECUTE\";\n\n/** Permissions for UC_CONNECTION resources */\nexport type UcConnectionPermission = \"USE_CONNECTION\";\n\n/** Permissions for DATABASE resources */\nexport type DatabasePermission = \"CAN_CONNECT_AND_CREATE\";\n\n/** Permissions for GENIE_SPACE resources */\nexport type GenieSpacePermission =\n  | \"CAN_EDIT\"\n  | \"CAN_VIEW\"\n  | \"CAN_RUN\"\n  | \"CAN_MANAGE\";\n\n/** Permissions for EXPERIMENT resources */\nexport type ExperimentPermission = \"CAN_READ\" | \"CAN_EDIT\" | \"CAN_MANAGE\";\n\n/** Permissions for APP resources */\nexport type AppPermission = \"CAN_USE\";\n\n/**\n * Union of all possible permission levels across all resource types.\n */\nexport type ResourcePermission =\n  | SecretPermission\n  | JobPermission\n  | SqlWarehousePermission\n  | ServingEndpointPermission\n  | VolumePermission\n  | VectorSearchIndexPermission\n  | UcFunctionPermission\n  | UcConnectionPermission\n  | DatabasePermission\n  | GenieSpacePermission\n  | ExperimentPermission\n  | AppPermission;\n\n/**\n * Permission hierarchy per resource type (weakest to strongest).\n * Used to compare permissions when merging; higher index = more permissive.\n * Unknown permissions are treated as less than any known permission.\n */\nexport const PERMISSION_HIERARCHY_BY_TYPE: Record<\n  ResourceType,\n  readonly ResourcePermission[]\n> = {\n  [ResourceType.SECRET]: [\"READ\", \"WRITE\", \"MANAGE\"],\n  [ResourceType.JOB]: [\"CAN_VIEW\", \"CAN_MANAGE_RUN\", \"CAN_MANAGE\"],\n  [ResourceType.SQL_WAREHOUSE]: [\"CAN_USE\", \"CAN_MANAGE\"],\n  [ResourceType.SERVING_ENDPOINT]: [\"CAN_VIEW\", \"CAN_QUERY\", \"CAN_MANAGE\"],\n  [ResourceType.VOLUME]: [\"READ_VOLUME\", \"WRITE_VOLUME\"],\n  [ResourceType.VECTOR_SEARCH_INDEX]: [\"SELECT\"],\n  [ResourceType.UC_FUNCTION]: [\"EXECUTE\"],\n  [ResourceType.UC_CONNECTION]: [\"USE_CONNECTION\"],\n  [ResourceType.DATABASE]: [\"CAN_CONNECT_AND_CREATE\"],\n  [ResourceType.GENIE_SPACE]: [\"CAN_VIEW\", \"CAN_RUN\", \"CAN_EDIT\", \"CAN_MANAGE\"],\n  [ResourceType.EXPERIMENT]: [\"CAN_READ\", \"CAN_EDIT\", \"CAN_MANAGE\"],\n  [ResourceType.APP]: [\"CAN_USE\"],\n} as const;\n\n/** Set of valid permissions per type (for validation). */\nexport const PERMISSIONS_BY_TYPE: Record<\n  ResourceType,\n  readonly ResourcePermission[]\n> = PERMISSION_HIERARCHY_BY_TYPE;\n\n/**\n * Defines a single field for a resource. Each field has its own environment variable and optional description.\n * Single-value types use one key (e.g. id); multi-value types (database, secret) use multiple (e.g. instance_name, database_name or scope, key).\n */\nexport interface ResourceFieldEntry {\n  /** Environment variable name for this field */\n  env: string;\n  /** Human-readable description for this field */\n  description?: string;\n}\n\n/**\n * Declares a resource requirement for a plugin.\n * Can be defined statically in a manifest or dynamically via getResourceRequirements().\n */\nexport interface ResourceRequirement {\n  /** Type of Databricks resource required */\n  type: ResourceType;\n\n  /** Unique alias for this resource within the plugin (e.g., 'warehouse', 'secrets'). Used for UI/display. */\n  alias: string;\n\n  /** Stable key for machine use (env naming, composite keys, app.yaml). Required. */\n  resourceKey: string;\n\n  /** Human-readable description of why this resource is needed */\n  description: string;\n\n  /** Required permission level for the resource */\n  permission: ResourcePermission;\n\n  /**\n   * Map of field name to env and optional description.\n   * Single-value types use one key (e.g. id); multi-value (database, secret) use multiple keys.\n   */\n  fields: Record<string, ResourceFieldEntry>;\n\n  /** Whether this resource is required (true) or optional (false) */\n  required: boolean;\n}\n\n/**\n * Internal representation of a resource in the registry.\n * Extends ResourceRequirement with resolution state and plugin ownership.\n */\nexport interface ResourceEntry extends ResourceRequirement {\n  /** Plugin(s) that require this resource (comma-separated if multiple) */\n  plugin: string;\n\n  /** Whether the resource has been resolved (all field env vars set) */\n  resolved: boolean;\n\n  /** Resolved value per field name. Populated by validate() when all field env vars are set. */\n  values?: Record<string, string>;\n\n  /**\n   * Per-plugin permission tracking.\n   * Maps plugin name to the permission it originally requested.\n   * Populated when multiple plugins share the same resource.\n   */\n  permissionSources?: Record<string, ResourcePermission>;\n}\n\n/**\n * Result of validating all registered resources against the environment.\n */\nexport interface ValidationResult {\n  /** Whether all required resources are available */\n  valid: boolean;\n\n  /** List of missing required resources */\n  missing: ResourceEntry[];\n\n  /** Complete list of all registered resources (required and optional) */\n  all: ResourceEntry[];\n}\n\nimport type { JSONSchema7 } from \"json-schema\";\n\n/**\n * Configuration schema definition for plugin config.\n * Re-exported from the standard JSON Schema Draft 7 types.\n *\n * @see {@link https://json-schema.org/draft-07/json-schema-release-notes | JSON Schema Draft 7}\n */\nexport type ConfigSchema = JSONSchema7;\n\n/**\n * Plugin manifest that declares metadata and resource requirements.\n * Attached to plugin classes as a static property.\n */\nexport interface PluginManifest {\n  /** Plugin identifier (matches plugin.name) */\n  name: string;\n\n  /** Human-readable display name for UI/CLI */\n  displayName: string;\n\n  /** Brief description of what the plugin does */\n  description: string;\n\n  /**\n   * Resource requirements declaration\n   */\n  resources: {\n    /** Resources that must be available for the plugin to function */\n    required: Omit<ResourceRequirement, \"required\">[];\n\n    /** Resources that enhance functionality but are not mandatory */\n    optional: Omit<ResourceRequirement, \"required\">[];\n  };\n\n  /**\n   * Configuration schema for the plugin.\n   * Defines the shape and validation rules for plugin config.\n   */\n  config?: {\n    schema: ConfigSchema;\n  };\n\n  /**\n   * Optional metadata for community plugins\n   */\n  author?: string;\n  version?: string;\n  repository?: string;\n  keywords?: string[];\n  license?: string;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAgBA,IAAY,sDAAL;;AAEL;;AAGA;;AAGA;;AAGA;;AAGA;;AAGA;;AAGA;;AAGA;;AAGA;;AAGA;;AAGA;;AAGA;;;;;;;;AAqEF,MAAa,+BAGT;EACD,aAAa,SAAS;EAAC;EAAQ;EAAS;EAAS;EACjD,aAAa,MAAM;EAAC;EAAY;EAAkB;EAAa;EAC/D,aAAa,gBAAgB,CAAC,WAAW,aAAa;EACtD,aAAa,mBAAmB;EAAC;EAAY;EAAa;EAAa;EACvE,aAAa,SAAS,CAAC,eAAe,eAAe;EACrD,aAAa,sBAAsB,CAAC,SAAS;EAC7C,aAAa,cAAc,CAAC,UAAU;EACtC,aAAa,gBAAgB,CAAC,iBAAiB;EAC/C,aAAa,WAAW,CAAC,yBAAyB;EAClD,aAAa,cAAc;EAAC;EAAY;EAAW;EAAY;EAAa;EAC5E,aAAa,aAAa;EAAC;EAAY;EAAY;EAAa;EAChE,aAAa,MAAM,CAAC,UAAU;CAChC;;AAGD,MAAa,sBAGT"}